Package convex.core.data

Class Index<K extends ABlobLike<?>,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.AIndex<K,V>

convex.core.data.Index<K,V>

Type Parameters:

K - Type of Keys

V - Type of values

All Implemented Interfaces:

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

public final class Index<K extends ABlobLike<?>,V extends ACell>
extends AIndex<K,V>

Index node implementation, providing an efficient radix tree based immutable data structure for indexed access and sorting. Supporting:

• An optional prefix string
• An optional entry with this exact prefix
• Up to 16 child entries at the next level of depth

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 final Index<?,?>	EMPTY	Empty Index singleton
static final Ref<Index>[]	EMPTY_CHILDREN

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

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Index(long depth, MapEntry<K,V> entry, Ref<Index>[] entries, short mask, long count)

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.
Index<K,V>	assoc(ACell key, ACell value)	Associates a blob key with a value in this data structure.
Index<K,V>	assocEntry(MapEntry<K,V> e)	Associate the given map entry into the map.
boolean	containsValue(ACell value)	CHecks if this map contains the given value.
static <K extends ABlobLike<?>, V extends ACell> Index<K,V>	create(MapEntry<K,V> me)
static <R extends AIndex<K, V>, K extends ABlobLike<?>, V extends ACell> R	create(HashMap<K,V> map)
static <K extends ABlobLike<?>, V extends ACell> Index<K,V>	create(K k, V v)
Index<K,V>	dissoc(K k)
Index<K,V>	empty()	Returns an empty instance of the same Type as this data structure.
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.
MapEntry<K,V>	entryAt(long ix)	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(Index<K,V> a)	Checks this Index for equality with another Index
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
Index<K,V>	filterValues(Predicate<V> pred)	Filters all values in this map with the given predicate.
void	forEach(BiConsumer<? super K,? super V> action)
V	get(K key)	Gets the map entry for a given Blob
MapEntry<K,V>	getEntry(K key)
protected MapEntry<K,V>	getEntryByHash(Hash hash)	Gets the map entry with the specified hash
<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.
boolean	isDataValue()	Returns true if this cell instance is a first class value, i.e.
static <K extends ABlobLike<?>> boolean	keyMatch(K a, K b)	Tests if two keys match (up to the maximum index key depth)
static <K extends ABlobLike<?>, V extends ACell> Index<K,V>	none()
static <K extends ABlobLike<?>, V extends ACell> Index<K,V>	of(Object... kvs)
static <K extends ABlobLike<?>, V extends ACell> Index<K,V>	of(Object k, Object v)
static <K extends ABlobLike<?>, V extends ACell> Index<K,V>	read(Blob b, int pos)
<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
Index<K,V>	slice(long start)	Slices this Index, starting at the specified position Removes n leading entries from this Index, in key order.
Index<K,V>	slice(long start, long end)	Returns a slice of this Index
ACell	toCanonical()	Converts this Cell to a canonical version.
static <K extends ABlobLike<?>, V extends ACell> Index<K,V>	unsafeCreate(long depth, MapEntry<K,V> entry, Ref<Index>[] entries, int mask, long count)
Index<K,V>	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.

Methods inherited from class convex.core.data.AIndex

containsKey, dissoc, entrySet, get, getEntry, getKeyRefEntry, getType

Methods inherited from class convex.core.data.AMap

clear, conj, containsKey, containsKeyRef, containsValue, entryVector, get, get, get, getElementRef, getKeys, keySet, merge, print, put, putAll, remove, values

Methods inherited from class convex.core.data.ADataStructure

checkIndex, conjAll, 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.Map

compute, computeIfAbsent, computeIfPresent, equals, getOrDefault, hashCode, isEmpty, merge, putIfAbsent, remove, replace, replace, replaceAll, size

Field Details

EMPTY_CHILDREN

public static final Ref<Index>[] EMPTY_CHILDREN

EMPTY

public static final Index<?,?> EMPTY

Empty Index singleton

Constructor Details

Index

protected Index(long depth,
 MapEntry<K,V> entry,
 Ref<Index>[] entries,
 short mask,
 long count)

Method Details

unsafeCreate

public static <K extends ABlobLike<?>,
V extends ACell>
Index<K,V> unsafeCreate(long depth,
 MapEntry<K,V> entry,
 Ref<Index>[] entries,
 int mask,
 long count)

create

public static <K extends ABlobLike<?>,
V extends ACell>
Index<K,V> create(MapEntry<K,V> me)

create

public static <K extends ABlobLike<?>,
V extends ACell>
Index<K,V> create(K k,
 V v)

of

public static <K extends ABlobLike<?>,
V extends ACell>
Index<K,V> of(Object k,
 Object v)

of

public static <K extends ABlobLike<?>,
V extends ACell>
Index<K,V> of(Object... kvs)

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.

Overrides:

isCanonical in class AIndex<K extends ABlobLike<?>,V extends 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 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<MapEntry<K extends ABlobLike<?>,V extends ACell>>

