Files
marqdo/lib/table.mq.md
T

36 KiB

markup, title, description
markup title description
occlusion lib/table List and map helpers. Prefer put (1-based path, same nesting as access reads); at/set_at/slice are 0-based. Use lib/json only for parse/stringify.

List and map helpers. Prefer put for nested writes; authors should read with access reads, not new footnote indexes.

Transform lists, maps and row records using explicit data shapes.

Behavior and limits: put/access integer paths are one-based; at/slice/insert/remove_at are zero-based. Updates return new values: keep the result. rows is a length alias; from_columns/to_columns perform shape conversion.

This single source file is the usage and development manual. Import it directly, or use marqdo call with a function heading below. Parameter tables give types and defaults; required parameters must be supplied. Return tables are progressive contracts; prose describes failure and limits.

Implementation: src/host/collection.rs、src/host/collection_ops.rs

For development, keep EN/ZH behavior aligned and compose public libraries first. Add host primitives only at OS or algorithm boundaries and declare their effects. Run marqdo check --narrative-ratio on this file and the real workflows in tests/stdlib_tasks.rs after edits.

put

参数 类型 默认 说明
in any required Input collection; None seeds a new record
at any required Text key, one-based index, or nested path of keys and indices
value any required Value to transform or store, without mutating the input
返回 类型 说明
result any Update one element of collection in at path at to value

Use in, at, value as the inputs for this operation.

Effects: pure.

Update one element of collection in at path at to value.

at is a text key, a 1-based list index, or a list of keys/indices (same nesting as access reads).

Caller: [table.put] in=None at="Authorization" value="Bearer-x"

Return [Update one element of collection in at path at to value](> host_collection_put in=in at=at value=value).

len

参数 类型 默认 说明
xs any required Input list or collection, as required by this operation
返回 类型 说明
result number Length of list or map xs

Use xs as the inputs for this operation.

Effects: pure.

Length of list or map xs.

Return Len.

rows

参数 类型 默认 说明
xs any required Input list or collection, as required by this operation
返回 类型 说明
result number Row count for list xs (alias of len)

Use xs as the inputs for this operation.

Effects: pure.

Row count for list xs (alias of len).

Return Len.

at

参数 类型 默认 说明
xs any required Input list or collection, as required by this operation
i number required Zero-based element or row index
返回 类型 说明
result any Zero-based index into xs at i (same as builtin at)

Use xs, i as the inputs for this operation.

Effects: pure.

Zero-based index into xs at i (same as builtin at). Out of range → None.

Return [At](at(value=xs, index=i)).

row_at

参数 类型 默认 说明
xs any required Input list or collection, as required by this operation
i number required Zero-based element or row index
返回 类型 说明
result any Zero-based row from xs at i

Use xs, i as the inputs for this operation.

Effects: pure.

Zero-based row from xs at i.

Return [At](at(value=xs, index=i)).

append

参数 类型 默认 说明
list any required Input list; updates return a new list
item any required Element to insert, replace or compare
返回 类型 说明
result list Append item to list

Use list, item as the inputs for this operation.

Effects: pure.

Append item to list.

Return [Append item to list](> host_list_append list=list item=item).

prepend

参数 类型 默认 说明
list any required Input list; updates return a new list
item any required Element to insert, replace or compare
返回 类型 说明
result list Prepend item to list

Use list, item as the inputs for this operation.

Effects: pure.

Prepend item to list.

Return [Prepend item to list](> host_list_prepend list=list item=item).

concat

参数 类型 默认 说明
a any required First list; None is an empty-list seed
b any required List appended after a
返回 类型 说明
result list Concatenate lists a and b

Use a, b as the inputs for this operation.

Effects: pure.

Concatenate lists a and b.

Return [Concatenate lists a and b](> host_list_concat a=a b=b).

insert

参数 类型 默认 说明
list any required Input list; updates return a new list
index number required Zero-based position to insert, replace or remove
item any required Element to insert, replace or compare
返回 类型 说明
result list Insert item into list at zero-based index (may insert at len to append)

Use list, index, item as the inputs for this operation.

Effects: pure.

Insert item into list at zero-based index (may insert at len to append).

Return [Insert item into list at zero-based index (may insert at len to append)](> host_list_insert list=list index=index item=item).

