This repository is now archived. Just see if the browser now has native versions. If not checkout es-toolkit for maintained lib like this.

<span class="github-only">

The stable release documentation can be found here https://epeli.github.io/underscore.string/

</span>

Underscore.string

Javascript lacks complete string manipulation operations. This is an attempt to fill that gap. List of build-in methods can be found for example from [Dive Into JavaScript][d]. Originally started as an Underscore.js extension but is a full standalone library nowadays.

Upgrading from 2.x to 3.x? Please read the changelog.

Usage

For Node.js, Browserify and Webpack

Install from npm

npm install underscore.string

Require individual functions

var slugify = require("underscore.string/slugify");

slugify("Hello world!");
// => hello-world

or load the full library to enable chaining

var s = require("underscore.string");

s("   epeli  ").trim().capitalize().value();
// => "Epeli"

but especially when using with Browserify the individual function approach is recommended because using it you only add those functions to your bundle you use.

In Meteor

From your Meteor project folder

    meteor add underscorestring:underscore.string

and you'll be able to access the library with the s global from both the server and the client.

s.slugify("Hello world!");
// => hello-world

s("   epeli  ").trim().capitalize().value();
// => "Epeli"

Others

The dist/underscore.string.js file is an UMD build. You can load it using an AMD loader such as RequireJS or just stick it to a web page and access the library from the s global.

Underscore.js/Lo-Dash integration

It is still possible use as Underscore.js/Lo-Dash extension

_.mixin(s.exports());

But it's not recommended since include, contains, reverse and join are dropped because they collide with the functions already defined by Underscore.js.

Lo-Dash-FP/Ramda integration

If you want to use underscore.string with ramdajs or Lo-Dash-FP you can use underscore.string.fp.

npm install underscore.string.fp

var S = require('underscore.string.fp');
var filter = require('lodash-fp').filter;
var filter = require('ramda').filter;

filter(S.startsWith('.'), [
  '.vimrc',
  'foo.md',
  '.zshrc'
]);
// => ['.vimrc', '.zshrc']

Download

• Development version Uncompressed with Comments
• Production version Minified

API

Individual functions

numberFormat(number, [ decimals=0, decimalSeparator='.', orderSeparator=',']) => string

Formats the numbers.

numberFormat(1000, 2);
// => "1,000.00"

numberFormat(123456789.123, 5, ".", ",");
// => "123,456,789.12300"

levenshtein(string1, string2) => number

Calculates [Levenshtein distance][ld] between two strings. [ld]: http://en.wikipedia.org/wiki/Levenshtein_distance

levenshtein("kitten", "kittah");
// => 2

capitalize(string, [lowercaseRest=false]) => string

Converts first letter of the string to uppercase. If true is passed as second argument the rest of the string will be converted to lower case.

capitalize("foo Bar");
// => "Foo Bar"

capitalize("FOO Bar", true);
// => "Foo bar"

decapitalize(string) => string

Converts first letter of the string to lowercase.

decapitalize("Foo Bar");
// => "foo Bar"

chop(string, step) => array

chop("whitespace", 3);
// => ["whi", "tes", "pac", "e"]

clean(string) => string

Trim and replace multiple spaces with a single space.

clean(" foo    bar   ");
// => "foo bar"

cleanDiacritics(string) => string

Replace diacritic characters with closest ASCII equivalents. Check the source for supported characters. Pull requests welcome for missing characters!

cleanDiacritics("ääkkönen");
// => "aakkonen"

chars(string) => array

chars("Hello");
// => ["H", "e", "l", "l", "o"]

swapCase(string) => string

Returns a copy of the string in which all the case-based characters have had their case swapped.

swapCase("hELLO");
// => "Hello"

include(string, substring) => boolean

Tests if string contains a substring.

include("foobar", "ob");
// => true

count(string, substring) => number

Returns number of occurrences of substring in string.

count("Hello world", "l");
// => 3

escapeHTML(string) => string

Converts HTML special characters to their entity equivalents. This function supports cent, yen, euro, pound, lt, gt, copy, reg, quote, amp, apos.

