Functions on Strings

The functions and operators are defined on the XML Schema Part 2: Datatypes Second Edition xs:string datatype and the datatypes derived from it.

*** Issues: prefixes must be documented. ***

*** Issue: Collation support. The functions compare, contains, starts-with, ends-with, string-before, string-after all have both a form that allows specification of a collation order and a form which does not. If these are really required we should define which collation orders implementations are required to support. Two options: (a) drop the forms which include collation arguments. These could be added in future dialects or local extensions but would not be required in conformant BLD implements; (b) include the collation forms and specify that conformant implementations are only required to support collation order: http://www.w3.org/2005/xpath-functions/collation/codepoint as described in http://www.w3.org/TR/xpath-functions/#collations. ***

Equality and Comparison of Strings

1. fn:compare

fn:compare($comparand1 as xs:string?, 
           $comparand2 as xs:string?) as xs:integer?

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

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.

Functions on String Values

1. fn:concat

fn:concat($arg1  as xs:anyAtomicType?,
          $arg2  as xs:anyAtomicType?,
          ...  ) as xs:string

Accepts two or more xs:anyAtomicType arguments and casts them to xs:string. Returns the xs:string that is the concatenation of the values of its arguments after conversion.

2. fn:string-join

fn:string-join($arg1 as xs:string*, $arg2 as xs:string) as xs:string

Returns a xs:string created by concatenating the members of the $arg1 sequence using $arg2 as a separator.

3. fn:substring

fn:substring( $sourceString      as xs:string?,
              $startingLoc       as xs:double) as xs:string

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

Returns the portion of the value of $sourceString beginning at the position indicated by the value of $startingLoc and continuing for the number of characters indicated by the value of $length. The characters returned do not extend beyond $sourceString. If $startingLoc is zero or negative, only those characters in positions greater than zero are returned.

4. fn:string-length

fn:string-length() as xs:integer

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

Returns an xs:integer equal to the length in characters of the value of $arg.

5. fn:upper-case

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

6. fn:lower-case

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

7. fn:encode-for-uri

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

This function encodes reserved characters in an xs:string that is intended to be used in the path segment of a URI. It is invertible but not idempotent.

8. fn:iri-to-uri

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

9. fn:escape-html-uri

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

This function escapes all characters except printable characters of the US-ASCII coded character set, specifically the octets ranging from 32 to 126 (decimal). The effect of the function is to escape a URI in the manner html user agents handle attribute values that expect URIs. Each character in $uri to be escaped is replaced by an escape sequence, which is formed by encoding the character as a sequence of octets in UTF-8, and then representing each of these octets in the form %HH, where HH is the hexadecimal representation of the octet. This function must always generate hexadecimal values using the upper-case letters A-F.

Functions Based on Substring Matching

The functions described here examine a string $arg1 to see whether it contains another string $arg2 as a substring. The result depends on whether $arg2 is a substring of $arg1, and if so, on the range of characters in $arg1 which $arg2 matches.

1. fn:contains

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

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

Returns an xs:boolean indicating whether or not the value of $arg1 contains (at the beginning, at the end, or anywhere within) at least one sequence of collation units that provides a minimal match to the collation units in the value of $arg2, according to the collation that is used. "Minimal match" is defined in Unicode Collation Algorithm.

2. fn:starts-with

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

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

Returns an xs:boolean indicating whether or not the value of $arg1 starts with a sequence of collation units that provides a minimal match to the collation units of $arg2 according to the collation that is used. "Minimal match" is defined in Unicode Collation Algorithm.

3. fn:ends-with

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

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

4. fn:substring-before

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

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

Returns the substring of the value of $arg1 that precedes in the value of $arg1 the first occurrence of a sequence of collation units that provides a minimal match to the collation units of $arg2 according to the collation that is used.

5. fn:substring-after

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

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

String Functions that Use Pattern Matching

The three functions described here make use of a regular expression syntax for pattern matching. The regular expression syntax is described here.

1. fn:matches

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

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

The function returns true if $input matches the regular expression supplied as $pattern as influenced by the value of $flags, if present; otherwise, it returns false.

The effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string. Flags are defined in 7.6.1.1 Flags.

2. fn:replace

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

fn:replace( $input       as xs:string?,
            $pattern     as xs:string,
            $replacement as xs:string,
            $flags       as xs:string) as xs: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.

3. fn:tokenize

fn:tokenize($input as xs:string?, $pattern as xs:string) as xs:string*

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

This function breaks the $input string into a sequence of strings, treating any substring that matches $pattern as a separator. The separators themselves are not returned.