string

String utilities.

Table of Contents #

camelCase(str):String #

Convert string to "camelCase" text.

See: pascalCase(), unCamelCase()

Example


camelCase('lorem-ipsum-dolor'); // "loremIpsumDolor"
camelCase('lorem ipsum dolor'); // "loremIpsumDolor"

contains(str, substring, [fromIndex]):Boolean #

Checks if string contains the given substring.

See: startsWith(), endsWith()

Example


contains('lorem', 'or');  // true
contains('lorem', 'bar'); // false

crop(str, maxChars, [append]):String #

Truncate string at full words. Alias to truncate(str, maxChars, append, true);.

See: truncate()

Example


crop('lorem ipsum dolor', 10);      // "lorem..."
crop('lorem ipsum dolor', 10, '+'); // "lorem+"

endsWith(str, suffix):Boolean #

Checks if string ends with specified suffix.

See: startsWith(), contains()

Example


endsWith('lorem ipsum', 'lorem'); // false
endsWith('lorem ipsum', 'ipsum'); // true

escapeHtml(str):String #

Escapes the following special characters for use in HTML:

No other characters are escaped. To HTML-escape other characters as well, use a third-party library like he.

See: unescapeHtml()

Example


escapeHtml('lorem & "ipsum"'); // "lorem & "ipsum""

escapeRegExp(str):String #

Escape special chars to be used as literals in RegExp constructors.

Example


str = escapeRegExp('[lorem.ipsum]'); // "\\[lorem\\.ipsum\\]"
reg = new RegExp(str);               // /\[lorem\.ipsum\]/

escapeUnicode(str[, shouldEscapePrintable]):String #

Unicode escape chars.

It will only escape non-printable ASCII chars unless shouldEscapePrintable is set to true.

See: unescapeUnicode()


escapeUnicode('føo bår');
// > "f\u00f8o b\u00e5r"
escapeUnicode('føo bår', true);
// > "\u0066\u00f8\u006f\u0020\u0062\u00e5\u0072"

hyphenate(str):String #

Replaces spaces with hyphens, split camelCase text, remove non-word chars, remove accents and convert to lower case.

See: slugify(), underscore(), unhyphenate


hyphenate(' %# lorem ipsum  ? $  dolor'); // "lorem-ipsum-dolor"
hyphenate('spéçïãl çhârs');               // "special-chars"
hyphenate('loremIpsum');                  // "lorem-ipsum"

insert(str, index, partial):String #

Inserts a partial before the given index in the provided str. If the index is larger than the length of the string the partial is appended at the end. A negative index is treated as length - index where length is the length or the string.


insert('this is a sentence', 10, 'sample '); // "this is a sample sentence"
insert('foo', 100, 'bar'); // "foobar"
insert('image.png', -4, '-large'); // "image-large.png"

interpolate(str, replacements[, syntax]):String #

String interpolation. Format/replace tokens with object properties.


var tmpl = 'Hello {{name}}!';
interpolate(tmpl, {name: 'World'});       // "Hello World!"
interpolate(tmpl, {name: 'Lorem Ipsum'}); // "Hello Lorem Ipsum!"

tmpl = 'Hello {{name.first}}!';
interpolate(tmpl, {name: {first: 'Lorem'}}); // "Hello Lorem!"

It uses a mustache-like syntax by default but you can set your own format if needed. You can also use Arrays for the replacements (since Arrays are objects as well):


// matches everything inside "${}"
var syntax = /\$\{([^}]+)\}/g;
var tmpl = "Hello ${0}!";
interpolate(tmpl, ['Foo Bar'], syntax); // "Hello Foo Bar!"

lowerCase(str):String #

"Safer" String.toLowerCase(). (Used internally)

Example


(null).toLowerCase();      // Error!
(undefined).toLowerCase(); // Error!
lowerCase(null);           // ""
lowerCase(undefined);      // ""

lpad(str, minLength[, char]):String #

Pad string from left with char if its' length is smaller than minLen.

See: rpad()

Example


lpad('a', 5);        // "    a"
lpad('a', 5, '-');   // "----a"
lpad('abc', 3, '-'); // "abc"
lpad('abc', 4, '-'); // "-abc"

