Class ListUtil

java.lang.Object
com.sure.tool.collection.ListUtil

public class ListUtil extends Object
列表工具类,参考 Hutool 的 ListUtil 设计。

English: List-specific helpers such as partitioning, splitting and safe indexing.

Since:
0.1.0
Author:
suretool
  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    average(List<? extends Number> list)
    数值均值(null 元素跳过;空或全 null 返回 0.0)。
    static <T> List<List<T>>
    cartesianProduct(List<? extends List<? extends T>> lists)
    任意维度笛卡尔积(对齐 Guava Lists.cartesianProduct)。
    static <T> List<List<T>>
    chunk(List<T> list, int size)
    均分块:按固定大小切分为多个子列表(与 partition(List, int) 同语义,别名友好)。
    static <T> Set<List<T>>
    combinations(List<T> list, int k)
    k 元素组合(对齐 Guava Sets.combinations 的列表版)。
    static <T> List<T>
    concat(List<? extends T>... lists)
    拼接多个列表(对齐 Guava Iterables.concat,null 列表跳过)。
    static <T> List<T>
    concat(List<? extends T> left, List<? extends T> right)
    拼接两个列表(对齐 Guava Lists.concat)。
    static <T> List<T>
    distinct(List<T> list)
    去重并保持原有顺序(首个出现位置保留)。
    static <T> List<T>
    filter(List<T> list, Predicate<T> predicate)
    过滤:仅保留满足谓词的元素(保序)。
    static <T,R> List<R>
    flatMap(List<T> list, Function<T,List<R>> mapper)
    扁平映射:将每个元素展开为其子列表并依次拼接,内层 null 列表跳过。
    static <T> T
    get(List<T> list, int index)
    越界安全取值:索引越界时返回 null,负数从尾部定位(-1 表示末尾元素)。
    static <T> List<T>
    intersection(List<T> left, List<T> right)
    交集(保序去重):按左列表出现顺序。
    static boolean
    isEmpty(List<?> list)
    列表是否为空。
    static boolean
    isNotEmpty(List<?> list)
    列表是否非空。
    static <T,R> List<R>
    map(List<T> list, Function<T,R> mapper)
    映射:对每个元素应用函数生成新列表。
    static <T extends Comparable<? super T>>
    T
    max(List<T> list)
    自然序最大值(空列表抛 NoSuchElementException)。
    static <T> T
    max(List<T> list, Comparator<? super T> comparator)
    按比较器取最大值(空列表抛 NoSuchElementException)。
    static <T extends Comparable<? super T>>
    T
    min(List<T> list)
    自然序最小值(空列表抛 NoSuchElementException)。
    static <T> T
    min(List<T> list, Comparator<? super T> comparator)
    按比较器取最小值(空列表抛 NoSuchElementException)。
    static <T> List<T>
    move(List<T> list, int from, int to)
    元素移动到新下标(其余元素顺移,与 List.move 语义一致)。
    static <T> List<T>
    page(int pageIndex, int pageSize, List<T> list)
    分页截取:返回第 pageIndex 页(从 0 开始)的 pageSize 条数据。
    static <T> List<List<T>>
    partition(List<T> list, int size)
    列表切分:按固定大小切分为多个子列表。
    static <T> Set<List<T>>
    permutations(List<T> list)
    全排列(对齐 Guava Collections2.permutations)。
    static <T> List<T>
    reverse(List<T> list)
    反转列表(原地)。
    static <T> List<T>
    reverseNew(List<T> list)
    反转列表(返回新列表,不影响原列表)。
    static <T> List<T>
    sample(List<T> list, int count)
    随机取样:返回不重复的 count 个元素(保原顺序的随机子集);count 不小于列表大小时返回全量洗牌副本。
    static <T> List<T>
    shuffle(List<T> list, Random random)
    原地洗牌(Fisher-Yates,可注入随机源)。
    static <T> List<T>
    shuffleCopy(List<T> list, Random random)
    洗牌副本:返回洗牌后的新列表,原列表不变。
    static <T> List<T>
    sub(List<T> list, int fromIndex, int toIndex)
    截取子列表。
    static <T> List<T>
    subListSafe(List<T> list, int fromIndex, int toIndex)
    越界安全截取:起始与结束下标被钳制到合法范围,起始大于结束时返回空列表。
    static <T> List<T>
    subtract(List<T> left, List<T> right)
    差集(保序去重):左列表中不在右列表的元素。
    static long
    sum(List<? extends Number> list)
    数值求和(null 元素跳过;空或全 null 返回 0)。
    static <T> List<T>
    toList(T... values)
    创建列表。
    static <T> List<T>
    union(List<T> left, List<T> right)
    并集(保序去重):先左后右,右侧重复元素不追加。
    static <T,U> List<List<Object>>
    zip(List<T> left, List<U> right)
    两列表按最短长度配对(zip),返回不可变二元组列表。

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • toList

      @SafeVarargs public static <T> List<T> toList(T... values)
      创建列表。
      Type Parameters:
      T - 元素类型
      Parameters:
      values - 元素
      Returns:
      列表
    • partition

      public static <T> List<List<T>> partition(List<T> list, int size)
      列表切分:按固定大小切分为多个子列表。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表
      size - 每份大小
      Returns:
      切分后的子列表集合
    • page

      public static <T> List<T> page(int pageIndex, int pageSize, List<T> list)
      分页截取:返回第 pageIndex 页(从 0 开始)的 pageSize 条数据。
      Type Parameters:
      T - 元素类型
      Parameters:
      pageIndex - 页码(从 0 开始)
      pageSize - 每页条数
      list - 数据列表
      Returns:
      当页数据
    • sub

      public static <T> List<T> sub(List<T> list, int fromIndex, int toIndex)
      截取子列表。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表
      fromIndex - 起始索引(含)
      toIndex - 结束索引(不含)
      Returns:
      子列表
    • reverse

      public static <T> List<T> reverse(List<T> list)
      反转列表(原地)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表
      Returns:
      反转后的列表
    • reverseNew

      public static <T> List<T> reverseNew(List<T> list)
      反转列表(返回新列表,不影响原列表)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表
      Returns:
      反转后的新列表
    • isEmpty

      public static boolean isEmpty(List<?> list)
      列表是否为空。
      Parameters:
      list - 列表
      Returns:
      是否为空
    • isNotEmpty

      public static boolean isNotEmpty(List<?> list)
      列表是否非空。
      Parameters:
      list - 列表
      Returns:
      是否非空
    • get

      public static <T> T get(List<T> list, int index)
      越界安全取值:索引越界时返回 null,负数从尾部定位(-1 表示末尾元素)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表(null 返回 null)
      index - 下标(支持负数尾部定位)
      Returns:
      对应元素,越界或列表为 null 时返回 null
      Since:
      1.16.0
    • subListSafe

      public static <T> List<T> subListSafe(List<T> list, int fromIndex, int toIndex)
      越界安全截取:起始与结束下标被钳制到合法范围,起始大于结束时返回空列表。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表(null 返回空列表)
      fromIndex - 起始下标(含,可越界)
      toIndex - 结束下标(不含,可越界)
      Returns:
      子列表副本
      Since:
      1.16.0
    • distinct

      public static <T> List<T> distinct(List<T> list)
      去重并保持原有顺序(首个出现位置保留)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表(null 返回空列表)
      Returns:
      去重后的新列表
      Since:
      1.16.0
    • map

      public static <T,R> List<R> map(List<T> list, Function<T,R> mapper)
      映射:对每个元素应用函数生成新列表。
      Type Parameters:
      T - 元素类型
      R - 结果类型
      Parameters:
      list - 列表(null 返回空列表)
      mapper - 映射函数(null 时抛 NullPointerException)
      Returns:
      映射后的新列表
      Since:
      1.16.0
    • filter

      public static <T> List<T> filter(List<T> list, Predicate<T> predicate)
      过滤:仅保留满足谓词的元素(保序)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表(null 返回空列表)
      predicate - 过滤谓词(null 时抛 NullPointerException)
      Returns:
      过滤后的新列表
      Since:
      1.16.0
    • flatMap

      public static <T,R> List<R> flatMap(List<T> list, Function<T,List<R>> mapper)
      扁平映射:将每个元素展开为其子列表并依次拼接,内层 null 列表跳过。
      Type Parameters:
      T - 元素类型
      R - 结果元素类型
      Parameters:
      list - 列表(null 返回空列表)
      mapper - 展开函数(null 时抛 NullPointerException)
      Returns:
      扁平化后的新列表
      Since:
      1.16.0
    • zip

      public static <T,U> List<List<Object>> zip(List<T> left, List<U> right)
      两列表按最短长度配对(zip),返回不可变二元组列表。
      Type Parameters:
      T - 左元素类型
      U - 右元素类型
      Parameters:
      left - 左列表(null 按空处理)
      right - 右列表(null 按空处理)
      Returns:
      配对结果
      Since:
      1.16.0
    • shuffle

      public static <T> List<T> shuffle(List<T> list, Random random)
      原地洗牌(Fisher-Yates,可注入随机源)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表(null 不操作)
      random - 随机源(null 时使用默认)
      Returns:
      洗牌后的同一列表
      Since:
      1.16.0
    • shuffleCopy

      public static <T> List<T> shuffleCopy(List<T> list, Random random)
      洗牌副本:返回洗牌后的新列表,原列表不变。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表(null 返回空列表)
      random - 随机源(null 时使用默认)
      Returns:
      洗牌后的新列表
      Since:
      1.16.0
    • sample

      public static <T> List<T> sample(List<T> list, int count)
      随机取样:返回不重复的 count 个元素(保原顺序的随机子集);count 不小于列表大小时返回全量洗牌副本。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表(null 返回空列表)
      count - 取样个数(<=0 返回空列表)
      Returns:
      取样结果新列表
      Since:
      1.16.0
    • chunk

      public static <T> List<List<T>> chunk(List<T> list, int size)
      均分块:按固定大小切分为多个子列表(与 partition(List, int) 同语义,别名友好)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表(null 返回空)
      size - 每块大小(<=0 抛 IllegalArgumentException)
      Returns:
      分块结果
      Since:
      1.16.0
    • union

      public static <T> List<T> union(List<T> left, List<T> right)
      并集(保序去重):先左后右,右侧重复元素不追加。
      Type Parameters:
      T - 元素类型
      Parameters:
      left - 左列表(null 按空处理)
      right - 右列表(null 按空处理)
      Returns:
      并集新列表
      Since:
      1.16.0
    • intersection

      public static <T> List<T> intersection(List<T> left, List<T> right)
      交集(保序去重):按左列表出现顺序。
      Type Parameters:
      T - 元素类型
      Parameters:
      left - 左列表(null 按空处理)
      right - 右列表(null 按空处理)
      Returns:
      交集新列表
      Since:
      1.16.0
    • subtract

      public static <T> List<T> subtract(List<T> left, List<T> right)
      差集(保序去重):左列表中不在右列表的元素。
      Type Parameters:
      T - 元素类型
      Parameters:
      left - 左列表(null 按空处理)
      right - 右列表(null 按空处理)
      Returns:
      差集新列表
      Since:
      1.16.0
    • min

      public static <T extends Comparable<? super T>> T min(List<T> list)
      自然序最小值(空列表抛 NoSuchElementException)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表
      Returns:
      最小元素
      Since:
      1.16.0
    • max

      public static <T extends Comparable<? super T>> T max(List<T> list)
      自然序最大值(空列表抛 NoSuchElementException)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表
      Returns:
      最大元素
      Since:
      1.16.0
    • min

      public static <T> T min(List<T> list, Comparator<? super T> comparator)
      按比较器取最小值(空列表抛 NoSuchElementException)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表
      comparator - 比较器
      Returns:
      最小元素
      Since:
      1.16.0
    • max

      public static <T> T max(List<T> list, Comparator<? super T> comparator)
      按比较器取最大值(空列表抛 NoSuchElementException)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表
      comparator - 比较器
      Returns:
      最大元素
      Since:
      1.16.0
    • sum

      public static long sum(List<? extends Number> list)
      数值求和(null 元素跳过;空或全 null 返回 0)。
      Parameters:
      list - 数值列表(null 按空处理)
      Returns:
      求和结果
      Since:
      1.16.0
    • average

      public static double average(List<? extends Number> list)
      数值均值(null 元素跳过;空或全 null 返回 0.0)。
      Parameters:
      list - 数值列表(null 按空处理)
      Returns:
      均值
      Since:
      1.16.0
    • move

      public static <T> List<T> move(List<T> list, int from, int to)
      元素移动到新下标(其余元素顺移,与 List.move 语义一致)。
      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表
      from - 原下标(越界抛 IndexOutOfBoundsException)
      to - 目标下标
      Returns:
      操作后的同一列表
      Since:
      1.16.0
    • cartesianProduct

      public static <T> List<List<T>> cartesianProduct(List<? extends List<? extends T>> lists)
      任意维度笛卡尔积(对齐 Guava Lists.cartesianProduct)。

      返回所有维度组合:[[1,2],[a,b]] -> [[1,a],[1,b],[2,a],[2,b]]; 任一维度为空集合时结果为空;输入列表本身为空时结果含一个空组合。

      Type Parameters:
      T - 元素类型
      Parameters:
      lists - 维度集合列表(外层为维度,内层为该维度取值),可为 null
      Returns:
      笛卡尔积列表;null 返回 null
      Since:
      1.19.0
    • permutations

      public static <T> Set<List<T>> permutations(List<T> list)
      全排列(对齐 Guava Collections2.permutations)。

      返回包含原列表在内的所有排列(n! 个,Set 去重同排列)。

      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表,可为 null
      Returns:
      排列集合;null 返回 null
      Since:
      1.19.0
    • combinations

      public static <T> Set<List<T>> combinations(List<T> list, int k)
      k 元素组合(对齐 Guava Sets.combinations 的列表版)。

      combinations([1,2,3], 2) -> [[1,2],[1,3],[2,3]];k=0 返回含空组合; k=n 返回原列表。k 越界(<0 或 >n)抛 IllegalArgumentException。

      Type Parameters:
      T - 元素类型
      Parameters:
      list - 列表,可为 null
      k - 组合大小
      Returns:
      组合列表集合;null 返回 null
      Since:
      1.19.0
    • concat

      public static <T> List<T> concat(List<? extends T> left, List<? extends T> right)
      拼接两个列表(对齐 Guava Lists.concat)。

      返回不可变视图,任一参数为 null 时按空列表处理。

      Type Parameters:
      T - 元素类型
      Parameters:
      left - 左列表,可为 null
      right - 右列表,可为 null
      Returns:
      拼接后的不可变列表
      Since:
      1.19.0
    • concat

      @SafeVarargs public static <T> List<T> concat(List<? extends T>... lists)
      拼接多个列表(对齐 Guava Iterables.concat,null 列表跳过)。
      Type Parameters:
      T - 元素类型
      Parameters:
      lists - 列表数组,可为 null
      Returns:
      拼接后的不可变列表;null 返回空列表
      Since:
      1.19.0