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 Summary

Constructors

Constructor	Description
RT()

Method Summary

Modifier and Type	Method	Description
static APrimitive	abs(ACell a)	Gets the absolute value of a numeric value.
static <T extends ACell> Boolean	allEqual(T[] values)	Returns true if all elements in an array are equal.
static Long	argumentCount(Object o)	Gets the count of objects in a collection for destructuring (may be data structure or Java Array)
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
static boolean	bool(ACell a)	Converts any CVM value to a boolean value.
static Address	callableAddress(ACell a)	Gets a callable Address from a cell value.
static AccountKey	castAccountKey(ACell a)	Coerce to an AccountKey.
static Address	castAddress(ACell a)	Casts the argument to a valid Address.
static ABlob	castBlob(ACell a)	Converts an object to a canonical blob representation.
static CVMLong	castByte(ACell a)	Explicitly converts a numerical value to a CVM Byte.
static CVMDouble	castDouble(ACell a)	Converts a numerical value to a CVM Double.
static <T extends ACell> AFn<T>	castFunction(ACell a)	Coerces an argument to a function interface.
static AInteger	castInteger(ACell a)	Converts a numerical value to a CVM Integer.
static Keyword	castKeyword(ACell a)	Coerces an named value to a Keyword.
static CVMLong	castLong(ACell a)	Converts a numerical value to a CVM Long.
static <T extends ACell> ASet<T>	castSet(ACell o)	Converts any collection to a set
static <T extends ACell> AVector<T>	castVector(ACell o)	Converts any countable data structure to a vector.
static CVMDouble	ceil(ACell a)	Gets the ceiling of a number after casting to a Double.
static Class<?>	commonNumericType(ACell[] args)	Get the target common numeric type for a given set of arguments.
static Long	compare(ACell a, ACell b, Long nanValue)	Compares two objects representing numbers numerically.
static ASequence<?>	concat(ASequence<?> a, ASequence<?> b)	Concatenates two sequences.
static <T extends ACell> AList<T>	cons(T x, ASequence<?> xs)	Prepends an element to a sequential data structure to create a new list.
static <T extends ACell> AList<T>	cons(T x, T y, ACell xs)	Prepends two elements to a sequential data structure.
static <T extends ACell> AList<T>	cons(T x, T y, T z, ACell xs)	Prepends three elements to a sequential data structure.
static Long	count(ACell a)	Gets the count of elements in a countable data structure.
static Long	count(Object o)	Gets the count of elements in a collection or Java array.
static <T extends ACell> T	cvm(Object o)	Converts a Java value to a CVM type.
static CVMDouble	divide(ACell[] args)
static double	doubleFromUnsignedLong(long a)	Converts a long value, treated as unsigned, to a double.
static AccountKey	ensureAccountKey(ACell a)	Implicit cast to an AccountKey.
static Address	ensureAddress(ACell a)	Ensures the argument is a valid Address.
static ADataStructure<?>	ensureAssociative(ACell o)	Ensures the argument is an associative data structure instance.
static ABlob	ensureBlob(ACell a)	Implicitly casts the argument to a Blob
static <V extends ACell> ABlobLike<V>	ensureBlobLike(ACell a)
static CVMChar	ensureChar(ACell a)	Implicitly casts argument to a CVM Character
static <E extends ACell> ACountable<E>	ensureCountable(ACell a)	Casts to an ACountable instance
static <E extends ACell> ADataStructure<E>	ensureDataStructure(ACell a)	Casts to an ADataStructure instance
static CVMDouble	ensureDouble(ACell a)	Ensures the argument is a CVM Double value.
static <T extends ACell> AFn<T>	ensureFunction(ACell a)	Ensure the argument is a valid CVM function.
static Hash	ensureHash(ACell o)	Coerces to Hash type.
static <K extends ACell, V extends ACell> AHashMap<K,V>	ensureHashMap(ACell a)	Casts the argument to a hashmap.
static AInteger	ensureInteger(ACell a)	Ensures the argument is a CVM Integer value.
static CVMLong	ensureLong(ACell a)	Ensures the argument is a CVM Integer within Long range.
static <K extends ACell, V extends ACell> AMap<K,V>	ensureMap(ACell a)	Converts the argument to a non-null Map.
static <K extends ACell, V extends ACell> MapEntry<K,V>	ensureMapEntry(ACell x)	Converts an object to a map entry.
static ANumeric	ensureNumber(ACell a)	Converts a CVM value to the standard numeric representation.
static <T extends ACell> ASequence<T>	ensureSequence(ACell o)	Ensures argument is a sequence data structure.
static <T extends ACell> ASet<T>	ensureSet(ACell a)	Ensures the value is a Set.
static AString	ensureString(ACell a)	Ensures the argument is a CVM String
static Symbol	ensureSymbol(ACell a)	Ensures the argument is a Symbol.
static ATransaction	ensureTransaction(ACell maybeTx)	Casts to a transaction record, or null if not castable
static <T extends ACell> AVector<T>	ensureVector(ACell o)	Ensures argument is a Vector data structure.
static CVMBool	eq(ACell[] values)
static CVMDouble	exp(ACell arg)	Computes the result of a exp operation.
static int	findNonNumeric(ACell[] args)	Finds the first non-numeric value in an array.
static CVMDouble	floor(ACell a)	Gets the floor a number after casting to a double.
static CVMBool	ge(ACell[] values)
static ACell	get(ADataStructure<?> coll, ACell key)	Gets an element from a data structure using the given key.
static ACell	get(ADataStructure<?> coll, ACell key, ACell notFound)	Gets an element from a data structure using the given key.
static AType	getType(ACell a)	Get the runtime Type of any CVM value
static CVMBool	gt(ACell[] values)
static boolean	isBoolean(ACell value)	Tests if a value is one of the canonical boolean values 'true' or 'false'
static boolean	isCountable(ACell val)
static boolean	isNaN(ACell val)
static boolean	isNumber(ACell val)	Tests if a Value is a valid numerical value type.
static boolean	isValidAmount(long amount)
static <T> T	json(ACell o)	Converts a CVM value to equivalent JSON value as expressed in equivalent JVM types.
static String	jsonKey(ACell k)	Gets a String from a value suitable for use as a JSON map key
static HashMap<String,Object>	jsonMap(AMap<?,?> m)	Converts a CVM Map to a JSON representation
static <T> T	jvm(ACell o)	Converts a CVM value to equivalent JVM value
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
static CVMBool	le(ACell[] values)
static CVMBool	lt(ACell[] values)
static ACell	max(ACell[] values)	Gets the minimum of a set of numeric values
static ACell	max(ACell a, ACell b)	Gets the minimum of two numeric values
static ACell	min(ACell[] values)	Gets the minimum of a set of numeric values
static ACell	min(ACell a, ACell b)	Gets the minimum of two numeric values
static ANumeric	minus(ACell[] args)
static ANumeric	multiply(ACell... args)
static AString	name(ACell a)	Gets the name from a CVM value.
static <T extends ACell> T	nth(ACell o, long i)	Gets the nth element from a sequential collection.
static <T extends ACell> T	nth(Object o, long i)	Variant of nth that also handles Java Arrays.
static Class<?>	numericType(ACell a)	Gets the numeric class of an object
static ANumeric	plus(ACell[] args)
static CVMDouble	pow(ACell[] args)	Computes the result of a pow operation.
static AString	print(ACell a)	Prints a value to a String as long as the result fits within a given print limit.
static AString	print(ACell a, long limit)	Prints a cell to a BlobBuilder, up to a specified limit of bytes WARNING: May return null
static boolean	print(BlobBuilder bb, ACell a, long limit)	Prints a cell to a BlobBuilder, up to a specified limit of bytes
static <T extends ACell> ASequence<T>	sequence(ACell o)	Converts any collection of cells into a Sequence data structure.
static ACell	signum(ACell a)	Gets the signum of a numeric value
static long	splitmix64Calc(long seed)	Compute a SplitMix64 value for a given seed.
static long	splitmix64Update(long seed)	Compute a SplitMix64 update.
static CVMDouble	sqrt(ACell a)	Gets the exact positive square root of a number after casting to a Double.
static AString	str(ACell a)	Converts a value to a CVM String representation.
static AString	str(ACell[] args)	Converts arguments to an AString representation.
static Address	toAddress(Object a)	Casts an arbitrary value to an Address
static String	toString(ACell a)	Converts a value to a Java String representation
static String	toString(ACell a, long limit)	Converts a value to a Java String representation
static void	validate(Object o)	Validates an object.
static void	validateCell(ACell o)	Validate a Cell.
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
static <T extends ACell> AVector<T>	vec(ACollection<T> coll)	Converts any collection to a vector.
static <T extends ACell> AVector<T>	vec(Object o)	Converts any data structure to a vector

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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 -1 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. May wrap a Java array in VectorArray

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

