GroupWith

GroupWith is a higher-order data transformation that partitions a collection by a key produced from each element using a user-supplied function. Given a function f and a collection xs, groupWith f xs returns a mapping from keys k to the list of elements x whose f x equals k. In many libraries it is described as a bucketing utility and may return a dictionary-like map or a list of key–value pairs.

Semantically, groupWith differs from grouping by runs of equal keys in some languages. It groups all elements by the key returned by f, regardless of their positions in the input. The keys are determined by f, and most implementations preserve the original order of elements within each bucket. The ordering of the keys themselves depends on the implementation and data structure used (for example, insertion order in an ordered map versus arbitrary order in a hash map).

Examples help illustrate the concept. groupWith parity [1, 2, 3, 4, 5] with parity x = x mod 2 yields a grouping such as {1: [1, 3, 5], 0: [2, 4]}. Another example: groupWith length ["a","bb","ccc","dd"] yields {1: ["a"], 2: ["bb","dd"], 3: ["ccc"]}.

In practice, many languages provide similar functionality under names like groupBy, groupByKey, bucket, or partition. A typical implementation uses a map or dictionary to accumulate elements by their key as the input is traversed. Performance is commonly O(n) on average with hash-based structures, and memory usage grows with the number of distinct keys.