XQEngine: Functions and Operators

This is a currently short but growing alphabetic list of all functions and operators currently implemented by XQEngine. There are two namespace prefixes in use in this document:
represents the namespace URI "http://www.w3.org/2003/11/xpath-functions", for functions defined in the XQuery 1.0 and XPath 2.0 Functions and Operators document.
represents the URI "http://www.fatdog.com/xqe-functions", the namespace URI for XQEngine-specific functions.
These namespace prefixes are currently in use in this documentation only. These functions as actually invoked in XQEngine queries take no prefixes at this point; I have not yet implemented that functionlity.

fn:boolean( $arg as item()* ) as xs:boolean

Returns the Effective Boolean Value of its argument. The EFB is calculated as follows :

    boolean( () )      -> false   (: the empty sequence :)
    boolean( false() ) -> false
    boolean( "" )      -> false   (: a zero-length string :)
    boolean( 0 )       -> false   (: an integer 0 :)

The Effective Boolean Value of all other argument types evaluates to true.


    boolean( doc( "NoSuchDocumentInTheKnownUniverse" ) ) -> false 
                                                           (: evals to the empty sequence :)
    boolean( (1, 2, 3) ) -> true

fn:count( $arg as item()* ) as xs:integer

Returns the number of items in the sequence that $arg evaluates to. Returns 0 if $arg is the emtpy sequence.


    count( (1,2,<emptyTag/>) )     -> 3

    count( doc( "bib.xml" )/book ) -> 4

    count( ( () )                  -> 0

xqe:contains-word($path as node()+, $word as xs:string+, $caseSensitive as xs:boolean?) as node()*

The location path $path is evaluated and nodes in the resulting node sequence are checked for instances of the word $word. Words are sequences of non-whitespace characters delimited by whitespace. The default is a case-insensitive search, although the optional boolean argument, $caseSensitive can be used to specify that case is significant. Nodes satisfying the search are returned. An empty sequence will be returned if either $path evaluates to an empty sequence or the sequence is non-empty but no words are found.

Several things are noteworthy here:

  • Instances of $word can be found in any descendant element of a node in the node sequence $path evaluates to for that node to be returned. In other words, the queries
        contains-word( doc( "bib.xml" ), "tcp/ip" )
        contains-word( doc( "bib.xml" )/bib, "tcp/ip" )
        contains-word( doc( "bib.xml" )/bib/book, "tcp/ip" )
        contains-word( doc( "bib.xml" )/bib/book/title, "tcp/ip" )
    are all equivalent and return a single node, the type of node depending on the particular query. This can be both useful (you might want to know which document(s) contain a particular word, and return only the top-level document node(s) in that case), as well as potentially confusing (the query "contains-word( //*, "tcp/ip" ) returns three hits, one for the <title> node that actually contains the hit, and one for each of its superordinate <book> and <bib> elements.)

  • The $word string can be a word phrase, in which case the phrase is automatically parsed into individual words, all of which must be present for the search to hold. The above "tcp/ip" example demonstrates this: the slash ("/") acts as a word delimitor. Note that word order is not significant in this case: the search "ip/tcp" (as well as "tcp:ip", "ic tcp", etc., etc.) would succeed as well.

  • If you want to use a phrase search, you can also explicitly parse the phrase yourself, using as many string argments as required :
        contains-word( doc( "bib.xml" ), "tcp", "ip" )

cw(...) is a valid shortcut for the name of this function.

NOTA: The signature of this function might change in future to return a boolean value, depending on the final recommendations of the W3C's Full-Text Task Force. A boolean return type makes this function more composable with other XQuery expressions.

xqe:chr( $codePoint as xs:integer ) as xs:string?

This is a convenience function, one use of which is to allow greater control in formatting serialized output.


    1, " ", 2 -> 1 2

    1, chr(10), 2 -> 1

    let $twoLineFeeds := (chr(10), chr(10))
    return 1, $twoLineFeeds, 2

    ->  1


fn:doc( $docUri as xs:string ) as node()?

xqe:doc( $docId as xs:integer ) as node()?

fn:doc( $docUri as xs:string ) retrieves a document node, given the name that was originally passed to XQEngine.setDocument() or XQEngine.setQuery( "doc(...)" ) to index it. If the document exists but has not already been indexed, it will be. If the evaluation of $docUri results in an empty sequence ("No Such Document"), the function returns the empty sequence.

fn:doc( $docId as xs:integer ) takes the integer docId assigned by XQEngine when the document was indexed and returns the corresponding document node.


    doc( "bib.xml" )//book[ @year = '1992' ]/title

	-> <title>Advanced Programming in the Unix environment</title>

    doc( 0 )//book[ @year = '1992' ]/title

	-> <title>Advanced Programming in the Unix environment</title>

xqe:document-name( $docNode as node()? ) as xs:string?

This function provides similar but not identical functionality to the "Functions and Operators" function, fn:document-uri(). Both functions take a document node as argument and return the name of the document containing the node. The main difference is that the latter function returns an empty sequence in the case of a relative URI, while a relative URI can be a perfectly valid document name in the case of fn:document-name(). The function will throw an InvalidQueryException if the $docNode is neither the empty sequence nor a document node. See root() for how to derive a document node from another node subordinate to it.

document-name() returns the empty sequence if passed the empty sequence as an argument.

This function is useful for returning the names of documents contributing to nodes in a hit list. See examples below.

doc-name() is a valid shorthand name for this function.


    document-name( doc( "bib.xml" ) ) -> "bib.xml"

    doc-name( root( //editor ) )      -> "bib.xml"

    for $book in //book
       <title document = "{ doc-name( root( $book )) }">
           { $book/title/text() } 
       </title>, chr(10)  


     <title document="bib.xml">TCP/IP Illustrated</title>
     <title document="bib.xml">Advanced Programming in the Unix environment</title>
     <title document="bib.xml">Data on the Web</title>
     <title document="bib.xml">The Economics of Technology and Content for Digital TV</title>
     <title document="book.xml">Data on the Web</title>

fn:empty( $items as item()? ) as xs:boolean

If $items evaluates to the empty sequence, a boolean true is returned. Otherwise false is returned. See exists().


    empty( () )        -> true

    empty( (1, 2, 3) ) -> false

fn:exists( $items as item()? ) as xs:boolean

If $items evaluates to the empty sequence, a boolean false is returned. Otherwise true is returned. See emtpy().


    exists( () ) -> false

    exists( 47 ) -> true

    exists( doc( "noSuchDocumentInTheKnownUniverse" ) ) -> false

fn:false( ) as xs:boolean

Constructs and returns the boolean value false.


    false() -> false

xqe:name( $node as node()? ) as xs:string

Returns the name of a single element or attribute node. Returns a 0-length string if its argument evaluates to the empty sequence or is a node without a name, such as a document or text node. Throws an exception if its argument is neither the empty sequence nor a single node.


    name( //editor )           -> "editor"
    name( /bib/book[1]/@year ) -> "year"
    name( () )                 -> ""  
    name( //xyzzy )            -> ""  
    name( doc("bib.xml" ))     -> ""  (: a "nameless" node type :)
    name( //book )             -> InvalidQueryException  (: node but not single :)            
    name( 47 )                 -> InvalidQueryException  (: not a node at all   :)

fn:not( $arg as item()* ) as xs:boolean

Negates the Effective Boolean Value of its argument. See fn:boolean().


   not( true() ) -> false

   not( () )     -> true

fn:root( $node as node()? ) as xs:string

Returns the empty sequence if $node evaluates to the empty sequence. Throws an InvalidQueryException if $node does not evaluate to a single node. If $node is the document node, it returns that. Otherwise returns the document node representing the document containing the node. Useful for accessing a hit node's document node, possibly to derive the name of the owning document. See document-name(). root() currently does not work for constructed nodes.


     doc-name( root(//editor) ) -> "bib.xml"

     root( //book )             -> InvalidQueryException (: must be a single node or empty sequence :)

fn:string( $seq as item()* ) as xs:boolean

If $seq is the empty sequence, the zero-length string is returned. If $seq is a node, the function returns the string-value of the node, as obtained using the dm:string-value accessor defined in the "XQuery 1.0 and XPath 2.0 Data Model" document. For non-node items (ie atomic values), the function casts the item to a string.


    string( //book/author/last ) -> "StevensStevensAbiteboulBunemanSuciu"

    string( 1 )                  -> "1"

    string( () )                 -> 

xqe:true( ) as xs:boolean

Constructs and returns the boolean value true.


    true() -> true

    contains-word( doc( "bib.xml" )/bib, "TCP/IP", true() ) (: used as a boolean argument :)

  created 25feb04
  last updated 25feb04

  XQEngine home