String Functions

Strings from a character set may need to be sorted differently for different applications. You must consider the sort order when you invoke string comparisons. Some string functions will require understanding of the default sort order and any other special collation. For more information, see the Character Model for the World Wide Web 1.0. The following string functions are available:

• xf:compare
• xf:concat
• xf:contains
• xf:ends-with
• xf:lower-case
• xf:starts-with
• xf:string-length
• xf:substring (format1)
• xf:substring (format 2)
• xf:substring-after
• xf:substring-before
• xf:upper-case
• xfext:match
• xfext:trim

xf:compare

Returns -1, 0, or 1, depending on whether the value of Parameter1 is less than (-1), equal to (0), or greater than (1)the value of Parameter2.

Data Types

• Parameter1 data type: xs:string?
• Parameter2 data type: xs:string?
• Returned data type: xs:integer?

Notes

If either argument is an empty list, the result is an empty list.

Liquid Data generates an error if either parameter is not a string.

XQuery Specification Compliance

Liquid Data does not support the xf:compare format that accepts collations.

Examples

• xf:compare("a", "b") returns the integer value -1.
• xf:compare("a", "a") returns the integer value 0.
• xf:compare("b", "a") returns the integer value 1.
• xf:compare("a", 3) generates a compile-time error because the second parameter is not a string.
• xf:compare("a", ()) returns an empty list ().
• xf:compare((), "a") returns an empty list ().

 

---

xf:concat

Returns a string that concatenates Parameter1 with Parameter2.

Data Types

• Parameter1 data type: xs:string?
• Parameter2 data type: xs:string?
• Returned data type: xs:string?

Notes

The result string may not reflect Unicode or other W3C normalization.

Returns an empty string if the function has no arguments. If any argument is an empty list, it is treated as an empty string.

Liquid Data generates an error if either parameter is not a string.

XQuery Specification Compliance

Liquid Data does not support a variable number of parameters to be concatenated. Choose only two strings to concatenate with each operation.

Examples

• xf:concat("a", "b") returns the string value "ab."
• xf:concat("a", xf:concat("b", "c")) returns the string value "abc."
• xf:concat("abc", ()) returns the string value "abc."
• xf:concat((), "abc") returns the string value "abc."
• xf:concat((), ()) returns an empty list ().
• xf:concat("a", 4) generates a compile-time error because the second parameter is not a string.

 

---

xf:contains

Returns a boolean value of true or false indicating whether Parameter1 contains a string that is equal to Parameter2 at the beginning, at the end, or anywhere within Parameter1.

Data Types

• Parameter1 data type: xs:string?
• Parameter2 data type: xs:string?
• Returned data type: xs:boolean?

Notes

If the value of Parameter2 is a zero-length string, the function returns true. If the value of Parameter1 is a zero-length string and the value of Parameter2 is not a zero-length string, the function returns false.

If the value of Parameter1 or Parameter2 is an empty list, the function returns an empty list.

Liquid Data generates an error if either parameter is not a string.

XQuery Specification Compliance

Liquid Data does not support the xf:contains format that accepts collations.

Examples

• xf:contains("abc", "a") returns the boolean value true.
• xf:contains("abc", "b") returns the boolean value true.
• xf:contains("abc", "c") returns the boolean value true.
• xf:contains("abc", "d") returns the boolean value false.
• xf:contains("abc", "") returns the boolean value true.
• xf:contains("abc", ()) returns an empty list ().
• xf:contains((), "abc") returns an empty list ().
• xf:contains("abc", 4) generates a compile-time error because the second parameter is not a string.

 

---

xf:ends-with

Returns a boolean value or true or false indicating whether Parameter1 ends with a string that is equal to Parameter2.

Data Types

• Parameter1 data type: xs:string?
• Parameter2 data type: xs:string?
• Returned data type: xs:boolean?

Notes

