docs: document byte order in parse() and stringify(). fixes #503

uuidjs · Aug 3, 2020 · f4a58fe · f4a58fe
1 parent ade3655
commit f4a58fe
Show file tree

Hide file tree

Showing 2 changed files with 75 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -77,23 +77,31 @@ NIL_UUID; // ⇨ '00000000-0000-0000-0000-000000000000'
 
 Convert UUID string to array of bytes
 
-|           |                                          |
-| --------- | ---------------------------------------- |
-| `str`     | A valid UUID `String`                    |
-| _returns_ | `Uint8Array[16]`                         |
-| _throws_  | `TypeError` if `str` is not a valid UUID |
+|           |                                                                                    |
+| --------- | ---------------------------------------------------------------------------------- |
+| `str`     | A valid UUID `String`                                                              |
+| _returns_ | `Uint8Array[16]` |
+| _throws_  | `TypeError` if `str` is not a valid UUID                                           |
+
+Note: Ordering of values in the byte arrays used by `parse()` and `stringify()`
+follows the left &Rarr; right order of hex-pairs in UUID strings.  As shown in
+the example below.
 
 Example:
 
 ```javascript
 import { parse as uuidParse } from 'uuid';
 
-uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨ 
-  // Uint8Array(16) [
-  //   110, 192, 189, 127,  17,
-  //   192,  67, 218, 151,  94,
-  //    42, 138, 217, 235, 174,
-  //    11
+// Parse a UUID
+const bytes = uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b');
+
+// Convert to hex strings to show byte order (for documentation purposes)
+[...bytes].map((v) => v.toString(16).padStart(2, '0')); // ⇨ 
+  // [
+  //   '6e', 'c0', 'bd', '7f',
+  //   '11', 'c0', '43', 'da',
+  //   '97', '5e', '2a', '8a',
+  //   'd9', 'eb', 'ae', '0b'
   // ]
 ```
 
@@ -103,17 +111,38 @@ Convert array of bytes to UUID string
 
 |                |                                                                             |
 | -------------- | --------------------------------------------------------------------------- |
-| `arr`          | `Array`-like collection of 16 values (starting from `offset`) between 0-255 |
+| `arr`          | `Array`-like collection of 16 values (starting from `offset`) between 0-255.|
 | [`offset` = 0] | `Number` Starting index in the Array                                        |
 | _returns_      | `String`                                                                    |
 | _throws_       | `TypeError` if a valid UUID string cannot be generated                      |
 
+Note: Ordering of values in the byte arrays used by `parse()` and `stringify()`
+follows the left &Rarr; right order of hex-pairs in UUID strings.  As shown in
+the example below.
+
 Example:
 
 ```javascript
 import { stringify as uuidStringify } from 'uuid';
 
-const uuidBytes = [110, 192, 189, 127, 17, 192, 67, 218, 151, 94, 42, 138, 217, 235, 174, 11];
+const uuidBytes = [
+  0x6e,
+  0xc0,
+  0xbd,
+  0x7f,
+  0x11,
+  0xc0,
+  0x43,
+  0xda,
+  0x97,
+  0x5e,
+  0x2a,
+  0x8a,
+  0xd9,
+  0xeb,
+  0xae,
+  0x0b,
+];
 
 uuidStringify(uuidBytes); // ⇨ '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'
 ```

diff --git a/README_js.md b/README_js.md
@@ -95,31 +95,56 @@ Convert UUID string to array of bytes
 | _returns_ | `Uint8Array[16]`                         |
 | _throws_  | `TypeError` if `str` is not a valid UUID |
 
+Note: Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left &Rarr; right order of hex-pairs in UUID strings. As shown in the example below.
+
 Example:
 
 ```javascript --run
 import { parse as uuidParse } from 'uuid';
 
-uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // RESULT
+// Parse a UUID
+const bytes = uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b');
+
+// Convert to hex strings to show byte order (for documentation purposes)
+[...bytes].map((v) => v.toString(16).padStart(2, '0')); // RESULT
 ```
 
 ### uuid.stringify(arr[, offset])
 
 Convert array of bytes to UUID string
 
-|                |                                                                             |
-| -------------- | --------------------------------------------------------------------------- |
-| `arr`          | `Array`-like collection of 16 values (starting from `offset`) between 0-255 |
-| [`offset` = 0] | `Number` Starting index in the Array                                        |
-| _returns_      | `String`                                                                    |
-| _throws_       | `TypeError` if a valid UUID string cannot be generated                      |
+|                |                                                                              |
+| -------------- | ---------------------------------------------------------------------------- |
+| `arr`          | `Array`-like collection of 16 values (starting from `offset`) between 0-255. |
+| [`offset` = 0] | `Number` Starting index in the Array                                         |
+| _returns_      | `String`                                                                     |
+| _throws_       | `TypeError` if a valid UUID string cannot be generated                       |
+
+Note: Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left &Rarr; right order of hex-pairs in UUID strings. As shown in the example below.
 
 Example:
 
 ```javascript --run
 import { stringify as uuidStringify } from 'uuid';
 
-const uuidBytes = [110, 192, 189, 127, 17, 192, 67, 218, 151, 94, 42, 138, 217, 235, 174, 11];
+const uuidBytes = [
+  0x6e,
+  0xc0,
+  0xbd,
+  0x7f,
+  0x11,
+  0xc0,
+  0x43,
+  0xda,
+  0x97,
+  0x5e,
+  0x2a,
+  0x8a,
+  0xd9,
+  0xeb,
+  0xae,
+  0x0b,
+];
 
 uuidStringify(uuidBytes); // RESULT
 ```