String Formatters

Version 24.1.8910


String Formatters


The list of formatters on this page manipulate string data. The syntax for all formatters is the same, as shown below:

[attr | formatter1() | formatter2()]

Attributes (variables) are piped in (using a vertical pipe character - |) to formatters from left to right. The attribute that is piped into string formatters should always be the raw string upon which an operation should be performed. For example, if the attribute myString is set to hello, then the following code returns a value of lo:

[myString | substring(4)]


allownull()

Returns NULL if the attribute does not exist; otherwise, the formatter returns the value if the attribute does exist.

arrayfind(substring)

Returns the index at which the string is found in the attribute array. The index is 1 based.

  • searchstring: The string to search for in the original value.

base64decode()

Converts the attribute value to a base-64 decoded string.

base64encode()

Converts the attribute value to a base-64 encoded string.

capitalize()

Returns the original attribute value with only its first character capitalized.

capitalizeall()

Returns the original attribute value with the first character of all words capitalized.

center(integer_width[, character])

Returns the attribute value centered in a string of a width that is specified by the first parameter. The padding is done by using the fillchar that is specified by the second parameter.

  • width: The total width of the output string.

  • character: The optional character that is used for padding. If a character is not specified, the default character is a space.

contains(value[, ifcontains][, ifnotcontains])

Returns a value of true (or ifcontains) if the attribute value contains the parameter value; otherwise, the value false (or ifnotcontains) is returned.

  • value: The string to find from the attribute value.

  • ifcontains: The optional value that is returned if the attribute value contains the parameter value.

  • ifnotcontains: The optional value that is returned if the attribute value does not contain the parameter value.

count(substring)

Returns the number of occurrences in the attribute value of a substring that is specified by the first parameter.

  • substring: The substring to search for in the attribute value.

currency([integer_count])

Returns the numeric value formatted as a currency value.

  • count: The optional number that specifies how many places to the right of the decimal are displayed. The default count is 2.

decimal([integer_count])

Returns the numeric value formatted as a decimal number.

  • count: The optional number that indicates how many places to the right of the decimal are displayed. The default count is 2.

def([notexists][, exists])

Checks for the existence of an attribute. If the attribute does not exist, the specified parameter value is returned.

  • notexists: The optional value to return if the attribute value does not exist.

  • exists: The optional value to return if the original attribute exists. If a value is not specified, the original value of the attribute is returned.

empty(value)

Returns the specified value if the attribute value is empty; otherwise, the original attribute value is returned.

  • value: The value that is used if the attribute is empty.

endswith(substring[, iftrue][, iffalse])

Determines whether the attribute value ends with the specified parameter. Returns a value of true (or iftrue) if the attribute ends with the value; otherwise, the value false (or iffalse) is returned.

  • substring: The string that is expected at the end.

  • iftrue: The optional value that is returned if the attribute value ends with the parameter value.

  • iffalse: The optional value that is returned if the attribute value does not end with the parameter value.

equals(value[, ifequals][, ifnotequals])

Compares the attribute value with the first parameter value. Returns a value of true (or ifequals) if the values are equal; otherwise, a value of false (or ifnotequals) is returned.

  • value: The string to compare with the attribute value.

  • ifequals: The optional value that is returned if the attribute value equals the value represented by the first parameter.

  • ifnotequals: The optional value that is returned if the attribute value does not equal the value represented by the first parameter.

extendtabs([integer_width])

Replaces all tab characters that are found in the attribute value with spaces. If the tab size that is specified by the parameter is not given, a default tab size of eight characters is used.

  • width: The optional tab width. The default value is 8.

expr(expression)

Evaluates the mathematical expression.

  • expression: The expression.

find(substring[, integer_startindex])

Returns the lowest zero-based index at which the substring is found in the attribute value.

  • substring: The string to search for in the attribute value.

  • startindex: The optional index at which to start the search.

getlength()

Returns the number of characters in the attribute value.

guid()

Generates and returns a globally-unique identifier (Id) value. The attribute that is passed into this formatter is ignored. Therefore, common practice is to use the default item _ as the formatter input (for example, [_ | guid()]).

ifequal(value[, ifequals][, ifnotequals])

