feat: more array functions (#657)

doc-surrealdb_versioned_docs/version-latest/surrealql/functions/database/array.mdx

@@ -194,14 +194,14 @@ These functions can be used when working with, and manipulating arrays of data.
       <td scope="row" data-label="Function"><a href="#arrayshuffle"><code>array::shuffle()</code></a></td>
       <td scope="row" data-label="Description">Randomly shuffles the contents of an array</td>
     </tr>
-    <tr>
-      <td scope="row" data-label="Function"><a href="#arraysort"><code>array::sort()</code></a></td>
-      <td scope="row" data-label="Description">Sorts the values in an array in ascending or descending order</td>
-    </tr>
     <tr>
       <td scope="row" data-label="Function"><a href="#arrayslice"><code>array::slice()</code></a></td>
       <td scope="row" data-label="Description">Returns a slice of an array</td>
     </tr>
+    <tr>
+      <td scope="row" data-label="Function"><a href="#arraysort"><code>array::sort()</code></a></td>
+      <td scope="row" data-label="Description">Sorts the values in an array in ascending or descending order</td>
+    </tr>
     <tr>
       <td scope="row" data-label="Function"><a href="#arraysortasc"><code>array::sort::asc()</code></a></td>
       <td scope="row" data-label="Description">Sorts the values in an array in ascending order</td>
@@ -694,23 +694,6 @@ The `array::filter_index` function can also take a [closure](/docs/surrealdb/sur
 
 <br />
 
-## `array::first`
-
-The `array::first` function returns the first value from an array.
-
-```surql title="API DEFINITION"
-array::first(array) -> any
-```
-The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
-
-```surql
-RETURN array::first([ 's', 'u', 'r', 'r', 'e', 'a', 'l' ]);
-
-"s"
-```
-
-<br />
-
 ## `array::find`
 
 ```surql title="API DEFINITION"
@@ -758,6 +741,8 @@ NONE
 }
 ```
 
+<br />
+
 ## `array::find_index`
 
 ```surql title="API DEFINITION"
@@ -791,6 +776,23 @@ The `array::find_index` function also be called using the alias `array::index_of
 
 <br />
 
+## `array::first`
+
+The `array::first` function returns the first value from an array.
+
+```surql title="API DEFINITION"
+array::first(array) -> any
+```
+The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
+
+```surql
+RETURN array::first([ 's', 'u', 'r', 'r', 'e', 'a', 'l' ]);
+
+"s"
+```
+
+<br />
+
 ## `array::flatten`
 
 The `array::flatten` flattens an array of arrays, returning a new array with all sub-array elements concatenated into it.
@@ -1224,7 +1226,7 @@ RETURN array::push([1,2,3,4], 5);
 The `array::range` function creates an array of numbers from a given range.
 
 ```surql title="API DEFINITION"
-array::range(start, end) -> array
+array::range(start, count) -> array
 ```
 The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
 
@@ -1330,95 +1332,95 @@ RETURN array::shuffle([ 1, 2, 3, 4, 5 ]);
 
 <br />
 
-## `array::sort`
+## `array::slice`
 
-The `array::sort` function sorts the values in an array in ascending or descending order.
+The `array::slice` returns a slice of an array, based on a starting position, and a length or negative position.
 
 
 ```surql title="API DEFINITION"
-array::sort(array) -> array
+array::slice(array, start, len) -> array
 ```
+The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
 
-The function also accepts a second boolean parameter which determines the sorting direction. The second parameter can be `true` for ascending order, or `false` for descending order.
-
-```surql title="API DEFINITION"
-array::sort(array, bool) -> array
-```
-The function also accepts a second string parameter which determines the sorting direction. The second parameter can be `'asc'` for ascending order, or `'desc'` for descending order.
+```surql
+RETURN array::slice([ 1, 2, 3, 4, 5 ], 1, 2);
 
-```surql title="API DEFINITION"
-array::sort(array, string) -> array
+[2,3]
 ```
 
-The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
+The following example shows how you can use this function with a starting position, and a negative position, which will slice off the first and last element from the array:
 
-```surql
-RETURN array::sort([ 1, 2, 1, null, "something", 3, 3, 4, 0 ]);
+```surql 
+RETURN array::slice([ 1, 2, 3, 4, 5 ], 1, -1);
 
-[ null, 0, 1, 1, 2, 3, 3, 4, "something" ]
+[ 2, 3, 4 ]
 ```
+The following example shows how you can use this function with just a starting position, which will only slice from the beginning of the array:
+
 ```surql
-RETURN array::sort([1,2,1,null,"something",3,3,4,0], false);
+RETURN array::slice([ 1, 2, 3, 4, 5 ], 2);
 
-[ "something", 4, 3, 3, 2, 1, 1, 9, null ]
+[ 3, 4, 5 ]
 ```
+
+The following example shows how you can use this function with just a negative position, which will only slice from the end of the array:
+
 ```surql
-RETURN array::sort([1,2,1,null,"something",3,3,4,0], "asc");
+RETURN array::slice([ 1, 2, 3, 4, 5 ], -2);
 
-[ null, 0, 1, 1, 2, 3, 3, 4, "something" ]
+[ 4, 5 ]
 ```
+The following example shows how you can use this function with a negative position, and a length of the slice:
+
 ```surql
-RETURN array::sort([1,2,1,null,"something",3,3,4,0], "desc");
+RETURN array::slice([ 1, 2, 3, 4, 5 ], -3, 2);
 
-[ "something", 4, 3, 3, 2, 1, 1, 9, null ]
+[ 3, 4 ]
 ```
 
 <br />
 
-## `array::slice`
+## `array::sort`
 
-The `array::slice` returns a slice of an array, based on a starting position, and a length or negative position.
+The `array::sort` function sorts the values in an array in ascending or descending order.
 
 
 ```surql title="API DEFINITION"
-array::slice(array, start, len) -> array
+array::sort(array) -> array
 ```
-The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
 
-```surql
-RETURN array::slice([ 1, 2, 3, 4, 5 ], 1, 2);
+The function also accepts a second boolean parameter which determines the sorting direction. The second parameter can be `true` for ascending order, or `false` for descending order.
 
-[2,3]
+```surql title="API DEFINITION"
+array::sort(array, bool) -> array
 ```
+The function also accepts a second string parameter which determines the sorting direction. The second parameter can be `'asc'` for ascending order, or `'desc'` for descending order.
 
-The following example shows how you can use this function with a starting position, and a negative position, which will slice off the first and last element from the array:
-
-```js
-RETURN array::slice([ 1, 2, 3, 4, 5 ], 1, -1);
-
-[ 2, 3, 4 ]
+```surql title="API DEFINITION"
+array::sort(array, string) -> array
 ```
-The following example shows how you can use this function with just a starting position, which will only slice from the beginning of the array:
 
-```js
-RETURN array::slice([ 1, 2, 3, 4, 5 ], 2);
-
-[ 3, 4, 5 ]
-```
+The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
 
-The following example shows how you can use this function with just a negative position, which will only slice from the end of the array:
+```surql
+RETURN array::sort([ 1, 2, 1, null, "something", 3, 3, 4, 0 ]);
 
-```js
-RETURN array::slice([ 1, 2, 3, 4, 5 ], -2);
+[ null, 0, 1, 1, 2, 3, 3, 4, "something" ]
+```
+```surql
+RETURN array::sort([1,2,1,null,"something",3,3,4,0], false);
 
-[ 4, 5 ]
+[ "something", 4, 3, 3, 2, 1, 1, 9, null ]
 ```
-The following example shows how you can use this function with a negative position, and a length of the slice:
+```surql
+RETURN array::sort([1,2,1,null,"something",3,3,4,0], "asc");
 
-```js
-RETURN array::slice([ 1, 2, 3, 4, 5 ], -3, 2);
+[ null, 0, 1, 1, 2, 3, 3, 4, "something" ]
+```
+```surql
+RETURN array::sort([1,2,1,null,"something",3,3,4,0], "desc");
 
-[ 3, 4 ]
+[ "something", 4, 3, 3, 2, 1, 1, 9, null ]
 ```
 
 <br />