set_at

参数 类型 默认 说明
list any required Input list; updates return a new list
index number required Zero-based position to insert, replace or remove
item any required Element to insert, replace or compare
返回 类型 说明
result list Zero-based replace of list at index with item

Use list, index, item as the inputs for this operation.

Effects: pure.

Zero-based replace of list at index with item. Prefer put with a 1-based index for author-facing edits.

Return [Zero-based replace of list at index with item](> host_list_set_at list=list index=index item=item).

remove_at

参数 类型 默认 说明
list any required Input list; updates return a new list
index number required Zero-based position to insert, replace or remove
返回 类型 说明
result list Remove zero-based index from list

Use list, index as the inputs for this operation.

Effects: pure.

Remove zero-based index from list.

Return [Remove zero-based index from list](> host_list_remove_at list=list index=index).

pop

参数 类型 默认 说明
list any required Input list; updates return a new list
返回 类型 说明
result list Drop the last item of list (errors if empty)

Use list as the inputs for this operation.

Effects: pure.

Drop the last item of list (errors if empty). Use last first when you need the removed value.

We retain n = Len.

  1. n > 0 Return [Drop the last item of list (errors if empty)](> host_list_remove_at list=list index=n - 1).

Return [Drop the last item of list (errors if empty)](> host_list_remove_at list=list index=0).

first

参数 类型 默认 说明
list any required Input list; updates return a new list
返回 类型 说明
result any First item of list

Use list as the inputs for this operation.

Effects: pure.

First item of list.

Return [First item of list](> host_list_first list=list).

last

参数 类型 默认 说明
list any required Input list; updates return a new list
返回 类型 说明
result any Last item of list

Use list as the inputs for this operation.

Effects: pure.

Last item of list.

Return [Last item of list](> host_list_last list=list).

slice

参数 类型 默认 说明
list any required Input list; updates return a new list
start number required Inclusive zero-based slice start
end any None Exclusive zero-based slice end; None selects through the end
返回 类型 说明
result list Zero-based half-open slice of list from start to end

Use list, start, end=None as the inputs for this operation.

Effects: pure.

Zero-based half-open slice of list from start to end.

Return [Zero-based half-open slice of list from start to end](> host_list_slice list=list start=start end=end).

contains

参数 类型 默认 说明
list any required Input list; updates return a new list
item any required Element to insert, replace or compare
返回 类型 说明
result bool Whether list contains item

Use list, item as the inputs for this operation.

Effects: pure.

Whether list contains item.

Return [Whether list contains item](> host_list_contains list=list item=item).

index_of

参数 类型 默认 说明
list any required Input list; updates return a new list
item any required Element to insert, replace or compare
返回 类型 说明
result any Zero-based index of item in list, or None

Use list, item as the inputs for this operation.

Effects: pure.

Zero-based index of item in list, or None.

Return [Zero-based index of item in list, or None](> host_list_index_of list=list item=item).

reverse

参数 类型 默认 说明
list any required Input list; updates return a new list
返回 类型 说明
result list Reverse list

Use list as the inputs for this operation.

Effects: pure.

Reverse list.

Return [Reverse list](> host_list_reverse list=list).

sort

参数 类型 默认 说明
list any required Input list; updates return a new list
返回 类型 说明
result list Stable ascending sort: numbers, text, bool, None, then structured values by type/display

Use list as the inputs for this operation.

Effects: pure.

Stable ascending sort: numbers, text, bool, None, then structured values by type/display. Numeric cross-type comparison preserves large integer order.

Return [Stable ascending sort: numbers, text, bool, None, then structured values by type/display](> host_list_sort list=list).

sort_by

参数 类型 默认 说明
list any required Input list; updates return a new list
key text required Field name or key required by this operation
返回 类型 说明
result list Sort a list of maps by field key

Use list, key as the inputs for this operation.

Effects: pure.

Sort a list of maps by field key.

Return [Sort a list of maps by field key](> host_list_sort_by list=list key=key).

unique

参数 类型 默认 说明
list any required Input list; updates return a new list
返回 类型 说明
result list Stable unique of list (first wins)

Use list as the inputs for this operation.

Effects: pure.

