Skip to content

Commit

Permalink
doc: remove example labels from buffer.md
Browse files Browse the repository at this point in the history
Remove instances of `Example:` that introduce code that is
self-evidently example code. Move descriptive text about examples into
comments in the code. Wrap adjacent text to 80 characters.

PR-URL: #19582
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
  • Loading branch information
Trott authored and targos committed Mar 27, 2018
1 parent f07e820 commit 4db7848
Showing 1 changed file with 22 additions and 73 deletions.
95 changes: 22 additions & 73 deletions doc/api/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,8 +120,6 @@ impact* on performance. Use of the `--zero-fill-buffers` option is recommended
only when necessary to enforce that newly allocated `Buffer` instances cannot
contain potentially sensitive data.

Example:

```txt
$ node --zero-fill-buffers
> Buffer.allocUnsafe(5);
Expand Down Expand Up @@ -157,8 +155,6 @@ such as UTF-8, UCS2, Base64, or even Hex-encoded data. It is possible to
convert back and forth between `Buffer` instances and ordinary JavaScript strings
by using an explicit character encoding.

Example:

```js
const buf = Buffer.from('hello world', 'ascii');

Expand Down Expand Up @@ -229,8 +225,6 @@ elements, and not as a byte array of the target type. That is,
It is possible to create a new `Buffer` that shares the same allocated memory as
a [`TypedArray`] instance by using the TypeArray object's `.buffer` property.

Example:

```js
const arr = new Uint16Array(2);

Expand Down Expand Up @@ -259,8 +253,6 @@ Note that when creating a `Buffer` using a [`TypedArray`]'s `.buffer`, it is
possible to use only a portion of the underlying [`ArrayBuffer`] by passing in
`byteOffset` and `length` parameters.

Example:

```js
const arr = new Uint16Array(20);
const buf = Buffer.from(arr.buffer, 0, 16);
Expand Down Expand Up @@ -289,8 +281,6 @@ function:
`Buffer` instances can be iterated over using the [`ECMAScript 2015`] (ES6) `for..of`
syntax.

Example:

```js
const buf = Buffer.from([1, 2, 3]);

Expand Down Expand Up @@ -329,8 +319,6 @@ changes:

Allocates a new `Buffer` using an `array` of octets.

Example:

```js
// Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'
const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
Expand Down Expand Up @@ -370,8 +358,6 @@ share the same allocated memory as the [`TypedArray`].
The optional `byteOffset` and `length` arguments specify a memory range within
the `arrayBuffer` that will be shared by the `Buffer`.

Example:

```js
const arr = new Uint16Array(2);

Expand Down Expand Up @@ -409,8 +395,6 @@ changes:

Copies the passed `buffer` data onto a new `Buffer` instance.

Example:

```js
const buf1 = new Buffer('buffer');
const buf2 = new Buffer(buf1);
Expand Down Expand Up @@ -453,8 +437,6 @@ created in this way is *not initialized*. The contents of a newly created
[`Buffer.alloc(size)`][`Buffer.alloc()`] instead to initialize a `Buffer`
to zeroes.

Example:

```js
const buf = new Buffer(10);

Expand Down Expand Up @@ -514,8 +496,6 @@ changes:
Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the
`Buffer` will be *zero-filled*.

Example:

```js
const buf = Buffer.alloc(5);

Expand All @@ -530,8 +510,6 @@ thrown. A zero-length `Buffer` will be created if `size` is 0.
If `fill` is specified, the allocated `Buffer` will be initialized by calling
[`buf.fill(fill)`][`buf.fill()`].

Example:

```js
const buf = Buffer.alloc(5, 'a');

Expand All @@ -542,8 +520,6 @@ console.log(buf);
If both `fill` and `encoding` are specified, the allocated `Buffer` will be
initialized by calling [`buf.fill(fill, encoding)`][`buf.fill()`].

Example:

```js
const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');

Expand Down Expand Up @@ -577,8 +553,6 @@ initialized*. The contents of the newly created `Buffer` are unknown and
*may contain sensitive data*. Use [`Buffer.alloc()`] instead to initialize
`Buffer` instances to zeroes.

Example:

