Package convex.core.data

Class AVector<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.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>
Direct Known Subclasses:
AMapEntry, VectorArray, 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

  • 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​(VectorLeaf<T> listVector)
      Appends a ListVector chunk to this vector. This vector must contain a whole number of chunks
      Parameters:
      listVector - 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 if limit of printing is exceeded otherwise DoS attacks may be possible.
      Specified by:
      print in class AObject
      Parameters:
      sb - BlobBuilder to append to
      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 <R extends ACell> AVector<R> concat​(ASequence<R> 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)

    • spliterator

      public Spliterator<T> spliterator()

    • spliterator

      public abstract Spliterator<T> spliterator​(long position)

    • 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()

    • 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>
      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. 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 <R extends ACell> AVector<R> conj​(R 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>
      Type Parameters:
      R - Type of Value added
      Parameters:
      value - Value to add
      Returns:
      Updated sequence

    • conjAll

      public <R extends ACell> AVector<R> conjAll​(ACollection<R> 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>
      Type Parameters:
      R - Type of Value added
      Parameters:
      xs - New elements to add
      Returns:
      The updated data structure, or null if a failure occurred due to invalid elementtypes

    • 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
      Specified by:
      next in class ASequence<T extends ACell>
      Returns:
      Sequence following the first element

    • slice

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

    • assoc

      public abstract <R extends ACell> AVector<R> assoc​(long i, R 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 ADataStructure<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 @

    • getTag

      public byte getTag()
      Description copied from class: ACell
      Gets the tag byte for this cell. The tag byte is always written as the first byte of the Cell's 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