lib: implement slice() function

Implement a new function `slice()` to complement the existing `splice()`
function and model it's semantics after the ES6 `Array.slice()` version.

Fixes: #106
Signed-off-by: Jo-Philipp Wich <jo@mein.io>

1 files changed, 75 insertions, 44 deletions

diff --git a/README.md b/README.md
index fc80c9b..967a8a3 100644
--- a/README.md
+++ b/README.md
@@ -927,14 +927,45 @@ sort(["Bean", "Orange", "Apple"], function(a, b) {
 
 Removes the elements designated by `off` and `len` from  the given an array,
 and replaces them with the additional arguments passed, if any. Returns the
-last element removed, or `null` if no elements are removed. The array grows or shrinks as necessary.
+last element removed, or `null` if no elements are removed. The array grows
+or shrinks as necessary.
 
 If `off` is negative then it starts that far from the end of the array. If
 `len` is omitted, removes everything from `off` onward. If `len` is negative,
 removes the elements from `off` onward except for `-len` elements at the end of
 the array. If both `off` and `len` are omitted, removes everything.
 
-#### 6.33. `split(str, sep[, limit])`
+#### 6.33. `slice(arr[, off[, end]])`
+
+Performs a shallow copy of a portion of the source array, as specified by the
+start and end offsets. Returns a new array containing the copied elements.
+The original array is not modified.
+
+The `off` argument specifies the index of the first element to copy from the
+source array while he `end` argument specifies the index of the first element
+to exclude from the returned array, means the copied slice of the source array
+spans from `off` (inclusive) to `end - 1`.
+
+If either `off` or `end` is negative then it starts that far from the end of
+the array. If `off` is omitted it defaults to `0`, if end is omitted, it
+defaults to the length of the source array. Either value is capped to the length
+of the source array.
+
+Returns a new array containing the copied elements, if any.
+
+Returns `null` is the given source argument is not an array value.
+
+```javascript
+slice([1, 2, 3])          // [1, 2, 3]
+slice([1, 2, 3], 1)       // [2, 3]
+slice([1, 2, 3], -1)      // [3]
+slice([1, 2, 3], -3, -1)  // [1, 2]
+slice([1, 2, 3], 10)      // []
+slice([1, 2, 3], 2, 1)    // []
+slice("invalid", 1, 2)    // null
+```
+
+#### 6.34. `split(str, sep[, limit])`
 
 Split the given string using the separator passed as second argument and return
 an array containing the resulting pieces.
@@ -952,15 +983,15 @@ split("foo,bar,baz", /[ao]/)  // ["f", "", ",b", "r,b", "z"]
 split("foo=bar=baz", "=", 2)  // ["foo", "bar=baz"]
 ```
 
-#### 6.34. `sqrt(x)`
+#### 6.35. `sqrt(x)`
 
 Return the nonnegative square root of x.
 
-#### 6.35. `srand(n)`
+#### 6.36. `srand(n)`
 
 Seed the PRNG using the given number.
 
-#### 6.36. `substr(str, off, len)`
+#### 6.37. `substr(str, off, len)`
 
 Extracts a substring out of `str` and returns it. First character is at offset
 zero. If `off` is negative, starts that far back from the end of the string.
@@ -977,7 +1008,7 @@ substr(s, -4);        // tree
 substr(s, -4, 2);     // tr
 ```
 
-#### 6.37. `time()`
+#### 6.38. `time()`
 
 Returns the current UNIX epoch.
 
@@ -985,7 +1016,7 @@ Returns the current UNIX epoch.
 time();     // 1598043054
 ```
 
-#### 6.38. `trim()`
+#### 6.39. `trim()`
 
 Trim any of the specified characters in `c` from the start and end of `str`.
 If the second argument is omitted, trims the characters, ` ` (space), `\t`,
@@ -996,14 +1027,14 @@ ltrim("  foo  \n")     // "foo"
 ltrim("--bar--", "-")  // "bar"
 ```
 
-#### 6.39. `type(x)`
+#### 6.40. `type(x)`
 
 Returns the type of the given value as string which might be one of
 `"function"`, `"object"`, `"array"`, `"double"`, `"int"` or `"bool"`.
 
 Returns `null` when no value or `null` is passed.
 
-#### 6.40. `uchr(n1, ...)`
+#### 6.41. `uchr(n1, ...)`
 
 Converts each given numeric value to an utf8 escape sequence and returns the
 resulting string. Invalid numeric values or values outside the range `0` ..
@@ -1014,17 +1045,17 @@ uchr(0x2600, 0x26C6, 0x2601);  // "☀⛆☁"
 uchr(-1, 0x20ffff, "foo");     // "���"
 ```
 
-#### 6.41. `uc(str)`
+#### 6.42. `uc(str)`
 
 Converts the given string to uppercase and return the resulting string.
 Returns `null` if the given argument could not be converted to a string.
 
-#### 6.42. `unshift(arr, v1, ...)`
+#### 6.43. `unshift(arr, v1, ...)`
 
 Add the given values to the beginning of the array passed as first argument.
 Returns the last value added to the array.
 
-#### 6.43. `values(obj)`
+#### 6.44. `values(obj)`
 
 Returns an array containing all values of the given object. Returns `null` if
 no object was passed.
@@ -1033,7 +1064,7 @@ no object was passed.
 values({ foo: true, bar: false });   // [true, false]
 ```
 
-#### 6.44. `printf(fmt, ...)`
+#### 6.45. `printf(fmt, ...)`
 
 Formats the given arguments according to the given format string and outputs the
 result to stdout.
@@ -1077,14 +1108,14 @@ well.
 %}
 ```
 
-#### 6.45. `sprintf(fmt, ...)`
+#### 6.46. `sprintf(fmt, ...)`
 
 Formats the given arguments according to the given format string and returns the
 resulting string.
 
 See `printf()` for details.
 
-#### 6.46. `match(str, /pattern/)`
+#### 6.47. `match(str, /pattern/)`
 
 Match the given string against the regular expression pattern specified as
 second argument.
@@ -1100,7 +1131,7 @@ match("foobarbaz", /b.(.)/)   // ["bar", "r"]
 match("foobarbaz", /b.(.)/g)  // [["bar", "r"], ["baz", "z"]]
 ```
 
-#### 6.47. `replace(str, /pattern/, replace[, limit])`
+#### 6.48. `replace(str, /pattern/, replace[, limit])`
 
 Replace occurences of the specified pattern in the string passed as first
 argument. The pattern value may be either a regular expression or a plain
@@ -1138,7 +1169,7 @@ replace("aaaaa", "a", "x", 3)                               // xxxaa
 replace("foo bar baz", /[ao]/g, "x", 3)                     // fxx bxr baz
 ```
 
-#### 6.48. `json(str)`
+#### 6.49. `json(str)`
 
 Parse the given string as JSON and return the resulting value. Throws an
 exception on parse errors, trailing garbage or premature EOF.
@@ -1148,7 +1179,7 @@ json('{"a":true, "b":123}')   // { "a": true, "b": 123 }
 json('[1,2,')                 // Throws exception
 ```
 
-#### 6.49. `include(path[, scope])`
+#### 6.50. `include(path[, scope])`
 
 Evaluate and include the file at the given path and optionally override the
 execution scope with the given scope object.
@@ -1191,14 +1222,14 @@ include("./untrusted.uc", proto({
 }, {}))
 ```
 
-#### 6.50. `warn(x, ...)`
+#### 6.51. `warn(x, ...)`
 
 Print any of the given values to stderr. Arrays and objects are converted to
 their JSON representation.
 
 Returns the amount of bytes printed.
 
-#### 6.51. `system(command, timeout)`
+#### 6.52. `system(command, timeout)`
 
 Executes the given command, waits for completion and returns the resulting
 exit code.
@@ -1228,7 +1259,7 @@ system(["/usr/bin/date", "+%s"]);          // prints the UNIX timestamp to stdou
 system("sleep 3 && echo 'Success'", 1000); // returns -9
 ```
 
-#### 6.52. `trace(level)`
+#### 6.53. `trace(level)`
 
 Enables or disables VM opcode tracing. When invoked with a positive non-zero
 level, opcode tracing is enabled and debug information is printed to stderr
@@ -1241,7 +1272,7 @@ implementation might provide different different verbosity levels or treat
 the level argument as bit mask to enable or disable individual debug
 elements.
 
-#### 6.53. `proto(val[, proto])`
+#### 6.54. `proto(val[, proto])`
 
 Get or set the prototype of the array or object value `val`.
 
@@ -1254,17 +1285,17 @@ set as prototype on the array or object in `val`.
 
 Throws an exception if the given prototype value is not an object.
 
-#### 6.54. `sleep(milliseconds)`
+#### 6.55. `sleep(milliseconds)`
 
 Pause execution for the given amount of milliseconds. Returns `false` if
 an invalid value was passed, otherwise `true`.
 
-#### 6.55. `assert(cond[, message])`
+#### 6.56. `assert(cond[, message])`
 
 Raise an exception with the given `message` parameter if the value in `cond`
 is not truish. When `message` is omitted, the default value is `Assertion failed`.
 
-#### 6.56. `render(path_or_func[, scope_or_fnarg1 [, fnarg2 [, ...]]])`
+#### 6.57. `render(path_or_func[, scope_or_fnarg1 [, fnarg2 [, ...]]])`
 
 When invoked with a string value as first argument, the function acts like
 like `include()` but captures the output of the included file as string and
@@ -1277,7 +1308,7 @@ given function and passes all subsequent arguments to it. Any output
 called function is captured and returned as string. The return value of the
 called function is discarded.
 
-#### 6.57. `regexp(source[, flags])`
+#### 6.58. `regexp(source[, flags])`
 
 Construct a regular expression instance from the given `source` pattern string
 and any flags optionally specified by the `flags` argument.
@@ -1296,7 +1327,7 @@ regexp('foo.*bar', 'x');    // throws "Type error: Unrecognized flag character '
 regexp('foo.*(');           // throws "Syntax error: Unmatched ( or \("
 ```
 
-#### 6.58. `wildcard(subject, pattern[, nocase])`
+#### 6.59. `wildcard(subject, pattern[, nocase])`
 
 Match the given subject against the supplied wildcard (file glob) pattern.
 
@@ -1306,7 +1337,7 @@ a string before being matched.
 
 Returns `true` when the subject matches the pattern or `false` when not.
 
-#### 6.59. `sourcepath([depth [, dironly]])`
+#### 6.60. `sourcepath([depth [, dironly]])`
 
 Determine the path of the source file currently being executed by ucode.
 
@@ -1325,7 +1356,7 @@ file path.
 If `depth` exceeds the size of the call stack, the function returns `null`
 as well.
 
-#### 6.60. `min([val1 [, val2 [, ...]]])`
+#### 6.61. `min([val1 [, val2 [, ...]]])`
 
 Return the smallest value among all parameters passed to the function.
 The function does a `val1 < val2` comparison internally, which means that
@@ -1342,7 +1373,7 @@ min("def", "abc", "ghi");     // "abc"
 min(true, false);             // false
 ```
 
-#### 6.61. `max([val1 [, val2 [, ...]]])`
+#### 6.62. `max([val1 [, val2 [, ...]]])`
 
 Return the largest value among all parameters passed to the function.
 The function does a `val1 > val2` comparison internally, which means that
@@ -1359,7 +1390,7 @@ max("def", "abc", "ghi");     // "ghi"
 max(true, false);             // true
 ```
 
-#### 6.62. `b64dec(str)`
+#### 6.63. `b64dec(str)`
 
 Decodes the given base64 encoded string and returns the decoded result, any
 whitespace in the input string is ignored.
@@ -1375,7 +1406,7 @@ b64dec(123);                      // null
 b64dec("XXX");                    // null
 ```
 
-#### 6.63. `b64enc(str)`
+#### 6.64. `b64enc(str)`
 
 Encodes the given string into base64 and returns the resulting encoded
 string.
@@ -1387,7 +1418,7 @@ b64enc("This is a test");         // "VGhpcyBpcyBhIHRlc3Q="
 b64enc(123);                      // null
 ```
 
-#### 6.64. `uniq(array)`
+#### 6.65. `uniq(array)`
 
 Returns a new array containing all unique values of the given input
 array. The order is preserved, that is subsequent duplicate values
@@ -1400,7 +1431,7 @@ uniq([ 1, true, "foo", 2, true, "bar", "foo" ]); // [ 1, true, "foo", 2, "bar" ]
 uniq("test");                                    // null
 ```
 
-#### 6.65. `localtime([epoch])`
+#### 6.66. `localtime([epoch])`
 
 Return the given epoch timestamp (or now, if omitted) as a dictionary
 containing broken-down date and time information according to the local
@@ -1437,13 +1468,13 @@ localtime(1647953502);
 // }
 ```
 
-#### 6.66. `gmtime([epoch])`
+#### 6.67. `gmtime([epoch])`
 
 Like `localtime()` but interpreting the given epoch value as UTC time.
 
 See `localtime()` for details on the return value.
 
-#### 6.67. `timelocal(datetimespec)`
+#### 6.68. `timelocal(datetimespec)`
 
 Performs the inverse operation of `localtime()` by taking a broken-down
 date and time dictionary and transforming it into an epoch value according
@@ -1462,14 +1493,14 @@ timelocal({ "sec": 42, "min": 51, "hour": 13, "mday": 22, "mon": 3, "year": 2022
 // 1647953502
 ```
 
-#### 6.68. `timegm(datetimespec)`
+#### 6.69. `timegm(datetimespec)`
 
 Like `timelocal()` but interpreting the given date time specification as
 UTC time.
 
 See `timelocal()` for details.
 
-#### 6.69. `clock([monotonic])`
+#### 6.70. `clock([monotonic])`
 
 Reads the current second and microsecond value of the system clock.
 
@@ -1492,7 +1523,7 @@ clock();        // [ 1647954926, 798269464 ]
 clock(true);    // [ 474751, 527959975 ]
 ```
 
-#### 6.70. `hexdec(hexstring[, skipchars])`
+#### 6.71. `hexdec(hexstring[, skipchars])`
 
 The `hexdec()` function decodes the given hexadecimal digit string into
 a byte string, optionally skipping specified characters.
@@ -1510,7 +1541,7 @@ hexdec("48656c6c6f20776f726c64210a");  // "Hello world!\n"
 hexdec("44:55:66:77:33:44", ":");      // "DUfw3D"
 ```
 
-#### 6.71. `hexenc(val)`
+#### 6.72. `hexenc(val)`
 
 The `hexenc()` function encodes the given byte string into a hexadecimal
 digit string, converting the input value to a string if needed.
@@ -1521,7 +1552,7 @@ Returns the encoded hexadecimal digit string.
 hexenc("Hello world!\n");   // "48656c6c6f20776f726c64210a"
 ```
 
-#### 6.72. `gc([operation[, argument]])`
+#### 6.73. `gc([operation[, argument]])`
 
 The `gc()` function allows interaction with the mark and sweep garbage
 collector of the running ucode virtual machine.
@@ -1546,7 +1577,7 @@ If the `operation` argument is omitted, the default is `collect`.
 
 Returns `null` if a non-string `operation` value is given.
 
-#### 6.73. `loadstring(code[, options])`
+#### 6.74. `loadstring(code[, options])`
 
 Compiles the given code string into a ucode program and returns the resulting
 program entry function. The optinal `options` dictionary allows overriding
@@ -1587,7 +1618,7 @@ let fn2 = loadstring("return 1 + 2;", { raw_mode: true });
 fn2(); // 3
 ```
 
-#### 6.74. `loadfile(path[, options])`
+#### 6.75. `loadfile(path[, options])`
 
 Compiles the given file into a ucode program and returns the resulting program
 entry function.
@@ -1602,7 +1633,7 @@ Throws an exception on compilation or file i/o errors.
 loadfile("./templates/example.uc");  // function main() { ... }
 ```
 
-#### 6.75. `call(fn[, ctx[, scope[, arg1[, ...]]]])`
+#### 6.76. `call(fn[, ctx[, scope[, arg1[, ...]]]])`
 
 Calls the given function value with a modified environment. The given `ctx`
 argument is used as `this` context for the invoked function and the given