Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: document default length as buffer.length #40354

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

doc: document default length as buffer.length #40354

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
454c42b
doc: document default length as buffer.length
wbt Oct 6, 2021
ebcad8d
doc: update reference link
wbt Oct 7, 2021
406a6b0
doc: add line break in md source
wbt Oct 7, 2021
5d5072e
doc: describe buf.length as alias
wbt Oct 7, 2021
5bb6caa
doc: trim a trailing whitespace
wbt Oct 7, 2021
42d002a
doc: trim trailing whitespace
wbt Oct 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -378,7 +378,7 @@ added:
* `offset` {integer} The location in the buffer at which to start filling.
**Default:** `0`
* `length` {integer} The number of bytes to read. **Default:**
`buffer.byteLength`
`buffer.length` (`.byteLength` for TypedArray|DataView types)
* `position` {integer} The location where to begin reading data from the
file. If `null`, data will be read from the current file position, and
the position will be updated. If `position` is an integer, the current
Expand Down Expand Up @@ -568,7 +568,7 @@ changes:
* `offset` {integer} The start position from within `buffer` where the data
to write begins. **Default:** `0`
* `length` {integer} The number of bytes from `buffer` to write. **Default:**
`buffer.byteLength`
`buffer.length` (`.byteLength` for TypedArray|DataView types; ignored for string|Object types)
* `position` {integer} The offset from the beginning of the file where the
data from `buffer` should be written. If `position` is not a `number`,
the data will be written at the current position. See the POSIX pwrite(2)
Expand Down Expand Up @@ -3022,7 +3022,7 @@ changes:
* `options` {Object}
* `buffer` {Buffer|TypedArray|DataView} **Default:** `Buffer.alloc(16384)`
* `offset` {integer} **Default:** `0`
* `length` {integer} **Default:** `buffer.byteLength`
* `length` {integer} **Default:** `buffer.length` (`.byteLength` for TypedArray|DataView types)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally don't think this makes it much clearer. buffer.byteLength is correct for Buffer and TypedArray, whereas buffer.length is only correct for Buffer (and Uint8Array).

buffer.byteLength is always correct, buffer.length is not.

Copy link
Contributor Author

@wbt wbt Oct 7, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to the documentation, Buffer.byteLength is a function that does not return the number of bytes in the buffer. Buffer.length does provide that data.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wbt Buffer extends Uint8Array. buffer.byteLength is the instance property that is inherited from Uint8Array. Buffer.byteLength() (capital B) is the static method.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tniessen Does the latest commit seem to provide more helpful clarification?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW I agree with Tobias, we should keep referencing .byteLength – it's also what the code is doing.

* `position` {integer|bigint} **Default:** `null`
* `callback` {Function}
* `err` {Error}
Expand Down Expand Up @@ -4134,7 +4134,7 @@ the current position. See pwrite(2).
The callback will receive the arguments `(err, written, string)` where `written`
specifies how many _bytes_ the passed string required to be written. Bytes
written is not necessarily the same as string characters written. See
[`Buffer.byteLength`][].
[`Buffer.byteLength()`][].
wbt marked this conversation as resolved.
Show resolved Hide resolved

It is unsafe to use `fs.write()` multiple times on the same file without waiting
for the callback. For this scenario, [`fs.createWriteStream()`][] is
Expand Down Expand Up @@ -5025,7 +5025,7 @@ changes:
* `buffer` {Buffer|TypedArray|DataView}
* `options` {Object}
* `offset` {integer} **Default:** `0`
* `length` {integer} **Default:** `buffer.byteLength`
* `length` {integer} **Default:** `buffer.length` (`.byteLength` for TypedArray|DataView types)
* `position` {integer|bigint} **Default:** `null`
* Returns: {number}

Expand Down