Map functions

20 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.

map_add

Merges key domains and totals their associated numeric contributions.

map_add(map(K,V:number),map(K,V),...) -> map(K,sum_type(V))

Combines all keys and adds the numeric values associated with each key using checked SQL sum widening. Missing keys and NULL values contribute zero, whereas a NULL outer map returns NULL. Output keys retain canonical order; incompatible descriptors raise TYPE_MISMATCH and unrepresentable totals raise NUMERIC_OVERFLOW.

Example

map_add(map_cast('a', 2), map_cast('a', 3, 'b', 4))
-- → {'a': 5, 'b': 4}

map_all

Requires every stored key-value pair to satisfy a supplied predicate.

map_all(lambda(K,V)->bool,map(K,V)) -> bool

Evaluates the lambda for each key-value pair and returns true only when every evaluation is true. Empty maps return true, NULL predicate results count as false, and a NULL outer map returns NULL. Keys are non-NULL and ordered, values retain their declared nullability, and an incompatible Boolean lambda signature raises TYPE_MISMATCH.

Example

map_all((k, v) -> v > 0, map_cast('a', 2, 'b', 3))
-- → true

map_apply

Transforms both keys and values, then sorts the resulting unique keys.

map_apply(lambda(K,V)->tuple(K′,V′),map(K,V)) -> map(K′,V′)

Applies a lambda returning a key-value tuple to every entry and orders the result by the transformed key descriptor. Input value NULLs are passed to the lambda, a NULL outer map returns NULL, and transformed NULL or duplicate keys raise INVALID_ARGUMENT. The new key type must support ordered keys and the lambda must return a compatible tuple or TYPE_MISMATCH is raised.

Example

map_apply((k, v) -> (k, v * 2), map_cast('a', 2))
-- → {'a': 4}

map_cast

Constructs a unique-key mapping from alternating entries or parallel arrays.

map_cast(K,V,...) -> map(K,V)
map_cast(array(K),array(V)) -> map(K,V)

Builds a map with canonical key order from alternating key-value arguments or equally sized key and value arrays. Keys must be non-NULL and support ordering; duplicates, NULL keys, odd variadic arity and unequal array lengths raise INVALID_ARGUMENT. NULL values require a nullable value descriptor, NULL outer arrays return NULL, and incompatible descriptors raise TYPE_MISMATCH.

Example

map_cast('b', 2, 'a', 1)
-- → {'a': 1, 'b': 2}

map_concat

Combines disjoint mappings and rejects any repeated key across inputs.

map_concat(map(K,V),map(K,V),...) -> map(K,V)

Copies all input entries into a canonically ordered map without choosing a winner for duplicate keys. Duplicate keys across inputs raise INVALID_ARGUMENT, distinguishing this contract from duplicate-preserving map concatenation in other dialects. A NULL outer argument returns NULL, nullable values remain NULL, and incompatible key or value descriptors raise TYPE_MISMATCH.

Example

map_concat(map_cast('b', 2), map_cast('a', 1))
-- → {'a': 1, 'b': 2}

map_contains

Checks whether a mapping stores a particular key regardless of its associated value.

map_contains(map(K,V),K) -> bool

Returns true when the searched key is present, including when its stored value is NULL. A NULL map or search argument returns NULL, and an empty map returns false. The search descriptor must be compatible with the non-NULL ordered key type or TYPE_MISMATCH is raised; value inspection is unnecessary.

Example

map_contains(map_cast('a', 1, 'b', 2), 'b')
-- → true

map_contains_key_like

Detects string keys matching a SQL LIKE pattern among eligible entries.

map_contains_key_like(map(string,V),pattern:string) -> bool

Applies SQL LIKE to string keys and returns whether a matching entry exists; percent matches a sequence and underscore matches one character. Entries whose values are NULL do not match under this contract, and a NULL map or pattern returns NULL. Empty maps return false, while non-string key descriptors raise TYPE_MISMATCH.

Example

map_contains_key_like(map_cast('sensor_a', 2, 'product_b', 3), 'sensor%')
-- → true

