xsl:for-each-group
Selects a sequence of nodes and/or atomic items and organizes them into subsets called groups.
Category: instruction
Content: (
xsl:sort*
, sequence-constructor
)
Permitted parent elements:
any XSLT element whose content model is
sequence-constructor; any literal result element
Attributes
|
| Expression to select nodes/values. |
|
| Groups together all items having the same value for a grouping key. The grouping key may have multiple values (a sequence of values) in which case the item is added to more than one group. |
|
| Groups together all items having the
same value for a grouping key, provided that they are also adjacent in the input
sequence. This is useful when you need to wrap a new element around a sequence
of related elements in the source documents, for example a consecutive sequence
of |
|
| Processes the items in the
supplied sequence in turn, starting a new group whenever one of the items
matches a specified pattern. This is useful, for example, when matching an
|
|
| Processes the items in the
supplied sequence in turn, closing the current group whenever one of the items
matches a specified pattern. This is useful when matching a sequence of items in
which the last item in the group carries some distinguishing attribute such as
|
|
| New in XSLT 4.0. Allows a new group to be
started conditionally based on the contents of the current group so far. The
value of the attribute is an expression, which must return a boolean. The
expression is supplied with two variables, namely (a) |
|
| New in XSLT 4.0. Not implemented in Saxon 13. |
|
| Can be used when grouping using either
|
|
| The name of a collating sequence, used
when comparing grouping keys. Can be used when grouping using either
|
Saxon availability
Available in XSLT 2.0 and later versions. Available in all Saxon editions. Available for all platforms.
Notes on the Saxon implementation
The composite attribute has been implemented since Saxon 9.6.
Since 9.6, Saxon supports streamed grouping when the group-adjacent,
group-starting-with, or group-ending-with
attributes are used. Streaming with a group-by attribute became
available in 9.7 maintenance releases and is fully supported in Saxon 9.8 (in
this case the xsl:for-each-group instruction must appear within
xsl:fork).
The XSLT 4.0 split-when attribute is available from Saxon 13.
Streaming is not yet implemented for split-when. In Saxon 11
and 12, this attribute was available experimentally under the name
break-when provided that syntax extensions were enabled;
for now this is retained as a synonym, but will be removed in a later
release.
The XSLT 4.0 merge-when attribute is not yet implemented in
Saxon.
Details
There are four possible ways of defining the grouping using different attributes:
group-by, group-adjacent,
group-starting-with, and group-ending-with.
In XSLT 3.0, the capabilities of the xsl:for-each-group instruction
are extended by virtue of the fact that the pattern used in
group-starting-with or group-ending-with can now
match atomic items as well as nodes.
In XSLT 4.0, two new ways of defining the grouping are introduced
using the new attributes merge-when and split-when.
Only split-when is currently implemented in Saxon 13. This allows a
new group to be started conditionally based on the contents of the current group
so far. For example, split-when="@date lt $group[last()]/@date
causes a new group to be started whenever the date on the current item is
earlier than the date on the last item in the previous group.
Examples
For examples of using the instruction, see the XSLT 3.0 specification.