| XQUERY/XSLT API DOCUMENTATION 4.2 |
All XQuery & XSLT Functions MarkLogic Built-In Functions Admin (xdmp:) AppServer (xdmp:) Classifier (cts:) Debug (dbg:) Document Conversion (xdmp:) Extension (xdmp:) Documents, Directories, Properties, and Locks Functions Extension Functions Function Values Functions HTTP Functions JSON Functions MarkLogic Server Functions Search Functions XML Functions XQuery Context Functions XSLT Functions map (map:) Math (math:) Profile (prof:) Search (cts:) cts:query Constructors Functions Geospatial Functions Geospatial Lexicon Functions Lexicon Functions Search Functions Search Clustering Functions Security (xdmp:) Server Monitoring (xdmp:) Spell (spell:) Update (xdmp:) XQuery Library Modules Admin Library (admin:) Actions Functions Appserver Functions Database Functions Forest Functions Group Functions Host Functions Mimetypes Functions Scheduler Functions Alerting (alert:) Elastic Compute Cloud (ec2:) Entity Enrichment (entity:) Flexible Replication (flexrep:) Geospatial Supporting Functions GEO Functions GeoRSS Functions GML Functions KML Functions MCGM Functions Information Studio (info:) Information Studio Developer (infodev:) Library Services (dls:) cts:query Constructor Functions Document Management Functions Document Update Functions Retention Policy Functions XInclude Functions Modular Documents XInclude Functions XPointer Functions PKI (pki:) Plugin (plugin:) Search (search:) Security-sec (sec:) Spelling Dictionary Management (spell:) Thesaurus (thsr:) Triggers (trgr:) Triggers Library (trgr:) WordProcessingML (ooxml:) ZIP Package (ooxml:) CPF Functions Content Processing Framework (cpf:) CSS Conversion (css:) DocBook Conversion (dbk:) Domains (dom:) Excel Conversion (excel:) Generic Conversion (cvt:) Links (lnk:) MSWord Conversion (msword:) PDF Conversion (pdf:) Pipelines (p:) Powerpoint Conversion (ppt:) XHTML Conversion (xhtml:) W3C-Standard Functions Accessor (fn:) AnyURI (fn:) Boolean (fn:) Context (fn:) DurationDateTime (fn:) Error and Trace (fn:) Node (fn:) Numeric (fn:) QName (fn:) Sequence (fn:) String (fn:) XSLT (fn:) W3C XQuery/XSLT Reference W3C XQuery Functions W3C XQuery Language W3C XSLT Language
This page was generated September 12, 2012 6:01 AM | XQuery & XSLT Built-In & 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:analyze-string | The result of the function is a new element node whose string value is the original string, but which contains markup to show which parts of the input match the regular expression.
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:analyze-string(
| $in as xs:string?,
| $regex as xs:string,
| [$flags as xs:string]
) as element(s:results)
Summary: The result of the function is a new element node whose string value is the original string, but which contains markup to show which parts of the input match the regular expression.
Parameters:
$in : The string to start with.
$regex : The regular expression pattern 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:analyze-string('Tom Jim John',"Jim")

    =>
    <s:analyze-string-result>
      <s:non-match>Tom </s:non-match>
      <s:match>Jim</s:match>
      <s:non-match> John</s:non-match>
    </s:analyze-string-result>
Example:
    fn:analyze-string('Tom Jim John',"(Jim)")

    =>
    <s:analyze-string-result>
      <s:non-match>Tom </s:non-match>
        <s:match>
          <s:group nr="1">Jim</s:group>
        </s:match>
      <s:non-match> John</s:non-match>
    </s:analyze-string-result>
Example:
    fn:analyze-string('Tom Jim John',"((Jim) John)")

    =>
    <s:analyze-string-result>
      <s:non-match>Tom </s:non-match>
      <s:match>
        <s:group nr="1">
        <s:group nr="2">Jim</s:group>
        John
        </s:group>
      </s:match>
    </s:analyze-string-result>
Example:
    fn:analyze-string("http://example.com/", "\w+")

    =>
    <result xmlns="http://www.w3.org/2009/xpath-functions/analyze-string">
      <match>http</match>
      <non-match>://</non-match>
      <match>example</match>
      <non-match>.</non-match>
      <match>com</match>
      <non-match>/</non-match>
    </result>
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 Search 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 Search 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 Search 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. If the pattern does not match the $input string, the function will return the $input string unchanged.
$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 Search 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 Search 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 Search 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

© Copyright 2002-2012 MarkLogic Corporation. All rights reserved.