xsl:for-each-group

Selects a sequence of nodes and/or atomic values 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

select

expression

Expression to select nodes/values.

array?

expression

Experimental addition in XSLT 4.0, allowed only if syntax extensions are enabled: an alternative to the select attribute. Defines an array over which the statement will iterate. The XSLT statements subordinate to the xsl:for-each-group element are applied to each member of the input array in turn; the members are presented as instances of the type record(value), which can be converted to a sequence (or in many cases, a single item) using the expression ?value.

map?

expression

Experimental addition in XSLT 4.0, allowed only if syntax extensions are enabled: an alternative to the select attribute. Defines a map over which the statement will iterate. The XSLT statements subordinate to the xsl:for-each-group element are applied to each entry of the input map in turn (in an undefined order); the entries are presented as instances of the type record(key as xs:anyAtomicType, value as item()*), so the key can be obtained using ?key, and the value using ?value. Because the order of entries is undefined, the only grouping option that makes sense for maps is group-by.

group-by?

expression

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.

group-adjacent?

expression

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 <bullet> elements. In this case the grouping key must be single-valued.

group-starting-with?

pattern

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 <h2> element and its following <p> elements.

group-ending-with?

pattern

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 continued="no".

break-when?

expression

Experimental addition in 4.0; available only if syntax extensions are enabled. The value of the attribute is an expression, which must return a boolean. The expression is supplied with two variables, namely (a) $group which is set to the contents of the current group, and (b) $next which is set to the next item. The expression returns false if the new item is to be added to the end of the current group, or true if the current group is complete and the new item is to become the first item in a new current group. For example break-when="sum($group/@page-count) gt 100" starts a new group when the size of the current group passes some threshold.

composite?

boolean

Can be used when grouping using either group-by or group-adjacent. If set to yes, then the group-by and group-adjacent expressions may evaluate to a sequence, and grouping is done by comparing the entire sequence. If set to no (the default), then when group-by evaluates to a sequence, the relevant item has multiple grouping keys and goes in multiple groups; with group-adjacent, a sequence-valued grouping key is then an error.

collation?

{ uri }

The name of a collating sequence, used when comparing grouping keys. Can be used when grouping using either group-by or group-adjacent. If present it must be a collation URI that uses the scheme and path http://www.w3.org/2013/collation/UCA, in which case it requests use of the Unicode Collation Algorithm, or is a collation otherwise recognized by Saxon: see Sorting and collations.

Saxon availability

Available in XSLT 2.0 and later versions. Available in all Saxon editions. Available for all platforms.

Notes on the Saxon implementation

Earlier drafts of XSLT 3.0 introduced new attributes bind-group and bind-grouping-key; these are no longer supported since Saxon 9.6.

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 break-when attribute is available from Saxon 11. Streaming is not yet implemented for break-when.

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 values as well as nodes.

Examples

For examples of using the instruction, see the XSLT 2.0 specification.

Links to W3C specifications

XSLT 2.0 Specification

XSLT 3.0 Specification

XSLT 4.0 Specification

See also

xsl:sort

current-group()

current-grouping-key()