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

See Also

on page 240

on page 271

on page 500

on page 517

xsl:perform-sort

The

instruction is used to sort a sequence. If you want to process the items in a sequence in sorted order, you can achieve this by adding

elements to an

or

instruction. If you just want to sort the sequence, without processing the items individually, this can be done using

.

Changes in 2.0

This instruction is new in XSLT 2.0

Format

Position

is an instruction, and may be used anywhere within a sequence constructor.

Attributes

Content

The

instruction always contains one or more

elements to specify the sort order.

In addition, it may contain a sequence constructor. This is an alternative to the
select
attribute: if the
select
attribute is present, then the

element must contain only

elements. It can also contain

elements to define what an XSLT 1.0 processor should do when it encounters this instruction in forward-compatible mode.

Effect

The instruction forms an initial sequence by evaluating the expression in the
select
attribute or the contained sequence constructor, whichever is present. It then sorts this initial sequence to produce a sorted sequence, according to the rules for

, which are given on page 458. The result of the

instruction is the sorted sequence.

Usage and Examples

The

instruction is useful when you want to create a sorted sequence in a variable, or as the result of a function. If you want to process items in sorted order you can achieve this using

or

, but these instructions do not deliver the sorted sequence directly as a value in its own right.

For example, you could define a global variable containing the speakers in a play, sorted alphabetically, by writing:

The following function returns the earliest and latest date in a sequence of events, as a sequence of two

elements with
date
attributes:

See Also

on page 240

on page 322

on page 455

xsl:preserve-space

The

element, along with

, is used to control the way in which whitespace nodes in the source document are handled.

Changes in 2.0

The syntax of a
NameTest
has been extended to allow the format
*:NCName
, which matches all elements with a given local name, in any namespace.

Format

Position

is a top-level declaration, which means that it must be a child of the

element. There are no constraints on its ordering relative to other declarations.

Attributes

The
NameTest
construct is defined in XPath, and is described in Chapter 9 on page 614.

Content

None, the element is always empty.

Effect

This declaration, together with

, defines the way that whitespace-only text nodes in the source document are handled. Unless contradicted by an

element,

indicates that whitespace-only text nodes occurring as children of a specified element are to be retained in the source tree.

Preserving whitespace-only text nodes is the default action, so this element only needs to be used where it is necessary to contradict an

element. More specifically, a whitespace text node is stripped only if (a) it matches a
NameTest
specified in an

element, and (b) it does not match a
NameTest
in an overriding

element.

The concept of whitespace-only text nodes is explained in Chapter 3 (see page 144). A whitespace-only text node is a text node whose text consists
entirely
of a sequence of whitespace characters, these being space, tab, carriage return, and linefeed
(x20
,
x09
,
x0D
, and
x0A)
. The

element has no effect on whitespace contained in text nodes that also contain non-whitespace characters; such whitespace is always preserved and is part of the value of the text node.

This declaration also affects the handling of whitespace-only text nodes in any document loaded using functions such as
document()
,
doc()
, or
collection()
. It does not affect the handling of whitespace-only text nodes in the stylesheet, or in documents returned as the result of extension functions or passed to the stylesheet as the value of a stylesheet parameter. Also, the element does not affect anything that happens to the source document before the XSLT processor gets to see it, so if you create the source tree using an XML parser that strips whitespace nodes (as Microsoft's MSXML3 does, by default), then specifying

in the stylesheet will not get these nodes back—they are already gone.

Although an XML 1.1 parser will recognize the characters
x85
and
x2028
as representing line endings, the XSLT processor will not treat these characters as whitespace. It doesn't need to, because the XML parser will have converted them into regular newline characters.

Before a node is classified as a whitespace-only text node, the tree is normalized by concatenating all adjacent text nodes. This includes the merging of text that originated in different XML entities, and also text written within CDATA sections.

A whitespace-only text node may either be stripped or preserved. If it is stripped, it is removed from the tree. This means it will never be matched, it will never be copied to the output, and it will never be counted when nodes are numbered. If it is preserved, it is retained on the tree in its original form, subject only to the end-of-line normalization performed by the XML parser.