Skip to content

Commit e47ae58

Browse files
committed
doc: copyedit buffer doc
PR-URL: #4187 Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
1 parent 70fb06a commit e47ae58

File tree

1 file changed

+38
-38
lines changed

1 file changed

+38
-38
lines changed

doc/api/buffer.markdown

+38-38
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Stability: 2 - Stable
44

5-
Pure JavaScript is Unicode friendly but not nice to binary data. When
5+
Pure JavaScript is Unicode-friendly but not nice to binary data. When
66
dealing with TCP streams or the file system, it's necessary to handle octet
77
streams. Node.js has several strategies for manipulating, creating, and
88
consuming octet streams.
@@ -15,23 +15,23 @@ The `Buffer` class is a global, making it very rare that one would need
1515
to ever `require('buffer')`.
1616

1717
Converting between Buffers and JavaScript string objects requires an explicit
18-
encoding method. Here are the different string encodings.
18+
encoding method. The different string encodings are:
1919

20-
* `'ascii'` - for 7 bit ASCII data only. This encoding method is very fast, and
20+
* `'ascii'` - for 7-bit ASCII data only. This encoding method is very fast and
2121
will strip the high bit if set.
2222

2323
* `'utf8'` - Multibyte encoded Unicode characters. Many web pages and other
2424
document formats use UTF-8.
2525

26-
* `'utf16le'` - 2 or 4 bytes, little endian encoded Unicode characters.
26+
* `'utf16le'` - 2 or 4 bytes, little-endian encoded Unicode characters.
2727
Surrogate pairs (U+10000 to U+10FFFF) are supported.
2828

2929
* `'ucs2'` - Alias of `'utf16le'`.
3030

3131
* `'base64'` - Base64 string encoding.
3232

33-
* `'binary'` - A way of encoding the buffer into a one-byte (i.e. `latin-1`)
34-
encoded string. The string `'latin-1'` is not supported. Instead simply pass
33+
* `'binary'` - A way of encoding the buffer into a one-byte (`latin-1`)
34+
encoded string. The string `'latin-1'` is not supported. Instead, pass
3535
`'binary'` to use `'latin-1'` encoding.
3636

3737
* `'hex'` - Encode each byte as two hexadecimal characters.
@@ -45,8 +45,8 @@ Creating a typed array from a `Buffer` works with the following caveats:
4545
with elements `[1,2,3,4]`, not a `Uint32Array` with a single element
4646
`[0x1020304]` or `[0x4030201]`.
4747

48-
NOTE: Node.js v0.8 simply retained a reference to the buffer in `array.buffer`
49-
instead of cloning it.
48+
NOTE: Node.js v0.8 retained a reference to the buffer in `array.buffer` instead
49+
of cloning it.
5050

5151
While more efficient, it introduces subtle incompatibilities with the typed
5252
arrays specification. `ArrayBuffer#slice()` makes a copy of the slice while
@@ -74,9 +74,9 @@ Copies the passed `buffer` data onto a new `Buffer` instance.
7474
* `size` Number
7575

7676
Allocates a new buffer of `size` bytes. `size` must be less than
77-
1,073,741,824 bytes (1 GB) on 32 bits architectures or
78-
2,147,483,648 bytes (2 GB) on 64 bits architectures,
79-
otherwise a [`RangeError`][] is thrown.
77+
1,073,741,824 bytes (1 GB) on 32-bit architectures or
78+
2,147,483,648 bytes (2 GB) on 64-bit architectures.
79+
Otherwise, a [`RangeError`][] is thrown.
8080

8181
Unlike `ArrayBuffers`, the underlying memory for buffers is not initialized. So
8282
the contents of a newly created `Buffer` are unknown and could contain
@@ -208,14 +208,14 @@ Example: copy an ASCII string into a buffer, one byte at a time:
208208

209209
// Node.js
210210

211-
Returns a boolean of whether `this` and `otherBuffer` have the same
211+
Returns a boolean indicating whether `this` and `otherBuffer` have the same
212212
bytes.
213213

214214
### buf.compare(otherBuffer)
215215

216216
* `otherBuffer` {Buffer}
217217

218-
Returns a number indicating whether `this` comes before or after or is
218+
Returns a number indicating whether `this` comes before, after, or is
219219
the same as the `otherBuffer` in sort order.
220220

221221

@@ -227,7 +227,7 @@ the same as the `otherBuffer` in sort order.
227227
* `sourceEnd` Number, Optional, Default: `buffer.length`
228228

