This section contains brief descriptions of the functions that apply to string values.
Function | What it does |
---|---|
convert | Converts a string to another data type or converts another data type to a string. |
decode | Converts an encoded string expression back to the original string. |
encode | Converts a string expression to a meaningless text string. |
hex | Translates a string literal containing hexadecimal character codes into an ASCII string. |
in_set | Returns the Boolean value true if one string is composed entirely of characters from another string. |
is_number | Returns the Boolean value true if a string expression evaluates to a float or integer value. |
is_time | Returns the Boolean value true if a string expression evaluates to a valid time value. |
len | Returns the length of a string. |
Changes a string's characters to lowercase or uppercase. | |
Deletes blanks or specified characters from the beginning (ltrim), end (rtrim), or both ends (trim) of a string. | |
max | Returns the largest value from a list of expressions of any supported data type. |
min | Returns the smallest value from a list of expressions of any supported data type. |
numbertostring | Converts a float or integer expression to a string expression, using a specified mask. |
repeat | Creates a string by repeating another string a specified number of times. |
strins | Inserts one string into another string at a specified location. |
strloc | Returns the starting position of a substring within a string. If the substring is not found, the function returns zero. |
stringtotime | Converts a string expression to a time expression, using a specified mask. |
substitute | Within a string, replaces one substring with another. |
substr | Returns a substring given a specified starting position and length. |
timetostring | Converts a time expression to a string expression, using a specified mask. |
translate | Replaces characters in a string. |
xmlencode | Converts an XML field to a string expression. |
xmldecode | Converts a string expression to XML. |
This function translates a string literal of hexadecimal character codes into an ASCII string. The hex function can express any character, although you generally use it for characters that do not have ASCII representations, such as tabs.
hex (hex_codes)
where hex_codes is a string literal containing the hex
code for a character or a series of characters.hex ("616263")
This function creates a new string by replacing the characters in one string with the characters you specify. The translate function is useful for encoding characters.
translate (source_string, search_string,
replace_string)
where:Parameter | Description |
---|---|
source_string | The string containing the characters to be replaced. |
search_string | The string of characters within source_string to replace. Must be the same length as replace_string. |
replace_string | The string of replacement characters. Must be the same length as search_string. |
The search-and-replace occurs on a per-character basis. If the search string is "abc" and the replace string is "def", the function translates "a" to "d", "b" to "e", and "c" to "f" in the newly created string.
source_string contains "*123-#44-!999"
search_string contains "#*!-"
replace_string contains "XYZ&"
the
function outputs the following new string:Y123&X44&Z999
Note that the contents of the source string, the search string, and the replace string do not change.
translate (str, ".,", ",.")
lower (string_exp)
upper (string_exp)
where
string_exp is the string expression to convert.This function compares two strings, returning a Boolean value of true if every character in the first string is contained somewhere in the second string. If the first string contains at least one character that is not also contained in the second string, the function returns a value of false. The characters need not appear in the same order in both strings; also, the second string can contain additional characters.
in_set (subset_string, superset_string)
where:Parameter | Description |
---|---|
subset_string | The string expression containing only the subset characters. |
superset_string | The string expression to which subset_string is compared. |
in_set (name, "abcdefghijklmnopqrstuvwxyz")
the function
returns true if name = "jim"
but false if
name = "Fido"
or name = "a.b"
len (string_expr)
where string_expr is a string expression whose length
is to be calculated.len ("Hamilton Burger")
repeat (string_expr, repeat_num)
where:Parameter | Description |
---|---|
string_expr | The string expression to be repeated. |
repeat_num | The number of times to repeat string_exp. |
repeat ("abcd", 5)
A substring is a part of a source string; it can be less than or equal to the length of the source string. For example, Good, Morn, od Morni, and Good Morni are all substrings of Good Morning.
Use the strloc function to find out where a particular substring occurs in a source string. This function returns the starting character position of the substring in the source string.
If the substring can be found in the source string more than once, the function returns the starting position of its first occurrence. If the substring is not found, or if the substring is longer than the source string, the function returns zero.
strloc (source_string, sub_string)
where:Parameter | Description |
---|---|
source_string | The string in which to search for the substring. |
sub_string | The string to search for. |
strloc ("Good Morning", "Morning")
This function extracts a substring from a source string, thereby creating a new string. You specify the source string and the character position where the extraction begins. In addition, you can optionally supply the number of characters to be extracted; if you do not provide this information, the extraction stops at the end of the source string.
substr (source_string, start_pos {, length})
where:Parameter | Description |
---|---|
source_string | The source string. |
start_pos | The character position at which extraction begins. |
length | The number of characters to be extracted (for example, the length of the extracted string). |
substr ("Good Morning!", 6, 7)
This function can also extract zero-length strings (strings with no characters between the quotes) at a position of one more than the length of a string. This usage is helpful for algorithms which have zero-length strings as an edge condition. You can extract characters from positions 1 through the last character of the string +1; so, positions 1 and the length of the string +1 are edge conditions.
Runtime errors occur if:
strins (source_string, insert_string, start_pos)
where:Parameter | Description |
---|---|
source_string | The string that will be combined with insert_string to produce a new string. |
insert_string | The string that will be combined with source_string to produce a new string. |
start_pos | The position in source_string at which the insertion begins; the value ranges from 1 to the length of source_string + 1. A runtime error occurs if you specify a value less than 1 or greater than source_string + 1. |
insert_str = "Mr. Jones,"
and that
source_str = "Good morning, what a lovely day."
strins (source_str, insert_str, 15)
Good morning, Mr. Jones, what a lovely day.
substitute (source_string, unwanted_string,
replacement_string)
where:Parameter | Description |
---|---|
source_string | The string that contains unwanted_string. |
unwanted_string | A substring of source_string. |
replacement_string | The string that will replace unwanted_string to create a new string. |
substitute (TestString, "abc", "wxyz")
TestString = "abcdabcd"
the function returns the following new
string:wxyzdwxyzd
Note that the contents of the source string, the unwanted
string, and the replacement string do not change.These functions create a new string by copying an existing source string and deleting blanks or specified characters from the beginning (ltrim), end (rtrim), or both ends (trim) of the new string. In all cases, the source string remains unchanged.
ltrim (string_expr{, trim_char}opt)
rtrim (string_expr{, trim_char}opt)
trim (string_expr{, trim_char}opt)
where:Parameter | Description |
---|---|
string_expr | The source string expression to copy. |
trim_char | An optional parameter that specifies the characters to be deleted from the new string. If you do not specify this parameter, blanks are deleted. Depending on the function, the deletion starts at either the beginning, end, or both ends of the new string and continues until a character not specified in trim_char (or a non-blank character) is found. |
LastName = "Smith"
and the returned new string is
"Smith"
ltrim (LastName)
Status = "OpenXY&Z&&&&"
the returned new string
is
"OpenXY&Z"
rtrim (Status, "&")
rtrim (AccountName, "0123456789")
This function determines whether the specified string expression evaluates to a float or integer value. The is_number function returns the Boolean value true if the entire string (not just a substring) evaluates to a float or integer and false otherwise.
is_number (expr)
where expr is a string
expression.is_number ("123.4")
is_number ("no")
is_number ("abc63j")
This function determines whether the specified string expression evaluates to a time value of a specified format. The is_time function returns the Boolean value true if the entire string (not just a substring) evaluates to a time that is formatted as specified; otherwise, the function returns a value of false.
is_time (str_expr, date_time_mask)
where:Parameter | Description |
---|---|
str_expr | A string expression. |
date_time_mask | A date/time mask that specifies the format which str_expr must use in order for is_time to return a value of true. |
is_time ("nov121995", "mm/dd/yyyy")
is_time ("11/12/1995", "mm/dd/yyyy")
timetostring (time_expr, date_time_mask)
where:Parameter | Description |
---|---|
time_expr | An expression of type time. |
date_time_mask | A date/time mask that determines the format of the timetostring function's output. |
timetostring (systemtime(), "mm/dd/yyyy hh:tt:ss am")
7/1/1985 12:45:06 pm
See information about the systemtime() function.
stringtotime (string_expr, date_time_mask)
where:Parameter | Description |
---|---|
string_expr | An expression of type string. |
date_time_mask | A date/time mask that specifies the time format to use for the conversion. |
stringtotime (HostTime, "mon. dd, yyyy hh:tt:ss am")
HostTime = "Jul. 1, 1985 12:45:06 pm"
then the
resulting output is the time value equivalent to July 1, 1985 at 6 seconds past 12:45 p.m.These function convert strings into meaningless strings for the purpose of disguising the contents. Both the encode and the decode must be in the same workflow.
encode (string_expr)
decode (string_expr)
where:Parameter | Description |
---|---|
string_expr | An expression of type string. The string cannot be a literal. |