Skip to content

Latest commit

 

History

History
186 lines (132 loc) · 5.96 KB

README.md

File metadata and controls

186 lines (132 loc) · 5.96 KB
Raw

Stringz Build Status codecov npm

A really small, performant, unicode-aware library for working with Strings in Node.js.

Javascript has a serious problem with unicode. Even ES6 can’t solve the problem entirely since some characters like the new colored emojis are three bytes instead of two bytes. Sometimes even more! "👍🏽".length returns 4 which is totally wrong (hint: it should be 1!). ES6's Array.from tried to solve this, but that even fails: Array.from("👍🏽") returns ["👍", "🏽"] which is incorrect. This library tries to tackle all these problems with a mega RegExp. Read More Here.

Features

  • Unicode-aware string manipulation tools
  • High performance

Install

$ npm install stringz --save

And import it in your awesome node app:

// ES2015+
import * as stringz from 'stringz'; // OR:
import { limit, substring, length, substr } from 'stringz';
// CommonJS
const stringz = require('stringz'); // OR:
const { limit, substr } = require('stringz');

Usage

Limit String to Width

function limit(str[, limit[, padStr[, padPosition]]])
Param Type Default Description
str String none The string to be limited
limit Number 16 Desired string length
padStr String "#" Character to pad the output with
padPosition String "right" Pad position: "right" or "left"

Examples

// Truncate:
limit('Life’s like a box of chocolates.', 20); // "Life's like a box of"

// Pad:
limit('Everybody loves emojis!', 26, '💩'); // "Everybody loves emojis!💩💩💩"
limit('What are you looking at?', 30, '+', 'left'); // "++++++What are you looking at?"

// Unicode Aware:
limit('🤔🤔🤔', 2); // "🤔🤔"
limit('👍🏽👍🏽', 4, '👍🏽'); // "👍🏽👍🏽👍🏽👍🏽"

String Length

function length(str)
Param Type Default Description
str String none String to return the length for

Examples

length('Iñtërnâtiônàlizætiøn☃💩'); // 22

Substring

function substring(str, start[, end])
Param Type Default Description
str String none String to be devided
start Number none Start position
end Number End of string End position

Examples

substring('Emojis 👍🏽 are 🍆 poison. 🌮s are bad.', 7, 14); // "👍🏽 are 🍆"

Substr

function substr(str[, start[, length]])
Param Type Default Description
str String none String to be devided
start Number Start of string Start position
length Number String length minus start parameter Length of result

Examples

substr('A.C. Milan 🇮🇹⚽️', 5, 7); // "Milan 🇮🇹"

IndexOf

function indexOf(str[, searchStr[, position]])
Param Type Default Description
str String none String to get index
searchStr String none String to be searched
position Number 0 Start of searching

Examples

indexOf('Emojis 👍🏽 are 🍆 poison. 🌮s are bad.', 'are'); // 9
indexOf('Emojis 👍🏽 are 🍆 poison. 🌮s are bad.', 'are', 10); // 26

ToArray

function toArray(str)
Param Type Default Description
str String none String to convert to array

Examples

toArray('👍🏽🍆🌮'); // ['👍🏽', '🍆', '🌮']

Test

$ npm test

Benchmark

This library scores high in a length benchmark (it's intended usage) and should be fast for most use case.

Stringz .length (accurate) x 861,039 ops/sec ±1.57% (84 runs sampled)
Lodash .toArray (accurate) x 795,108 ops/sec ±2.13% (82 runs sampled)
Emoji Aware .split (inaccurate) x 2,269 ops/sec ±1.38% (85 runs sampled)
Spliddit .length (inaccurate) x 487,718 ops/sec ±2.21% (83 runs sampled)
UTF8 Length (inaccurate) x 232,918 ops/sec ±1.02% (87 runs sampled)
Fastest is Stringz .length

To run benchmarks yourself:

$ cd ./benchmark
$ npm install
$ node run.js

Changelog

Moved to CHANGELOG.md

License

This software is released under the MIT License.