Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sallar/stringz
:100: Super fast unicode-aware string manipulation Javascript library
https://github.com/sallar/stringz
javascript nodejs string-manipulation strings substr unicode utf-8
Last synced: 5 days ago
JSON representation
:100: Super fast unicode-aware string manipulation Javascript library
- Host: GitHub
- URL: https://github.com/sallar/stringz
- Owner: sallar
- License: mit
- Created: 2016-07-26T17:32:03.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-09-11T14:30:25.000Z (2 months ago)
- Last Synced: 2024-10-28T20:06:23.725Z (17 days ago)
- Topics: javascript, nodejs, string-manipulation, strings, substr, unicode, utf-8
- Language: TypeScript
- Homepage:
- Size: 1.03 MB
- Stars: 239
- Watchers: 5
- Forks: 13
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Stringz [](https://travis-ci.org/sallar/stringz) [](https://codecov.io/gh/sallar/stringz) [](https://www.npmjs.com/package/stringz)
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](https://mathiasbynens.be/notes/javascript-unicode).
## Features
* Unicode-aware string manipulation tools
* High performance
## Install
```bash
$ npm install stringz --save
```
And import it in your awesome node app:
```javascript
// ES2015+
import * as stringz from 'stringz'; // OR:
import { limit, substring, length, substr } from 'stringz';
```
```javascript
// CommonJS
const stringz = require('stringz'); // OR:
const { limit, substr } = require('stringz');
```
## Usage
* [`limit()`](#limit-string-to-width)
* [`length()`](#string-length)
* [`substring()`](#substring)
* [`substr()`](#substr)
* [`indexOf()`](#indexof)
* [`toArray()`](#toarray)
### 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
```javascript
// 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
```javascript
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
```javascript
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
```javascript
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
```javascript
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
```javascript
toArray('👍🏽🍆🌮'); // ['👍🏽', '🍆', '🌮']
```
## Test
```bash
$ 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:
```bash
$ cd ./benchmark
$ npm install
$ node run.js
```
## Changelog
[Moved to CHANGELOG.md](CHANGELOG.md)
## License
This software is released under the
[MIT License](http://sallar.mit-license.org/).