Tuple functions

14 functions. Names resolve case-insensitively; an alias binds the same function as its canonical name. Each entry gives the signatures, the behaviour and an example.

tuple_cast

Constructs a typed record with one to sixteen independently described fields.

tuple_cast(T1,...) -> tuple(T1,...)

Packs the supplied arguments into a tuple, preserving each field descriptor and explicit NULL value instead of finding one common element type. The field count must be between one and sixteen or INVALID_ARGUMENT is raised. Field nullability is part of the resulting descriptor, so a NULL field does not make the complete tuple NULL.

Example

tuple_cast(7, 'sensor')
-- → (7, 'sensor')

tuple_concat

Appends record fields in argument order while preserving their individual types.

tuple_concat(tuple(T1,...),tuple(U1,...),...) -> tuple(T1,...,U1,...)

Concatenates tuple fields from left to right, retaining each field descriptor, name and nullability. A NULL outer tuple returns NULL, while NULL fields inside non-NULL tuples are preserved. The combined field count cannot exceed sixteen and declared names must remain unique; violating these constraints raises INVALID_ARGUMENT.

Example

tuple_concat((1, 'a'), (2, 'b'))
-- → (1, 'a', 2, 'b')

tuple_divide

Computes position-wise quotients for two numeric records.

tuple_divide(tuple(T1:number,...),tuple(U1:number,...)) -> tuple(arithmetic_result(T1,U1),...)

Divides each field in the first tuple by the corresponding field in the second using checked numeric promotion. NULL outer tuples return NULL and any NULL operand field yields a NULL result field. Unequal arity or nonnumeric fields raise TYPE_MISMATCH, a zero divisor raises INVALID_ARGUMENT, and an unrepresentable checked result raises NUMERIC_OVERFLOW.

Example

tuple_divide((8, 9), (2, 3))
-- → (4, 3)

tuple_divide_by_number

Scales every numeric record component by one common divisor.

tuple_divide_by_number(tuple(T1:number,...),U:number) -> tuple(arithmetic_result(T1,U),...)

Divides every tuple field by the supplied scalar using the arithmetic result descriptor for that field and scalar pair. A NULL tuple or scalar returns NULL, while NULL fields remain NULL. Nonnumeric operands raise TYPE_MISMATCH, division by zero raises INVALID_ARGUMENT, and checked representability failures raise NUMERIC_OVERFLOW.

Example

tuple_divide_by_number((8, 12), 4)
-- → (2, 3)

tuple_element

Reads a record field selected by a bound ordinal or declared name.

tuple_element(tuple(T1,...),index:uint8 const) -> T_index
tuple_element(tuple(T1,...),field_name:string const) -> T_field

Returns the field identified by a constant one-based position or declared field name, with the selected field descriptor and nullability. A NULL outer tuple produces NULL, and a selected NULL field remains NULL. An absent position raises INDEX_OUT_OF_BOUNDS and an unknown name raises INVALID_ARGUMENT at binding; no implicit default is supplied.

Example

tuple_element((7, 'sensor'), 2)
-- → 'sensor'

tuple_flatten

Expands nested record fields recursively into declaration-order leaves.

tuple_flatten(tuple(T1,tuple(T2,...),...)) -> tuple(T1,T2,...)

Recursively removes nested tuple boundaries while preserving leaf declaration order and field descriptors. NULL outer input returns NULL and leaf nullability is retained in the resulting tuple. Joined field paths must remain unique and the flattened record must have at most sixteen fields; violating either constraint raises INVALID_ARGUMENT.

Example

tuple_flatten((1, (2, 3)))
-- → (1, 2, 3)

tuple_hamming_distance

Counts unequal record positions using NULL-safe field comparison.

tuple_hamming_distance(tuple(T1,...),tuple(T1,...)) -> uint64

Compares corresponding tuple fields and returns the number of unequal positions as uint64. Equality is NULL-safe, so two NULL fields compare equal while one NULL and one non-NULL field differ; a NULL outer tuple returns NULL. Tuples must have equal arity and compatible equality-capable field descriptors or TYPE_MISMATCH is raised.

