From 0212e137d855fbd5d2643c3c2750b30aa65611af Mon Sep 17 00:00:00 2001 From: Phil Rzewski Date: Sun, 7 Jul 2024 14:06:26 -0700 Subject: [PATCH 1/3] Improve docs for shape and a la carte shaping functions --- docs/language/functions/cast.md | 8 +++++++- docs/language/functions/fill.md | 10 ++++++++++ docs/language/functions/order.md | 5 +++++ docs/language/functions/shape.md | 10 +++++----- 4 files changed, 27 insertions(+), 6 deletions(-) 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..37b488cd76 100644 --- a/docs/language/functions/fill.md +++ b/docs/language/functions/fill.md @@ -16,8 +16,18 @@ present in the output type `t` but not in the input. 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. +The order of newly added fields relative to fields already present is +undefined. If maintaining relative order is important, consider applying the +[`order`](./order.md) or [`shape`](./shape) function. + 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 From f12bfdeae4c1bd0a86d8ccb48b50c0a7d0731360 Mon Sep 17 00:00:00 2001 From: Phil Rzewski Date: Sun, 7 Jul 2024 14:13:33 -0700 Subject: [PATCH 2/3] Add missing .md that caused broken link --- docs/language/functions/fill.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/language/functions/fill.md b/docs/language/functions/fill.md index 37b488cd76..671ec967cb 100644 --- a/docs/language/functions/fill.md +++ b/docs/language/functions/fill.md @@ -18,7 +18,7 @@ you want to be sure that all fields in a schema are present in a record. The order of newly added fields relative to fields already present is undefined. If maintaining relative order is important, consider applying the -[`order`](./order.md) or [`shape`](./shape) function. +[`order`](./order.md) or [`shape`](./shape.md) function. If `val` is not a record, it is returned unmodified. From 7b9a253525adbf4a46dc5959a4b34a2260e6bd66 Mon Sep 17 00:00:00 2001 From: Phil Rzewski Date: Mon, 8 Jul 2024 11:50:15 -0700 Subject: [PATCH 3/3] PR feedback: Clarify where fill puts added fields --- docs/language/functions/fill.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/language/functions/fill.md b/docs/language/functions/fill.md index 671ec967cb..f7bdf910a8 100644 --- a/docs/language/functions/fill.md +++ b/docs/language/functions/fill.md @@ -11,15 +11,13 @@ 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. -The order of newly added fields relative to fields already present is -undefined. If maintaining relative order is important, consider applying the -[`order`](./order.md) or [`shape`](./shape.md) function. - If `val` is not a record, it is returned unmodified. :::tip