1 <span class="github-only">
3 The stable release documentation can be found here https://epeli.github.io/underscore.string/
7 # Underscore.string [![Build Status](https://secure.travis-ci.org/epeli/underscore.string.png?branch=master)](http://travis-ci.org/epeli/underscore.string) #
9 Javascript lacks complete string manipulation operations.
10 This is an attempt to fill that gap. List of build-in methods can be found
11 for example from [Dive Into JavaScript][d].
12 Originally started as an Underscore.js extension but is a full standalone
15 Upgrading from 2.x to 3.x? Please read the [changelog][c].
17 [c]: https://github.com/epeli/underscore.string/blob/master/CHANGELOG.markdown#300
21 ### For Node.js, Browserify and Webpack
25 npm install underscore.string
27 Require individual functions
30 var slugify = require("underscore.string/slugify");
32 slugify("Hello world!");
36 or load the full library to enable chaining
39 var s = require("underscore.string");
41 s(" epeli ").trim().capitalize().value();
45 but especially when using with [Browserify][] the individual function approach
46 is recommended because using it you only add those functions to your bundle you
49 [Browserify]: http://browserify.org/
53 From your [Meteor][] project folder
56 meteor add underscorestring:underscore.string
59 and you'll be able to access the library with the ***s*** global from both the server and the client.
62 s.slugify("Hello world!");
65 s(" epeli ").trim().capitalize().value();
69 [Meteor]: http://www.meteor.com/
73 The `dist/underscore.string.js` file is an [UMD][] build. You can load it using
74 an AMD loader such as [RequireJS][] or just stick it to a web page and access
75 the library from the ***s*** global.
77 [UMD]: https://github.com/umdjs/umd
78 [RequireJS]: http://requirejs.org/
80 ### Underscore.js/Lo-Dash integration
82 It is still possible use as Underscore.js/Lo-Dash extension
87 But it's not recommended since `include`, `contains`, `reverse` and `join`
88 are dropped because they collide with the functions already defined by Underscore.js.
90 ### Lo-Dash-FP/Ramda integration
92 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).
94 npm install underscore.string.fp
97 var S = require('underscore.string.fp');
98 var filter = require('lodash-fp').filter;
99 var filter = require('ramda').filter;
101 filter(S.startsWith('.'), [
106 // => ['.vimrc', '.zshrc']
111 * [Development version](https://raw.github.com/epeli/underscore.string/master/dist/underscore.string.js) *Uncompressed with Comments*
112 * [Production version](https://github.com/epeli/underscore.string/raw/master/dist/underscore.string.min.js) *Minified*
116 ### Individual functions
118 #### numberFormat(number, [ decimals=0, decimalSeparator='.', orderSeparator=',']) => string
123 numberFormat(1000, 2);
126 numberFormat(123456789.123, 5, ".", ",");
127 // => "123,456,789.12300"
131 #### levenshtein(string1, string2) => number
133 Calculates [Levenshtein distance][ld] between two strings.
134 [ld]: http://en.wikipedia.org/wiki/Levenshtein_distance
137 levenshtein("kitten", "kittah");
141 #### capitalize(string, [lowercaseRest=false]) => string
143 Converts first letter of the string to uppercase. If `true` is passed as second argument the rest
144 of the string will be converted to lower case.
147 capitalize("foo Bar");
150 capitalize("FOO Bar", true);
154 #### decapitalize(string) => string
156 Converts first letter of the string to lowercase.
159 decapitalize("Foo Bar");
163 #### chop(string, step) => array
166 chop("whitespace", 3);
167 // => ["whi", "tes", "pac", "e"]
170 #### clean(string) => string
172 Trim and replace multiple spaces with a single space.
179 #### cleanDiacritics(string) => string
181 Replace [diacritic][dc] characters with closest ASCII equivalents. Check the
182 [source][s] for supported characters. [Pull requests][p] welcome for missing
185 [dc]: https://en.wikipedia.org/wiki/Diacritic
186 [s]: https://github.com/epeli/underscore.string/blob/master/cleanDiacritics.js
187 [p]: https://github.com/epeli/underscore.string/blob/master/CONTRIBUTING.markdown
190 cleanDiacritics("ääkkönen");
194 #### chars(string) => array
198 // => ["H", "e", "l", "l", "o"]
201 #### swapCase(string) => string
203 Returns a copy of the string in which all the case-based characters have had their case swapped.
210 #### include(string, substring) => boolean
212 Tests if string contains a substring.
215 include("foobar", "ob");
219 #### count(string, substring) => number
221 Returns number of occurrences of substring in string.
224 count("Hello world", "l");
228 #### escapeHTML(string) => string
230 Converts HTML special characters to their entity equivalents.
231 This function supports cent, yen, euro, pound, lt, gt, copy, reg, quote, amp, apos.
234 escapeHTML("<div>Blah blah blah</div>");
235 // => "<div>Blah blah blah</div>"
238 #### unescapeHTML(string) => string
240 Converts entity characters to HTML equivalents.
241 This function supports cent, yen, euro, pound, lt, gt, copy, reg, quote, amp, apos, nbsp.
244 unescapeHTML("<div>Blah blah blah</div>");
245 // => "<div>Blah blah blah</div>"
248 #### insert(string, index, substring) => string
251 insert("Hellworld", 4, "o ");
255 #### replaceAll(string, find, replace, [ignorecase=false]) => string
258 replaceAll("foo", "o", "a");
262 #### isBlank(string) => boolean
265 isBlank(""); // => true
266 isBlank("\n"); // => true
267 isBlank(" "); // => true
268 isBlank("a"); // => false
271 #### join(separator, ...strings) => string
273 Joins strings together with given separator
276 join(" ", "foo", "bar");
280 #### lines(str) => array
282 Split lines to an array
285 lines("Hello\nWorld");
286 // => ["Hello", "World"]
289 #### wrap(str, options) => string
291 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).
294 wrap("Hello World", { width:5 })
297 wrap("Hello World", { width:6, seperator:'.', trailingSpaces: true })
298 // => "Hello .World "
300 wrap("Hello World", { width:5, seperator:'.', cut:true, trailingSpaces: true })
301 // => "Hello. Worl.d "
303 wrap("Hello World", { width:5, seperator:'.', preserveSpaces: true })
308 #### dedent(str, [pattern]) => string
310 Dedent unnecessary indentation or dedent by a pattern.
312 Credits go to @sindresorhus.
313 This implementation is similar to https://github.com/sindresorhus/strip-indent
316 dedent(" Hello\n World");
317 // => "Hello\n World"
319 dedent("\t\tHello\n\t\t\t\tWorld");
320 // => "Hello\n\t\tWorld"
322 dedent(" Hello\n World", " "); // Dedent by 2 spaces
323 // => " Hello\n World"
326 #### reverse(string) => string
328 Return reversed string:
335 #### splice(string, index, howmany, substring) => string
337 Like an array splice.
340 splice("https://edtsech@bitbucket.org/edtsech/underscore.strings", 30, 7, "epeli");
341 // => "https://edtsech@bitbucket.org/epeli/underscore.strings"
344 #### startsWith(string, starts, [position]) => boolean
346 This method checks whether the string begins with `starts` at `position` (default: 0).
349 startsWith("image.gif", "image");
352 startsWith(".vimrc", "vim", 1);
356 #### endsWith(string, ends, [position]) => boolean
358 This method checks whether the string ends with `ends` at `position` (default: string.length).
361 endsWith("image.gif", "gif");
364 endsWith("image.old.gif", "old", 9);
368 #### pred(string) => string
370 Returns the predecessor to str.
380 #### succ(string) => string
382 Returns the successor to str.
393 #### titleize(string) => string
396 titleize("my name is epeli");
397 // => "My Name Is Epeli"
400 #### camelize(string, [decapitalize=false]) => string
402 Converts underscored or dasherized string to a camelized one. Begins with
403 a lower case letter unless it starts with an underscore, dash or an upper case letter.
406 camelize("moz-transform");
409 camelize("-moz-transform");
412 camelize("_moz_transform");
415 camelize("Moz-transform");
418 camelize("-moz-transform", true);
422 #### classify(string) => string
424 Converts string to camelized class name. First letter is always upper case
427 classify("some_class_name");
428 // => "SomeClassName"
431 #### underscored(string) => string
433 Converts a camelized or dasherized string into an underscored one
436 underscored("MozTransform");
437 // => "moz_transform"
440 #### dasherize(string) => string
442 Converts a underscored or camelized string into an dasherized one
445 dasherize("MozTransform");
446 // => "-moz-transform"
449 #### humanize(string) => string
451 Converts an underscored, camelized, or dasherized string into a humanized one.
452 Also removes beginning and ending whitespace, and removes the postfix '_id'.
455 humanize(" capitalize dash-CamelCase_underscore trim ");
456 // => "Capitalize dash camel case underscore trim"
459 #### trim(string, [characters]) => string
461 Trims defined characters from begining and ending of the string.
462 Defaults to whitespace characters.
468 trim("_-foobar-_", "_-");
473 #### ltrim(string, [characters]) => string
475 Left trim. Similar to trim, but only for left side.
477 #### rtrim(string, [characters]) => string
479 Right trim. Similar to trim, but only for right side.
481 #### truncate(string, length, [truncateString = '...']) => string
484 truncate("Hello world", 5);
487 truncate("Hello", 10);
491 #### prune(string, length, pruneString) => string
493 Elegant version of truncate. Makes sure the pruned string does not exceed the
494 original length. Avoid half-chopped words when truncating.
497 prune("Hello, world", 5);
500 prune("Hello, world", 8);
503 prune("Hello, world", 5, " (read a lot more)");
504 // => "Hello, world" (as adding "(read a lot more)" would be longer than the original string)
506 prune("Hello, cruel world", 15);
507 // => "Hello, cruel..."
513 #### words(str, delimiter=/\s+/) => array
515 Split string by delimiter (String or RegExp), /\s+/ by default.
518 words(" I love you ");
519 // => ["I", "love", "you"]
521 words("I_love_you", "_");
522 // => ["I", "love", "you"]
524 words("I-love-you", /-/);
525 // => ["I", "love", "you"]
531 #### sprintf(string format, ...arguments) => string
533 C like string formatting.
534 Credits goes to [Alexandru Marasteanu][o].
535 For more detailed documentation, see the [original page][o].
537 [o]: http://www.diveintojavascript.com/projects/javascript-sprintf
540 sprintf("%.1f", 1.17);
544 #### pad(str, length, [padStr, type]) => string
546 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.
555 pad("1", 8, "0", "right");
558 pad("1", 8, "0", "both");
561 pad("1", 8, "bleepblorp", "both");
565 #### lpad(str, length, [padStr]) => string
567 left-pad a string. Alias for `pad(str, length, padStr, "left")`
574 #### rpad(str, length, [padStr]) => string
576 right-pad a string. Alias for `pad(str, length, padStr, "right")`
583 #### lrpad(str, length, [padStr]) => string
585 left/right-pad a string. Alias for `pad(str, length, padStr, "both")`
593 #### toNumber(string, [decimals]) => number
595 Parse string to number. Returns NaN if string can't be parsed to number.
601 toNumber("2.556", 1);
604 toNumber("999.999", -1);
608 #### strRight(string, pattern) => string
610 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.
613 strRight("This_is_a_test_string", "_");
614 // => "is_a_test_string"
617 #### strRightBack(string, pattern) => string
619 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.
622 strRightBack("This_is_a_test_string", "_");
626 #### strLeft(string, pattern) => string
628 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.
631 strLeft("This_is_a_test_string", "_");
635 #### strLeftBack(string, pattern) => string
637 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.
640 strLeftBack("This_is_a_test_string", "_");
641 // => "This_is_a_test";
644 #### stripTags(string) => string
646 Removes all html tags from string.
649 stripTags("a <a href=\"#\">link</a>");
652 stripTags("a <a href=\"#\">link</a><script>alert(\"hello world!\")</script>");
653 // => "a linkalert("hello world!")"
656 #### toSentence(array, [delimiter, lastDelimiter]) => string
658 Join an array into a human readable sentence.
661 toSentence(["jQuery", "Mootools", "Prototype"]);
662 // => "jQuery, Mootools and Prototype";
664 toSentence(["jQuery", "Mootools", "Prototype"], ", ", " unt ");
665 // => "jQuery, Mootools unt Prototype";
668 #### toSentenceSerial(array, [delimiter, lastDelimiter]) => string
670 The same as `toSentence`, but adjusts delimeters to use [Serial comma](http://en.wikipedia.org/wiki/Serial_comma).
673 toSentenceSerial(["jQuery", "Mootools"]);
674 // => "jQuery and Mootools"
676 toSentenceSerial(["jQuery", "Mootools", "Prototype"]);
677 // => "jQuery, Mootools, and Prototype"
679 toSentenceSerial(["jQuery", "Mootools", "Prototype"], ", ", " unt ");
680 // => "jQuery, Mootools, unt Prototype"
683 #### repeat(string, count, [separator]) => string
685 Repeats a string count times.
691 repeat("foo", 3, "bar");
692 // => "foobarfoobarfoo"
695 #### surround(string, wrap) => string
697 Surround a string with another string.
700 surround("foo", "ab");
704 #### quote(string, quoteChar) or q(string, quoteChar) => string
706 Quotes a string. `quoteChar` defaults to `"`.
712 #### unquote(string, quoteChar) => string
714 Unquotes a string. `quoteChar` defaults to `"`.
720 unquote("'foo'", "'");
725 #### slugify(string) => string
727 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`.
730 slugify("Un éléphant à l\'orée du bois");
731 // => "un-elephant-a-l-oree-du-bois"
734 ***Caution: this function is charset dependent***
736 #### naturalCmp(string1, string2) => number
738 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.
740 Just past it to `Array#sort`.
743 ["foo20", "foo5"].sort(naturalCmp);
744 // => ["foo5", "foo20"]
747 #### toBoolean(string) => boolean
749 Turn strings that can be commonly considered as booleas to real booleans. Such as "true", "false", "1" and "0". This function is case insensitive.
762 It can be customized by giving arrays of truth and falsy value matcher as parameters. Matchers can be also RegExp objects.
765 toBoolean("truthy", ["truthy"], ["falsy"]);
768 toBoolean("true only at start", [/^true/]);
772 #### map(string, function) => string
774 Creates a new string with the results of calling a provided function on every character of the given string.
777 map("Hello world", function(x) {
782 map(12345, function(x) {
787 map("Hello world", function(x) {
788 if (x === 'o') x = 'O';
794 ### Library functions
796 If you require the full library you can use chaining and aliases
798 #### s(string) => chain
800 Start a chain. Returns an immutable chain object with the string functions as
801 methods which return a new chain object instead of the plain string value.
803 The chain object includes also following native Javascript string methods:
805 - [toUpperCase](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase)
806 - [toLowerCase](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase)
807 - [split](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split)
808 - [replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
809 - [slice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice)
810 - [substring](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/String/substring)
811 - [substr](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr)
812 - [concat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat)
816 Return the string value from the chain
819 s(" foo ").trim().capitalize().value();
823 When calling a method which does not return a string the resulting value is
827 s(" foobar ").trim().startsWith("foo");
831 #### chain.tap(function) => chain
833 Tap into the chain with a custom function
836 s("foo").tap(function(value){
837 return value + "bar";
860 This library is maintained by
862 - Esa-Matti Suuronen – ***[@epeli](https://github.com/epeli)***
863 - Christoph Hermann – ***[@stoeffel](https://github.com/stoeffel)***
869 Copyright (c) 2011 Esa-Matti Suuronen esa-matti@suuronen.org
871 Permission is hereby granted, free of charge, to any person obtaining a copy
872 of this software and associated documentation files (the "Software"), to deal
873 in the Software without restriction, including without limitation the rights
874 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
875 copies of the Software, and to permit persons to whom the Software is
876 furnished to do so, subject to the following conditions:
878 The above copyright notice and this permission notice shall be included in
879 all copies or substantial portions of the Software.
881 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
882 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
883 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
884 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
885 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
886 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
890 [d]: http://www.diveintojavascript.com/core-javascript-reference/the-string-object