docs/howto: use list.{Sort,IsSorted}{,Strings}

This adds 6 Commented CUE guides on the matched pairs of
list.Sort/list.IsSorted and list.SortStrings/list.IsSortedStrings.

One guide is added for each of list.Sort{,Strings}, and two guides are
added for each of list.IsSorted{,Strings} - one for the function's
boolean return form and one for its use as a field validator.

Preview-Path: /docs/howto/use-the-built-in-function-list-issorted-to-report-if-lists-are-sorted-using-a-comparator/
Preview-Path: /docs/howto/use-the-built-in-function-list-issorted-to-validate-that-lists-are-sorted-using-a-comparator/
Preview-Path: /docs/howto/use-the-built-in-function-list-issortedstrings-to-report-if-lists-of-strings-are-sorted-alphabetically/
Preview-Path: /docs/howto/use-the-built-in-function-list-issortedstrings-to-validate-that-lists-of-strings-are-sorted-alphabetically/
Preview-Path: /docs/howto/use-the-built-in-function-list-sort-to-sort-lists-using-a-comparator/
Preview-Path: /docs/howto/use-the-built-in-function-list-sortstrings-to-sort-lists-of-strings-alphabetically/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I8938f36f597d3efe88b66b1b78f218db714ab33d
Dispatch-Trailer: {"type":"trybot","CL":1174391,"patchset":16,"ref":"refs/changes/91/1174391/16","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-function-list-issorted-to-report-if-lists-are-sorted-using-a-comparator/en.md

@@ -0,0 +1,89 @@
+---
+title: Using the built-in function "list.IsSorted" to report if lists are sorted using a comparator
+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.IsSorted`](https://pkg.go.dev/cuelang.org/go/pkg/list#IsSorted)
+to test and report if lists are sorted, using either a predefined or custom
+comparator.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "list"
+
+// When testing lists that are composed of only numbers or only strings,
+// list.IsSorted may be provided with one of the predefined comparators
+// "list.Ascending" or "list.Descending".
+isSorted: list.IsSorted([1, 2.2, 3], list.Ascending)
+
+// Testing if lists of strings are sorted alphabetically may also be
+// performed with list.IsSortedStrings (see "Related content", below).
+// Testing if lists of strings have any other sort order, including reverse
+// alphabetical order, requires list.IsSorted.
+stringsDescendingTrue: list.IsSorted(["C", "B", "A"], list.Descending)
+stringsDescendingFalse: list.IsSorted(["A", "B", "C"], list.Descending)
+
+// When testing lists containing other types (or a mixture of types),
+// list.IsSorted must be provided with a custom comparator.
+structsCustomTrue: list.IsSorted([{a: 1}, {a: 2}, {a: 3}], {x: {}, y: {}, less: x.a < y.a})
+structsCustomFalse: list.IsSorted([{a: 2}, {a: 3}, {a: 1}], {x: {}, y: {}, less: x.a < y.a})
+
+// The comparator defines how to compare the list's elements, and must adhere
+// to the list.Comparer schema (see output, below).
+comparatorSchema: list.Comparer
+
+// The comparator's "less" field encodes a comparison between its "x" and "y"
+// fields' values.  It can contain any comparison logic needed to express a
+// particular sort order.
+// The "x" and "y" fields might hold any pair of the list's elements during the
+// sort operation.
+// The "less" field must be an expression that is able to compare any two
+// elements from lists that the comparator will handle. It must evaluate to a
+// boolean value that reports if "x" is less than "y".
+_sortStringsDescendingLength: {
+	x:    string
+	y:    string
+	less: len(x) > len(y)
+}
+
+// The comparator does not need to be provided inline - it may be a reference.
+stringsLengthDescendingTrue: list.IsSorted(["AAA", "AA", "A"], _sortStringsDescendingLength)
+stringsLengthDescendingFalse: list.IsSorted(["A", "AA", "AAA"], _sortStringsDescendingLength)
+-- out --
+isSorted:               true
+stringsDescendingTrue:  true
+stringsDescendingFalse: false
+structsCustomTrue:      true
+structsCustomFalse:     false
+comparatorSchema: {
+    T:    _
+    x:    _
+    y:    _
+    less: bool
+}
+stringsLengthDescendingTrue:  true
+stringsLengthDescendingFalse: false
+{{{end}}}
+
+## Related content
+
+- `list.IsSorted` can also be used [as a field validator]({{< relref
+    "../use-the-built-in-function-list-issorted-to-validate-that-lists-are-sorted-using-a-comparator"
+  >}})
+- Use `list.IsSortStrings`
+  [to test and report if lists of strings are sorted alphabetically]({{< relref
+    "../use-the-built-in-function-list-issortedstrings-to-report-if-lists-of-strings-are-sorted-alphabetically"
+  >}}) without needing to define a comparator
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

content/docs/howto/use-the-built-in-function-list-issorted-to-report-if-lists-are-sorted-using-a-comparator/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-list-issorted-to-report-if-lists-are-sorted-using-a-comparator": {
+					page: {
+						cache: {
+							code: {
+								cc: "cj2xqW4HrhrZ6Kq0axCoL+ebDSW8RXypPM4yyXYlvFM="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-function-list-issorted-to-report-if-lists-are-sorted-using-a-comparator/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-list-issorted-to-report-if-lists-are-sorted-using-a-comparator": {}

content/docs/howto/use-the-built-in-function-list-issorted-to-validate-that-lists-are-sorted-using-a-comparator/en.md

@@ -0,0 +1,84 @@
+---
+title: Using the built-in function "list.IsSorted" to validate that lists are sorted using a comparator
+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.IsSorted`](https://pkg.go.dev/cuelang.org/go/pkg/list#IsSorted)
+as a field validator to assert that lists are sorted, using either a predefined
+or custom comparator.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+import "list"
+
+// When validating lists that are composed of only numbers or only strings,
+// list.IsSorted may be provided with one of the predefined comparators
+// "list.Ascending" or "list.Descending".
+numbersAscending: [1, 2.2, 3]
+numbersAscending: list.IsSorted(list.Ascending)
+
+// Validating that lists of strings are sorted alphabetically may also be
+// performed with list.IsSortedStrings (see "Related content", below).
+// Validating that lists of strings have any other sort order, including
+// reverse alphabetical order, requires list.IsSorted.
+stringsDescending: ["A", "B", "C"]
+stringsDescending: list.IsSorted(list.Descending) // validation failure
+
+// When validating lists containing other types (or a mixture of types),
+// list.IsSorted must be provided with a custom comparator.
+structsCustom: list.IsSorted({x: {}, y: {}, less: x.a < y.a})
+structsCustom: [{a: 1}, {a: 2}, {a: 3}]
+
+// The comparator defines how to compare the list's elements, and must adhere
+// to the list.Comparer schema (see output, below).
+comparatorSchema: list.Comparer
+
+// The comparator's "less" field encodes a comparison between its "x" and "y"
+// fields' values.  It can contain any comparison logic needed to express a
+// particular sort order.
+// The "x" and "y" fields might hold any pair of the list's elements during the
+// sort operation.
+// The "less" field must be an expression that is able to compare any two
+// elements from lists that the comparator will handle. It must evaluate to a
+// boolean value that reports if "x" is less than "y".
+_sortStringsDescendingLength: {
+	x:    string
+	y:    string
+	less: len(x) > len(y)
+}
+
+// The comparator does not need to be provided inline - it may be a reference.
+stringsLengthDescending: ["AA", "BBB", "C"]
+stringsLengthDescending: list.IsSorted(_sortStringsDescendingLength) // validation failure
+-- out --
+stringsDescending: invalid value ["A","B","C"] (does not satisfy list.IsSorted({T:number | string,x:number | string,y:number | string,less:_|_(Descending.less: unresolved disjunction number | string (type (string|number)) (and 1 more errors))})):
+    ./file.cue:16:20
+    ./file.cue:15:20
+stringsLengthDescending: invalid value ["AA","BBB","C"] (does not satisfy list.IsSorted({x:string,y:string,less:_|_(_sortStringsDescendingLength.less: incomplete argument string (type string) (and 1 more errors))})):
+    ./file.cue:43:26
+    ./file.cue:42:26
+{{{end}}}
+
+## Related content
+
+- `list.IsSorted` can also be used
+  [to return a list's sort status as a boolean]({{< relref
+    "../use-the-built-in-function-list-issorted-to-report-if-lists-are-sorted-using-a-comparator"
+  >}})
+- Use `list.IsSortStrings`
+  [to validate that lists of strings are sorted alphabetically]({{< relref
+    "../use-the-built-in-function-list-issortedstrings-to-validate-that-lists-of-strings-are-sorted-alphabetically"
+  >}}) without needing to define a comparator
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

