lib/dojo/string.js.uncompressed.js

   1 define("dojo/string", [
   2         "./_base/kernel",       // kernel.global
   3         "./_base/lang"
   4 ], function(kernel, lang){
   5
   6 // module:
   7 //              dojo/string
   8
   9 var string = {
  10         // summary:
  11         //              String utilities for Dojo
  12 };
  13 lang.setObject("dojo.string", string);
  14
  15 string.rep = function(/*String*/str, /*Integer*/num){
  16         // summary:
  17         //              Efficiently replicate a string `n` times.
  18         // str:
  19         //              the string to replicate
  20         // num:
  21         //              number of times to replicate the string
  22
  23         if(num <= 0 || !str){ return ""; }
  24
  25         var buf = [];
  26         for(;;){
  27                 if(num & 1){
  28                         buf.push(str);
  29                 }
  30                 if(!(num >>= 1)){ break; }
  31                 str += str;
  32         }
  33         return buf.join("");    // String
  34 };
  35
  36 string.pad = function(/*String*/text, /*Integer*/size, /*String?*/ch, /*Boolean?*/end){
  37         // summary:
  38         //              Pad a string to guarantee that it is at least `size` length by
  39         //              filling with the character `ch` at either the start or end of the
  40         //              string. Pads at the start, by default.
  41         // text:
  42         //              the string to pad
  43         // size:
  44         //              length to provide padding
  45         // ch:
  46         //              character to pad, defaults to '0'
  47         // end:
  48         //              adds padding at the end if true, otherwise pads at start
  49         // example:
  50         //      |       // Fill the string to length 10 with "+" characters on the right.  Yields "Dojo++++++".
  51         //      |       string.pad("Dojo", 10, "+", true);
  52
  53         if(!ch){
  54                 ch = '0';
  55         }
  56         var out = String(text),
  57                 pad = string.rep(ch, Math.ceil((size - out.length) / ch.length));
  58         return end ? out + pad : pad + out;     // String
  59 };
  60
  61 string.substitute = function(   /*String*/              template,
  62                                                                         /*Object|Array*/map,
  63                                                                         /*Function?*/   transform,
  64                                                                         /*Object?*/             thisObject){
  65         // summary:
  66         //              Performs parameterized substitutions on a string. Throws an
  67         //              exception if any parameter is unmatched.
  68         // template:
  69         //              a string with expressions in the form `${key}` to be replaced or
  70         //              `${key:format}` which specifies a format function. keys are case-sensitive.
  71         // map:
  72         //              hash to search for substitutions
  73         // transform:
  74         //              a function to process all parameters before substitution takes
  75         //              place, e.g. mylib.encodeXML
  76         // thisObject:
  77         //              where to look for optional format function; default to the global
  78         //              namespace
  79         // example:
  80         //              Substitutes two expressions in a string from an Array or Object
  81         //      |       // returns "File 'foo.html' is not found in directory '/temp'."
  82         //      |       // by providing substitution data in an Array
  83         //      |       string.substitute(
  84         //      |               "File '${0}' is not found in directory '${1}'.",
  85         //      |               ["foo.html","/temp"]
  86         //      |       );
  87         //      |
  88         //      |       // also returns "File 'foo.html' is not found in directory '/temp'."
  89         //      |       // but provides substitution data in an Object structure.  Dotted
  90         //      |       // notation may be used to traverse the structure.
  91         //      |       string.substitute(
  92         //      |               "File '${name}' is not found in directory '${info.dir}'.",
  93         //      |               { name: "foo.html", info: { dir: "/temp" } }
  94         //      |       );
  95         // example:
  96         //              Use a transform function to modify the values:
  97         //      |       // returns "file 'foo.html' is not found in directory '/temp'."
  98         //      |       string.substitute(
  99         //      |               "${0} is not found in ${1}.",
 100         //      |               ["foo.html","/temp"],
 101         //      |               function(str){
 102         //      |                       // try to figure out the type
 103         //      |                       var prefix = (str.charAt(0) == "/") ? "directory": "file";
 104         //      |                       return prefix + " '" + str + "'";
 105         //      |               }
 106         //      |       );
 107         // example:
 108         //              Use a formatter
 109         //      |       // returns "thinger -- howdy"
 110         //      |       string.substitute(
 111         //      |               "${0:postfix}", ["thinger"], null, {
 112         //      |                       postfix: function(value, key){
 113         //      |                               return value + " -- howdy";
 114         //      |                       }
 115         //      |               }
 116         //      |       );
 117
 118         thisObject = thisObject || kernel.global;
 119         transform = transform ?
 120                 lang.hitch(thisObject, transform) : function(v){ return v; };
 121
 122         return template.replace(/\$\{([^\s\:\}]+)(?:\:([^\s\:\}]+))?\}/g,
 123                 function(match, key, format){
 124                         var value = lang.getObject(key, false, map);
 125                         if(format){
 126                                 value = lang.getObject(format, false, thisObject).call(thisObject, value, key);
 127                         }
 128                         return transform(value, key).toString();
 129                 }); // String
 130 };
 131
 132 string.trim = String.prototype.trim ?
 133         lang.trim : // aliasing to the native function
 134         function(str){
 135                 str = str.replace(/^\s+/, '');
 136                 for(var i = str.length - 1; i >= 0; i--){
 137                         if(/\S/.test(str.charAt(i))){
 138                                 str = str.substring(0, i + 1);
 139                                 break;
 140                         }
 141                 }
 142                 return str;
 143         };
 144
 145 /*=====
 146  string.trim = function(str){
 147          // summary:
 148          //             Trims whitespace from both sides of the string
 149          // str: String
 150          //             String to be trimmed
 151          // returns: String
 152          //             Returns the trimmed string
 153          // description:
 154          //             This version of trim() was taken from [Steven Levithan's blog](http://blog.stevenlevithan.com/archives/faster-trim-javascript).
 155          //             The short yet performant version of this function is dojo.trim(),
 156          //             which is part of Dojo base.  Uses String.prototype.trim instead, if available.
 157          return "";     // String
 158  };
 159  =====*/
 160
 161         return string;
 162 });