Skip to content

Commit cfb3cdb

Browse files
broofabroofa
authored
docs: document byte order in parse() and stringify(). fixes #503 (#504)
1 parent ade3655 commit cfb3cdb

2 files changed

Lines changed: 71 additions & 21 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -83,37 +83,62 @@ Convert UUID string to array of bytes
8383
| _returns_ | `Uint8Array[16]` |
8484
| _throws_ | `TypeError` if `str` is not a valid UUID |
8585

86+
Note: Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left ↠ right order of hex-pairs in UUID strings. As shown in the example below.
87+
8688
Example:
8789

8890
```javascript
8991
import { parse as uuidParse } from 'uuid';
9092

91-
uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨
92-
// Uint8Array(16) [
93-
// 110, 192, 189, 127, 17,
94-
// 192, 67, 218, 151, 94,
95-
// 42, 138, 217, 235, 174,
96-
// 11
93+
// Parse a UUID
94+
const bytes = uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b');
95+
96+
// Convert to hex strings to show byte order (for documentation purposes)
97+
[...bytes].map((v) => v.toString(16).padStart(2, '0')); // ⇨
98+
// [
99+
// '6e', 'c0', 'bd', '7f',
100+
// '11', 'c0', '43', 'da',
101+
// '97', '5e', '2a', '8a',
102+
// 'd9', 'eb', 'ae', '0b'
97103
// ]
98104
```
99105

100106
### uuid.stringify(arr[, offset])
101107

102108
Convert array of bytes to UUID string
103109

104-
| | |
105-
| -------------- | --------------------------------------------------------------------------- |
106-
| `arr` | `Array`-like collection of 16 values (starting from `offset`) between 0-255 |
107-
| [`offset` = 0] | `Number` Starting index in the Array |
108-
| _returns_ | `String` |
109-
| _throws_ | `TypeError` if a valid UUID string cannot be generated |
110+
| | |
111+
| -------------- | ---------------------------------------------------------------------------- |
112+
| `arr` | `Array`-like collection of 16 values (starting from `offset`) between 0-255. |
113+
| [`offset` = 0] | `Number` Starting index in the Array |
114+
| _returns_ | `String` |
115+
| _throws_ | `TypeError` if a valid UUID string cannot be generated |
116+
117+
Note: Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left ↠ right order of hex-pairs in UUID strings. As shown in the example below.
110118

111119
Example:
112120

113121
```javascript
114122
import { stringify as uuidStringify } from 'uuid';
115123

116-
const uuidBytes = [110, 192, 189, 127, 17, 192, 67, 218, 151, 94, 42, 138, 217, 235, 174, 11];
124+
const uuidBytes = [
125+
0x6e,
126+
0xc0,
127+
0xbd,
128+
0x7f,
129+
0x11,
130+
0xc0,
131+
0x43,
132+
0xda,
133+
0x97,
134+
0x5e,
135+
0x2a,
136+
0x8a,
137+
0xd9,
138+
0xeb,
139+
0xae,
140+
0x0b,
141+
];
117142

118143
uuidStringify(uuidBytes); // ⇨ '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'
119144
```

‎README_js.md‎

Lines changed: 33 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -95,31 +95,56 @@ Convert UUID string to array of bytes
9595
| _returns_ | `Uint8Array[16]` |
9696
| _throws_ | `TypeError` if `str` is not a valid UUID |
9797

98+
Note: Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left ↠ right order of hex-pairs in UUID strings. As shown in the example below.
99+
98100
Example:
99101

100102
```javascript --run
101103
import { parse as uuidParse } from 'uuid';
102104

103-
uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // RESULT
105+
// Parse a UUID
106+
const bytes = uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b');
107+
108+
// Convert to hex strings to show byte order (for documentation purposes)
109+
[...bytes].map((v) => v.toString(16).padStart(2, '0')); // RESULT
104110
```
105111

106112
### uuid.stringify(arr[, offset])
107113

108114
Convert array of bytes to UUID string
109115

110-
| | |
111-
| -------------- | --------------------------------------------------------------------------- |
112-
| `arr` | `Array`-like collection of 16 values (starting from `offset`) between 0-255 |
113-
| [`offset` = 0] | `Number` Starting index in the Array |
114-
| _returns_ | `String` |
115-
| _throws_ | `TypeError` if a valid UUID string cannot be generated |
116+
| | |
117+
| -------------- | ---------------------------------------------------------------------------- |
118+
| `arr` | `Array`-like collection of 16 values (starting from `offset`) between 0-255. |
119+
| [`offset` = 0] | `Number` Starting index in the Array |
120+
| _returns_ | `String` |
121+
| _throws_ | `TypeError` if a valid UUID string cannot be generated |
122+
123+
Note: Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left ↠ right order of hex-pairs in UUID strings. As shown in the example below.
116124

117125
Example:
118126

119127
```javascript --run
120128
import { stringify as uuidStringify } from 'uuid';
121129

122-
const uuidBytes = [110, 192, 189, 127, 17, 192, 67, 218, 151, 94, 42, 138, 217, 235, 174, 11];
130+
const uuidBytes = [
131+
0x6e,
132+
0xc0,
133+
0xbd,
134+
0x7f,
135+
0x11,
136+
0xc0,
137+
0x43,
138+
0xda,
139+
0x97,
140+
0x5e,
141+
0x2a,
142+
0x8a,
143+
0xd9,
144+
0xeb,
145+
0xae,
146+
0x0b,
147+
];
123148

124149
uuidStringify(uuidBytes); // RESULT
125150
```

0 commit comments

Comments
 (0)