content/docs/howto/use-the-built-in-function-list-issorted-to-validate-that-lists-are-sorted-using-a-comparator/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-list-issorted-to-validate-that-lists-are-sorted-using-a-comparator": {
+					page: {
+						cache: {
+							code: {
+								cc: "Rj+X4MvAX/2fJvVNfXRF2zu7HsrUOkJHyM1mfOZu+aI="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-function-list-issorted-to-validate-that-lists-are-sorted-using-a-comparator/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-list-issorted-to-validate-that-lists-are-sorted-using-a-comparator": {}

content/docs/howto/use-the-built-in-function-list-issortedstrings-to-report-if-lists-of-strings-are-sorted-alphabetically/en.md

@@ -0,0 +1,46 @@
+---
+title: Using the built-in function "list.IsSortedStrings" to report if lists of strings are sorted alphabetically
+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.IsSortedStrings`](https://pkg.go.dev/cuelang.org/go/pkg/list#IsSortedStrings)
+to test and report if lists of strings are sorted alphabetically.
+
+{{{with code "en" "cc"}}}
+#location left right
+
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "list"
+
+_unsorted: ["B", "C", "A"]
+_sorted: ["A", "B", "C"]
+
+testUnsorted: list.IsSortedStrings(_unsorted)
+testSorted:   list.IsSortedStrings(_sorted)
+-- out --
+testUnsorted: false
+testSorted:   true
+{{{end}}}
+
+## Related content
+
+- `list.IsSortedStrings` can also be used
+  [as a field validator]({{< relref
+    "../use-the-built-in-function-list-issortedstrings-to-validate-that-lists-of-strings-are-sorted-alphabetically"
+  >}})
+- `list.IsSortedStrings` only tests if lists of strings are sorted
+  alphabetically - use `list.Sort`
+  [to test any other list type or sort order]({{< relref
+    "../use-the-built-in-function-list-issorted-to-report-if-lists-are-sorted-using-a-comparator"
+  >}})
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

content/docs/howto/use-the-built-in-function-list-issortedstrings-to-report-if-lists-of-strings-are-sorted-alphabetically/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-list-issortedstrings-to-report-if-lists-of-strings-are-sorted-alphabetically": {
+					page: {
+						cache: {
+							code: {
+								cc: "W2PCRqt6yZpvpMG4DmnDmGPGS0MI63BVTI3T9yfgm9Q="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-function-list-issortedstrings-to-report-if-lists-of-strings-are-sorted-alphabetically/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-list-issortedstrings-to-report-if-lists-of-strings-are-sorted-alphabetically": {}

content/docs/howto/use-the-built-in-function-list-issortedstrings-to-validate-that-lists-of-strings-are-sorted-alphabetically/en.md

@@ -0,0 +1,47 @@
+---
+title: Using the built-in function "list.IsSortedStrings" to validate that lists of strings are sorted alphabetically
+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.IsSortedStrings`](https://pkg.go.dev/cuelang.org/go/pkg/list#IsSortedStrings)
+as a field validator to assert that lists of strings are sorted alphabetically.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+! exec cue eval
+cmp stderr out
+-- file.cue --
+package example
+
+import "list"
+
+sorted: ["A", "B", "C"]
+unsorted: ["B", "C", "A"]
+
+sorted:   list.IsSortedStrings
+unsorted: list.IsSortedStrings // validation failure
+-- out --
+unsorted: invalid value ["B","C","A"] (does not satisfy list.IsSortedStrings):
+    ./file.cue:6:11
+    ./file.cue:9:11
+{{{end}}}
+
+## Related content
+
+- `list.IsSortedStrings` can also be used
+  [to return a list's sort status as a boolean]({{< relref
+    "../use-the-built-in-function-list-issortedstrings-to-report-if-lists-of-strings-are-sorted-alphabetically"
+  >}})
+- `list.IsSortedStrings` only validates if lists of strings are sorted
+  alphabetically - use `list.IsSorted`
+  [to validate any other list type or sort order]({{< relref
+    "../use-the-built-in-function-list-issorted-to-validate-that-lists-are-sorted-using-a-comparator"
+  >}})
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

content/docs/howto/use-the-built-in-function-list-issortedstrings-to-validate-that-lists-of-strings-are-sorted-alphabetically/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-list-issortedstrings-to-validate-that-lists-of-strings-are-sorted-alphabetically": {
+					page: {
+						cache: {
+							code: {
+								cc: "1hGjlyPgFFcvFQG/zUoCc0gbjLFmpcX+uGHC2brMNg4="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-function-list-issortedstrings-to-validate-that-lists-of-strings-are-sorted-alphabetically/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-list-issortedstrings-to-validate-that-lists-of-strings-are-sorted-alphabetically": {}