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 Boolean eq​(ACell[] values)

    • ge

      public static Boolean ge​(ACell[] values)

    • gt

      public static Boolean gt​(ACell[] values)

    • le

      public static Boolean le​(ACell[] values)

    • lt

      public static Boolean lt​(ACell[] values)

    • 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 APrimitive plus​(ACell[] args)

    • plusDouble

      public static CVMDouble plusDouble​(ACell[] args)

    • minus

      public static APrimitive minus​(ACell[] args)

    • minusDouble

      public static APrimitive minusDouble​(ACell[] args)

    • times

      public static APrimitive times​(ACell[] args)

    • timesDouble

      public static APrimitive timesDouble​(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 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

    • 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:
      Less than 0 if a is smaller, greater than 0 if a is larger, 0 if a equals b

    • compare

      public static long compare​(long a, long b)
      Compares two long values numerically, according to Java primitive comparisons.
      Parameters:
      a - First number
      b - Second number
      Returns:
      -1 if a is less than b, 1 if greater, 0 is they are equal

    • ensureNumber

      public static INumeric ensureNumber​(ACell a)
      Converts a CVM value to the standard numeric representation. Result will be one of:
      • Long for Byte, 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
      Parameters:
      val - Value to test
      Returns:
      True if a number, false otherwise

    • inc

      public static CVMLong inc​(ACell x)
      Increments a Long value
      Parameters:
      x - Value to increment
      Returns:
      Long Value, or null if conversion fails

    • dec

      public static CVMLong dec​(ACell x)
      Decrements a Long value
      Parameters:
      x - Value to decrement
      Returns:
      Long Value, or null if conversion fails

    • 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 Long 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.
      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 Long value.
      Parameters:
      a - Value to cast
      Returns:
      CVMLong value, or null if not convertible

    • castByte

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

    • toCharacter

      public static CVMChar toCharacter​(ACell a)
      Casts a value to a Character
      Parameters:
      a - Value to cast
      Returns:
      CVMChar value, or null if cast fails

    • vec

      public static <T extends ACell> AVector<T> vec​(Object o)
      Converts any data structure to a vector
      Parameters:
      o - Object to attemptto 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

    • str

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

    • 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, addresses, hashes and hex strings
      Parameters:
      a - Object to convert to a Blob
      Returns:
      Blob value, or null if not convertable 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 argument to a keyword.
      Parameters:
      a - Value to cast
      Returns:
      Keyword if correctly constructed, or null if a failure occurs

    • ensureSymbol

      public static Symbol ensureSymbol​(ACell a)
      Coerces an named argument to 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 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 cast fails

    • keys

      public static <R extends ACell> AVector<R> keys​(ACell a)
      Returns the vector of keys of a map, or null if the object is not a 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 IAssociative 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. Returns null if the argument is not a set.
      Type Parameters:
      T - Type of set element
      Parameters:
      a - Value to cast
      Returns:
      A set instance, or null if the argument cannot be converted to 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 object)
      Implicitly casts the argument to a Blob
      Parameters:
      object - Value to cast to Blob
      Returns:
      Blob instance, or null if cast fails

    • ensureString

      public static AString ensureString​(ACell a)
      Implicitly casts the argument to a CVM String
      Parameters:
      a - Value to cast to a String
      Returns:
      AString instance, or null if cast fails

    • 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

    • mod

      public static CVMLong mod​(ACell a, ACell b)
      Compute mode.
      Parameters:
      a - First numeric argument (numerator)
      b - First numeric argument (divisor)
      Returns:
      Numeric value or null if cast fails

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