If Parameter2 is a zero-length string, then the function returns true. If Parameter1 is a zero-length string and Parameter2 is not a zero-length string, the function returns false.

If Parameter1 or Parameter2 is an empty list, the function returns an empty list.

Liquid Data generates an error if either parameter is not a string.

XQuery Specification Compliance

Liquid Data does not support the xf:ends-with format that accepts collations.

Examples

• xf:ends-with("abc", "a") returns the boolean value false.
• xf:ends-with("abc", "b") returns the boolean value false.
• xf:ends-with("abc", "c") returns the boolean value true.
• xf:ends-with("abc", "d") returns the boolean value false.
• xf:ends-with("abc", "") returns the boolean value true.
• xf:ends-with("abc", ()) returns an empty list ().
• xf:ends-with((), "abc") returns an empty list ().
• xf:ends-with("abc", 4) generates a compile-time error because the second parameter is not a string.

 

---

xf:lower-case

Returns the value of the input string after translating every uppercase letter to its corresponding lower-case value.

Data Types

• Input data type: xs:string?
• Returned data type: xs:string?

Notes

Every uppercase letter that does not have a lower-case corresponding value and every character that is not an uppercase letter appears in the output in its original form.

If the source value is an empty list, the function returns an empty list.

XQuery Specification Compliance

Conforms to the current specification.

Examples

• xf:lower-case("ABc!D") returns the string value "abc!d."
• xf:lower-case("") returns the empty string "".
• xf:lower-case(()) returns the empty list ().
• xf:lower-case(4) generates a compile-time error because the parameter is not a string.

 

---

xf:starts-with

Returns a boolean value or true or false indicating whether Parameter1 starts with a string that is equal to Parameter2.

Data Types

• Parameter1 data type: xs:string?
• Parameter2 data type: xs:string?
• Returned data type: xs:boolean?

Notes

If Parameter2 is a zero-length string, then the function returns true. If Parameter1 is a zero-length string and tParameter2 is not a zero-length string, the function returns false.

If Parameter1 or Parameter2 is an empty list, the function returns an empty list.

Liquid Data generates an error if either parameter is not a string.

XQuery Specification Compliance

Liquid Data does not support the xf:ends-with format that accepts collations.

Examples

• xf:starts-with("abc", "a") returns the boolean value true.
• xf:starts-with("abc", "b") returns the boolean value false.
• xf:starts-with("abc", "c") returns the boolean value false.
• xf:starts-with("abc", "d") returns the boolean value false.
• xf:starts-with("abc", "") returns the boolean value true.
• xf:starts-with("abc", ()) returns the empty list ().
• xf:starts-with((), "abc") returns the empty list ().
• xf:starts-with("abc", 4) generates a compile-time error because the second parameter is not a string.

 

---

xf:string-length

Returns an integer equal to the number of characters in the input source string.

Data Types

• Input data type: xs:string?
• Returned data type: xs:integer?

Notes

If the source value is an empty list, the function returns an empty list.

Liquid Data generates an error if either parameter is not a string.

XQuery Specification Compliance

• Liquid Data treats xf:string as both a constructor and an accessor.
• Liquid Data supports only the string format that requires one node of any type as the input.
• Liquid Data accepts xsext:anyType input instead of a list of items.
• Liquid Data returns an optional string.
• Liquid Data does not recognize entities.

Examples

• xf:string-length("abc") returns the integer value 3.
• xf:string-length("") returns the integer value 0.
• xf:string-length(()) returns the empty list ().
• xf:string-length(4) generates a compile-time error because the parameter is not a string.

 

---

xf:substring (format1)

Returns that part of the Parameter1 source string from the starting location specified by Parameter2.

Data Types

• Parameter1 data type: xs:string?
• Parameter2 data type: xs:integer?
• Returned data type: xs:string?

Notes

If the starting location is a negative value, or greater than the length of source string, an error occurs.

The first character of a string is located at position 1 (not position 0).

If Parameter1 or Parameter2 is an empty list, the function returns an empty list.

