tdt:group() and tdt:ungroup()

These functions can be used to group nodes based on specified grouping criteria. Grouping criteria are represented by one or more strings containing relative XPaths, optionally prefixed with “~” aggregation prefix.

Note:

The tdt:group() function generates a break or new group every time the value of any of the keys changes. Because of this it is necessary to add an aggregation prefix if data is not already aggregated or sorted.

When tdt:group() is called, several steps are performed:

•	Input node-set is enumerated.

•	All given XPaths are evaluated in the context of each element.

•	Aggregation is performed based on given aggregation keys.

•	Grouping is performed based on equality.

•	For each resulting group, a synthesized tdt:group element is created. See Synthesized groups below.

•	Node-set of all synthesized tdt:group elements is returned.

Each synthesized tdt:group element contains summary information about grouping operation, number of grouped nodes etc., but does not contain the actual grouped nodes.

The grouped nodes can be accessed using the tdt:ungroup() function. This function accepts the tdt:group element as argument, and returns a node-set of grouped original nodes.

Signature (tdt:group)

<node-set> tdt:group(<node-set>[, <string>, … ])

Signature (tdt:ungroup)

<node-set> tdt:ungroup(<node>)

Example

Data source

<data> <message> <r cls="A" num="10">1</r> <r cls="A" num="5">2</r> <r cls="B" num="10">3</r> <r cls="B" num="5">4</r> <r cls="B" num="10">5</r> <r cls="A" num="5">6</r> <r cls="A" num="10">7</r> <r cls="B" num="5">8</r> <r cls="B" num="10">9</r> </message> </data>

Expected result

<data> <message> <cls size="2" cls="A" num="10"> <r>1</r> <r>7</r> </cls> <cls size="2" cls="A" num="5"> <r>2</r> <r>6</r> </cls> <cls size="3" cls="B" num="10"> <r>3</r> <r>5</r> <r>9</r> </cls> <cls size="2" cls="B" num="5"> <r>4</r> <r>8</r> </cls> </message> </data>

Data template

<data> <message> <cls size="?" cls="?" num="?"> <r>?</r> </cls> </message> </data>

Data transformation

<tdt:rule path="/data/message"> <tdt:value key=".">/data/message</tdt:value> </tdt:rule> <tdt:rule path="/data/message/cls"> <tdt:value key=".">tdt:group(r, '~@cls', '~@num')</tdt:value> <tdt:value key="@size">@size</tdt:value> <tdt:value key="@cls">tdt:key[@key='~@cls']</tdt:value> <tdt:value key="@num">tdt:key[2]</tdt:value> </tdt:rule> <tdt:rule path="/data/message/cls/r"> <tdt:value key=".">tdt:ungroup()</tdt:value> <tdt:value key="text()">text()</tdt:value> </tdt:rule>

Synthesized groups

The tdt:group() function call returns a node-set of synthesized tdt:group elements, where each element represents a single group. A tdt:group element does not contain the actual grouped nodes – it contains several synthesized sub-nodes and attributes. To access the actual grouped nodes you must use the tdt:ungroup() function.

The synthesized structure is as follows:

<tdt:group size="?">
   <tdt:key key="?">?</tdt:key>
</tdt:group>

Where:

•	@size – the number of nodes in the group.

•	tdt:key – one child for every grouping argument.

•	@key – string XPath used for grouping (optionally prefixed with '~' aggregation prefix)

•	text() – actual result data value of the XPath used for grouping

In the example above, the first synthesized group looks like this:

<tdt:group size="2">
   <tdt:key key="~@cls">A</tdt:key>
   <tdt:key key="~@num">10</tdt:key>
</tdt:group>