Class PersistentMap<K,V>

java.lang.Object
cloud.opencode.base.collections.immutable.PersistentMap<K,V>
Type Parameters:
K - key type | 键类型
V - value type | 值类型
public final class PersistentMap<K,V> extends Object
PersistentMap - Persistent immutable map based on HAMT (Hash Array Mapped Trie) PersistentMap - 基于 HAMT（哈希数组映射字典树）的持久化不可变映射

Uses structural sharing for efficient immutable updates. put/remove operations return new maps in O(log32 n) time, sharing structure with the original map.

使用结构共享实现高效的不可变更新。put/remove 操作在 O(log32 n) 时间内返回新映射，与原映射共享结构。

Features | 主要功能:

  • Structural sharing via HAMT - 基于 HAMT 的结构共享
  • Immutable - 不可变
  • O(log32 n) put/get/remove - O(log32 n) 的插入/查找/删除
  • Hash collision handling - 哈希冲突处理

Usage Examples | 使用示例:

// Create map - 创建映射
PersistentMap<String, Integer> map = PersistentMap.<String, Integer>empty()
    .put("a", 1)
    .put("b", 2);

// Original is unchanged after put - put 后原映射不变
PersistentMap<String, Integer> map2 = map.put("c", 3);
// map still has size 2, map2 has size 3

// Get value - 获取值
Optional<Integer> val = map.get("a"); // Optional[1]

// Remove key - 删除键
PersistentMap<String, Integer> map3 = map.remove("a");

Performance | 性能特性:

  • put: O(log32 n) - put: O(log32 n)
  • get: O(log32 n) - get: O(log32 n)
  • remove: O(log32 n) - remove: O(log32 n)
  • containsKey: O(log32 n) - containsKey: O(log32 n)

Security | 安全性:

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

  • Method Details

    • empty

      public static <K,V> PersistentMap<K,V> empty()
      Return an empty persistent map. 返回一个空的持久化映射。
      Type Parameters:
      K - key type | 键类型
      V - value type | 值类型
      Returns:
      empty persistent map | 空的持久化映射

    • of

      public static <K,V> PersistentMap<K,V> of(K k1, V v1)
      Create a persistent map with one entry. 创建包含一个条目的持久化映射。
      Type Parameters:
      K - key type | 键类型
      V - value type | 值类型
      Parameters:
      k1 - the key | 键
      v1 - the value | 值
      Returns:
      persistent map with one entry | 包含一个条目的持久化映射

    • of

      public static <K,V> PersistentMap<K,V> of(K k1, V v1, K k2, V v2)
      Create a persistent map with two entries. 创建包含两个条目的持久化映射。
      Type Parameters:
      K - key type | 键类型
      V - value type | 值类型
      Parameters:
      k1 - the first key | 第一个键
      v1 - the first value | 第一个值
      k2 - the second key | 第二个键
      v2 - the second value | 第二个值
      Returns:
      persistent map with two entries | 包含两个条目的持久化映射

    • put

      public PersistentMap<K,V> put(K key, V value)
      Return a new map with the given key-value pair added or updated. 返回添加或更新给定键值对后的新映射。
      Parameters:
      key - the key | 键
      value - the value | 值
      Returns:
      a new map with the entry | 包含该条目的新映射

    • remove

      public PersistentMap<K,V> remove(K key)
      Return a new map with the given key removed. 返回删除给定键后的新映射。
      Parameters:
      key - the key to remove | 要删除的键
      Returns:
      a new map without the key | 不包含该键的新映射

    • get

      public Optional<V> get(K key)
      Return the value associated with the given key, if present. 返回与给定键关联的值（如果存在）。
      Parameters:
      key - the key | 键
      Returns:
      optional containing the value, or empty | 包含值的 Optional，或空

    • containsKey

      public boolean containsKey(K key)
      Check if this map contains the given key. 检查此映射是否包含给定键。
      Parameters:
      key - the key | 键
      Returns:
      true if the key is present | 如果键存在则返回 true

    • size

      public int size()
      Return the number of entries in this map. 返回此映射中的条目数量。
      Returns:
      the size | 大小

    • isEmpty

      public boolean isEmpty()
      Check if this map is empty. 检查此映射是否为空。
      Returns:
      true if the map is empty | 如果映射为空则返回 true

    • toMap

      public Map<K,V> toMap()
      Convert this persistent map to a JDK Map. 将此持久化映射转换为 JDK Map。
      Returns:
      an unmodifiable map containing all entries | 包含所有条目的不可修改映射

    • keySet

      public Set<K> keySet()
      Return the set of keys. 返回键的集合。
      Returns:
      unmodifiable set of keys | 不可修改的键集合

    • values

      public Collection<V> values()
      Return the collection of values. 返回值的集合。
      Returns:
      unmodifiable collection of values | 不可修改的值集合

    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      Return the set of entries. 返回条目集合。
      Returns:
      unmodifiable set of entries | 不可修改的条目集合

    • stream

      public Stream<Map.Entry<K,V>> stream()
      Return a sequential stream over the entries. 返回条目上的顺序流。
      Returns:
      a stream of entries | 条目的流

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object