Class Sequence<T>

java.lang.Object
cloud.opencode.base.functional.monad.Sequence<T>
Type Parameters:
T - element type - 元素类型

Security | 安全性:

  • Thread-safe: Yes (immutable record) - 线程安全: 是（不可变记录）
  • Null-safe: Yes (validates inputs) - 空值安全: 是（验证输入）
All Implemented Interfaces:
Iterable<T>
public final class Sequence<T> extends Object implements Iterable<T>
Sequence - Lazy evaluated sequence Sequence - 惰性求值序列

A lazy sequence that computes elements only when needed. Unlike Stream, Sequence can be traversed multiple times. Similar to Kotlin's Sequence or Scala's LazyList.

一个只在需要时计算元素的惰性序列。与 Stream 不同，Sequence 可以多次遍历。 类似于 Kotlin 的 Sequence 或 Scala 的 LazyList。

Features | 主要功能:

  • Lazy evaluation - 惰性求值
  • Reusable (can traverse multiple times) - 可重用（可多次遍历）
  • Memory efficient (no intermediate collections) - 内存高效（无中间集合）
  • Short-circuit operations - 短路操作
  • Infinite sequences support - 支持无限序列

Usage Examples | 使用示例:

// Create from elements
Sequence<Integer> seq = Sequence.of(1, 2, 3, 4, 5);

// Lazy operations - nothing computed yet
Sequence<Integer> result = seq
    .filter(x -> x > 2)
    .map(x -> x * 2)
    .take(2);

// Computed only when consuming
List<Integer> list = result.toList();  // [6, 8]

// Can be traversed again
int sum = result.fold(0, Integer::sum);  // 14

// Infinite sequence
Sequence<Integer> naturals = Sequence.iterate(1, n -> n + 1);
List<Integer> first10 = naturals.take(10).toList();

// Generate sequence
Sequence<Double> randoms = Sequence.generate(Math::random);

Comparison with Stream | 与 Stream 对比:

  • Stream: single-use, parallel support - 一次性使用，支持并行
  • Sequence: reusable, sequential only - 可重用，仅顺序执行
