StringBuilder for Node.js

An easy and fast in-memory string builder for Node.js.

NOTICE: N-API is a new experimental feature in Node.js 8. Currently, it can be used by adding --napi-modules option when executing Node.js 8.

Code Example

const StringBuilder = require('node-stringbuilder');
var sb = new StringBuilder('Hi');
sb.appendLine(',').append('This is a simple example demonstrating how to use this module.');
console.log(sb.toString()); // Hi,
// This is a simple example demonstrating how to use this module.
sb.insert('Text can be added into any position of this builder.');
sb.replace(53, 118, 'Or replace the existing text.');
console.log(sb.toString()); // Text can be added into any position of this builder.HOr replace the existing text.
sb.deleteCharAt(52).insert(52, ' ');
console.log(sb.toString()); // Text can be added into any position of this builder. Or replace the existing text.
sb.toLowerCase().replaceAll('text', 'string');
console.log(sb.toString()); // string can be added into any position of this builder. or replace the existing string.
console.log(sb.clone().reverse().toString()); // .gnirts gnitsixe eht ecalper ro .redliub siht fo noitisop yna otni dedda eb nac gnirts
console.log(sb.toString(0, 19)); // string can be added
console.log(sb.length()); // 86
console.log(sb.count()); // 15
console.log(sb.indexOf('is')); // Uint32Array [ 43, 72 ]
console.log(sb.indexOfSkip('is')); // Uint32Array [ 43, 72 ]
console.log(sb.lastIndexOf('is')); // Uint32Array [ 72, 43 ]
console.log(sb.indexOfRegExp(/is/g)); // { index: [ 43, 72 ], lastIndex: [ 45, 74 ] }
console.log(sb.repeat().indexOf('is')); // Uint32Array [ 43, 72, 129, 158 ]
sb.substring(11, 37);
console.log(sb.toString()); // be added into any position
console.log(sb.equalsIgnoreCase('be Added into Any position')); // true
console.log(sb.toBuffer()); // UTF-8 encoded

Installation

Run npm i or npm install to install.

npm install node-stringbuilder

If you want to save this module to package.json, please add --save option.

npm install node-stringbuilder --save

Features

• Implemented with N-API.
• Operating strings in a scalable buffer.
• Multiple types of data are allowed to input.
  • Strings
  • Buffers(UTF-8 encoded)
  • Instances of this StringBuilder module
  • ReadStream(to read file)
  • Numbers, booleans, other objects
• Fast string search algorithm(Boyer-Moore-MagicLen)
• Clonable

Usage

Initiaiizing

Import this module by using require function.

const StringBuilder = require('node-stringbuilder');

Use new operator or from function to create a StringBuilder instance.

var sb1 = new StringBuilder();
// or
var sb2 = StringBuilder.from();

When creating an instance of StringBuilder, you can initialize the text and capacity.

var sb = StringBuilder.from('First', 4096);

By default, a block of buffer space used by StringBuilder is 128 characters. The space of the buffer can be expanded or shrinked by blocks.

// To expand
var newCapacity = 65536;
sb.expandCapacity(newCapacity);
// To shrink
sb.shrinkCapacity();

If some text are added into StringBuilder, StringBuilder will check its space. And if the space is too small, it will re-alloc a bigger one automatically. This re-allocation has overheads, if it does this frequently, your program may be slowed down. Therefore, if you can predict the length of your text, please set the capacity when creating a StringBuilder instance.

Append

Concat text.

sb.append('string').append(123).append(false).append(fs.createReadStream(path));

Add a new line after append.

sb.appendLine('string');

Append text repeatedly.

sb.appendRepeat('string', 3);

Append a file asynchronizely.

await sb.appendReadStream(fs.createReadStream(path));

Insert

Insert text to any position.

sb.insert('string'); // To the head.
sb.insert(5, 'string');

Replace

Replace text to the position in a range of index.

sb.replace(4, 15, 'string');

Replace existing substrings to another.

sb.replacePattern('old', 'new');
sb.replacePattern('old', 'new', offset, limit);

Replace all existing substrings to another.

sb.replaceAll('old', 'new');

Delete

Delete text from a range of index.

sb.delete(4, 15);

Delete a character at a index.

sb.deleteCharAt(4);

Clear all text, but preserve the capacity.

sb.clear();

Substring

Reserve text in a range of index.

sb.substring(1, 5); // input the start and end index

sb.substr(1, 5); // input the start index and length

