Runtime Type : Types : StringUtil
Analogs:
Inherits from: root→Object→StringUtil
Contains utility functions for dealing with strings.
Contents |
Key Concepts
StringUtil is a utility that operates on primative string. To operate on one specific string object, see StringObject.
Class Members
Fields
Functions
Function Summary
| compareN | Compares N characters between two strings where N is the number of characters to compare. |
| convertDataToStr | Converts a number to a string. |
| convertStrToNumber | Converts a string to a number. |
| convertToMIMEType | Converts a file extension and to the associated MIME type. |
| endsWith | Compares two strings to determine if one string is the suffix of the other string. |
| escapeSpecialChars | Removes a set of characters from a string by escaping them. |
| find | Finds a substring within a larger string. |
| findOneNotOf | Finds the first index in a string that contains a character that is not a member of a given set of characters. |
| findOneOf | Finds the first index in a string that contains a character that is a member of a given set of characters. |
| findSubstr | Finds a substring within a larger string. |
| getTextFromHTML | Removes HTML tags from text. |
| insertHTMLToBody | Inserts an HTML string into the body of another HTML string. |
| length | Determines the number of characters in a string. |
| regexExecute | Executes a regular expression and returns a collection of matches. |
| regexMatch | Determines if a given string matches the given regular expression. |
| spanExcluding | Searches the source string, starting with the first character, for any characters not in the set string. Processing continues until a character is found in the source string that is included in the set string. |
| spanIncluding | Searches the source string, starting with the first character, for any characters also in the set string. Processing continues until a character is found in the source string that is not included in the set string. |
| split | Splits a string into a collection of strings, creating a new field in the collection at every occurrence of a substring you designate as the separator. |
| startsWith | Compares two strings to determine if one string is the prefix of the other string. |
| stringExpToData | Converts a string to a Data type. Valid characters include alpha-numerics, period (dot), and the minus sign (-) if it's the first character and it's followed by another legal character. Any other characters cause isValid to be false. |
| stringReplace | Replaces the substring you specify with a different string you specify. |
| stringToData | Converts a string to the specified data type. |
| stripExcluding | Strips all characters from the string that are not in the exclude set. |
| stripIncluding | Strips all characters from the string, except those in the include set. |
| substr | Retrieves a substring from the given string. |
| toLower | Converts all letters in a string to lower-case letters. |
| toUpper | Converts all letters in a string to upper-case letters. |
| trim | Trims whitespace from the beginning and end of the input string. |
| urlDecode | Changes URL compatible symbols and characters in a string to equivalent ASCII characters. |
| urlEncode | Changes characters in a string not compatible with a URL to URL compatible symbols and characters. |
| validEmail | Verifies that the given email address is a valid email address. |
| validPassword | Verifies that the given password is a valid password. |
| xmlDecode | Changes XML compatible symbols and characters in a string to equivalent ASCII characters. |
| xmlEncode | Changes ASCII characters in a string not compatible with XML to XML compatible symbols and characters. |
Function Detail
compareN
Compares N characters between two strings where N is the number of characters to compare.
Syntax
compareN( [in] string string1, [in] string string2, [in] int length, [in] boolean ignoreCase, [out] int32 result )
Parameters
- string1
- the first string in the comparison
- string2
- the second string in the comparison
- length
- the number of characters to compare
- noCase
- if true, perform case-insensitive comparison; else, perform case-sensitive comparison
- result
- the result of the comparison (result < 0 means string1 comes before string2; result = 0 means string1 equals string2; result > 0 means string1 comes after string2).
convertDataToStr
Converts a number to a string.
Syntax
convertDataToStr( [in] Data val, [out] string result )
Parameters
- val
- the number to convert
- result
- the string to return
convertStrToNumber
Converts a string to a number
Syntax
convertStrToNumber( [in] string val, [in] string type, [out] Data result )
Parameters
- val
- the string to convert
- type
- the type of number to convert to
Integer (i8, i16, i32, i64)
Floating Point (fl, do)
Unsigned Integer (u8, u16, u32, u64)- result
- the resulting number
convertToMIMEType
Converts a file extension and to the associated MIME type.
Syntax
convertToMIMEType( [in] string extention, [out] string mimeType )
Parameters
- extention
- the extension to convert
- mimeType
- the associated MIME type returned
a - application/octet-stream
ai - application/postscript
aif - audio/x-aiff
aifc - audio/x-aiff
arc - application/octet-stream
asc - text/plain
asf - video/x-ms-asf
asx - video/x-ms-asf
au - audio/basic
avi - application/x-msvideo
bcpio - application/octet-stream
bin - application/octet-stream
bmp - image/x-xbitmap
c - text/plain
c++ - text/plain
cc - text/plain
ccad - application/clariscad
class - application/octet-stream
cpp - text/plain
cpt - application/mac-compactpro
cdf - application/x-netcdf
cpio - application/x-cpio
csh - application/x-csh
css - text/css
dcr - application/x-director
dir - application/x-director
dll - application/octet-stream
dms - application/octet-stream
doc - application/msword
djv - image/x-djvu
djvu - image/x-djvu
drw - application/drafting
dtd - text/xml
dump - application/octet-stream
dvi - application/x-dvi
dwg - application/octet-stream
dxf - application/dxf
dxr - application/x-director
eps - application/postscript
etx - text/x-setext
evy - application/x-envoy
exe - application/octet-stream
ez - application/andrew-inset
f - text/plain
f90 - text/plain
fif - application/fractals
fli - application/octet-stream
gif - image/gif
gl - application/octet-stream
gtar - application/x-gtar
gz - application/x-gzip
h - text/plain
hdf - application/x-hdf
hh - text/plain
hpx - application/mac-binhex40
hqx - application/octet-stream
htm - text/html
html - text/html
ice - x-conference/x-cooltalk
iges - model/iges
igs - model/iges
ips - application/x-ipscript
ipx - application/x-ipix
isv - bws-internal/intrasrv-urlencoded
iw4 - image/x-iw44
iw44 - image/x-iw44
ief - image/ief
java - text/plain
jfif - image/jpeg
jfif-tbnl - image/jpeg
jfm - bws-internal/intrasrv-format
jpe - image/jpeg
jpeg - image/jpeg
jpg - image/jpeg
jrp - bws-internal/intrasrv-report
js - application/x-javascript
kar - audio/midi
latex - application/x-latex
lha - application/octet-stream
log - text/plain
ls - application/x-javascript
lsp - application/x-lisp
lzh - application/octet-stream
m - text/plain
man - application/x-troff-man
me - application/x-troff-me
mesh - model/mesh
mid - audio/midi
midi - audio/midi
mif - application/x-mif
mime - message/rfc822
mocha - application/x-javascript
mov - video/quicktime
movie - video/x-sgi-movie
mp2 - audio/mpeg
mp3 - audio/mpeg
mpe - video/mpeg
mpeg - video/mpeg
mpg - video/mpeg
mpga - audio/mpeg
ms - application/x-troff-ms
msh - model/mesh
mv - video/x-sgi-movie
nc - application/x-netcdf
o - application/octet-stream
oda - application/oda
pac - application/x-ns-proxy-autoconfig
pbm - image/x-portable-bitmap
pdb - chemical/x-pdb
pdf - application/pdf
pgm - image/x-portable-graymap
pgn - application/x-chess-pgn
php3 - application/x-httpd-php3
phtml-msql2 - application/x-httpd-php-msql2
phtml - application/x-httpd-php
pl - text/plain
png - image/png
pnm - image/x-portable-anymap
pot - application/mspowerpoint
ppm - image/x-portable-pixmap
pps - application/mspowerpoint
ppt - application/mspowerpoint
ppz - application/mspowerpoint
pre - application/x-freelance
prt - application/pro_eng
ps - application/postscript
qt - video/quicktime
ra - audio/x-realaudio
ram - audio/x-realaudio
ras - image/x-cmu-raster
rgb - image/x-rgb
rm - audio/x-pn-realaudio
roff - application/x-troff
rpm - audio/x-pn-realaudio-plugin
rtf - application/rft
rtx - application/rtf
saveme - application/octet-stream
scm - application/octet-stream
set - application/set
sgm - text/x-sgml
sgml - text/x-sgml
sh - application/x-shar
shar - application/x-shar
silo - model/mesh
sit - application/stuffit
skd - application/x-koan
skm - application/x-koan
skp - application/x-koan
skt - application/x-koan
smi - application/smil
smil - application/smil
snd - audio/basic
sol - application/solids
spl - application/x-futuresplash
src - application/x-wais-source
step - application/STEP
stl - application/SLA
stp - application/STEP
sv4cpio - application/x-sv4-cpio
sv4crc - application/x-sv4-crc
swf - application/x-shockwave-flash
t - application/x-troff
tar - application/x-tar
tcl - application/x-tcl
tex - application/x-tex
texi - application/x-texinfo
texinfo - application/x-texinfo
text - text/plain
tif - image/tiff
tiff - image/tiff
tr - application/x-troff
tsi - audio/TSP-audio
tsp - application/dsptype
tsv - text/tab-separated-values
txt - text/plain
unv - application/i-deas
ustar - application/x-ustar
uu - application/octet-stream
vcd - application/x-cdlink
vda - application/vda
viv - video/vnd.vivo
vivo - video/vnd.vivo
vox - audio/voxware
wav - audio/x-wav
wax - audio/x-ms-wax
wm - video/x-ms-wm
wma - audio/x-ms-wma
wmd - application/x-ms-wmd
wmv - video/x-ms-wmv
wmx - video/x-ms-wmx
wmz - application/x-ms-wmz
wrl - model/vrml
wsrc - application/x-wais-source
wvx - video/x-ms-wvx
xbm - image/x-xbitmap
xlc - application/vnd.ms-excel
xll - application/vnd.ms-excel
xlm - application/vnd.ms-excel
xls - application/vnd.ms-excel
xlw - application/vnd.ms-excel
xml - text/xml
xpm - image/x-xpixmap
xwd - image/x-xwindowdump
xyz - chemical/x-pdb
z - application/octet-stream
zip - application/zip
endsWith
Compares two strings to determine if one string is the suffix of the other string.
Syntax
endsWith( [in] string source, [in] string suffix,[in] boolean ignoreCase, [out] boolean result )
Parameters
- source
- the string to look in
- suffix
- the string to compare against source
- ignoreCase
- if true, perform a case-insensitive search; if false, perform a case-sensitive search
- result
- the result of the comparison (result is true if prefix matches the end of source; otherwise result is false)
escapeSpecialChars
Removes from a string those characters which you decide to make illegal. The function "escapes" (places a slash \ in front of) the illegal characters.
Syntax
escapeSpecialChars([in] string originalString, [in] string escapeChars, [out] string newString)
Parameters
- originalString
- the string on which the function operates
- escapeChars
- the set of "characters you provide for the function to "escape"
- newString
- the string that returns with the characters "escaped"
find
Finds a substring within a larger string.
Syntax
find( [in] string str, [in] string subStr, [in] int startAt, [in] boolean ignoreCase, [out] int index )
Parameters
- str
- the string to look in
- subStr
- the substring to find
- startAt
- the initial index at which to begin the search in the original string
- ignoreCase
- if true, perform a case-insensitive search; if false, perform a case-sensitive search
- index
- the index of the substring in the original string, if it was found; -1 otherwise
findOneNotOf
Finds the first index in a string that contains a character that is not a member of a given set of characters.
For example, if the source string is 23sample and the set of characters to compare against is 1234567890, then the index is 2 (an index of 2 represents the third position in the string because strings have 0-based indexing), 2 is the first index in the source string that contains a character that is not a member of the set of characters compared against.
Syntax
findOneNotOf( [in] string source, [in] string set, [out] boolean index )
Parameters
- source
- the string to look in
- set
- the set of characters to compare against each index in source
- index
- the first index in source that does not contain a character in set, if one is found; -1 otherwise
findOneOf
Finds the first index in string that contains a character that is a member of a given set of characters.
For example, if the source string is ex23sample and the set of characters to compare against is 1234567890, then the index is 2 (an index of 2 represents the third position in the string because strings have 0-based indexing), 2 is the first index in the source string that contains a character that is a member of the set of characters compared against.
Syntax
findOneOf( [in] string source, [in] string set, [out] int index )
Parameters
- source
- the string to look in
- set
- the set of characters to compare against each index in source
- index
- the first index in source that does contains a character in set, if one is found; -1 otherwise
findSubstr
Finds a substring within a larger string.
Syntax
findSubstr( [in] string str, [in] string sub, [in] boolean ignoreCase, [out] int start, [out] int end )
Parameters
- str
- the string to search in
- sub
- the substring to find
- ignoreCase
- if true, perform a case-insensitive search; if false, perform a case-sensitive search
- start
- the index of the substring in the original string, if it was found; -1 otherwise
- end
- the index of the first character after the substring in the original string, if it was found; -1 otherwise
getTextFromHTML
Removes HTML tags from text.
Syntax
getTextFromHTML( [in] string html, [out] string text )
Parameters
- html
- the HTML from which to extract text
- text
- the extracted text to return
insertHTMLToBody
Inserts an HTML string into the body of another HTML string.
Syntax
insertHTMLToBody( [in] string htmlBody, [in] string htmlText, [in] boolean insertAtBegining, [out] string result )
Parameters
- htmlBody
- An HTML string into which another HTML string (defined by the htmlText argument) is to be inserted.
- htmlText
- An HTML string that is to be inserted into another HTML string (defined by the htmlBody argument).
- insertAtBegining
- A boolean value that, if true, htmlText is inserted immediately after the <body> tag. If false, htmlText is inserted immediately before the </body> tag.
- result
- Resulting HTML string (htmlBody with htmlText inserted according to insertAtBeginning)
length
Determines the number of characters in a string.
Syntax
length( [in] string str, [out] int len )
Parameters
- str
- the string whose length we want
- len
- the length of the string str
regexExecute
Executes a regular expression and returns a collection of matches.
- Syntax
regexExecute( [in] string regex, [in] string subject, [out] Collection(RegexMatch) matches)
- Parameters
regex
the regular expression to execute
subject
the subject for the execution of the regular expression.
matches
specifies the field or variable that receives the resulting collection of matches. The collection is null if no matches were found. Otherwise, the collection contains one or more RegexMatch objects containing the details of each match.
regexMatch
Determines if a given string matches the given regular expression.
Syntax
regexMatch( [in] string regex, [out] boolean result, [in] string subject )
Parameters
regex
the regular expression to try to matchresult
true is the string matches, false otherwisesubject
- the string to check
spanExcluding
Searches the source string, starting with the first character, for any characters not in the set string. Processing continues until a character is found in the source string that is included in the set string.
Syntax
spanExcluding( [in] string source, [in] string set, [out] Collection(string) result )
Parameters
- source
- the string searched
- set
- the substring containing characters that are compared to characters in the source string
- result
- the resulting string showing characters in the source string (starting with the first character) that are not in the set string
spanIncluding
Searches the source string, starting with the first character, for any characters also in the set string. Processing continues until a character is found in the source string that is not included in the set string.
Syntax
spanExcluding( [in] string source, [in] string set, [out] Collection(string) result )
Parameters
- source
- the string searched
- set
- the substring containing characters that are compared to characters in the source string
- result
- the resulitng string showing characters in the source string (starting with the first character) that are also in the set string
split
Splits a string into a collection of strings, creating a new field in the collection at every occurrence of a substring you designate as the separator.
Syntax
split( [in] string text, [in] string separator, [out] Collection(string) fields)
Parameters
- text
- the string you want to split
- separator
- the substring you designate to split on
Note If you need to split on a special character, such as a tab or a line break, see the Expressions Cheat Sheet.
- fields
- a Collection of the resulting strings
startsWith
Compares two strings to determine if one string is the prefix of the other string.
Syntax
startsWith( [in] string source, [in] string prefix,[in] boolean ignoreCase, [out] boolean result )
Parameters
- source
- the string to look in
- prefix
- the string to compare against source
- ignoreCase
- if true, perform a case-insensitive search; if false, perform a case-sensitive search
- result
- the result of the comparison (result is true if suffix matches the end of source; otherwise result is false)
stringExpToData
Converts a string to a Data type. Valid characters include alpha-numerics, period (dot), and the minus sign (-) if it's the first character and it's followed by another legal character. Any other characters cause isValid to be false.
- A string representation of a number is converted to a number.
- A string in quotes (single or double) is converted to a Data string.
- A string consisting of the word "true" is converted to a boolean with a value of true.
- A string consisting of the word "false" is converted to a boolean with a value of false.
- A string consisting of the word "null" is converted to a null object.
Syntax
stringExpToData( [in] string expression, [out] Data data, [out] boolean isValid )
Parameters
- expression
- string expression to be converted
- data
- result of the conversion
- isValid
- boolean that reflects whether the characters in expression are valid (true) or invalid (false).
stringReplace
Replaces the substring you specify with a different string you specify.
Syntax
stringReplace( [in] string str, [in] string oldStr, [in] string newStr, [out] string output )
Parameters
- str
- the string on which to perform the replace
- oldStr
- the substring you want to replace
- newStr
- the new string you want to insert in place of the old substring
- output
- the modified string
stringToData
Converts a string to the specified data type.
Syntax
stringToData( [in] string stringValue, [in] Data data, [out] Data outData )
Parameters
- stringValue
- the string to be converted
- data
- the type to convert the string to
- outData
- the resulting output
stripExcluding
Searches the source string, starting with the first character, for any characters not in the (exclude) set string. Strips all characters from the string that are not in the exclude set.
Syntax
spanExcluding( [in] string source, [in] string set, [out] Collection(string) result )
Parameters
- source
- the string searched
- set
- the substring containing characters that are compared to characters in the source string
- result
- the resulting string showing characters in the source string (starting with the first character) that are not in the set string
stripIncluding
Searches the source string, starting with the first character, for any characters in the (include) set string. Strips all characters from the string, except those in the include set.
Syntax
spanExcluding( [in] string source, [in] string set, [out] Collection(string) result )
Parameters
- source
- the string you want searched
- set
- the string of characters you designate to be compared with characters in the source string
- result
- the resulting string showing all instances of characters also in the set string
substr
Retrieves a substring from the given string.
Syntax
substr( [in] string str, [in] int start, [in] int after, [out] string result )
Parameters
- str
- the string from which to retrieve the substring
- start
- the starting index in the original string of the substring
- after
- the index in the original string directly after the end of the substring
- result
- the resulting substring to be returned
toLower
Converts all letters in a string to lower-case letters.
Syntax
toLower( [in] string inStr, [out] string outStr )
Parameters
- inStr
- the string you want to convert
- outStr
- the converted string to be returned
toUpper
Converts all letters in a string to upper-case letters.
Syntax
toUpper( [in] string inStr, [out] string outStr )
Parameters
- inStr
- the string you want to convert
- outStr
- the converted string to be returned
trim
Trims whitespace from the beginning and end of the input string.
Syntax
trim( [in] string inputString, [out] string outputString )
Parameters
- inputString
- the string you want to trim
- outputString
- the trimmed string to be returned
urlDecode
Changes URL compatible symbols and characters in a source string to a string of equivalent ASCII characters (for example %20 becomes a space, %2C becomes a comma).
Syntax
urlDecode( [in] string source, [out] string dest)
Parameters
- source
- the string you want decoded
- dest
- the decoded string to be returned
urlEncode
Changes characters in a string not compatible with a URL to URL compatible symbols and characters (for example, a space becomes %20, and a comma becomes %2C).
Syntax
urlEncode( [in] string source, [out] string dest)
Parameters
- source
- the string you want to encode
- dest
- the encoded string to be returned
validEmail
Verifies that the given email address is a valid email address.
<p class="admonition_Body">Note This function only validates whether the address is structured like an email address. It does not determine whether the email address is real, that is, valid according to the mail server at the email address's domain.</p>
Syntax
validEmail( [in] string email, [out] boolean isValid )
Parameters
- the email address to check
- isValid
- if the email address is valid, then isValid is true; otherwise, isValid is false
validPassword
Verifies that the given password is a valid password.
Syntax
validPassword( [in] string password, [in] int minLength, [in] string modifiers, [out] boolean result )
Parameters
- password
- the password to check
- minLength
- the minimum number of characters a password can have
- modifiers
- currently the only modifier implemented is require-numbers; to require a valid password to contain some numbers set this argument to require-numbers
- result
- if the password is valid, then result is true; otherwise, result is false
xmlDecode
Changes XML compatible symbols and characters in a string to equivalent ASCII characters. For example, " is converted to a quote mark (").
Syntax
xmlDecode( [in] string inputString, [out] string ouputString )
Parameters
- inputString
- the string you want to decode
- ouputString
- the decoded string to be returned
xmlEncode
Changes characters in a string not compatible with XML to XML compatible symbols and characters. For example, a quote mark (") is converted to ".
Syntax
xmlEncode( [in] string inputString, [out] string outputString )
Parameters
- inputString
- the string you want to encode
- outputString
- the encoded string to be returned
Properties
Common Properties
Specialized Properties
None.
Unique Properties
None.
Best Practices