lib/dojo/string.js

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