Collections: Specialized Maps (IntMap, FloatMap)

Bifurcan provides highly optimized sorted maps for primitive integer and floating-point keys: IntMap and FloatMap. These collections can be used as efficient sparse vectors or as high-performance sorted maps when keys are numeric.

IntMap

IntMap is an immutable sorted map of long integers to arbitrary values. It is a powerful and efficient data structure that combines concepts from Patricia tries and CHAMP tries.

Features

• High Performance: Significantly faster than a general-purpose SortedMap for integer keys due to its specialized structure.
• Sorted Keys: Keys are always kept in sorted order.
• Sparse Vector: Can be used as a sparse vector where indices are long values.
• Efficient Set Operations: Like Map, IntMap has a canonical structure, making operations like merge, difference, and intersection very fast.

Usage

import io.lacuna.bifurcan.IntMap;

// Create an IntMap
IntMap<String> sparseVector = new IntMap<String>()
    .put(100, "value at 100")
    .put(-50, "value at -50")
    .put(1_000_000, "large index");

System.out.println(sparseVector.get(100L)); // Optional[value at 100]

// Slice a range of keys
IntMap<String> slice = sparseVector.slice(0, 200);
System.out.println(slice.size()); // 1
System.out.println(slice.keys().first()); // 100

FloatMap

FloatMap provides similar functionality for double keys. It is built on top of IntMap by converting double values to their long bit representations in a way that preserves their natural ordering.

Features

• Sorted Floating-Point Keys: Keeps entries sorted by double keys.
• Performance: Shares the same performance benefits as IntMap.
• NaN and Zero Handling: Does not allow NaN as a key and treats -0.0 as equivalent to 0.0 to maintain sorted integrity.

Usage

import io.lacuna.bifurcan.FloatMap;

// Create a FloatMap
FloatMap<String> floatMap = new FloatMap<String>()
    .put(3.14, "pi")
    .put(-1.5, "negative one point five")
    .put(42.0, "forty-two");

System.out.println(floatMap.get(3.14)); // Optional[pi]

// Find the floor entry for a key
System.out.println(floatMap.floor(0.0).key()); // -1.5