docs/howto: use list.Contains to search in a list

This adds a Commented CUE guide demonstrating how to use list.Contains
to report if value is found in a list.

The function call is initially demonstrated with an inline example, and
then in slightly more structured form with 2x2 simple and 1x2 composite
examples. It's important to include the composite example to show the
range of options that /don't/ trigger a positive result - i.e. what CUE
/doesn't/ consider a match by this function's standards.

Preview-Path: /docs/howto/use-the-builtin-function-list-contains-to-report-if-a-value-is-in-a-list/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I5db7e64b786f239d031cfec00e4ba50db0ef8e0f
Dispatch-Trailer: {"type":"trybot","CL":1174384,"patchset":1,"ref":"refs/changes/84/1174384/1","targetBranch":"alpha"}

content/docs/howto/use-the-builtin-function-list-contains-to-report-if-a-value-is-in-a-list/en.md

@@ -0,0 +1,110 @@
+---
+title: Using the builtin function "list.Contains" to report if a value is contained in a list
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the builtin function `list.Contains` to report if a
+simple or composite value is contained in a list.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "list"
+
+inline: list.Contains([1, 2, "3", 4, "five"], 4)
+
+numbers: {
+	haystack1: list.Contains(_haystack1, _needle)
+	haystack2: list.Contains(_haystack2, _needle)
+
+	_needle: 42
+	// _haystack1 does *not* contain the needle.
+	_haystack1: [-10, 0, 10, 20, 30, 40, 50]
+	// _haystack2 *does* contain the needle.
+	_haystack2: [-10, 0, 42, 20, 30, 42, 50]
+}
+
+strings: {
+	haystack1: list.Contains(_haystack1, _needle)
+	haystack2: list.Contains(_haystack2, _needle)
+
+	_needle: "A Needle"
+	// _haystack1 does *not* contain the needle.
+	_haystack1: ["some hay", "more hay", "nothing but hay"]
+	// _haystack2 *does* contain the needle.
+	_haystack2: ["some hay", "more hay", "A Needle", "even more hay"]
+}
+
+composite: {
+	haystack1: list.Contains(_haystack1, _needle)
+	haystack2: list.Contains(_haystack2, _needle)
+
+	_needle: {
+		a: 42
+		b: c: "A Needle"
+	}
+	// _haystack1 does *not* contain the needle.
+	_haystack1: [
+		{
+			a: 42
+			b: c: "a needle"
+		},
+		{
+			a: 42
+			b: c: "A Needle"
+			b: d: "An extra field"
+		},
+		{
+			a: 42
+			B: c: "A Needle"
+		},
+		{
+			a: 42
+			b: c: "A Needle": ".. as a key, not a value"
+		},
+		{
+			a: 42.0
+			b: c: "A Needle"
+		},
+	]
+	// _haystack2 *does* contain the needle.
+	_haystack2: [
+		-10,
+		0,
+		"some hay",
+		"more hay",
+		{
+			a: 42
+			b: c: "A Needle"
+		},
+	]
+}
+-- out --
+inline: true
+numbers: {
+    haystack1: false
+    haystack2: true
+}
+strings: {
+    haystack1: false
+    haystack2: true
+}
+composite: {
+    haystack1: false
+    haystack2: true
+}
+{{{end}}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) builtin package

content/docs/howto/use-the-builtin-function-list-contains-to-report-if-a-value-is-in-a-list/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-builtin-function-list-contains-to-report-if-a-value-is-in-a-list": {
+					page: {
+						cache: {
+							code: {
+								cc: "NKcfxC3yjQXOUiE7eOgkUdtMBiENqjOOhzLbOW9VELM="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-builtin-function-list-contains-to-report-if-a-value-is-in-a-list/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-builtin-function-list-contains-to-report-if-a-value-is-in-a-list": {}

hugo/content/en/docs/howto/use-the-builtin-function-list-contains-to-report-if-a-value-is-in-a-list/index.md

@@ -0,0 +1,109 @@
+---
+title: Using the builtin function "list.Contains" to report if a value is contained in a list
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the builtin function `list.Contains` to report if a
+simple or composite value is contained in a list.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "list"
+
+inline: list.Contains([1, 2, "3", 4, "five"], 4)
+
+numbers: {
+	haystack1: list.Contains(_haystack1, _needle)
+	haystack2: list.Contains(_haystack2, _needle)
+
+	_needle: 42
+	// _haystack1 does *not* contain the needle.
+	_haystack1: [-10, 0, 10, 20, 30, 40, 50]
+	// _haystack2 *does* contain the needle.
+	_haystack2: [-10, 0, 42, 20, 30, 42, 50]
+}
+
+strings: {
+	haystack1: list.Contains(_haystack1, _needle)
+	haystack2: list.Contains(_haystack2, _needle)
+
+	_needle: "A Needle"
+	// _haystack1 does *not* contain the needle.
+	_haystack1: ["some hay", "more hay", "nothing but hay"]
+	// _haystack2 *does* contain the needle.
+	_haystack2: ["some hay", "more hay", "A Needle", "even more hay"]
+}
+
+composite: {
+	haystack1: list.Contains(_haystack1, _needle)
+	haystack2: list.Contains(_haystack2, _needle)
+
+	_needle: {
+		a: 42
+		b: c: "A Needle"
+	}
+	// _haystack1 does *not* contain the needle.
+	_haystack1: [
+		{
+			a: 42
+			b: c: "a needle"
+		},
+		{
+			a: 42
+			b: c: "A Needle"
+			b: d: "An extra field"
+		},
+		{
+			a: 42
+			B: c: "A Needle"
+		},
+		{
+			a: 42
+			b: c: "A Needle": ".. as a key, not a value"
+		},
+		{
+			a: 42.0
+			b: c: "A Needle"
+		},
+	]
+	// _haystack2 *does* contain the needle.
+	_haystack2: [
+		-10,
+		0,
+		"some hay",
+		"more hay",
+		{
+			a: 42
+			b: c: "A Needle"
+		},
+	]
+}
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue eval
+inline: true
+numbers: {
+    haystack1: false
+    haystack2: true
+}
+strings: {
+    haystack1: false
+    haystack2: true
+}
+composite: {
+    haystack1: false
+    haystack2: true
+}
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) builtin package