From 86f0662f891ac83f474a412b4271af996f1ea44e Mon Sep 17 00:00:00 2001
From: Jo-Philipp Wich <jo@mein.io>
Date: Fri, 11 Feb 2022 18:13:02 +0100
Subject: lib: change `ord()` to always return single byte value

The most common usecase is extracting the value of a single byte at a
specific offset, e.g. to scan a string char-by-char to construct a hash.

Furthermore, constructing an array which contains the results of multiple
`ord()` invocations is trivial while efficiently extracting a single byte
value without the overhead of an intermediate array is not.

Due to that, change `ord()` to always return a single integer byte value
at the offset specified as second argument or at offset 0 in case no
argument was supplied.

That means that `ord("Abc", 0, 1, 2)` will now return `65` instead of the
former `[ 65, 98, 99 ]` result.

Code relying on the former behaviour should either perform multiple calls
to `ord()`, passing different offsets each time or switch to the `struct`
module which allows efficient unpacking of string data.

Signed-off-by: Jo-Philipp Wich <jo@mein.io>
---
 README.md | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index a078ce4..33e9bd1 100644
--- a/README.md
+++ b/README.md
@@ -719,23 +719,24 @@ a = map(["foo", 1, true, null, 2.2], type);
 // a = ["string", "int", "bool", null, "double"]
 ```
 
-#### 6.21. `ord(s, ...)`
+#### 6.21. `ord(s [, offset])`
 
 Without further arguments, this function returns the byte value of the first
 character in the given string.
 
-If one or more index arguments are supplied, an array containing the byte
-values at each given index is returned. If an invalid index is supplied, the
-corresponding array entry will be `null`. Negative index entries are counted
-towards the end of the string, e.g. `-2` will return the value of the second
-last character.
+If an offset argument is supplied, the byte value of the character at this
+position is returned. If an invalid index is supplied, the function will
+return `null`. Negative index entries are counted towards the end of the
+string, e.g. `-2` will return the value of the second last character.
 
 ```javascript
-ord("Abc");                 // 65
-ord("Abc", 0);              // [ 65 ]
-ord("Abc", 1, -1);          // [ 98, 99 ]
-ord("Abc", 2, 1, 0);        // [ 99, 98, 65 ]
-ord("Abc", 10, -10, "nan"); // [ null, null, null ]
+ord("Abc");         // 65
+ord("Abc", 0);      // 65
+ord("Abc", 1);      // 98
+ord("Abc", 2);      // 99
+ord("Abc", 10);     // null
+ord("Abc", -10);    // null
+ord("Abc", "nan");  // null
 ```
 
 #### 6.22. `pop(arr)`
-- 
cgit v1.2.3