Skip to content

Commit 3f208c7

Browse files
committed
doc: add missing properties in Buffer docs
PR-URL: #7784 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trevor Norris <[email protected]>
1 parent 87a097d commit 3f208c7

File tree

1 file changed

+35
-24
lines changed

1 file changed

+35
-24
lines changed

doc/api/buffer.md

+35-24
Original file line numberDiff line numberDiff line change
@@ -391,11 +391,9 @@ deprecated: v6.0.0
391391

392392
* `size` {Number}
393393

394-
Allocates a new `Buffer` of `size` bytes. The `size` must be less than
395-
or equal to the value of `require('buffer').kMaxLength` (on 64-bit
396-
architectures, `kMaxLength` is `(2^31)-1`). Otherwise, a [`RangeError`][] is
397-
thrown. A zero-length Buffer will be created if a `size` less than or equal to
398-
0 is specified.
394+
Allocates a new `Buffer` of `size` bytes. The `size` must be less than or equal
395+
to the value of [`buffer.kMaxLength`]. Otherwise, a [`RangeError`] is thrown.
396+
A zero-length `Buffer` will be created if `size <= 0`.
399397

400398
Unlike [`ArrayBuffers`][`ArrayBuffer`], the underlying memory for `Buffer` instances
401399
created in this way is *not initialized*. The contents of a newly created `Buffer`
@@ -469,10 +467,9 @@ const buf = Buffer.alloc(5);
469467
console.log(buf);
470468
```
471469

472-
The `size` must be less than or equal to the value of
473-
`require('buffer').kMaxLength` (on 64-bit architectures, `kMaxLength` is
474-
`(2^31)-1`). Otherwise, a [`RangeError`][] is thrown. A zero-length Buffer will
475-
be created if a `size` less than or equal to 0 is specified.
470+
The `size` must be less than or equal to the value of [`buffer.kMaxLength`].
471+
Otherwise, a [`RangeError`] is thrown. A zero-length `Buffer` will be created if
472+
`size <= 0`.
476473

477474
If `fill` is specified, the allocated `Buffer` will be initialized by calling
478475
[`buf.fill(fill)`][`buf.fill()`].
@@ -512,10 +509,8 @@ added: v5.10.0
512509
* `size` {Number}
513510

514511
Allocates a new *non-zero-filled* `Buffer` of `size` bytes. The `size` must
515-
be less than or equal to the value of `require('buffer').kMaxLength` (on 64-bit
516-
architectures, `kMaxLength` is `(2^31)-1`). Otherwise, a [`RangeError`][] is
517-
thrown. A zero-length Buffer will be created if a `size` less than or equal to
518-
0 is specified.
512+
be less than or equal to the value of [`buffer.kMaxLength`]. Otherwise, a
513+
[`RangeError`] is thrown. A zero-length `Buffer` will be created if `size <= 0`.
519514

520515
The underlying memory for `Buffer` instances created in this way is *not
521516
initialized*. The contents of the newly created `Buffer` are unknown and
@@ -542,14 +537,13 @@ Note that the `Buffer` module pre-allocates an internal `Buffer` instance of
542537
size [`Buffer.poolSize`] that is used as a pool for the fast allocation of new
543538
`Buffer` instances created using [`Buffer.allocUnsafe()`] (and the deprecated
544539
`new Buffer(size)` constructor) only when `size` is less than or equal to
545-
`Buffer.poolSize >> 1` (floor of `Buffer.poolSize` divided by two). The default
546-
value of `Buffer.poolSize` is `8192` but can be modified.
540+
`Buffer.poolSize >> 1` (floor of [`Buffer.poolSize`] divided by two).
547541

548542
Use of this pre-allocated internal memory pool is a key difference between
549543
calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`.
550544
Specifically, `Buffer.alloc(size, fill)` will *never* use the internal `Buffer`
551545
pool, while `Buffer.allocUnsafe(size).fill(fill)` *will* use the internal
552-
Buffer pool if `size` is less than or equal to half `Buffer.poolSize`. The
546+
`Buffer` pool if `size` is less than or equal to half [`Buffer.poolSize`]. The
553547
difference is subtle but can be important when an application requires the
554548
additional performance that [`Buffer.allocUnsafe()`] provides.
555549

@@ -561,10 +555,9 @@ added: v5.10.0
561555
* `size` {Number}
562556

563557
Allocates a new *non-zero-filled* and non-pooled `Buffer` of `size` bytes. The
564-
`size` must be less than or equal to the value of
565-
`require('buffer').kMaxLength` (on 64-bit architectures, `kMaxLength` is
566-
`(2^31)-1`). Otherwise, a [`RangeError`][] is thrown. A zero-length Buffer will
567-
be created if a `size` less than or equal to 0 is specified.
558+
`size` must be less than or equal to the value of [`buffer.kMaxLength`].
559+
Otherwise, a [`RangeError`] is thrown. A zero-length `Buffer` will be created if
560+
`size <= 0`.
568561

569562
The underlying memory for `Buffer` instances created in this way is *not
570563
initialized*. The contents of the newly created `Buffer` are unknown and
@@ -842,6 +835,16 @@ added: v0.9.1
842835
Returns `true` if `encoding` contains a supported character encoding, or `false`
843836
otherwise.
844837

838+
### Class Property: Buffer.poolSize
839+
<!-- YAML
840+
added: v0.11.3
841+
-->
842+
843+
* {Number} **Default:** `8192`
844+
845+
This is the number of bytes used to determine the size of pre-allocated, internal
846+
`Buffer` instances used for pooling. This value may be modified.
847+
845848
### buf[index]
846849
<!-- YAML
847850
type: property
@@ -2197,6 +2200,16 @@ Returns the maximum number of bytes that will be returned when
21972200
Note that this is a property on the `buffer` module as returned by
21982201
`require('buffer')`, not on the `Buffer` global or a `Buffer` instance.
21992202

2203+
## buffer.kMaxLength
2204+
<!-- YAML
2205+
added: v3.0.0
2206+
-->
2207+
2208+
* {Number} The largest size allowed for a single `Buffer` instance
2209+
2210+
On 32-bit architectures, this value is `(2^30)-1` (~1GB).
2211+
On 64-bit architectures, this value is `(2^31)-1` (~2GB).
2212+
22002213
## Class: SlowBuffer
22012214
<!-- YAML
22022215
deprecated: v6.0.0
@@ -2247,10 +2260,8 @@ deprecated: v6.0.0
22472260
* `size` Number
22482261

22492262
Allocates a new `SlowBuffer` of `size` bytes. The `size` must be less than
2250-
or equal to the value of `require('buffer').kMaxLength` (on 64-bit
2251-
architectures, `kMaxLength` is `(2^31)-1`). Otherwise, a [`RangeError`][] is
2252-
thrown. A zero-length Buffer will be created if a `size` less than or equal to
2253-
0 is specified.
2263+
or equal to the value of [`buffer.kMaxLength`]. Otherwise, a [`RangeError`] is
2264+
thrown. A zero-length `Buffer` will be created if `size <= 0`.
22542265

22552266
The underlying memory for `SlowBuffer` instances is *not initialized*. The
22562267
contents of a newly created `SlowBuffer` are unknown and could contain

0 commit comments

Comments
 (0)