Package convex.core.data

Class AVector<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.ASequence<T>

convex.core.data.AVector<T>

Type Parameters:

T - Type of element in Vector

All Implemented Interfaces:

IAssociative<CVMLong,T>, IValidated, IWriteable, Iterable<T>, Collection<T>, List<T>, SequencedCollection<T>

Direct Known Subclasses:

ASpecialVector, VectorLeaf, VectorTree

public abstract class AVector<T extends ACell>
extends ASequence<T>

Abstract base class for vectors. Vectors are immutable sequences of values, with efficient appends to the tail of the list. This is a hierarchy with multiple implementations for different vector types, but all should conform to the general AVector interface. We use an abstract base class in preference to an interface because we control the hierarchy and it offers some mild performance advantages. General design goals: - Immutability - Cell structure breakdown for larger vectors, while keeping a shallow tree - Optimised performance for end of vector (conj, pop, last etc.) - Fast prefix comparisons to support consensus algorithm "If I had any recommendation to you at all, it's just if you're thinking about designing a system and you're not sure, whether you can answer all that questions in the forward direction, choose immutability. You can almost back into a little more than 50% of this design just by haven taken immutability as a constraint, saying 'oh my god now what am I gonna do? I cannot change this. I better do this!' And keep forcing you into good answers. So if I had any architectural guidance from this: Just do it. Choose immutability and see where it takes you." - Rich Hickey

Field Summary

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

Constructor	Description
AVector(long count)

Method Summary