Returns:

true if the object is a Value, false otherwise

updateRefs

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

Overrides:

updateRefs in class ACell

Parameters:

func - Ref update function

Returns:

Cell with updated Refs

get

public V get(K key)

Description copied from class: AIndex

Gets the map entry for a given Blob

Specified by:

get in class AIndex<K extends ABlobLike<?>,V extends ACell>

Parameters:

key - Key to lookup up

Returns:

The value specified by the given blob key or null if not present.

getEntry

public MapEntry<K,V> getEntry(K key)

Specified by:

getEntry in class AIndex<K extends ABlobLike<?>,V extends ACell>

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.

Specified by:

getRefCount in class AIndex<K extends ABlobLike<?>,V extends 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

Specified by:

getRef in class AIndex<K extends ABlobLike<?>,V extends ACell>

Type Parameters:

R - Type of referenced Cell

Parameters:

i - Index of ref to get

Returns:

The Ref at the specified index

assoc

public Index<K,V> assoc(ACell key,
 ACell value)

Description copied from class: AIndex

Associates a blob key with a value in this data structure. Returns null if the key is not a valid Index key

Specified by:

assoc in class AIndex<K extends ABlobLike<?>,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

dissoc

public Index<K,V> dissoc(K k)

Specified by:

dissoc in class AIndex<K extends ABlobLike<?>,V extends ACell>

keyMatch

public static <K extends ABlobLike<?>> boolean keyMatch(K a,
 K b)

Tests if two keys match (up to the maximum index key depth)

Parameters:

a - First key

b - second key

Returns:

True if keys match

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 ABlobLike<?>,V extends ACell>

Parameters:

h - HashSet in which to accumulate entries

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 ABlobLike<?>,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 ABlobLike<?>,V extends ACell>

Parameters:

al - ArrayList in which to accumulate values

forEach

public void forEach(BiConsumer<? super K,? super V> action)

Specified by:

forEach in interface Map<K extends ABlobLike<?>,V extends ACell>

Specified by:

forEach in class AMap<K extends ABlobLike<?>,V extends ACell>

assocEntry

public Index<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 AMap<K extends ABlobLike<?>,V extends ACell>

Parameters:

e - A map entry

Returns:

The updated map

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 ABlobLike<?>,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 ABlobLike<?>,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

filterValues

public Index<K,V> filterValues(Predicate<V> pred)

Description copied from class: AMap

Filters all values in this map with the given predicate.

Overrides:

filterValues in class AMap<K extends ABlobLike<?>,V extends ACell>

Parameters:

pred - A predicate specifying which elements to retain.

Returns:

The updated map containing those entries where the predicate returned true.

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

Specified by:

estimatedEncodingSize in interface IWriteable

Specified by:

estimatedEncodingSize in class AIndex<K extends ABlobLike<?>,V extends ACell>

Returns:

The estimated size for the binary representation of this object.

read

public static <K extends ABlobLike<?>,
V extends ACell>
Index<K,V> read(Blob b,
 int pos)
         throws BadFormatException

Throws:

BadFormatException

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 ABlobLike<?>,V extends ACell>

Parameters:

hash - Hash of key to lookup

Returns:

The specified MapEntry, or null if not found.

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

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

empty

public Index<K,V> empty()

Description copied from class: ADataStructure

Returns an empty instance of the same Type as this data structure.

Specified by:

empty in class AMap<K extends ABlobLike<?>,V extends ACell>

Returns:

An empty data structure

none

public static <K extends ABlobLike<?>,
V extends ACell>
Index<K,V> none()

entryAt

public MapEntry<K,V> entryAt(long ix)

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 AIndex<K extends ABlobLike<?>,V extends ACell>

Parameters:

ix - Index of entry

Returns:

MapEntry at the specified index.

slice

public Index<K,V> slice(long start)

Slices this Index, starting at the specified position Removes n leading entries from this Index, in key order.

Overrides:

slice in class AMap<K extends ABlobLike<?>,V extends ACell>

Parameters:

start - Start position of entries to keep

Returns:

Updated Index with leading entries removed, or null if invalid slice

slice

public Index<K,V> slice(long start,
 long end)

Returns a slice of this Index

Overrides:

slice in class AMap<K extends ABlobLike<?>,V extends ACell>

Parameters:

start - Start position of slice (inclusive)

end - End position of slice (exclusive)

Returns:

Slice of Index, or null if invalid slice

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(Index<K,V> a)

Checks this Index for equality with another Index

Parameters:

a - Index to compare with

Returns:

true if maps are equal, false otherwise.

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

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 ABlobLike<?>,V extends ACell>

Parameters:

value - Value to check

Returns:

true if map contains value, false otherwise

create

public static <R extends AIndex<K,
V>,
K extends ABlobLike<?>,
V extends ACell>
R create(HashMap<K,V> map)