Skip to content

List Transforms

Normative reference

See the Transforms reference for the normative definition of each transform below, plus worked examples.

Most of the 16 transforms below operate on list input; first, last, and size also accept strings (first/last character, character count). A list whose shape does not match a transform's expectations (a non-list input, or contents of the wrong type) yields null (a soft failure); a malformed argument list is a transform error.

Name Arguments Description
compact — Removes null elements.
concat: other (a list) Appends other's elements.
first — First element of a list, or first character of a string.
last — Last element of a list, or last character of a string.
size — Element count of a list, or character count of a string.
join: separator? (default " ") Joins elements (string-coerced) with separator.
reverse — Reverses element order.
sort: property? Sorts elements. With no argument, sorts the elements themselves; with property, sorts by that property of each element (a struct). Keys must be uniformly numeric or uniformly string, else null.
sum: property? Sums numeric elements, or a numeric property of each element. null if any value is non-numeric.
uniq — Removes duplicates, comparing by string form (first occurrence wins).
map: property Projects each element (a struct) to its property value, resolved via a KPointer — a bare key like "name" uses dot-notation, "/addr/city" uses an RFC 6901 pointer. Requires every element to be a struct.
where: property value? Filters to elements (structs) matching a predicate: with value, elements whose property string-equals value; with no value, elements whose property is truthy.
reject: property value? The inverse of where — elements that do not match the predicate.
find: property value? The first element (a struct) matching the same predicate as where. A soft failure (NoMatch, yielding null) when nothing matches.
find_index: property value? The index of the first matching element. A soft failure (NoMatch, yielding null) when nothing matches.
has: property value? true/false — whether any element matches the same predicate as where.

Examples

{{#each items | sort: "price" }}
  {{ name }}: {{ price }}
{{/each}}

{{ users | where: "active" | map: "email" | join: ", " }}

{{ items | sum }}                     {{! sum of numeric elements }}
{{ items | sum: "quantity" }}          {{! sum of each element's "quantity" field }}

{{ users | find: "role" "admin" }}     {{! the first admin user's struct, or null }}

Where to next

  • Transforms overview — the pipe operator and argument forms.
  • Blocks — {{#each}} iterates the same list a transform pipeline can filter/sort/map first.
  • Interpolation — the identifier/pointer forms map/where/sort/sum accept as a property argument.