Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@locustjs/extensions-string) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '|', '<', '>', '?', ':', '{', '}', '[', ']', ';', '"', "'", ',', '.', '/', '-', '=', '\\', '`'
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

`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"
]
*/

@locustjs/extensions-string

Package Exports

Readme

About

Install

Current version

Import

Usage

1. Direct call

2. As extension method on string instances

3. As static method on String

Classes

StringBuilder

Functions

replaceAll(str, find, replace)

reverse(str)

ltrim(str)

rtrim(str)

toArray(str)

fromArray(arr)

toBytes(str)

fromBytes(arr)

Character type checking

stringify(str, char = '"')

unString(str)

toggleCase(str) or changeCase(str)

pascalCase(str, replacer)

camelCase(str, replacer)

capitalize(str)

left(str, n)

right(str, n)

format(str, ...args)

nsplit(str, separators, callback?)

xsplit(str, separator, ...transforms)

2. As extension method on `string` instances

3. As static method on `String`

`StringBuilder`

`replaceAll(str, find, replace)`

`reverse(str)`

`ltrim(str)`

`rtrim(str)`

`toArray(str)`

`fromArray(arr)`

`toBytes(str)`

`fromBytes(arr)`

`stringify(str, char = '"')`

`unString(str)`

`toggleCase(str)` or `changeCase(str)`

`pascalCase(str, replacer)`

`camelCase(str, replacer)`

`capitalize(str)`

`left(str, n)`

`right(str, n)`

`format(str, ...args)`

`nsplit(str, separators, callback?)`

`xsplit(str, separator, ...transforms)`