Modifier and Type	Method	Description
abstract boolean	allMatch(Predicate<? super T> pred)
abstract boolean	anyMatch(Predicate<? super T> pred)
abstract AVector<T>	append(T value)	Appends a single element to this vector
AVector<T>	appendAll(List<T> list)
abstract AVector<T>	appendChunk(AVector<T> chunk)	Appends a ListVector chunk to this vector.
abstract AVector<T>	assoc(long i, T value)	Updates a value at the given position in the sequence.
abstract long	commonPrefixLength(AVector<T> b)	Computes the length of the longest common prefix of this vector and another vector.
abstract AVector<T>	concat(ASequence<? extends T> b)	Concatenates the elements from another sequence to the end of this sequence.
final AVector<T>	conj(ACell value)	Adds an element to the sequence in the natural position
AVector<T>	conjAll(ACollection<? extends T> xs)	Adds multiple elements to this data structure, in the natural manner defined by the general data structure type.
AList<T>	cons(T x)	Prepends an element to this sequence, returning a list.
AVector<T>	empty()	Returns an empty instance of the same Type as this data structure.
abstract int	encodeRaw(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, excluding the tag byte.
final boolean	equals(ACell a)	Checks for equality with another Cell.
abstract boolean	equals(AVector<? super T> a)
<R extends ACell> AVector<R>	flatMap(Function<? super T,? extends ASequence<R>> mapper)
T	get(int index)	Gets the element at the specified index in this sequence.
abstract T	get(long i)	Gets the element at the specified index in this vector
abstract VectorLeaf<T>	getChunk(long offset)	Gets the VectorLeaf chunk at a given offset
protected abstract Ref<T>	getElementRefUnsafe(long i)	Gets an element Ref from this vector, assuming bounds already checked
byte	getTag()	Gets the tag byte for this cell.
AType	getType()	Gets the most specific known runtime Type for this Cell.
final int	indexOf(Object o)
abstract boolean	isCanonical()	Returns true if this vector is in canonical format, i.e.
abstract boolean	isFullyPacked()	Returns true if this Vector is a single fully packed tree.
boolean	isPacked()	Returns true if this Vector is a packed packed tree.
Iterator<T>	iterator()
final int	lastIndexOf(Object o)
final ListIterator<T>	listIterator(int index)
abstract ListIterator<T>	listIterator(long index)	Gets the ListIterator for a long position
abstract <R extends ACell> AVector<R>	map(Function<? super T,? extends R> mapper)	Maps a function over a collection, applying it to each element in turn.
AVector<T>	mergeWith(AVector<T> b, MergeFunction<T> func)	Merges this vector with another vector, using the provided merge function.
abstract AVector<T>	next()	Gets the sequence of all elements after the first, or null if no elements remain after the first (i.e.
boolean	print(BlobBuilder sb, long limit)	Prints this Object to a readable String Representation.
abstract <R> R	reduce(BiFunction<? super R,? super T,? extends R> func, R value)
AList<T>	reverse()	Reverses a sequence, converting Lists to Vectors and vice versa
abstract AVector<T>	slice(long start, long end)	Produces a slice of this sequence, beginning with the specified start index and of the given length.
final AVector<T>	subVector(long start, long length)	Gets a vector containing the specified subset of this sequence, or null if range is invalid
Object[]	toArray()
abstract AVector<T>	updateRefs(IRefFunction func)	Updates all Refs in this object using the given function.

Methods inherited from class convex.core.data.ASequence

add, addAll, assoc, checkRange, contains, containsKey, forEach, get, get, getElementRef, isCVMValue, longIndexOf, longLastIndexOf, remove, set, spliterator, spliterator, subList, toCellArray, visitElementRefs

Methods inherited from class convex.core.data.ACollection

add, addAll, clear, containsAll, copyToArray, encode, remove, removeAll, retainAll, toArray, toVector

Methods inherited from class convex.core.data.ADataStructure

checkIndex, count, isDataValue, isEmpty, size, toCVMString

Methods inherited from class convex.core.data.ACountable

slice

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, getRef, getRefCount, hashCode, isEmbedded, toCanonical, toString, validate, validateCell

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 convex.core.data.IWriteable

estimatedEncodingSize

Methods inherited from interface java.util.List

add, addAll, addFirst, addLast, clear, containsAll, equals, getFirst, getLast, hashCode, isEmpty, listIterator, remove, removeAll, removeFirst, removeLast, replaceAll, retainAll, reversed, size, sort, toArray

Constructor Details

AVector

public AVector(long count)

Method Details

getType

public AType getType()

Description copied from class: ACell

Gets the most specific known runtime Type for this Cell.

Specified by:

getType in class ACollection<T extends ACell>

Returns:

The Type of this Call

get

public abstract T get(long i)

Gets the element at the specified index in this vector

Specified by:

get in class ASequence<T extends ACell>

Parameters:

i - The index of the element to get

Returns:

The element value at the specified index

appendChunk

public abstract AVector<T> appendChunk(AVector<T> chunk)

Appends a ListVector chunk to this vector. This vector must contain a whole number of chunks

Parameters:

chunk - A chunk to append. Must be a ListVector of maximum size

Returns:

The updated vector, of the same type as this vector @

getChunk

public abstract VectorLeaf<T> getChunk(long offset)

Gets the VectorLeaf chunk at a given offset

Parameters:

offset - Offset into this vector. Must be a valid chunk start position

Returns:

The chunk referenced

append

public abstract AVector<T> append(T value)

Appends a single element to this vector

Parameters:

value - Value to append

Returns:

Updated vector

isFullyPacked

public abstract boolean isFullyPacked()

Returns true if this Vector is a single fully packed tree. i.e. a full ListVector or TreeVector.

Returns:

true if fully packed, false otherwise

isPacked

public boolean isPacked()

Returns true if this Vector is a packed packed tree. i.e. an exact whole number of chunks

Returns:

true if packed, false otherwise

print

public boolean print(BlobBuilder sb,
 long limit)

Description copied from class: AObject

Prints this Object to a readable String Representation. SECURITY: Must halt and return false in O(1) time when limit of printing is exceeded otherwise DoS attacks may be possible.

Specified by:

print in class AObject

Parameters:

sb - BlobBuilder to append to. May be partially written if print limit exceeded

limit - Limit of printing in string bytes

Returns:

True if fully printed within limit, false otherwise

get

public T get(int index)

Description copied from class: ASequence

Gets the element at the specified index in this sequence. Behaves as if the index was considered as a long

Specified by:

get in interface List<T extends ACell>

Overrides:

get in class ASequence<T extends ACell>

Parameters:

index - Index of element to get

Returns:

Element at the specified index

anyMatch

public abstract boolean anyMatch(Predicate<? super T> pred)

allMatch

public abstract boolean allMatch(Predicate<? super T> pred)

map

public abstract <R extends ACell> AVector<R> map(Function<? super T,? extends R> mapper)

Description copied from class: ACollection

Maps a function over a collection, applying it to each element in turn.

Specified by:

map in class ASequence<T extends ACell>

Type Parameters:

R - Type of element in resulting collection

Parameters:

mapper - Function to map over collection

Returns:

Collection after function applied to each element

flatMap

public <R extends ACell> AVector<R> flatMap(Function<? super T,? extends ASequence<R>> mapper)

Overrides:

flatMap in class ASequence<T extends ACell>

concat

public abstract AVector<T> concat(ASequence<? extends T> b)

Description copied from class: ASequence

Concatenates the elements from another sequence to the end of this sequence. Potentially O(n) in size of resulting sequence

Specified by:

concat in class ASequence<T extends ACell>

Parameters:

b - A sequence of values to concatenate.

Returns:

The concatenated sequence, of the same type as this sequence.

reduce

public abstract <R> R reduce(BiFunction<? super R,? super T,? extends R> func,
 R value)

iterator

public Iterator<T> iterator()

Specified by:

iterator in interface Collection<T extends ACell>

Specified by:

iterator in interface Iterable<T extends ACell>

Specified by:

iterator in interface List<T extends ACell>

Overrides:

iterator in class ACollection<T extends ACell>

toArray

public Object[] toArray()

Specified by:

toArray in interface Collection<T extends ACell>

Specified by:

toArray in interface List<T extends ACell>

Overrides:

toArray in class ACollection<T extends ACell>

indexOf

public final int indexOf(Object o)

lastIndexOf

public final int lastIndexOf(Object o)

listIterator

public final ListIterator<T> listIterator(int index)

listIterator

public abstract ListIterator<T> listIterator(long index)

Description copied from class: ASequence

Gets the ListIterator for a long position

Specified by:

listIterator in class ASequence<T extends ACell>

Parameters:

index -

Returns:

ListIterator instance.

isCanonical

public abstract boolean isCanonical()

Returns true if this vector is in canonical format, i.e. suitable as top-level serialised representation of a vector.

Specified by:

isCanonical in class ACell

Returns:

true if the vector is in canonical format, false otherwise

updateRefs

public abstract AVector<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

commonPrefixLength

public abstract long commonPrefixLength(AVector<T> b)

Computes the length of the longest common prefix of this vector and another vector.

Parameters:

b - Any vector

Returns:

Length of the longest common prefix

appendAll

public AVector<T> appendAll(List<T> list)

conj

public final AVector<T> conj(ACell value)

Description copied from class: ASequence

Adds an element to the sequence in the natural position

Specified by:

conj in class ASequence<T extends ACell>

Parameters:

value - Value to add

Returns:

Updated sequence, or null if value is invalid

conjAll

public AVector<T> conjAll(ACollection<? extends T> xs)

Description copied from class: ADataStructure

Adds multiple elements to this data structure, in the natural manner defined by the general data structure type. e.g. append at the end of a vector. This may be more efficient than using 'conj' for individual items.

Overrides:

conjAll in class ADataStructure<T extends ACell>

Parameters:

xs - New elements to add

Returns:

The updated data structure, or null if a failure occurred due to invalid element types

cons

public AList<T> cons(T x)

Description copied from class: ASequence

Prepends an element to this sequence, returning a list.

Specified by:

cons in class ASequence<T extends ACell>

Parameters:

x - Any new element value

Returns:

A list starting with the new element.

next

public abstract AVector<T> next()

Description copied from class: ASequence

Gets the sequence of all elements after the first, or null if no elements remain after the first (i.e. count of 0 or 1)

Specified by:

next in class ASequence<T extends ACell>

Returns:

Sequence following the first element

slice

public abstract AVector<T> slice(long start,
 long end)

Description copied from class: ASequence

Produces a slice of this sequence, beginning with the specified start index and of the given length. The start and end must be contained within this sequence. Will return the same sequence if the start is zero and the length matches this sequence.

Specified by:

slice in class ASequence<T extends ACell>

Parameters:

start - Index of the start element

end - End index(exclusive)

Returns:

A sequence representing the requested slice.

subVector

public final AVector<T> subVector(long start,
 long length)

Description copied from class: ASequence

Gets a vector containing the specified subset of this sequence, or null if range is invalid

Specified by:

subVector in class ASequence<T extends ACell>

Parameters:

start - Start index of sub vector

length - Length of sub vector to produce

Returns:

Sub-vector of this sequence

assoc

public abstract AVector<T> assoc(long i,
 T value)

Description copied from class: ASequence

Updates a value at the given position in the sequence.

Specified by:

assoc in class ASequence<T extends ACell>

Parameters:

i - Index of element to update

value - New element value

Returns:

Updated sequence, or null if index is out of range

empty

public AVector<T> empty()

Description copied from class: ADataStructure

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

Specified by:

empty in class ASequence<T extends ACell>

Returns:

An empty data structure

reverse

public AList<T> reverse()

Description copied from class: ASequence

Reverses a sequence, converting Lists to Vectors and vice versa

Specified by:

reverse in class ASequence<T extends ACell>

Returns:

Reversed sequence

mergeWith

public AVector<T> mergeWith(AVector<T> b,
 MergeFunction<T> func)

Merges this vector with another vector, using the provided merge function. Returns the same vector if the result is equal to this vector, or the other vector if the result is exactly equal to the other vector. The merge function is passed null for elements where one vector is shorter than the other.

Parameters:

b - Another vector

func - A merge function to apply to all elements of this and the other vector

Returns:

A new vector, equal in length to the largest of the two vectors passed @

equals

public final 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 abstract boolean equals(AVector<? super T> a)

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

encodeRaw

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

getElementRefUnsafe

protected abstract Ref<T> getElementRefUnsafe(long i)

Gets an element Ref from this vector, assuming bounds already checked

Parameters:

i - Index at which to get element Ref

Returns:

Element Ref