Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Buffers and Encoding

Node.js buf.copy() method

Reference for Node.js buf.copy(): copy a byte range into another buffer, handle overlap and truncation, and understand the returned byte count and the buf.set() alternative.

buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]]) copies bytes from buf into target and returns the number of bytes actually copied. It never grows the target: if the range does not fit, the copy is cut short and no error is raised.

Unlike buf.subarray(), the result is independent memory. It also works when the source and target are the same buffer or overlap, in which case the bytes arrive as if the source had been copied to a temporary place first.

NODE
const target = Buffer.alloc(6, ".");
const n = Buffer.from("abc").copy(target, 2);
// n === 3, target is "..abc."

Try it

Node.js Copying into a larger buffer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Truncation and overlap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
buf.copy(target, targetStart = 0, sourceStart = 0, sourceEnd = buf.length)
// returns number
Name Description
target A Buffer or Uint8Array to copy into.
targetStart Offset in target where writing starts. Default 0.
sourceStart Offset in buf where reading starts. Default 0.
sourceEnd Offset in buf where reading stops, not included. Default buf.length.

Returns: the number of bytes copied, which is the smaller of the requested range and the room left in target.

Errors and edge cases:

  • target that is not a Buffer or Uint8Array throws TypeError (ERR_INVALID_ARG_TYPE).
  • A negative targetStart, sourceStart or sourceEnd, or a sourceStart larger than buf.length, throws ERR_OUT_OF_RANGE. Fractions are truncated.
  • If targetStart is at or beyond the end of target, or sourceStart is not below sourceEnd, nothing is copied and the result is 0.
  • sourceEnd above the length is clamped to the length.

Usage notes

  • Check the return value if truncation would be a bug. The method will not warn you.
  • target.set(source, offset) throws RangeError when the source does not fit, which is safer when you expect a perfect fit. copy() is better when partial copies are fine or you need a source range.
  • A range of one buffer into another: target.set(buf.subarray(a, b), offset) is equivalent to buf.copy(target, offset, a, b).
  • Overlap is safe, so copy() can shift data inside a buffer, for example to remove consumed bytes from the front of a receive buffer.
  • Cheaper than concatenating in a loop. When you know the total size, allocate once and copy each piece in, or call Buffer.concat() with the total length.
  • For a duplicate of a whole buffer, Buffer.from(buf) is simpler.
  • Strings: to place text into a buffer, use buf.write() instead; copy() only moves bytes.