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

Grouping keys are compared based on their type. For example, numbers are compared as numbers, and dates are compared as dates. Two grouping keys are considered equal based on the rules of the XPath
eq
operator, which is explained in Chapter 8 on page 582. Strings are compared using the collation specified in the
collation
attribute if present (for more details on collations, see under

on page 455). Two NaN (not-a-number) values are considered equal to each other even though they are not equal when compared using
eq
. If two values cannot be compared (because they are of noncomparable types; for example,
xs:date
and
xs:integer
), then they are considered not equal, which means the items end up in different groups.

If the
group-by
expression for any item in the population evaluates to an empty sequence, then the item will not be allocated to any groups, which means it will not be processed at all.

group-adjacent

When the
group-adjacent
attribute is used to define the grouping criteria, items are assigned to groups on the following basis:

• The first item in the population starts a new group.
  
• Subsequent items in the population are allocated to the same group as the previous item in the population if and only if they share the same value for the grouping key defined by the
  group-adjacent
  attribute; otherwise, they are allocated to a new group.
  

The
group-adjacent
expression is evaluated once for each item in the population. During this evaluation, the context item is this item, the context position is the position of this item in population order, and the context size is the size of the population. The value that results from evaluating the
group-adjacent
expression is atomized (see page 81). Unlike the
group-by
attribute, the result of evaluating the
group-adjacent
expression, after atomization, must be a single value. A type error is reported if the value is an empty sequence, or if it is a sequence containing more than one atomic value.

Values of the grouping key are compared in the same way as for the
group-by
attribute. This means, for example, that strings are compared using the collation defined in the
collation
attribute if specified, and that NaN values compare equal.

There are two main reasons for using
group-adjacent
in preference to
group-by
:

• Firstly, when there is a genuine requirement not to group items with the same grouping key unless they are adjacent. For example, a sequence of temperature readings might be presented so that the only readings actually shown are those that differ from the previous reading. This can be achieved by grouping adjacent readings and only displaying the first reading in each group.
  
• Secondly, when it is known that the items with common grouping keys will always be adjacent in the population. In this case using
  group-adjacent
  might give the same result as
  group-by
  , but might be more efficient because the XSLT processor can perform the grouping in a single pass through the data.
  

group-starting-with

The
group-starting-with
attribute is an XSLT pattern (not an expression). Patterns are described in Chapter 12. Patterns apply only to nodes, so this attribute must be used only when the population consists entirely of nodes. The nodes in the population are assigned to groups on the following basis:

• The first node in the population starts a new group.
  
• Subsequent nodes in the population start a new group if they match the pattern, and are assigned to the same group as the previous node otherwise.
  

The result is that the initial node in each group (the one that comes first in population order) will always match the pattern, with the possible exception of the first group, which may contain no node that matches the pattern.

The
group-starting-with
attribute is useful where the population consists of a repeating group of nodes whose first member can be readily identified: for example, a

element followed by a sequence of

elements, then another

, and so on. In this case the grouping can easily be defined using
group-starting-with=“header”
.

group-ending-with

This attribute behaves in a very similar way to
group-starting-with
, except that the pattern identifies the last item in a group instead of the first. The nodes in the population are assigned to groups on the following basis:

• The first node in the population starts a new group.
  
• Subsequent nodes in the population start a new group if the previous node in the population matches the pattern, and they are assigned to the same group as the previous node otherwise.
  

The most common use case for this option is where input records contain a continuation marker of some kind. For example, the population might consist of elements that have the attribute
continued=“yes”
or
continued=“no”
. A group can then be defined using the criterion
group-ending-with=“*[@continued=“no“]”
.