map_contains_value_like

Searches stored text values for wildcard matches.

map_contains_value_like(map(K,string),pattern:string) -> bool

Returns true if any non-NULL string value satisfies the supplied SQL LIKE pattern, using percent and underscore wildcard semantics. NULL stored values never match; NULL map or pattern arguments return NULL. An empty map produces false, and a value descriptor other than string raises TYPE_MISMATCH.

Example

map_contains_value_like(map_cast('a', 'red', 'b', 'blue'), 'bl%')
-- → true

map_exists

Finds at least one key-value entry accepted by a Boolean lambda.

map_exists(lambda(K,V)->bool,map(K,V)) -> bool

Invokes the predicate on map entries and succeeds when at least one result is true. NULL predicate results are false, empty maps return false, and NULL outer input returns NULL. Nullable values are supplied to the lambda under their bound descriptor; an incompatible predicate signature raises TYPE_MISMATCH and its volatility governs invocation restrictions.

Example

map_exists((k, v) -> v > 2, map_cast('a', 1, 'b', 3))
-- → true

map_extract_key_like

Retains matching key entries as a canonically ordered submap.

map_extract_key_like(map(string,V),pattern:string) -> map(string,V)

Keeps entries whose string key satisfies SQL LIKE, preserving canonical key order and the original descriptors. Entries with NULL values do not match under the stated contract, and NULL outer map or pattern arguments return NULL. No match produces an empty map; non-string key descriptors raise TYPE_MISMATCH.

Example

map_extract_key_like(map_cast('sensor_a', 2, 'product_b', 3), 'sensor%')
-- → {'sensor_a': 2}

map_extract_key_value_pairs

Parses delimited text into unique string-keyed string values.

map_extract_key_value_pairs(text:string) -> map(string,string)
map_extract_key_value_pairs(text:string,key_value_delimiter:string) -> map(string,string)
map_extract_key_value_pairs(text:string,key_value_delimiter:string,pair_delimiters:string) -> map(string,string)
map_extract_key_value_pairs(text:string,key_value_delimiter:string,pair_delimiters:string,quote:string) -> map(string,string)

Reads key-value pairs from text, defaulting to colon between key and value, space/comma/semicolon between pairs and double quote for quoting. The resulting map has canonical key order; malformed syntax or duplicate keys raises INVALID_ARGUMENT. NULL arguments return NULL, and this basic parser does not provide the separate backslash-escape decoding contract.

Example

map_extract_key_value_pairs('a:1,b:2')
-- → {'a': '1', 'b': '2'}

map_extract_key_value_pairs_with_escaping

Decodes backslash-escaped pair text into an ordered dictionary.

map_extract_key_value_pairs_with_escaping(text:string) -> map(string,string)
map_extract_key_value_pairs_with_escaping(text:string,key_value_delimiter:string) -> map(string,string)
map_extract_key_value_pairs_with_escaping(text:string,key_value_delimiter:string,pair_delimiters:string) -> map(string,string)
map_extract_key_value_pairs_with_escaping(text:string,key_value_delimiter:string,pair_delimiters:string,quote:string) -> map(string,string)

Parses delimited key-value text while interpreting backslash escapes, then produces unique ordered string keys with string values. Defaults are colon for assignment, space/comma/semicolon for pair separation and double quote for quoting; duplicate keys or malformed escaped input raise INVALID_ARGUMENT. NULL text or delimiter arguments return NULL rather than an empty dictionary.

Example

map_extract_key_value_pairs_with_escaping('a:1,b:2')
-- → {'a': '1', 'b': '2'}

map_extract_value_like

Selects entries by SQL wildcard matching on their textual payloads.

map_extract_value_like(map(K,string),pattern:string) -> map(K,string)

Retains the key-value pairs whose non-NULL string value satisfies the LIKE pattern and emits them in canonical key order. NULL stored values are excluded, NULL outer arguments propagate NULL, and no matches yield an empty map. A non-string value descriptor raises TYPE_MISMATCH; key ordering and value descriptors are preserved.

