From 4b13f3576ba2f2ace629e0a8d853a2b552d06861 Mon Sep 17 00:00:00 2001 From: David Bottiau Date: Mon, 2 Sep 2024 02:15:18 +0200 Subject: [PATCH] feat: more array functions (#657) --- .../surrealql/functions/database/array.mdx | 142 +++++++++--------- 1 file changed, 72 insertions(+), 70 deletions(-) diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/functions/database/array.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/functions/database/array.mdx index 991c07a7c..be99f402c 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/functions/database/array.mdx +++ b/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. array::shuffle() Randomly shuffles the contents of an array - - array::sort() - Sorts the values in an array in ascending or descending order - array::slice() Returns a slice of an array + + array::sort() + Sorts the values in an array in ascending or descending order + array::sort::asc() Sorts the values in an array in ascending order @@ -694,23 +694,6 @@ The `array::filter_index` function can also take a [closure](/docs/surrealdb/sur
-## `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" -``` - -
- ## `array::find` ```surql title="API DEFINITION" @@ -758,6 +741,8 @@ NONE } ``` +
+ ## `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
+## `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" +``` + +
+ ## `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 ]);
-## `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 ] ```
-## `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 ] ```