Compares the attribute value with the first parameter value. Returns a value of true (or ifequals) if they are equal; otherwise, a value of false (or ifnotequals) is returned.

  • value: The string to compare with the attribute value.

  • ifequals: The optional value that is returned if the attribute value equals the value represented by the first parameter.

  • ifnotequals: The optional value that is returned if the attribute value does not equal the value represented by the first parameter.

ifmatches(value[, ifmatch][, ifnotmatch])

Returns a value of true (or ifmatch) if the attribute value matches the first parameter; otherwise, a value of false (or ifnotmatch) is returned.

  • value: The value that is compared with the attribute value.

  • ifmatch: The optional value that is returned if the attribute value matches the parameter value.

  • ifnotmatch: The optional value that is returned if the attribute value does not match the parameter value.

iftrue([iftrue][, iffalse])

Checks the attribute value. Returns a value of true (or iftrue) if the attribute value is true; otherwise, a value of false (or iffalse) is returned.

  • iftrue: The optional value that is returned if the attribute value is true.

  • iffalse: The optional value that is returned if the attribute value is false.

implode([separator])

Implodes multiple values to a string that is separated by a separator.

  • separator: The optional separator.

insert(integer_index, string)

Inserts the specified string at the specified index.

  • index: The zero-based index of the position in the original value where the new string should be inserted.

  • string: The string to insert into the original value.

isalpha([ifalpha][, ifnotalpha])

Returns a value of true (or ifalpha) if all characters in the attribute value are alphabetic and there is at least one character; otherwise, a value of false (or ifnotalpha) is returned.

  • ifalpha: The optional value that is returned if the attribute value is alphabetic.

  • ifnotalpha: The optional value that is returned if the attribute value is not alphabetic.

isalphabetic([ifalpha][, ifnotalpha])

Returns a value of true (or ifalpha) if all characters in the attribute value are alphabetic and there is at least one character; otherwise, a value of false (or ifnotalpha) is returned.

  • ifalpha: The optional value that is returned if the attribute value is alphabetic.

  • ifnotalpha: The optional value that is returned if the attribute value is not alphabetic.

isalphanum([ifalphanum][, ifnotalphanum])

Returns a value of true (or ifalphanum) if all characters in the attribute value are alphanumeric and there is at least one character; otherwise, a value of false (or ifnotalphanum) is returned.

  • ifalphanum: The optional value that is returned if the attribute value contains only alphabetic or numeric characters.

  • ifnotalphanum: The optional value that is returned if the attribute value contains nonalphabetic or nonnumeric characters.

isalphanumeric([ifalphanum][, ifnotalphanum])

Returns a value of true (or ifalphanum) if all characters in the attribute value are alphanumeric and there is at least one character; otherwise, a value of false (or ifnotalphanum) is returned.

  • ifalphanum: The optional value that is returned if the attribute value contains only alphabetic or numeric characters.

  • ifnotalphanum: The optional value that is returned if the attribute value contains nonalphabetic or nonnumeric characters.

isdigit([ifnum][, ifnotnum])

Returns a value of true (or ifnum) if all characters in the attribute value are digits and there is at least one character; otherwise, a value of false (or ifnotnum) is returned.

  • ifnum: The optional value that is returned if the attribute value is numeric.

  • ifnotnum: The optional value that is returned if the attribute value is not numeric.

islower([iflower][, ifnotlower])

Returns a value of true (or iflower) if all letters in the attribute value are lowercase and there is at least one character that is a letter; otherwise, a value of false (or ifnotlower) is returned.

  • iflower: The optional value that is returned if the attribute value is lowercase.

  • ifnotlower: The optional value that is returned if the attribute value is not lowercase.

isnumeric([ifnum][, ifnotnum])

Returns a value of true (or ifnum) if all characters in the attribute value are digits and there is at least one character; otherwise, a value of false (or ifnotnum) is returned.

  • ifnum: The optional value that is returned if the attribute value is numeric.

  • ifnotnum: The optional value that is returned if the attribute value is not numeric.

isspace([ifspace][, ifnotspace])