229229
Copies data from a region of this buffer to a region in the target buffer even
230-
if the target memory region overlaps with the source. If `undefined` the
230+
if the target memory region overlaps with the source. If `undefined`, the
231231
`targetStart` and `sourceStart` parameters default to `0` while `sourceEnd`
232232
defaults to `buffer.length`.
233233

@@ -326,7 +326,7 @@ use [`buf.slice`][] to create a new buffer.
326326
* `noAssert` Boolean, Optional, Default: false
327327
* Return: Number
328328

329-
Reads a 64 bit double from the buffer at the specified offset with specified
329+
Reads a 64-bit double from the buffer at the specified offset with specified
330330
endian format.
331331

332332
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
@@ -356,7 +356,7 @@ Example:
356356
* `noAssert` Boolean, Optional, Default: false
357357
* Return: Number
358358

359-
Reads a 32 bit float from the buffer at the specified offset with specified
359+
Reads a 32-bit float from the buffer at the specified offset with specified
360360
endian format.
361361

362362
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
@@ -381,7 +381,7 @@ Example:
381381
* `noAssert` Boolean, Optional, Default: false
382382
* Return: Number
383383

384-
Reads a signed 8 bit integer from the buffer at the specified offset.
384+
Reads a signed 8-bit integer from the buffer at the specified offset.
385385

386386
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
387387
may be beyond the end of the buffer. Defaults to `false`.
@@ -396,7 +396,7 @@ complement signed values.
396396
* `noAssert` Boolean, Optional, Default: false
397397
* Return: Number
398398

399-
Reads a signed 16 bit integer from the buffer at the specified offset with
399+
Reads a signed 16-bit integer from the buffer at the specified offset with
400400
specified endian format.
401401

402402
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
@@ -412,7 +412,7 @@ complement signed values.
412412
* `noAssert` Boolean, Optional, Default: false
413413
* Return: Number
414414

415-
Reads a signed 32 bit integer from the buffer at the specified offset with
415+
Reads a signed 32-bit integer from the buffer at the specified offset with
416416
specified endian format.
417417

418418
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
@@ -447,7 +447,7 @@ may be beyond the end of the buffer. Defaults to `false`.
447447
* `noAssert` Boolean, Optional, Default: false
448448
* Return: Number
449449

450-
Reads an unsigned 8 bit integer from the buffer at the specified offset.
450+
Reads an unsigned 8-bit integer from the buffer at the specified offset.
451451

452452
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
453453
may be beyond the end of the buffer. Defaults to `false`.
@@ -477,7 +477,7 @@ Example:
477477
* `noAssert` Boolean, Optional, Default: false
478478
* Return: Number
479479

480-
Reads an unsigned 16 bit integer from the buffer at the specified offset with
480+
Reads an unsigned 16-bit integer from the buffer at the specified offset with
481481
specified endian format.
482482

483483
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
@@ -513,7 +513,7 @@ Example:
513513
* `noAssert` Boolean, Optional, Default: false
514514
* Return: Number
515515

516-
Reads an unsigned 32 bit integer from the buffer at the specified offset with
516+
Reads an unsigned 32-bit integer from the buffer at the specified offset with
517517
specified endian format.
518518

519519
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
@@ -604,7 +604,7 @@ See `buffer.write()` example, above.
604604

605605
### buf.toJSON()
606606

607-
Returns a JSON-representation of the Buffer instance. `JSON.stringify`
607+
Returns a JSON representation of the Buffer instance. `JSON.stringify`
608608
implicitly calls this function when stringifying a Buffer instance.
609609

610610
Example:
@@ -650,7 +650,7 @@ The method will not write partial characters.
650650
* `noAssert` Boolean, Optional, Default: false
651651

652652
Writes `value` to the buffer at the specified offset with specified endian
653-
format. Note, `value` must be a valid 64 bit double.
653+
format. `value` must be a valid 64-bit double.
654654

655655
Set `noAssert` to true to skip validation of `value` and `offset`. This means
656656
that `value` may be too large for the specific function and `offset` may be
@@ -679,7 +679,7 @@ Example:
679679
* `noAssert` Boolean, Optional, Default: false
680680

681681
Writes `value` to the buffer at the specified offset with specified endian
682-
format. Note, behavior is unspecified if `value` is not a 32 bit float.
682+
format. Behavior is unspecified if `value` is not a 32-bit float.
683683

684684
Set `noAssert` to true to skip validation of `value` and `offset`. This means
685685
that `value` may be too large for the specific function and `offset` may be
@@ -706,8 +706,8 @@ Example:
706706
* `offset` Number
707707
* `noAssert` Boolean, Optional, Default: false
708708

