Skip to content

Commit 79131d7

Browse files
committed
doc: document unspecified behavior for buf.write* methods
Per #1161, when the buf.write*() methods are given anything other than what they expect, indicate that the behavior is unspecified. Fixes: #1161
1 parent a15906c commit 79131d7

File tree

1 file changed

+20
-9
lines changed

1 file changed

+20
-9
lines changed

doc/api/buffer.markdown

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1397,7 +1397,8 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
13971397

13981398
Writes `value` to the Buffer at the specified `offset` with specified endian
13991399
format (`writeDoubleBE()` writes big endian, `writeDoubleLE()` writes little
1400-
endian). The `value` argument must be a valid 64-bit double.
1400+
endian). The `value` argument *should* be a valid 64-bit double. Behavior is
1401+
unspecified if `value` is anything other than a 64-bit double.
14011402

14021403
Set `noAssert` to true to skip validation of `value` and `offset`. This means
14031404
that `value` may be too large for the specific function and `offset` may be
@@ -1459,8 +1460,9 @@ console.log(buf);
14591460
* `noAssert` {Boolean} Default: false
14601461
* Return: {Number} The offset plus the number of written bytes
14611462

1462-
Writes `value` to the Buffer at the specified `offset`. The `value` must be a
1463-
valid signed 8-bit integer.
1463+
Writes `value` to the Buffer at the specified `offset`. The `value` should be a
1464+
valid signed 8-bit integer. Behavior is unspecified if `value` is anything
1465+
other than a signed 8-bit integer.
14641466

14651467
Set `noAssert` to true to skip validation of `value` and `offset`. This means
14661468
that `value` may be too large for the specific function and `offset` may be
@@ -1487,7 +1489,8 @@ console.log(buf);
14871489

14881490
Writes `value` to the Buffer at the specified `offset` with specified endian
14891491
format (`writeInt16BE()` writes big endian, `writeInt16LE()` writes little
1490-
endian). The `value` must be a valid signed 16-bit integer.
1492+
endian). The `value` should be a valid signed 16-bit integer. Behavior is
1493+
unspecified if `value` is anything other than a signed 16-bit integer.
14911494

14921495
Set `noAssert` to true to skip validation of `value` and `offset`. This means
14931496
that `value` may be too large for the specific function and `offset` may be
@@ -1514,7 +1517,8 @@ console.log(buf);
15141517

15151518
Writes `value` to the Buffer at the specified `offset` with specified endian
15161519
format (`writeInt32BE()` writes big endian, `writeInt32LE()` writes little
1517-
endian). The `value` must be a valid signed 32-bit integer.
1520+
endian). The `value` should be a valid signed 32-bit integer. Behavior is
1521+
unspecified if `value` is anything other than a signed 32-bit integer.
15181522

15191523
Set `noAssert` to true to skip validation of `value` and `offset`. This means
15201524
that `value` may be too large for the specific function and `offset` may be
@@ -1560,15 +1564,18 @@ that `value` may be too large for the specific function and `offset` may be
15601564
beyond the end of the Buffer leading to the values being silently dropped. This
15611565
should not be used unless you are certain of correctness.
15621566

1567+
Behavior is unspecified if `value` is anything other than an integer.
1568+
15631569
### buf.writeUInt8(value, offset[, noAssert])
15641570

15651571
* `value` {Number} Bytes to be written to Buffer
15661572
* `offset` {Number} `0 <= offset <= buf.length - 1`
15671573
* `noAssert` {Boolean} Default: false
15681574
* Return: {Number} The offset plus the number of written bytes
15691575

1570-
Writes `value` to the Buffer at the specified `offset`. The `value` must be a
1571-
valid unsigned 8-bit integer.
1576+
Writes `value` to the Buffer at the specified `offset`. The `value` should be a
1577+
valid unsigned 8-bit integer. Behavior is unspecified if `value` is anything
1578+
other than an unsigned 8-bit integer.
15721579

15731580
Set `noAssert` to true to skip validation of `value` and `offset`. This means
15741581
that `value` may be too large for the specific function and `offset` may be
@@ -1598,7 +1605,8 @@ console.log(buf);
15981605

15991606
Writes `value` to the Buffer at the specified `offset` with specified endian
16001607
format (`writeUInt16BE()` writes big endian, `writeUInt16LE()` writes little
1601-
endian). The `value` must be a valid unsigned 16-bit integer.
1608+
endian). The `value` should be a valid unsigned 16-bit integer. Behavior is
1609+
unspecified if `value` is anything other than an unsigned 16-bit integer.
16021610

16031611
Set `noAssert` to true to skip validation of `value` and `offset`. This means
16041612
that `value` may be too large for the specific function and `offset` may be
@@ -1632,7 +1640,8 @@ console.log(buf);
16321640

16331641
Writes `value` to the Buffer at the specified `offset` with specified endian
16341642
format (`writeUInt32BE()` writes big endian, `writeUInt32LE()` writes little
1635-
endian). The `value` must be a valid unsigned 32-bit integer.
1643+
endian). The `value` should be a valid unsigned 32-bit integer. Behavior is
1644+
unspecified if `value` is anything other than an unsigned 32-bit integer.
16361645

16371646
Set `noAssert` to true to skip validation of `value` and `offset`. This means
16381647
that `value` may be too large for the specific function and `offset` may be
@@ -1678,6 +1687,8 @@ that `value` may be too large for the specific function and `offset` may be
16781687
beyond the end of the Buffer leading to the values being silently dropped. This
16791688
should not be used unless you are certain of correctness.
16801689

1690+
Behavior is unspecified if `value` is anything other than an unsigned integer.
1691+
16811692
## buffer.INSPECT_MAX_BYTES
16821693

16831694
* {Number} Default: 50

0 commit comments

Comments
 (0)