Example

map_extract_value_like(map_cast('a', 'red', 'b', 'blue'), 'bl%')
-- → {'b': 'blue'}

map_filter

Keeps key-value pairs selected by an entry-wise Boolean condition.

map_filter(lambda(K,V)->bool,map(K,V)) -> map(K,V)

Evaluates the lambda against each original key-value entry and includes that entry only when the result is true. NULL results are false, NULL outer input returns NULL, and an empty map remains empty. Surviving entries retain canonical key order and original descriptors; incompatible predicate argument or result types raise TYPE_MISMATCH.

Example

map_filter((k, v) -> v > 1, map_cast('a', 1, 'b', 3))
-- → {'b': 3}

map_from_arrays

Associates aligned key and value vectors into a sorted unique mapping.

map_from_arrays(array(K),array(V)) -> map(K,V)

Pairs each key-array position with the corresponding value-array position and canonicalizes output key order. NULL keys, duplicate keys and unequal input lengths raise INVALID_ARGUMENT, while nullable value elements are retained. NULL outer array input returns NULL, and keys without ordered-key capability or incompatible descriptors raise TYPE_MISMATCH.

Example

map_from_arrays(['b', 'a'], [2, 1])
-- → {'a': 1, 'b': 2}

map_keys

Extracts stored lookup keys in their canonical sorted order.

map_keys(map(K,V)) -> array(K)

Returns an array of all map keys ordered by the key descriptor, independently of the values stored at those keys. Keys are non-NULL, even when corresponding values are NULL; a NULL outer map returns NULL. Empty maps yield an empty key array whose element type remains the bound key type.

Example

map_keys(map_cast('b', 2, 'a', 1))
-- → ['a', 'b']

map_populate_series

Fills missing integer keys between range endpoints with default numeric values.

map_populate_series(map(K:int*,V:number)) -> map(K,V)
map_populate_series(map(K:int*,V:number),maximum:K) -> map(K,V)

Expands integer keys from the existing minimum through the maximum, optionally extending the upper endpoint to the supplied maximum. Missing positions receive default(V), existing entries retain their values and NULL outer input returns NULL. Noninteger keys raise TYPE_MISMATCH, and the resulting element count is checked before allocation with RESOURCE_LIMIT on excess.

Example

map_populate_series(map_cast(1, 5, 3, 7))
-- → {1: 5, 2: 0, 3: 7}

map_subtract

Computes per-key differences by deducting later mappings from the first.

map_subtract(map(K,V:number),map(K,V),...) -> map(K,sum_type(V))

Forms the union of key domains and subtracts each later map contribution from the first map value, taking absent entries as zero. NULL values also contribute zero, but a NULL outer map makes the whole result NULL. Values use checked SQL sum widening and keys retain canonical order; descriptor incompatibility raises TYPE_MISMATCH and overflow raises NUMERIC_OVERFLOW.

Example

map_subtract(map_cast('a', 8), map_cast('a', 3, 'b', 2))
-- → {'a': 5, 'b': -2}

map_update

Overlays right-hand entries onto a mapping, replacing matching left values.

map_update(map(K,V),map(K,V)) -> map(K,V)

Creates the unique union of both key sets and chooses the right-hand value wherever a key occurs in both arguments. Right-hand NULL values replace earlier values when the descriptor is nullable, and a NULL outer map returns NULL. Canonical key order is retained; incompatible key or value descriptors raise TYPE_MISMATCH.

Example

map_update(map_cast('a', 1, 'b', 2), map_cast('b', 9))
-- → {'a': 1, 'b': 9}

map_values

Projects stored payloads in the same positional order as their sorted keys.

map_values(map(K,V)) -> array(V)

Returns map values ordered by their associated canonical keys, aligning positionally with the key projection. Nullable values remain NULL entries, while a NULL outer map returns NULL. An empty map yields an empty array with the existing value descriptor rather than inferring a type from absent data.

Example

map_values(map_cast('b', 2, 'a', 1))
-- → [1, 2]