Extensions to the standard javascript String object

stringextensions.js

/* 
 * Author      : leif.o.olsen
 * Description : Extensions to the standard javascript String object
 */

(function () {
    var methods = {
        /**
         * Check if a string contains a newline character
         * @return {boolean} true if a newline character ocurs in the string
         */
        hasNewLine: function() {
          return (/\n/).test(this);
        },

        /**
         * Check if a string is empty
         * @return {boolean} true if empty
         */
        isEmpty: function() {
          return this == '';
        },

        /**
         * Check if a string only contains whitespaces
         * @return {boolean} true if blank
         */
        isBlank: function() {
          return /^\s*$/.test(this);
        },

        // Removes leading and trailing spaces
        // This method does not change the String object it is called on. It simply returns a new string.
        // See: // See: http://blog.stevenlevithan.com/archives/faster-trim-javascript
        // Example: '  hat    cat  ' returns 'hat    cat'
        trim: function() {
          var s = this.replace(/^\s\s*/, ''),
              i = s.length,
              ws= /\s/;
          if( i ) {
            while (ws.test(s.charAt(--i)));
            return s.slice(0, i + 1);
          }
          return '';
        },

        // trimLeft:
        // Removes leading spaces
        // This method does not change the String object it is called on. It simply returns a new string.
        // Example: '  hat    cat  ' returns 'hat    cat  '
        trimLeft: function() {
          return( this.replace(/^\s\s*/, '') );
        },

        // trimRight:
        // Removes trailing spaces
        // This method does not change the String object it is called on. It simply returns a new string.
        // Example: '  hat    cat  ' returns '  hat    cat'
        trimRight: function() {
          return( this.replace(/\s\s*$/, '') );
        },

        // Removes leading and trailing (white)spaces and
        // replaces interior consecutive spaces with a single space.  If the string contains
        // line breaks then the the line break will be kept in advantage of the space if preserveLineBreaks flag is true.
        // This method does not change the String object it is called on. It simply returns a new string.
        //
        // Example: '  hat    cat  rat   ' -> 'hat cat rat'
        //
        normalizeSpaces: function( preserveFlag ) {
          var preserveNone  = 0, // 00b
              preserveSpace = 1, // 10b
              preserveLbr   = 2; // 01b
              
          preserveFlag = preserveFlag || preserveNone;
          for (var i = 0, lines = this.split("\n"), length = lines.length; i < length; i++) {
            lines[i] = lines[i].trim().replace(/ +/g, ' ');
          }
          return ( preserveFlag & preserveSpace 
            ? lines.join(' ') : preserveFlag & preserveLbr 
            ? lines.join('\n') : lines.join('') ).trim();
        },


        // Returns a value >= 0 if 'token' ocurs in 's', otherwise -1
        // flag     : gim, see JavaScript RegExp documentation
        //                 g - Not applicable, no meaning here
        //                 i - Ignore case
        //                 m - Multiline
        // Example  : this   : 'a String'
        //            token  : 'str'
        //            flag   : i
        //            returns: 2
        //
        indexOfToken: function(token, flag) {
            var result = new RegExp(token||'', flag||'').exec(this); 
            return( result ? result.index : -1 );
        },


        /**
         * Converts a hyphenated string to a camelcase string.
         * Example: "this-is-hypen" --> "thisIsHypen"
         * @return {String} The camelized string
         */
        toCamelCase: function() {
          var s = this;
          for(var exp = /-([a-z])/; exp.test(s); s = s.replace(exp, RegExp.$1.toUpperCase()) );
          return s;
        },

        /**
         * Converts a cameCased string to a hyphenated string.
         * Example: "thisIsCamel" --> "this-is-camel"
         * @return {String} The hypenated string
         */
        toHyphen: function() {
          return this.replace(/([A-Z])/g, "-$1" ).toLowerCase();
        },

        /**
         * Splits name value pairs into an hash array.
         * example: "a:1;b:2;c:3" -> result['a']=1, result['b']=2, result['c']=3
         *    
         * @param {Char} attributeSeparator, default value is ';'
         * @param {Char} nameValueSeparator, default value is ':'
         * 
         * @return {Array} Hash array with name value pairs where name is the index used to get the
         * corresponding value. 
         */
        splitAttributes: function(attributeSeparator, nameValueSeparator) {
          var result=[];
          if( this.length > 0 ) {
            // the '\\s*'+(separator)+'\\s*' ensures that whitespaces are removed from
            // the split. No need to trim name value pairs.
            var attrs = this.split(new RegExp('\\s*'+(attributeSeparator || ';')+'\\s*'));
            var nv = new RegExp('\\s*'+(nameValueSeparator || ':')+'\\s*');
            for(var i=0, j=attrs.length; i<j; i++) {
              var pair = attrs[i].split(nv);
              if(pair && pair.length>1 && pair[1]) {
                result[pair[0]] = pair[1]; 
              } 
            }
          }
          return result;    
        },

        // You supply a template string, in which you add place-holders for values using {0} to {9}, 
        // and then supply up to 9 other arguments which represent the strings to insert. For example:
        // "And the {0} want to know whose {1} you {2}".format("papers", "shirt", "wear"); ==>
        // And the papers want to know whose shirt you wear
        // see: http://code.google.com/p/base2/
        // see: http://frogsbrain.wordpress.com/2007/04/28/javascript-stringformat-method/
        //
        format: function( /* arguments */ ) {
          var pattern = /\{\d+\}/g;
          var args = arguments;
          return this.replace( pattern, function(capture){ 
            return args[capture.match(/\d+/)]; 
          });
        }

    };

    for (var i in methods) {
        if (!String.prototype[i]) String.prototype[i] = methods[i];
    }
})();


(function() {
    console.log("hasNewLine      [" + "A string with \n newline".hasNewLine() + "]");
    console.log("isEmpty         [" + "".isEmpty()                            + "]");
    console.log("isBlank         [" + "     ".isBlank() + "]");
    console.log("indexOfToken    [" + "This is my kittycat.".indexOfToken("cat") + "]");
    console.log("indexOfToken    [" + "This cat is my cat.".indexOfToken("Cat", 'i') + "]");
    console.log("normalizeSpaces [" + '  This    is  my cat.      '.normalizeSpaces() + "]");
    console.log("trim            [" + "    This is my cat.    ".trim() + "]");
    console.log("trimLeft        [" + "    This is my cat.    ".trimLeft() + "]");
    console.log("trimRight       [" + "    This is my cat.    ".trimRight() + "]");
    console.log("toCamelCase     [" + "riding-on-a-camel".toCamelCase() + "]");
    console.log("toHyphen        [" + "ridingOnACamel".toHyphen() + "]");
    var v = "a:1;b:2;c:3".splitAttributes();
    console.log("splitAttributes [" + v['a'] + ", " + v['b'] + ", "+ v['c'] + "]");
    console.log("format          [" + "The quick {0} fox jumps over the lazy {1}".format("brown", "dog") + "]");
}());