Example

tuple_hamming_distance((1, 2, 3), (1, 5, 6))
-- → 2

tuple_minus

Subtracts corresponding components of one numeric record from another.

tuple_minus(tuple(T1:number,...),tuple(U1:number,...)) -> tuple(arithmetic_result(T1,U1),...)

Subtracts each right-hand field from the corresponding left-hand field and derives each result through checked numeric promotion. A NULL tuple returns NULL, and a NULL operand at one position affects only that result field. Unequal arity or nonnumeric fields raise TYPE_MISMATCH; arithmetic outside the promoted descriptor raises NUMERIC_OVERFLOW.

Example

tuple_minus((8, 9), (2, 3))
-- → (6, 6)

tuple_multiply

Forms component-wise products between equally sized numeric records.

tuple_multiply(tuple(T1:number,...),tuple(U1:number,...)) -> tuple(arithmetic_result(T1,U1),...)

Multiplies corresponding fields and uses the checked arithmetic result descriptor independently at each position. NULL outer tuples propagate NULL, while a NULL field in either operand produces NULL only at that position. Different tuple arities or nonnumeric fields raise TYPE_MISMATCH, and unrepresentable products raise NUMERIC_OVERFLOW.

Example

tuple_multiply((2, 3), (4, 5))
-- → (8, 15)

tuple_multiply_by_number

Applies one numeric scale factor to every record field.

tuple_multiply_by_number(tuple(T1:number,...),U:number) -> tuple(arithmetic_result(T1,U),...)

Multiplies each numeric tuple component by the scalar and promotes each field-scalar pair using checked arithmetic. NULL tuple or scalar input returns NULL, and existing NULL fields remain NULL. Incompatible operand types raise TYPE_MISMATCH, while a product that cannot fit its promoted result descriptor raises NUMERIC_OVERFLOW.

Example

tuple_multiply_by_number((2, 3), 4)
-- → (8, 12)

tuple_names

Lists declared record field names, substituting ordinal text for unnamed fields.

tuple_names(tuple(T1,...)) -> array(string)

Returns field names as a string array in declaration order; fields without names use their one-based ordinal rendered as text. Field values and field NULLs do not change those names, while a NULL outer tuple returns NULL. The result reflects the bound tuple descriptor rather than inspecting the contents for labels.

Example

tuple_names((7, 'sensor'))
-- → ['1', '2']

tuple_negate

Reverses the sign of each numeric component with checked signed widening.

tuple_negate(tuple(T1:number,...)) -> tuple(negate_type(T1),...)

Applies unary minus independently to every tuple field and widens unsigned fields to an appropriate signed descriptor. A NULL outer tuple returns NULL and NULL fields remain NULL. Nonnumeric fields raise TYPE_MISMATCH; a uint256 value whose negative cannot be represented, or any other checked negation overflow, raises NUMERIC_OVERFLOW.

Example

tuple_negate((2, -3))
-- → (-2, 3)

tuple_plus

Adds aligned numeric record components into separately promoted result fields.

tuple_plus(tuple(T1:number,...),tuple(U1:number,...)) -> tuple(arithmetic_result(T1,U1),...)

Sums corresponding fields from two tuples of equal arity, computing a checked arithmetic descriptor for each position. NULL outer input returns NULL, and either operand being NULL at a field produces NULL at that field only. Arity or numeric type incompatibility raises TYPE_MISMATCH, and an unrepresentable sum raises NUMERIC_OVERFLOW.

Example

tuple_plus((2, 3), (4, 5))
-- → (6, 8)

tuple_to_name_value_pairs

Converts homogeneous record fields into ordered label-value pairs.

tuple_to_name_value_pairs(tuple(T,T,...)) -> array(tuple(string,T))

Emits an array of two-field tuples containing each field name and its value in declaration order. All source fields must share one descriptor or TYPE_MISMATCH is raised; unnamed fields use their ordinal names. Field NULLs are retained in the emitted pairs, while a NULL outer tuple returns NULL.

Example

tuple_to_name_value_pairs((7, 9))
-- → [('1', 7), ('2', 9)]