String Formatters

Version 23.4.8839

Common String Formatters
More String Formatters

String Formatters

Common String Formatters

The following string formatters are among the most commonly used. An example of each formatter is provided for reference.

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

Returns true if the input string contains the target, and false otherwise.

The ifcontains parameter can be set to an alternate value to return if the input string contains the target, and the ifnotcontains parameter can be set to an alternate value to return if the input string does not contain the target.

Example

<arc:set attr="myString" value="hello world" />
<arc:if exp="[myString | contains('hello')]">
  <arc:set attr="response" value="hello to you too!" />
  <arc:else>
    <arc:set attr="response" value="I would appreciate a greeting" />
  </arc:else>
</arc:if>

def(ifnotexists[, ifexists])

Sets the ‘default’ value of an attribute: if the attribute has not yet been set to a value, set it to the value passed in ifnotexists; if the attribute already exists, set it to the value passed in ifexists.

Example

<!-- count the number of loops in an XML document using xmlDOMSearch -->

<arc:set attr="xml.uri" value="[FilePath]" />
<arc:set attr="xml.xpath" value="/Items/test/loop" />

<arc:call op="xmlDOMSearch" in="xml">
  <!-- this code will execute for each occurrence of the 'xpath' in the XML document -->
  <arc:set attr="loopCount" value="[loopCount | def(0) | add(1)]" />
</arc:call>

equals(value[, ifequal][, ifnotequal])

Returns true if the input attribute matches the value, and false otherwise.

If ifequal and/or ifnotequal are provided, the values in these parameters will be returned instead of true and false, respectively.

Example

<arc:set attr="myItem.code" value="[xpath(data/lineitems/itemcode)]" />
<arc:if exp="[myItem.code | equals('A5')]">
  <arc:set attr="myItem.name" value="spoon" />
  <arc:else>
    <arc:set attr="myItem.name" value="fork" />
  </arc:else>
</arc:if>

find(target[, startindex])

Searches the input string and returns the position in this string where the target first appears (zero-based index).

If startindex is provided, the formatter will start searching for the target starting at this index in the input string (i.e. will ignore instances of the target that appear earlier than startindex).

Example

<arc:set attr="myString" value="Please excuse my dear Aunt Sally." />
<arc:set attr="whereIsSally" value="[myString | find('Sally')]" />
<!-- whereIsSally has the value: 27 -->

getlength()

Returns the number of characters in the input attribute.

Example

<arc:set attr="myString" value="hello world" />
<arc:set attr="stringLength" value="[myString | getlength()]" />

guid(includehyphens)

Generates a globally-unique identifier (GUID) value. By default, the formatter returns all of the characters in a single, unformatted string. To include hyphens that conform to the standard 8-4-4-4-12 GUID format, use the includehyphens parameter, and set it to true.

This formatter does not modify the input attribute (variable), so no such input attribute is required.

Example

<arc:set attr="myGUID" value="[guid(true)]" />

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

Searches the input string for the regex pattern specified by pattern and returns the first set of characters that match the pattern.

The index parameter can be used to find occurrences other than the first; for example, providing ‘1’ for the index will find the second occurrence, and providing ‘2’ as the index will find the third occurrence. The option parameter accepts an optional comma-separated list of regular expression options (e.g. IgnoreCase, Multiline, Singleline, and IgnorePatternWhitespace).

Example

<arc:set attr="myString" value="The cost of the item is $12.98." />
<arc:set attr="decimalPattern" value="\[0-9\]+\.?\[0-9\]*" />
<arc:set attr="price" value="[myString | regexmatch([decimalPattern])]" />
<!-- price has the value: 12.98 -->

replace(oldvalue, newvalue[, ishex])

Searches the input string for each occurrence of oldvalue, removes it, and replaces it with newvalue.

The ishex parameter indicates if the oldvalue parameter is a hex representation of a character to replace (default false).

Example

