docs/howto: use list.{Avg,Max,Min,Sum}

This adds a Commented CUE guide that demonstrates the use of list.Avg,
list.Max, list.Min and list.Sum to produce simple summary statistics of
numeric lists.

A manually calculated mean using len() and the result of list.Sum is
included in order to highlight the equivalence of this method and
list.Avg. List contents are selected that elongate the mean's decimal
representation, which further highlights the two methods' equality.

Preview-Path: /docs/howto/use-the-built-in-functions-list-avg-list-max-list-min-list-sum-to-summarise-lists-of-numbers/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I439b302a51f84c724af58c4f9c56ecca912778ae
Dispatch-Trailer: {"type":"trybot","CL":1174381,"patchset":3,"ref":"refs/changes/81/1174381/3","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-functions-list-avg-list-max-list-min-list-sum-to-summarise-lists-of-numbers/en.md

@@ -0,0 +1,52 @@
+---
+title: Using the built-in functions "list.Avg", "list.Max", "list.Min, and "list.Sum" to summarise lists of numbers
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in functions `list.Avg`, `list.Max`,
+`list.Min` and `list.Sum` to calculate various simple summary statistics for a
+list of numbers including the list's arithmetic mean, its maximum and minimum
+values, and the sum of its values.
+
+{{{with code "en" "cc"}}}
+#location left right
+
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "list"
+
+sum:  list.Sum(_data)
+min:  list.Min(_data)
+max:  list.Max(_data)
+mean: list.Avg(_data)
+
+manualMean: sum / len(_data)
+
+_data: [
+	-0.00000000001,
+	0,
+	1,
+	5,
+	10,
+	42,
+	-999,
+]
+-- out --
+sum:        -941.00000000001
+min:        -999
+max:        42
+mean:       -134.4285714285728571428571428571429
+manualMean: -134.4285714285728571428571428571429
+{{{end}}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

content/docs/howto/use-the-built-in-functions-list-avg-list-max-list-min-list-sum-to-summarise-lists-of-numbers/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-functions-list-avg-list-max-list-min-list-sum-to-summarise-lists-of-numbers": {
+					page: {
+						cache: {
+							code: {
+								cc: "5rBRQCW3czcAE68hKXRNyM1yY5RJP7Z1i3NXzQDbTqI="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-functions-list-avg-list-max-list-min-list-sum-to-summarise-lists-of-numbers/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-functions-list-avg-list-max-list-min-list-sum-to-summarise-lists-of-numbers": {}

hugo/content/en/docs/howto/use-the-built-in-functions-list-avg-list-max-list-min-list-sum-to-summarise-lists-of-numbers/index.md

@@ -0,0 +1,51 @@
+---
+title: Using the built-in functions "list.Avg", "list.Max", "list.Min, and "list.Sum" to summarise lists of numbers
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in functions `list.Avg`, `list.Max`,
+`list.Min` and `list.Sum` to calculate various simple summary statistics for a
+list of numbers including the list's arithmetic mean, its maximum and minimum
+values, and the sum of its values.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="left" >}}
+package example
+
+import "list"
+
+sum:  list.Sum(_data)
+min:  list.Min(_data)
+max:  list.Max(_data)
+mean: list.Avg(_data)
+
+manualMean: sum / len(_data)
+
+_data: [
+	-0.00000000001,
+	0,
+	1,
+	5,
+	10,
+	42,
+	-999,
+]
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="right" >}}
+$ cue eval
+sum:        -941.00000000001
+min:        -999
+max:        42
+mean:       -134.4285714285728571428571428571429
+manualMean: -134.4285714285728571428571428571429
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package