@locustjs/extensions-string

About

This library contains extensions for string.

Install

npm i @locustjs/extensions-string

Current version

2.0.7

Import

CommonJs

var someFn = require("@locustjs/extensions-string").someFn;

ES6

import { someFn } from "@locustjs/extensions-string";

Usage

string extension methods can be used in three ways.

1. Direct call

import { replaceAll } from "@locustjs/extensions-string";

const str = "Hello";

console.log(replaceAll(str, "l", "$")); // He$o

Pros

• Works on undefined variables as well.

Cons

• Requires import

2. As extension method on string instances

First, we need to configure the extension method using configureStringExtensions() function. This has to be performed only once, like at the start point of the app. Then, we can freely call the extension on any string literal or variable.

// app startup
configureStringExtensions("replaceAll,format");

...

let str = "Hello";

console.log(str.replaceAll("l", "$")); // He$o

str = "Hello {0}";

console.log(str.format("ali")); // Hello ali

Pros

• Does not require import
• More readable code

Cons

• Does not work on undefined variables

3. As static method on String

const str = "Hello";

console.log(String.replaceAll(str, "l", "$")); // He$o

Pros

• Works on undefined variables as well.
• Does not require import

Cons

• More characters to type
• Less readable

Classes

StringBuilder

A helper class to concatenate strings more efficiently. It uses an internal array, places given strings inside the array, extends array size if needed, joins the array upon calling toString method and resets the array.

Method/Prop	Description
append(x: any):int	appends x to the internal buffer and returns index of new appended item in the internal buffer
appendAt(index, x: any)	adds x at index position in the internal buffer
removeAt(index, count = 1)	removes count items from index from the internal buffer
replaceAt(index, item)	replaces item at index position in the internal buffer with item
itemAt(index)	returns item at index position in the internal buffer
clear()	clears/resets internal buffer
toString()	joins and returns buffered items as a single string value and then resets internal buffer
getString(from?, to?)	joins buffered items starting at from index (inclusive, default = 0), ending at to index (exclusive, default = count) and returns a string value, but does not reset internal buffer
toLower(from?, to?)	changes items starting at from index (inclusive, default = 0), ending at to index (exclusive, default = count) to lowercase. It does not reset internal buffer
toUpper(from?, to?)	changes items starting at from index (inclusive, default = 0), ending at to index (exclusive, default = count) to uppercase. It does not reset internal buffer
trim(from?, to?)	trims items starting at from index (inclusive, default = 0), ending at to index (exclusive, default = count). It does not reset internal buffer
length	returns total length of buffered content
count	returns number of appended items in the buffer

Example 1: basic

const sb = new StringBuilder();

sb.append("Hello");
sb.append(" World");
sb.append("\n");
sb.append("Goodbye");

console.log(sb.toString());
/* output:
Hello World
Goodbye
*/

We can specify buffer size (length of the temporal array that holds appended items) in the constructor of StringBuilder. Default value is 32.

Example 2: bufferSize

const sb = new StringBuilder(10);

sb.append("Hello");
sb.append(" World");
sb.append("\n");
sb.append("Goodbye");

console.log(sb.toString());
/* output:
Hello World
Goodbye
*/

StringBuilder.append returns index of current appended item in the internal buffer. Using this index and StringBuilder.remove(), we can later remove items from buffer.

Example 3: appendAt()

const sb = new StringBuilder(100);

sb.append("a1");
sb.append("a2");
sb.append("a3");

sb.appendAt(1, "a4");

console.log(sb.toString()); // a1a4a2a3

Example 4: removeAt()

const sb = new StringBuilder(100);

sb.append("a1");
sb.append("a2");
sb.append("a3");
sb.append("a4");
sb.append("a5");

sb.removeAt(1, 2);

console.log(sb.toString()); // a1a4a5

Example 5: replaceAt()

const sb = new StringBuilder(100);

sb.append("a1");
sb.append("a2");
sb.append("a3");

sb.replaceAt(1, "a5");

console.log(sb.toString()); // a1a5a3

Example 6: getString()

const sb = new StringBuilder(100);

sb.append("a1");
sb.append("a2");
sb.append("a3");
sb.append("a4");
sb.append("a5");

console.log(sb.getString()); // a1a2a3a4a5
console.log(sb.getString(2)); // a3a4a5
console.log(sb.getString(1, 4)); // a2a3a4
console.log(sb.getString(4, 1)); // a4a3a2
console.log(sb.getString()); // a1a2a3a4a5

