string.js, or simply S is a lightweight (< 5 kb minified and gzipped) JavaScript library for the browser or for Node.js that provides extra String methods. Originally, it modified the String prototype. But I quickly learned that in JavaScript, this is considered poor practice.

Why?

Personally, I prefer the cleanliness of the way code looks when it appears to be native methods. i.e. when you modify native JavaScript prototypes. However, if any app dependency required string.js, then the app's string prototype would be modified in every module. This could be troublesome. So I settled on creating a wrapper a la jQuery style. For those of you prototype hatin' fools, there is the method extendPrototype().

Why wasn't I happy with any of them? They are all static methods that don't seem to support chaining in a clean way 'OR' they have an odd dependency. Sugar is the notable exception.

Installation

npminstall--savestring

Experiment with String.js Now

Assuming you're on http://stringjs.com, just simply open up the Webkit inspector in either Chrome or Safari, or the web console in Firefox and you'll notice that string.js is included in this page so that you can start experimenting with it right away.

Usage

Node.js

var S = require('string');

Originally, I was using $s but glancing over the code, it was easy to confuse $s for string.js with $ for jQuery. Feel free to use the most convenient variable for you.

Rails

Browsers

<!-- HTML5 --><scriptsrc="https://cdn.rawgit.com/jprichardson/string.js/master/lib/string.min.js"></script><!-- Note that in the mime type for Javascript is now officially 'application/javascript'. If you
set the type to application/javascript in IE browsers, your Javscript will fail. Just don't set a
type via the script tag and set the mime type from your server. Most browsers look at the server mime
type anyway --><!-- For HTML4/IE --><scripttype="text/javascript"src="https://cdn.rawgit.com/jprichardson/string.js/master/lib/string.min.js"></script>

Still like the clean look of calling these methods directly on native Strings? No problem. Call extendPrototype(). Make sure to not call this at the module level, at it'll effect the entire application lifecycle. You should really only use this at the method level. The one exception being if your application will not be a dependency of another application.

S.extendPrototype();
var name = 'Your name is JP'.right(2); //'JP'
S.restorePrototype(); //be a good citizen and clean up

Extending string.js

Native JavaScript Methods

string.js imports all of the native JavaScript methods. This is for convenience. The only difference is that the imported methods return string.js objects instead of native JavaScript strings. The one exception to this is the method charAt(index). This is because charAt() only returns a string of length one. This is typically done for comparisons and a string.js object will have little to no value here.

All of the native methods support chaining with the string.js methods.

- template(values, [open], [close])

Takes a string and interpolates the values. Defaults to {{ and }} for Mustache compatible templates. However, you can change this default by modifying S.TMPL_OPEN and S.TMPL_CLOSE.

Example:

var str = "Hello {{name}}! How are you doing during the year of {{date-year}}?"
var values = {name: 'JP', 'date-year': 2013}
console.log(S(str).template(values).s) //'Hello JP! How are you doing during theyearof2013?'
str = "Hello #{name}! How are you doing during the year of #{date-year}?"
console.log(S(str).template(values, '#{', '}').s) //'Hello JP! How are you doing during the year of 2013?'
S.TMPL_OPEN = '{'
S.TMPL_CLOSE = '}'
str = "Hello {name}! How are you doing during the year of {date-year}?"
console.log(S(str).template(values).s) //'Hello JP! How are you doing during theyearof2013?'

- times(n)

Returns a string repeated n times.

Alias: repeat()

Example:

S(' ').times(5).s //' '
S('*').times(3).s //'***'

- toBoolean() / toBool()

Converts a a logical truth string to boolean. That is: true, 1, 'true', 'on', or 'yes'.

- trimRight()

- truncate(length, [chars])

Truncates the string, accounting for word placement and character count.

Example:

S('this is some long text').truncate(3).s //'...'
S('this is some long text').truncate(7).s //'this is...'
S('this is some long text').truncate(11).s //'this is...'
S('this is some long text').truncate(12).s //'this is some...'
S('this is some long text').truncate(11).s //'this is...'
S('this is some long text').truncate(14, ' read more').s //'this is some read more'

+ VERSION

Returns native JavaScript string containing the version of string.js.

Example:

S.VERSION; //1.0.0

Quirks

decodeHtmlEntities() converts &nbsp; to 0xa0 (160) and not 0x10 (20). Most browsers consider 0xa0 to be whitespace characters, Internet Explorer does not despite it being part of the ECMA standard. Google Closure does a good job of normalizing this behavior. This may need to be fixed in string.js at some point in time.

License

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.