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(dstEncoding,string[,caseSensitive={TRUE|FALSE}])

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

For a list of valid encoding values for dstEncoding, 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).

FindRegularExpression(string,regExp[,startIdx][,captureNum][,matchNum][,caseSensitive={TRUE|FALSE}])

Returns the index in string string 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 captureNum=0 (default), the entire matching index is returned; otherwise, the specified parenthesized capture is returned. If matchNum=0 (default), FindRegularExpression() returns the first match that is found. If matchNum > 0, the search is repeated matchNum times, each time starting the search at the character after the first character of the previous match. If caseSensitive=FALSE , the search is case insensitive. If TRUE, the search is case sensitive.

Equivalent transformer: StringSearcher

Example

@FindRegularExpression(open,e) returns 2.

FindString(string,strToFind[,startIdx][,caseSensitive={TRUE|FALSE}])

Returns the index in string string starting at startIdx that matches strToFind , 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 string , then matching strToFind going forward (from left to right). If startIdx is not specified, the search starts at index 0. If caseSensitive=FALSE , the search is case-insensitive. If TRUE, the search is case-sensitive.

Equivalent transformer: StringSearcher

Format(format,number)

Formats the specified number number according to % conversion specifier format, 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 format.

Equivalent transformer: StringFormatter

For more information: https://www.astro.princeton.edu/~rhl/Tcl-Tk_docs/tcl/format.n.html

Examples

To return string 12345.68 from floating-point value 12345.6789: Format(%.2f,12345.6789)
To define a maximum field width, add a number before the decimal point. For example, Format(%10.2f,12345.6789) returns 12345.68.
To pad the left-hand side with zeros, add a zero after the % character. For example, Format(%010.2f,12345.6789) returns 0012345.68.
To add a sign, whether positive or negative, add a plus after the % sign. For example, Format(%+010.2f,12345.6789) returns +012345.68.

FullTitleCase(string)

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,index)

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

Left(string,numChars)

Returns a substring that contains the numChars leftmost characters of string.

LowerCase(string)

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

Equivalent transformer: StringCaseChanger

PadLeft(string,padLength[,char])

Returns the input string with at least padLength characters. If the input string string is not padLength 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,padLength[,char])

Returns the input string with at least padLength characters. If the input string string is not padLength 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

ReplaceRegularExpression(string,regExp,after[,caseSensitive={TRUE|FALSE}])

Returns a string with all character sequences that match regExp replaced with after. If caseSensitive=FALSE , the search is case insensitive. If TRUE, the search is case sensitive. If no match is found, string is returned.

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,before,after[,caseSensitive={TRUE|FALSE}])

Returns a string with every instance of before in string replaced with after. If caseSensitive=FALSE , the search is case insensitive. If TRUE, the search is case sensitive.

Equivalent transformer: StringReplacer

Right(string,numChars)

Returns a substring that contains the numChars rightmost characters of string.

StringLength(string)

Returns the length of the input string.

Equivalent transformer: StringLengthCalculator

Substring(string,startIdx[,numChars])

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

SubstringRegularExpression(string,regExp[,startIdx][,captureNum][,matchNum][,caseSensitive={TRUE|FALSE}])

Returns a substring of string that matches regExp, starting at startIdx (or, if startIdx is a negative integer, starting at startIdx characters from the end of string). If captureNum=0 (default), the entire matching substring is returned; otherwise, the specified parenthesized capture is returned. If matchNum=0 (default), SubstringRegularExpression() returns the first match that is found. If matchNum > 0, the search is repeated matchNum times, each time starting the search at the character after the first character of the previous match. If caseSensitive=TRUE, letters match only if they are both upper case or both lower case. If FALSE, they match regardless of their case.

If no match is found, null is returned.

TitleCase(string)

Returns a string with the first character in 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.

Equivalent transformer: StringCaseChanger

Trim(string[,chars])

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

TrimLeft(string[,chars])

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

TrimRight(string[,chars])

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

UpperCase(string)

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

Equivalent transformer: StringCaseChanger

WordCount(string)

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

Deprecated Functions

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

Note Replaced with @FindRegularExpression()

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

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

Note Replaced with @ReplaceRegularExpression()

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