1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
# 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 | <code>String</code> | _none_ | The string to be limited |
| limit | <code>Number</code> | <code>16</code> | Desired string length |
| padStr | <code>String</code> | <code>"#"</code> | Character to pad the output with |
| padPosition | <code>String</code> | <code>"right"</code> | Pad position: <code>"right"</code> or <code>"left"</code> |
#### 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 | <code>String</code> | _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 | <code>String</code> | _none_ | String to be devided |
| start | <code>Number</code> | _none_ | Start position |
| end | <code>Number</code> | 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 | <code>String</code> | _none_ | String to be devided |
| start | <code>Number</code> | Start of string | Start position |
| length | <code>Number</code> | 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 | <code>String</code> | _none_ | String to get index |
| searchStr | <code>String</code> | _none_ | String to be searched |
| position | <code>Number</code> | 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 | <code>String</code> | _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/).
|
