Package convex.core.data

Class SetTree<T extends ACell>

java.lang.Object
convex.core.data.AObject
convex.core.data.ACell
convex.core.data.ACountable<E>
convex.core.data.ADataStructure<T>
convex.core.data.ACollection<T>
convex.core.data.ASet<T>
convex.core.data.AHashSet<T>
convex.core.data.SetTree<T>
Type Parameters:
T - Type of Set elements
All Implemented Interfaces:
IAssociative<T,CVMBool>, IValidated, IWriteable, Iterable<T>, Collection<T>, Set<T>
public class SetTree<T extends ACell> extends AHashSet<T>
Persistent Set for large hash sets 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

    • unsafeCreate

      public static <T extends ACell> SetTree<T> unsafeCreate(Ref<AHashSet<T>>[] children, int shift, short mask, long count)

    • create

      public static <V extends ACell> SetTree<V> create(Ref<V>[] elementRefs, int shift)
      Create a SetTree given a number of element Refs to distribute among children. O(n) in number of elements.
      Type Parameters:
      V - Type of elements
      Parameters:
      elementRefs - Array of Refs to elements
      shift - Hex digit position at which to split children.
      Returns:
      New SetTree node

    • getElementRef

      public Ref<T> getElementRef(long i)
      Description copied from class: ACountable
      Gets a Ref to the element at the specified element index in this collection
      Specified by:
      getElementRef in class ACountable<T extends ACell>
      Parameters:
      i - Index of element to get
      Returns:
      Element at the specified index

    • getRefByHash

      protected Ref<T> getRefByHash(Hash hash)
      Description copied from class: ASet
      Gets the Ref in the Set for a given hash, or null if not found
      Specified by:
      getRefByHash in class ASet<T extends ACell>
      Parameters:
      hash - Hash to check for set membership
      Returns:
      Ref to value with given Hash, or null

    • exclude

      public AHashSet<T> exclude(ACell key)
      Description copied from class: ASet
      Updates the set to exclude the given element
      Overrides:
      exclude in class AHashSet<T extends ACell>
      Parameters:
      key - Value to exclude
      Returns:
      Updated set

    • excludeRef

      public AHashSet<T> excludeRef(Ref<T> keyRef)
      Specified by:
      excludeRef in class AHashSet<T 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

    • toCanonical

      public AHashSet<T> 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 AHashSet<T extends ACell>
      Returns:
      Canonical version of Cell

    • replaceChild

      protected AHashSet<T> replaceChild(int i, Ref<AHashSet<T>> newChild)
      Replaces the child ref at a given index position. Will return this if no change
      Parameters:
      i -
      newChild -
      Returns:
      Updated SetTree

    • digitForIndex

      public static int digitForIndex(int index, short mask)

    • include

      public SetTree<T> include(ACell value)
      Description copied from class: ASet
      Updates the set to include the given element
      Overrides:
      include in class AHashSet<T extends ACell>
      Parameters:
      value - Value to include
      Returns:
      Updated set

    • includeRef

      protected SetTree<T> includeRef(Ref<T> e, int shift)
      Specified by:
      includeRef in class AHashSet<T extends ACell>

    • includeRef

      public AHashSet<T> includeRef(Ref<T> ref)
      Description copied from class: ASet
      Adds a value to this set using a Ref to the value
      Specified by:
      includeRef in class AHashSet<T extends ACell>
      Parameters:
      ref - Ref to value to include
      Returns:
      Updated set

    • encode

      public int encode(byte[] bs, int pos)
      Description copied from class: ACell
      Writes this Cell's encoding to a byte array, including a tag byte which will be written first. Cell must be canonical, or else an error may occur.
      Specified by:
      encode in interface IWriteable
      Specified by:
      encode in class ACollection<T extends ACell>
      Parameters:
      bs - A byte array to which to write the encoding
      pos - The offset into the byte array
      Returns:
      New position after writing

    • 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 <V extends ACell> SetTree<V> read(Blob b, int pos, long count) throws BadFormatException
      Reads a SetTree from the provided Blob encoding
      Parameters:
      b - Blob to read from
      pos - Start position in Blob (location of tag byte)
      count - Number of elements
      Returns:
      New decoded instance
      Throws:
      BadFormatException - In the event of any encoding error

    • 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

    • getMask

      public short getMask()
      Returns the mask value of this SetTree node. Each set bit indicates the presence of a child set with the given hex digit
      Returns:
      Mask value

    • 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 SetTree<T> 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.
      Overrides:
      updateRefs in class ACell
      Parameters:
      func - Ref update function
      Returns:
      Cell with updated Refs

    • mergeWith

      public AHashSet<T> mergeWith(AHashSet<T> b, int setOp)
      Specified by:
      mergeWith in class AHashSet<T extends ACell>

    • mergeWith

      protected AHashSet<T> mergeWith(AHashSet<T> b, int setOp, int shift)
      Specified by:
      mergeWith in class AHashSet<T extends ACell>

    • 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

    • 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(Hash base, int digit, int position) throws InvalidDataException
      Description copied from class: AHashSet
      Validates the set 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 hashes start with the correct prefix of hex characters.
      Specified by:
      validateWithPrefix in class AHashSet<T extends ACell>
      Parameters:
      base - Hash for earlier prefix values
      digit - Hex digit expected at position [shift]
      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

    • containsAll

      public boolean containsAll(ASet<T> b)
      Description copied from class: ASet
      Tests if this set contains all the elements of another set
      Specified by:
      containsAll in class ASet<T extends ACell>
      Parameters:
      b - Set to compare with
      Returns:
      True if other set is completely contained within this set, false otherwise

    • containsAll

      protected boolean containsAll(SetTree<T> map)

    • getValueRef

      public Ref<T> getValueRef(ACell k)
      Description copied from class: ASet
      Gets the Ref in the Set for a given value, or null if not found
      Specified by:
      getValueRef in class ASet<T extends ACell>
      Parameters:
      k - Value to check for set membership
      Returns:
      Ref to value, or null

    • copyToArray

      protected <R> void copyToArray(R[] arr, int offset)
      Description copied from class: ACollection
      Copies the elements of this collection in order to an array at the specified offset
      Specified by:
      copyToArray in class ACollection<T extends ACell>
      Type Parameters:
      R - Type of array elements required

    • containsHash

      public boolean containsHash(Hash hash)
      Description copied from class: AHashSet
      Tests if this Set contains a given hash
      Specified by:
      containsHash in class AHashSet<T extends ACell>
      Parameters:
      hash - Hash to test for set membership
      Returns:
      True if set contains value for given hash, false otherwise

    • slice

      public ASet<T> slice(long start, long end)
      Description copied from class: ASet
      Gets a slice of this Set
      Specified by:
      slice in class ASet<T extends ACell>
      Parameters:
      start - start index (inclusive)
      end - end index (exclusive)
      Returns:
      Slice of set, or null if invalid slice