[ library(lists_of_structures) | Reference Manual | Alphabetic Index ]
# group_with_key(+Key, +Structs, -Grouped)

Partition a list into sublists by key
*Key*
- Key argument position (non-negative integer, or list of those)
*Structs*
- List of structures
*Grouped*
- Variable, or list of KeyVal-SubList structures

## Description

The list Structs is partitioned into maximal sublists of consecutive
elements with identical keys, such that concatenating all these sublists
would yield the original list. If the original list was ordered according
to the Key'th argument, then the sublists represent a partitioning of
the original elements according to their different key values.

The output argument Grouped is bound to a list of KeyVal-SubList pairs,
where KeyVal is the value of the Key'th argument that all the structures
in SubList have in common.

### Modes and Determinism

- group_with_key(+, +, -) is det

### Exceptions

*(4) instantiation fault *
- Arguments are insufficiently instantiated
*(5) type error *
- Some argument or its components are of the wrong type
*(6) out of range *
- Some structure does not have a Key'th argument

## Examples

?- group_with_key(1, [f(a,1), f(a,2), f(b,2), f(c,2), f(c,5)], Groups).
Groups = [a - [f(a,1), f(a,2)], b - [f(b,2)], c - [f(c,2),f(c,5)]]
Yes (0.00s cpu)
?- group_with_key(2, [f(a,1), f(a,2), f(b,2), f(c,2), f(c,5)], Groups).
Groups = [1 - [f(a,1)], 2 - [f(a,2),f(b,2),f(c,2)], 5 - [f(c,5)]]
Yes (0.00s cpu)

## See Also

group_by_key / 3, same_key_prefix / 5, sort / 4, merge / 5