Functions

replaceAll(str, find, replace)

Replaces find with replace in str string.

let str = "to be or not to be";

// usage 1: direct call
console.log(replaceAll(str, "to", "2"));
// usage 2: as an extension method
console.log(str.replaceAll("to", "2"));
// usage 3: as static method
console.log(String.replaceAll(str, "to", "2"));

/* output:
2 be or not 2 be
*/

reverse(str)

Reverses str string.

let str = "Hello World";

// usage 1: direct call
console.log(reverse(str));
// usage 2: as an extension method
console.log(str.reverse());
// usage 3: as static method
console.log(String.reverse(str));

/* output:
dlroW olleH
*/

ltrim(str)

Removes white-space character from left-side of str string.

let str = "  Hello  ";

// usage 1: direct call
console.log(`"${ltrim(str)}"`);
// usage 2: as an extension method
console.log(`"${str.ltrim()}"`);
// usage 3: as static method
console.log(`"${String.ltrim(str)}"`);

/* output:
"Hello  "
*/

rtrim(str)

Removes white-space character from right-side of str string.

let str = "  Hello  ";

// usage 1: direct call
console.log(`"${rtrim(str)}"`);
// usage 2: as an extension method
console.log(`"${str.rtrim()}"`);
// usage 3: as static method
console.log(`"${String.rtrim(str)}"`);

/* output:
"  Hello"
*/

toArray(str)

Converts str string into an array of ascii-codes.

let str = "Hello";

// usage 1: direct call
console.log(toArray(str));
// usage 2: as an extension method
console.log(str.toArray());
// usage 3: as static method
console.log(String.toArray(str));

/* output:
[72, 101, 108, 108, 111]
*/

str = "علی";

// usage 1: direct call
console.log(toArray(str));
// usage 2: as an extension method
console.log(str.toArray());
// usage 3: as static method
console.log(String.toArray(str));

/* output:
[1593, 1604, 1740]
*/

fromArray(arr)

Converts arr array into a string.

let arr = [72, 101, 108, 108, 111];

// usage 1: direct call
console.log(fromArray(arr));
// usage 3: as static method
console.log(String.fromArray(arr));

/* output:
Hello
*/

toBytes(str)

Converts str string into an array of unsigned bytes.

let str = "سلام";

// usage 1: direct call
console.log(toBytes(str));
// usage 2: as an extension method
console.log(str.toBytes());
// usage 3: as static method
console.log(String.toBytes(str));

/* output:
[216, 185, 217, 132, 219, 140]
*/

fromBytes(arr)

Converts arr byte-array into a string.

let arr = new Uint8Array([216, 185, 217, 132, 219, 140]);

// usage 1: direct call
console.log(fromBytes(arr));
// usage 3: as static method
console.log(String.fromBytes(arr));

/* output:
علی
*/

Character type checking

// checks if input is only one character
console.log(String.isCharacter("a")); // true
console.log(String.isCharacter("ab")); // false

// punctuation letters: '.', ',', ';', ':', '?', '!', '(', ')', '-', "'", '"', '/', '\\', '{', '}', '[', ']', '%', '#'
console.log(String.isPunctuation(".")); // true
console.log(String.isPunctuation("+")); // false

// control characters: '~', '!', '@', '#', '
stringify(str, char = '"')
Adds string characters to both sides of str string.
let str = "Hello";

// usage 1: direct call
console.log(stringify(str)); // "Hello"
console.log(stringify(str, "'")); // 'Hello'
// usage 2: as an extension method
console.log(str.stringify()); // "Hello"
console.log(str.stringify("'")); // 'Hello'
// usage 3: as static method
console.log(String.stringify(str)); // "Hello"
console.log(String.stringify(str, "'")); // 'Hello'
unString(str)
Removes string characters from either side(s) of str string.
let str = '"Hello"';

// usage 1: direct call
console.log(unString(str));
// usage 2: as an extension method
console.log(str.unString());
// usage 3: as static method
console.log(String.unString(str));

/* output:
Hello
*/
toggleCase(str) or changeCase(str)
Changes alphabetic cases of alphabet characters in str string.
let str = "Google Play";

// usage 1: direct call
console.log(changeCase(str));
// usage 2: as an extension method
console.log(str.changeCase());
// usage 3: as static method
console.log(String.changeCase(str));

