Package convex.core.data

Class Symbol

java.lang.Object
convex.core.data.AObject
convex.core.data.ACell
convex.core.data.ASymbolic
convex.core.data.Symbol
All Implemented Interfaces:
IValidated, IWriteable
public class Symbol extends ASymbolic

Class representing a Symbol. Symbols are more commonly used in CVM code to refer to functions and values in the execution environment.

Symbols are simply small immutable data Objects, and can be used freely in data structures. They can be used as map keys, however for most normal circumstances Strings or Keywords are more appropriate as keys.

A Symbol comprises: - A name

"Becoming sufficiently familiar with something is a substitute for understanding it." - John Conway

  • Field Details

  • 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 Symbol create​(String name)
      Creates a Symbol with the given name
      Parameters:
      name - Symbol name
      Returns:
      Symbol instance, or null if the Symbol is invalid

    • create

      public static Symbol create​(AString name)
      Creates a Symbol with the given name. Must be an unqualified name.
      Parameters:
      name - Name for Symbol
      Returns:
      Symbol instance, or null if the name is invalid for a Symbol.

    • unsafeCreate

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

    • unsafeCreate

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

    • equals

      public boolean equals​(ACell o)
      Description copied from class: ACell
      Checks for equality with another object. In general, data objects should be considered equal if they have the same canonical representation, i.e. an identical encoding with the same hash value. Subclasses SHOULD override this if offer have a more efficient equals implementation. MUST NOT require reads from Store.
      Overrides:
      equals in class ACell
      Parameters:
      o - Cell to compare with. May be null??
      Returns:
      True if this cell is equal to the other object

    • equals

      public boolean equals​(Symbol sym)
      Tests if this Symbol is equal to another Symbol. Equality is defined by both namespace and name being equal.
      Parameters:
      sym - Symbol to compare with
      Returns:
      true if Symbols are equal, false otherwise

    • 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

    • read

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

    • 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

    • 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.
      Returns:
      The estimated size for the binary representation of this object.

    • 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