Stable unique of list (first wins).

Return [Stable unique of list (first wins)](> host_list_unique list=list).

chunk

参数 类型 默认 说明
list any required Input list; updates return a new list
size number required Positive number of elements per chunk
返回 类型 说明
result list Split list into chunks of size

Use list, size as the inputs for this operation.

Effects: pure.

Split list into chunks of size.

Return [Split list into chunks of size](> host_list_chunk list=list size=size).

zip

参数 类型 默认 说明
a any required First list of each pair
b any required Second list of each pair
返回 类型 说明
result list Pair lists a and b until the shorter ends

Use a, b as the inputs for this operation.

Effects: pure.

Pair lists a and b until the shorter ends.

Return [Pair lists a and b until the shorter ends](> host_list_zip a=a b=b).

flatten

参数 类型 默认 说明
list any required Input list; updates return a new list
返回 类型 说明
result list One-level flatten of list

Use list as the inputs for this operation.

Effects: pure.

One-level flatten of list.

Return [One-level flatten of list](> host_list_flatten list=list).

clear

参数 类型 默认 说明
value any required Value to transform or store, without mutating the input
返回 类型 说明
result any Empty list or empty map for value (by type)

Use value as the inputs for this operation.

Effects: pure.

Empty list or empty map for value (by type).

Return [Empty list or empty map for value (by type)](> host_collection_clear value=value).

get

参数 类型 默认 说明
map any required Input string-keyed map
key text required Field name or key required by this operation
返回 类型 说明
result any Shallow get from map at key

Use map, key as the inputs for this operation.

Effects: pure.

Shallow get from map at key. Missing → None. Prefer access reads in author code.

Return [Shallow get from map at key](> host_map_get map=map key=key).

set

参数 类型 默认 说明
map any required Input string-keyed map
key text required Field name or key required by this operation
value any required Value to transform or store, without mutating the input
返回 类型 说明
result map Shallow map update

Use map, key, value as the inputs for this operation.

Effects: pure.

Shallow map update. Prefer put for nested paths.

Return [Shallow map update](> host_map_set map=map key=key value=value).

delete

参数 类型 默认 说明
map any required Input string-keyed map
key text required Field name or key required by this operation
返回 类型 说明
result map Delete key from map

Use map, key as the inputs for this operation.

Effects: pure.

Delete key from map.

Return [Delete key from map](> host_map_delete map=map key=key).

has

参数 类型 默认 说明
map any required Input string-keyed map
key text required Field name or key required by this operation
返回 类型 说明
result bool Whether map has key

Use map, key as the inputs for this operation.

Effects: pure.

Whether map has key.

Return [Whether map has key](> host_map_has map=map key=key).

keys

参数 类型 默认 说明
map any required Input string-keyed map
返回 类型 说明
result list Keys of map

Use map as the inputs for this operation.

Effects: pure.

Keys of map.

Return [Keys of map](> host_map_keys map=map).

values

参数 类型 默认 说明
map any required Input string-keyed map
返回 类型 说明
result list Values of map

Use map as the inputs for this operation.

Effects: pure.

Values of map.

Return [Values of map](> host_map_values map=map).

items

参数 类型 默认 说明
map any required Input string-keyed map
返回 类型 说明
result list Key/value rows from map

Use map as the inputs for this operation.

Effects: pure.

Key/value rows from map.

Return [Key/value rows from map](> host_map_items map=map).

merge

参数 类型 默认 说明
a any required Base record; None seeds an empty record
b any required Record merged over a; later values win
返回 类型 说明
result map Merge maps a and b (right-hand keys win)

Use a, b as the inputs for this operation.

Effects: pure.

Merge maps a and b (right-hand keys win).

Return [Merge maps a and b (right-hand keys win)](> host_map_merge a=a b=b).

size

参数 类型 默认 说明
map any required Input string-keyed map
返回 类型 说明
result number Key count of map

Use map as the inputs for this operation.

Effects: pure.

Key count of map.

Return [Key count of map](> host_map_size map=map).

empty_list

返回 类型 说明
result list Empty list

Effects: pure.

Empty list.

Return [Empty list](> host_list_concat a=None b=None).

empty_map

返回 类型 说明
result map Return a new empty map as a seed for immutable updates; this is not an empty list

