Package convex.core.data

Class Keyword

java.lang.Object
convex.core.data.AObject
convex.core.data.ACell
convex.core.data.ASymbolic
convex.core.data.Keyword
All Implemented Interfaces:
IValidated, IWriteable, Comparable<Keyword>
public class Keyword extends ASymbolic implements Comparable<Keyword>
Keyword data type. Intended as human-readable map keys, tags and option specifiers etc. Keywords evaluate to themselves, and as such can be considered as literal constants. "Programs must be written for people to read, and only incidentally for machines to execute." ― Harold Abelson

  • Field Details

    • MAX_CHARS

      public static final int MAX_CHARS
      Maximum size of a Keyword in UTF-8 bytes representation
      See Also:

    • MIN_CHARS

      public static final int MIN_CHARS
      Minimum size of a Keyword in UTF-8 bytes representation
      See Also:

  • 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

    • create

      public static Keyword create(String name)
      Creates a Keyword with the given name
      Parameters:
      name - A String to use as the keyword name
      Returns:
      The new Keyword, or null if the name is invalid for a Keyword

    • unsafeCreate

      public static Keyword unsafeCreate(String rawName)
      Creates a Keyword in an unsafe manner (possibly invalid name), used for testing
      Parameters:
      rawName - Raw Keyword name
      Returns:
      Possibly invalid Keyword

    • unsafeCreate

      public static Keyword unsafeCreate(StringShort rawName)
      Creates a Keyword in an unsafe manner (possibly invalid name), used for testing
      Parameters:
      rawName - Raw Keyword name
      Returns:
      Possibly invalid Keyword

    • create

      public static Keyword create(AString name)
      Creates a Keyword with the given name
      Parameters:
      name - A String to use as the keyword name
      Returns:
      The new Keyword, or null if the name is invalid for a Keyword

    • createChecked

      public static Keyword createChecked(AString aString)
      Creates a Keyword with the given name, throwing an exception if name is not valid
      Parameters:
      aString - A String of at least 1 and no more than 64 UTF-8 bytes in length
      Returns:
      The new Keyword

    • createChecked

      public static Keyword createChecked(String aString)

    • isCanonical

      public boolean isCanonical()
      Description copied from class: ACell
      Returns true if this Cell is in a canonical representation for message writing. Non-canonical objects may be used on a temporary internal basis, they must always be converted to canonical representations for external use (e.g. Encoding).
      Specified by:
      isCanonical in class ACell
      Returns:
      true if the object is in canonical format, false otherwise

    • read

      public static Keyword read(ByteBuffer bb) throws BadFormatException
      Reads a Keyword from the given ByteBuffer, assuming tag already consumed
      Parameters:
      bb - ByteBuffer source
      Returns:
      The Keyword read
      Throws:
      BadFormatException - If a Keyword could not be read correctly

    • 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

    • print

      public boolean print(BlobBuilder bb, 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:
      bb - BlobBuilder to append to
      limit - Limit of printing in string bytes
      Returns:
      True if fully printed within limit, false otherwise

    • 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 likely to contain the entire object when represented in binary format, including the tag byte.
      Specified by:
      estimatedEncodingSize in interface IWriteable
      Returns:
      The estimated size for the binary representation of this object.

    • equals

      public boolean equals(ACell other)
      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.
      Overrides:
      equals in class ACell
      Parameters:
      other - Cell to compare with. May be null.
      Returns:
      True if this cell is equal to the other object

    • compareTo

      public int compareTo(Keyword k)
      Specified by:
      compareTo in interface Comparable<Keyword>

    • validateCell

      public void validateCell() throws InvalidDataException
      Description copied from class: ASymbolic
      Validates this Symbolic value
      Specified by:
      validateCell in class ASymbolic
      Throws:
      InvalidDataException - If the symbolic value is invalid

    • 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 ACell
      Returns:
      The number of Refs in this Cell

    • 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

    • toCanonical

      public ACell toCanonical()
      Description copied from class: ACell
      Converts this Cell to its canonical version. Returns this Cell if already canonical, may be O(n) in size of value otherwise.
      Specified by:
      toCanonical in class ACell
      Returns:
      Canonical version of Cell

    • 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