Returns a value of true (or ifspace) if there are only white-space characters in the attribute value and there is at least one character; otherwise, a value of false (or ifnotspace) is returned.

  • ifspace: The optional value that is returned if the attribute value is a space.

  • ifnotspace: The optional value that is returned if the attribute value is not a space.

isupper([ifupper][, ifnotupper])

Returns a value of true (or ifupper) if all letters in the attribute value are uppercase and there is at least one character that is a letter; otherwise, a value of false (or ifnotupper) is returned.

  • ifupper: The optional value that is returned if the attribute value is uppercase.

  • ifnotupper: The optional value that is returned if the attribute value is not uppercase.

join([separator])

Implodes multiple values to a string that is separated by a separator.

  • separator: The optional separator.

jsonescape()

Converts the attribute value to a JSON-escaped, single-line string.

just(integer_width[, character])

Returns the left-justified attribute value in a string of a length that is specified by the first parameter. The padding is done by using the fillchar that is specified by the second parameter.

  • width: The total width of the output string.

  • character: The optional character that is used for padding. The default character is a space.

lfind(substring[, integer_startindex])

Returns the lowest zero-based index at which the substring is found in the attribute value.

  • substring: The string to search for in the attribute value.

  • startindex: The optional index at which to start the search.

ljust(integer_width[, character])

Returns the left-justified attribute value in a string of a length that is specified by the first parameter. The padding is done by using the fillchar that is specified by the second parameter.

  • width: The total width of the output string.

  • character: The optional character that is used for padding. The default character is a space.

lsplit(delimiter, integer_index)

Splits the string that is represented by the attribute value into tokens delimited by the first parameter and returns the token at the index that is specified by the second parameter; counts from the left.

  • delimiter: The string that is used as a separator for splitting the string into tokens.

  • index: The index of the token that is requested, where the first token is at index 1.

match(pattern[, index][, option])

Searches the string that is represented by the attribute value for an occurrence of the regular expression supplied in the pattern parameter.

  • pattern: The regular expression pattern to match.

  • index: The optional numbered index of the match to return. The default index is 0.

  • option: The optional comma-separated list of regular expression options. Some of the commonly used options are IgnoreCase, Multiline, Singleline, and IgnorePatternWhitespace.

md5hash([converttobase64])

Computes the MD5 hash of the attribute value.

  • encodetobase64: The optional Boolean value that specifies whether to convert the result into a base-64 encoded string. The default value is true.

notequals(value[, notequals][, equals])

Compares the attribute value with the first parameter value. Returns a value of true (or notequals) if they are not equal; otherwise, a value of false(or equals) is returned.

  • value: The string to compare with the attribute value.

  • notequals: The optional value that is returned if the attribute value does not equal the value represented by the first parameter.

  • equals: The optional value that is returned if the attribute value equals the value represented by the first parameter.

nowhitespace()

Removes the white space from the string that is represented by the attribute value.

percentage([integer_count])

Returns the numeric value formatted as a percentage.

  • count: The optional number that indicates how many places to the right of the decimal are displayed.

regex(pattern[, index][, option])

Searches the string that is represented by the attribute value for an occurrence of the regular expression supplied in the pattern parameter.

  • pattern: The regular expression pattern to match.

  • index: The optional numbered index of the match to return. The default is 0.

  • option: The optional comma-separated list of regular expression options. Some of the commonly used options are IgnoreCase, Multiline, Singleline, and IgnorePatternWhitespace.

regexmatch(pattern[, index][, option])

Searches the string that is represented by the attribute value for an occurrence of the regular expression supplied in the pattern parameter.

  • pattern: The regular expression pattern to match.

  • index: The optional numbered index of the match to return. The default index is 0.

  • option: The optional comma-separated list of regular expression options. Some of the commonly used options are IgnoreCase, Multiline, Singleline, and IgnorePatternWhitespace.

regexreplace(search, replacewith[, integer_startat])

Replaces all occurrences of the regular expression pattern that is found in the attribute value with replacewith.

  • search: The regular expression to search with.

  • replacewith: The text to replace the match with.

  • startat: The optional character index at which to start replacement. The default index is 0.

remove(integer_index[, integer_count])

