io.lacuna.bifurcan

Class Map<K,V>

java.lang.Object

io.lacuna.bifurcan.Map<K,V>

All Implemented Interfaces:

ICollection<IMap<K,V>,IEntry<K,V>>, IMap<K,V>, Cloneable, Iterable<IEntry<K,V>>, Function<K,V>

public class Map<K,V>
extends Object
implements IMap<K,V>, Cloneable

An implementation of an immutable hash-map based on the general approach described by Steindorfer and Vinju in this paper. It allows for customized hashing and equality semantics, and due to its default reliance on Java's semantics, it is significantly faster than Clojure's PersistentHashMap for lookups and construction for collections smaller than 100k entries, and has equivalent performance for larger collections.

By ensuring that equivalent maps always have equivalent layout in memory, it can perform equality checks and set operations (union, difference, intersection) significantly faster than a more naive implementation.. By keeping the memory layout of each node more compact, iteration is at least 2x faster than Clojure's map.

Field Summary

Fields

Modifier and Type	Field and Description
static Map	EMPTY

Constructor Summary

Constructors

Constructor and Description
Map()
Map(ToLongFunction<K> hashFn, BiPredicate<K,K> equalsFn) Creates a map.

Method Summary

Modifier and Type	Method and Description
Map<K,V>	clone()
boolean	contains(K key)
Map<K,V>	difference(IMap<K,?> m)
Map<K,V>	difference(ISet<K> keys)
boolean	equals(IMap<K,V> m, BiPredicate<V,V> valEquals)
boolean	equals(Object obj)
Map<K,V>	forked() This returns a data structure which is forked, which is equivalent to Clojure's persistent data structures, also sometimes called functional or immutable.
static <K,V> Map<K,V>	from(IList<IEntry<K,V>> entries)
static <K,V> Map<K,V>	from(IMap<K,V> map)
static <K,V> Map<K,V>	from(Iterator<IEntry<K,V>> entries)
static <K,V> Map<K,V>	from(Map<K,V> map)
V	get(K key, V defaultValue)
int	hashCode()
OptionalLong	indexOf(K key)
Map<K,V>	intersection(IMap<K,?> m)
Map<K,V>	intersection(ISet<K> keys)
boolean	isLinear()
Iterator<IEntry<K,V>>	iterator()
BiPredicate<K,K>	keyEquality()
ToLongFunction<K>	keyHash()
Set<K>	keys()
Map<K,V>	linear() This returns a data structure which is linear, or temporarily mutable.
<U> Map<K,U>	mapValues(BiFunction<K,V,U> f)
Map<K,V>	merge(IMap<K,V> m, BinaryOperator<V> mergeFn)
IEntry<K,V>	nth(long idx)
Map<K,V>	put(K key, V value, BinaryOperator<V> merge)
Map<K,V>	put(K key, V value, BinaryOperator<V> merge, Object editor)
Map<K,V>	remove(K key)
Map<K,V>	remove(K key, Object editor)
long	size()
List<Map<K,V>>	split(int parts) Splits the collection into roughly even pieces, for parallel processing.
String	toString()
Map<K,V>	union(IMap<K,V> m)
Map<K,V>	update(K key, UnaryOperator<V> update)
Map<K,V>	update(K key, UnaryOperator<V> update, Object editor)

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface io.lacuna.bifurcan.IMap

apply, containsAll, containsAll, containsAny, containsAny, entries, get, getOrCreate, hashSortedEntries, put, save, spliterator, stream, toMap, values

Methods inherited from interface io.lacuna.bifurcan.ICollection

nth, save

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.function.Function

andThen, compose, identity

Field Detail

EMPTY

public static final Map EMPTY

Constructor Detail

Map

public Map(ToLongFunction<K> hashFn,
           BiPredicate<K,K> equalsFn)

Creates a map.

Parameters:

hashFn - a function which yields the hash value of keys

equalsFn - a function which checks equality of keys

Map

public Map()

Method Detail

from

public static <K,V> Map<K,V> from(IMap<K,V> map)

Parameters:

map - another map

Returns:

an equivalent forked map, with the same equality semantics

from

public static <K,V> Map<K,V> from(Map<K,V> map)

Returns:

a forked map with the same contents as map

from

public static <K,V> Map<K,V> from(Iterator<IEntry<K,V>> entries)

Parameters:

entries - an iterator of IEntry objects

Returns:

a forked map containing the remaining entries

from

public static <K,V> Map<K,V> from(IList<IEntry<K,V>> entries)

Parameters:

entries - a list of IEntry objects

Returns:

a forked map containing these entries

keys

public Set<K> keys()

Specified by:

keys in interface IMap<K,V>

Returns:

a set representing all keys in the map

keyHash

public ToLongFunction<K> keyHash()

Specified by:

keyHash in interface IMap<K,V>

Returns:

the hash function used by the map

keyEquality

public BiPredicate<K,K> keyEquality()

Specified by:

keyEquality in interface IMap<K,V>

Returns:

the key equality semantics used by the map

get

public V get(K key,
             V defaultValue)

Specified by:

get in interface IMap<K,V>

Returns:

the value under key, or defaultValue if there is no such key

put

public Map<K,V> put(K key,
                    V value,
                    BinaryOperator<V> merge)

Specified by:

put in interface IMap<K,V>