ensureVector

public static <T extends ACell> AVector<T> ensureVector(ACell o)

Ensures argument is a Vector data structure. Returns null if not a vector is not possible.

Type Parameters:

T - Type of Vector elements

Parameters:

o - Value to cast to Vector

Returns:

An AVector instance, or null if the argument is not a Vector

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

argumentCount

public static Long argumentCount(Object o)

Gets the count of objects in a collection for destructuring (may be data structure or Java Array)

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

isCountable

public static boolean isCountable(ACell val)

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

ensureBlobLike

public static <V extends ACell> ABlobLike<V> ensureBlobLike(ACell a)

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 JSON value object

Returns:

Java Object which represents JSON value

jsonMap

public static HashMap<String,Object> jsonMap(AMap<?,?> m)

Converts a CVM Map to a JSON representation

Parameters:

m - Map to convert to JSON representation

Returns:

Java value which represents JSON object

jsonKey

public static String jsonKey(ACell k)

Gets a String from a value suitable for use as a JSON map key

Parameters:

k - Value to convert to a JSON key

Returns:

String usable as JSON key

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)

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

ensureTransaction

public static ATransaction ensureTransaction(ACell maybeTx)

Casts to a transaction record, or null if not castable

Parameters:

maybeTx - Cell which should be a transaction

Returns:

Transaction value, or null if not a transaction