string-unified

All you need to handle Unicode strings properly in JS.

This library builds on the power of grapheme-splitter to provide all essential functions for accurate Unicode string manipulations.

Installation

Node.js

npm i string-unified

Browsers

jsDelivr

https://cdn.jsdelivr.net/npm/string-unified@latest

Unpkg

https://unpkg.com/string-unified@latest/dist/index.js

And import string-unified like this

// ES2015+
import * as unified from "string-unified";
import { length, charAt, substring } from "string-unified";

// CommonJS
const unified = require("string-unified")
const { length, charAt, substring } = require("string-unified");

Usage

• length()
• charAt()
• substring()
• indexOf()
• lastIndexOf()
• includes()
• split()
• startsWith()
• endsWith()
• match()

All functions except match() are transpiled to ES5. See below for why match() requires ES2015+.

length

Get the length of a string.

function length(str)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to find length for|

Examples

length('abc') // 3

length('谢谢') // 2

length('अनुच्छेद') // 5

length('뎌쉐') // 2

length('Ĺo͂řȩm̅') // 5

length('Z͑ͫ̓ͪ̂ͫ̽͏̴̙̤̞͉͚̯̞̠͍A̴̵̜̰͔ͫ͗͢L̠ͨͧͩ͘G̴̻͈͍͔̹̑͗̎̅͛́Ǫ̵̹̻̝̳͂̌̌͘') // 5

length('🎅🔥🌘☀🛴👚') // 6

length('🏳️‍🌈') // 1

charAt

Get the character at an index.

function charAt(str, index)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to get char from| |index|number|none|index to get char|

Examples

charAt('helloあ', 5) // 'あ'

charAt('谢谢你😊', 10) // undefined

// negative indices also work!
// same as charAt('谢谢你😊', 3)
charAt('谢谢你😊', -1) // '😊'

substring

Get a substring of a string.

function substring(str, start?, end?)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to retrieve substring from| |start|number|0|start index of substring| |end|number|end of string|end index of substring|

Examples

substring('🥪🥗🍤🍜🍚', 3) // '🍜🍚'

substring('🥪🥗🍤🍜🍚', 2, 5) // '🍤🍜🍚'

// negative indices also work!
// same as substring('🥪🥗🍤🍜🍚', 2, 3)
substring('🥪🥗🍤🍜🍚', -3, -2) // '🍤'

indexOf

Get the index of the first occurence of a search string.

function indexOf(str, searchStr, start?, end?)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to search in| |searchStr|string|none|string to search for| |start|number|0|start index of the search| |end|number|end of string|end index of the search|

Examples

// get index of the *first* occurence
indexOf('🚗🚌🚑🚜🚒🚜', '🚜') // 3

// return undefined if not found
indexOf('🚗🚌🚑🚜🚒🚜', '🛴🛴🛴') // undefined

lastIndexOf

Get the index of the last occurence of a search string.

function lastIndexOf(str, searchStr, start?, end?)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to search in| |searchStr|string|none|string to search for| |start|number|0|start index of the search| |end|number|end of string|end index of the search|

Examples

// get index of the *last* occurence
lastIndexOf('🚗🚌🚑🚜🚒🚜', '🚜') // 5

// return undefined if not found
lastIndexOf('🚗🚌🚑🚜🚒🚜', '🛴🛴🛴') // undefined

includes

Test if a search string appears in a string.

function includes(str, searchStr, start?, end?)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to search in| |searchStr|string|none|string to search for| |start|number|0|start index of the search| |end|number|end of string|end index of the search|

Examples

includes('🎁🎄🎃🎉🧧', '🎃') // true

// same as includes('🎃🎉🧧', '🎁')
includes('🎁🎄🎃🎉🧧', '🎁', 2) // false

// same as includes('🎉', '🎉')
includes('🎁🎄🎃🎉🧧', '🎉', 3, 4) // true

// negative indices also work!
// same as includes('🎃🎉🧧', '🎁')
includes('🎁🎄🎃🎉🧧', '🎁', -3) // false

split

Split a string by a separator (can be a string or regex).

function split(str, separator?, limit?)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to split| |separator|string or RegExp|none|separator to split string| |limit|number|+Infinity|limit of the number of splits returned

