java.lang.Object

cloud.opencode.base.collections.transform.GroupingUtil

public final class GroupingUtil extends Object

GroupingUtil - Collection Grouping Utilities GroupingUtil - 集合分组工具

Provides utilities for grouping collection elements.

提供分组集合元素的工具。

Features | 主要功能:

Group by key function - 按键函数分组
Multi-level grouping - 多级分组
Index by key - 按键索引
Unique index - 唯一索引

Usage Examples | 使用示例:

List<Person> people = ...;

// Group by city - 按城市分组
Map<String, List<Person>> byCity = GroupingUtil.groupBy(people, Person::getCity);

// Group by multiple keys - 按多个键分组
Map<String, Map<Integer, List<Person>>> byCityAndAge =
    GroupingUtil.groupBy(people, Person::getCity, Person::getAge);

// Index by ID - 按 ID 索引
Map<Long, Person> byId = GroupingUtil.indexBy(people, Person::getId);

Security | 安全性:

Thread-safe: Yes (stateless utility) - 是（无状态工具）
Null-safe: No (input must not be null) - 否（输入不能为null）

Performance | 性能特性:

Time complexity: O(n) for groupBy, indexBy, and countBy where n is the number of elements - 时间复杂度: groupBy、indexBy、countBy 均为 O(n)，n为元素数量
Space complexity: O(n) for the resulting map - 空间复杂度: O(n)，存储结果映射

Since:

JDK 25, opencode-base-collections V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static <T> long

count(Iterable<T> items, Predicate<? super T> predicate)

Count items matching predicate.

static <T,K> Map<K,Long>

countBy(Iterable<T> items, Function<? super T, ? extends K> keyFunction)

Count items by key.

static <T> Map<T,Long>

frequency(Iterable<T> items)

Get frequency map of elements.

static <T,K> Map<K,List<T>>

groupBy(Iterable<T> items, Function<? super T, ? extends K> keyFunction)

Group items by a key function.

static <T,K,V> Map<K,List<V>>

groupBy(Iterable<T> items, Function<? super T, ? extends K> keyFunction, Function<? super T, ? extends V> valueFunction)

Group items by a key function with value transformation.

static <T,K1,K2> Map<K1, Map<K2,List<T>>>

groupByNested(Iterable<T> items, Function<? super T, ? extends K1> keyFunction1, Function<? super T, ? extends K2> keyFunction2)

Group items by two levels of keys.

static <T, K extends Comparable<? super K>> Map<K,List<T>>

groupBySorted(Iterable<T> items, Function<? super T, ? extends K> keyFunction)

Group items by key with sorted keys.

static <T,K> Map<K,List<T>>

groupBySorted(Iterable<T> items, Function<? super T, ? extends K> keyFunction, Comparator<? super K> comparator)

Group items by key with custom sorted keys.

static <T,K> Map<K,Set<T>>

groupByToSet(Iterable<T> items, Function<? super T, ? extends K> keyFunction)

Group items into sets by key.

static <T,K> Map<K,T>

indexBy(Iterable<T> items, Function<? super T, ? extends K> keyFunction)

Index items by a unique key.

static <T,K> Map<K,T>

indexByFirst(Iterable<T> items, Function<? super T, ? extends K> keyFunction)

Index items by a key, keeping the first value for duplicates.

static <T,K> Map<K,T>

indexByLast(Iterable<T> items, Function<? super T, ? extends K> keyFunction)

Index items by a key, keeping the last value for duplicates.

static <T> T

leastFrequent(Iterable<T> items)

Get least frequent element.

static <T> T

mostFrequent(Iterable<T> items)

Get most frequent element.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- groupBy
  
  public static <T,K> Map<K,List<T>> groupBy(Iterable<T> items, Function<? super T, ? extends K> keyFunction)
  
  Group items by a key function. 按键函数分组项目。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K - key type | 键类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction - the key function | 键函数
  
  Returns:
  
  map of groups | 组映射
- groupBy
  
  public static <T,K,V> Map<K,List<V>> groupBy(Iterable<T> items, Function<? super T, ? extends K> keyFunction, Function<? super T, ? extends V> valueFunction)
  
  Group items by a key function with value transformation. 按键函数分组项目并转换值。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K - key type | 键类型
  
  V - value type | 值类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction - the key function | 键函数
  
  valueFunction - the value function | 值函数
  
  Returns:
  
  map of groups | 组映射