709-
Writes `value` to the buffer at the specified offset. Note, `value` must be a
710-
valid signed 8 bit integer.
709+
Writes `value` to the buffer at the specified offset. `value` must be a
710+
valid signed 8-bit integer.
711711

712712
Set `noAssert` to true to skip validation of `value` and `offset`. This means
713713
that `value` may be too large for the specific function and `offset` may be
@@ -725,7 +725,7 @@ signed integer into `buffer`.
725725
* `noAssert` Boolean, Optional, Default: false
726726

727727
Writes `value` to the buffer at the specified offset with specified endian
728-
format. Note, `value` must be a valid signed 16 bit integer.
728+
format. `value` must be a valid signed 16-bit integer.
729729

730730
Set `noAssert` to true to skip validation of `value` and `offset`. This means
731731
that `value` may be too large for the specific function and `offset` may be
@@ -743,7 +743,7 @@ complement signed integer into `buffer`.
743743
* `noAssert` Boolean, Optional, Default: false
744744

745745
Writes `value` to the buffer at the specified offset with specified endian
746-
format. Note, `value` must be a valid signed 32 bit integer.
746+
format. `value` must be a valid signed 32-bit integer.
747747

748748
Set `noAssert` to true to skip validation of `value` and `offset`. This means
749749
that `value` may be too large for the specific function and `offset` may be
@@ -778,8 +778,8 @@ to `false`.
778778
* `offset` Number
779779
* `noAssert` Boolean, Optional, Default: false
780780

781-
Writes `value` to the buffer at the specified offset. Note, `value` must be a
782-
valid unsigned 8 bit integer.
781+
Writes `value` to the buffer at the specified offset. `value` must be a
782+
valid unsigned 8-bit integer.
783783

784784
Set `noAssert` to true to skip validation of `value` and `offset`. This means
785785
that `value` may be too large for the specific function and `offset` may be
@@ -806,7 +806,7 @@ Example:
806806
* `noAssert` Boolean, Optional, Default: false
807807

808808
Writes `value` to the buffer at the specified offset with specified endian
809-
format. Note, `value` must be a valid unsigned 16 bit integer.
809+
format. `value` must be a valid unsigned 16-bit integer.
810810

811811
Set `noAssert` to true to skip validation of `value` and `offset`. This means
812812
that `value` may be too large for the specific function and `offset` may be
@@ -837,7 +837,7 @@ Example:
837837
* `noAssert` Boolean, Optional, Default: false
838838

839839
Writes `value` to the buffer at the specified offset with specified endian
840-
format. Note, `value` must be a valid unsigned 32 bit integer.
840+
format. `value` must be a valid unsigned 32-bit integer.
841841

842842
Set `noAssert` to true to skip validation of `value` and `offset`. This means
843843
that `value` may be too large for the specific function and `offset` may be
@@ -886,7 +886,7 @@ be overridden by user modules. See [`util.inspect()`][] for more details on
886886
`buffer.inspect()` behavior.
887887

888888
Note that this is a property on the buffer module returned by
889-
`require('buffer')`, not on the Buffer global, or a buffer instance.
889+
`require('buffer')`, not on the Buffer global or a buffer instance.
890890

891891
## ES6 iteration
892892

@@ -901,7 +901,7 @@ Buffers can be iterated over using `for..of` syntax:
901901
// 2
902902
// 3
903903

904-
Additionally, `buffer.values()`, `buffer.keys()` and `buffer.entries()`
904+
Additionally, the `buffer.values()`, `buffer.keys()`, and `buffer.entries()`
905905
methods can be used to create iterators.
906906

907907
## Class: SlowBuffer
@@ -914,7 +914,7 @@ larger allocated object. This approach improves both performance and memory
914914
usage since v8 does not need to track and cleanup as many `Persistent` objects.
915915

916916
In the case where a developer may need to retain a small chunk of memory from a
917-
pool for an indeterminate amount of time it may be appropriate to create an
917+
pool for an indeterminate amount of time, it may be appropriate to create an
918918
un-pooled Buffer instance using SlowBuffer and copy out the relevant bits.
919919

920920
// need to keep around a few small chunks of memory
@@ -929,8 +929,8 @@ un-pooled Buffer instance using SlowBuffer and copy out the relevant bits.
929929
store.push(sb);
930930
});
931931

932-
Though this should be used sparingly and only be a last resort *after* a developer
933-
has actively observed undue memory retention in their applications.
932+
This should be used only as a last resort *after* a developer has observed
933+
undue memory retention in their applications.
934934

935935
[`Array#indexOf()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf
936936
[`buf.fill(0)`]: #buffer_buf_fill_value_offset_end

0 commit comments

Comments
 (0)