Effects: pure.

Empty map.

Return a new empty map as a seed for immutable updates; this is not an empty list.

Return [Return a new empty map as a seed for immutable updates; this is not an empty list](> host_map_merge a=None b=None).

range

参数 类型 默认 说明
start number required First numeric value of the sequence
end number required Exclusive bound of the sequence
step number 1 Nonzero range increment; sign must point toward the end
返回 类型 说明
result list Generate a half-open integer sequence; negative steps are allowed, zero is rejected, at most 1000000 items

Use start, end, step=1 as the inputs for this operation.

Effects: pure.

Generate a half-open integer sequence; negative steps are allowed, zero is rejected, at most 1000000 items.

Return [Generate a half-open integer sequence; negative steps are allowed, zero is rejected, at most 1000000 items](> host_table_range start=start end=end step=step).

enumerate

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
start number 0 Index value assigned to the first record; default is one
返回 类型 说明
result list Return index/value records without modifying the input; index starts at start

Use list, start=0 as the inputs for this operation.

Effects: pure.

Return index/value records without modifying the input; index starts at start.

Return [Return index/value records without modifying the input; index starts at start](> host_table_enumerate list=list start=start).

pluck

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
key text required Field name or storage key to read, compare or update
返回 类型 说明
result list Extract one field from every record; a missing field is an error instead of silently becoming None

Use list, key as the inputs for this operation.

Effects: pure.

Extract one field from every record; a missing field is an error instead of silently becoming None.

Return [Extract one field from every record; a missing field is an error instead of silently becoming None](> host_table_pluck list=list key=key).

project

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
keys list required Ordered field-name list
返回 类型 说明
result list Keep the requested fields, in keys order; every requested field must exist

Use list, keys as the inputs for this operation.

Effects: pure.

Keep the requested fields, in keys order; every requested field must exist.

Return [Keep the requested fields, in keys order; every requested field must exist](> host_table_project list=list keys=keys).

where

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
key text required Field name or storage key to read, compare or update
value any required Value to transform or store, without mutating the input
op text "eq" Operation name understood by this helper
返回 类型 说明
result list Keep matching records

Use list, key, value, op="eq" as the inputs for this operation.

Effects: pure.

Keep matching records. Operators: eq/ne/gt/ge/lt/le/contains/in; these are fixed operations, never code to evaluate.

Return [Keep matching records](> host_table_where list=list key=key value=value op=op).

group_by

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
key text required Field name or storage key to read, compare or update
返回 类型 说明
result list Return first-seen ordered key/count/rows records; group keys keep their original value types

Use list, key as the inputs for this operation.

Effects: pure.

Call this function directly:

marqdo call lib/table.mq.md group_by 'list=[{"team":"a","n":3},{"team":"b","n":1},{"team":"a","n":2}]' 'key="team"' --effects none --json

Return first-seen ordered key/count/rows records; group keys keep their original value types.

Return [Return first-seen ordered key/count/rows records; group keys keep their original value types](> host_table_group_by list=list key=key).

unique_by

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
key text required Field name or storage key to read, compare or update
返回 类型 说明
result list Keep the first record per field value; input order is preserved

Use list, key as the inputs for this operation.

Effects: pure.

Keep the first record per field value; input order is preserved.

Return [Keep the first record per field value; input order is preserved](> host_table_unique_by list=list key=key).

aggregate

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
key any None Field name or storage key to read, compare or update
op text "sum" Operation name understood by this helper
返回 类型 说明
result number Aggregate scalar values or one record field: sum/count/min/max/mean

Use list, key=None, op="sum" as the inputs for this operation.

Effects: pure.

Aggregate scalar values or one record field: sum/count/min/max/mean. Empty sum/count is zero; empty min/max/mean fails; integer sum checks overflow.

Return [Aggregate scalar values or one record field: sum/count/min/max/mean](> host_table_aggregate list=list key=key op=op).

sort_keys

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
keys list required Ordered field-name list
descending bool False Whether the multi-key sort is descending
返回 类型 说明
result list Stable lexicographic sort by fields in keys order; descending reverses the comparison, keeping equal-key order

Use list, keys, descending=False as the inputs for this operation.

Effects: pure.

