This page was generated
July 7, 2010
4:04 PM
XQuery Built-In and Modules Function Reference

Built-In: String

The string built-in functions are XQuery functions defined to operate on string values. They are defined in XQuery 1.0 and XPath 2.0 Functions and Operators.

The string built-in functions use the fn namespace prefix, which is predefined in the server. Also, the fn prefix is the default prefix for function calls if none is specified.

Function Summary
fn:codepoint-equal Returns true if the specified parameters are the same Unicode code point, otherwise returns false.
fn:codepoints-to-string Creates an xs:string from a sequence of Unicode code points.
fn:compare Returns -1, 0, or 1, depending on whether the value of the $comparand1 is respectively less than, equal to, or greater than the value of $comparand2, according to the rules of the collation that is used.
fn:concat Returns the xs:string that is the concatenation of the values of the specified parameters.
fn:contains Returns true if the first parameter contains the string from the second parameter, otherwise returns false.
fn:encode-for-uri Invertible function that escapes characters required to be escaped inside path segments of URIs.
fn:ends-with Returns true if the first parameter ends with the string from the second parameter, otherwise returns false.
fn:escape-html-uri %-escapes everything except printable ASCII characters.
fn:escape-uri This is a May 2003 function, and is only available in compatibility mode (XQuery 0.9-ML)--it has been replaced with fn:encode-for-uri, fn:iri-to-uri, and fn:escape-html-uri.
fn:iri-to-uri Idempotent function that escapes non-URI characters.
fn:lower-case Returns the specified string converting all of the characters to lower-case characters.
fn:matches Returns true if the specified $input matches the specified $pattern, otherwise returns false.
fn:normalize-space Returns the specified string with normalized whitespace, which strips off any leading or trailing whitespace and replaces any other sequences of more than one whitespace characters with a single space character (#x20).
fn:normalize-unicode Return the argument normalized according to the normalization criteria for a normalization form identified by the value of $normalizationForm.
fn:replace Returns a string constructed by replacing the specified $pattern on the $input string with the specified $replacement string.
fn:starts-with Returns true if the first parameter starts with the string from the second parameter, otherwise returns false.
fn:string-join Returns an xs:string created by concatenating the members of the $parameter1 sequence using $parameter2 as a separator.
fn:string-length Returns an integer representing the length of the specified string.
fn:string-pad [0.9-ml only] Returns a string representing the $padString concatenated with itself the number of times specifed in $padCount.
fn:string-to-codepoints Returns the sequence of Unicode code points that constitute an xs:string.
fn:substring Returns a substring starting from the $startingLoc and continuing for $length characters.
fn:substring-after Returns the substring created by taking all of the input characters that occur after the specified $after characters.
fn:substring-before Returns the substring created by taking all of the input characters that occur before the specified $before characters.
fn:tokenize Returns a sequence of strings contructed by breaking the specified input into substrings separated by the specified $pattern.
fn:translate Returns a string where every character in $src that occurs in some position in the $mapString is translated into the $transString character in the corresponding location of the $mapString character.
fn:upper-case Returns the specified string converting all of the characters to upper-case characters.
Function Detail
fn:codepoint-equal(
$comparand1 as xs:string?,
$comparand2 as xs:string?
)  as  xs:boolean?
Summary:

Returns true if the specified parameters are the same Unicode code point, otherwise returns false. The codepoints are compared according to the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

If either argument is the empty sequence, the result is the empty sequence.


Parameters:
$comparand1 : A string to be compared.
$comparand2 : A string to be compared.

Example:
let $cp := fn:string-to-codepoints("123456")
return
fn:codepoint-equal("123456", fn:codepoints-to-string($cp) )

=> true

fn:codepoints-to-string(
$arg as xs:integer*
)  as  xs:string
Summary:

Creates an xs:string from a sequence of Unicode code points. Returns the zero-length string if $arg is the empty sequence. If any of the code points in $arg is not a legal XML character, an error is raised.

Parameters:
$arg : A sequence of Unicode code points.

Example:

fn:codepoints-to-string((2309, 2358, 2378, 2325)) returns
"अशॊक"

            

fn:compare(
$comparand1 as xs:string?,
$comparand2 as xs:string?,
[$collation as xs:string]
)  as  xs:integer?
Summary:

Returns -1, 0, or 1, depending on whether the value of the $comparand1 is respectively less than, equal to, or greater than the value of $comparand2, according to the rules of the collation that is used.


Parameters:
$comparand1 : A string to be compared.
$comparand2 : A string to be compared.
$collation (optional): The optional name of a valid collation URI. For information on the collation URI syntax, see the Developer's Guide.

Example:
fn:compare("hello", "goodbye")

=> 1

fn:concat(
$parameter1 as xs:anyAtomicType?,
[$parameterN as xs:anyAtomicType?,...]
)  as  xs:string
Summary:

Returns the xs:string that is the concatenation of the values of the specified parameters. Accepts two or more xs:anyAtomicType arguments and casts them to xs:string. If any of the parameters is the empty sequence, the parameter is treated as the zero-length string.


Parameters:
$parameter1 : A value.
$parameterN (optional): A value.

Example:
fn:concat("a", "b", "c")

=> abc

fn:contains(
$parameter1 as xs:string?,
$parameter2 as xs:string?,
[$collation as xs:string]
)  as  xs:boolean
Summary:

Returns true if the first parameter contains the string from the second parameter, otherwise returns false.

Parameters:
$parameter1 : The string from which to test.
$parameter2 : The string to test for existence in the first parameter.
$collation (optional): The optional name of a valid collation URI. For information on the collation URI syntax, see the Developer's Guide.

Example:
fn:contains("this is a string", "s a s")

=> true

fn:encode-for-uri(
$uri-part as xs:string
)  as  xs:string
Summary:

Invertible function that escapes characters required to be escaped inside path segments of URIs.

Parameters:
$uri-part : A string representing an unescaped URI.

Example:
fn:encode-for-uri("http://example.com/Weather/Los%20Angeles#ocean")
=> "http%3A%2F%2Fexample.com%2FWeather%2FLos%2520Angeles%23ocean"

fn:ends-with(
$parameter1 as xs:string?,
$parameter2 as xs:string?,
[$collation as xs:string]
)  as  xs:boolean
Summary:

Returns true if the first parameter ends with the string from the second parameter, otherwise returns false.

Parameters:
$parameter1 : The parameter from which to test.
$parameter2 : The string to test whether it is at the end of the first parameter.
$collation (optional): The optional name of a valid collation URI. For information on the collation URI syntax, see the Developer's Guide.

Example:
fn:ends-with("this is a string", "a string")

=> true

fn:escape-html-uri(
$uri-part as xs:string
)  as  xs:string
Summary:

%-escapes everything except printable ASCII characters.

Parameters:
$uri-part : A string representing an unescaped URI.

Example:
fn:escape-html-uri("http://example.com/Weather/Los Angeles#ocean")
=> "http://example.com/Weather/Los Angeles#ocean"

fn:escape-uri(
$uri-part as xs:string,
$escape-reserved as xs:boolean
)  as  xs:string
Summary:

This is a May 2003 function, and is only available in compatibility mode (XQuery 0.9-ML)--it has been replaced with fn:encode-for-uri, fn:iri-to-uri, and fn:escape-html-uri. Returns a string representing the specified URI either with escaped reserved characters ($escape-reserved=true) or with the reserved characters left as specified ($escape-reserved=true). For more details, see the W3C XQuery Functions and Operators specification.

Parameters:
$uri-part : A string representing an unescaped URI.
$escape-reserved : Specify a boolean value of true to return an escaped URI or a boolean value of false to return an unescaped URI.

Example:
fn:escape-uri("http://developer.marklogic.com", fn:true())

=> http%3A%2F%2Fdeveloper.marklogic.com

fn:escape-uri("http://developer.marklogic.com", fn:false())

=> http://developer.marklogic.com

fn:iri-to-uri(
$uri-part as xs:string
)  as  xs:string
Summary:

Idempotent function that escapes non-URI characters.

Parameters:
$uri-part : A string representing an unescaped URI.

Example:
fn:iri-to-uri("http://example.com/Weather/Los%20Angeles#ocean")
=> "http://example.com/Weather/Los%20Angeles#ocean"

fn:lower-case(
$string as xs:string?
)  as  xs:string?
Summary:

Returns the specified string converting all of the characters to lower-case characters. If a character does not have a corresponding lower-case character, then the original character is returned. The lower-case characters are determined using the Unicode Case Mappings.

Parameters:
$string : The string to convert.

Example:
fn:lower-case("aBCD")

=> abcd 

fn:matches(
$input as xs:string?,
$pattern as xs:string,
[$flags as xs:string]
)  as  xs:boolean?
Summary:

Returns true if the specified $input matches the specified $pattern, otherwise returns false.

Parameters:
$input : The input from which to match.
$pattern : The regular expression to match.
$flags (optional): The flag representing how to interpret the regular expression. One of "s", "m", "i", or "x", as defined in http://www.w3.org/TR/xpath-functions/#flags.

Example:
fn:matches("this is a string", "is")

=> true

fn:matches("this is a string", "zoo")

=> false

fn:normalize-space(
[$input as xs:string?]
)  as  xs:string?
Summary:

Returns the specified string with normalized whitespace, which strips off any leading or trailing whitespace and replaces any other sequences of more than one whitespace characters with a single space character (#x20).

Parameters:
$input (optional): The string from which to normalize whitespace.

Example:
fn:normalize-space("
this
is
  a string
  ")

=> this is a string

fn:normalize-unicode(
$arg as xs:string?,
[$normalizationForm as xs:string]
)  as  xs:string?
Summary:

Return the argument normalized according to the normalization criteria for a normalization form identified by the value of $normalizationForm. The effective value of the $normalizationForm is computed by removing leading and trailing blanks, if present, and converting to upper case.

Parameters:
$arg : The string to normalize.
$normalizationForm (optional): The form under which to normalize the specified string: NFC, NFD, NFKC, or NFKD.


fn:replace(
$input as xs:string?,
$pattern as xs:string,
$replacement as xs:string,
[$flags as xs:string]
)  as  xs:string?
Summary:

Returns a string constructed by replacing the specified $pattern on the $input string with the specified $replacement string.

Parameters:
$input : The string to start with.
$pattern : The regular expression pattern to match.
$replacement : The regular expression pattern to replace the $pattern with. It can also be a capture expression (for more details, see http://www.w3.org/TR/xpath-functions/#func-replace).
$flags (optional): The flag representing how to interpret the regular expression. One of "s", "m", "i", or "x", as defined in http://www.w3.org/TR/xpath-functions/#flags.

Example:
fn:replace("this is a string", "this", "that")

-> that is a string

fn:starts-with(
$parameter1 as xs:string?,
$parameter2 as xs:string?,
[$collation as xs:string]
)  as  xs:boolean
Summary:

Returns true if the first parameter starts with the string from the second parameter, otherwise returns false.

Parameters:
$parameter1 : The string from which to test.
$parameter2 : The string to test whether it is at the beginning of the first parameter.
$collation (optional): The optional name of a valid collation URI. For information on the collation URI syntax, see the Developer's Guide.

Example:
fn:starts-with("abcd", "ab")

=> true

fn:string-join(
$parameter1 as xs:string*,
$parameter2 as xs:string
)  as  xs:string
Summary:

Returns an xs:string created by concatenating the members of the $parameter1 sequence using $parameter2 as a separator. If the value of $arg2 is the zero-length string, then the members of $parameter1 are concatenated without a separator.

If the value of $parameter1 is the empty sequence, the zero-length string is returned.


Parameters:
$parameter1 : A sequence of strings.
$parameter2 : A separator string to concatenate between the items in $parameter1.

Example:
fn:string-join(("hello", "goodbye"), " and ")

=> hello and goodbye
Example:
let $string := "this is a string"
return
fn:string-join(fn:tokenize($string, " "),
               "-")

=> this-is-a-string

fn:string-length(
[$sourceString as xs:string?]
)  as  xs:integer?
Summary:

Returns an integer representing the length of the specified string. The length is 1-based, so a string that is one character long returns a value of 1.

Parameters:
$sourceString (optional): The string to calculate the length.

Example:
fn:string-length("12345")

=> 5

fn:string-pad(
$padString as xs:string?,
$padCount as xs:integer
)  as  xs:string?
Summary:

[0.9-ml only] Returns a string representing the $padString concatenated with itself the number of times specifed in $padCount.

Parameters:
$padString : The string to pad.
$padCount : The number of times to pad the string.

Example:
fn:string-pad("abc", 3)

=> abcabcabc

fn:string-to-codepoints(
$arg as xs:string
)  as  xs:integer*
Summary:

Returns the sequence of Unicode code points that constitute an xs:string. If $arg is a zero-length string or the empty sequence, the empty sequence is returned.


Parameters:
$arg : A string.

Example:
fn:string-to-codepoints("Thèrése") 

returns the sequence (84, 104, 233, 114, 232, 115, 101)

fn:substring(
$sourceString as xs:string?,
$startingLoc as xs:double,
[$length as xs:double]
)  as  xs:string?
Summary:

Returns a substring starting from the $startingLoc and continuing for $length characters.

Parameters:
$sourceString : The string from which to create a substring.
$startingLoc : The number of characters from the start of the $sourceString.
$length (optional): The number of characters beyond the $startingLoc.

Example:
fn:substring("123456", 2, 2)

=> "23"

fn:substring-after(
$input as xs:string?,
$after as xs:string?,
[$collation as xs:string]
)  as  xs:string?
Summary:

Returns the substring created by taking all of the input characters that occur after the specified $after characters.

Parameters:
$input : The string from which to create the substring.
$after : The string after which the substring is created.
$collation (optional): The optional name of a valid collation URI. For information on the collation URI syntax, see the Developer's Guide.

Example:
fn:substring-after("123456", "3")

=> "456"

fn:substring-before(
$input as xs:string?,
$before as xs:string?,
[$collation as xs:string]
)  as  xs:string?
Summary:

Returns the substring created by taking all of the input characters that occur before the specified $before characters.

Parameters:
$input : The string from which to create the substring.
$before : The string before which the substring is created.
$collation (optional): The optional name of a valid collation URI. For information on the collation URI syntax, see the Developer's Guide.

Example:
fn:substring-before("abcdef", "def")

=> abc

fn:tokenize(
$input as xs:string?,
$pattern as xs:string,
[$flags as xs:string]
)  as  xs:string*
Summary:

Returns a sequence of strings contructed by breaking the specified input into substrings separated by the specified $pattern. The specified $pattern is not returned as part of the returned items.

Parameters:
$input : The string to tokenize.
$pattern : The regular expression pattern from which to separate the tokens.
$flags (optional): The flag representing how to interpret the regular expression. One of "s", "m", "i", or "x", as defined in http://www.w3.org/TR/xpath-functions/#flags.

Example:
fn:tokenize("this is a string", " ")

=> returns the sequence ("this", "is", "a", "string")

fn:tokenize("this is a string", " ")[last()]

=> string

fn:translate(
$src as xs:string?,
$mapString as xs:string?,
$transString as xs:string?
)  as  xs:string?
Summary:

Returns a string where every character in $src that occurs in some position in the $mapString is translated into the $transString character in the corresponding location of the $mapString character.

Parameters:
$src : The string to translate characters.
$mapString : The string representing characters to be translated.
$transString : The string representing the characters to which the $mapString characters are translated.

Example:
fn:translate("abcd", "abcd", "wxyz") 

=> wxyz

fn:upper-case(
$string as xs:string?
)  as  xs:string?
Summary:

Returns the specified string converting all of the characters to upper-case characters. If a character does not have a corresponding upper-case character, then the original character is returned. The upper-case characters are determined using the Unicode Case Mappings.

Parameters:
$string : The string to upper-case.

Example:
fn:upper-case("Abcd")

=> ABCD