merge - a function which will be invoked if there is a pre-existing value under key, with the current value as the first argument and new value as the second, to determine the combined result

Returns:

an updated map with value under key

put

public Map<K,V> put(K key,
                    V value,
                    BinaryOperator<V> merge,
                    Object editor)

update

public Map<K,V> update(K key,
                       UnaryOperator<V> update)

Specified by:

update in interface IMap<K,V>

update - a function which takes the existing value, or null if none exists, and returns an updated value.

Returns:

an updated map with update(value) under key.

update

public Map<K,V> update(K key,
                       UnaryOperator<V> update,
                       Object editor)

remove

public Map<K,V> remove(K key)

Specified by:

remove in interface IMap<K,V>

Returns:

an updated map that does not contain key

remove

public Map<K,V> remove(K key,
                       Object editor)

contains

public boolean contains(K key)

Specified by:

contains in interface IMap<K,V>

Returns:

true if key is in the map, false otherwise

indexOf

public OptionalLong indexOf(K key)

Specified by:

indexOf in interface IMap<K,V>

Returns:

the index of key within the collection, if it's present

nth

public IEntry<K,V> nth(long idx)

Specified by:

nth in interface ICollection<IMap<K,V>,IEntry<K,V>>

Returns:

the element at idx

forked

public Map<K,V> forked()

Description copied from interface: ICollection

This returns a data structure which is forked, which is equivalent to Clojure's persistent data structures, also sometimes called functional or immutable. This is called "forked" because it means that multiple functions can make divergent changes to the data structure without affecting each other.

If only a single function or scope uses the data structure, it can be left as a linear data structure, which can have significant performance benefits.

If the data structure is already forked, it will simply return itself.

Specified by:

forked in interface ICollection<IMap<K,V>,IEntry<K,V>>

Specified by:

forked in interface IMap<K,V>

Returns:

a forked form of the data structure

linear

public Map<K,V> linear()

Description copied from interface: ICollection

This returns a data structure which is linear, or temporarily mutable. The term "linear", as used here, does not completely align with the formal definition of linear types as used in type theory. It is meant to describe the linear dataflow of the method calls, and as a converse to "forked" data structures.

If ICollection.forked() is called on a linear collection, all references to that linear collection should be discarded.

If the data structure is already linear, it will simply return itself.

Specified by:

linear in interface ICollection<IMap<K,V>,IEntry<K,V>>

Specified by:

linear in interface IMap<K,V>

Returns:

a linear form of this data structure

mapValues

public <U> Map<K,U> mapValues(BiFunction<K,V,U> f)

Specified by:

mapValues in interface IMap<K,V>

Type Parameters:

U - the new type of the values

Parameters:

f - a function which transforms the values

Returns:

a transformed map which shares the same equality semantics

split

public List<Map<K,V>> split(int parts)

Description copied from interface: ICollection

Splits the collection into roughly even pieces, for parallel processing. Depending on the size and contents of the collection, this function may not return exactly parts subsets.

Specified by:

split in interface ICollection<IMap<K,V>,IEntry<K,V>>

Specified by:

split in interface IMap<K,V>

Parameters:

parts - the target number of pieces

Returns:

a list containing subsets of the collection.

union

public Map<K,V> union(IMap<K,V> m)

Specified by:

union in interface IMap<K,V>

Returns:

a combined map, with the values from m shadowing those in this amp

merge

public Map<K,V> merge(IMap<K,V> m,
                      BinaryOperator<V> mergeFn)

Specified by:

merge in interface IMap<K,V>

Parameters:

m - another map

mergeFn - a function which, in the case of key collisions, takes two values and returns the merged result

Returns:

a new map representing the merger of the two maps

difference

public Map<K,V> difference(ISet<K> keys)

Specified by:

difference in interface IMap<K,V>

Returns:

a new map representing the current map, less the keys in keys

intersection

public Map<K,V> intersection(ISet<K> keys)

Specified by:

intersection in interface IMap<K,V>

Returns:

a new map representing the current map, but only with the keys in keys

difference

public Map<K,V> difference(IMap<K,?> m)

Specified by:

difference in interface IMap<K,V>

Returns:

a new map representing the current map, less the keys in m

intersection

public Map<K,V> intersection(IMap<K,?> m)

Specified by:

intersection in interface IMap<K,V>

Returns:

a new map representing the current map, but only with the keys in m

size

public long size()

Specified by:

size in interface ICollection<IMap<K,V>,IEntry<K,V>>

Returns:

the number of elements in the collection

isLinear

public boolean isLinear()

Specified by:

isLinear in interface ICollection<IMap<K,V>,IEntry<K,V>>

Specified by:

isLinear in interface IMap<K,V>

Returns:

true, if the collection is linear

iterator

public Iterator<IEntry<K,V>> iterator()

Specified by:

iterator in interface IMap<K,V>

Specified by:

iterator in interface Iterable<IEntry<K,V>>

Returns:

an iterator over all entries in the map

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(IMap<K,V> m,
                      BiPredicate<V,V> valEquals)

Specified by:

equals in interface IMap<K,V>

Parameters:

m - another map

valEquals - a predicate which checks value equalities

Returns:

true, if the maps are equivalent

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object

clone

public Map<K,V> clone()

Specified by:

clone in interface ICollection<IMap<K,V>,IEntry<K,V>>

Overrides:

clone in class Object

Returns:

a cloned copy of the collection