```js
const buf = Buffer.allocUnsafe(10);

Expand Down Expand Up @@ -635,8 +609,6 @@ memory from a pool for an indeterminate amount of time, it may be appropriate
to create an un-pooled `Buffer` instance using `Buffer.allocUnsafeSlow()` then
copy out the relevant bits.

Example:

```js
// Need to keep around a few small chunks of memory
const store = [];
Expand Down Expand Up @@ -686,8 +658,6 @@ For `'base64'` and `'hex'`, this function assumes valid input. For strings that
contain non-Base64/Hex-encoded data (e.g. whitespace), the return value might be
greater than the length of a `Buffer` created from the string.

Example:

```js
const str = '\u00bd + \u00bc = \u00be';

Expand Down Expand Up @@ -716,8 +686,6 @@ Compares `buf1` to `buf2` typically for the purpose of sorting arrays of
`Buffer` instances. This is equivalent to calling
[`buf1.compare(buf2)`][`buf.compare()`].

Example:

```js
const buf1 = Buffer.from('1234');
const buf2 = Buffer.from('0123');
Expand Down Expand Up @@ -757,9 +725,9 @@ If `totalLength` is provided, it is coerced to an unsigned integer. If the
combined length of the `Buffer`s in `list` exceeds `totalLength`, the result is
truncated to `totalLength`.

Example: Create a single `Buffer` from a list of three `Buffer` instances

```js
// Create a single `Buffer` from a list of three `Buffer` instances.

const buf1 = Buffer.alloc(10);
const buf2 = Buffer.alloc(14);
const buf3 = Buffer.alloc(18);
Expand All @@ -785,8 +753,6 @@ added: v5.10.0

Allocates a new `Buffer` using an `array` of octets.

Example:

```js
// Creates a new Buffer containing UTF-8 bytes of the string 'buffer'
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
Expand All @@ -810,8 +776,6 @@ memory. For example, when passed a reference to the `.buffer` property of a
[`TypedArray`] instance, the newly created `Buffer` will share the same
allocated memory as the [`TypedArray`].

Example:

```js
const arr = new Uint16Array(2);

Expand All @@ -834,8 +798,6 @@ console.log(buf);
The optional `byteOffset` and `length` arguments specify a memory range within
the `arrayBuffer` that will be shared by the `Buffer`.

Example:

```js
const ab = new ArrayBuffer(10);
const buf = Buffer.from(ab, 0, 2);
Expand All @@ -856,8 +818,6 @@ added: v5.10.0

Copies the passed `buffer` data onto a new `Buffer` instance.

Example:

```js
const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);
Expand Down Expand Up @@ -976,9 +936,9 @@ This operator is inherited from `Uint8Array`, so its behavior on out-of-bounds
access is the same as `UInt8Array` - that is, getting returns `undefined` and
setting does nothing.

Example: Copy an ASCII string into a `Buffer`, one byte at a time

```js
// Copy an ASCII string into a `Buffer` one byte at a time.

const str = 'Node.js';
const buf = Buffer.allocUnsafe(str.length);

Expand Down Expand Up @@ -1090,10 +1050,8 @@ added: v0.1.90
Copies data from a region of `buf` to a region in `target` even if the `target`
memory region overlaps with `buf`.

Example: Create two `Buffer` instances, `buf1` and `buf2`, and copy `buf1` from
byte 16 through byte 19 into `buf2`, starting at the 8th byte in `buf2`

```js
// Create two `Buffer` instances.
const buf1 = Buffer.allocUnsafe(26);
const buf2 = Buffer.allocUnsafe(26).fill('!');

Expand All @@ -1102,16 +1060,17 @@ for (let i = 0; i < 26; i++) {
buf1[i] = i + 97;
}

// Copy `buf1` bytes 16 through 19 into `buf2` starting at byte 8 of `buf2`
buf1.copy(buf2, 8, 16, 20);

console.log(buf2.toString('ascii', 0, 25));
// Prints: !!!!!!!!qrst!!!!!!!!!!!!!
```

Example: Create a single `Buffer` and copy data from one region to an
overlapping region within the same `Buffer`

