Package convex.core.lang

Class RT

java.lang.Object
convex.core.lang.RT
public class RT extends Object
Static utility class for Runtime functions. Mostly low-level support for Core language capabilities, which will be wrapped as functions in the initial execution environment. "Low-level programming is good for the programmer's soul." — John Carmack

  • Constructor Details

    • RT

      public RT()

  • Method Details

    • allEqual

      public static <T extends ACell> Boolean allEqual(T[] values)
      Returns true if all elements in an array are equal. Nulls are equal to null only.
      Type Parameters:
      T - Type of values
      Parameters:
      values - Array of values
      Returns:
      True if all values are equal

    • eq

      public static CVMBool eq(ACell[] values)

    • ge

      public static CVMBool ge(ACell[] values)

    • gt

      public static CVMBool gt(ACell[] values)

    • le

      public static CVMBool le(ACell[] values)

    • lt

      public static CVMBool lt(ACell[] values)

    • min

      public static ACell min(ACell[] values)
      Gets the minimum of a set of numeric values
      Parameters:
      values - Arguments for which to compute minimum value
      Returns:
      minimum value, or null if any argument is non-numeric

    • min

      public static ACell min(ACell a, ACell b)
      Gets the minimum of two numeric values
      Parameters:
      a - First value
      b - Second value
      Returns:
      minimum value, or null if any argument is non-numeric

    • max

      public static ACell max(ACell[] values)
      Gets the minimum of a set of numeric values
      Parameters:
      values - Arguments for which to compute minimum value
      Returns:
      minimum value, or null if any argument is non-numeric

    • max

      public static ACell max(ACell a, ACell b)
      Gets the minimum of two numeric values
      Parameters:
      a - First value
      b - Second value
      Returns:
      minimum value, or null if any argument is non-numeric

    • commonNumericType

      public static Class<?> commonNumericType(ACell[] args)
      Get the target common numeric type for a given set of arguments. - Integers upcast to Long - Anything else upcasts to Double
      Parameters:
      args - Argument array
      Returns:
      The target numeric type, or null if there is a non-numeric argument

    • findNonNumeric

      public static int findNonNumeric(ACell[] args)
      Finds the first non-numeric value in an array. Used for error reporting.
      Parameters:
      args - Argument array
      Returns:
      First non-numeric value, or null if not found.

    • numericType

      public static Class<?> numericType(ACell a)
      Gets the numeric class of an object
      Parameters:
      a - Numerical value
      Returns:
      Long.class or Double.class if cast possible, or null if not numeric.

    • plus

      public static ANumeric plus(ACell[] args)

    • minus

      public static ANumeric minus(ACell[] args)

    • multiply

      public static ANumeric multiply(ACell... args)

    • divide

      public static CVMDouble divide(ACell[] args)

    • pow

      public static CVMDouble pow(ACell[] args)
      Computes the result of a pow operation. Returns null if a cast fails.
      Parameters:
      args - Argument array, should be length 2
      Returns:
      Result of exponentiation

    • exp

      public static CVMDouble exp(ACell arg)
      Computes the result of a exp operation. Returns null if a cast fails.
      Parameters:
      arg - Numeric value
      Returns:
      Numeric result, or null

    • floor

      public static CVMDouble floor(ACell a)
      Gets the floor a number after casting to a double. Equivalent to java.lang.StrictMath.floor(...)
      Parameters:
      a - Numerical Value
      Returns:
      The floor of the number, or null if cast fails

    • ceil

      public static CVMDouble ceil(ACell a)
      Gets the ceiling of a number after casting to a Double. Equivalent to java.lang.StrictMath.ceil(...)
      Parameters:
      a - Numerical Value
      Returns:
      The ceiling of the number, or null if cast fails

    • sqrt

      public static CVMDouble sqrt(ACell a)
      Gets the exact positive square root of a number after casting to a Double. Returns NaN for negative numbers.
      Parameters:
      a - Numerical Value
      Returns:
      The square root of the number, or null if cast fails

    • splitmix64Update

      public static long splitmix64Update(long seed)
      Compute a SplitMix64 update. Component for splittable PRNG. See: https://xorshift.di.unimi.it/splitmix64.c
      Parameters:
      seed - Initial SplitMix64 seed
      Returns:
      Updated SplitMix64 seed

    • splitmix64Calc

      public static long splitmix64Calc(long seed)
      Compute a SplitMix64 value for a given seed. Component for splittabe PRNG See: https://xorshift.di.unimi.it/splitmix64.c
      Parameters:
      seed - Initial SplitMix64 seed
      Returns:
      Updated SplitMix64 seed

    • doubleFromUnsignedLong

      public static double doubleFromUnsignedLong(long a)
      Converts a long value, treated as unsigned, to a double. Useful for randomness
      Parameters:
      a - Long value, treated as unsigned
      Returns:
      Double value of long

    • abs

      public static APrimitive abs(ACell a)
      Gets the absolute value of a numeric value. Supports double and long.
      Parameters:
      a - Numeric CVM value
      Returns:
      Absolute value, or null if not a numeric value

    • signum

      public static ACell signum(ACell a)
      Gets the signum of a numeric value
      Parameters:
      a - Numeric value
      Returns:
      value of -1, 0 or 1, NaN is argument is NaN, or null if the argument is not numeric

    • compare

      public static Long compare(ACell a, ACell b, Long nanValue)
      Compares two objects representing numbers numerically.
      Parameters:
      a - First numeric value
      b - Second numeric value
      nanValue - Value to return in case of a NaN result
      Returns:
      -1 if a is smaller, 1 if a is larger, 0 if a equals b, null if either value non-numeric, NaN if either value is NaN

    • ensureNumber

      public static ANumeric ensureNumber(ACell a)
      Converts a CVM value to the standard numeric representation. Result will be one of:
      • Long for Long
      • Double for Double
      • null for any non-numeric value
      Parameters:
      a - Value to convert to numeric representation
      Returns:
      The number value, or null if cannot be converted

    • isNumber

      public static boolean isNumber(ACell val)
      Tests if a Value is a valid numerical value type. Note: Returns false for null, but true for NaN
      Parameters:
      val - Value to test
      Returns:
      True if a number, false otherwise

    • castDouble

      public static CVMDouble castDouble(ACell a)
      Converts a numerical value to a CVM Double.
      Parameters:
      a - Value to cast
      Returns:
      Double value, or null if not convertible

    • ensureDouble

      public static CVMDouble ensureDouble(ACell a)
      Ensures the argument is a CVM Double value.
      Parameters:
      a - Value to cast
      Returns:
      CVMDouble value, or null if not convertible

    • castLong

      public static CVMLong castLong(ACell a)
      Converts a numerical value to a CVM Long. Doubles and floats will be converted if possible. Integers are truncated to last 64 bits
      Parameters:
      a - Value to cast
      Returns:
      Long value, or null if not convertible

    • ensureLong

      public static CVMLong ensureLong(ACell a)
      Ensures the argument is a CVM Integer within Long range.
      Parameters:
      a - Value to cast
      Returns:
      CVMLong value, or null if not convertible / within long range.

    • castInteger

      public static AInteger castInteger(ACell a)
      Converts a numerical value to a CVM Integer. Doubles and floats will be converted if possible.
      Parameters:
      a - Value to cast
      Returns:
      Integer value, or null if not convertible

    • ensureInteger

      public static AInteger ensureInteger(ACell a)
      Ensures the argument is a CVM Integer value.
      Parameters:
      a - Value to cast
      Returns:
      AInteger value, or null if not convertible

    • castByte

      public static CVMLong castByte(ACell a)
      Explicitly converts a numerical value to a CVM Byte. Doubles and floats will be converted if possible. Takes last byte of Blobs
      Parameters:
      a - Value to cast
      Returns:
      Long value, or null if not convertible

    • vec

      public static <T extends ACell> AVector<T> vec(Object o)
      Converts any data structure to a vector
      Parameters:
      o - Object to attempt to convert to a Vector
      Returns:
      AVector instance, or null if not convertible

    • castVector

      public static <T extends ACell> AVector<T> castVector(ACell o)
      Converts any countable data structure to a vector. Might be O(n)
      Parameters:
      o - Value to convert
      Returns:
      AVector instance, or null if conversion fails

    • castSet

      public static <T extends ACell> ASet<T> castSet(ACell o)
      Converts any collection to a set
      Parameters:
      o - Value to cast
      Returns:
      Set instance, or null if cast fails

    • vec

      public static <T extends ACell> AVector<T> vec(ACollection<T> coll)
      Converts any collection to a vector. Always succeeds, but may have O(n) cost Null values are converted to empty vector (considered as empty sequence)
      Parameters:
      coll - Collection to convert to a Vector
      Returns:
      Vector instance

    • sequence

      public static <T extends ACell> ASequence<T> sequence(ACell o)
      Converts any collection of cells into a Sequence data structure. Potentially O(n) in size of collection. Nulls are converted to an empty vector. Returns null if conversion is not possible.
      Type Parameters:
      T - Type of cell in collection
      Parameters:
      o - An object that contains a collection of cells
      Returns:
      An ASequence instance, or null if the argument cannot be converted to a sequence

    • ensureSequence

      public static <T extends ACell> ASequence<T> ensureSequence(ACell o)
      Ensures argument is a sequence data structure. Nulls are converted to an empty vector. Returns null if conversion is not possible.
      Type Parameters:
      T - Type of sequence elements
      Parameters:
      o - Value to cast to sequence
      Returns:
      An ASequence instance, or null if the argument cannot be converted to a sequence

    • nth

      public static <T extends ACell> T nth(ACell o, long i)
      Gets the nth element from a sequential collection. Throws an exception if access is out of bounds - caller responsibility to check bounds first
      Type Parameters:
      T - Type of element in collection
      Parameters:
      o - Countable Value
      i - Index of element to get
      Returns:
      Element from collection at the specified position

    • nth

      public static <T extends ACell> T nth(Object o, long i)
      Variant of nth that also handles Java Arrays. Used for destructuring.
      Type Parameters:
      T - Return type
      Parameters:
      o - Object to check for indexed element
      i - Index to check
      Returns:
      Element at specified index

    • count

      public static Long count(Object o)
      Gets the count of elements in a collection or Java array. Null is considered an empty collection.
      Parameters:
      o - An Object representing a collection of items to be counted
      Returns:
      The count of elements in the collection, or null if not countable

    • count

      public static Long count(ACell a)
      Gets the count of elements in a countable data structure. Null is considered an empty collection.
      Parameters:
      a - Any Cell potentially representing a collection of items to be counted
      Returns:
      The count of elements in the collection, or null if not countable

    • str

      public static AString str(ACell[] args)
      Converts arguments to an AString representation. Handles:
      • CVM Strings (unchanged)
      • Blobs (converted to hex)
      • Numbers (converted to canonical numeric representation)
      • Other Objects (printed in canonical format)
      Parameters:
      args - Values to convert to String
      Returns:
      AString value, or null if allowable String length exceeded

    • print

      public static boolean print(BlobBuilder bb, ACell a, long limit)
      Prints a cell to a BlobBuilder, up to a specified limit of bytes
      Parameters:
      bb - BlobBuilder instance
      a - Cell to print (may be nil)
      limit - Limit of printing
      Returns:
      True if within limit, false if exceeded (output may still be partially written to BlobBuilder)

    • print

      public static AString print(ACell a, long limit)
      Prints a cell to a BlobBuilder, up to a specified limit of bytes WARNING: May return null
      Parameters:
      a - Cell to print (may be nil)
      limit - Limit of printing in bytes
      Returns:
      Printed String, or null if limit exceeded

    • print

      public static AString print(ACell a)
      Prints a value to a String as long as the result fits within a given print limit. WARNING: May return null
      Parameters:
      a - Cell value to print
      Returns:
      Printed String, or null if print limit exceeded

    • str

      public static AString str(ACell a)
      Converts a value to a CVM String representation. Required to work for all valid Cells.
      Parameters:
      a - Value to convert to a CVM String
      Returns:
      CVM String representation of object

    • toString

      public static String toString(ACell a)
      Converts a value to a Java String representation
      Parameters:
      a - Any CVM value
      Returns:
      Java String representation. May be "nil".

    • toString

      public static String toString(ACell a, long limit)
      Converts a value to a Java String representation
      Parameters:
      a - Any CVM value
      limit - Limit of string printing
      Returns:
      Java String representation. May be "nil". May include message if print limit exceeded

    • name

      public static AString name(ACell a)
      Gets the name from a CVM value. Supports Strings, Keywords and Symbols.
      Parameters:
      a - Value to cast to a name
      Returns:
      Name of the argument, or null if not Named

    • cons

      public static <T extends ACell> AList<T> cons(T x, ASequence<?> xs)
      Prepends an element to a sequential data structure to create a new list. May be O(n). The new element will always be in position 0
      Type Parameters:
      T - Type of elements
      Parameters:
      x - Element to prepend
      xs - Any sequential object, or null (will be treated as empty sequence)
      Returns:
      A new list with the cons'ed element at the start

    • cons

      public static <T extends ACell> AList<T> cons(T x, T y, ACell xs)
      Prepends two elements to a sequential data structure. The new elements will always be in position 0 and 1
      Type Parameters:
      T - Type of elements
      Parameters:
      x - Element to prepend at position 0
      y - Element to prepend at position 1
      xs - Any sequential object, or null (will be treated as empty sequence)
      Returns:
      A new list with the cons'ed elements at the start

    • cons

      public static <T extends ACell> AList<T> cons(T x, T y, T z, ACell xs)
      Prepends three elements to a sequential data structure. The new elements will always be in position 0, 1 and 2
      Type Parameters:
      T - Type of elements
      Parameters:
      x - Element to prepend at position 0
      y - Element to prepend at position 1
      z - Element to prepend at position 2
      xs - Any sequential object
      Returns:
      A new list with the cons'ed elements at the start

    • castFunction

      public static <T extends ACell> AFn<T> castFunction(ACell a)
      Coerces an argument to a function interface. Certain values e.g. Keywords can be used / applied in function position.
      Type Parameters:
      T - Function return type
      Parameters:
      a - Value to cast to a function
      Returns:
      AFn instance, or null if the argument cannot be coerced to a function.

    • ensureFunction

      public static <T extends ACell> AFn<T> ensureFunction(ACell a)
      Ensure the argument is a valid CVM function. Returns null otherwise.
      Type Parameters:
      T - Function return type
      Parameters:
      a - Value to cast to a function
      Returns:
      IFn instance, or null if the argument cannot be coerced to a function.

    • castAddress

      public static Address castAddress(ACell a)
      Casts the argument to a valid Address. Handles:
      • Strings, which are interpreted as 16-character hex strings
      • Addresses, which are returned unchanged
      • Blobs, which are converted to addresses if and only if they are of the correct length (8 bytes)
      • Numeric Longs, which are converted to the equivalent Address
      Parameters:
      a - Value to cast to an Address
      Returns:
      Address value or null if not castable to a valid address

    • toAddress

      public static Address toAddress(Object a)
      Casts an arbitrary value to an Address
      Parameters:
      a - Value to cast. Strings or CVM values accepted
      Returns:
      Address instance, or null if not convertible

    • ensureAddress

      public static Address ensureAddress(ACell a)
      Ensures the argument is a valid Address.
      Parameters:
      a - Value to cast
      Returns:
      Address value or null if not a valid address

    • ensureAccountKey

      public static AccountKey ensureAccountKey(ACell a)
      Implicit cast to an AccountKey. Accepts blobs of correct length
      Parameters:
      a - Value to cast
      Returns:
      AccountKey instance, or null if coercion fails

    • castAccountKey

      public static AccountKey castAccountKey(ACell a)
      Coerce to an AccountKey. Accepts strings and blobs of correct length
      Parameters:
      a - Value to cast
      Returns:
      AccountKey instance, or null if coercion fails

    • castBlob

      public static ABlob castBlob(ACell a)
      Converts an object to a canonical blob representation. Handles blobs, longs addresses, hashes and hex strings
      Parameters:
      a - Value to convert to a Blob
      Returns:
      Blob value, or null if not convertible to a blob

    • ensureMap

      public static <K extends ACell, V extends ACell> AMap<K,V> ensureMap(ACell a)
      Converts the argument to a non-null Map. Nulls are implicitly converted to the empty map.
      Type Parameters:
      K - Type of map keys
      V - Type of map values
      Parameters:
      a - Value to cast
      Returns:
      Map instance, or null if argument cannot be converted to a map

    • get

      public static ACell get(ADataStructure<?> coll, ACell key)
      Gets an element from a data structure using the given key.
      Parameters:
      coll - Collection to query
      key - Key to look up in collection
      Returns:
      Value from collection with the specified key, or null if not found.

    • get

      public static ACell get(ADataStructure<?> coll, ACell key, ACell notFound)
      Gets an element from a data structure using the given key. Returns the notFound parameter if the data structure does not have the specified key
      Parameters:
      coll - Collection to query
      key - Key to look up in collection
      notFound - Value to return if the lookup failed
      Returns:
      Value from collection with the specified key, or notFound argument if not found.

    • bool

      public static boolean bool(ACell a)
      Converts any CVM value to a boolean value. An value is considered falsey if null or equal to CVMBool.FALSE, truthy otherwise
      Parameters:
      a - Object to convert to boolean value
      Returns:
      true if object is truthy, false otherwise

    • ensureMapEntry

      public static <K extends ACell, V extends ACell> MapEntry<K,V> ensureMapEntry(ACell x)
      Converts an object to a map entry. Handles MapEntries and length 2 Vectors.
      Type Parameters:
      K - Type of map key
      V - Type of map value
      Parameters:
      x - Value to cast
      Returns:
      MapEntry instance, or null if conversion fails

    • ensureHash

      public static Hash ensureHash(ACell o)
      Coerces to Hash type. Converts blobs of correct length.
      Parameters:
      o - Value to cast
      Returns:
      Hash instance, or null if conversion not possible

    • castKeyword

      public static Keyword castKeyword(ACell a)
      Coerces an named value to a Keyword.
      Parameters:
      a - Value to cast
      Returns:
      Valid Keyword if correctly constructed, or null if a failure occurs

    • ensureSymbol

      public static Symbol ensureSymbol(ACell a)
      Ensures the argument is a Symbol.
      Parameters:
      a - Value to cast
      Returns:
      Symbol if correctly constructed, or null if a failure occurs

    • ensureDataStructure

      public static <E extends ACell> ADataStructure<E> ensureDataStructure(ACell a)
      Casts to an ADataStructure instance
      Type Parameters:
      E - Type of data structure element
      Parameters:
      a - Value to cast
      Returns:
      ADataStructure instance, or null if not a data structure

    • ensureCountable

      public static <E extends ACell> ACountable<E> ensureCountable(ACell a)
      Casts to an ACountable instance
      Type Parameters:
      E - Type of countable element
      Parameters:
      a - Value to cast
      Returns:
      ADataStructure instance, or null if not a data structure

    • isBoolean

      public static boolean isBoolean(ACell value)
      Tests if a value is one of the canonical boolean values 'true' or 'false'
      Parameters:
      value - Value to test
      Returns:
      True if the value is a canonical boolean value.

    • concat

      public static ASequence<?> concat(ASequence<?> a, ASequence<?> b)
      Concatenates two sequences. Ignores nulls.
      Parameters:
      a - First sequence. Will be used to determine the type of the result if not null.
      b - Second sequence. Will be the result if the first parameter is null.
      Returns:
      Concatenated Sequence

    • validate

      public static void validate(Object o) throws InvalidDataException
      Validates an object. Might be a Cell or Ref
      Parameters:
      o - Object to validate
      Throws:
      InvalidDataException - For any validation failure

    • validateCell

      public static void validateCell(ACell o) throws InvalidDataException
      Validate a Cell.
      Parameters:
      o - Object to validate
      Throws:
      InvalidDataException - For any validation failure

    • assoc

      public static <R extends ACell> ADataStructure<R> assoc(ADataStructure<R> coll, ACell key, ACell value)
      Associates a key position with a given value in an associative data structure
      Parameters:
      coll - Any associative data structure
      key - Key to update or add
      value - Value to associate with key
      Returns:
      Updated data structure, or null if implicit cast of key or value to required type fails

    • keys

      public static <R extends ACell> AVector<R> keys(ACell a)
      Returns a Vector of keys of a Map, or null if the object is not a Map WARNING: Potentially O(n) in size of Map
      Parameters:
      a - Value to extract keys from (i.e. a Map)
      Returns:
      Vector of keys in the Map

    • values

      public static <R extends ACell> AVector<R> values(ACell a)
      Returns the vector of values of a map, or null if the object is not a map
      Parameters:
      a - Value to extract values from (i.e. a Map)
      Returns:
      Vector of values from a map, or null if the object is not a map

    • ensureAssociative

      public static ADataStructure<?> ensureAssociative(ACell o)
      Ensures the argument is an associative data structure instance. A null argument is considered an empty map.
      Parameters:
      o - Value to cast
      Returns:
      IAssociative instance, or null if conversion is not possible

    • ensureSet

      public static <T extends ACell> ASet<T> ensureSet(ACell a)
      Ensures the value is a Set. null is converted to the empty Set.
      Type Parameters:
      T - Type of Set element
      Parameters:
      a - Value to cast
      Returns:
      A Set instance, or null if the argument is not a Set

    • ensureHashMap

      public static <K extends ACell, V extends ACell> AHashMap<K,V> ensureHashMap(ACell a)
      Casts the argument to a hashmap. null is converted to the empty HashMap.
      Type Parameters:
      K - Type of keys
      V - Type of values
      Parameters:
      a - Any object
      Returns:
      AHashMap instance, or null if not a hash map

    • ensureBlob

      public static ABlob ensureBlob(ACell a)
      Implicitly casts the argument to a Blob
      Parameters:
      a - Value to cast to Blob
      Returns:
      Blob instance, or null if cast fails

    • ensureString

      public static AString ensureString(ACell a)
      Ensures the argument is a CVM String
      Parameters:
      a - Value to cast to a String
      Returns:
      AString instance, or null if argument is not a String

    • isValidAmount

      public static boolean isValidAmount(long amount)

    • cvm

      public static <T extends ACell> T cvm(Object o)
      Converts a Java value to a CVM type.
      Parameters:
      o - Any Java Object
      Returns:
      Valid CVM type

    • jvm

      public static <T> T jvm(ACell o)
      Converts a CVM value to equivalent JVM value
      Parameters:
      o - Value to convert to JVM type
      Returns:
      Java value, or unchanged input

    • json

      public static <T> T json(ACell o)
      Converts a CVM value to equivalent JSON value as expressed in equivalent JVM types. Note some special one-way conversions that are required because JSON is not sufficiently expressive for all CVM types: - Address becomes a Number (Long type) - Lists and Vectors both become an Array (Java List type) - Characters become a String - Blobs become a hex string representation '0x....'
      Parameters:
      o - Value to convert to JVM type
      Returns:
      Java value which represents JSON object

    • getType

      public static AType getType(ACell a)
      Get the runtime Type of any CVM value
      Parameters:
      a - Any CVM value
      Returns:
      Type of CVM value

    • isNaN

      public static boolean isNaN(ACell val)

    • isCVM

      public static boolean isCVM(ACell a)
      Checks if a Cell is a valid CVM value
      Parameters:
      a - Cell to check
      Returns:
      True if CVM VAlue, false otherwise

    • ensureChar

      public static CVMChar ensureChar(ACell a)
      Implicitly casts argument to a CVM Character
      Parameters:
      a - Value to cast
      Returns:
      CVMChar instance, or null if not implicitly castable

    • callableAddress

      public static Address callableAddress(ACell a)
      Gets a callable Address from a cell value. Handles regular Addresses and scoped call targets
      Parameters:
      a - Value to extract Address from
      Returns:
      Address of callable target, or null if not a valid call target