Package convex.core.data

Class MapLeaf<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.MapLeaf<K,V>

Type Parameters:

K - Type of keys

V - Type of values

All Implemented Interfaces:

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

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

Limited size Persistent Merkle Map implemented as a small sorted list of Key/Value pairs Must be sorted by Key hash value to ensure uniqueness of representation

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
static final int	MAX_ENTRIES	Maximum number of entries in a MapLeaf

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.
AHashMap<K,V>	assoc(ACell key, ACell value)	Associates the given key with the specified value.
protected AHashMap<K,V>	assoc(K key, V value, int shift)
AHashMap<K,V>	assocEntry(MapEntry<K,V> e)	Associate the given map entry into the map.
AHashMap<K,V>	assocEntry(MapEntry<K,V> e, int shift)
AHashMap<K,V>	assocRef(Ref<K> keyRef, V value)
protected AHashMap<K,V>	assocRef(Ref<K> keyRef, V value, int shift)
boolean	containsAllKeys(AHashMap<K,V> b)	Returns true if this map contains all the same keys as another map
protected boolean	containsAllKeys(MapLeaf<K,V> b)
boolean	containsValue(ACell value)	CHecks if this map contains the given value.
static <K extends ACell, V extends ACell> MapLeaf<K,V>	create(MapEntry<K,V> item)
static <K extends ACell, V extends ACell> MapLeaf<K,V>	create(MapEntry<K,V>[] entries)	Creates a ListMap with the specified entries.
protected static <K extends ACell, V extends ACell> MapLeaf<K,V>	create(MapEntry<K,V>[] entries, int offset, int length)	Creates a MapLeaf with the specified entries.
MapLeaf<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.
MapLeaf<K,V>	dissocRef(Ref<K> key)	Dissoc given a Ref to the key value.
static <K extends ACell, V extends ACell> MapLeaf<K,V>	emptyMap()
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.
boolean	equals(MapLeaf<K,V> a)
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
MapLeaf<K,V>	filterHexDigits(int digitPos, int mask)	Filters this ListMap to contain only key hashes with the hex digits specified in the given Mask
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.
Set<K>	keySet()
MapLeaf<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>	mergeDifferences(MapLeaf<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> MapLeaf<K,V>	read(Blob b, int pos, long count)	Reads a MapLeaf from the provided Blob encoding.
<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
MapLeaf<K,V>	slice(long start, long end)	Gets a slice of this data structure
ACell	toCanonical()	Converts this Cell to a canonical version.
static <K extends ACell, V extends ACell> MapLeaf<K,V>	unsafeCreate(MapEntry<K,V>... items)	Creates a MapLeaf
MapLeaf	updateRefs(IRefFunction func)	Updates all Refs in this object using the given function.
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, isDataValue, 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, validate

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_ENTRIES

public static final int MAX_ENTRIES

Maximum number of entries in a MapLeaf

See Also:

• Constant Field Values

MAX_ENCODING_LENGTH

public static int MAX_ENCODING_LENGTH

Method Details

create

public static <K extends ACell,
V extends ACell>
MapLeaf<K,V> create(MapEntry<K,V>[] entries)

Creates a ListMap with the specified entries. Entries must have distinct keys but may otherwise be specified in any order. Null entries are ignored/removed.

Parameters:

entries - Entries for map

Returns:

New ListMap

create

protected static <K extends ACell,
V extends ACell>
MapLeaf<K,V> create(MapEntry<K,V>[] entries,
 int offset,
 int length)

Creates a MapLeaf with the specified entries. Null entries are ignored/removed.

Parameters:

entries -

offset - Offset into entries array

length - Number of entries to take from entries array, starting at offset

Returns:

A new ListMap

create

public static <K extends ACell,
V extends ACell>
MapLeaf<K,V> create(MapEntry<K,V> item)

unsafeCreate

public static <K extends ACell,
V extends ACell>
MapLeaf<K,V> unsafeCreate(MapEntry<K,V>... items)

Creates a MapLeaf

Type Parameters:

K - Type of keys

V - Type of values

Parameters:

items - Array of map entries

Returns:

Potentially invalid MapLeaf

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

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.

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

dissoc

public MapLeaf<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 MapLeaf<K,V> dissocRef(Ref<K> key)

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:

key - Ref of key to remove

Returns:

Map with specified key removed.

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 AHashMap<K,V> assocEntry(MapEntry<K,V> e,
 int shift)

Specified by:

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

assoc

public AHashMap<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

assoc

protected AHashMap<K,V> assoc(K key,
 V value,
 int shift)

assocRef

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

Specified by:

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

assocRef

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

Specified by:

assocRef 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>
MapLeaf<K,V> read(Blob b,
 int pos,
 long count)
           throws BadFormatException

Reads a MapLeaf from the provided Blob encoding.

Parameters:

b - Blob to read from

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

count - Count of map elements

Returns:

A Map as deserialised from the provided ByteBuffer

Throws:

BadFormatException - If encoding is invalid

emptyMap

public static <K extends ACell,
V extends ACell>
MapLeaf<K,V> emptyMap()

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

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 MapLeaf 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

filterHexDigits

public MapLeaf<K,V> filterHexDigits(int digitPos,
 int mask)

Filters this ListMap to contain only key hashes with the hex digits specified in the given Mask

Parameters:

digitPos - Position of the hex digit to filter

mask - Mask of digits to include

Returns:

Filtered ListMap

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.

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>

mergeDifferences

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

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

equals

public boolean equals(MapLeaf<K,V> a)

mapEntries

public MapLeaf<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

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> b)

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:

b - Map to compare with

Returns:

True if this map contains all the keys of the other

containsAllKeys

protected boolean containsAllKeys(MapLeaf<K,V> b)

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 ACell 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 MapLeaf<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