String Formatters

Version 20.0.7580


String Formatters

Version 20.0.7580


The following is a list of formatters that manipulate string data. The syntax for all formatters is the same: attributes (variables) are “piped” in to formatters from left-to-right, e.g.:

[attr | formatter1() | formatter2()]

The attribute 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 would return ‘lo’:

[myString | substring(4)]

allownull()

Returns NULL if the attribute does not exist or the value if it does.

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 width specified by the first parameter. Padding is done using the fillchar specified by the second parameter.

  • width: The total width of the output string.
  • character: The optional character used for padding. If not specified this defaults to a space.

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

Returns true (or ifcontains) if the attribute value contains the parameter value, false (or ifnotcontains) otherwise.

  • value: The string to find from the attribute value.
  • ifcontains: The optional value returned if the attribute value contains the parameter value.
  • ifnotcontains: The optional value 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 specified by the first parameter.

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

currency([integer_count])

Returns the numeric value formatted as currency.

  • count: The optional number specifying how many places to the right of the decimal are displayed. The default 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. Default is 2.

def([notexists][, exists])

Checks for the existence of an attribute and returns the specified parameter value if it does not.

  • 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 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.

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

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

Determines whether the attribute value ends with the specified parameter. Returns true (or iftrue) if the attribute ends with the value and false (or iffalse) if not.

  • substring: The string expected at the end.
  • iftrue: The optional value returned if the attribute value ends with the parameter value.
  • iffalse: The optional value 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 and returns true (or ifequals) if they are equal and false (or ifnotequals) if they are not.

  • value: The string to compare with the attribute value.
  • ifequals: The optional value returned if the attribute value equals the value represented by the first parameter.
  • ifnotequals: The optional value returned if the attribute value does not equal the value represented by the first parameter.

extendtabs([integer_width])

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

  • width: The optional tab width, defaults to 8 if not specified.

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 ID value. The attribute that is passed into this formatter is ignored, so common practice is to use the default item ‘_’ as the formatter input, e.g.: [_ | guid()]

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

Compares the attribute value with the first parameter value and returns true (or ifequals) if they are equal and false (or ifnotequals) if they are not.

  • value: The string to compare with the attribute value.
  • ifequals: The optional value returned if the attribute value equals the value represented by the first parameter.
  • ifnotequals: The optional value returned if the attribute value does not equal the value represented by the first parameter.

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

Returns true (or ifmatch) if the attribute value matches the first parameter, otherwise false (or ifnotmatch).

  • value: The value that will be compared with the attribute value.
  • ifmatch: The optional value returned if the attribute value matches the parameter value.
  • ifnotmatch: The optional value returned if the attribute value does not match the parameter value.

iftrue([iftrue][, iffalse])

Checks the attribute value and returns true (or iftrue) if true and false (or iffalse) if false.

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

implode([separator])

Implodes multiple values to a string 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 true (or ifalpha) if all characters in the attribute value are alphabetic and there is at least one character, false (or ifnotalpha) otherwise.

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

isalphabetic([ifalpha][, ifnotalpha])

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

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

isalphanum([ifalphanum][, ifnotalphanum])

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

  • ifalphanum: The optional value returned if the attribute value contains only alphabetic or numeric characters.
  • ifnotalphanum: The optional value returned if the attribute value contains nonalphabetic or nonnumeric characters.

isalphanumeric([ifalphanum][, ifnotalphanum])

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

  • ifalphanum: The optional value returned if the attribute value contains only alphabetic or numeric characters.
  • ifnotalphanum: The optional value returned if the attribute value contains nonalphabetic or nonnumeric characters.

isdigit([ifnum][, ifnotnum])

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

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

islower([iflower][, ifnotlower])

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

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

isnumeric([ifnum][, ifnotnum])

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

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

isspace([ifspace][, ifnotspace])

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

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

isupper([ifupper][, ifnotupper])

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

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

join([separator])

Implodes multiple values to a string 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 attribute value left-justified in a string of length specified by the first parameter. Padding is done using the fillchar specified by the second parameter.

  • width: The total width of the output string.
  • character: The optional character used for padding. The default 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 attribute value left-justified in a string of length specified by the first parameter. Padding is done using the fillchar specified by the second parameter.

  • width: The total width of the output string.
  • character: The optional character used for padding. The default is a space.

lsplit(delimiter, integer_index)

Splits the string 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 used as a separator for splitting the string into tokens.
  • index: The index of the token requested where the first token is at index 1.

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

Searches the string 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.

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. Default is true.

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

Compares the attribute value with the first parameter value. Returns true (or notequals) if they are not equal and false (or equals) if they are.

  • value: The string to compare with the attribute value.
  • notequals: The optional value returned if the attribute value does not equal the value represented by the first parameter.
  • equals: The optional value returned if the attribute value equals the value represented by the first parameter.

nowhitespace()

Removes the white space from the string 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 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 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.

regexreplace(search, replacewith[, integer_startat])

Replaces all occurrences of the regular expression pattern 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. Default is 0.

remove(integer_index[, integer_count])

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

  • index: The position to begin deleting the characters.
  • count: The optional number of characters to delete. If not provided all characters starting from the specified index will be deleted.

replace(oldvalue, newvalue[, ishex])

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

  • oldvalue: The string to be replaced.
  • newvalue: The string to replace all occurrences of the first parameter.
  • ishex: The optional boolean value specifying whether the first parameter is a hex representation of a character to replace. Default 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 length specified by the second parameter. Padding is done using the fillchar specified by the first parameter.

  • width: The total width of the output string.
  • character: The optional character used for padding, if not specified this defaults to a space.

rsplit(delimiter, integer_index)

Splits the string 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 used as a separator for splitting the string into tokens.
  • index: The index of the token 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. Default is true.

substring(integer_index[, integer_length])

Returns a substring of the attribute value; starts at the index 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 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 used as a separator for splitting the string into tokens.
  • index: The index of the token 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. Default is SQL.

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

Returns true (or iftrue) if the attribute value starts with the specified parameter, false (or iffalse) otherwise.

  • 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 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 represented by the attribute value with all characters converted to lowercase.

toupper()

Returns the string 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 specified by the parameter.

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

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

Wraps a string to a certain width while respecting word boundaries.

  • width: The maximum line length after wrapping the string.
  • break: The character(s) used to break the string; the default value is CRLF (e.g. ‘\r\n’).
  • cut: The optional boolean value that specifies whether to wrap the string at or before the specified width. Default is false.
  • wrapexp: A regex expression representing the characters to replace when “breaking” the string; the default is the ‘space’ character (this default is intended for strings consisting of words separated by spaces). To break a string unconditionally without respecting word boundaries, set this paramater to empty string: ‘’

print([delim])

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

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

xmldecode()

Converts the attribute value to a XML decoded string.

xmlencode()

Converts the attribute value to a XML encoded string.