<arc:set attr="myString" value="I hope you have a wonderful day." />
<arc:set attr="honestString" value="[myString | replace('you', 'I')]" />
<!-- honestString holds the value: I hope I have a wonderful day. -->

regexreplace(pattern, newvalue[, startindex])

Searches the input string for the regex pattern specified by pattern and replaces each occurrence with newvalue.

If the startindex parameter is provided, the search will begin at this position in the string (i.e. the formatter will ignore instances of the pattern that occur prior to startindex).

Example

<arc:set attr="myString" value="The cost of the item is $12.98." />
<arc:set attr="decimalPattern" value="\[0-9\]+\.?\[0-9\]*" />
<arc:set attr="updatedListing" value="[myString | regexreplace([decimalPattern],'10.99')]" />
<!-- updatedListing has the value: The cost of the item is $10.99 -->

split(delimiter, indextoreturn)

Splits the input string at each occurrence of the delimiter into a set of substrings, then returns the string at the given index.

If indextoreturn is provided, then the set of substrings is indexed to return one of the substrings (e.g. passing ‘1’ as the indextoreturn would return the first substring that resulted from the split).

Example

<arc:set attr="myName" value="Walter White" />
<arc:set attr="firstName" value="[myName | split(' ',1)]" />
<!-- firstName contains the value: Walter -->

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

Returns true if the input string starts with the value specified as the target, and false otherwise.

If iftrue is provided, this value is returned instead of true when the target is found, and if iffalse is provided, this value is returned instead of false when the target is not found.

Example

<arc:set attr="myString" value="Sir, your carriage is ready." />
<arc:if exp="[myString | startswith('Sir')"]>
  <arc:set attr="response" value="Thank you." />
  <arc:else>
    <arc:set attr="response" value="Use your manners." />
  </arc:else>
</arc:if>

substring(index[, length])

Returns a substring of the input string value, starting at the index value and ending length characters later. If length is not provided, the substring will end at the end of the original string.

Example

<!-- parse out the characters before the first comma, combining substring() with find() -->

<arc:set attr="myString" value="Luke, I am your father". />
<arc:set attr="commaPosition" value="[myString | find(',')]" />
<arc:set attr="introClause" value="[myString | substring(0, [commaPosition])]" />
<!-- introClause has the value: Luke -->

trim()

Removes leading and trailing whitespace from the input string.

Example

<arc:set attr="uglyString" value="    here is some data.  " />
<arc:set attr="prettyString" value="[uglyString | trim()]" />

Vault(ItemName)

Returns the value of an item in the Global Settings Vault that matches the provided value for ItemName.

Note: Use caution when referring to encrypted vault items in scripting contexts to ensure that sensitive information is not included in the logs.

Example

<arc:set attr="URLtoResource" value="[Vault(commonURL)]" />

More String Formatters

Below is the list of less-common formatters, grouped by functionality.

Capitalization Formatters

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.

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.

Encoding/Decoding Formatters

base64decode()

Converts the attribute value to a base 64 decoded string.

base64encode()

Converts the attribute value to a base 64 encoded string.

jsonescape()

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

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.

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.

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.

xmldecode()

Converts the attribute value to a XML decoded string.

xmlencode()

Converts the attribute value to a XML encoded string.

Joining Formatters

concat([newString])

Concatenates the value piped into the formatter with the parameter passed to the formatter

newString: The string to append to the attribute.

join([separator])

implode([separator])

Implodes multiple values to a string separated by a separator.

separator: The optional separator.

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.

Logical Formatters

allownull()

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

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.

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.

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.

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.

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.

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.

Parsing Formatters

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.

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.

striphtml()

Returns the string with any HTML markup removed.

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.

toalpha()

Returns only the letters in a string.

toalphanum()

Returns only the alphanumeric characters in a string.

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.

Searching Formatters

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.

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.

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.

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.

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.

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.

Whitespace Formatters

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.

expandtabs([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.

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.

nowhitespace()

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

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.

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.

trimend()

Trims trailing white space from an attribute.

trimstart()

Trims leading white space from an attribute.

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: ‘’