Package convex.core.data

Class SetTree<T extends ACell>

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

convex.core.data.ACountable<T>

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 Summary

Fields

Modifier and Type	Field	Description
static int	MAX_ENCODING_LENGTH

Fields inherited from class convex.core.data.AHashSet

MAX_SHIFT, OP_DIFF_LEFT, OP_DIFF_RIGHT, OP_INTERSECTION, OP_UNION

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
boolean	containsAll(ASet<?> b)	Tests if this set contains all the elements of another set
protected boolean	containsAll(SetTree<?> other)
boolean	containsHash(Hash hash)	Tests if this Set contains a given hash
protected <R> void	copyToArray(R[] arr, int offset)	Copies the elements of this collection in order to an array at the specified offset
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.
static int	digitForIndex(int index, short mask)
int	encode(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, including a tag byte which will be written first.
int	encodeRaw(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, excluding the tag byte.
boolean	equals(ACell a)	Checks for equality with another Cell.
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
AHashSet<T>	exclude(ACell key)	Updates the set to exclude the given element
AHashSet<T>	excludeRef(Ref<?> keyRef)
Ref<T>	getElementRef(long i)	Gets a Ref to the element at the specified element index in this collection
short	getMask()	Returns the mask value of this SetTree node.
<R extends ACell> Ref<R>	getRef(int i)	Gets a numbered child Ref from within this Cell.
protected Ref<T>	getRefByHash(Hash hash)	Gets the Ref in the Set for a given hash, or null if not found
int	getRefCount()	Gets the number of Refs contained within this Cell.
Ref<T>	getValueRef(ACell k)	Gets the Ref in the Set for a given value, or null if not found
SetTree<T>	include(ACell value)	Updates the set to include the given element
AHashSet<T>	includeRef(Ref<T> ref)	Adds a value to this set using a Ref to the value
protected SetTree<T>	includeRef(Ref<T> e, int shift)
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.
AHashSet<T>	mergeWith(AHashSet<T> b, int setOp)
protected AHashSet<T>	mergeWith(AHashSet<T> b, int setOp, int shift)
static <V extends ACell> SetTree<V>	read(Blob b, int pos, long count)	Reads a SetTree from the provided Blob encoding
protected AHashSet<T>	replaceChild(int i, Ref<AHashSet<T>> newChild)	Replaces the child ref at a given index position.
ASet<T>	slice(long start, long end)	Gets a slice of this Set
AHashSet<T>	toCanonical()	Converts this Cell to a canonical version.
static <T extends ACell> SetTree<T>	unsafeCreate(Ref<AHashSet<T>>[] children, int shift, short mask, long count)
SetTree<T>	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(Hash base, int digit, int position)	Validates the set with a given hex prefix.

Methods inherited from class convex.core.data.AHashSet

applyOp, applySelf, conj, conjAll, contains, disjAll, excludeAll, get, getByHash, includeAll, intersectAll, reverseOp, toArray

Methods inherited from class convex.core.data.ASet

assoc, contains, containsKey, empty, get, get, getTag, getType, isSubset, map, print, slice, toVector

Methods inherited from class convex.core.data.ACollection

add, addAll, clear, containsAll, iterator, remove, removeAll, retainAll, toArray, toCellArray

Methods inherited from class convex.core.data.ADataStructure

checkIndex, 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

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

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.Set

add, addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, spliterator, toArray

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

toCanonical

public AHashSet<T> 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 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 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

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

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

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<?> 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<?> other)

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

Parameters:

arr -

offset -

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