6.3.9. Common Utilities

You can access the following functions in the substrate REPL To run the REPL: make repl

caar

Returns the first item of the first list of the outer list.

cadar

Takes the first inner list and returns the item after the first value.

cadr

Returns the first item from the outer list after the first value.

cddr

Returns the last item of the last item of a list.

Sequence Helpers

to-bool

Interprets a truthy value, returning a boolean.

implies

Perform logical implies on the two arguments:

• If the first argument is truthy, return the boolean value of the second argument
• If the first argument if false, return true

when

The when macro acts as a "one-armed if" expression but also allows multiple consequent expressions which are evaluated as if in a progn.

unless

The unless macro acts as a "one-armed if not" expression but also allows multiple consequent expressions which are evaluated as if in a progn.

while

The while macro emulates the C "while" block. If predicate-expression evaluates to true, consequent-expressions are evaluated and then the process repeats. If and when the loop terminates, the predicate-expression will have just evaluated to false. The macro always evaluates to ().

default

Returns x if truthy, and d otherwise.

default-string

Returns x if the string isn't empty (""), and d otherwise.

curry

Returns a function which will call FUN passing it INITIAL-ARGS and then any other args.

vector-if-nil

Returns a empty vector if x is nil, and x otherwise.

bool-is-substantial

Returns false for non-boolean values or x for booleans.

int-is-substantial

Checks if the value can be interpreted as a int and is non-zero.

float-is-substantial

Checks if the value can be interpreted as a float and is non-zero.

string-is-substantial

Checks if the value is a string and isn't empty.

nil-if-empty-string

Returns nil for empty strings, otherwise returns the input string.

num?

Checks if the value is a number.

num-is-substantial

Checks if the value can be interpreted as a number and is non-zero.

seq?

Checks if the value is a sequence (list or vector).

seq-is-substantial

Checks if the value is a non-empty sequence.

map-is-substantial

Checks if the value is a non-empty map.

generic-is-substantial

Checks the value is non-empty and substantial across types.

widen-number

Zero pads the number with a width of 20.

widen-number-pennies

Zero pads to penny width.

string-in?

Checks if the string is in the string sequence.

strings-in?

Determines that all strings in seq s are in seq lis.

string-starts-with?

Checks if the string has the given prefix.

string-substring

Gets a string substring.

string-is-digits?

Checks if the string contains only numeric digits.

string-is-hexdigits?

Checks if the string contains only hexadecimal digits.

string-is-guid?

Checks if the string is a universally unique identifier.

basic-match

Checks if the strings match, supports ? to mach any character.

count

Counts the items matched by the predicate function.

seq-with-index

Returns the sequence values with indexes.

foldlpairs

foldl sequence pairs.

deduplicate

Deduplicate a sequence of hashable values.

deduplicate-list

Same as deduplicate, but only for list sequences.

deduplicate-vector

Same as deduplicate, but only for vector sequences.

make-string-set

Creates a sorted-map with string keys mapping to true values.

elps> (make-string-set '("A" "B" "C" "D" "C" "B" "A"))
(sorted-map "A" true "B" true "C" true "D" true)

make-mergemap

Constructs a new map by taking the union of keys, vals of maps m1 and m2, where m2 value override m1 values where both maps share a common key.

make-submap

Create a sorted-map containing the subset of m's values associated with keys in the sequence, map-keys. Any elements of map-keys that are not keys of m will not be keys of the returned submap either.

strings-unique?

Returns true if all strings in sequence s1 are unique.

strings-union

Performs a union of two string sequences.

strings-intersect

Returns unique elements present in both sequences.

strings-intersect-seqs

Returns unique elements present in both sequences.

strings-subtract

Returns unique elements of sequence minuend which are not present in sequence subtrahend.

strings-xor

Returns unique strings that are in seqa or seqb, but are not in both.

strings-equal?

Returns true if the unique strings in seqa are exactly same in seqb.

clear-map!

Clears map values, mutating the input map.

deep-equal?

Works closer to the way that equal? is supposed to for structured data.

denil

Filters out nil values from a sequence.

human-join-strings

Joins a list of strings with commas, and adds an "and" before the last element. It uses oxford comma style.

triml

Remove leading spaces from a string.

trimr

Remove trailing spaces from a string.

trim

Removes leading and trailing spaces from a string.

human-full-name

Tries to construct a single full name string based on optional name fields.

encode-map-storage-key

Encode a map to be used as part of a storage key delimited by ":". The encoding doesn't use ":" so that two maps may be used side-by-side in a storage key without ambiguity.

map-with-index

Map a function on a sequence, where the first argument to the function is i and the second argument to the function is the i-th element. Returns a list.

strings-intersect-seqs

Performs intersection across a sequence of string sequences.

find-pos

find-pos iterates across seq and returns the last position that fn returned true.

If no element is found, 0 is returned, which requires special handling when the element found is the first element.

decimal-money-add

Add 2 decimal strings, and return a decimal string. DEPRECATED: Please use libdecimal instead of these decimal-money functions.

memoize

An optimization technique by storing the results of expensive function calls and returning the cached result when the same inputs occur again.

now

Returns current UTC time.

now-unix

Returns current time as hexidecimal of the unix epoch time in seconds.

cdar

Returns everything but the first item of the first list, of the outer list.

widen-number-range

Returns number range.

widen-number-prefix

Returns number prefix.

widen-number-pennies-range

Returns pennies range.

widen-number-pennies-prefix

Returns pennies prefix.

String-trailer

Returns a substring without a provided prefix.

digit-to-true

Returns digit to true sorted map.

hexdigit-to-true

Returns hex digit to true sorted map.

hexdigit-to-number

Returns hex digit to number sorted map.

now-epoch

Return current unix epoch time in seconds.

concat!

Mutates the first vector to include the second vector as the last elements.

get-tx-metadata

Get metadata (transaction metadata is stored in the state database under the transaction ID) with string key from the transaction context.

entity-metadata

Returns a specified entry in the metadata field of an entity.

get-metadata-str

Returns the string value for a specific entry in the metadata field of an entity.

get-metadata-int

Returns the integer value for a specific entry in the metadata field of an entity.

assert-deep-equal

Ensures the 2 arguments are deeply equal. Used in testing.

asset-not-deep-equal

Ensures the 2 arguments are NOT deeply equal. Used in testing.

assert-condition

Expects an exception or error to be returned and handles accordingly.

timestamp-to-date

Converts a timestamp to a date.

date-now

Returns today's date.

ymd-between-dates

Returns the number of years, months, and days in between 2 dates as a vector.

ymd-extract

Extracts the year, month, and date and returns that as a vector.

decimal-money-from-int

Returns the integer input in money format.

decimal-money-from-vector

Takes a vector of the dollar amount and cent amount as input and returns in money format.

decimal-money-to-vector

Takes a money amount as input and returns a vector of the dollar amount and the cent amount.

decimal-money-cmp

Whether the first money amount is larger than the second.