Logic Apps (Standard) Data Mapper: String functions

Overview

String functions are used to manipulate strings in standard ways, such as conversions to all uppercase or all lowercase, string concatenation, determination of string length, white space trimming, etc. If you come from the BizTalk Server background or are migrating BizTalk Server projects, they are the equivalent of String Functoids inside BizTalk Mapper Editor.

Available Functions

The String functoids are:

• Codepoints to string: Converts the specified codepoints value to a string and returns the result.
• Concat: Combines two or more strings and returns the combined string.
• Contains: Returns true or false based on whether the string input contains the specified substring.
• Ends with: Returns true or false based on whether the string input ends with the specified substring.
• Length: Returns the number of items in the specified string or array.
• Lowercase: Returns a string in lowercase format.
• Name: Returns the local name of the selector node, which is useful when you want to retrieve the name of the incoming message component, not the value.
• Regular expression matches: Returns true or false based on whether the string input matches the specified regular expression.
• Regular expression replace: Returns a string created from the string input by using a given regular expression to find and replace matching substrings with the specified string.
• Replace: Replaces a substring with the specified string and return the new complete string.
• Starts with: Returns true if the given string starts with the specified substring.
• String to codepoints: Converts the specified string to codepoints.
• Substring: Returns characters from the specified string, starting from the specified position.
• Substring after: Returns the characters that follow the specified substring in the source string.
• Substring before: Returns the characters that precede the specified substring in the source string.
• Trim: Returns the specified string with all the leading and trailing white space characters removed.
• Trim left: Returns the specified string with all the leading white space characters removed.
• Trim right: Returns the specified string with all the trailing white space characters removed.
• Uppercase: Returns a string in uppercase format.

Codepoints to string

This function states that you can convert the specified codepoints value to a string and returns the result. but first, we need to understand what is a codepoint! In character encoding terminology, a code point, codepoint, or code position is a numerical value that maps to a specific character. Code points usually represent a single grapheme, usually a letter, digit, punctuation mark, or whitespace but sometimes represent symbols, control characters, or formatting. You can check and learn more about codepoint here: https://codepoints.net/. For example, the codepoint 65 is the letter A.

Behind the scenes, this function is translated to the following XPath function: codepoints-to-string()

• codepoints-to-string($arg as xs:string) as xs:string

Concat

This function states that you can combine two or more strings and returns the combined string.

Behind the scenes, this function is translated to the following XPath function: concat()

• concat( $arg1 as xs:anyAtomicType?, $arg2 as xs:anyAtomicType?, … ) as xs:string

Rules:

• This function accepts two or more xs:anyAtomicType arguments and casts each one to xs:string. The function returns the xs:string that is, the concatenation of the values of its arguments after conversion. If any argument is the empty sequence, that argument is treated as the zero-length string.
• The concat function is specified to allow two or more arguments, which are concatenated together. This is the only function specified in this document that allows a variable number of arguments.

Contains

This function states that it returns true or false based on whether the string input (argument 1) contains the specified substring (argument 2).

Behind the scenes, this function is translated to the following XPath function: contains()

