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(string str1, string str2, [bool 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 str2, 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(string str, string regExp, [int startIdx], [bool caseSensitive], [-1])

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. If -1 is specified, FindRegEx() returns the index in str starting at startIdx from the end of str going backwards.

Equivalent transformer: StringSearcher

FindString(string str, string findStr, [int startIdx], [bool 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(string formatStr, float num)

Formats the specified number as specified by 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}.

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

FullTitleCase(string 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(string str, int 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(string str, int n)

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

LowerCase(string str)

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

Equivalent transformer: StringCaseChanger

PadLeft(string str, int n, [string 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(string str, int n, [string 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(string str, string regExp, string newStr, [bool 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(string str, string oldStr, string newStr, [bool 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(string str, int n)

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

StringLength(string str)

Returns the length of the input string.

Equivalent transformer: StringLengthCalculator

Substring(string str, int startIdx[, int 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(string 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(string str, [string chars])

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

TrimLeft(string str, [string chars])

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

TrimRight(string str, [string chars])

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

UpperCase(string str)

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

Equivalent transformer: StringCaseChanger

WordCount(string str)

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