
group_with_key(+Key, +Structs, -Grouped)

   Partition a list into sublists by key

Arguments
   Key                 Key argument position (positive integer, or list of those)
   Structs             List of structures
   Grouped             Variable, or list of KeyVal-SubList structures

Type
   library(lists_of_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 --- Arguments are insufficiently instantiated
     5 --- Some argument or its components are of the wrong type
     6 --- 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, group_values_with_key / 4, same_key_prefix / 5, sort / 4, merge / 5