If you omit Parameter3, the function returns characters up to the end of the source string.

Liquid Data generates an error if Parameter1 is not a string or if the starting location is less than 1.

XQuery Specification Compliance

• Liquid Data supports xs:integer instead of xs:decimal as the starting location and length parameters.
• If the starting location is greater than the length of the input sequence, Liquid Data returns an empty list instead of generating an error.

 

---

xf:substring (format 2)

Returns that part of the Parameter1 source string from the starting location specified by Parameter2 and continuing for the number of characters equal to the length specified by Parameter3.

Data Types

• Parameter1 data type: xs:string?
• Parameter2 data type: xs:integer?
• Parameter3 data type: xs:integer?
• Returned data type: xs:string?

Notes

If the starting location is a negative value, or greater than the length of the source string, an error occurs.

The first character of a string is located at position 1 (not position 0).

If you omit length, the substring identifies characters to the end of the source string.

If length exceeds the number of characters in the source string, the function identifies only characters until the end of the source string.

If Parameter1, Parameter2, or Parameter3 is an empty list, the function returns an empty list.

Liquid Data generates an error if Parameter1 is not a string or if the starting location is less than 1.

Liquid Data is able to process either format of xf:substring. Adding a third parameter automatically invokes Format 2.

XQuery Specification Compliance

• Liquid Data supports xs:integer instead of xs:decimal as the starting location and length parameters.
• If the starting location is greater than the length of the input sequence, Liquid Data returns an empty list instead of generating an error.

 

---

xf:substring-after

Returns that part of the Parameter1 source string that follows the first occurrence of those characters specified in Parameter2.

Data Types

• Parameter1 data type: xs:string?
• Parameter2 data type: xs:string?
• Returned data type: xs:string?

Notes

If Parameter2 is a zero-length string, the function returns the value of Parameter1. If Parameter1 is a zero-length string and Parameter2 is a zero-length string, the function returns a zero-length string.

If Parameter1 does not contain a string that is equal to Parameter2, the function returns a zero-length string.

If Parameter1 or Parameter2 is an empty list, the function returns an empty list.

XQuery Specification Compliance

Liquid Data does not support the xf:substring-after format that accepts collations.

Examples

• xf:substring-after("abcde", "d") returns the string value "e."
• xf:substring-after("abcde", "") returns the string value "abcde."
• xf:substring-after("abcde", "x") returns the empty string "".
• xf:substring-after("abcde", ()) returns the empty list ().
• xf:substring-after((), "x") returns the empty list ().
• xf:substring-after("abc34de", 3) generates a compile-time error because the second parameter is not a string.

 

---

xf:substring-before

Returns that part of the Parameter1 source string that precedes the first occurrence of those characters specified in Parameter2.

Data Types

• Parameter1 data type: xs:string?
• Parameter2 data type: xs:string?
• Returned data type: xs:string?

Notes

If Parameter2 is a zero-length string, the function returns the value of Parameter1. If Parameter1 is a zero-length string and Parameter2 is a zero-length string, the function returns a zero-length string.

If Parameter1 does not contain a string that is equal to Parameter2, the function returns a zero-length string.

If Parameter1 or Parameter2 is an empty list, the function returns an empty list.

XQuery Specification Compliance

Liquid Data does not support the xf:substring-before format that accepts collations.

Examples

• xf:substring-before("abcde", "d") returns the string value "abc."
• xf:substring-before("abcde", "") returns the string value "abcde."
• xf:substring-after("abcde", "x") returns the empty string "".
• xf:substring-before("abcde", ()) returns an empty list ().
• xf:substring-before((), "x") returns an empty list ().
• xf:substring-before("abc34de", 3) generates a compile-time error because the second parameter is not a string.

 

---

xf:upper-case

Returns the value of the input string after translating every lower-case letter to its uppercase correspondent.

Data Types

• Input Parameter data type = xs:string?
• Returned data type: xs:string?