ltrim(str, [chars]):String #

Remove chars or white-spaces from beginning of string.

chars is an array of chars to remove from the beginning of the string. If chars is not specified, Unicode whitespace chars will be used instead.

See: rtrim(), trim()

Example


ltrim('   lorem ipsum   ');      // "lorem ipsum   "
ltrim('--lorem ipsum--', ['-']); // "lorem ipsum--"

makePath(...args):String #

Group arguments as path segments, if any of the args is null or undefined it will be ignored from resulting path. It will also remove duplicate "/".

See: array/join()

Example


makePath('lorem', 'ipsum', null, 'dolor'); // "lorem/ipsum/dolor"
makePath('foo///bar/');                    // "foo/bar/"

normalizeLineBreaks(str, [lineBreak]):String #

Normalize line breaks to a single format. Defaults to Unix \n.

It handles DOS (\r\n), Mac (\r) and Unix (\n) formats.

Example


// "foo\nbar\nlorem\nipsum"
normalizeLineBreaks('foo\nbar\r\nlorem\ripsum');

// "foo\rbar\rlorem\ripsum"
normalizeLineBreaks('foo\nbar\r\nlorem\ripsum', '\r');

// "foo bar lorem ipsum"
normalizeLineBreaks('foo\nbar\r\nlorem\ripsum', ' ');

pascalCase(str):String #

Convert string to "PascalCase" text.

See: camelCase()

Example


pascalCase('lorem-ipsum-dolor'); // "LoremIpsumDolor"
pascalCase('lorem ipsum dolor'); // "LoremIpsumDolor"

properCase(str):String #

UPPERCASE first char of each word, lowercase other chars.

Example


properCase('loRem iPSum'); // "Lorem Ipsum"

removeNonASCII(str):String #

Remove non-printable ASCII chars.

Example


removeNonASCII('äÄçÇéÉêlorem-ipsumöÖÐþúÚ'); // "lorem-ipsum"

removeNonWord(str):String #

Remove non-word chars.

Example


var str = 'lorem ~!@#$%^&*()_+`-={}[]|\\:";\'/?><., ipsum';
removeNonWord(str); // "lorem - ipsum"

repeat(str, n):String #

Repeat string n-times.

Example


repeat('a', 3);  // "aaa"
repeat('bc', 2); // "bcbc"
repeat('a', 0);  // ""

replace(str, search, replacements):String #

Replace string(s) with the replacement(s) in the source.

search and replacements can be an array, or a single item. For every item in search, it will call str.replace with the search item and the matching replacement in replacements. If replacements only contains one replacement, it will be used for all the searches, otherwise it will use the replacement at the same index as the search.

Example


replace('foo bar', 'foo', 'test');                // "test bar"
replace('test 1 2', ['1', '2'], 'n');             // "test n n"
replace('test 1 2', ['1', '2'], ['one', 'two']);  // "test one two"
replace('123abc', [/\d/g, /[a-z]/g], ['0', '.']); // "000..."

replaceAccents(str):String #

Replaces all accented chars with regular ones.

Important: Only covers Basic Latin and Latin-1 unicode chars.

Example


replaceAccents('spéçïãl çhârs'); // "special chars"

rpad(str, minLength[, char]):String #

Pad string from right with char if its' length is smaller than minLen.

See: lpad()

Example


rpad('a', 5);        // "a    "
rpad('a', 5, '-');   // "a----"
rpad('abc', 3, '-'); // "abc"
rpad('abc', 4, '-'); // "abc-"

rtrim(str, [chars]):String #

Remove chars or white-spaces from end of string.

chars is an array of chars to remove from the end of the string. If chars is not specified, Unicode whitespace chars will be used instead.

See: trim(), ltrim()

Example


rtrim('   lorem ipsum   ');      // "   lorem ipsum"
rtrim('--lorem ipsum--', ['-']); // "--lorem ipsum"

sentenceCase(str):String #

UPPERCASE first char of each sentence and lowercase other chars.

Example


var str = 'Lorem IpSum DoLOr. maeCeNnas Ullamcor.';
sentenceCase(str); // "Lorem ipsum dolor. Maecennas ullamcor."

stripHtmlTags(str):String #