Stable lexicographic sort by fields in keys order; descending reverses the comparison, keeping equal-key order.

Return [Stable lexicographic sort by fields in keys order; descending reverses the comparison, keeping equal-key order](> host_table_sort_keys list=list keys=keys descending=descending).

rename

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
fields map required Structured field/value record attached to the log event
返回 类型 说明
result list Rename fields using an old-name/new-name map; duplicate output names fail

Use list, fields as the inputs for this operation.

Effects: pure.

Rename fields using an old-name/new-name map; duplicate output names fail.

Return [Rename fields using an old-name/new-name map; duplicate output names fail](> host_table_rename list=list fields=fields).

from_columns

参数 类型 默认 说明
columns map required Column-name/list record; all columns must have equal length
返回 类型 说明
result list Convert a column map to row records

Use columns as the inputs for this operation.

Effects: pure.

Convert a column map to row records. Every column must be a list of equal length; scalar object fields are not inferred as columns.

Return [Convert a column map to row records](> host_table_from_columns columns=columns).

to_columns

参数 类型 默认 说明
rows list required List of row records, rather than an implicit column map
返回 类型 说明
result map Convert records with identical field sets into a column map; empty input yields an empty map

Use rows as the inputs for this operation.

Effects: pure.

Convert records with identical field sets into a column map; empty input yields an empty map.

Return [Convert records with identical field sets into a column map; empty input yields an empty map](> host_table_to_columns rows=rows).

join

参数 类型 默认 说明
a list required First operand; its domain is described by this operation
b list required Second operand; its domain is described by this operation
key text required Field name or storage key to read, compare or update
right_key text required Matching field in right-hand records
mode text "inner" Join mode: inner or left
返回 类型 说明
result list Join records by field equality, preserving left and matching-right order

Use a, b, key, right_key, mode="inner" as the inputs for this operation.

Effects: pure.

Join records by field equality, preserving left and matching-right order. mode is inner/left; colliding right fields use right_ prefix; unresolved name collisions fail.

Return [Join records by field equality, preserving left and matching-right order](> host_table_join a=a b=b key=key right_key=right_key mode=mode).

cast

参数 类型 默认 说明
rows list required List of row records, rather than an implicit column map
schema map required Field/type record using the standard contract type vocabulary
返回 类型 说明
result list Convert schema fields to text/int/number/bool/any; missing or invalid cells report row and field

Use rows, schema as the inputs for this operation.

Effects: pure.

Convert schema fields to text/int/number/bool/any; missing or invalid cells report row and field. Other fields survive.

Return [Convert schema fields to text/int/number/bool/any; missing or invalid cells report row and field](> host_table_cast rows=rows schema=schema).

union

参数 类型 默认 说明
a list required First operand; its domain is described by this operation
b list required Second operand; its domain is described by this operation
返回 类型 说明
result list Stable set union; first occurrences win, using the same type-sensitive equality as unique

Use a, b as the inputs for this operation.

Effects: pure.

Stable set union; first occurrences win, using the same type-sensitive equality as unique.

Return [Stable set union; first occurrences win, using the same type-sensitive equality as unique](> host_table_union a=a b=b).

intersection

参数 类型 默认 说明
a list required First operand; its domain is described by this operation
b list required Second operand; its domain is described by this operation
返回 类型 说明
result list Stable set intersection; duplicates are removed

Use a, b as the inputs for this operation.

Effects: pure.

Stable set intersection; duplicates are removed.

Return [Stable set intersection; duplicates are removed](> host_table_intersection a=a b=b).

difference

参数 类型 默认 说明
a list required First operand; its domain is described by this operation
b list required Second operand; its domain is described by this operation
返回 类型 说明
result list Stable values in a but not b; duplicates are removed

Use a, b as the inputs for this operation.

Effects: pure.

Stable values in a but not b; duplicates are removed.

Return [Stable values in a but not b; duplicates are removed](> host_table_difference a=a b=b).

try_cast

参数 类型 默认 说明
rows list required List of row records, rather than an implicit column map
schema map required Field/type record using the standard contract type vocabulary
返回 类型 说明
result map Recoverable cast; invalid fields return Result instead of aborting the caller

Use rows, schema as the inputs for this operation.