/* output:
gOOGLE pLAY
*/
pascalCase(str, replacer)
Turns first letters of words into uppercase in str string and removes other none-alphabetic characters.
Example 1:
let str = "an introduction to javascript";

// usage 1: direct call
console.log(pascalCase(str));
// usage 2: as an extension method
console.log(str.pascalCase());
// usage 3: as static method
console.log(String.pascalCase(str));

/* output:
AnIntroductionToJavascript
*/
It is also possible to prevent removal of non-alpha characters.
Example 2:
let str = "an introduction to javascript";

// usage 1: direct call
console.log(pascalCase(str, false));
// usage 2: as an extension method
console.log(str.pascalCase(false));
// usage 3: as static method
console.log(String.pascalCase(str, false));

/* output:
An Introduction To Javascript
*/
Using the second parameter, we can specify a replacer to be used to replace non-alpha characters.
Example 3:
let str = "an introduction to javascript";

// usage 1: direct call
console.log(pascalCase(str, '-'));
// usage 2: as an extension method
console.log(str.pascalCase('-'));
// usage 3: as static method
console.log(String.pascalCase(str, '-'));

/* output:
An-Introduction-To-Javascript
*/
camelCase(str, replacer)
Turns first letters of words into uppercase in str string except first word and removes other none-alphabetic characters.
let str = "an introduction to javascript";

// usage 1: direct call
console.log(camelCase(str));
// usage 2: as an extension method
console.log(str.camelCase());
// usage 3: as static method
console.log(String.camelCase(str));

/* output:
anIntroductionToJavascript
*/
Example 2:
let str = "an introduction to javascript";

// usage 1: direct call
console.log(camelCase(str, false));
// usage 2: as an extension method
console.log(str.camelCase(false));
// usage 3: as static method
console.log(String.camelCase(str, false));

/* output:
an Introduction To Javascript
*/
Example 3:
let str = "an introduction to javascript";

// usage 1: direct call
console.log(camelCase(str, '-'));
// usage 2: as an extension method
console.log(str.camelCase('-'));
// usage 3: as static method
console.log(String.camelCase(str, '-'));

/* output:
an-Introduction-To-Javascript
*/
capitalize(str)
Turns first letters of words into uppercase in str string.
let str = "to be or not to be";

// usage 1: direct call
console.log(capitalize(str));
// usage 2: as an extension method
console.log(str.capitalize());
// usage 3: as static method
console.log(String.capitalize(str));

/* output:
To Be Or Not To Be
*/
left(str, n)
Returns n characters from left-side of str.
let str = "abcdefgh";

// usage 1: direct call
console.log(left(str, 3));
// usage 2: as an extension method
console.log(str.left(3));
// usage 3: as static method
console.log(String.left(str, 3));

/* output:
abc
*/
right(str, n)
Returns n characters from right-side of str.
let str = "abcdefgh";

// usage 1: direct call
console.log(right(str, 3));
// usage 2: as an extension method
console.log(str.right(3));
// usage 3: as static method
console.log(String.right(str, 3));

/* output:
fgh
*/
format(str, ...args)
Formats given str based on given args arguments.
Example 1:
const pattern = "My name is {0}; I am {1} years old.";

// usage 1: direct call
console.log(format(pattern, "John", 23));
// usage 2: as an extension method
console.log(pattern.format("John", 23));
// usage 3: as static method
console.log(String.format(pattern, "John", 23));

/* output:
My name is John; I am 23 years old.
*/
Example 2:
const pattern = "My name is {name}; I am {age} years old.";
const arg = { name: "John", age: 23 };
// usage 1: direct call
console.log(format(pattern, arg));
// usage 2: as an extension method
console.log(pattern.format(arg));
// usage 3: as static method
console.log(String.format(pattern, arg));

/* output:
My name is John; I am 23 years old.
*/
Example 3:
const pattern = `{{ and }} characters are used for escaping.
example: format("hello {{name}}", {{ name: '{name}' }})
result: hello {name}
`;
const arg = { name: "John" };
// usage 1: direct call
console.log(format(pattern, arg));
// usage 2: as an extension method
console.log(pattern.format(arg));
// usage 3: as static method
console.log(String.format(pattern, arg));

/* output:
{ and } characters are used for escaping.
example: format("hello {name}", { name: 'John' })
result: hello John
*/
nsplit(str, separators, callback?)
splits str based on given array of separators, calls callback function on each segment (if callback is specified).
Callback signature:
callback({
    input: str,
    value: current part,
    index: part index,
    level: number,
    separator: current separator
})
If callback returns antyhing, nsplit uses that instead of passed segment.
Example 1:
const str = "a=10&b=john";