Reverse

Reverse text.

sb.reverse();

Upper/Lower Case

Convert text to upper or lower case.

sb.upperCase();
sb.lowerCase();

Trim

Remove any leading and trailing whitespace.

sb.trim();

Repeat

Repeat current text for specific count.

sb.repeat(1);

Expand Capacity

Expand the capacity of this StringBuilder.

sb.expandCapacity(4096).append('string');

Expand and get the updated capacity,

var capacity = sb.expandCapacity(4096, true);

Shrink Capacity

Shrink the capacity of this StringBuilder.

sb.shrinkCapacity().clone().append('string');

Shrink and get the updated capacity,

var capacity = sb.shrinkCapacity(true);

Get Current Text Length

To get the length of this StringBuilder,

var length = sb.length();

Get Current Capacity

To get the length of this StringBuilder,

var capacity = sb.capacity();

Count the words

To count the words,

var words = sb.count();

Build String

Build a string of a specific range of index.

var str = sb.toString(4, 10);

Build a UTF-8 buffer of a specific range of index.

var buffer = sb.toBuffer(4, 10);

To get the full text,

var text = sb.toString();
var buffer = sb.toBuffer();

To get one character at a specific index,

var c = sb.charAt(4);

Search String

Search substrings from the head,

var indexArray = sb.indexOf('string');
var indexArray2 = sb.indexOf('string', offset, limit);

Search substrings from the head by using RegExp,

var indexArray = sb.indexOf(/string/g);

Search substrings from the end,

var indexArray = sb.lastIndexOf('string');

Equals

Determine whether the two strings are the same.

var equal = sb.equals('string');

To ignore the case of letters,

var equal = sb.equalsIgnoreCase('string');

Determine whether it starts or ends with a specific pattern.

var start = sb.startsWith('string');
var end = sb.endsWith('string');

RegExp is not supported in startsWith and endsWith methods.

Clone

Clone this StringBuilder.

var newSB = sb.clone();

Tests

To run the test suite, first install the dependencies, then run npm test:

npm install
npm test

Benchmark

To run the benchmark suite, first install the dependencies, then run npm run benchmark:

npm install
npm run benchmark

Here is my result,

Append
  - 43 milliseconds
  ✓ Natively append text 1000000 times (43ms)
  - 567 milliseconds
  ✓ Use StringBuilder to append text 1000000 times (567ms)
  - 1278 milliseconds
  ✓ Use StringBuilder to insert text 1000000 times at the end (1287ms)
  - 17 milliseconds
  ✓ Use StringBuilder to append text 1000000 times repeatly

Insert
  - 92 milliseconds
  ✓ Natively insert text 10000 times (92ms)
  - 10 milliseconds
  ✓ Use StringBuilder to insert text 10000 times

Delete
  - 1427 milliseconds
  ✓ Natively delete text 5000 times (1429ms)
  - 87 milliseconds
  ✓ Use StringBuilder to delete text 5000 times (88ms)

Replace
  - 1511 milliseconds
  ✓ Natively replace text 5000 times (1513ms)
  - 85 milliseconds
  ✓ Use StringBuilder to replace text 5000 times (86ms)

Replace Pattern
  - 37 milliseconds
  ✓ Natively replace text with the same length by using a RegExp pattern
  - 20 milliseconds
  ✓ Use StringBuilder to replace text with the same length by using a pattern
  - 35 milliseconds
  ✓ Natively replace text by using a RegExp pattern
  - 29 milliseconds
  ✓ Use StringBuilder to replace text by using a pattern

Equals
  - 2 milliseconds
  ✓ Natively check the equal 50000 times
  - 13 milliseconds
  ✓ Use StringBuilder to check the equal 50000 times

EqualsIgnoreCase
  - 21 milliseconds
  ✓ Natively check the equal 50000 times
  - 19 milliseconds
  ✓ Use StringBuilder to check the equal 50000 times

IndexOf
  - 65 milliseconds
  ✓ Natively search text (65ms)
  - 2 milliseconds
  ✓ Use StringBuilder to search text

Reverse
  - 516 milliseconds
  ✓ Natively reverse text (516ms)
  - 14 milliseconds
  ✓ Use StringBuilder to reverse text

According to the result of benchmark, if you just want to append a few different strings, please append them by using native operator + instead of this module.

License

MIT

To Do

• More test cases

If you can help me do this as collaborators, I will be grateful.