Class IteratorUtil

java.lang.Object
cloud.opencode.base.collections.IteratorUtil
public final class IteratorUtil extends Object
IteratorUtil - Iterator Utility Class IteratorUtil - 迭代器工具类

Provides comprehensive operations for Iterator including creation, concatenation, filtering, transformation, and conversion.

提供全面的迭代器操作，包括创建、连接、过滤、转换和转换。

Features | 主要功能:

  • Factory methods for iterators - 迭代器工厂方法
  • Concatenation and partitioning - 连接和分区
  • Filtering and transformation - 过滤和转换
  • PeekingIterator support - PeekingIterator 支持

Usage Examples | 使用示例:

// Create empty iterator - 创建空迭代器
Iterator<String> empty = IteratorUtil.emptyIterator();

// Create singleton iterator - 创建单元素迭代器
Iterator<String> single = IteratorUtil.singletonIterator("hello");

// Create peeking iterator - 创建可查看迭代器
PeekingIterator<String> peeking = IteratorUtil.peekingIterator(list.iterator());

// Filter iterator - 过滤迭代器
Iterator<String> filtered = IteratorUtil.filter(iterator, s -> s.length() > 5);

Performance | 性能特性:

  • Most operations are lazy - 大多数操作是惰性的
  • No additional memory allocation for transformations - 转换不需要额外内存分配

Security | 安全性:

  • Thread-safe: No - 线程安全: 否
  • Null-safe: Yes - 空值安全: 是
Since:
JDK 25, opencode-base-collections V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • emptyIterator

      public static <E> Iterator<E> emptyIterator()
      Returns an empty iterator 空迭代器
      Type Parameters:
      E - element type | 元素类型
      Returns:
      empty iterator | 空迭代器

    • singletonIterator

      public static <E> Iterator<E> singletonIterator(E value)
      Returns a singleton iterator 单元素迭代器
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      value - the single value | 单个值
      Returns:
      singleton iterator | 单元素迭代器

    • unmodifiableIterator

      public static <E> Iterator<E> unmodifiableIterator(Iterator<? extends E> iterator)
      Returns an unmodifiable iterator 不可变迭代器
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterator - the iterator | 迭代器
      Returns:
      unmodifiable iterator | 不可变迭代器

    • concat

      @SafeVarargs public static <E> Iterator<E> concat(Iterator<? extends E>... inputs)
      Concatenate multiple iterators 连接多个迭代器
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      inputs - iterators to concatenate | 要连接的迭代器
      Returns:
      concatenated iterator | 连接后的迭代器

    • partition

      public static <E> Iterator<List<E>> partition(Iterator<E> iterator, int size)
      Partition iterator into chunks 分区
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterator - the iterator | 迭代器
      size - chunk size | 分区大小
      Returns:
      iterator of chunks | 分区迭代器

    • filter

      public static <E> Iterator<E> filter(Iterator<E> unfiltered, Predicate<? super E> predicate)
      Filter iterator 过滤
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      unfiltered - the unfiltered iterator | 未过滤的迭代器
      predicate - the predicate | 谓词
      Returns:
      filtered iterator | 过滤后的迭代器

    • transform

      public static <F,T> Iterator<T> transform(Iterator<F> fromIterator, Function<? super F, ? extends T> function)
      Transform iterator 转换
      Type Parameters:
      F - from type | 源类型
      T - to type | 目标类型
      Parameters:
      fromIterator - the source iterator | 源迭代器
      function - the transform function | 转换函数
      Returns:
      transformed iterator | 转换后的迭代器

    • tryFind

      public static <E> Optional<E> tryFind(Iterator<E> iterator, Predicate<? super E> predicate)
      Try to find the first matching element 查找
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterator - the iterator | 迭代器
      predicate - the predicate | 谓词
      Returns:
      optional containing the first match | 包含第一个匹配的 Optional

    • get

      public static <E> E get(Iterator<E> iterator, int position)
      Get element at position 按索引获取
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterator - the iterator | 迭代器
      position - the position | 位置
      Returns:
      element at position | 指定位置的元素
      Throws:
      IndexOutOfBoundsException - if position is out of bounds | 如果位置越界

    • getNext

      public static <E> E getNext(Iterator<? extends E> iterator, E defaultValue)
      Get next element or default 获取下一个元素（带默认值）
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterator - the iterator | 迭代器
      defaultValue - default value | 默认值
      Returns:
      next element or default | 下一个元素或默认值

    • toArray

      public static <E> E[] toArray(Iterator<? extends E> iterator, Class<E> type)
      Convert to array 转为数组
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterator - the iterator | 迭代器
      type - the element type class | 元素类型类
      Returns:
      array | 数组

    • addAll

      public static <E> boolean addAll(Collection<E> addTo, Iterator<? extends E> iterator)
      Add all elements to a collection 添加到集合
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      addTo - the target collection | 目标集合
      iterator - the iterator | 迭代器
      Returns:
      true if collection was modified | 如果集合被修改则返回 true

    • size

      public static int size(Iterator<?> iterator)
      Get the size (consumes iterator) 计算大小（消耗迭代器）
      Parameters:
      iterator - the iterator | 迭代器
      Returns:
      size | 大小

    • contains

      public static boolean contains(Iterator<?> iterator, Object element)
      Check if iterator contains an element 检查是否包含
      Parameters:
      iterator - the iterator | 迭代器
      element - the element | 元素
      Returns:
      true if contains | 如果包含则返回 true

    • removeAll

      public static <E> boolean removeAll(Iterator<E> removeFrom, Collection<?> elementsToRemove)
      Remove all matching elements 移除所有匹配元素
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      removeFrom - the source iterator | 源迭代器
      elementsToRemove - the elements to remove | 要移除的元素
      Returns:
      true if any elements were removed | 如果有元素被移除则返回 true

    • elementsEqual

      public static boolean elementsEqual(Iterator<?> iterator1, Iterator<?> iterator2)
      Check if two iterators have equal elements 检查元素相等
      Parameters:
      iterator1 - first iterator | 第一个迭代器
      iterator2 - second iterator | 第二个迭代器
      Returns:
      true if equal | 如果相等则返回 true

    • toString

      public static String toString(Iterator<?> iterator)
      Convert to string representation 转为字符串
      Parameters:
      iterator - the iterator | 迭代器
      Returns:
      string representation | 字符串表示

    • peekingIterator

      public static <E> PeekingIterator<E> peekingIterator(Iterator<? extends E> iterator)
      Create a peeking iterator Peek 迭代器（可查看下一个元素）
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterator - the iterator | 迭代器
      Returns:
      peeking iterator | 可查看迭代器

    • advance

      public static int advance(Iterator<?> iterator, int numberToAdvance)
      Advance iterator by n positions 消耗并丢弃 N 个元素
      Parameters:
      iterator - the iterator | 迭代器
      numberToAdvance - the number to advance | 前进数量
      Returns:
      actual number advanced | 实际前进数量

    • limit

      public static <E> Iterator<E> limit(Iterator<E> iterator, int limitSize)
      Limit the number of elements 限制数量
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterator - the iterator | 迭代器
      limitSize - the limit | 限制数量
      Returns:
      limited iterator | 限制后的迭代器

    • cycle

      public static <E> Iterator<E> cycle(Iterable<E> iterable)
      Cycle through the iterable 循环迭代
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterable - the iterable | 可迭代对象
      Returns:
      cycling iterator | 循环的迭代器