source: Dev/branches/rest-dojo-ui/client/dojo/string.js @ 256

define(["./_base/kernel", "./_base/lang"], function(dojo, lang) {
        // module:
        //              dojo/string
        // summary:
        //              TODOC

lang.getObject("string", true, dojo);

/*=====
dojo.string = {
        // summary: String utilities for Dojo
};
=====*/

dojo.string.rep = function(/*String*/str, /*Integer*/num){
        // summary:
        //              Efficiently replicate a string `n` times.
        // str:
        //              the string to replicate
        // num:
        //              number of times to replicate the string

        if(num <= 0 || !str){ return ""; }

        var buf = [];
        for(;;){
                if(num & 1){
                        buf.push(str);
                }
                if(!(num >>= 1)){ break; }
                str += str;
        }
        return buf.join("");    // String
};

dojo.string.pad = function(/*String*/text, /*Integer*/size, /*String?*/ch, /*Boolean?*/end){
        // summary:
        //              Pad a string to guarantee that it is at least `size` length by
        //              filling with the character `ch` at either the start or end of the
        //              string. Pads at the start, by default.
        // text:
        //              the string to pad
        // size:
        //              length to provide padding
        // ch:
        //              character to pad, defaults to '0'
        // end:
        //              adds padding at the end if true, otherwise pads at start
        // example:
        //      |       // Fill the string to length 10 with "+" characters on the right.  Yields "Dojo++++++".
        //      |       dojo.string.pad("Dojo", 10, "+", true);

        if(!ch){
                ch = '0';
        }
        var out = String(text),
                pad = dojo.string.rep(ch, Math.ceil((size - out.length) / ch.length));
        return end ? out + pad : pad + out;     // String
};

dojo.string.substitute = function(      /*String*/              template,
                                                                        /*Object|Array*/map,
                                                                        /*Function?*/   transform,
                                                                        /*Object?*/             thisObject){
        // summary:
        //              Performs parameterized substitutions on a string. Throws an
        //              exception if any parameter is unmatched.
        // template:
        //              a string with expressions in the form `${key}` to be replaced or
        //              `${key:format}` which specifies a format function. keys are case-sensitive.
        // map:
        //              hash to search for substitutions
        // transform:
        //              a function to process all parameters before substitution takes
        //              place, e.g. mylib.encodeXML
        // thisObject:
        //              where to look for optional format function; default to the global
        //              namespace
        // example:
        //              Substitutes two expressions in a string from an Array or Object
        //      |       // returns "File 'foo.html' is not found in directory '/temp'."
        //      |       // by providing substitution data in an Array
        //      |       dojo.string.substitute(
        //      |               "File '${0}' is not found in directory '${1}'.",
        //      |               ["foo.html","/temp"]
        //      |       );
        //      |
        //      |       // also returns "File 'foo.html' is not found in directory '/temp'."
        //      |       // but provides substitution data in an Object structure.  Dotted
        //      |       // notation may be used to traverse the structure.
        //      |       dojo.string.substitute(
        //      |               "File '${name}' is not found in directory '${info.dir}'.",
        //      |               { name: "foo.html", info: { dir: "/temp" } }
        //      |       );
        // example:
        //              Use a transform function to modify the values:
        //      |       // returns "file 'foo.html' is not found in directory '/temp'."
        //      |       dojo.string.substitute(
        //      |               "${0} is not found in ${1}.",
        //      |               ["foo.html","/temp"],
        //      |               function(str){
        //      |                       // try to figure out the type
        //      |                       var prefix = (str.charAt(0) == "/") ? "directory": "file";
        //      |                       return prefix + " '" + str + "'";
        //      |               }
        //      |       );
        // example:
        //              Use a formatter
        //      |       // returns "thinger -- howdy"
        //      |       dojo.string.substitute(
        //      |               "${0:postfix}", ["thinger"], null, {
        //      |                       postfix: function(value, key){
        //      |                               return value + " -- howdy";
        //      |                       }
        //      |               }
        //      |       );

        thisObject = thisObject || dojo.global;
        transform = transform ?
                lang.hitch(thisObject, transform) : function(v){ return v; };

        return template.replace(/\$\{([^\s\:\}]+)(?:\:([^\s\:\}]+))?\}/g,
                function(match, key, format){
                        var value = lang.getObject(key, false, map);
                        if(format){
                                value = lang.getObject(format, false, thisObject).call(thisObject, value, key);
                        }
                        return transform(value, key).toString();
                }); // String
};

/*=====
dojo.string.trim = function(str){
        // summary:
        //              Trims whitespace from both sides of the string
        // str: String
        //              String to be trimmed
        // returns: String
        //              Returns the trimmed string
        // description:
        //              This version of trim() was taken from [Steven Levithan's blog](http://blog.stevenlevithan.com/archives/faster-trim-javascript).
        //              The short yet performant version of this function is dojo.trim(),
        //              which is part of Dojo base.  Uses String.prototype.trim instead, if available.
        return "";      // String
}
=====*/

dojo.string.trim = String.prototype.trim ?
        lang.trim : // aliasing to the native function
        function(str){
                str = str.replace(/^\s+/, '');
                for(var i = str.length - 1; i >= 0; i--){
                        if(/\S/.test(str.charAt(i))){
                                str = str.substring(0, i + 1);
                                break;
                        }
                }
                return str;
        };

return dojo.string;
});