From 57678e55817366c39a3a241f89949c8fbe8418bc Mon Sep 17 00:00:00 2001 From: Livia Medeiros <74449973+LiviaMedeiros@users.noreply.github.com> Date: Tue, 3 May 2022 02:01:27 +0800 Subject: [PATCH] fs: add `read(buffer[, options])` versions This adds the following: - `fs.read(fd, buffer[, options], callback)`. - `filehandle.read(buffer[, options])`. PR-URL: https://github.com/nodejs/node/pull/42768 Refs: https://github.com/nodejs/node/pull/42601 Reviewed-By: Antoine du Hamel --- doc/api/fs.md | 49 +++++++++++++++++++ lib/fs.js | 37 ++++++++------ lib/internal/fs/promises.js | 17 +++++-- test/parallel/test-fs-read-offset-null.js | 44 ++++++++++++----- test/parallel/test-fs-read-optional-params.js | 46 ++++++++--------- .../test-fs-read-promises-optional-params.js | 12 ++++- 6 files changed, 151 insertions(+), 54 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index a6f0a22cbf985a..fc27ea30d1f5f1 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -417,6 +417,33 @@ Reads data from the file and stores that in the given buffer. If the file is not modified concurrently, the end-of-file is reached when the number of bytes read is zero. +#### `filehandle.read(buffer[, options])` + + + +* `buffer` {Buffer|TypedArray|DataView} A buffer that will be filled with the + file data read. +* `options` {Object} + * `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 - offset` + * `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 + file position will remain unchanged. **Default:**: `null` +* Returns: {Promise} Fulfills upon success with an object with two properties: + * `bytesRead` {integer} The number of bytes read + * `buffer` {Buffer|TypedArray|DataView} A reference to the passed in `buffer` + argument. + +Reads data from the file and stores that in the given buffer. + +If the file is not modified concurrently, the end-of-file is reached when the +number of bytes read is zero. + #### `filehandle.readableWebStream()` + +* `fd` {integer} +* `buffer` {Buffer|TypedArray|DataView} The buffer that the data will be + written to. +* `options` {Object} + * `offset` {integer} **Default:** `0` + * `length` {integer} **Default:** `buffer.byteLength - offset` + * `position` {integer|bigint} **Default:** `null` +* `callback` {Function} + * `err` {Error} + * `bytesRead` {integer} + * `buffer` {Buffer} + +Similar to the [`fs.read()`][] function, this version takes an optional +`options` object. If no `options` object is specified, it will default with the +above values. + ### `fs.readdir(path[, options], callback)`