Skip to content

buffer: adds buffer.prototype.split / join

Rodrigo Muino Tomonari requested to merge github/fork/eljefedelrodeodeljefe/feature/buffer-split-join into master
Checklist
  • tests and code linting passes
  • a test and/or benchmark is included
  • documentation is changed or added
  • the commit message follows commit guidelines
Affected core subsystem(s)

buffer

Description of change

WIP

  • benchmarks
  • one less copy (had problems persisting the input buffer in .split())
  • general c++ related review induced changes, style etc.

Description/ Motivation This PR introduces two additions to the buffer API, .split() and .join(). Motivation is too handle buffers directly (say in streams) and having higher efficiency to what would be possible in userland js. This continues the discussion from https://github.com/nodejs/node/issues/5683 whereas as a .replace() API seemed too high level, but can be easily implemented with the methods here.

Comparison In string scenarios the methods are 1.5x to 3x times slower, whereas a similar JS implementation would be 10x to 20x slower. Detailed benchmarks are yet to be written and also the currently implementation makes at least one copy too much (WIP).

Usage The potential usage is bot only string manipulation, but having a general byte manipulation interface with efficient copying.

For docs:

Class Method: Buffer.split([separator])
  • separator {Buffer} A separator that gets matched against the input buffer
  • Return: {Array} Array of Buffers

Buffer.split() behaves similar to String.prototype.split, as such it matches an input against a source buffer, splits the source buffer, removes the input and returns the number of resulting buffers in an array.

const buf = new Buffer('Hello World');
const res = buf.split(new Buffer(' '))

console.log(res);
// [ <Buffer 48 65 6c 6c 6f>, <Buffer 57 6f 72 6c 64> ]

It is also possible to split with an empty buffer, which results in an array with the single bytes of buffer contents wrapped in new buffers.

const buf = new Buffer('Hello');
const res = buf.split(new Buffer(''))

console.log(res);
// [ <Buffer 48>, <Buffer 65>, <Buffer 6c>, <Buffer 6c>, <Buffer 6f> ]
Class Method: Buffer.join(array[, insert])
  • array {Array} Array of buffers that will be joined together
  • insert {Buffer} Buffer that gets inserted between the subjects
  • Return: {Buffer}

Buffer.join() behaves similar to Array.prototype.join, as such it matches takes an array of buffers and generate new buffer with the concatenated buffers. Optionally it takes a an insert as argument that will be inserted between the buffers.

const res = Buffer.join([
  new Buffer('Hello'),
  new Buffer('World'),
], new Buffer('\n'));

console.log(res);
// <Buffer 48 65 6c 6c 6f 0a 57 6f 72 6c 64>
console.log(res.toString());
// Hello
// World

Note: Array.prototype.join would fill in commas if no insert will be provided. Buffer.join() though will simply concat against the next buffer.

const res = Buffer.join([
  new Buffer('Hello'),
  new Buffer('World'),
]);

console.log(res.toString());
// HelloWorld

Merge request reports