XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (530 page)

See Also

string-to-codepoints()
on page 881

collection

The
collection()
function returns a sequence of documents, or more generally a sequence of nodes, identified by a URI. The way in which a URI can be used to locate a collection of documents is entirely implementation-defined.

Signature

Effect

This function is specified in very abstract terms, and it's likely that its detailed behavior will vary considerably from one implementation to the next.

Many XML databases have the concept of a collection as a container for documents, and the containers generally have a name, which can be mapped into some kind of URI. Beyond that, there are many variations; for example, some systems might allow collections to be nested hierarchically, some systems might use a collection to store all the documents that are validated against one particular schema, and so on. Some implementations map the concept of a collection onto a simple directory containing the documents (perhaps with a filter applied to the document names), or onto an XML catalog file that holds a list of the documents within the collection.

All that the spec really says about this function is that the supplied URI argument is resolved against the base URI from the static context, and the resulting absolute URI is used to identify a collection of documents; the result is a sequence containing the document nodes of these documents. In fact it isn't constrained to return document nodes, there might be collections that return other kinds of nodes.

The specification also says that the function is
stable
, which means that if you call it twice in the same expression (or, in the case of XSLT, in the same transformation), then you get the same answer back each time. In other words, a collection at least gives the appearance of being immutable for the duration of a query or transformation.

There's one other provision: if you call the
document-uri()
function on a document that was returned as part of the collection, then this will either return nothing, or it will return a URI that can be used as input to the
doc()
function to retrieve the original document. This rule gives you a useful guarantee if you want to follow hyperlinks between different documents in the collection.

Beyond this, it's not really possible to say what the
collection()
function does, without going into the details of individual implementations. The following table gives a summary of its behavior in the main XSLT 2.0 implementations available at the time of writing:

Product	Action
Altova	If the URI identifies a catalog file (see below), then the files listed in the catalog are loaded and returned as the result of the collection() function. Alternatively the argument may specify a directory and/or a filename pattern. For example, collection(“*.xml”) selects all files with extension “.xml” in the same directory as the stylesheet.
Gestalt	Gestalt allows you to supply a URI that references a directory, for example file:///c:/input-dir/ . The collection that is returned contains a document node for each well-formed XML file in that directory.
Saxon	Saxon allows you to set up your own CollectionURIResolver , which can interpret the collection URI any way it likes. By default, it provides two options: the collection URI can resolve to a catalog file (see below), which lists the documents to be loaded; or it can be a URI referring to a directory, in which case all the XML files in that directory are loaded. It is also possible to specify query parameters in the URI that define a filename pattern that restricts the files selected, together with details such as whether the directory contents are scanned recursively, whether parsing errors are fatal, and whether schema or DTD validation is to be attempted. Further details at http://www.saxonica.com/documentation/sourcedocs/collections.html .

The format of the catalog file used by Saxon and Altova is not defined in any standard, but it is similar for both products. Here is an example:

Saxon also allows an attribute
stable=“no”
on the

element to override the normal requirement for the collection to be immutable. It can save the processor a lot of work (and memory) to omit this check.

See Also

doc()
on page 750

compare

The
compare()
function is used to compare two strings, and to decide whether they are equal, or if not, which one sorts before the other.

For example, under most collations
compare(“ALPHA”, “BETA”)
returns
-1
.

Signature

Effect

If either
value-1
or
value-2
is an empty sequence, the result is an empty sequence.

If
value-1
is less than
value-2
, the function returns
-1
; if they are equal, it returns
0
; and if
value-1
is greater than
value-2
, it returns
+1
. The string comparison is done using the supplied
collation
if specified; if the collation argument is omitted, the comparison is done using the default collation. For more information on collations, see the section
Collations
in Chapter 6, page 459.

Examples

These examples assume the availability of two collation URIs:
$strong
, which considers first the character value, then accents, then case (with upper case first); and
$weak
, which considers only the character value.