diff --git a/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/en.md b/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/en.md new file mode 100644 index 000000000..1c934a22d --- /dev/null +++ b/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/en.md @@ -0,0 +1,92 @@ +--- +title: Using the built-in function "list.Contains" to report if a value is 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 built-in function +[`list.Contains`](https://pkg.go.dev/cuelang.org/go/pkg/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" + +// When passed two arguments, list.Contains returns a boolean value reporting +// if the second argument is an element present at the top level of the first. +contains: list.Contains([1, 2, 3, 4, 5], 4) + +// The example contents of _source are assigned below. +_source: [...] + +// Either of list.Contains' arguments may be a reference. +containsBasicInt: list.Contains(_source, 1) +containsBasicString: list.Contains(_source, "TWO") + +// If the second argument is a struct, then for a match to be reported all the +// struct's fields must be present inside a single struct member of the first +// argument, with both structs' fields holding equivalent values. There must be +// no additional fields present. +containsStructMissingField: list.Contains(_source, { + asInt: 3 +}) +containsStructAllFields: list.Contains(_source, { + asInt: 3 + asString: "three" +}) +containsStructExtraFields: list.Contains(_source, { + asInt: 3 + asString: "three" + asFloat: 3.0 +}) + +// If the second argument is a list, then the entire list must be an element +// present at the top level of the first argument, with both lists' elements +// holding the same values in the same order. +containsListMissingElement: list.Contains(_source, ["four"]) +containsListAllElementsIncorrectOrder: list.Contains(_source, ["four", 4]) +containsListAllElementsCorrectOrder: list.Contains(_source, [4, "four"]) +containsListExtraElements: list.Contains(_source, ["four", 4, 4.0]) + +_source: [ + 1, "two", + {asInt: 3, asString: "three"}, + [4, "four"], +] +-- out -- +contains: true +containsBasicInt: true +containsBasicString: false +containsStructMissingField: false +containsStructAllFields: true +containsStructExtraFields: false +containsListMissingElement: false +containsListAllElementsIncorrectOrder: false +containsListAllElementsCorrectOrder: true +containsListExtraElements: false +{{{end}}} + +{{< info >}} +[Issue #49](https://github.com/cue-lang/docs-and-content/issues/49) tracks the +documentation of precisely what CUE means by values being "equivalent", +"equal", or "comparable". When this documentation is complete it will be linked +to, and fewer examples will be presented in this guide. +{{< /info >}} + +## Related content + +- `list.Contains` can also be used + [as a field validator]({{< relref + "../use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list" + >}}) +- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package diff --git a/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/gen_cache.cue b/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/gen_cache.cue new file mode 100644 index 000000000..4ceffe289 --- /dev/null +++ b/content/docs/howto/use-the-built-in-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-built-in-function-list-contains-to-report-if-a-value-is-in-a-list": { + page: { + cache: { + code: { + cc: "7y8OZIMI60CsLiJQHcQ6gsT0ztL7h/dnmw2hLL39RMk=" + } + } + } + } + } + } + } +} diff --git a/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/page.cue b/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/page.cue new file mode 100644 index 000000000..a511da125 --- /dev/null +++ b/content/docs/howto/use-the-built-in-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-built-in-function-list-contains-to-report-if-a-value-is-in-a-list": {} diff --git a/content/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/en.md b/content/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/en.md new file mode 100644 index 000000000..13570165a --- /dev/null +++ b/content/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/en.md @@ -0,0 +1,132 @@ +--- +title: Using the built-in function "list.Contains" to validate that a value is 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 built-in function +[`list.Contains`](https://pkg.go.dev/cuelang.org/go/pkg/list#Contains) +as a validator that checks if a simple or composite value is contained in a +list. + +{{{with code "en" "cc"}}} +#location top bottom + +! exec cue vet +cmp stderr out +-- file.cue -- +package example + +import "list" + +// The example contents of aList are assigned below. +aList: [...] + +// When passed a single argument and unified with a list, list.Contains emits +// an error if the argument is not an element present at the top level of the +// unified list. +aList: list.Contains(1) +aList: list.Contains("TWO") + +// If the argument is a struct, then all the struct's fields must be present +// inside a single struct member of the unified list, with both structs' fields +// holding equivalent values. There must be no additional fields present. +aList: list.Contains({asInt: 3}) +aList: list.Contains({asInt: 3, asString: "three"}) +aList: list.Contains({asInt: 3, asString: "three", asFloat: 3.0}) + +// If the argument is a list, then the entire list must be an element present +// at the top level of the unified list, with both lists' elements holding the +// same values in the same order. +aList: list.Contains(["four"]) +aList: list.Contains(["four", 4]) +aList: list.Contains([4, "four"]) +aList: list.Contains(["four", 4, 4.0]) + +aList: [ + 1, "two", + {asInt: 3, asString: "three"}, + [4, "four"], +] +-- out -- +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains("TWO")): + ./file.cue:12:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:22 + ./file.cue:17:8 + ./file.cue:18:8 + ./file.cue:19:8 + ./file.cue:24:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:27:8 + ./file.cue:29:8 +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains({asInt:3})): + ./file.cue:17:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:8 + ./file.cue:18:8 + ./file.cue:19:8 + ./file.cue:24:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:27:8 + ./file.cue:29:8 +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains({asInt:3,asString:"three",asFloat:3.0})): + ./file.cue:19:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:8 + ./file.cue:17:8 + ./file.cue:18:8 + ./file.cue:24:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:27:8 + ./file.cue:29:8 +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains(["four"])): + ./file.cue:24:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:8 + ./file.cue:17:8 + ./file.cue:18:8 + ./file.cue:19:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:27:8 + ./file.cue:29:8 +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains(["four",4,4.0])): + ./file.cue:27:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:8 + ./file.cue:17:8 + ./file.cue:18:8 + ./file.cue:19:8 + ./file.cue:24:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:29:8 +{{{end}}} + +{{< info >}} +[Issue #49](https://github.com/cue-lang/docs-and-content/issues/49) tracks the +documentation of precisely what CUE means by values being "equivalent", +"equal", or "comparable". When this documentation is complete it will be linked +to, and fewer examples will be presented in this guide. +{{< /info >}} + +## Related content + +- `list.Contains` can also be used + [to report if a value is in a list]({{< relref + "../use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list" + >}}) +- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package diff --git a/content/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/gen_cache.cue b/content/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/gen_cache.cue new file mode 100644 index 000000000..eeb7e5ca6 --- /dev/null +++ b/content/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/gen_cache.cue @@ -0,0 +1,18 @@ +package site +{ + content: { + docs: { + howto: { + "use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list": { + page: { + cache: { + code: { + cc: "hv8PfR/54xrzDBdAYXVKZCrJ+3ampKOVguKYaTTqDAg=" + } + } + } + } + } + } + } +} diff --git a/content/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/page.cue b/content/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/page.cue new file mode 100644 index 000000000..68269262b --- /dev/null +++ b/content/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/page.cue @@ -0,0 +1,3 @@ +package site + +content: docs: howto: "use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list": {} diff --git a/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/index.md b/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/index.md new file mode 100644 index 000000000..a47fed247 --- /dev/null +++ b/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/index.md @@ -0,0 +1,91 @@ +--- +title: Using the built-in function "list.Contains" to report if a value is 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 built-in function +[`list.Contains`](https://pkg.go.dev/cuelang.org/go/pkg/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" + +// When passed two arguments, list.Contains returns a boolean value reporting +// if the second argument is an element present at the top level of the first. +contains: list.Contains([1, 2, 3, 4, 5], 4) + +// The example contents of _source are assigned below. +_source: [...] + +// Either of list.Contains' arguments may be a reference. +containsBasicInt: list.Contains(_source, 1) +containsBasicString: list.Contains(_source, "TWO") + +// If the second argument is a struct, then for a match to be reported all the +// struct's fields must be present inside a single struct member of the first +// argument, with both structs' fields holding equivalent values. There must be +// no additional fields present. +containsStructMissingField: list.Contains(_source, { + asInt: 3 +}) +containsStructAllFields: list.Contains(_source, { + asInt: 3 + asString: "three" +}) +containsStructExtraFields: list.Contains(_source, { + asInt: 3 + asString: "three" + asFloat: 3.0 +}) + +// If the second argument is a list, then the entire list must be an element +// present at the top level of the first argument, with both lists' elements +// holding the same values in the same order. +containsListMissingElement: list.Contains(_source, ["four"]) +containsListAllElementsIncorrectOrder: list.Contains(_source, ["four", 4]) +containsListAllElementsCorrectOrder: list.Contains(_source, [4, "four"]) +containsListExtraElements: list.Contains(_source, ["four", 4, 4.0]) + +_source: [ + 1, "two", + {asInt: 3, asString: "three"}, + [4, "four"], +] +{{< /code-tab >}} +{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}} +$ cue eval +contains: true +containsBasicInt: true +containsBasicString: false +containsStructMissingField: false +containsStructAllFields: true +containsStructExtraFields: false +containsListMissingElement: false +containsListAllElementsIncorrectOrder: false +containsListAllElementsCorrectOrder: true +containsListExtraElements: false +{{< /code-tab >}} +{{< /code-tabs >}} + +{{< info >}} +[Issue #49](https://github.com/cue-lang/docs-and-content/issues/49) tracks the +documentation of precisely what CUE means by values being "equivalent", +"equal", or "comparable". When this documentation is complete it will be linked +to, and fewer examples will be presented in this guide. +{{< /info >}} + +## Related content + +- `list.Contains` can also be used + [as a field validator]({{< relref + "../use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list" + >}}) +- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package diff --git a/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/index.md b/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/index.md new file mode 100644 index 000000000..1ab4fbb5e --- /dev/null +++ b/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/index.md @@ -0,0 +1,131 @@ +--- +title: Using the built-in function "list.Contains" to validate that a value is 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 built-in function +[`list.Contains`](https://pkg.go.dev/cuelang.org/go/pkg/list#Contains) +as a validator that checks 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" + +// The example contents of aList are assigned below. +aList: [...] + +// When passed a single argument and unified with a list, list.Contains emits +// an error if the argument is not an element present at the top level of the +// unified list. +aList: list.Contains(1) +aList: list.Contains("TWO") + +// If the argument is a struct, then all the struct's fields must be present +// inside a single struct member of the unified list, with both structs' fields +// holding equivalent values. There must be no additional fields present. +aList: list.Contains({asInt: 3}) +aList: list.Contains({asInt: 3, asString: "three"}) +aList: list.Contains({asInt: 3, asString: "three", asFloat: 3.0}) + +// If the argument is a list, then the entire list must be an element present +// at the top level of the unified list, with both lists' elements holding the +// same values in the same order. +aList: list.Contains(["four"]) +aList: list.Contains(["four", 4]) +aList: list.Contains([4, "four"]) +aList: list.Contains(["four", 4, 4.0]) + +aList: [ + 1, "two", + {asInt: 3, asString: "three"}, + [4, "four"], +] +{{< /code-tab >}} +{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}} +$ cue vet +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains("TWO")): + ./file.cue:12:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:22 + ./file.cue:17:8 + ./file.cue:18:8 + ./file.cue:19:8 + ./file.cue:24:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:27:8 + ./file.cue:29:8 +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains({asInt:3})): + ./file.cue:17:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:8 + ./file.cue:18:8 + ./file.cue:19:8 + ./file.cue:24:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:27:8 + ./file.cue:29:8 +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains({asInt:3,asString:"three",asFloat:3.0})): + ./file.cue:19:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:8 + ./file.cue:17:8 + ./file.cue:18:8 + ./file.cue:24:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:27:8 + ./file.cue:29:8 +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains(["four"])): + ./file.cue:24:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:8 + ./file.cue:17:8 + ./file.cue:18:8 + ./file.cue:19:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:27:8 + ./file.cue:29:8 +aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains(["four",4,4.0])): + ./file.cue:27:8 + ./file.cue:6:8 + ./file.cue:11:8 + ./file.cue:12:8 + ./file.cue:17:8 + ./file.cue:18:8 + ./file.cue:19:8 + ./file.cue:24:8 + ./file.cue:25:8 + ./file.cue:26:8 + ./file.cue:29:8 +{{< /code-tab >}} +{{< /code-tabs >}} + +{{< info >}} +[Issue #49](https://github.com/cue-lang/docs-and-content/issues/49) tracks the +documentation of precisely what CUE means by values being "equivalent", +"equal", or "comparable". When this documentation is complete it will be linked +to, and fewer examples will be presented in this guide. +{{< /info >}} + +## Related content + +- `list.Contains` can also be used + [to report if a value is in a list]({{< relref + "../use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list" + >}}) +- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package