| 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: Sequence
These built-in functions are XQuery functions defined to operate on sequences. They are defined in XQuery 1.0 and XPath 2.0 Functions and Operators.
Function Summary
fn:avg | Returns the average of the values in the input sequence $arg, that is, the sum of the values divided by the number of values.
fn:boolean | Computes the effective boolean value of the sequence $arg.
fn:collection | Returns all of the documents that belong to the specified collection(s).
fn:count | Returns the number of items in the value of $arg.
fn:deep-equal | This function assesses whether two sequences are deep-equal to each other.
fn:distinct-nodes | [0.9-ml only] Returns the sequence resulting from removing from the input sequence all but one of a set of nodes that have the same identity as one another.
fn:distinct-values | Returns the sequence that results from removing from $arg all but one of a set of values that are eq to one other.
fn:doc | Returns the document(s) stored in the database at the specified URI(s).
fn:doc-available | If fn:doc($uri) returns a document node, this function returns true.
fn:empty | If the value of $arg is the empty sequence, the function returns true; otherwise, the function returns false.
fn:exactly-one | Returns $arg if it contains exactly one item.
fn:exists | If the value of $arg is not the empty sequence, the function returns true; otherwise, the function returns false.
fn:id | Returns the sequence of element nodes that have an ID value matching the value of one or more of the IDREF values supplied in $arg.
fn:idref | Returns the sequence of element or attribute nodes that have an IDREF value matching the value of one or more of the ID values supplied in $arg.
fn:index-of | Returns a sequence of positive integers giving the positions within the sequence $seqParam of items that are equal to $srchParam.
fn:insert-before | Returns a new sequence constructed from the value of $target with the value of $inserts inserted at the position specified by the value of $position.
fn:max | Selects an item from the input sequence $arg whose value is greater than or equal to the value of every other item in the input sequence.
fn:min | Selects an item from the input sequence $arg whose value is less than or equal to the value of every other item in the input sequence.
fn:one-or-more | Returns $arg if it contains one or more items.
fn:remove | Returns a new sequence constructed from the value of $target with the item at the position specified by the value of $position removed.
fn:reverse | Reverses the order of items in a sequence.
fn:subsequence | Returns the contiguous sequence of items in the value of $sourceSeq beginning at the position indicated by the value of $startingLoc and continuing for the number of items indicated by the value of $length.
fn:sum | Returns a value obtained by adding together the values in $arg.
fn:unordered | Returns the items of $sourceSeq in an implementation dependent order.
fn:zero-or-one | Returns $arg if it contains zero or one items.
Function Detail
fn:avg(
| $arg as xs:anyAtomicType*
) as xs:anyAtomicType?
Summary: Returns the average of the values in the input sequence $arg, that is, the sum of the values divided by the number of values. If $arg is the empty sequence, the empty sequence is returned. If $arg contains values of type xs:untypedAtomic they are cast to xs:double. Duration values must either all be xs:yearMonthDuration values or must all be xs:dayTimeDuration values. For numeric values, the numeric promotion rules defined in 6.2 Operators on Numeric Values are used to promote all values to a single common type. After these operations, $arg must contain items of a single type, which must be one of the four numeric types,xs:yearMonthDuration or xs:dayTimeDuration or one if its subtypes. If the above conditions are not met, then a type error is raised [err:FORG0006]. Otherwise, returns the average of the values computed as sum($arg) div count($arg). For detailed type semantics, see Section 7.2.10 The fn:min, fn:max, fn:avg, and fn:sum functions[FS].
Parameters:
$arg : The sequence of values to average.
Example:
    Assume:
    $d1 = xs:yearMonthDuration("P20Y")
    $d2 = xs:yearMonthDuration("P10M")
    $seq3 = (3, 4, 5)

    Then:

    fn:avg($seq3) returns 4.0.

    fn:avg(($d1, $d2))
    returns a yearMonthDuration with value 125 months.

    fn:avg(($d1, $seq3)) raises a type error [err:FORG0006].

    fn:avg(()) returns ().

    fn:avg((xs:float('INF')), xs:float('-INF')) returns NaN.

    fn:avg(($seq3, xs:float('NaN')) returns NaN.
fn:boolean(
| $arg as item()*
) as xs:boolean
Summary: Computes the effective boolean value of the sequence $arg. See Section 2.4.3 Effective Boolean Value[XP]. NOTE: NEW 1.0 SEMANTICS NOT IMPLEMENTED: STILL USES MAY 2003 SEMANTICS. If $arg is the empty sequence, fn:boolean returns false. If $arg is a sequence whose first item is a node, fn:boolean returns true. If $arg is a singleton value of type xs:boolean or a derived from xs:boolean, fn:boolean returns $arg. If $arg is a singleton value of type xs:string or a type derived from xs:string or xs:untypedAtomic, fn:boolean returns false if the operand value has zero length; otherwise it returns true. If $arg is a singleton value of any numeric type or a type derived from a numeric type, fn:boolean returns false if the operand value is NaN or is numerically equal to zero; otherwise it returns true. In all other cases, fn:boolean raises a type error [err:FORG0006]. The static semantics of this function are described in Section 7.2.4 The fn:boolean function[FS]. Note: The result of this function is not necessarily the same as " $arg cast as xs:boolean ". For example, fn:boolean("false") returns the value "true" whereas "false" cast as xs:boolean returns false.
Parameters:
$arg : A sequence of items.
Example:
    let $x := ("a", "b", "c")
    return
    fn:boolean($x)
    => raises a type error [err:FORG0006].

    let $x := ("a", "b", "c")
    return
    fn:boolean($x[1])
    => returns true.

    let $x := ("a", "b", "c")
    return
    fn:boolean($x[0])
    => returns false.
fn:collection(
| [$uri as xs:string*]
) as document-node()*
Summary: Returns all of the documents that belong to the specified collection(s).
Parameters:
$uri (optional): The URI of the collection to retrieve. If you omit this parameter, returns all of the documents in the database. If you specify a list of URIs, returns all of the documents in all of the collections at the URIs specified in the list.
Example:
    fn:collection("mycollection")[1]
    => returns the first document in the "mycollection" collection
fn:count(
| $arg as item()*,
| [$maximum as xs:double?]
) as xs:integer
Summary: Returns the number of items in the value of $arg. Returns 0 if $arg is the empty sequence.
Parameters:
$arg : The sequence of items to count.
$maximum (optional): The maximum value of the count to return. MarkLogic Server will stop count when the $maximum value is reached and return the $maximum value. This is an extension to the W3C standard `fn:count` function.
Example:
    Assume:
    $seq1 = ($item1, $item2)
    $seq3 = (), the empty sequence

    Then:

    fn:count($seq1) returns 2.

    fn:count($seq3) returns 0.

    Assume $seq2 = (98.5, 98.3, 98.9).

    Then:

    fn:count($seq2) returns 3.
    fn:count($seq2[. > 100]) returns 0.
fn:deep-equal(
| $parameter1 as item()*,
| $parameter2 as item()*,
| [$collation as xs:string]
) as xs:boolean
Summary: This function assesses whether two sequences are deep-equal to each other. To be deep-equal, they must contain items that are pairwise deep-equal; and for two items to be deep-equal, they must either be atomic values that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal. This is defined in more detail below. The $collation argument identifies a collation which is used at all levels of recursion when strings are compared (but not when names are compared), according to the rules in 7.3.1 Collations. If the two sequences are both empty, the function returns true. If the two sequences are of different lengths, the function returns false. If the two sequences are of the same length, the function returns true if and only if every item in the sequence $parameter1 is deep-equal to the item at the same position in the sequence $parameter2. The rules for deciding whether two items are deep-equal follow. Call the two items $i1 and $i2 respectively. If $i1 and $i2 are both atomic values, they are deep-equal if and only if ($i1 eq $i2) is true. Or if both values are NaN. If the eq operator is not defined for $i1 and $i2, the function returns false. If one of the pair $i1 or $i2 is an atomic value and the other is a node, the function returns false. If $i1 and $i2 are both nodes, they are compared as described below: If the two nodes are of different kinds, the result is false. If the two nodes are both document nodes then they are deep-equal if and only if the sequence $i1/(*|text()) is deep-equal to the sequence $i2/(*|text()). If the two nodes are both element nodes then they are deep-equal if and only if all of the following conditions are satisfied: the two nodes have the same name, that is (node-name($i1) eq node-name($i2)). the two nodes are both annotated as having simple content or both nodes are annotated as having complex content. the two nodes have the same number of attributes, and for every attribute $a1 in $i1/@* there exists an attribute $a2 in $i2/@* such that $a1 and $a2 are deep-equal. One of the following conditions holds: Both element nodes have a type annotation that is simple content, and the typed value of $i1 is deep-equal to the typed value of $i2. Both element nodes have a type annotation that is complex content with elementOnly content, and each child element of $i1 is deep-equal to the corresponding child element of $i2. Both element nodes have a type annotation that is complex content with mixed content, and the sequence $i1/(*|text()) is deep-equal to the sequence $i2/(*|text()). Both element nodes have a type annotation that is complex content with empty content. If the two nodes are both attribute nodes then they are deep-equal if and only if both the following conditions are satisfied: the two nodes have the same name, that is (node-name($i1) eq node-name($i2)). the typed value of $i1 is deep-equal to the typed value of $i2. If the two nodes are both processing instruction nodes or namespace bindings, then they are deep-equal if and only if both the following conditions are satisfied: the two nodes have the same name, that is (node-name($i1) eq node-name($i2)). the string value of $i1 is equal to the string value of $i2. If the two nodes are both text nodes or comment nodes, then they are deep-equal if and only if their string-values are equal. Notes: The two nodes are not required to have the same type annotation, and they are not required to have the same in-scope namespaces. They may also differ in their parent, their base URI, and the values returned by the is-id and is-idrefs accesors (see Section 5.5 is-id Accessor[DM] and Section 5.6 is-idrefs Accessor[DM]). The order of children is significant, but the order of attributes is insignificant. The following note applies to the Jan 2007 XQuery specification, but not to the May 2003 XQuery specification: The contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. However, the presence of a comment or processing instruction, if it causes a text node to be split into two text nodes, may affect the result. The result of fn:deep-equal(1, current-dateTime()) is false; it does not raise an error.
Parameters:
$parameter1 : The first sequence of items.
$parameter2 : The sequence of items to compare to the first sequence of items.
$collation (optional): The optional name of a valid collation URI. For information on the collation URI syntax, see the Search Developer's Guide.
Example:
    Assume $at := <attendees>
                 <name last='Parker' first='Peter'/>
    	     <name last='Barker' first='Bob'/>
                 <name last='Parker' first='Peter'/>
    	   </attendees>

    Then:

    fn:deep-equal($at, $at/*) returns false.

    fn:deep-equal($at/name[1], $at/name[2]) returns false.

    fn:deep-equal($at/name[1], $at/name[3]) returns true.

    fn:deep-equal($at/name[1], 'Peter Parker') returns false.
fn:distinct-nodes(
| $nodes as node()*
) as node()*
Summary: [0.9-ml only] Returns the sequence resulting from removing from the input sequence all but one of a set of nodes that have the same identity as one another. If the empty sequence is input, `fn:distinct-nodes` returns the empty sequence.
Parameters:
$nodes : A sequence of nodes from which to eliminate duplicate nodes (nodes with the same identity) so that only one node of each identity remains.
Usage Notes: Note that for a node to have the same identity as another node, it must be exactly the same node (not an equivalent node). For example, for a node bound to the variable $x to have the same identity as a node bound to the variable $y, the following must return true:
    $x is $y
Example:
      (:
        assume /mydoc.xml has the following contents:
        <a>hello</a>
      :)

      let $x := fn:doc("/mydoc.xml")/a
      let $y := /a
      return
      fn:distinct-nodes(($x, $y))

    => <a>hello</a>
Example:
      (:
        assume /mydoc.xml has the following contents:
        <a>hello</a>
      :)

      let $x := fn:doc("/mydoc.xml")/a
      let $y := <a>hello</a>
      return
      fn:distinct-nodes(($x, $y))

    => (<a>hello</a>, <a>hello</a>)
       It returns both nodes because they do not
       have the same identity.
fn:distinct-values(
| $arg as xs:anyAtomicType*,
| [$collation as xs:string]
) as xs:anyAtomicType*
Summary: Returns the sequence that results from removing from $arg all but one of a set of values that are eq to one other. Values that cannot be compared, i.e. the eq operator is not defined for their types, are considered to be distinct. Values of type xs:untypedAtomic are compared as if they were of type xs:string. The order in which the sequence of values is returned is implementation dependent. The static type of the result is a sequence of prime types as defined in Section 7.2.7 The fn:distinct-values function[FS]. The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations. The collation is used when string comparison is required. If $arg is the empty sequence, the empty sequence is returned. For xs:float and xs:double values, positive zero is equal to negative zero and, although NaN does not equal itself, if $arg contains multiple NaN values a single NaN is returned. If xs:dateTime, xs:date or xs:time values do not have a timezone, they are considered to have the implicit timezone provided by the dynamic context for the purpose of comparison. Note that xs:dateTime, xs:date or xs:time values can compare equal even if their timezones are different. Which value of a set of values that compare equal is returned is implementation dependent.
Parameters:
$arg : A sequence of values to filter.
$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:distinct-values((1, 2.0, 3, 2)) might return (1, 3, 2.0). The following query:
    let $x as xs:untypedAtomic*
        := (xs:untypedAtomic("cherry"),
            xs:untypedAtomic("bar"),
            xs:untypedAtomic("bar"))
    return fn:distinct-values ($x)
returns a sequence containing two items ("cherry", "bar") of type xs:untypedAtomic.
fn:doc(
| [$uri as xs:string*]
) as document-node()*
Summary: Returns the document(s) stored in the database at the specified URI(s).
Parameters:
$uri (optional): The URI of the document to retrieve. If you omit this parameter, returns all of the documents in the database - this is only allowed if you're not using xquery version 1.0 strict. If you specify a list of URIs, returns all of the documents at the URIs specified in the list.
Usage Notes: The `document-node()` returned contains an `element()` root node for XML documents, a `text()` root node for text documents, and a `binary()` root node for binary documents.
Example:
    fn:doc("/mydocs/doc.xml")

    => returns the document at the URI /mydocs/doc.xml
fn:doc-available(
| $uri as xs:string?
) as xs:boolean
Summary: If fn:doc($uri) returns a document node, this function returns true. If $uri is not a valid xs:anyURI, an error is raised [err:FODC0005]. Otherwise, this function returns false. If this function returns true, then calling fn:doc($uri) within the same execution scope must return a document node.
Parameters:
$uri : The URI of the document to check.
Example:
    fn:doc-available("/mydocs/doc.xml")

    => true is /mydocs/doc.xml is a document in the database
fn:empty(
| $arg as item()*
) as xs:boolean
Summary: If the value of $arg is the empty sequence, the function returns true; otherwise, the function returns false.
Parameters:
$arg : A sequence to test.
Example:
    fn:empty(fn:remove(("hello", "world"), 1))

    => false
fn:exactly-one(
| $arg as item()*
) as item()
Summary: Returns $arg if it contains exactly one item. Otherwise, raises an error [err:FORG0005]. For detailed type semantics, see Section 7.2.16 The fn:zero-or-one, fn:one-or-more, and fn:exactly-one functions[FS].
Parameters:
$arg : The sequence of items.
Example:
    fn:exactly-one(("hello"))

    => "hello"

    fn:exactly-one(("hello", "goodbye"))

    => XDMP-NOTONEITEM exception (because there are 2 items)
fn:exists(
| $arg as item()*
) as xs:boolean
Summary: If the value of $arg is not the empty sequence, the function returns true; otherwise, the function returns false.
Parameters:
$arg : A sequence to test.
Example:
    fn:exists(fn:remove(("hello"), 1))

    => false
fn:id(
| $arg as xs:string*,
| [$node as node()]
) as element()*
Summary: Returns the sequence of element nodes that have an ID value matching the value of one or more of the IDREF values supplied in $arg.
Parameters:
$arg : The IDs of the elements to return.
$node (optional): The target node.
2. - Usage Notes: The function returns a sequence, in document order with duplicates eliminated, containing every element node E that satisfies all the following conditions: E is in the target document. The target document is the document containing $node, or the document containing the context node if the second argument is omitted. An error is raised [err:FODC0001] if $node, or the context item if the second argument is omitted, is a node in a tree whose root is not a document node or if the second argument is omitted and there is no context item [err:FONC0001], or if the context item is not a node [err:FOTY0011]. E has an ID value equal to one of the candidate IDREF values, where: An element has an ID value equal to V if either or both of the following conditions are true: The is-id property (See Section 5.5 is-id AccessorDM.) of the element node is true, and the typed value of the element node is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint). The element has an attribute node whose is-id property (See Section 5.5 is-id AccessorDM.) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint). Each xs:string in $arg is parsed as if it were of type IDREFS, that is, each xs:string in $arg is treated as a space-separated sequence of tokens, each acting as an IDREF. These tokens are then included in the list of candidate IDREFs. If any of the tokens is not a lexically valid IDREF (that is, if it is not lexically an xs:NCName), it is ignored. Formally, The candidate IDREF values are the strings in the sequence given by the expression:
         for $s in $arg
         return fn:tokenize(fn:normalize-space($s), ' ')
                          [. castable as xs:IDREF]
If several elements have the same ID value, then E is the one that is first in document order. Notes: If the data model is constructed from an Infoset, an attribute will have the is-id property if the corresponding attribute in the Infoset had an attribute type of ID: typically this means the attribute was declared as an ID in a DTD. If the data model is constructed from a PSVI, an element or attribute will have the is-id property if its schema-defined type is xs:ID or a type derived by restriction from xs:ID. No error is raised in respect of a candidate IDREF value that does not match the ID of any element in the document. If no candidate IDREF value matches the ID value of any element, the function returns the empty sequence. It is not necessary that the supplied argument should have type xs:IDREF or xs:IDREFS, or that it should be derived from a node with the is-idrefs property. An element may have more than one ID value. This can occur with synthetic data models or with data models constructed from a PSVI where an the element and one of its attributes are both typed as xs:ID. If the source document is well-formed but not valid, it is possible for two or more elements to have the same ID value. In this situation, the function will select the first such element. It is also possible in a well-formed but invalid document to have an element or attribute that has the is-id property but whose value does not conform to the lexical rules for the xs:ID type. Such a node will never be selected by this function.
Example:
    let $x := document{
      <html xmlns="http://www.w3.org/1999/xhtml">
        <p id="myID">hello</p>
      </html> }
    return
    fn:id("myID", $x)

    => <p id="myID" xmlns="http://www.w3.org/1999/xhtml">hello</p>
Example:
    xquery version "1.0-ml";
    declare namespace xh="http://www.w3.org/1999/xhtml";

    let $x := document {
      <html xmlns="http://www.w3.org/1999/xhtml">
        <p id="myID">hello</p>
        <p>hello</p>
      </html> }
    return
    $x/xh:html/xh:p[. is fn:id("myID")]

    => <p id="myID" xmlns="http://www.w3.org/1999/xhtml">hello</p>
fn:idref(
| $arg as xs:string*,
| [$node as node()]
) as node()*
Summary: Returns the sequence of element or attribute nodes that have an IDREF value matching the value of one or more of the ID values supplied in $arg.
Parameters:
$arg : The IDREFs of the elements and attributes to return.
$node (optional): The target node.
2. - Usage Notes: The function returns a sequence, in document order with duplicates eliminated, containing every element or attribute node $N that satisfies all the following // conditions: $N is in the target document. The target document is the document containing $node, or the document containing the context node if the second argument is omitted. An error is raised [err:FODC0001] if $node, or the context item if the second argument is omitted, is a node in a tree whose root is not a document node or if the second argument is omitted and there is no context item [err:FONC0001], or if the context item is not a node [err:FOTY0011]. $N has an IDREF value equal to one of the candidate ID values, where: A node $N has an IDREF value equal to V if either or both of the following conditions are true: The is-idrefs property (See Section 5.6 is-idref AccessorDM.) of $N is true. The sequence fn:tokenize(fn:normalize-space($N), ' ') contains a string that is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint). Each xs:string in $arg is parsed as if it were of type xs:ID. These xs:strings are then included in the list of candidate xs:IDs. If any of the xs:strings in $arg is not a lexically valid xs:ID (that is, if it is not lexically an xs:NCName), it is ignored. More formally, The candidate ID values are the strings in the sequence
         $arg[. castable as xs:ID]
Notes: An element or attribute typically acquires the is-idrefs property by being validated against the schema type xs:IDREF or xs:IDREFS, or (for attributes only) by being described as of type IDREF or IDREFS in a DTD. No error is raised in respect of a candidate ID value that does not match the IDREF value of any element or attribute in the document. If no candidate ID value matches the IDREF value of any element or attribute, the function returns the empty sequence. It is possible for two or more nodes to have an IDREF value that matches a given candidate ID value. In this situation, the function will return all such nodes. However, each matching node will be returned at most once, regardless how many candidate ID values it matches. It is possible in a well-formed but invalid document to have a node whose is-idrefs property is true but that does not conform to the lexical rules for the xs:IDREF type. The effect of the above rules is that ill-formed candidate ID values and ill-formed IDREF values are ignored
Example:
    (:
       assume /mydocs/idref.xml has an element named idrefs that is
       of type xs:IDREF or xs:IDREFS
    :)
    fn:idref("myID", doc("/mydocs/idref.xml"))

    => <idrefs>myID</idrefs>
fn:index-of(
| $seqParam as xs:anyAtomicType*,
| $srchParam as xs:anyAtomicType,
| $collationLiteral as xs:string
) as xs:integer*
Summary: Returns a sequence of positive integers giving the positions within the sequence $seqParam of items that are equal to $srchParam. The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations. The collation is used when string comparison is required. The items in the sequence $seqParam are compared with $srchParam under the rules for the eq operator. Values that cannot be compared, i.e. the eq operator is not defined for their types, are considered to be distinct. If an item compares equal, then the position of that item in the sequence $srchParam is included in the result. If the value of $seqParam is the empty sequence, or if no item in $seqParam matches $srchParam, then the empty sequence is returned. The first item in a sequence is at position 1, not position 0. The result sequence is in ascending numeric order.
Parameters:
$seqParam : A sequence of values.
$srchParam : A value to find on the list.
$collationLiteral : A collation identifier.
Example:
    fn:index-of ((10, 20, 30, 40), 35) returns ().

    fn:index-of ((10, 20, 30, 30, 20, 10), 20)
      returns (2, 5).

    fn:index-of (("a", "sport", "and", "a", "pastime"), "a")
      returns (1, 4).

    If @a is an attribute of type xs:NMTOKENS whose
    typed value is " red green blue ", then:

    fn:index-of (@a, "blue") returns 3.

    This is because the function calling mechanism
    atomizes the attribute node to produce a sequence of
    three xs:NMTOKENs.
fn:insert-before(
| $target as item()*,
| $position as xs:integer,
| $inserts as item()*
) as item()*
Summary: Returns a new sequence constructed from the value of $target with the value of $inserts inserted at the position specified by the value of $position. (The value of $target is not affected by the sequence construction.) If $target is the empty sequence, $inserts is returned. If $inserts is the empty sequence, $target is returned. The value returned by the function consists of all items of $target whose index is less than $position, followed by all items of $inserts, followed by the remaining elements of $target, in that sequence. If $position is less than one (1), the first position, the effective value of $position is one (1). If $position is greater than the number of items in $target, then the effective value of $position is equal to the number of items in $target plus 1. For detailed semantics see, Section 7.2.15 The fn:insert-before function[FS].
Parameters:
$target : The sequence of items into which new items will be inserted.
$position : The position in the target sequence at which the new items will be added.
$inserts : The items to insert into the target sequence.
Example:
    let $x := ("a", "b", "c")

    fn:insert-before($x, 0, "z") returns ("z", "a", "b", "c")

    fn:insert-before($x, 1, "z") returns ("z", "a", "b", "c")

    fn:insert-before($x, 2, "z") returns ("a", "z", "b", "c")

    fn:insert-before($x, 3, "z") returns ("a", "b", "z", "c")

    fn:insert-before($x, 4, "z") returns ("a", "b", "c", "z")
fn:max(
| $arg as xs:anyAtomicType*,
| [$collation as xs:string]
) as xs:anyAtomicType?
Summary: Selects an item from the input sequence $arg whose value is greater than or equal to the value of every other item in the input sequence. If there are two or more such items, then the specific item whose value is returned is implementation dependent. The following rules are applied to the input sequence: Values of type xs:untypedAtomic in $arg are cast to xs:double. For numeric values, the numeric promotion rules defined in 6.2 Operators on Numeric Values are used to promote all values to a single common type. The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence.This function returns an item from the converted sequence rather than the input sequence. If the converted sequence is empty, the empty sequence is returned. All items in $arg must be numeric or derived from a single base type for which the ge operator is defined. In addition, the values in the sequence must have a total order. If date/time values do not have a timezone, they are considered to have the implicit timezone provided by the dynamic context for purposes of comparison. Duration values must either all be xs:yearMonthDuration values or must all be xs:dayTimeDuration values. If any of these conditions is not met, then a type error is raised [err:FORG0006]. If the converted sequence contains the value NaN, the value NaN is returned. If the items in the value of $arg are of type xs:string or types derived by restriction from xs:string, then the determination of the item with the largest value is made according to the collation that is used. If the type of the items in $arg is not xs:string and $collation is specified, the collation is ignored. The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations. Otherwise, the result of the function is the result of the expression:
       if (every $v in $c satisfies $c[1] ge $v)
       then $c[1]
       else fn:max(fn:subsequence($c, 2))
evaluated with $collation as the default collation if specified, and with $c as the converted sequence. For detailed type semantics, see Section 7.2.10 The fn:min, fn:max, fn:avg, and fn:sum functions[FS]. Notes: If the converted sequence contains exactly one value then that value is returned. The default type when the fn:max function is applied to xs:untypedAtomic values is xs:double. This differs from the default type for operators such as gt, and for sorting in XQuery and XSLT, which is xs:string.
Parameters:
$arg : The sequence of values whose maximum will be returned.
$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:max((3,4,5)) returns 5.
    fn:max((5, 5.0e0)) returns 5.0e0.
    fn:max((3,4,"Zero")) raises a type error [err:FORG0006].
    fn:max((fn:current-date(), xs:date("2001-01-01")))
    typically returns the current date.
    fn:max(("a", "b", "c")) returns "c" under a typical
                                    default collation.
fn:min(
| $arg as xs:anyAtomicType*,
| [$collation as xs:string]
) as xs:anyAtomicType?
Summary: Selects an item from the input sequence $arg whose value is less than or equal to the value of every other item in the input sequence. If there are two or more such items, then the specific item whose value is returned is implementation dependent. The following rules are applied to the input sequence: Values of type xs:untypedAtomic in $arg are cast to xs:double. For numeric values, the numeric promotion rules defined in 6.2 Operators on Numeric Values are used to promote all values to a single common type. The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence.This function returns an item from the converted sequence rather than the input sequence. If the converted sequence is empty, the empty sequence is returned. All items in $arg must be numeric or derived from a single base type for which the le operator is defined. In addition, the values in the sequence must have a total order. If date/time values do not have a timezone, they are considered to have the implicit timezone provided by the dynamic context for purposes of comparison. Duration values must either all be xs:yearMonthDuration values or must all be xs:dayTimeDuration values. If any of these conditions is not met, then a type error is raised [err:FORG0006]. If the converted sequence contains the value NaN, the value NaN is returned. If the items in the value of $arg are of type xs:string or types derived by restriction from xs:string, then the determination of the item with the largest value is made according to the collation that is used. If the type of the items in $arg is not xs:string and $collation is specified, the collation is ignored. The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations. Otherwise, the result of the function is the result of the expression:
       if (every $v in $c satisfies $c[1] le $v)
       then $c[1]
       else fn:min(fn:subsequence($c, 2))
evaluated with $collation as the default collation if specified, and with $c as the converted sequence. For detailed type semantics, see Section 7.2.10 The fn:min, fn:max, fn:avg, and fn:sum functions[FS]. Notes: If the converted sequence contains exactly one value then that value is returned. The default type when the fn:min function is applied to xs:untypedAtomic values is xs:double. This differs from the default type for operators such as gt, and for sorting in XQuery and XSLT, which is xs:string.
Parameters:
$arg : The sequence of values whose minimum will be returned.
$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:min((3,4,5)) returns 3.

    fn:min((5, 5.0e0)) returns 5.0e0.

    fn:min((3,4,"Zero")) raises a type error [err:FORG0006].

    fn:min(xs:float(0.0E0), xs:float(-0.0E0) can return
    either positive or negative zero.
    [XML Schema Part 2: Datatypes Second Edition] does
    not distinguish between the values positive zero
    and negative zero.
    The result is implementation dependent.

    fn:min((fn:current-date(), xs:date("2001-01-01")))
    typically returns xs:date("2001-01-01").

    fn:min(("a", "b", "c")) returns "a" under a
    typical default collation.
fn:one-or-more(
| $arg as item()*
) as item()+
Summary: Returns $arg if it contains one or more items. Otherwise, raises an error [err:FORG0004]. For detailed type semantics, see Section 7.2.16 The fn:zero-or-one, fn:one-or-more, and fn:exactly-one functions[FS].
Parameters:
$arg : The sequence of items.
Example:
    fn:one-or-more( () )

    => XDMP-ZEROITEMS exception

    fn:one-or-more("hello")

    => "hello"
fn:remove(
| $target as item()*,
| $position as xs:integer
) as item()*
Summary: Returns a new sequence constructed from the value of $target with the item at the position specified by the value of $position removed. If $position is less than 1 or greater than the number of items in $target, $target is returned. Otherwise, the value returned by the function consists of all items of $target whose index is less than $position, followed by all items of $target whose index is greater than $position. If $target is the empty sequence, the empty sequence is returned. For detailed type semantics, see Section 7.2.11 The fn:remove function[FS].
Parameters:
$target : The sequence of items from which items will be removed.
$position : The position in the target sequence from which the items will be removed.
Example:
    let $x := ("a", "b", "c")

    fn:remove($x, 0) returns ("a", "b", "c")

    fn:remove($x, 1) returns ("b", "c")

    fn:remove($x, 6) returns ("a", "b", "c")

    fn:remove((), 3) returns ()
fn:reverse(
| $target as item()*
) as item()*
Summary: Reverses the order of items in a sequence. If $arg is the empty sequence, the empty sequence is returned. For detailed type semantics, see Section 7.2.12 The fn:reverse function[FS].
Parameters:
$target : The sequence of items to be reversed.
Usage Notes: The sequence you specify to reverse must fit into memory, so the sequence size should not be larger than your memory cache sizes.
Example:
    let $x := ("a", "b", "c")
    return
    fn:reverse($x)

    => ("c", "b", "a")
Example:
    fn:reverse(("hello"))

    => ("hello")
Example:
    fn:reverse(())

    => ()
fn:subsequence(
| $sourceSeq as item()*,
| $startingLoc as xs:double,
| [$length as xs:double]
) as item()*
Summary: Returns the contiguous sequence of items in the value of $sourceSeq beginning at the position indicated by the value of $startingLoc and continuing for the number of items indicated by the value of $length. In the two-argument case, returns: $sourceSeq[fn:round($startingLoc) le $p] In the three-argument case, returns: $sourceSeq[fn:round($startingLoc) le $p and $p lt fn:round($startingLoc) + fn:round($length)] Notes: If $sourceSeq is the empty sequence, the empty sequence is returned. If $startingLoc is zero or negative, the subsequence includes items from the beginning of the $sourceSeq. If $length is not specified, the subsequence includes items to the end of $sourceSeq. If $length is greater than the number of items in the value of $sourceSeq following $startingLoc, the subsequence includes items to the end of $sourceSeq. The first item of a sequence is located at position 1, not position 0. For detailed type semantics, see Section 7.2.13 The fn:subsequence functionFS. The reason the function accepts arguments of type xs:double is that many computations on untyped data return an xs:double result; and the reason for the rounding rules is to compensate for any imprecision in these floating-point computations.
Parameters:
$sourceSeq : The sequence of items from which a subsequence will be selected.
$startingLoc : The starting position of the start of the subsequence.
$length (optional): The length of the subsequence.
Example:
    Assume $seq = ($item1, $item2, $item3, $item4, ...)

    fn:subsequence($seq, 4) returns ($item4, ...)

    fn:subsequence($seq, 3, 2) returns ($item3, $item4)
fn:sum(
| $arg as xs:anyAtomicType*,
| [$zero as xs:anyAtomicType?]
) as xs:anyAtomicType?
Summary: Returns a value obtained by adding together the values in $arg. If $zero is not specified, then the value returned for an empty sequence is the xs:integer value 0. If $zero is specified, then the value returned for an empty sequence is $zero. Any values of type xs:untypedAtomic in $arg are cast to xs:double. The items in the resulting sequence may be reordered in an arbitrary order. The resulting sequence is referred to below as the converted sequence. If the converted sequence is empty, then the single-argument form of the function returns the xs:integer value 0; the two-argument form returns the value of the argument $zero. If the converted sequence contains the value NaN, NaN is returned. All items in $arg must be numeric or derived from a single base type. In addition, the type must support addition. Duration values must either all be xs:yearMonthDuration values or must all be xs:dayTimeDuration values. For numeric values, the numeric promotion rules defined in 6.2 Operators on Numeric Values are used to promote all values to a single common type. The sum of a sequence of integers will therefore be an integer, while the sum of a numeric sequence that includes at least one xs:double will be an xs:double. If the above conditions are not met, a type error is raised [err:FORG0006]. Otherwise, the result of the function, using the second signature, is the result of the expression:
       if (fn:count($c) eq 0) then
           $zero
       else if (fn:count($c) eq 1) then
           $c[1]
       else
           $c[1] + fn:sum(subsequence($c, 2))
where $c is the converted sequence. The result of the function, using the first signature, is the result of the expression:fn:sum($arg, 0). For detailed type semantics, see Section 7.2.10 The fn:min, fn:max, fn:avg, and fn:sum functions[FS]. Notes: The second argument allows an appropriate value to be defined to represent the sum of an empty sequence. For example, when summing a sequence of durations it would be appropriate to return a zero-length duration of the appropriate type. This argument is necessary because a system that does dynamic typing cannot distinguish "an empty sequence of integers", for example, from "an empty sequence of durations". If the converted sequence contains exactly one value then that value is returned.
Parameters:
$arg : The sequence of values to be summed.
$zero (optional): The value to return as zero if the input sequence is the empty sequence. This parameter is not available in the 0.9-ml XQuery dialect.
Usage Notes: When running this in the 0.9-ml XQuery dialect, there is no second argument to `fn:sum`; the second ($zero) argument is available in both the 1.0 and 1.0-ml dialects.
Example:
    Assume:
    $d1 = xs:yearMonthDuration("P20Y")
    $d2 = xs:yearMonthDuration("P10M")
    $seq1 = ($d1, $d2)
    $seq3 = (3, 4, 5)

    fn:sum(($d1, $d2))
    returns an xs:yearMonthDuration with a value of 250 months.

    fn:sum($seq1[. > xs:yearMonthDuration('P3M')],
                     xs:yearMonthDuration('P0M'))
    returns an xs:yearMonthDuration with a value of 0 months.

    fn:sum($seq3) returns 12.

    fn:sum(()) returns 0.

    fn:sum((),()) returns ().

    fn:sum((1 to 100)[.>0], 0) returns 0.

    fn:sum(($d1, 9E1)) raises an error [err:FORG0006].
fn:unordered(
| $sourceSeq as item()*
) as item()*
Summary: Returns the items of $sourceSeq in an implementation dependent order. Note: Query optimizers may be able to do a better job if the order of the output sequence is not specified. For example, when retrieving prices from a purchase order, if an index exists on prices, it may be more efficient to return the prices in index order rather than in document order.
Parameters:
$sourceSeq : The sequence of items.
fn:zero-or-one(
| $arg as item()*
) as item()?
Summary: Returns $arg if it contains zero or one items. Otherwise, raises an error [err:FORG0003]. For detailed type semantics, see Section 7.2.16 The fn:zero-or-one, fn:one-or-more, and fn:exactly-one functions[FS].
Parameters:
$arg : The sequence of items.
Example:
    fn:zero-or-one("hello")

    => "hello"

    fn:zero-or-one(("hello", "goodbye"))

    => XDMP-MORETHANONEITEM exception (because there are two items)

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