escapeHTML("<div>Blah blah blah</div>");
// => "&lt;div&gt;Blah blah blah&lt;/div&gt;"

unescapeHTML(string) => string

Converts entity characters to HTML equivalents. This function supports cent, yen, euro, pound, lt, gt, copy, reg, quote, amp, apos, nbsp.

unescapeHTML("<div>Blah blah blah</div>");
// => "<div>Blah blah blah</div>"

insert(string, index, substring) => string

insert("Hellworld", 4, "o ");
// => "Hello world"

replaceAll(string, find, replace, [ignorecase=false]) => string

replaceAll("foo", "o", "a");
// => "faa"

isBlank(string) => boolean

isBlank(""); // => true
isBlank("\n"); // => true
isBlank(" "); // => true
isBlank("a"); // => false

join(separator, ...strings) => string

Joins strings together with given separator

join(" ", "foo", "bar");
// => "foo bar"

lines(str) => array

Split lines to an array

lines("Hello\nWorld");
// => ["Hello", "World"]

wrap(str, options) => string

Splits a line str (default '') into several lines of size options.width (default 75) using a options.seperator (default '\n'). If options.trailingSpaces is true, make each line at least width long using trailing spaces. If options.cut is true, create new lines in the middle of words. If options.preserveSpaces is true, preserve the space that should be there at the end of a line (only works if options.cut is false).

wrap("Hello World", { width:5 })
// => "Hello\nWorld"

wrap("Hello World", { width:6, seperator:'.', trailingSpaces: true })
// => "Hello .World "

wrap("Hello World", { width:5, seperator:'.', cut:true, trailingSpaces: true })
// => "Hello. Worl.d    "

wrap("Hello World", { width:5, seperator:'.', preserveSpaces: true })
// => "Hello .World"

dedent(str, [pattern]) => string

Dedent unnecessary indentation or dedent by a pattern.

Credits go to @sindresorhus. This implementation is similar to https://github.com/sindresorhus/strip-indent

dedent("  Hello\n    World");
// => "Hello\n  World"

dedent("\t\tHello\n\t\t\t\tWorld");
// => "Hello\n\t\tWorld"

dedent("    Hello\n    World", "  "); // Dedent by 2 spaces
// => "  Hello\n  World"

reverse(string) => string

Return reversed string:

reverse("foobar");
// => "raboof"

splice(string, index, howmany, substring) => string

Like an array splice.

splice("https://edtsech@bitbucket.org/edtsech/underscore.strings", 30, 7, "epeli");
// => "https://edtsech@bitbucket.org/epeli/underscore.strings"

startsWith(string, starts, [position]) => boolean

This method checks whether the string begins with starts at position (default: 0).

startsWith("image.gif", "image");
// => true

startsWith(".vimrc", "vim", 1);
// => true

endsWith(string, ends, [position]) => boolean

This method checks whether the string ends with ends at position (default: string.length).

endsWith("image.gif", "gif");
// => true

endsWith("image.old.gif", "old", 9);
// => true

pred(string) => string

Returns the predecessor to str.

pred("b");
// => "a"

pred("B");
// => "A"

succ(string) => string

Returns the successor to str.

succ("a");
// => "b"

succ("A");
// => "B"

titleize(string) => string

titleize("my name is epeli");
// => "My Name Is Epeli"

camelize(string, [decapitalize=false]) => string

Converts underscored or dasherized string to a camelized one. Begins with a lower case letter unless it starts with an underscore, dash or an upper case letter.

camelize("moz-transform");
// => "mozTransform"

camelize("-moz-transform");
// => "MozTransform"

camelize("_moz_transform");
// => "MozTransform"

camelize("Moz-transform");
// => "MozTransform"

camelize("-moz-transform", true);
// => "mozTransform"

classify(string) => string

Converts string to camelized class name. First letter is always upper case

classify("some_class_name");
// => "SomeClassName"

underscored(string) => string

Converts a camelized or dasherized string into an underscored one