• contains($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean

Rules:

• If the value of $arg1 or $arg2 is the empty sequence or contains only ignorable collation units, it is interpreted as the zero-length string.
• If the value of $arg2 is the zero-length string, then the function returns true.
• If the value of $arg1 is the zero-length string, the function returns false.

Ends with

This function states that it returns true or false based on whether the string input ends with the specified substring.

Behind the scenes, this function is translated to the following XPath function: ends-with()

• ends-with($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean

Rules:

• If the value of $arg1 or $arg2 is the empty sequence or contains only ignorable collation units, it is interpreted as the zero-length string.
• If the value of $arg2 is the zero-length string, then the function returns true.
• If the value of $arg1 is the zero-length string, and the value of $arg2 is not the zero-length string, then the function returns false.
• The function returns an xs:boolean indicating whether or not the value of $arg1 ends with a sequence of collation units that provides a match to the collation units of $arg2 according to the collation that is used.

Length

This function states that it returns the number of items in the specified string or array.

Behind the scenes, this function is translated to the following XPath function: string-lenght()

• string-length($arg as xs:string?) as xs:integer

Rules:

• The function returns an xs:integer equal to the length in characters of the value of $arg.
• If the value of $arg is the empty sequence, the function returns the xs:integer value zero (0).

Lowercase

This function states that it returns a string in lowercase format.

Behind the scenes, this function is translated to the following XPath function: lower-case()

• lower-case($arg as xs:string?) as xs:string

Rules:

• If the value of $arg is the empty sequence, the zero-length string is returned.
• Otherwise, the function returns the value of $arg after translating every character to its lower-case correspondent as defined in the appropriate case mappings section in the Unicode standard.

Name

This function states that it returns the local name of the selector node, which is useful when you want to retrieve the name of the incoming message component, not the value.

Behind the scenes, this function is translated to the following XPath function: local-name-from-QName()

• local-name-from-QName($arg as xs:QName?) as xs:NCName

Rules:

• If $arg is the empty sequence, the function returns the empty sequence.
• Otherwise, the function returns a xs:NCName representing the local part of $arg.

Regular expression matches

This function states that it returns true or false based on whether the string input matches the specified regular expression.

Behind the scenes, this function is translated to the following XPath function: matches()

• matches($input as xs:string?, $pattern as xs:string) as xs:boolean

Rules:

• If $input is the empty sequence, it is interpreted as the zero-length string.
• The function returns true if $input or some substring of $input matches the regular expression supplied as $pattern. Otherwise, the function returns false. 

Regular expression replace

This function states that it returns a string created from the string input by using a given regular expression to find and replace matching substrings with the specified string.

Behind the scenes, this function is translated to the following XPath function: replace()

• replace($input as xs:string?, $pattern as xs:string, $replacement as xs:string) as xs:string

Rules:

• If $input is the empty sequence, it is interpreted as the zero-length string.
• The function returns the xs:string that is obtained by replacing each non-overlapping substring of $input that matches the given $pattern with an occurrence of the $replacement string.
• If two overlapping substrings of $input both match the $pattern, then only the first one (that is, the one whose first character comes first in the $input string) is replaced.

In this sample above, if the city element from the source message has the value abracadabra then the output will be *c*bra

Replace

This function states that it replaces a substring with the specified string and returns the new complete string.

Behind the scenes, this function is translated to the following XPath function: replace()

• replace($input as xs:string?, $pattern as xs:string, $replacement as xs:string) as xs:string

This will be exactly the same as the previous one, but instead of using a regular expression pattern, we use a string to be replaced.

Starts with

This function states that it returns true if the given string starts with the specified substring.

Behind the scenes, this function is translated to the following XPath function: starts-with()

• starts-with($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean

Rules:

• If the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.
• If the value of $arg2 is the zero-length string, then the function returns true. If the value of $arg1 is the zero-length string, and the value of $arg2 is not the zero-length string, then the function returns false.

String to codepoints

This function states that it converts the specified string to codepoints. But first, we need to understand what is a codepoint! In character encoding terminology, a code point, codepoint, or code position is a numerical value that maps to a specific character. Code points usually represent a single grapheme, usually a letter, digit, punctuation mark, or whitespace but sometimes represent symbols, control characters, or formatting. You can check and learn more about codepoint here: https://codepoints.net/. For example, the letter A is the codepoint 65.

Behind the scenes, this function is translated to the following XPath function: string-to-codepoints()

• fn:string-to-codepoints($arg as xs:string?) as xs:integer

Rules:

• The function returns a sequence of integers, each integer being the Unicode codepoint of the corresponding character in $arg.
• If $arg is a zero-length string or the empty sequence, the function returns the empty sequence.

Substring

This function states that it returns characters from the specified string, starting from the specified position.

Behind the scenes, this function is translated to the following XPath function: substring()

• substring($sourceString as xs:string?, $start as xs:double, $length as xs:double) as xs:string

or

• substring($sourceString as xs:string?, $start as xs:double) as xs:string

Rules:

• If the value of $sourceString is the empty sequence, the function returns the zero-length string.
• Otherwise, the function returns a string comprising those characters of $sourceString whose index position (counting from one) is greater than or equal to the value of $start (rounded to an integer), and (if $length is specified) less than the sum of $start and $length (both rounded to integers).
• The characters returned do not extend beyond $sourceString. If $start is zero or negative, only those characters in positions greater than zero are returned.

Substring after

This function states that it returns the characters that follow the specified substring in the source string.

Behind the scenes, this function is translated to the following XPath function: substring-after()

• substring-after($arg1 as xs:string?, $arg2 as xs:string?) as xs:string

Rules:

• If the value of $arg1 or $arg2 is the empty sequence or contains only ignorable collation units, it is interpreted as the zero-length string.
• If the value of $arg2 is the zero-length string, then the function returns the value of $arg1.
• If the value of $arg1 does not contain a string that is equal to the value of $arg2, then the function returns the zero-length string.

Substring before

This function states that it returns the characters that precede the specified substring in the source string.

Behind the scenes, this function is translated to the following XPath function: substring-before()

• substring-before($arg1 as xs:string?, $arg2 as xs:string?) as xs:string

Rules:

• If the value of $arg1 or $arg2 is the empty sequence or contains only ignorable collation units, it is interpreted as the zero-length string.
• If the value of $arg2 is the zero-length string, then the function returns the zero-length string.
• If the value of $arg1 does not contain a string that is equal to the value of $arg2, then the function returns the zero-length string.

Trim

This function states that it returns the specified string with all the leading and trailing white space characters removed.

Behind the scenes, this function is translated to the following XPath function: replace()

• replace($input as xs:string?, ‘^\s*|\s*$’, ”)

This is a specific call to the replace() function where the second and third arguments are already specified behind the scenes. Trim functoid is an abstraction of this replace() function call.

Trim left

This function states that it returns the specified string with all the leading white space characters removed.

Behind the scenes, this function is translated to the following XPath function: replace()

• replace($input as xs:string?, ‘^\s+’, ”)

This is a specific call to the replace() function where the second and third arguments are already specified behind the scenes. Trim functoid is an abstraction of this replace() function call.

Trim right

This function states that it returns the specified string with all the trailing white space characters removed.

Behind the scenes, this function is translated to the following XPath function: replace()

• replace($input as xs:string?, ‘\s+$’, ”)

This is a specific call to the replace() function where the second and third arguments are already specified behind the scenes. Trim functoid is an abstraction of this replace() function call.

Uppercase

This function states that it returns a string in uppercase format.

Behind the scenes, this function is translated to the following XPath function: upper-case()

• upper-case($arg as xs:string?) as xs:string

Rules:

• If the value of $arg is the empty sequence, the zero-length string is returned.
• Otherwise, the function returns the value of $arg after translating every character to its upper-case correspondent as defined in the appropriate case mappings section in the Unicode standard.

Hope you find this helpful! So, if you liked the content or found it useful and want to help me write more, you can buy (or help buy) my son a Star Wars Lego!