Package convex.core.data

Class SetLeaf<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.SetLeaf<T>

Type Parameters:

T - Type of values

All Implemented Interfaces:

IAssociative<T,CVMBool>, IValidated, IWriteable, Iterable<T>, Collection<T>, Set<T>

public class SetLeaf<T extends ACell>
extends AHashSet<T>

Limited size Persistent Merkle Set implemented as a small sorted list of Values Must be sorted by Key hash value to ensure uniqueness of representation

Field Summary

Fields

Modifier and Type	Field	Description
static final int	MAX_ELEMENTS	Maximum number of elements in a SetLeaf
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
protected void	accumulateValues(ArrayList<T> al)
boolean	containsAll(ASet<?> b)	Tests if this set contains all the elements of another set
protected boolean	containsAll(SetLeaf<?> b)
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> SetLeaf<V>	create(Ref<V>... elements)	Creates a SetLeaf with the specified elements.
protected static <V extends ACell> SetLeaf<V>	create(Ref<V>[] entries, int offset, int length)	Creates a SetLeaf with the specified elements.
static <V extends ACell> SetLeaf<V>	create(V item)
static <V extends ACell> SetLeaf<V>	emptySet()
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.
boolean	equals(SetLeaf<T> a)
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
SetLeaf<T>	exclude(ACell key)	Updates the set to exclude the given element
SetLeaf<T>	excludeRef(Ref<?> key)
SetLeaf<T>	filterHexDigits(int digitPos, int mask)	Filters this ListMap to contain only key hashes with the hex digits specified in the given Mask
T	get(long index)	Gets the element at the specified element index in this value
Ref<T>	getElementRef(long i)	Gets a Ref to the element at the specified element index in this collection
Ref<T>	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
AHashSet<T>	includeRef(Ref<T> ref)	Adds a value to this set using a Ref to the value
protected AHashSet<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.
final boolean	isDataValue()	Returns true if this cell instance is a first class value, i.e.
boolean	isSubset(ASet<? super T> b)	Tests if this set is a (non-strict) subset of another Set
AHashSet<T>	mergeWith(AHashSet<T> b, int setOp)
protected AHashSet<T>	mergeWith(AHashSet<T> b, int setOp, int shift)
AHashSet<T>	mergeWith(SetLeaf<T> b, int setOp, int shift)
static <V extends ACell> SetLeaf<V>	read(Blob b, int pos, long count)	Reads a MapLeaf from the provided ByteBuffer Assumes the header byte is already read.
<R> R	reduceValues(BiFunction<? super R,? super T,? extends R> func, R initial)
ASet<T>	slice(long start, long end)	Gets a slice of this Set
AHashSet<T>	toCanonical()	Converts this Cell to a canonical version.
static <V extends ACell> SetLeaf<V>	unsafeCreate(Ref<V>... refs)	Create a SetLeaf with raw element Refs.
static <V extends ACell> SetLeaf<V>	unsafeCreate(V... elements)	Create a SetLeaf with raw elements.
SetLeaf	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 prefix, 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, include, includeAll, intersectAll, reverseOp, toArray

Methods inherited from class convex.core.data.ASet

assoc, contains, containsKey, empty, get, getTag, getType, 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, 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_ELEMENTS

public static final int MAX_ELEMENTS

Maximum number of elements in a SetLeaf

See Also:

• Constant Field Values

MAX_ENCODING_LENGTH

public static int MAX_ENCODING_LENGTH

Method Details

create

@SafeVarargs
public static <V extends ACell> SetLeaf<V> create(Ref<V>... elements)

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

Parameters:

elements - Refs of Elements to include

Returns:

New ListMap

unsafeCreate

public static <V extends ACell> SetLeaf<V> unsafeCreate(Ref<V>... refs)

Create a SetLeaf with raw element Refs. Can create an invalid Cell, useful mainly for testing

Parameters:

refs - Refs to set elements, in desired order

Returns:

SetLeaf instance, possibly invalid

unsafeCreate

public static <V extends ACell> SetLeaf<V> unsafeCreate(V... elements)

Create a SetLeaf with raw elements. Can create an invalid Cell, useful mainly for testing

Parameters:

elements - Elements to include in set, in desired order

Returns:

SetLeaf instance, possibly invalid

create

protected static <V extends ACell> SetLeaf<V> create(Ref<V>[] entries,
 int offset,
 int length)

Creates a SetLeaf with the specified elements. Null references are ignored/removed.

Parameters:

entries - Refs to elements to include (some may be null)

offset - Offset into entries array

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

Returns:

A new ListMap

create

public static <V extends ACell> SetLeaf<V> create(V item)

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

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

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 SetLeaf<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 SetLeaf<T> excludeRef(Ref<?> key)

Specified by:

excludeRef in class AHashSet<T extends ACell>

accumulateValues

protected void accumulateValues(ArrayList<T> al)

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

Reads a MapLeaf from the provided ByteBuffer Assumes the header byte is already read.

Parameters:

b - Blob to read from

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

count - Count of map elements

Returns:

New decoded instance

Throws:

BadFormatException - In the event of any encoding error

emptySet

public static <V extends ACell> SetLeaf<V> emptySet()

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<T 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 Ref<T> 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

Parameters:

i - Index of ref to get

Returns:

The Ref at the specified index

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

updateRefs

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

filterHexDigits

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

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>

mergeWith

public AHashSet<T> mergeWith(SetLeaf<T> b,
 int setOp,
 int shift)

reduceValues

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

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(SetLeaf<T> a)

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 prefix,
 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:

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

isSubset

public boolean isSubset(ASet<? super T> b)

Description copied from class: ASet

Tests if this set is a (non-strict) subset of another Set

Overrides:

isSubset in class ASet<T extends ACell>

Parameters:

b - Set to test against

Returns:

True if this is a subset of the other set, false otherwise.

containsAll

protected boolean containsAll(SetLeaf<?> b)

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

includeRef

protected AHashSet<T> includeRef(Ref<T> e,
 int shift)

Specified by:

includeRef in class AHashSet<T extends ACell>

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 -

get

public T get(long index)

Description copied from class: ACountable

Gets the element at the specified element index in this value

Overrides:

get in class ASet<T extends ACell>

Parameters:

index - Index of element to get

Returns:

Element at the specified index

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

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