Package convex.core.data

Class MapTree<K extends ACell,V extends ACell>

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

convex.core.data.ACountable<MapEntry<K,V>>

convex.core.data.ADataStructure<MapEntry<K,V>>

convex.core.data.AMap<K,V>

convex.core.data.AHashMap<K,V>

convex.core.data.MapTree<K,V>

Type Parameters:

K - Type of map keys

V - Type of map values

All Implemented Interfaces:

IAssociative<K,V>, IValidated, IWriteable, Map<K,V>

public class MapTree<K extends ACell,V extends ACell>
extends AHashMap<K,V>

Persistent Map for large hash maps requiring tree structure. Internally implemented as a radix tree, indexed by key hash. Uses an array of child Maps, with a bitmap mask indicating which hex digits are present, i.e. have non-empty children.

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field	Description
static int	MAX_ENCODING_LENGTH	Max length is tag, shift byte, 2 byte mask, max count plus embedded Refs

Fields inherited from class convex.core.data.ADataStructure

count

Fields inherited from class convex.core.data.ACell

cachedRef, memorySize

Fields inherited from class convex.core.data.AObject

encoding

Method Summary

Modifier and Type	Method	Description
protected void	accumulateEntrySet(Set<Map.Entry<K,V>> h)	Accumulate all entries from this map in the given mutable Set.
protected void	accumulateKeySet(Set<K> h)	Accumulate all keys from this map in the given mutable Set.
protected void	accumulateValues(List<V> al)	Accumulate all values from this map in the given mutable list.
MapTree<K,V>	assoc(ACell key, ACell value)	Associates the given key with the specified value.
AHashMap<K,V>	assocEntry(MapEntry<K,V> e)	Associate the given map entry into the map.
MapTree<K,V>	assocEntry(MapEntry<K,V> e, int shift)
MapTree<K,V>	assocRef(Ref<K> keyRef, V value)
protected MapTree<K,V>	assocRef(Ref<K> keyRef, V value, int shift)
boolean	containsAllKeys(AHashMap<K,V> map)	Returns true if this map contains all the same keys as another map
protected boolean	containsAllKeys(MapTree<K,V> map)
boolean	containsValue(ACell value)	CHecks if this map contains the given value.
static <K extends ACell, V extends ACell> MapTree<K,V>	create(MapEntry<K,V>[] newEntries, int shift)
static int	digitForIndex(int index, short mask)
AHashMap<K,V>	dissoc(ACell key)	Dissociates a key from this map, returning an updated map if the key was removed, or the same unchanged map if the key is not present.
AHashMap<K,V>	dissocRef(Ref<K> keyRef)	Dissoc given a Ref to the key value.
int	encode(byte[] bs, int pos)	Writes this HashMap to a byte array.
int	encodeRaw(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, excluding the tag byte.
MapEntry<K,V>	entryAt(long i)	Gets the entry in this map at a specified index, according to the map-specific order.
boolean	equals(ACell a)	Checks for equality with another Cell.
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
void	forEach(BiConsumer<? super K,? super V> action)
V	get(ACell key)	Get the value associated with a given key.
MapEntry<K,V>	getEntry(ACell k)	Gets the MapEntry for the given key
protected MapEntry<K,V>	getEntryByHash(Hash hash)	Gets the map entry with the specified hash
MapEntry<K,V>	getKeyRefEntry(Ref<ACell> ref)	Get an entry given a Ref to the key value.
<R extends ACell> Ref<R>	getRef(int i)	Gets a numbered child Ref from within this Cell.
int	getRefCount()	Gets the number of Refs contained within this Cell.
byte	getTag()	Gets the tag byte for this cell.
boolean	isCanonical()	Returns true if this Cell is in a canonical representation.
final boolean	isCVMValue()	Returns true if this cell is a first class CVM Value allowable in the CVM state Sub-structural cells that are not themselves first class values should return false Records and types that are not permissible on the CVM should return false.
final boolean	isDataValue()	Returns true if this cell instance is a first class value, i.e.
Set<K>	keySet()
AHashMap<K,V>	mapEntries(Function<MapEntry<K,V>,MapEntry<K,V>> func)	Maps a function over all entries in this Map to produce updated entries.
AHashMap<K,V>	mergeDifferences(AHashMap<K,V> b, MergeFunction<V> func)	Merge this map with another map, using the given function for each key that is present in either map and has a different value The function is passed null for missing values in either map, and must return type V.
protected AHashMap<K,V>	mergeDifferences(AHashMap<K,V> b, MergeFunction<V> func, int shift)
AHashMap<K,V>	mergeWith(AHashMap<K,V> b, MergeFunction<V> func)	Merge this map with another map, using the given function for each key that is present in either map.
protected AHashMap<K,V>	mergeWith(AHashMap<K,V> b, MergeFunction<V> func, int shift)
static <K extends ACell, V extends ACell> MapTree<K,V>	read(Blob b, int pos, long count)	Reads a ListMap from the provided Blob
<R> R	reduceEntries(BiFunction<? super R,MapEntry<K,V>,? extends R> func, R initial)	Reduce over all map entries in this map
<R> R	reduceValues(BiFunction<? super R,? super V,? extends R> func, R initial)	Reduce over all values in this map
AHashMap<K,V>	slice(long start, long end)	Gets a slice of this data structure
AHashMap<K,V>	toCanonical()	Converts this Cell to a canonical version.
MapTree<K,V>	updateRefs(IRefFunction func)	Updates all Refs in this object using the given function.
void	validate()	Validates the complete structure of this object.
void	validateCell()	Validates the local structure and invariants of this cell.
protected void	validateWithPrefix(String prefix)	Validates the map with a given hex prefix for the Hash.

Methods inherited from class convex.core.data.AHashMap

containsKey, empty, entrySet, filterValues, getKeys, merge, merge, slice

Methods inherited from class convex.core.data.AMap

clear, conj, containsKey, containsKeyRef, containsValue, entryVector, get, get, get, getElementRef, getType, print, put, putAll, remove, values

Methods inherited from class convex.core.data.ADataStructure

checkIndex, conjAll, count, isEmpty, size, toCVMString

Methods inherited from class convex.core.data.ACell

attachMemorySize, attachRef, cachedEncoding, cachedHash, calcMemorySize, createEncoding, createRef, equals, genericEquals, getCanonical, getChildRefs, getEncoding, getEncodingLength, getHash, getMemorySize, getMemorySize, getRef, hashCode, isEmbedded, toString

Methods inherited from class convex.core.data.AObject

attachEncoding, print, print

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, equals, getOrDefault, hashCode, isEmpty, merge, putIfAbsent, remove, replace, replace, replaceAll, size

Field Details

MAX_ENCODING_LENGTH

public static int MAX_ENCODING_LENGTH

Max length is tag, shift byte, 2 byte mask, max count plus embedded Refs

Method Details

create

public static <K extends ACell,
V extends ACell>
MapTree<K,V> create(MapEntry<K,V>[] newEntries,
 int shift)

getEntry

public MapEntry<K,V> getEntry(ACell k)

Description copied from class: AMap

Gets the MapEntry for the given key

Specified by:

getEntry in class AMap<K extends ACell,V extends ACell>

Parameters:

k - Key to lookup in Map

Returns:

The map entry, or null if the key is not found

getKeyRefEntry

public MapEntry<K,V> getKeyRefEntry(Ref<ACell> ref)

Description copied from class: AMap

Get an entry given a Ref to the key value. This is more efficient than directly looking up using the key for some map types, and should be preferred if the caller already has a Ref available.

Specified by:

getKeyRefEntry in class AMap<K extends ACell,V extends ACell>

Parameters:

ref - Ref to Map key

Returns:

MapEntry for the given key ref

containsValue

public boolean containsValue(ACell value)

Description copied from class: AMap

CHecks if this map contains the given value. WARNING: probably O(n)

Specified by:

containsValue in class AMap<K extends ACell,V extends ACell>

Parameters:

value - Value to check

Returns:

true if map contains value, false otherwise

get

public V get(ACell key)

Description copied from class: ADataStructure

Get the value associated with a given key.

Specified by:

get in class AMap<K extends ACell,V extends ACell>

Parameters:

key - Associative key to look up

Returns:

Value from collection, or a falsey value (null or false) if not found

entryAt

public MapEntry<K,V> entryAt(long i)

Description copied from class: AMap

Gets the entry in this map at a specified index, according to the map-specific order. Caller responsible for bounds check!

Specified by:

entryAt in class AMap<K extends ACell,V extends ACell>

Parameters:

i - Index of entry

Returns:

MapEntry at the specified index.

getEntryByHash

protected MapEntry<K,V> getEntryByHash(Hash hash)

Description copied from class: AMap

Gets the map entry with the specified hash

Specified by:

getEntryByHash in class AMap<K extends ACell,V extends ACell>

Parameters:

hash - Hash of key to lookup

Returns:

The specified MapEntry, or null if not found.

dissoc

public AHashMap<K,V> dissoc(ACell key)

Description copied from class: AMap

Dissociates a key from this map, returning an updated map if the key was removed, or the same unchanged map if the key is not present.

Specified by:

dissoc in class AHashMap<K extends ACell,V extends ACell>

Parameters:

key - Key to remove.

Returns:

Updated map

dissocRef

public AHashMap<K,V> dissocRef(Ref<K> keyRef)

Description copied from class: AHashMap

Dissoc given a Ref to the key value.

Specified by:

dissocRef in class AHashMap<K extends ACell,V extends ACell>

Parameters:

keyRef - Ref of key to remove

Returns:

Map with specified key removed.

digitForIndex

public static int digitForIndex(int index,
 short mask)

assoc

public MapTree<K,V> assoc(ACell key,
 ACell value)

Description copied from class: AMap

Associates the given key with the specified value.

Specified by:

assoc in class AHashMap<K extends ACell,V extends ACell>

Parameters:

key - Map key to associate

value - Map value

Returns:

An updated map with the new association, or null if the association fails

assocRef

public MapTree<K,V> assocRef(Ref<K> keyRef,
 V value)

Specified by:

assocRef in class AHashMap<K extends ACell,V extends ACell>

assocRef

protected MapTree<K,V> assocRef(Ref<K> keyRef,
 V value,
 int shift)

Specified by:

assocRef in class AHashMap<K extends ACell,V extends ACell>

assocEntry

public AHashMap<K,V> assocEntry(MapEntry<K,V> e)

Description copied from class: AMap

Associate the given map entry into the map. May return null if the map entry is not valid for this map type.

Specified by:

assocEntry in class AHashMap<K extends ACell,V extends ACell>

Parameters:

e - A map entry

Returns:

The updated map

assocEntry

public MapTree<K,V> assocEntry(MapEntry<K,V> e,
 int shift)

Specified by:

assocEntry in class AHashMap<K extends ACell,V extends ACell>

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K extends ACell,V extends ACell>

Overrides:

keySet in class AMap<K extends ACell,V extends ACell>

accumulateKeySet

protected void accumulateKeySet(Set<K> h)

Description copied from class: AMap

Accumulate all keys from this map in the given mutable Set.

Specified by:

accumulateKeySet in class AMap<K extends ACell,V extends ACell>

Parameters:

h - HashSet in which to accumulate keys

accumulateValues

protected void accumulateValues(List<V> al)

Description copied from class: AMap

Accumulate all values from this map in the given mutable list.

Specified by:

accumulateValues in class AMap<K extends ACell,V extends ACell>

Parameters:

al - ArrayList in which to accumulate values

accumulateEntrySet

protected void accumulateEntrySet(Set<Map.Entry<K,V>> h)

Description copied from class: AMap

Accumulate all entries from this map in the given mutable Set.

Specified by:

accumulateEntrySet in class AMap<K extends ACell,V extends ACell>

Parameters:

h - HashSet in which to accumulate entries

encode

public int encode(byte[] bs,
 int pos)

Description copied from class: AHashMap

Writes this HashMap to a byte array. Will include values by default.

Specified by:

encode in interface IWriteable

Specified by:

encode in class AHashMap<K extends ACell,V extends ACell>

Parameters:

bs - Byte array to encode into

pos - Start position to encode at

Returns:

Updated position

encodeRaw

public int encodeRaw(byte[] bs,
 int pos)

Description copied from class: ACell

Writes this Cell's encoding to a byte array, excluding the tag byte.

Specified by:

encodeRaw in class ACell

Parameters:

bs - A byte array to which to write the encoding

pos - The offset into the byte array

Returns:

New position after writing

estimatedEncodingSize

public int estimatedEncodingSize()

Description copied from interface: IWriteable

Estimate the encoded data size for this Cell. Used for quickly sizing buffers. Implementations should try to return a size that is highly likely to contain the entire object when encoded, including the tag byte. Should not traverse soft Refs, i.e. must be usable on arbitrary partial data structures

Returns:

The estimated size for the binary representation of this object.

read

public static <K extends ACell,
V extends ACell>
MapTree<K,V> read(Blob b,
 int pos,
 long count)
           throws BadFormatException

Reads a ListMap from the provided Blob

Parameters:

b - Blob to read from

pos - Start position in Blob (location of tag byte)

count - Count of map entries*

Returns:

New decoded instance

Throws:

BadFormatException - In the event of any encoding error

forEach

public void forEach(BiConsumer<? super K,? super V> action)

Specified by:

forEach in interface Map<K extends ACell,V extends ACell>

Specified by:

forEach in class AMap<K extends ACell,V extends ACell>

isCanonical

public boolean isCanonical()

Description copied from class: ACell

Returns true if this Cell is in a canonical representation. Non-canonical objects may be used on a temporary internal basis, they should be converted to canonical representations for general purpose use.

Specified by:

isCanonical in class ACell

Returns:

true if the object is in canonical format, false otherwise

isCVMValue

public final boolean isCVMValue()

Description copied from class: ACell

Returns true if this cell is a first class CVM Value allowable in the CVM state Sub-structural cells that are not themselves first class values should return false Records and types that are not permissible on the CVM should return false. Pretty much everything else should return true. Note: CVM values might not be in a canonical format, e.g. temporary data structures

Specified by:

isCVMValue in class ACell

Returns:

true if the object is a CVM Value, false otherwise

isDataValue

public final boolean isDataValue()

Description copied from class: ACell

Returns true if this cell instance is a first class value, i.e. not a component of a larger data structure Sub-structural cells that are not themselves first class values should return false Everything else should return true.

Overrides:

isDataValue in class ADataStructure<MapEntry<K extends ACell,V extends ACell>>

Returns:

true if the object is a Value, false otherwise

getRefCount

public int getRefCount()

Description copied from class: ACell

Gets the number of Refs contained within this Cell. This number is final / immutable for any given instance and is defined by the Cell encoding rules. Contained Refs may be either external or embedded.

Overrides:

getRefCount in class ACell

Returns:

The number of Refs in this Cell

getRef

public <R extends ACell> Ref<R> getRef(int i)

Description copied from class: ACell

Gets a numbered child Ref from within this Cell. WARNING: May need to convert to a canonical instance

Overrides:

getRef in class ACell

Type Parameters:

R - Type of referenced Cell

Parameters:

i - Index of ref to get

Returns:

The Ref at the specified index

updateRefs

public MapTree<K,V> updateRefs(IRefFunction func)

Description copied from class: ACell

Updates all Refs in this object using the given function. The function *must not* change the hash value of Refs, in order to ensure structural integrity of modified data structures. The implementation *should* re-attach any original encoding in order to prevent re-encoding or surplus hashing This is a building block for a very sneaky trick that enables use to do a lot of efficient operations on large trees of smart references. Must return the same object if no Refs are altered.

Specified by:

updateRefs in class AHashMap<K extends ACell,V extends ACell>

Parameters:

func - Ref update function

Returns:

Cell with updated Refs

mergeWith

public AHashMap<K,V> mergeWith(AHashMap<K,V> b,
 MergeFunction<V> func)

Description copied from class: AHashMap

Merge this map with another map, using the given function for each key that is present in either map. The function is applied to the corresponding values with the same key. The function is passed null for missing values in either map, and must return type V. If the function returns null, the entry is removed. Returns the same map if no changes occurred. PERF WARNING: This method's contract requires calling the function on all values in both sets, which will cause a full data structure traversal. If the function will only return one or other of the compared values consider using mergeDifferences instead.

Specified by:

mergeWith in class AHashMap<K extends ACell,V extends ACell>

Parameters:

b - Other map to merge with

func - Merge function, returning a new value for each key

Returns:

A merged map, or this map if no changes occurred

mergeWith

protected AHashMap<K,V> mergeWith(AHashMap<K,V> b,
 MergeFunction<V> func,
 int shift)

Specified by:

mergeWith in class AHashMap<K extends ACell,V extends ACell>

mergeDifferences

public AHashMap<K,V> mergeDifferences(AHashMap<K,V> b,
 MergeFunction<V> func)

Description copied from class: AHashMap

Merge this map with another map, using the given function for each key that is present in either map and has a different value The function is passed null for missing values in either map, and must return type V. If the function returns null, the entry is removed. Returns the same map if no changes occurred.

Specified by:

mergeDifferences in class AHashMap<K extends ACell,V extends ACell>

Parameters:

b - Other map to merge with

func - Merge function, returning a new value for each key

Returns:

A merged map, or this map if no changes occurred

mergeDifferences

protected AHashMap<K,V> mergeDifferences(AHashMap<K,V> b,
 MergeFunction<V> func,
 int shift)

Specified by:

mergeDifferences in class AHashMap<K extends ACell,V extends ACell>

reduceValues

public <R> R reduceValues(BiFunction<? super R,? super V,? extends R> func,
 R initial)

Description copied from class: AMap

Reduce over all values in this map

Specified by:

reduceValues in class AMap<K extends ACell,V extends ACell>

Type Parameters:

R - Type of reduction return value

Parameters:

func - A function taking the reduction value and a map value

initial - Initial reduction value

Returns:

The final reduction value

reduceEntries

public <R> R reduceEntries(BiFunction<? super R,MapEntry<K,V>,? extends R> func,
 R initial)

Description copied from class: AMap

Reduce over all map entries in this map

Specified by:

reduceEntries in class AMap<K extends ACell,V extends ACell>

Type Parameters:

R - Type of reduction return value

Parameters:

func - A function taking the reduction value and a map entry

initial - Initial reduction value

Returns:

The final reduction value

equals

public boolean equals(ACell a)

Description copied from class: ACell

Checks for equality with another Cell. In general, Cells are considered equal if they have the same canonical representation, i.e. an identical encoding with the same hash value. Subclasses SHOULD override this if they have a more efficient equals implementation. MUST NOT require reads from Store.

Specified by:

equals in class ACell

Parameters:

a - Cell to compare with. May be null.

Returns:

True if this cell is equal to the other object

mapEntries

public AHashMap<K,V> mapEntries(Function<MapEntry<K,V>,MapEntry<K,V>> func)

Description copied from class: AHashMap

Maps a function over all entries in this Map to produce updated entries. May not change keys, but may return null to remove an entry.

Specified by:

mapEntries in class AHashMap<K extends ACell,V extends ACell>

Parameters:

func - A function that maps old map entries to updated map entries.

Returns:

The updated Map, or this Map if no changes

validate

public void validate()
              throws InvalidDataException

Description copied from interface: IValidated

Validates the complete structure of this object. It is necessary to ensure all child Refs are validated, so the general contract for validate is:

1. Call super.validate() - which will indirectly call validateCell()
2. Call validate() on any contained cells in this class

Specified by:

validate in interface IValidated

Overrides:

validate in class ACell

Throws:

InvalidDataException - If the data Value is invalid in any way

validateWithPrefix

protected void validateWithPrefix(String prefix)
                           throws InvalidDataException

Description copied from class: AHashMap

Validates the map with a given hex prefix for the Hash. This is necessary to ensure that child maps are valid, in particular have the correct shift level and that all key hashes start with the correct prefix of hex characters. TODO: consider faster way of passing prefix than hex string, probably a byte[] stack.

Specified by:

validateWithPrefix in class AHashMap<K extends ACell,V extends ACell>

Parameters:

prefix -

Throws:

InvalidDataException

validateCell

public void validateCell()
                  throws InvalidDataException

Description copied from class: ACell

Validates the local structure and invariants of this cell. Called by validate() super implementation. Should validate directly contained data, but should not validate all other structure of this cell. In particular, should not traverse potentially missing child Refs.

Specified by:

validateCell in class ACell

Throws:

InvalidDataException - If the Cell is invalid

containsAllKeys

public boolean containsAllKeys(AHashMap<K,V> map)

Description copied from class: AHashMap

Returns true if this map contains all the same keys as another map

Specified by:

containsAllKeys in class AHashMap<K extends ACell,V extends ACell>

Parameters:

map - Map to compare with

Returns:

True if this map contains all the keys of the other

containsAllKeys

protected boolean containsAllKeys(MapTree<K,V> map)

getTag

public byte getTag()

Description copied from class: ACell

Gets the tag byte for this cell. The tag byte is always equal to the first byte of the Cell's canonical Encoding, and is sufficient to distinguish how to read the rest of the encoding.

Specified by:

getTag in class ACell

Returns:

Tag byte for this Cell

toCanonical

public AHashMap<K,V> toCanonical()

Description copied from class: ACell

Converts this Cell to a canonical version. Must return this Cell if already canonical, may be O(n) in size of value otherwise. Callers should usually use getCanonical(), which caches canonical instances once created

Specified by:

toCanonical in class ACell

Returns:

Canonical version of Cell

slice

public AHashMap<K,V> slice(long start,
 long end)

Description copied from class: ACountable

Gets a slice of this data structure

Specified by:

slice in class AHashMap<K extends ACell,V extends ACell>

Parameters:

start - Start index (inclusive)

end - end index (exclusive)

Returns:

Slice of data structure, or null if invalid slice