// usage 1: direct call
console.log(nsplit(str, ["&", "="]));
// usage 2: as an extension method
console.log(str.nsplit(["&", "="]));
// usage 3: as static method
console.log(String.nsplit(str, ["&", "="]));

/* output:
[
    ['a', '10'],
    ['b', 'john']
]
*/
Example 2:
const str = "name=ali%20reza&age=23";
const result = nsplit(str, ['&', '='], ({ level, value }) => level == 1 ? decodeURI(value): value);

console.log(result);

/* output:
[
    ['name', 'ali reza'],
    ['age', '23']
]
*/
xsplit(str, separator, ...transforms)
nsplit str string based on given separator, iterates over the segments and and transforms them based on requested transformations..
Possible transforms:

trim or t
ltrim or lt
rtrim or rt
upper or u or up
lower or l or low
camel or c or cam
pascal or p or pas
changecase or cc
capitalize or c
stringify or s
reverse or r or rev
unstring or un
htmlencode or he
htmldecode or hd
urlencode or ue
urldecode or ud
free or f

const str = "   London, tehran  ,  ,, toKYO,,  istanbuL,";

// we want to remove empty strings, trim, lowercase and captalize items
// usage 1: direct call
console.log(xsplit(str, ",", "free","trim","lower","capitalize"));
console.log(xsplit(str, ",", "free,trim,lower,capitalize"));

// usage 2: as an extension method
console.log(str.xsplit(",", "f","t","l","cap"));  // same result
console.log(str.xsplit(",", "f,t,l,cap"));  // same result

// usage 3: as static method
console.log(String.xsplit(str, ",", "f,t,l,cap"));

/* output:
[
    "London",
    "Tehran",
    "Tokyo",
    "Istanbul"
]
*/
, '%', '^', '&', '*', '(', ')', '_', '+', '|', '<', '>', '?', ':', '{', '}', '[', ']', ';', '"', "'", ',', '.', '/', '-', '=', '\\', '`'
console.log(String.isControl("!")); // true
console.log(String.isControl("a")); // false

// checks if input is an alphabet character, upper or lower.
console.log(String.isAlpha("a")); // true
console.log(String.isAlpha("2")); // false

// isLetter() is the same as isAlpha()
console.log(String.isLetter("a")); // true
console.log(String.isLetter("2")); // false

// checks if input is a lower alphabet character
console.log(String.isLower("a")); // true
console.log(String.isLower("A")); // false

// checks if input is an upper alphabet character
console.log(String.isUpper("A")); // true
console.log(String.isUpper("a")); // false

// checks if input is a digit number 0-9
console.log(String.isDigit("2")); // true
console.log(String.isDigit("a")); // false

// checks if input is an alphabet or digit character
console.log(String.isAlphaNum("a")); // true
console.log(String.isAlphaNum("2")); // true
console.log(String.isAlphaNum("/")); // false

// checks if input is a word string that contains only alphabet, digit or underscore
console.log(String.isWord("abc")); // true
console.log(String.isWord("123")); // true
console.log(String.isWord("a2")); // true
console.log(String.isWord("a b")); // false
console.log(String.isWord("a1 ")); // false

// checks if input is an arithmatic operator: '/', '\\', '+', '-', '(', ')', '%', '^', '*', '++', '--'
console.log(String.isArithmatic("+")); // true
console.log(String.isArithmatic("&")); // false

// checks if input is a logical operator: '&&', '||', '!'
console.log(String.isLogic("&&")); // true
console.log(String.isLogic("&")); // false

// checks if input is a bitwise operator: '&', '|', '>>', '<<'
console.log(String.isBitwise("&")); // true
console.log(String.isBitwise("+")); // false

// checks if input is a comparison operator: '==', '!=', '<>', '>', '<', '>=', '<=', '===', '!=='
console.log(String.isComparison(">")); // true
console.log(String.isComparison("!")); // false

// checks if input is a whitespace character or string
console.log(String.isWhitespace(" ")); // true
console.log(String.isWhitespace("    ")); // true
console.log(String.isWhitespace("\n")); // true
console.log(String.isWhitespace("   \n")); // true
console.log(String.isWhitespace("\t")); // true
console.log(String.isWhitespace("=")); // false

