diff --git a/docs/language/functions/cast.md b/docs/language/functions/cast.md index 1a65052102..11184470bf 100644 --- a/docs/language/functions/cast.md +++ b/docs/language/functions/cast.md @@ -28,7 +28,7 @@ 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 array of records and recursively applied to each record. +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, @@ -41,6 +41,12 @@ 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. +:::tip +Many users seeking to `cast` record values prefer to use the +[`shape` function](./shape.md) which applies the `cast`, [`fill`](./fill.md), +and [`order`](./order.md) functions simultaneously. +::: + ### Examples _Cast primitives to type `ip`_ diff --git a/docs/language/functions/fill.md b/docs/language/functions/fill.md index e32923d7cb..f7bdf910a8 100644 --- a/docs/language/functions/fill.md +++ b/docs/language/functions/fill.md @@ -11,13 +11,21 @@ fill(val: any, t: type) -> any ### Description The _fill_ function adds to the input record `val` any fields that are -present in the output type `t` but not in the input. +present in the output type `t` but not in the input. Such fields are added +after the fields already present in `t` and in the order they appear in the +input record. Filled fields are added with a `null` value. Filling is useful when you want to be sure that all fields in a schema are present in a record. If `val` is not a record, it is returned unmodified. +:::tip +Many users seeking the functionality of `fill` prefer to use the +[`shape` function](./shape.md) which applies the `fill`, [`cast`](./cast.md), +and [`order`](./order.md) functions simultaneously on a record. +::: + ### Examples _Fill a record_ diff --git a/docs/language/functions/order.md b/docs/language/functions/order.md index 8d5e509a4f..5bc3e9c654 100644 --- a/docs/language/functions/order.md +++ b/docs/language/functions/order.md @@ -26,6 +26,11 @@ the empty record type, i.e., ``` order(val, <{}>) ``` +:::tip +Many users seeking the functionality of `order` prefer to use the +[`shape` function](./shape.md) which applies the `order`, [`cast`](./cast.md), +and [`fill`](./fill.md) functions simultaneously on a record. +::: :::tip Note [Record expressions](../expressions.md#record-expressions) can also be used to diff --git a/docs/language/functions/shape.md b/docs/language/functions/shape.md index ca6ac831a6..120a622b0a 100644 --- a/docs/language/functions/shape.md +++ b/docs/language/functions/shape.md @@ -11,12 +11,12 @@ shape(val: any, t: type) -> any ### Description The _shape_ function applies the -[cast](cast.md), -[fill](fill.md), and -[order](order.md) functions to its input to provide an -overall data shaping operation. +[`cast`](cast.md), +[`fill`](fill.md), and +[`order`](order.md) functions to its input to provide an +overall [data shaping](../shaping.md) operation. -Note that _shape_ does not perform a _crop_ function so +Note that `shape` does not perform a [`crop` function](./crop.md) so extra fields in the input are propagated to the output. ### Examples