Package Exports

node-stringbuilder
node-stringbuilder/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (node-stringbuilder) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

StringBuilder for Node.js

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

Code Example

const StringBuilder = require("node-stringbuilder");
const 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

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.

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

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

const 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
const 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,

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

Shrink Capacity

Shrink the capacity of this StringBuilder.

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

Shrink and get the updated capacity,

const capacity = sb.shrinkCapacity(true);

Get Current Text Length

To get the length of this StringBuilder,

const length = sb.length();

Get Current Capacity

To get the length of this StringBuilder,

const capacity = sb.capacity();

Count the words

To count the words,

const words = sb.count();

Build String

Build a string of a specific range of index.

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

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

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

To get the full text,

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

To get one character at a specific index,

const c = sb.charAt(4);

Search String

Search substrings from the head,

const indexArray = sb.indexOf("string");
const 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,

const indexArray = sb.lastIndexOf("string");

Equals

Determine whether the two strings are the same.

const equal = sb.equals("string");

To ignore the case of letters,

const equal = sb.equalsIgnoreCase("string");

Determine whether it starts or ends with a specific pattern.

const start = sb.startsWith("string");
const end = sb.endsWith("string");

RegExp is not supported in startsWith and endsWith methods.

Clone

Clone this StringBuilder.

const 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