// checks if input is an arithmatic, logical, bitwise or comparison character sequence
console.log(String.isMath("+")); // true
console.log(String.isMath("&")); // true
console.log(String.isMath("&&")); // true
console.log(String.isMath(">")); // true
console.log(String.isMath("<=")); // true
console.log(String.isMath("!")); // true
console.log(String.isMath("/")); // true
console.log(String.isMath("||")); // true
console.log(String.isMath("|")); // false

__INLINE_CODE_64__

Adds string characters to both sides of __INLINE_CODE_65__ string.

__CODE_BLOCK_22__

__INLINE_CODE_66__

Removes string characters from either side(s) of __INLINE_CODE_67__ string.

__CODE_BLOCK_23__

__INLINE_CODE_68__ or __INLINE_CODE_69__

Changes alphabetic cases of alphabet characters in __INLINE_CODE_70__ string.

__CODE_BLOCK_24__

__INLINE_CODE_71__

Turns first letters of words into uppercase in __INLINE_CODE_72__ string and removes other none-alphabetic characters.

Example 1:

__CODE_BLOCK_25__

It is also possible to prevent removal of non-alpha characters.

Example 2:

__CODE_BLOCK_26__

Using the second parameter, we can specify a __INLINE_CODE_73__ to be used to replace non-alpha characters.

Example 3:

__CODE_BLOCK_27__

__INLINE_CODE_74__

Turns first letters of words into uppercase in __INLINE_CODE_75__ string except first word and removes other none-alphabetic characters.

__CODE_BLOCK_28__

Example 2:

__CODE_BLOCK_29__

Example 3:

__CODE_BLOCK_30__

__INLINE_CODE_76__

Turns first letters of words into uppercase in __INLINE_CODE_77__ string.

__CODE_BLOCK_31__

__INLINE_CODE_78__

Returns __INLINE_CODE_79__ characters from left-side of __INLINE_CODE_80__.

__CODE_BLOCK_32__

__INLINE_CODE_81__

Returns __INLINE_CODE_82__ characters from right-side of __INLINE_CODE_83__.

__CODE_BLOCK_33__

__INLINE_CODE_84__

Formats given __INLINE_CODE_85__ based on given __INLINE_CODE_86__ arguments.

Example 1:

__CODE_BLOCK_34__

Example 2:

__CODE_BLOCK_35__

Example 3:

__CODE_BLOCK_36__

__INLINE_CODE_87__

splits __INLINE_CODE_88__ based on given array of separators, calls __INLINE_CODE_89__ function on each segment (if __INLINE_CODE_90__ is specified).

Callback signature:

__CODE_BLOCK_37__

If __INLINE_CODE_91__ returns antyhing, __INLINE_CODE_92__ uses that instead of passed segment.

Example 1:

__CODE_BLOCK_38__

Example 2:

__CODE_BLOCK_39__

__INLINE_CODE_93__

nsplit __INLINE_CODE_94__ string based on given __INLINE_CODE_95__, iterates over the segments and and transforms them based on requested transformations..

Possible __INLINE_CODE_96__:

• __INLINE_CODE_97__ or __INLINE_CODE_98__
• __INLINE_CODE_99__ or __INLINE_CODE_100__
• __INLINE_CODE_101__ or __INLINE_CODE_102__
• __INLINE_CODE_103__ or __INLINE_CODE_104__ or __INLINE_CODE_105__
• __INLINE_CODE_106__ or __INLINE_CODE_107__ or __INLINE_CODE_108__
• __INLINE_CODE_109__ or __INLINE_CODE_110__ or __INLINE_CODE_111__
• __INLINE_CODE_112__ or __INLINE_CODE_113__ or __INLINE_CODE_114__
• __INLINE_CODE_115__ or __INLINE_CODE_116__
• __INLINE_CODE_117__ or __INLINE_CODE_118__
• __INLINE_CODE_119__ or __INLINE_CODE_120__
• __INLINE_CODE_121__ or __INLINE_CODE_122__ or __INLINE_CODE_123__
• __INLINE_CODE_124__ or __INLINE_CODE_125__
• __INLINE_CODE_126__ or __INLINE_CODE_127__
• __INLINE_CODE_128__ or __INLINE_CODE_129__
• __INLINE_CODE_130__ or __INLINE_CODE_131__
• __INLINE_CODE_132__ or __INLINE_CODE_133__
• __INLINE_CODE_134__ or __INLINE_CODE_135__

__CODE_BLOCK_40__