Effects: pure.

Recoverable cast; invalid fields return Result instead of aborting the caller.

Return [Recoverable cast; invalid fields return Result instead of aborting the caller](> host_table_try_cast rows=rows schema=schema).

validate

参数 类型 默认 说明
rows list required List of row records, rather than an implicit column map
schema map required Field/type record using the standard contract type vocabulary
返回 类型 说明
result map Validate required fields using core gradual types, returning Result with error

Use rows, schema as the inputs for this operation.

Effects: pure.

Validate required fields using core gradual types, returning Result with error.details row/field diagnostics. int is the core number alias; use cast for strict integer conversion.

Return [Validate required fields using core gradual types, returning Result with error.details row/field diagnostics](> host_table_validate rows=rows schema=schema).

find

参数 类型 默认 说明
list list required Ordered row records to test without changing their order
key text required Field name whose value is compared in each row
value any required Comparison operand; in tests membership in this supplied collection
op text "eq" Comparison: eq, ne, gt, ge, lt, le, contains or in; invalid operators fail
返回 类型 说明
result any First matching row, or None when no row matches

Use list, key, value, op="eq" as the inputs for this operation.

Effects: pure.

Use the same comparison as where. Missing fields and invalid operators still produce a diagnostic; the input rows remain unchanged.

We retain selected = [Where](where(list=list, key=key, value=value, op=op)). Return First.

any

参数 类型 默认 说明
list list required Ordered row records to test without changing their order
key text required Field name whose value is compared in each row
value any required Comparison operand; in tests membership in this supplied collection
op text "eq" Comparison: eq, ne, gt, ge, lt, le, contains or in; invalid operators fail
返回 类型 说明
result bool Whether at least one row matches; false on an empty list

Use list, key, value, op="eq" as the inputs for this operation.

Effects: pure.

Use the same comparison as where. Missing fields and invalid operators still produce a diagnostic; the input rows remain unchanged.

We retain selected = [Where](where(list=list, key=key, value=value, op=op)). We retain matched = Len. Return matched > 0.

all

参数 类型 默认 说明
list list required Ordered row records to test without changing their order
key text required Field name whose value is compared in each row
value any required Comparison operand; in tests membership in this supplied collection
op text "eq" Comparison: eq, ne, gt, ge, lt, le, contains or in; invalid operators fail
返回 类型 说明
result bool Whether every row matches; true on an empty list

Use list, key, value, op="eq" as the inputs for this operation.

Effects: pure.

Use the same comparison as where. Missing fields and invalid operators still produce a diagnostic; the input rows remain unchanged.

We retain selected = [Where](where(list=list, key=key, value=value, op=op)). We retain matched = Len. We retain total = Len. Return matched == total.

summarize

参数 类型 默认 说明
list list required Input list; immutable updates return a new list
key text required Field name or storage key to read, compare or update
field text required Numeric field to aggregate within each group
op text "sum" Operation name understood by this helper
返回 类型 说明
result list Group by key and aggregate one field in a batch, returning first-seen key/count/value records

Use list, key, field, op="sum" as the inputs for this operation.

Effects: pure.

Group by key and aggregate one field in a batch, returning first-seen key/count/value records. Uses aggregate semantics and avoids repeatedly copying a growing output list in author loops.

Return [Group by key and aggregate one field in a batch, returning first-seen key/count/value records](> host_table_summarize list=list key=key field=field op=op).

from_pairs

参数 类型 默认 说明
pairs list required Ordered row records with text key and arbitrary value fields; extra fields are ignored
返回 类型 说明
result map New record in first-key insertion order; later entries replace an existing key's value

Effects: pure.

The input pairs makes a long named record readable as an @ table with key/value columns. Use this when a horizontal record would become too wide to inspect, such as prompt sections or configuration fragments. It uses the same ordinary row records and immutable map update as the rest of this library; no JSON text or alternate schema language is parsed. An empty list returns an empty record. Invalid keys are rejected by put, rather than silently creating a dummy column.

We begin with record = Create a new record. Each row contributes one explicit field; repeated keys update that field while keeping the position of its first occurrence.

After processing the ordered rows, return record. The original pairs remain available to the caller; this function performs no filesystem, network or plugin operation.