833 lines
19 KiB
Markdown
833 lines
19 KiB
Markdown
![]() |
<span class="github-only">
|
|||
|
|
|||
|
The stable release documentation can be found here https://epeli.github.io/underscore.string/
|
|||
|
|
|||
|
</span>
|
|||
|
|
|||
|
# Underscore.string [![Build Status](https://secure.travis-ci.org/epeli/underscore.string.png?branch=master)](http://travis-ci.org/epeli/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][c].
|
|||
|
|
|||
|
[c]: https://github.com/epeli/underscore.string/blob/master/CHANGELOG.markdown#300
|
|||
|
|
|||
|
## Usage
|
|||
|
|
|||
|
### In Node.js and Browserify
|
|||
|
|
|||
|
Install from npm
|
|||
|
|
|||
|
npm install underscore.string
|
|||
|
|
|||
|
Require individual functions
|
|||
|
|
|||
|
```javascript
|
|||
|
var slugify = require("underscore.string/slugify");
|
|||
|
|
|||
|
slugify("Hello world!");
|
|||
|
// => hello-world
|
|||
|
```
|
|||
|
|
|||
|
or load the full library to enable chaining
|
|||
|
|
|||
|
```javascript
|
|||
|
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.
|
|||
|
|
|||
|
[Browserify]: http://browserify.org/
|
|||
|
|
|||
|
### In Meteor
|
|||
|
|
|||
|
From your [Meteor][] project folder
|
|||
|
|
|||
|
```shell
|
|||
|
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.
|
|||
|
|
|||
|
```javascript
|
|||
|
s.slugify("Hello world!");
|
|||
|
// => hello-world
|
|||
|
|
|||
|
s(" epeli ").trim().capitalize().value();
|
|||
|
// => "Epeli"
|
|||
|
```
|
|||
|
|
|||
|
[Meteor]: http://www.meteor.com/
|
|||
|
|
|||
|
### 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.
|
|||
|
|
|||
|
[UMD]: https://github.com/umdjs/umd
|
|||
|
[RequireJS]: http://requirejs.org/
|
|||
|
|
|||
|
### Underscore.js/Lo-Dash integration
|
|||
|
|
|||
|
It is still possible use as Underscore.js/Lo-Dash extension
|
|||
|
|
|||
|
```javascript
|
|||
|
_.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](http://ramdajs.com/) or [Lo-Dash-FP](https://github.com/lodash/lodash-fp) you can use [underscore.string.fp](https://github.com/stoeffel/underscore.string.fp).
|
|||
|
|
|||
|
npm install underscore.string.fp
|
|||
|
|
|||
|
```javascript
|
|||
|
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](https://raw.github.com/epeli/underscore.string/master/dist/underscore.string.js) *Uncompressed with Comments*
|
|||
|
* [Production version](https://github.com/epeli/underscore.string/raw/master/dist/underscore.string.min.js) *Minified*
|
|||
|
|
|||
|
## API
|
|||
|
|
|||
|
### Individual functions
|
|||
|
|
|||
|
#### numberFormat(number, [ decimals=0, decimalSeparator='.', orderSeparator=',']) => string
|
|||
|
|
|||
|
Formats the numbers.
|
|||
|
|
|||
|
```javascript
|
|||
|
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
|
|||
|
|
|||
|
```javascript
|
|||
|
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.
|
|||
|
|
|||
|
```javascript
|
|||
|
capitalize("foo Bar");
|
|||
|
// => "Foo Bar"
|
|||
|
|
|||
|
capitalize("FOO Bar", true);
|
|||
|
// => "Foo bar"
|
|||
|
```
|
|||
|
|
|||
|
#### decapitalize(string) => string
|
|||
|
|
|||
|
Converts first letter of the string to lowercase.
|
|||
|
|
|||
|
```javascript
|
|||
|
decapitalize("Foo Bar");
|
|||
|
// => "foo Bar"
|
|||
|
```
|
|||
|
|
|||
|
#### chop(string, step) => array
|
|||
|
|
|||
|
```javascript
|
|||
|
chop("whitespace", 3);
|
|||
|
// => ["whi", "tes", "pac", "e"]
|
|||
|
```
|
|||
|
|
|||
|
#### clean(string) => string
|
|||
|
|
|||
|
Trim and replace multiple spaces with a single space.
|
|||
|
|
|||
|
```javascript
|
|||
|
clean(" foo bar ");
|
|||
|
// => "foo bar"
|
|||
|
```
|
|||
|
|
|||
|
#### chars(string) => array
|
|||
|
|
|||
|
```javascript
|
|||
|
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.
|
|||
|
|
|||
|
```javascript
|
|||
|
swapCase("hELLO");
|
|||
|
// => "Hello"
|
|||
|
```
|
|||
|
|
|||
|
#### include(string, substring) => boolean
|
|||
|
|
|||
|
Tests if string contains a substring.
|
|||
|
|
|||
|
```javascript
|
|||
|
include("foobar", "ob");
|
|||
|
// => true
|
|||
|
```
|
|||
|
|
|||
|
#### count(string, substring) => number
|
|||
|
|
|||
|
```javascript
|
|||
|
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.
|
|||
|
|
|||
|
```javascript
|
|||
|
escapeHTML("<div>Blah blah blah</div>");
|
|||
|
// => "<div>Blah blah blah</div>"
|
|||
|
```
|
|||
|
|
|||
|
#### unescapeHTML(string) => string
|
|||
|
|
|||
|
Converts entity characters to HTML equivalents.
|
|||
|
This function supports cent, yen, euro, pound, lt, gt, copy, reg, quote, amp, apos, nbsp.
|
|||
|
|
|||
|
```javascript
|
|||
|
unescapeHTML("<div>Blah blah blah</div>");
|
|||
|
// => "<div>Blah blah blah</div>"
|
|||
|
```
|
|||
|
|
|||
|
#### insert(string, index, substring) => string
|
|||
|
|
|||
|
```javascript
|
|||
|
insert("Hello ", 6, "world");
|
|||
|
// => "Hello world"
|
|||
|
```
|
|||
|
|
|||
|
#### replaceAll(string, find, replace, [ignorecase=false]) => string
|
|||
|
|
|||
|
```javascript
|
|||
|
replaceAll("foo", "o", "a");
|
|||
|
// => "faa"
|
|||
|
```
|
|||
|
|
|||
|
#### isBlank(string) => boolean
|
|||
|
|
|||
|
```javascript
|
|||
|
isBlank(""); // => true
|
|||
|
isBlank("\n"); // => true
|
|||
|
isBlank(" "); // => true
|
|||
|
isBlank("a"); // => false
|
|||
|
```
|
|||
|
|
|||
|
#### join(separator, ...strings) => string
|
|||
|
|
|||
|
Joins strings together with given separator
|
|||
|
|
|||
|
```javascript
|
|||
|
join(" ", "foo", "bar");
|
|||
|
// => "foo bar"
|
|||
|
```
|
|||
|
|
|||
|
#### lines(str) => array
|
|||
|
|
|||
|
Split lines to an array
|
|||
|
|
|||
|
```javascript
|
|||
|
lines("Hello\nWorld");
|
|||
|
// => ["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
|
|||
|
|
|||
|
```javascript
|
|||
|
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:
|
|||
|
|
|||
|
```javascript
|
|||
|
reverse("foobar");
|
|||
|
// => "raboof"
|
|||
|
```
|
|||
|
|
|||
|
#### splice(string, index, howmany, substring) => string
|
|||
|
|
|||
|
Like an array splice.
|
|||
|
|
|||
|
```javascript
|
|||
|
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).
|
|||
|
|
|||
|
```javascript
|
|||
|
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).
|
|||
|
|
|||
|
```javascript
|
|||
|
endsWith("image.gif", "gif");
|
|||
|
// => true
|
|||
|
|
|||
|
endsWith("image.old.gif", "old", 9);
|
|||
|
// => true
|
|||
|
```
|
|||
|
|
|||
|
#### pred(string) => string
|
|||
|
|
|||
|
Returns the predecessor to str.
|
|||
|
|
|||
|
```javascript
|
|||
|
pred("b");
|
|||
|
// => "a"
|
|||
|
|
|||
|
pred("B");
|
|||
|
// => "A"
|
|||
|
```
|
|||
|
|
|||
|
#### succ(string) => string
|
|||
|
|
|||
|
Returns the successor to str.
|
|||
|
|
|||
|
```javascript
|
|||
|
succ("a");
|
|||
|
// => "b"
|
|||
|
|
|||
|
succ("A");
|
|||
|
// => "B"
|
|||
|
```
|
|||
|
|
|||
|
|
|||
|
#### titleize(string) => string
|
|||
|
|
|||
|
```javascript
|
|||
|
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.
|
|||
|
|
|||
|
```javascript
|
|||
|
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
|
|||
|
|
|||
|
```javascript
|
|||
|
classify("some_class_name");
|
|||
|
// => "SomeClassName"
|
|||
|
```
|
|||
|
|
|||
|
#### underscored(string) => string
|
|||
|
|
|||
|
Converts a camelized or dasherized string into an underscored one
|
|||
|
|
|||
|
```javascript
|
|||
|
underscored("MozTransform");
|
|||
|
// => "moz_transform"
|
|||
|
```
|
|||
|
|
|||
|
#### dasherize(string) => string
|
|||
|
|
|||
|
Converts a underscored or camelized string into an dasherized one
|
|||
|
|
|||
|
```javascript
|
|||
|
dasherize("MozTransform");
|
|||
|
// => "-moz-transform"
|
|||
|
```
|
|||
|
|
|||
|
#### humanize(string) => string
|
|||
|
|
|||
|
Converts an underscored, camelized, or dasherized string into a humanized one.
|
|||
|
Also removes beginning and ending whitespace, and removes the postfix '_id'.
|
|||
|
|
|||
|
```javascript
|
|||
|
humanize(" capitalize dash-CamelCase_underscore trim ");
|
|||
|
// => "Capitalize dash camel case underscore trim"
|
|||
|
```
|
|||
|
|
|||
|
#### trim(string, [characters]) => string
|
|||
|
|
|||
|
Trims defined characters from begining and ending of the string.
|
|||
|
Defaults to whitespace characters.
|
|||
|
|
|||
|
```javascript
|
|||
|
trim(" foobar ");
|
|||
|
// => "foobar"
|
|||
|
|
|||
|
trim("_-foobar-_", "_-");
|
|||
|
// => "foobar"
|
|||
|
```
|
|||
|
|
|||
|
|
|||
|
#### ltrim(string, [characters]) => string
|
|||
|
|
|||
|
Left trim. Similar to trim, but only for left side.
|
|||
|
|
|||
|
#### rtrim(string, [characters]) => string
|
|||
|
|
|||
|
Right trim. Similar to trim, but only for right side.
|
|||
|
|
|||
|
#### truncate(string, length, truncateString) => string
|
|||
|
|
|||
|
```javascript
|
|||
|
truncate("Hello world", 5);
|
|||
|
// => "Hello..."
|
|||
|
|
|||
|
truncate("Hello", 10);
|
|||
|
// => "Hello"
|
|||
|
```
|
|||
|
|
|||
|
#### prune(string, length, pruneString) => string
|
|||
|
|
|||
|
Elegant version of truncate. Makes sure the pruned string does not exceed the
|
|||
|
original length. Avoid half-chopped words when truncating.
|
|||
|
|
|||
|
```javascript
|
|||
|
prune("Hello, world", 5);
|
|||
|
// => "Hello..."
|
|||
|
|
|||
|
prune("Hello, world", 8);
|
|||
|
// => "Hello..."
|
|||
|
|
|||
|
prune("Hello, world", 5, " (read a lot more)");
|
|||
|
// => "Hello, world" (as adding "(read a lot more)" would be longer than the original string)
|
|||
|
|
|||
|
prune("Hello, cruel world", 15);
|
|||
|
// => "Hello, cruel..."
|
|||
|
|
|||
|
prune("Hello", 10);
|
|||
|
// => "Hello"
|
|||
|
```
|
|||
|
|
|||
|
#### words(str, delimiter=/\s+/) => array
|
|||
|
|
|||
|
Split string by delimiter (String or RegExp), /\s+/ by default.
|
|||
|
|
|||
|
```javascript
|
|||
|
words(" I love you ");
|
|||
|
// => ["I", "love", "you"]
|
|||
|
|
|||
|
words("I_love_you", "_");
|
|||
|
// => ["I", "love", "you"]
|
|||
|
|
|||
|
words("I-love-you", /-/);
|
|||
|
// => ["I", "love", "you"]
|
|||
|
|
|||
|
words(" ")
|
|||
|
// => []
|
|||
|
```
|
|||
|
|
|||
|
#### sprintf(string format, ...arguments) => string
|
|||
|
|
|||
|
C like string formatting.
|
|||
|
Credits goes to [Alexandru Marasteanu][o].
|
|||
|
For more detailed documentation, see the [original page][o].
|
|||
|
|
|||
|
[o]: http://www.diveintojavascript.com/projects/javascript-sprintf
|
|||
|
|
|||
|
```javascript
|
|||
|
sprintf("%.1f", 1.17);
|
|||
|
// => "1.2"
|
|||
|
```
|
|||
|
|
|||
|
#### pad(str, length, [padStr, type]) => string
|
|||
|
|
|||
|
pads the `str` with characters until the total string length is equal to the passed `length` parameter. By default, pads on the **left** with the space char (`" "`). `padStr` is truncated to a single character if necessary.
|
|||
|
|
|||
|
```javascript
|
|||
|
pad("1", 8);
|
|||
|
// => " 1"
|
|||
|
|
|||
|
pad("1", 8, "0");
|
|||
|
// => "00000001"
|
|||
|
|
|||
|
pad("1", 8, "0", "right");
|
|||
|
// => "10000000"
|
|||
|
|
|||
|
pad("1", 8, "0", "both");
|
|||
|
// => "00001000"
|
|||
|
|
|||
|
pad("1", 8, "bleepblorp", "both");
|
|||
|
// => "bbbb1bbb"
|
|||
|
```
|
|||
|
|
|||
|
#### lpad(str, length, [padStr]) => string
|
|||
|
|
|||
|
left-pad a string. Alias for `pad(str, length, padStr, "left")`
|
|||
|
|
|||
|
```javascript
|
|||
|
lpad("1", 8, "0");
|
|||
|
// => "00000001"
|
|||
|
```
|
|||
|
|
|||
|
#### rpad(str, length, [padStr]) => string
|
|||
|
|
|||
|
right-pad a string. Alias for `pad(str, length, padStr, "right")`
|
|||
|
|
|||
|
```javascript
|
|||
|
rpad("1", 8, "0");
|
|||
|
// => "10000000"
|
|||
|
```
|
|||
|
|
|||
|
#### lrpad(str, length, [padStr]) => string
|
|||
|
|
|||
|
left/right-pad a string. Alias for `pad(str, length, padStr, "both")`
|
|||
|
|
|||
|
```javascript
|
|||
|
lrpad("1", 8, '0');
|
|||
|
// => "00001000"
|
|||
|
```
|
|||
|
|
|||
|
|
|||
|
#### toNumber(string, [decimals]) => number
|
|||
|
|
|||
|
Parse string to number. Returns NaN if string can't be parsed to number.
|
|||
|
|
|||
|
```javascript
|
|||
|
toNumber("2.556");
|
|||
|
// => 3
|
|||
|
|
|||
|
toNumber("2.556", 1);
|
|||
|
// => 2.6
|
|||
|
|
|||
|
toNumber("999.999", -1);
|
|||
|
// => 990
|
|||
|
```
|
|||
|
|
|||
|
#### strRight(string, pattern) => string
|
|||
|
|
|||
|
Searches a string from left to right for a pattern and returns a substring consisting of the characters in the string that are to the right of the pattern or all string if no match found.
|
|||
|
|
|||
|
```javascript
|
|||
|
strRight("This_is_a_test_string", "_");
|
|||
|
// => "is_a_test_string"
|
|||
|
```
|
|||
|
|
|||
|
#### strRightBack(string, pattern) => string
|
|||
|
|
|||
|
Searches a string from right to left for a pattern and returns a substring consisting of the characters in the string that are to the right of the pattern or all string if no match found.
|
|||
|
|
|||
|
```javascript
|
|||
|
strRightBack("This_is_a_test_string", "_");
|
|||
|
// => "string"
|
|||
|
```
|
|||
|
|
|||
|
#### strLeft(string, pattern) => string
|
|||
|
|
|||
|
Searches a string from left to right for a pattern and returns a substring consisting of the characters in the string that are to the left of the pattern or all string if no match found.
|
|||
|
|
|||
|
```javascript
|
|||
|
strLeft("This_is_a_test_string", "_");
|
|||
|
// => "This";
|
|||
|
```
|
|||
|
|
|||
|
#### strLeftBack(string, pattern) => string
|
|||
|
|
|||
|
Searches a string from right to left for a pattern and returns a substring consisting of the characters in the string that are to the left of the pattern or all string if no match found.
|
|||
|
|
|||
|
```javascript
|
|||
|
strLeftBack("This_is_a_test_string", "_");
|
|||
|
// => "This_is_a_test";
|
|||
|
```
|
|||
|
|
|||
|
#### stripTags(string) => string
|
|||
|
|
|||
|
Removes all html tags from string.
|
|||
|
|
|||
|
```javascript
|
|||
|
stripTags("a <a href="#">link</a>");
|
|||
|
// => "a link"
|
|||
|
|
|||
|
stripTags("a <a href="#">link</a><script>alert("hello world!")</script>");
|
|||
|
// => "a linkalert("hello world!")"
|
|||
|
```
|
|||
|
|
|||
|
#### toSentence(array, [delimiter, lastDelimiter]) => string
|
|||
|
|
|||
|
Join an array into a human readable sentence.
|
|||
|
|
|||
|
```javascript
|
|||
|
toSentence(["jQuery", "Mootools", "Prototype"]);
|
|||
|
// => "jQuery, Mootools and Prototype";
|
|||
|
|
|||
|
toSentence(["jQuery", "Mootools", "Prototype"], ", ", " unt ');
|
|||
|
// => "jQuery, Mootools unt Prototype";
|
|||
|
```
|
|||
|
|
|||
|
#### toSentenceSerial(array, [delimiter, lastDelimiter]) => string
|
|||
|
|
|||
|
The same as `toSentence`, but adjusts delimeters to use [Serial comma](http://en.wikipedia.org/wiki/Serial_comma).
|
|||
|
|
|||
|
```javascript
|
|||
|
toSentenceSerial(["jQuery", "Mootools"]);
|
|||
|
// => "jQuery and Mootools"
|
|||
|
|
|||
|
toSentenceSerial(["jQuery", "Mootools", "Prototype"]);
|
|||
|
// => "jQuery, Mootools, and Prototype"
|
|||
|
|
|||
|
toSentenceSerial(["jQuery", "Mootools", "Prototype"], ", ", " unt ');
|
|||
|
// => "jQuery, Mootools, unt Prototype"
|
|||
|
```
|
|||
|
|
|||
|
#### repeat(string, count, [separator]) => string
|
|||
|
|
|||
|
Repeats a string count times.
|
|||
|
|
|||
|
```javascript
|
|||
|
repeat("foo", 3);
|
|||
|
// => "foofoofoo"
|
|||
|
|
|||
|
repeat("foo", 3, "bar");
|
|||
|
// => "foobarfoobarfoo"
|
|||
|
```
|
|||
|
|
|||
|
#### surround(string, wrap) => string
|
|||
|
|
|||
|
Surround a string with another string.
|
|||
|
|
|||
|
```javascript
|
|||
|
surround("foo", "ab");
|
|||
|
// => "abfooab"
|
|||
|
```
|
|||
|
|
|||
|
#### quote(string, quoteChar) or q(string, quoteChar) => string
|
|||
|
|
|||
|
Quotes a string. `quoteChar` defaults to `"`.
|
|||
|
|
|||
|
```javascript
|
|||
|
quote("foo", '"');
|
|||
|
// => '"foo"';
|
|||
|
```
|
|||
|
#### unquote(string, quoteChar) => string
|
|||
|
|
|||
|
Unquotes a string. `quoteChar` defaults to `"`.
|
|||
|
|
|||
|
```javascript
|
|||
|
unquote('"foo"');
|
|||
|
// => "foo"
|
|||
|
|
|||
|
unquote("'foo'", "'");
|
|||
|
// => "foo"
|
|||
|
```
|
|||
|
|
|||
|
|
|||
|
#### slugify(string) => string
|
|||
|
|
|||
|
Transform text into an ascii slug which can be used in safely in URLs. Replaces whitespaces, accentuated, and special characters with a dash. Limited set of non-ascii characters are transformed to similar versions in the ascii character set such as `ä` to `a`.
|
|||
|
|
|||
|
```javascript
|
|||
|
slugify("Un éléphant à l\'orée du bois");
|
|||
|
// => "un-elephant-a-l-oree-du-bois"
|
|||
|
```
|
|||
|
|
|||
|
***Caution: this function is charset dependent***
|
|||
|
|
|||
|
#### naturalCmp(string1, string2) => number
|
|||
|
|
|||
|
Naturally sort strings like humans would do. None numbers are compared by their [ASCII values](http://www.asciitable.com/). Note: this means "a" > "A". Use `.toLowerCase` if this isn't to be desired.
|
|||
|
|
|||
|
Just past it to `Array#sort`.
|
|||
|
|
|||
|
```javascript
|
|||
|
["foo20", "foo5"].sort(naturalCmp);
|
|||
|
// => ["foo5", "foo20"]
|
|||
|
```
|
|||
|
|
|||
|
#### toBoolean(string) => boolean
|
|||
|
|
|||
|
Turn strings that can be commonly considered as booleas to real booleans. Such as "true", "false", "1" and "0". This function is case insensitive.
|
|||
|
|
|||
|
```javascript
|
|||
|
toBoolean("true");
|
|||
|
// => true
|
|||
|
|
|||
|
toBoolean("FALSE");
|
|||
|
// => false
|
|||
|
|
|||
|
toBoolean("random");
|
|||
|
// => undefined
|
|||
|
```
|
|||
|
|
|||
|
It can be customized by giving arrays of truth and falsy value matcher as parameters. Matchers can be also RegExp objects.
|
|||
|
|
|||
|
```javascript
|
|||
|
toBoolean("truthy", ["truthy"], ["falsy"]);
|
|||
|
// => true
|
|||
|
|
|||
|
toBoolean("true only at start", [/^true/]);
|
|||
|
// => true
|
|||
|
```
|
|||
|
|
|||
|
### Library functions
|
|||
|
|
|||
|
If you require the full library you can use chaining and aliases
|
|||
|
|
|||
|
#### s(string) => chain
|
|||
|
|
|||
|
Start a chain. Returns an immutable chain object with the string functions as
|
|||
|
methods which return a new chain object instead of the plain string value.
|
|||
|
|
|||
|
The chain object includes also following native Javascript string methods:
|
|||
|
|
|||
|
- [toUpperCase](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase)
|
|||
|
- [toLowerCase](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase)
|
|||
|
- [split](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split)
|
|||
|
- [replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
|
|||
|
- [slice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice)
|
|||
|
- [substring](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/String/substring)
|
|||
|
- [substr](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr)
|
|||
|
- [concat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat)
|
|||
|
|
|||
|
#### chain.value()
|
|||
|
|
|||
|
Return the string value from the chain
|
|||
|
|
|||
|
```javascript
|
|||
|
s(" foo ").trim().capitalize().value();
|
|||
|
// => "Foo"
|
|||
|
```
|
|||
|
|
|||
|
When calling a method which does not return a string the resulting value is
|
|||
|
immediately returned
|
|||
|
|
|||
|
```javascript
|
|||
|
s(" foobar ").trim().startsWith("foo");
|
|||
|
// => true
|
|||
|
```
|
|||
|
|
|||
|
#### chain.tap(function) => chain
|
|||
|
|
|||
|
Tap into the chain with a custom function
|
|||
|
|
|||
|
```javascript
|
|||
|
s("foo").tap(function(value){
|
|||
|
return value + "bar";
|
|||
|
}).value();
|
|||
|
// => "foobar"
|
|||
|
```
|
|||
|
|
|||
|
|
|||
|
#### Aliases
|
|||
|
|
|||
|
```javascript
|
|||
|
strip = trim
|
|||
|
lstrip = ltrim
|
|||
|
rstrip = rtrim
|
|||
|
center = lrpad
|
|||
|
rjust = lpad
|
|||
|
ljust = rpad
|
|||
|
contains = include
|
|||
|
q = quote
|
|||
|
toBool = toBoolean
|
|||
|
camelcase = camelize
|
|||
|
```
|
|||
|
|
|||
|
## Maintainers ##
|
|||
|
|
|||
|
This library is maintained by
|
|||
|
|
|||
|
- Esa-Matti Suuronen – ***[@epeli](https://github.com/epeli)***
|
|||
|
- Christoph Hermann – ***[@stoeffel](https://github.com/stoeffel)***
|
|||
|
|
|||
|
## Licence ##
|
|||
|
|
|||
|
The MIT License
|
|||
|
|
|||
|
Copyright (c) 2011 Esa-Matti Suuronen esa-matti@suuronen.org
|
|||
|
|
|||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|||
|
of this software and associated documentation files (the "Software"), to deal
|
|||
|
in the Software without restriction, including without limitation the rights
|
|||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|||
|
copies of the Software, and to permit persons to whom the Software is
|
|||
|
furnished to do so, subject to the following conditions:
|
|||
|
|
|||
|
The above copyright notice and this permission notice shall be included in
|
|||
|
all copies or substantial portions of the Software.
|
|||
|
|
|||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|||
|
THE SOFTWARE.
|
|||
|
|
|||
|
|
|||
|
[d]: http://www.diveintojavascript.com/core-javascript-reference/the-string-object
|