docs/howto: use list.Sort and list.IsSorted

This adds a Commented CUE guide demonstrating how to use list.Sort and
list.IsSorted.

It also updates the list.SortStrings counterpart guide to point to this
guide in its Related content section.

Preview-Path: /docs/howto/use-the-built-in-functions-list-sort-list-issorted/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I35a6b2a6134f2d1e94a3611778154130f36e72bf
Dispatch-Trailer: {"type":"trybot","CL":1174579,"patchset":5,"ref":"refs/changes/79/1174579/5","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-functions-list-sort-list-issorted/en.md

@@ -0,0 +1,92 @@
+---
+title: Using the built-in functions "list.Sort" and "list.IsSorted" to sort and test lists
+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.Sort` to sort lists, and
+`list.IsSorted` to test that lists are sorted, by using a predefined or custom
+comparator.
+
+{{{with code "en" "cc1"}}}
+#location top bottom
+
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "list"
+
+// When sorting lists that are composed of only numbers or only strings,
+// list.Sort may be provided with one of the predefined comparators
+// "list.Ascending" or "list.Descending".
+numbersAscending: list.Sort([3, 5, 1, 4, 2], list.Ascending)
+
+// Sorting strings alphabetically may also be performed with list.SortStrings
+// (see "Related content", below).
+// Sorting strings in any other way (including reverse alphabetical order)
+// requires list.Sort.
+stringsDescending: list.Sort(["aaaaa", "AA", "b", "BBB", "zzzz", "Z"], list.Descending)
+
+// When sorting lists containing other types (or a mixture of types), list.Sort
+// must be provided with a custom comparator. The comparator defines how to
+// compare the list's elements.
+structsCustom: list.Sort([{a: 2}, {a: 3}, {a: 1}], {x: {}, y: {}, less: x.a < y.a})
+
+// The comparator must adhere to the list.Comparer schema (see output, below).
+comparatorSchema: list.Comparer
+
+// The comparator can encode any legal CUE comparison between its "x" and
+// "y" fields' values. These values might contain any pairing of 2 of the
+// list's elements during the sort operation.
+// The "less" field must be an expression that is able to compare any 2
+// elements from the lists that the comparator will handle. It must evaluate to
+// a boolean value that reports if "x" is less than "y".
+_stringsCompareLengths: {
+	x:    string
+	y:    string
+	less: len(x) < len(y)
+}
+
+// The comparator does not need to be provided inline - it may be a reference.
+stringsLengthAscending: list.Sort(stringsDescending, _stringsCompareLengths)
+
+// list.IsSorted requires a comparator, and reports if the list is sorted
+// according to that comparator's definition. The comparator may be a reference.
+isSortedAscending:       list.IsSorted(stringsLengthAscending, list.Ascending)
+isSortedDescending:      list.IsSorted(stringsLengthAscending, list.Descending)
+isSortedLengthAscending: list.IsSorted(stringsLengthAscending, _stringsCompareLengths)
+-- out --
+numbersAscending: [1, 2, 3, 4, 5]
+stringsDescending: ["zzzz", "b", "aaaaa", "Z", "BBB", "AA"]
+structsCustom: [{
+    a: 1
+}, {
+    a: 2
+}, {
+    a: 3
+}]
+comparatorSchema: {
+    T:    _
+    x:    _
+    y:    _
+    less: bool
+}
+stringsLengthAscending: ["b", "Z", "AA", "BBB", "zzzz", "aaaaa"]
+isSortedAscending:       false
+isSortedDescending:      false
+isSortedLengthAscending: true
+{{{end}}}
+
+## Related content
+
+- Use [`list.SortStrings`]({{< relref
+    "../use-the-built-in-functions-list-sortstrings-list-issortedstrings"
+  >}}) to sort lists of strings 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-functions-list-sort-list-issorted/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-functions-list-sort-list-issorted": {
+					page: {
+						cache: {
+							code: {
+								cc1: "MW7MKsnCU+dlke06kBs+h9gZy3aeCkenpm48ir/Qu6U="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-functions-list-sort-list-issorted/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-functions-list-sort-list-issorted": {}

content/docs/howto/use-the-built-in-functions-list-sortstrings-list-issortedstrings/en.md

@@ -60,4 +60,8 @@ unsorted: invalid value ["c","b","a"] (does not satisfy list.IsSortedStrings):
 
 ## Related content
 
+- `list.SortStrings` can only sort lists of strings *alphabetically*.
+  In any other situation, use [`list.Sort`]({{< relref
+    "../use-the-built-in-functions-list-sort-list-issorted"
+  >}})
 - The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

hugo/content/en/docs/howto/use-the-built-in-functions-list-sort-list-issorted/index.md

@@ -0,0 +1,91 @@
+---
+title: Using the built-in functions "list.Sort" and "list.IsSorted" to sort and test lists
+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.Sort` to sort lists, and
+`list.IsSorted` to test that lists are sorted, by using a predefined or custom
+comparator.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "list"
+
+// When sorting lists that are composed of only numbers or only strings,
+// list.Sort may be provided with one of the predefined comparators
+// "list.Ascending" or "list.Descending".
+numbersAscending: list.Sort([3, 5, 1, 4, 2], list.Ascending)
+
+// Sorting strings alphabetically may also be performed with list.SortStrings
+// (see "Related content", below).
+// Sorting strings in any other way (including reverse alphabetical order)
+// requires list.Sort.
+stringsDescending: list.Sort(["aaaaa", "AA", "b", "BBB", "zzzz", "Z"], list.Descending)
+
+// When sorting lists containing other types (or a mixture of types), list.Sort
+// must be provided with a custom comparator. The comparator defines how to
+// compare the list's elements.
+structsCustom: list.Sort([{a: 2}, {a: 3}, {a: 1}], {x: {}, y: {}, less: x.a < y.a})
+
+// The comparator must adhere to the list.Comparer schema (see output, below).
+comparatorSchema: list.Comparer
+
+// The comparator can encode any legal CUE comparison between its "x" and
+// "y" fields' values. These values might contain any pairing of 2 of the
+// list's elements during the sort operation.
+// The "less" field must be an expression that is able to compare any 2
+// elements from the lists that the comparator will handle. It must evaluate to
+// a boolean value that reports if "x" is less than "y".
+_stringsCompareLengths: {
+	x:    string
+	y:    string
+	less: len(x) < len(y)
+}
+
+// The comparator does not need to be provided inline - it may be a reference.
+stringsLengthAscending: list.Sort(stringsDescending, _stringsCompareLengths)
+
+// list.IsSorted requires a comparator, and reports if the list is sorted
+// according to that comparator's definition. The comparator may be a reference.
+isSortedAscending:       list.IsSorted(stringsLengthAscending, list.Ascending)
+isSortedDescending:      list.IsSorted(stringsLengthAscending, list.Descending)
+isSortedLengthAscending: list.IsSorted(stringsLengthAscending, _stringsCompareLengths)
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue eval
+numbersAscending: [1, 2, 3, 4, 5]
+stringsDescending: ["zzzz", "b", "aaaaa", "Z", "BBB", "AA"]
+structsCustom: [{
+    a: 1
+}, {
+    a: 2
+}, {
+    a: 3
+}]
+comparatorSchema: {
+    T:    _
+    x:    _
+    y:    _
+    less: bool
+}
+stringsLengthAscending: ["b", "Z", "AA", "BBB", "zzzz", "aaaaa"]
+isSortedAscending:       false
+isSortedDescending:      false
+isSortedLengthAscending: true
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- Use [`list.SortStrings`]({{< relref
+    "../use-the-built-in-functions-list-sortstrings-list-issortedstrings"
+  >}}) to sort lists of strings alphabetically without needing to define a
+  comparator
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

hugo/content/en/docs/howto/use-the-built-in-functions-list-sortstrings-list-issortedstrings/index.md

@@ -58,4 +58,8 @@ unsorted: invalid value ["c","b","a"] (does not satisfy list.IsSortedStrings):
 
 ## Related content
 
+- `list.SortStrings` can only sort lists of strings *alphabetically*.
+  In any other situation, use [`list.Sort`]({{< relref
+    "../use-the-built-in-functions-list-sort-list-issorted"
+  >}})
 - The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package