- groupByNested
  
  public static <T,K1,K2> Map<K1, Map<K2,List<T>>> groupByNested(Iterable<T> items, Function<? super T, ? extends K1> keyFunction1, Function<? super T, ? extends K2> keyFunction2)
  
  Group items by two levels of keys. 按两级键分组项目。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K1 - first key type | 第一个键类型
  
  K2 - second key type | 第二个键类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction1 - the first key function | 第一个键函数
  
  keyFunction2 - the second key function | 第二个键函数
  
  Returns:
  
  nested map of groups | 嵌套的组映射
- indexBy
  
  public static <T,K> Map<K,T> indexBy(Iterable<T> items, Function<? super T, ? extends K> keyFunction)
  
  Index items by a unique key. 按唯一键索引项目。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K - key type | 键类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction - the key function | 键函数
  
  Returns:
  
  map of items by key | 按键的项目映射
  
  Throws:
  
  IllegalStateException - if duplicate keys exist | 如果存在重复键则抛出异常
- indexByFirst
  
  public static <T,K> Map<K,T> indexByFirst(Iterable<T> items, Function<? super T, ? extends K> keyFunction)
  
  Index items by a key, keeping the first value for duplicates. 按键索引项目，重复时保留第一个值。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K - key type | 键类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction - the key function | 键函数
  
  Returns:
  
  map of items by key | 按键的项目映射
- indexByLast
  
  public static <T,K> Map<K,T> indexByLast(Iterable<T> items, Function<? super T, ? extends K> keyFunction)
  
  Index items by a key, keeping the last value for duplicates. 按键索引项目，重复时保留最后一个值。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K - key type | 键类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction - the key function | 键函数
  
  Returns:
  
  map of items by key | 按键的项目映射
- countBy
  
  public static <T,K> Map<K,Long> countBy(Iterable<T> items, Function<? super T, ? extends K> keyFunction)
  
  Count items by key. 按键计数项目。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K - key type | 键类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction - the key function | 键函数
  
  Returns:
  
  map of counts | 计数映射
- count
  
  public static <T> long count(Iterable<T> items, Predicate<? super T> predicate)
  
  Count items matching predicate. 计数匹配谓词的项目。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  Parameters:
  
  items - the items | 项目
  
  predicate - the predicate | 谓词
  
  Returns:
  
  count | 计数
- frequency
  
  public static <T> Map<T,Long> frequency(Iterable<T> items)
  
  Get frequency map of elements. 获取元素的频率映射。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  Parameters:
  
  items - the items | 项目
  
  Returns:
  
  frequency map | 频率映射
- mostFrequent
  
  public static <T> T mostFrequent(Iterable<T> items)
  
  Get most frequent element. 获取最频繁的元素。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  Parameters:
  
  items - the items | 项目
  
  Returns:
  
  most frequent element or null | 最频繁的元素或 null
- leastFrequent
  
  public static <T> T leastFrequent(Iterable<T> items)
  
  Get least frequent element. 获取最不频繁的元素。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  Parameters:
  
  items - the items | 项目
  
  Returns:
  
  least frequent element or null | 最不频繁的元素或 null
- groupByToSet
  
  public static <T,K> Map<K,Set<T>> groupByToSet(Iterable<T> items, Function<? super T, ? extends K> keyFunction)
  
  Group items into sets by key. 按键将项目分组为集合。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K - key type | 键类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction - the key function | 键函数
  
  Returns:
  
  map of sets | 集合映射
- groupBySorted
  
  public static <T, K extends Comparable<? super K>> Map<K,List<T>> groupBySorted(Iterable<T> items, Function<? super T, ? extends K> keyFunction)
  
  Group items by key with sorted keys. 按键分组项目并排序键。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K - key type | 键类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction - the key function | 键函数
  
  Returns:
  
  sorted map of groups | 排序的组映射
- groupBySorted
  
  public static <T,K> Map<K,List<T>> groupBySorted(Iterable<T> items, Function<? super T, ? extends K> keyFunction, Comparator<? super K> comparator)
  
  Group items by key with custom sorted keys. 按键分组项目并使用自定义排序。
  
  Type Parameters:
  
  T - element type | 元素类型
  
  K - key type | 键类型
  
  Parameters:
  
  items - the items | 项目
  
  keyFunction - the key function | 键函数
  
  comparator - the comparator | 比较器
  
  Returns:
  
  sorted map of groups | 排序的组映射

Class GroupingUtil

Method Summary

Methods inherited from class Object

Method Details

groupBy

groupBy

groupByNested

indexBy

indexByFirst

indexByLast

countBy

count

frequency

mostFrequent

leastFrequent

groupByToSet

groupBySorted

groupBySorted