Examples

split('👩🔹👨🔹🧑🔹👧🔹👦🔹🧒', '🔹') //  ['👩','👨','🧑','👧','👦','🧒'])
split('👩🔹👨🔹🧑🔹👧🔹👦🔹🧒', '🔹', 3) // ['👩','👨','🧑']

// limit can be larger than array size
split('👩🔹👨🔹🧑', '🔹', 6) // ['👩','👨','🧑']

// no separator returns a copy of the string inside an array
split('👩🔹👨🔹🧑🔹👧🔹👦🔹🧒') // ['👩🔹👨🔹🧑🔹👧🔹👦🔹🧒']

// if separator is an empty string '', split whole string into a character array
split('👩🔹👨🔹🧑🔹👧🔹👦🔹🧒', '') //  ['👩','🔹','👨','🔹','🧑','🔹','👧','🔹','👦','🔹','🧒'])

// If separator is a regular expression containing capturing parentheses (), matched results are included
split('Hello👋 1 word. Sentence #️⃣ 2.', /(\d)/)) // ["Hello👋 ", "1", " word. Sentence #️⃣ ", "2", "."]

startsWith

Test is a string starts with a search string.

function startsWith(str, searchStr, start?, end?)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to search in| |searchStr|string|none|string to search for| |start|number|0|start index of the search| |end|number|end of string|end index of the search|

Examples

startsWith('🎢🎪🎭🎡🎠', '🎢🎪') // true

// same as startsWith('🎪🎭🎡🎠', '🎢')
startsWith('🎢🎪🎭🎡🎠', '🎢', 1) // false

// same as startsWith('🎪🎭', '🎪')
startsWith('🎢🎪🎭🎡🎠', '🎪', 1, 3) // true

// negative indices also work!
// same as startsWith('🎡🎠', '🎡')
startsWith('🎢🎪🎭🎡🎠', '🎡', -2) // true

endsWith

Test is a string ends with a search string.

function endsWith(str, searchStr, start?, end?)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to search in| |searchStr|string|none|string to search for| |start|number|0|start index of the search |end|number|end of string|end index of the search|

Examples

endsWith('🎢🎪🎭🎡🎠', '🎠') // true

// same as endsWith('🎭🎡🎠', '🎠')
endsWith('🎢🎪🎭🎡🎠', '🎠', 2) // true

// negative indices also work!
// same as endsWith('🎪🎭', '🎭')
endsWith('🎢🎪🎭🎡🎠', '🎭', -4, 3) // true

match

Note that match() requires ES2015+ because of limited support of unicode regexp in lower versions and limitations of current source code transpilers like regexpu.

Test if a string matches a regular expression or another string.

function match(str, regexp)

|Param|Type|Default|Description| |-----|----|-------|-----------| |str |string|none|string to search in| |regexp|RegExp or string|none|Regular expression or string to search for|

Examples

// Test if a string matches a RegExp
// Without global flag
match('🐵🐶🐺🐱', /🐺/) // ['🐺', index: 2, input: '🐵🐶🐺🐱', groups: undefined]

match('🏳️‍🌈', /🌈/) // null

// Must add 'u' flag otherwise throw "Range out of order in character class"
match('💩', /[💩-💫]/u) // ['💩', index: 0, input: '💩', groups: undefined]

// all operators like '.' includes unicode characters
match('foo👋bar', /foo(.)bar/) // ['foo👋bar', '👋', index: 0, input: 'foo👋bar', groups: undefined)

// With global flag
match('🐵🐺🐶🐺🐱', /🐺/g) // ['🐺', '🐺']

match('🏁🏳️‍🌈🏴🏳️‍🌈⛳🚩🏳️‍🌈🎌', /🏳️‍🌈[⛳🎌]/g) // ['🏳️‍🌈⛳', '🏳️‍🌈🎌']

// Test if a string matches another string
match('🏁🏳️‍🌈🏴🏳️‍🌈⛳🚩', '🏳️‍🌈') // ['🏳️‍🌈', index: 1, input: '🏁🏳️‍🌈🏴🏳️‍🌈⛳🚩', groups: undefined];

// Special case when regexp is undefined
match('Nothing will not match anything.', undefined) // null