Since:
JDK 25, opencode-base-functional V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • empty

      public static <T> Sequence<T> empty()
      Create an empty sequence. 创建空序列。
      Type Parameters:
      T - element type - 元素类型
      Returns:
      empty sequence - 空序列

    • of

      @SafeVarargs public static <T> Sequence<T> of(T... elements)
      Create a sequence from elements. 从元素创建序列。
      Type Parameters:
      T - element type - 元素类型
      Parameters:
      elements - the elements - 元素
      Returns:
      new sequence - 新序列

    • from

      public static <T> Sequence<T> from(Iterable<T> iterable)
      Create a sequence from iterable. 从可迭代对象创建序列。
      Type Parameters:
      T - element type - 元素类型
      Parameters:
      iterable - the iterable - 可迭代对象
      Returns:
      new sequence - 新序列

    • fromStream

      public static <T> Sequence<T> fromStream(Stream<T> stream)
      Create a sequence from stream (single-use). 从流创建序列（一次性使用）。
      Type Parameters:
      T - element type - 元素类型
      Parameters:
      stream - the stream - 流
      Returns:
      new sequence - 新序列

    • iterate

      public static <T> Sequence<T> iterate(T seed, UnaryOperator<T> f)
      Create an infinite sequence by repeatedly applying a function. 通过重复应用函数创建无限序列。
      Type Parameters:
      T - element type - 元素类型
      Parameters:
      seed - initial value - 初始值
      f - function to generate next - 生成下一个的函数
      Returns:
      infinite sequence - 无限序列

    • generate

      public static <T> Sequence<T> generate(Supplier<T> supplier)
      Create an infinite sequence from a supplier. 从供应商创建无限序列。
      Type Parameters:
      T - element type - 元素类型
      Parameters:
      supplier - value supplier - 值供应商
      Returns:
      infinite sequence - 无限序列

    • range

      public static Sequence<Integer> range(int start, int end)
      Create a sequence of integers from start (inclusive) to end (exclusive). 创建从 start（包含）到 end（不包含）的整数序列。
      Parameters:
      start - start value (inclusive) - 起始值（包含）
      end - end value (exclusive) - 结束值（不包含）
      Returns:
      integer sequence - 整数序列

    • rangeClosed

      public static Sequence<Integer> rangeClosed(int start, int end)
      Create a sequence of integers from start (inclusive) to end (inclusive). 创建从 start（包含）到 end（包含）的整数序列。
      Parameters:
      start - start value (inclusive) - 起始值（包含）
      end - end value (inclusive) - 结束值（包含）
      Returns:
      integer sequence - 整数序列

    • map

      public <R> Sequence<R> map(Function<? super T, ? extends R> mapper)
      Map each element to a new value. 将每个元素映射为新值。
      Type Parameters:
      R - result type - 结果类型
      Parameters:
      mapper - mapping function - 映射函数
      Returns:
      mapped sequence - 映射后的序列

    • flatMap

      public <R> Sequence<R> flatMap(Function<? super T, ? extends Sequence<R>> mapper)
      Map each element to a sequence and flatten. 将每个元素映射为序列并展平。
      Type Parameters:
      R - result type - 结果类型
      Parameters:
      mapper - mapping function - 映射函数
      Returns:
      flattened sequence - 展平后的序列

    • filter

      public Sequence<T> filter(Predicate<? super T> predicate)
      Filter elements matching the predicate. 过滤匹配谓词的元素。
      Parameters:
      predicate - filter predicate - 过滤谓词
      Returns:
      filtered sequence - 过滤后的序列

    • filterNot

      public Sequence<T> filterNot(Predicate<? super T> predicate)
      Filter elements not matching the predicate. 过滤不匹配谓词的元素。
      Parameters:
      predicate - filter predicate - 过滤谓词
      Returns:
      filtered sequence - 过滤后的序列

    • take

      public Sequence<T> take(int n)
      Take only the first n elements. 只取前 n 个元素。
      Parameters:
      n - number to take - 要取的数量
      Returns:
      truncated sequence - 截断后的序列

    • takeWhile

      public Sequence<T> takeWhile(Predicate<? super T> predicate)
      Take elements while predicate is true. 取元素直到谓词为假。
      Parameters:
      predicate - the predicate - 谓词
      Returns:
      truncated sequence - 截断后的序列

    • drop

      public Sequence<T> drop(int n)
      Drop the first n elements. 丢弃前 n 个元素。
      Parameters:
      n - number to drop - 要丢弃的数量
      Returns:
      remaining sequence - 剩余序列

    • dropWhile

      public Sequence<T> dropWhile(Predicate<? super T> predicate)
      Drop elements while predicate is true. 丢弃元素直到谓词为假。
      Parameters:
      predicate - the predicate - 谓词
      Returns:
      remaining sequence - 剩余序列

    • distinct

      public Sequence<T> distinct()
      Remove duplicate elements. 移除重复元素。
      Returns:
      distinct sequence - 去重后的序列

    • sorted

      public Sequence<T> sorted()
      Sort the sequence by natural order. 按自然顺序排序序列。
      Returns:
      sorted sequence - 排序后的序列

    • sorted

      public Sequence<T> sorted(Comparator<? super T> comparator)
      Sort the sequence by comparator. 按比较器排序序列。
      Parameters:
      comparator - the comparator - 比较器
      Returns:
      sorted sequence - 排序后的序列

    • zip

      public <U,R> Sequence<R> zip(Sequence<U> other, BiFunction<? super T, ? super U, ? extends R> zipper)
      Zip with another sequence. 与另一个序列合并。
      Type Parameters:
      U - other element type - 另一个元素类型
      R - result type - 结果类型
      Parameters:
      other - other sequence - 另一个序列
      zipper - combining function - 组合函数
      Returns:
      zipped sequence - 合并后的序列

    • zipWithIndex

      public Sequence<Sequence.IndexedValue<T>> zipWithIndex()
      Zip with index. 与索引合并。
      Returns:
      sequence of indexed elements - 带索引元素的序列

    • fold

      public <R> R fold(R initial, BiFunction<? super R, ? super T, ? extends R> folder)
      Fold elements from left with initial value. 从左侧使用初始值折叠元素。
      Type Parameters:
      R - result type - 结果类型
      Parameters:
      initial - initial value - 初始值
      folder - folding function - 折叠函数
      Returns:
      folded result - 折叠结果

    • reduce

      public Optional<T> reduce(BinaryOperator<T> reducer)
      Reduce elements (no initial value). 归约元素（无初始值）。
      Parameters:
      reducer - reducing function - 归约函数
      Returns:
      optional result - 可选结果

    • toList

      public List<T> toList()
      Collect to a list. 收集为列表。
      Returns:
      list of elements - 元素列表

    • toSet

      public Set<T> toSet()
      Collect to a set. 收集为集合。
      Returns:
      set of elements - 元素集合

    • collect

      public <R,A> R collect(Collector<? super T, A, R> collector)
      Collect using a collector. 使用收集器收集。
      Type Parameters:
      R - result type - 结果类型
      A - accumulator type - 累加器类型
      Parameters:
      collector - the collector - 收集器
      Returns:
      collected result - 收集结果

    • find

      public Optional<T> find(Predicate<? super T> predicate)
      Find first element matching predicate. 查找第一个匹配谓词的元素。
      Parameters:
      predicate - the predicate - 谓词
      Returns:
      optional first match - 可选的第一个匹配

    • first

      public Optional<T> first()
      Find first element. 查找第一个元素。
      Returns:
      optional first element - 可选的第一个元素

    • last

      public Optional<T> last()
      Find last element. 查找最后一个元素。
      Returns:
      optional last element - 可选的最后一个元素

    • any

      public boolean any(Predicate<? super T> predicate)
      Check if any element matches predicate. 检查是否有任何元素匹配谓词。
      Parameters:
      predicate - the predicate - 谓词
      Returns:
      true if any match - 如果有匹配返回 true

    • all

      public boolean all(Predicate<? super T> predicate)
      Check if all elements match predicate. 检查是否所有元素都匹配谓词。
      Parameters:
      predicate - the predicate - 谓词
      Returns:
      true if all match - 如果全部匹配返回 true

    • none

      public boolean none(Predicate<? super T> predicate)
      Check if no elements match predicate. 检查是否没有元素匹配谓词。
      Parameters:
      predicate - the predicate - 谓词
      Returns:
      true if none match - 如果全不匹配返回 true

    • count

      public long count()
      Count elements. 计数元素。
      Returns:
      element count - 元素数量

    • forEach

      public void forEach(Consumer<? super T> action)
      Perform action on each element. 对每个元素执行操作。
      Specified by:
      forEach in interface Iterable<T>
      Parameters:
      action - the action - 操作

    • toStream

      public Stream<T> toStream()
      Convert to stream. 转换为流。
      Returns:
      stream of elements - 元素流

    • iterator

      public Iterator<T> iterator()
      Specified by:
      iterator in interface Iterable<T>