Package convex.core.data

Class AString

java.lang.Object
convex.core.data.AObject
convex.core.data.ACell
convex.core.data.ACountable<T>
convex.core.data.ABlobLike<CVMChar>
convex.core.data.AString
All Implemented Interfaces:
IValidated, IWriteable, Comparable<AString>
Direct Known Subclasses:
StringShort, StringSlice, StringTree
public abstract class AString extends ABlobLike<CVMChar> implements Comparable<AString>
Abstract base Class representing a CVM String. CVM Strings are UTF-8 byte strings with an immutable, fixed count in bytes. CVM Strings are NOT enforced to be valid UTF-8, for reasons of performance, simplicity and consistent behaviour (e.g. in conversions to and from Blobs). It is up to clients to decide how to represent invalid UTF-8 if necessary.

  • Field Details

    • length

      protected long length

  • Constructor Details

    • AString

      protected AString(long length)

  • Method Details

    • getType

      public AType getType()
      Description copied from class: ACell
      Gets the most specific known runtime Type for this Cell.
      Overrides:
      getType in class ACell
      Returns:
      The Type of this Call

    • 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

    • count

      public long count()
      Description copied from class: ACountable
      Returns the number of elements in this data structure
      Specified by:
      count in class ACountable<CVMChar>
      Returns:
      Number of elements in this collection.

    • printEscaped

      protected abstract void printEscaped(BlobBuilder sb, long start, long end)
      Prints this string as escaped UTF-8
      Parameters:
      sb -

    • empty

      public final StringShort empty()
      Returns the singleton empty String
      Specified by:
      empty in class ABlobLike<CVMChar>
      Returns:
      An empty Countable value

    • charAt

      public final int charAt(long i)
      Gets the Unicode character at position i, or -1 if not valid
      Parameters:
      i - Index into String (byte position)
      Returns:
      Unicode code point, or -1 if not a valid code point at this position

    • intAt

      public int intAt(long index)
      Gets 32 bytes integer at given position. Extends with 255 (invalid UTF-8) if needed. The main purpose of this function is to enable fast peeking at UTF-8 characters
      Parameters:
      index - Index into String (byte position)
      Returns:
      Raw integer value

    • byteAt

      public abstract byte byteAt(long i)
      Gets a byte at the specified index. Returns -1 (0xff) if outside String.
      Specified by:
      byteAt in class ABlobLike<CVMChar>
      Parameters:
      i - Index into String (byte position)
      Returns:
      Raw byte value

    • get

      public CVMChar get(long i)
      Gets the Character at the specified point in the String, or null if there is no valid Character at this position.
      Specified by:
      get in class ACountable<CVMChar>
      Parameters:
      i - Index of element to get
      Returns:
      CVMChar instance, or null for invalid UTF-8 or any character out of the string bounds

    • getElementRef

      public Ref<CVMChar> 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<CVMChar>
      Parameters:
      i - Index of element to get
      Returns:
      Element at the specified index

    • getBytes

      public int getBytes(byte[] dest, int destOffset)
      Description copied from class: ABlobLike
      Copies the bytes from this instance to a given destination
      Specified by:
      getBytes in class ABlobLike<CVMChar>
      Parameters:
      dest - Destination array
      destOffset - Offset into destination array
      Returns:
      End position in destination array after writing

    • compareTo

      public abstract int compareTo(AString o)
      Specified by:
      compareTo in interface Comparable<AString>

    • toString

      public final String toString()
      Description copied from class: ACell
      Returns the Java String representation of this Cell. The String representation is intended to be a easy-to-read textual representation of the Cell's data content.
      Overrides:
      toString in class ACell

    • toCVMString

      public AString toCVMString(long limit)
      Description copied from class: ACell
      Returns the CVM String representation of this Cell. Normally, this is as printed, but may be different for some types. MUST return null in O(1) time if the length of the CVM String would exceed limit. The String representation is intended to be a easy-to-read textual representation of the Cell's data content.
      Overrides:
      toCVMString in class ACell
      Parameters:
      limit - Limit of CVM String length in UTF-8 bytes
      Returns:
      CVM String, or null if limit exceeded

    • append

      public AString append(AString b)
      Append a CVM String to this CVM String. Potentially O(n). Concatenates raw UTF-8 bytes.
      Parameters:
      b - String to append
      Returns:
      Concatenated String

    • slice

      public abstract AString slice(long start, long end)
      Gets a slice of this string, or null if not a valid slice
      Specified by:
      slice in class ACountable<CVMChar>
      Parameters:
      start - Start index (inclusive)
      end - End index (Exclusive)
      Returns:
      Specified substring

    • split

      public AVector<AString> split(CVMChar c)
      Splits this string by the given character The result will always have at least one String, and as many additional Strings as the split character occurs.
      Parameters:
      c - CMVChar instance with which to split
      Returns:
      Vector of Strings, excluding the split character.

    • 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 abstract int encodeRaw(byte[] bs, int pos)
      Encode the data of this String. Assumes tag already written
      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

    • writeRawData

      public abstract int writeRawData(byte[] bs, int pos)
      Write the raw UTF-8 data of this String to a byte array.
      Parameters:
      bs - Destination byte array
      pos - Position in target array to write to
      Returns:
      End position in array after writing

    • getTag

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

    • hashCode

      public final int hashCode()
      Gets a Java hashCode for this CVM String. Use the hashcode of underlying Blob
      Overrides:
      hashCode in class ACell
      Returns:
      integer hash code.

    • toBlob

      public abstract ABlob toBlob()
      Converts this String to a Blob representation. Must round trip all values.
      Returns:
      Blob representation of UTF-8 String

    • append

      public AString append(String string)
      Convenience method to add a Java String to a CVM String. Not particularly efficient.
      Parameters:
      string - String to append
      Returns:
      CVM String