Interface PersistentList<E>

Type Parameters:
E - element type | 元素类型
All Known Implementing Classes:
PersistentList.Cons, PersistentList.Nil
public sealed interface PersistentList<E> permits PersistentList.Nil<E>, PersistentList.Cons<E>
PersistentList - Persistent immutable linked list with structural sharing PersistentList - 基于结构共享的持久化不可变链表

A persistent list based on cons-cell linked list. All mutation operations return a new list while sharing structure with the original, making it ideal for functional programming and concurrent access.

基于 cons-cell 链表的持久化列表。所有变更操作都返回一个新列表，同时与原列表 共享结构，非常适合函数式编程和并发访问。

Features | 主要功能:

  • Structural sharing - 结构共享
  • Immutable - 不可变
  • O(1) prepend and tail - O(1) 前插和取尾
  • Functional operations (map, filter) - 函数式操作（映射、过滤）

Usage Examples | 使用示例:

// Create list - 创建列表
PersistentList<String> list = PersistentList.of("a", "b", "c");

// Prepend element (O(1)) - 前插元素 (O(1))
PersistentList<String> list2 = list.prepend("z"); // ["z", "a", "b", "c"]
// Original list is unchanged - 原列表不变
// list is still ["a", "b", "c"]

// Tail (O(1)) - 获取尾部 (O(1))
PersistentList<String> tail = list.tail(); // ["b", "c"]

// Map and filter - 映射和过滤
PersistentList<Integer> lengths = list.map(String::length);
PersistentList<String> filtered = list.filter(s -> s.compareTo("b") >= 0);

Performance | 性能特性:

  • prepend: O(1) - prepend: O(1)
  • head / tail: O(1) - head / tail: O(1)
  • append / reversed / map / filter: O(n) - append / reversed / map / filter: O(n)
  • contains / size: O(n) / O(1) - contains / size: O(n) / O(1)

Security | 安全性:

  • Thread-safe: Yes (immutable) - 线程安全: 是（不可变）
Since:
JDK 25, opencode-base-collections V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    PersistentList.Cons<E>
    Cons - A non-empty persistent list node (head + tail).
    static final record 
    PersistentList.Nil<E>
    Nil - The empty persistent list.

  • Method Summary

    Modifier and Type
    Method
    Description
    PersistentList<E>
    append(E element)
    Append an element to the end of this list (O(n)).
    boolean
    contains(Object element)
    Check if this list contains the given element.
    static <E> PersistentList<E>
    empty()
    Return an empty persistent list.
    PersistentList<E>
    filter(Predicate<? super E> predicate)
    Filter elements by a predicate and return a new list (O(n)).
    static <E> PersistentList<E>
    from(Iterable<E> iterable)
    Create a persistent list from an iterable.
    E
    head()
    Return the head (first element) of this list (O(1)).
    boolean
    isEmpty()
    Check if this list is empty.
    Iterator<E>
    iterator()
    Return an iterator over the elements.
    <R> PersistentList<R>
    map(Function<? super E, ? extends R> fn)
    Apply a function to each element and return a new list (O(n)).
    static <E> PersistentList<E>
    of(E... elements)
    Create a persistent list from the given elements.
    PersistentList<E>
    prepend(E element)
    Prepend an element to the front of this list (O(1)).
    PersistentList<E>
    reversed()
    Return a reversed copy of this list (O(n)).
    int
    size()
    Return the number of elements in this list.
    Stream<E>
    stream()
    Return a sequential stream over the elements.
    PersistentList<E>
    tail()
    Return the tail of this list (all elements except the first) (O(1)).
    List<E>
    toList()
    Convert this persistent list to a JDK List.

  • Method Details

    • empty

      static <E> PersistentList<E> empty()
      Return an empty persistent list. 返回一个空的持久化列表。
      Type Parameters:
      E - element type | 元素类型
      Returns:
      empty persistent list | 空的持久化列表

    • of

      @SafeVarargs static <E> PersistentList<E> of(E... elements)
      Create a persistent list from the given elements. 从给定的元素创建持久化列表。

      Elements are stored in the order provided.

      元素按提供的顺序存储。

      Type Parameters:
      E - element type | 元素类型
      Parameters:
      elements - the elements | 元素
      Returns:
      persistent list containing the elements | 包含元素的持久化列表

    • from

      static <E> PersistentList<E> from(Iterable<E> iterable)
      Create a persistent list from an iterable. 从可迭代对象创建持久化列表。
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      iterable - the iterable | 可迭代对象
      Returns:
      persistent list containing the elements | 包含元素的持久化列表

    • prepend

      PersistentList<E> prepend(E element)
      Prepend an element to the front of this list (O(1)). 在列表前端插入一个元素 (O(1))。
      Parameters:
      element - the element to prepend | 要前插的元素
      Returns:
      a new list with the element prepended | 前插元素后的新列表

    • append

      PersistentList<E> append(E element)
      Append an element to the end of this list (O(n)). 在列表末尾追加一个元素 (O(n))。
      Parameters:
      element - the element to append | 要追加的元素
      Returns:
      a new list with the element appended | 追加元素后的新列表

    • tail

      PersistentList<E> tail()
      Return the tail of this list (all elements except the first) (O(1)). 返回列表的尾部（除第一个元素外的所有元素）(O(1))。
      Returns:
      the tail of the list | 列表的尾部
      Throws:
      NoSuchElementException - if the list is empty | 如果列表为空

    • head

      E head()
      Return the head (first element) of this list (O(1)). 返回列表的头部（第一个元素）(O(1))。
      Returns:
      the head element | 头部元素
      Throws:
      NoSuchElementException - if the list is empty | 如果列表为空

    • size

      int size()
      Return the number of elements in this list. 返回列表中的元素数量。
      Returns:
      the size | 大小

    • isEmpty

      boolean isEmpty()
      Check if this list is empty. 检查列表是否为空。
      Returns:
      true if the list is empty | 如果列表为空则返回 true

    • contains

      boolean contains(Object element)
      Check if this list contains the given element. 检查列表是否包含给定元素。
      Parameters:
      element - the element to search for | 要搜索的元素
      Returns:
      true if the element is found | 如果找到元素则返回 true

    • reversed

      PersistentList<E> reversed()
      Return a reversed copy of this list (O(n)). 返回此列表的反转副本 (O(n))。
      Returns:
      reversed list | 反转后的列表

    • map

      <R> PersistentList<R> map(Function<? super E, ? extends R> fn)
      Apply a function to each element and return a new list (O(n)). 对每个元素应用函数并返回新列表 (O(n))。
      Type Parameters:
      R - result element type | 结果元素类型
      Parameters:
      fn - the mapping function | 映射函数
      Returns:
      a new list with mapped elements | 包含映射元素的新列表

    • filter

      PersistentList<E> filter(Predicate<? super E> predicate)
      Filter elements by a predicate and return a new list (O(n)). 按谓词过滤元素并返回新列表 (O(n))。
      Parameters:
      predicate - the filter predicate | 过滤谓词
      Returns:
      a new list with only matching elements | 仅包含匹配元素的新列表

    • toList

      List<E> toList()
      Convert this persistent list to a JDK List. 将此持久化列表转换为 JDK List。
      Returns:
      an unmodifiable list containing all elements | 包含所有元素的不可修改列表

    • stream

      Stream<E> stream()
      Return a sequential stream over the elements. 返回元素上的顺序流。
      Returns:
      a stream | 流

    • iterator

      Iterator<E> iterator()
      Return an iterator over the elements. 返回元素上的迭代器。
      Returns:
      an iterator | 迭代器