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<E>
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.

  • Field Details

    • MAX_ENCODING_LENGTH

      public static int MAX_ENCODING_LENGTH

  • 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(HashSet<K> h)
      Description copied from class: AMap
      Accumulate all keys from this map in the given HashSet.
      Specified by:
      accumulateKeySet in class AMap<K extends ACell,V extends ACell>
      Parameters:
      h - HashSet in which to accumulate keys

    • accumulateValues

      protected void accumulateValues(ArrayList<V> al)
      Description copied from class: AMap
      Accumulate all values from this map in the given ArrayList.
      Specified by:
      accumulateValues in class AMap<K extends ACell,V extends ACell>
      Parameters:
      al - ArrayList in which to accumulate values

    • entrySet

      public HashSet<Map.Entry<K,V>> entrySet()

    • accumulateEntrySet

      protected void accumulateEntrySet(HashSet<Map.Entry<K,V>> h)
      Description copied from class: AMap
      Accumulate all entries from this map in the given HashSet.
      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 for message writing. Non-canonical objects may be used on a temporary internal basis, they must always be converted to canonical representations for external use (e.g. Encoding).
      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 represents a first class CVM Value. Sub-structural cells that are not themselves first class values 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. WARNING: may not be valid id Cell is not canonical Contained Refs may be either external or embedded.
      Specified by:
      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 be unreliable is cell is not canonical
      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.
      Overrides:
      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. 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>
      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 its canonical version. Must return this Cell if already canonical, may be O(n) in size of value otherwise.
      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