```js
// Create a `Buffer` and copy data from one region to an overlapping region
// within the same `Buffer`.

const buf = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
Expand All @@ -1135,9 +1094,9 @@ added: v1.1.0
Creates and returns an [iterator] of `[index, byte]` pairs from the contents of
`buf`.

Example: Log the entire contents of a `Buffer`

```js
// Log the entire contents of a `Buffer`.

const buf = Buffer.from('buffer');

for (const pair of buf.entries()) {
Expand Down Expand Up @@ -1198,9 +1157,9 @@ Fills `buf` with the specified `value`. If the `offset` and `end` are not given,
the entire `buf` will be filled. This is meant to be a small simplification to
allow the creation and filling of a `Buffer` to be done on a single line.

Example: Fill a `Buffer` with the ASCII character `'h'`

```js
// Fill a `Buffer` with the ASCII character 'h'.

const b = Buffer.allocUnsafe(50).fill('h');

console.log(b.toString());
Expand All @@ -1212,9 +1171,9 @@ console.log(b.toString());
If the final write of a `fill()` operation falls on a multi-byte character,
then only the first bytes of that character that fit into `buf` are written.

Example: Fill a `Buffer` with a two-byte character

```js
// Fill a `Buffer` with a two-byte character.

console.log(Buffer.allocUnsafe(3).fill('\u0222'));
// Prints: <Buffer c8 a2 c8>
```
Expand Down Expand Up @@ -1355,8 +1314,6 @@ added: v1.1.0

Creates and returns an [iterator] of `buf` keys (indices).

Example:

```js
const buf = Buffer.from('buffer');

Expand Down Expand Up @@ -1457,9 +1414,9 @@ added: v0.1.90
Returns the amount of memory allocated for `buf` in bytes. Note that this
does not necessarily reflect the amount of "usable" data within `buf`.

Example: Create a `Buffer` and write a shorter ASCII string to it

```js
// Create a `Buffer` and write a shorter ASCII string to it.

const buf = Buffer.alloc(1234);

console.log(buf.length);
Expand Down Expand Up @@ -1819,10 +1776,10 @@ that of `end` equal to [`buf.length`].
Modifying the new `Buffer` slice will modify the memory in the original `Buffer`
because the allocated memory of the two objects overlap.

Example: Create a `Buffer` with the ASCII alphabet, take a slice, and then modify
one byte from the original `Buffer`

```js
// Create a `Buffer` with the ASCII alphabet, take a slice, and modify one byte
// from the original `Buffer`.

const buf1 = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
Expand Down Expand Up @@ -1954,8 +1911,6 @@ added: v0.9.2
Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls
this function when stringifying a `Buffer` instance.

Example:

```js
const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
const json = JSON.stringify(buf);
Expand Down Expand Up @@ -2065,8 +2020,6 @@ The `length` parameter is the number of bytes to write. If `buf` did not contain
enough space to fit the entire string, only a partial amount of `string` will
be written. However, partially encoded characters will not be written.

Example:

```js
const buf = Buffer.allocUnsafe(256);

Expand Down Expand Up @@ -2477,8 +2430,6 @@ In the case where a developer may need to retain a small chunk of memory from a
pool for an indeterminate amount of time, it may be appropriate to create an
un-pooled `Buffer` instance using `SlowBuffer` then copy out the relevant bits.

Example:

```js
// Need to keep around a few small chunks of memory
const store = [];
Expand Down Expand Up @@ -2513,10 +2464,8 @@ Allocates a new `Buffer` of `size` bytes. If the `size` is larger than
thrown. A zero-length `Buffer` will be created if `size` is 0.

The underlying memory for `SlowBuffer` instances is *not initialized*. The
contents of a newly created `SlowBuffer` are unknown and may contain
sensitive data. Use [`buf.fill(0)`][`buf.fill()`] to initialize a `SlowBuffer` to zeroes.

Example:
contents of a newly created `SlowBuffer` are unknown and may contain sensitive
data. Use [`buf.fill(0)`][`buf.fill()`] to initialize a `SlowBuffer` to zeroes.

```js
const { SlowBuffer } = require('buffer');
Expand Down

0 comments on commit 4db7848

Please sign in to comment.