Notes

Every lower-case letter that does not have an uppercase corresponding value and every character that is not a lower-case letter appears in the output in its original form.

If the source value is an empty list, the function returns an empty list.

Liquid Data generates an error if the parameter is not a string.

XQuery Specification Compliance

Conforms to the current specification.

Examples

• xf:upper-case("ABc!D") returns the string value "ABC!D."
• xf:upper-case("") returns the empty string "".
• xf:upper-case(()) returns the empty list ().
• xf:upper-case(4) generates a compile-time error because the parameter is not a string.

 

---

xfext:match

Returns a list of integers (either an empty list with 0 integers or a list with 2 integers) specifying which characters in the string input matches the input regular expression. When the function returns a match, the first integer represents the index of (the position of) the first character of the matching substring and the second integer represents the number of matching characters starting at the first match.

Data Types

• source - Input data type: xs:string?
• regularExpression - Input data type: xs:string?
• Returned data type: xs:int?

Notes

The index of the first character of the input source is 1, the index of the second character is 2, and so on.

The regularExpression input uses a standard regular expression language. The regular expression language uses the following components:

Table 9-4 Regular expression syntax examples for the xfext:match function  

Syntax Example	Description
Characters
unicode	Matches the specified unicode character.
\	Used to escape metacharacters such as *, +, and ?.
\\	Matches a single backslash ( \ ) character.
\0nnn	Matches the specified octal character.
\0xhh	Matches the specified 8-bit hexidecimal character.
\\uxhhh	Matches the specified 16-bit hexidecimal character.
\t	Matches an ASCII tab character.
\n	Matches an ASCII new line character.
\r	Matches an ASCII return character.
\f	Matches an ASCII form feed character.
Simple Character Classes
[bc]	Matches the characters b or c.
[a-f]	Matches any character between a and f.
[^bc]	Matches any character except b and c.
Predefined Character Classes
.	Matches any character except the new line character.
\w	Matches a word character: an alphanumeric character or the underscore ( _ ) character.
\W	Matches a non-word character.
\s	Matches a white space character.
\S	Matches a non-white space character.
\d	Matches a digit.
\D	Matches a non-digit.
Greedy Closures—match as many characters as possible
A*	Matches expression A zero or more times.
A+	Matches expression A one or more times.
A?	Matches expression A zero or one times.
A(n)	Matches expression A exactly n times.
A(n,)	Matches expression A at least n times.
A(n, m)	Matches expression A between n and m times.
Reluctant Closures—match as few characters as possible (stops when a match is found)
A*?	Matches expression A zero or more times.
A+?	Matches expression A one or more times.
A??	Matches expression A zero or one times.
Logical Operators
AB	Matches expression A followed by expression B.
A|B	Matches expression A or expression B.
(A)	Used for grouping expressions.

XQuery Specification Compliance

This is an extended function and is not part of the XQuery specification.

Examples

• xfext:match("abcde", "bcd") evaluates to the list (2,3)
• xfext:match("abcde", ()) evaluates to the empty list ()
• xfext:match((), "bcd") evaluates to the empty list ()
• xfext:match("abc", 4) generates an error at compile time because the second parameter is not a string
• xfext:match("abcccdee", "[bc]") evaluates to the list (2,1)

 

---

xfext:trim

Returns the value of the input string with leading and trailing white space removed from the string.

Data Types

• Input data type: xs:string?
• Returned data type: xs:string?

Notes

If the input string is an empty list, the function returns an empty list.

Liquid Data generates an error if the parameter is not a string.

XQuery Specification Compliance

The xfext:trim function is an extended function. For more information about extended functions, see Naming Conventions.

Examples

• xfext:trim("abc") returns the string value "abc"
• xfext:trim(" abc ") returns the string value "abc"
• xfext:trim(()) returns the empty list ()
• xfext:trim(5) generates a compile-time error because the parameter is not a string