cast
Function
cast — coerce a value to a different type
Synopsis
cast(val: any, t: type) -> any
cast(val: any, name: string) -> any
Description
The cast function performs type casts but handles both primitive types and
complex types. If the input type t is a primitive type, then the result
is equivalent to
t(val)
e.g., the result of cast(1, <string>) is the same as string(1) which is "1".
In the second form, where the name argument is a string, cast creates
a new named type where the name for the type is given by name and its
type is given by typeof(val). This provides a convenient mechanism
to create new named types from the input data itself without having to
hard code the type in the Zed source text.
For complex types, the cast function visits each leaf value in val and
casts that value to the corresponding type in t.
When a complex value has multiple levels of nesting,
casting is applied recursively down the tree. For example, cast is recursively
applied to each element in an array of records and recursively applied to each record.
If val is a record (or if any of its nested value is a record):
- absent fields are ignored and omitted from the result,
- extra input fields are passed through unmodified to the result, and
- fields are matched by name and are order independent and the input order is retained.
In other words, cast does not rearrange the order of fields in the input
to match the output type's order but rather just modifies the leaf values.
If a cast fails, an error is returned when casting to primitive types and the input value is returned when casting to complex types.
Many users seeking to cast record values prefer to use the
shape function which applies the cast, fill,
and order functions simultaneously.
Examples
Cast primitives to type ip
echo '"10.0.0.1" 1 "foo"' | zq -z 'cast(this, <ip>)' -
produces
10.0.0.1
error({message:"cannot cast to ip",on:1})
error({message:"cannot cast to ip",on:"foo"})
Cast a record to a different record type
echo '{a:1,b:2}{a:3}{b:4}' | zq -z 'cast(this, <{b:string}>)' -
produces
{a:1,b:"2"}
{a:3}
{b:"4"}
Create a name a typed and cast value to the new type
echo '{a:1,b:2}{a:3,b:4}' | zq -z 'cast(this, "foo")' -
produces
{a:1,b:2}(=foo)
{a:3,b:4}(=foo)
Name data based its properties
echo '{x:1,y:2}{r:3}{x:4,y:5}' | zq -z 'switch ( case has(x) => cast(this, "point") default => cast(this, "radius") ) | sort this' -
produces
{r:3}(=radius)
{x:1,y:2}(=point)
{x:4,y:5}(=point)