Deletes characters from the attribute value; begins at the zero-based index that is specified by the first parameter.

  • index: The position at which to begin deleting the characters.

  • count: The optional number of characters to delete. If a number is not specified, all characters starting from the specified index are deleted.

replace(oldvalue, newvalue[, ishex])

Replaces all occurrences of the first parameter in the string that is represented by the attribute value with the value of the second parameter.

  • oldvalue: The string that is to be replaced.

  • newvalue: The string to replace all occurrences of the first parameter.

  • ishex: The optional Boolean value that specifies whether the first parameter is a hex representation of a character to replace. The default value is false.

rfind(substring[, integer_startindex])

Returns the highest zero-based index at which the substring is found in the attribute value.

  • substring: The string to search for in the original value.

  • startindex: The optional index at which to start the search.

rjust(integer_width[, character])

Returns the right-justified attribute value in a string of a length that is specified by the second parameter. The padding is done by using the fillchar that is specified by the first parameter.

  • width: The total width of the output string.

  • character: The optional character that is used for padding. If a character is not specified, the default value is a space.

rsplit(delimiter, integer_index)

Splits the string that is represented by the attribute value into tokens delimited with the first parameter and returns the token at the index specified by the second parameter; counts from the right.

  • delimiter: The string that is used as a separator for splitting the string into tokens.

  • index: The index of the token that is requested where the first token is at index 1.

sha1hash([converttobase64])

Computes the SHA-1 hash of the attribute value.

  • encodetobase64: The optional Boolean value that specifies whether to convert the result into a base-64 encoded string. The default value is true.

substring(integer_index[, integer_length])

Returns a substring of the attribute value; starts at the index that is specified by the parameter and counts to the right.

  • index: The zero-based index at which the substring starts from the right.

  • length: The optional length of characters from the start index. The substring to the end is returned if length is not specified.

split(delimiter, integer_index)

Splits the string that is represented by the attribute value into tokens delimited by the first parameter and returns the token at the index specified by the second parameter; counts from the left.

  • delimiter: The string that is used as a separator for splitting the string into tokens.

  • index: The index of the token that is requested where the first token is at index 1.

sqlescape()

Converts the attribute value to an SQL-escaped, single-line string.

  • dbtype: The database type to encode. The allowed values are SQL or SQLite. The default type is SQL.

startswith(substring[, iftrue][, iffalse])

Returns a value of true (or iftrue) if the attribute value starts with the specified parameter; otherwise, a value of false (or iffalse) is returned.

  • substring: The string expected at the beginning.

  • iftrue: The optional value returned if the attribute value starts with the parameter value.

  • iffalse: The optional value returned if the attribute value does not start with the parameter value.

striphtml()

Returns the string with any HTML markup removed.

substring(integer_index[, integer_length])

Returns a substring of the attribute value; starts at the index that is specified by the parameter.

  • index: The zero-based index at which the substring starts.

  • length: The optional length of characters from the start index. A substring to the end of the string is returned if length is not specified.

toalpha()

Returns only the letters in a string.

toalphanum()

Returns only the alphanumeric characters in a string.

tolower()

Returns the string that is represented by the attribute value with all characters converted to lowercase.

toupper()

Returns the string that is represented by the attribute value with all characters converted to uppercase.

trim()

Trims leading and trailing white space from an attribute.

trimend()

Trims trailing white space from an attribute.

trimstart()

Trims leading white space from an attribute.

truncate(integer_count)

Truncates the attribute value to the number of characters that are specified by the parameter.

  • count: The number of characters in the resulting string.

wordwrap([integer_width][, break][, cut][, wrapexp])

Wraps a string to a given number of characters.

  • width: The optional number of characters at which the string will be wrapped.

  • break: The optional break parameter to be used to break the line.

  • cut: The optional Boolean value that specifies whether to wrap the string at or before the specified width. The default value is false.

  • wrapexp: The optional regex expression that is to be used as a breakable character. The default character is a space.

print([delim])

Returns a string with all the values of the attribute concatenated by using the specified delimiter.

  • delim: The optional delimiter with which to separate values. The default delimiter is a comma.

xmldecode()

Converts the attribute value to a XML-decoded string.

xmlencode()

Converts the attribute value to a XML-encoded string.