Remove HTML/XML tags from string.

Example


var str = '

lorem ipsum

'; stripHtmlTags(str); // "lorem ipsum"

startsWith(str, prefix):Boolean #

Checks if string starts with specified prefix.

See: endsWith(), contains()

Example


startsWith('lorem ipsum', 'lorem'); // true
startsWith('lorem ipsum', 'ipsum'); // false

slugify(str[, delimeter]):String #

Convert to lower case, remove accents, remove non-word chars and replace spaces with the delimeter. The default delimeter is a hyphen.

Note that this does not split camelCase text.

See: hyphenate() and underscore()

Example


var str = 'loremIpsum dolor spéçïãl chârs';
slugify(str); // "loremipsum-dolor-special-chars"
slugify(str, '_'); // "loremipsum_dolor_special_chars"

trim(str, [chars]):String #

Remove chars or white-spaces from beginning and end of string.

chars is an array of chars to remove from the beginning and end of the string. If chars is not specified, Unicode whitespace chars will be used instead.

See: rtrim(), ltrim()

Example


trim('   lorem ipsum   ');             // "lorem ipsum"
trim('-+-lorem ipsum-+-', ['-', '+']); // "lorem ipsum"

truncate(str, maxChars, [append], [onlyFullWords]):String #

Limit number of chars. Returned string length will be <= maxChars.

See: crop()

Arguments

  1. str (String) : String
  2. maxChars (Number) : Maximum number of characters including append.length.
  3. [append] (String) : Value that should be added to the end of string. Defaults to "...".
  4. [onlyFullWords] (Boolean) : If it shouldn't break words. Default is false. (favor crop() since code will be clearer).

Example


truncate('lorem ipsum dolor', 11);             // "lorem ip..."
truncate('lorem ipsum dolor', 11, '+');        // "lorem ipsu+"
truncate('lorem ipsum dolor', 11, null, true); // "lorem..."

typecast(str):* #

Parses string and convert it into a native value.

Example


typecast('lorem ipsum'); // "lorem ipsum"
typecast('123');         // 123
typecast('123.45');      // 123.45
typecast('false');       // false
typecast('true');        // true
typecast('null');        // null
typecast('undefined');   // undefined

unCamelCase(str, [delimiter]):String #

Add the delimiter between camelCase text and convert first char of each word to lower case.

The delimiter defaults to a space character.

See: [camelCase()][#camelCase]

Example


unCamelCase('loremIpsumDolor'); // "lorem ipsum dolor"
unCamelCase('loremIpsumDolor', '-'); // "lorem-ipsum-color"

underscore(str):String #

Replaces spaces with underscores, split camelCase text, remove non-word chars, remove accents and convert to lower case.

See: slugify(), hyphenate()


underscore(' %# lorem ipsum  ? $  dolor'); // "lorem_ipsum_dolor"
underscore('spéçïãl çhârs');               // "special_chars"
underscore('loremIpsum');                  // "lorem_ipsum"

unescapeHtml(str):String #

Unescapes the following HTML character references back into the raw symbol they map to:

No other HTML character references are unescaped. To HTML-unescape other entities as well, use a third-party library like he.

See: escapeHtml()

Example


unescapeHtml('lorem &amp; &quot;ipsum&quot;'); // 'lorem & "ipsum"'

unescapeUnicode(str):String #

Unescapes unicode char sequences.

See: escapeUnicode()


unescapeUnicode('\\u0066\\u00f8\\u006f\\u0020\\u0062\\u00e5\\u0072');
// > 'føo bår'

unhyphenate(str):String #

Replaces hyphens with spaces. (only hyphens between word chars)

See : hyphenate()

Example


unhyphenate('lorem-ipsum-dolor'); // "lorem ipsum dolor"

upperCase(str):String #

"Safer" String.toUpperCase(). (Used internally)

Example


(null).toUpperCase();      // Error!
(undefined).toUpperCase(); // Error!
upperCase(null);           // ""
upperCase(undefined);      // ""

WHITE_SPACES:Array #

Constant array of all Unicode white-space characters.


For more usage examples check specs inside /tests folder. Unit tests are the best documentation you can get...


Documentation generated by mdoc.