doc expressions: Document 'zip_with' and 'zip_map'

1 files changed, 24 insertions, 0 deletions

diff --git a/doc/concepts/expressions.md b/doc/concepts/expressions.md
index 79b114f3..74058f84 100644
--- a/doc/concepts/expressions.md
+++ b/doc/concepts/expressions.md
@@ -219,6 +219,30 @@ variables specified at `"var_key"` and `"var_val"` (literal
 strings, default values `"_"` and `"$_"`, respectively). The
 result of the evaluation is the list of those values.
 
+##### Zipping
+
+###### `"zip_with"`
+
+The keys `"range_1"` and `"range_2"` are evaluated and have
+to evaluate to lists. For each pair of entries, one from each
+list, in order, the expression `"body"` is evaluated in an
+environment obtained from the original one by correspondingly
+setting the variables specified at `"var_1"` and `"var_2"`
+(default values `"$1"` and `"$2"`, respectively). The result of
+the evaluation is the list of those values. If the input lists
+are of different lengths, any entry with no correspondence in
+the other list is ignored.
+
+###### `"zip_map"`
+
+The keys `"range_key"` and `"range_val"` are evaluated and have
+to evaluate to lists. The result is a map, from an entry in
+`"range_key"` to the entry in `"range_val"` with the same index.
+If the input lists are of different lengths, any entry with no
+correspondence in the other list is ignored. It is equivalent but
+more convenient and more performant to a `"zip_with"` expression
+generating a list of maps combined with a `map_union`.
+
 ##### Folding: `"foldl"`
 
 The key `"range"` is evaluated and has to evaluate to a list.