String Functions

When using string manipulation functions supported by FME Workbench, use the following guidelines to escape commas (,) and double quotes (") inside string input parameters:

• If a string input parameter contains commas, enclose the entire string in double quotes. For example, @FindString(@Value(_src),"2,3")
• If a string input parameter starts and/or ends in double quotes, enclose the entire string in double quotes, and escape any other double quotes by preceding with a backslash (\"). For example, @FindString(@Value(_src),""He said, \"Wow!\"""). If a string input parameter does not start and/or end in double quotes, but contains double quotes elsewhere inside the string, it is not necessary to escape them.

ConvertEncoding(str1, str2, [caseSensitive])

Encodes the string specified by str2 to the desired encoding specified by str1. If str2 is Null, it is set to the desired encoding but the output value is Null. If caseSensitiveis FALSE (default), the original (source) encoding of str2 is not considered; that is, the string is tagged with the new encoding without any changes to the string. If caseSensitive is TRUE, the source string is converted to the desired encoding based on the source encoding.

For a list of valid encoding values for str1, temporarily add the equivalent transformer AttributeEncoder to your workspace, open the transformer parameters dialog, and open the Destination Encoding drop-down list. The valid values are in parentheses (for example, utf-8).

FindRegEx(str, regExp, [startIdx], [caseSensitive], [caretMode])

Returns the index in string str starting at startIdx that matches regExp , or -1 if the string is not found. If startIdx is not specified, the search starts at index 0. If caseSensitive is FALSE, the search is case insensitive. Otherwise, the search is case sensitive.

The caretMode parameter can be used to instruct whether ^ should match at index 0 or at the offset. If TRUE, the caret starts at 0. If FALSE, the caret corresponds to the offset.

Equivalent transformer: StringSearcher

FindString(str, findStr, [startIdx], [caseSensitive])

Returns the index in string str starting at startIdx that matches findStr , or -1 if the string is not found. If startIdx is a negative integer, FindString() returns the index in str starting at startIdx from the end of str , then matching findStr going forward (from left to right). If startIdx is not specified, the search starts at index 0. If caseSensitive is FALSE, the search is case-insensitive. Otherwise, the search is case-sensitive.

Equivalent transformer: StringSearcher

Format(formatStr, num)

Formats the specified number num according to % conversion specifier formatStr, and returns the resulting string. This function calls Tcl function format to format the number by creating a command string in the form format {formatStr} {num}.

The % character must precede formatStr. For example, to return string 12345.68 from floating point value 12345.6789: Format(%.2f,12345.6789)

For more information about specifying formatStr, see http://www.astro.princeton.edu/~rhl/Tcl-Tk_docs/tcl/format.n.html.

FullTitleCase(str)

Returns a string with the first letter of each word, rather than just the first letter in the string, converted to its Unicode title case variant (or to uppercase if there is no title case variant) and the rest of the string lowercase.

The function ignores parentheses if they start the string or follow whitespace, and treats hyphens (-) as whitespace characters.

Equivalent transformer: StringCaseChanger

GetWord(str, wordNum)

Returns the wordNumth word in str . If wordNum is a negative integer, GetWord() returns the wordNumth word from the end of str. If there is no word at wordNum, an empty string is returned. Words in str must be delineated by blank spaces (space, tab, return carriage, and others).

Left(str, n)

Returns a substring that contains the n leftmost characters of str.

LowerCase(str)

Returns a string with all letters in str converted to lower case.

Equivalent transformer: StringCaseChanger

PadLeft(str, n, [char])

Returns the input string with at least n characters. If the input string str is not n characters long, it is padded with a prefix to this length with the specified char. If no char is specified, then a space is used.

Equivalent transformer: StringPadder

PadRight(str, n, [char])

Returns the input string with at least n characters. If the input string str is not n characters long, it is padded with a suffix to this length with the specified char. If no char is specified, a space is used.

Equivalent transformer: StringPadder

ReplaceRegEx(str, regExp, newStr, [caseSensitive])

Returns a string with all character sequences that match regExp replaced with newStr. If caseSensitive is FALSE, the search is case insensitive. Otherwise, the search is case sensitive.

Note: If an argument contains commas or parentheses, enclose the argument inside double quotes. For example: @ReplaceRegEx(@Value(string1),"[^\,](.*)",\1)

Equivalent transformer: StringReplacer

ReplaceString(str, oldStr, newStr, [caseSensitive])

Returns a string with every instance of oldStr in str replaced with newStr. If caseSensitive is FALSE, the search is case insensitive. Otherwise, the search is case sensitive.

Equivalent transformer: StringReplacer

Right(str, n)

Returns a substring that contains the n rightmost characters of str.

StringLength(str)

Returns the length of the input string.

Equivalent transformer: StringLengthCalculator

Substring(str, startIdx[, n])

Returns a substring of str starting at startIdx and includes n characters. If startIdx is a negative integer, Substring() returns a substring of str, starting at StartIdx from the end of str going backwards, and including n characters counting forward (from left to right). If n is not specified, then the substring starts at startIdx and goes to the end of the string. If startIdx is greater than the length of str, an empty string is returned.

TitleCase(str)

Returns a string with the first character in str converted to its Unicode title-case variant (or to uppercase if there is no title case variant) and the rest of the string lowercase.

Equivalent transformer: StringCaseChanger

Trim(str, [chars])

Returns a string in which the characters in str match the characters in chars, with leading and trailing characters in str removed. If chars is not specified, whitespace is removed (tab, space, carriage return).

TrimLeft(str, [chars])

Returns a string in which the characters in str match the characters in chars, with leading characters in str removed. If chars is not specified, whitespace is removed (tab, space, carriage return).

TrimRight(str, [chars])

Returns a string in which the characters in str match the characters in chars, with trailing characters in str removed. If chars is not specified, whitespace is removed (tab, space, carriage return).

UpperCase(str)

Returns a string with all letters in str converted to upper case.

Equivalent transformer: StringCaseChanger

WordCount(str)

Returns the number of words in str. Words are delineated by blank spaces (space, tab, carriage return, and others).