fn:collection

fn:collection() as item()*

fn:collection($arg as xs:string?) as item()*

This function is deterministic, context-dependent, and focus-independent. It depends on available collections, and static base URI.

This function takes an xs:string as argument and returns a sequence of items obtained by interpreting $arg as an xs:anyURI and resolving it according to the mapping specified in available collections described in Dynamic Context Components.

If available collections provides a mapping from this string to a sequence of items, the function returns that sequence. If available collections maps the string to an empty sequence, then the function returns an empty sequence.

If $arg is not specified, the function returns the sequence of items in the default collection in the dynamic context. See Dynamic Context Components.

If the value of $arg is a relative xs:anyURI, it is resolved against the value of the base-URI property from the static context.

If $arg is the empty sequence, the function behaves as if it had been called without an argument. See above.

By default, this function is deterministic. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [ERRFODC0003].

There is no requirement that any nodes in the result should be in document order, nor is there a requirement that the result should contain no duplicates.

A dynamic error is raised [ERRFODC0002] if no URI is supplied and the value of the default collection is absent.

A dynamic error is raised [ERRFODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.

A dynamic error is raised [ERRFODC0002] if available node collections provides no mapping for the absolutized URI.

A dynamic error may be raised [ERRFODC0004] if $arg is not a valid xs:anyURI.

In earlier releases, the primary use for the fn:collection function was to retrieve a collection of XML documents, perhaps held as lexical XML in operating system filestore, or perhaps held in an XML database. In this release the concept has been generalised to allow other resources to be retrieved: for example JSON documents might be returned as arrays or maps, non-XML text files might be returned as strings, and binary files might be returned as instances of xs:base64Binary.

The abstract concept of a collection might be realized in different ways by different implementations, and the ways in which URIs map to collections can be equally variable. Specifying resources using URIs is useful because URIs are dynamic, can be parameterized, and do not rely on an external environment.