dojo/_base/kernel.string

Summary

String utilities for Dojo

Methods

escape(str)

Defined by dojo/string

Efficiently escape a string for insertion into HTML (innerHTML or attributes), replacing &, <, >, ", ', and / characters.

Parameter	Type	Description
str	String	the string to escape

pad(text,size,ch,end)

Defined by dojo/string

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.

Parameter	Type	Description
text	String	the string to pad
size	Integer	length to provide padding
ch	String	Optional character to pad, defaults to '0'
end	Boolean	Optional adds padding at the end if true, otherwise pads at start

Returns: number

Examples

Example 1

// Fill the string to length 10 with "+" characters on the right.  Yields "Dojo++++++".
string.pad("Dojo", 10, "+", true);

rep(str,num)

Defined by dojo/string

Efficiently replicate a string n times.

Parameter	Type	Description
str	String	the string to replicate
num	Integer	number of times to replicate the string

Returns: string | undefined

substitute(template,map,transform,thisObject)

Defined by dojo/string

Performs parameterized substitutions on a string. Throws an exception if any parameter is unmatched.

Parameter	Type	Description
template	String	a string with expressions in the form ${key} to be replaced or ${key:format} which specifies a format function. keys are case-sensitive.
map	Object | Array	hash to search for substitutions
transform	Function	Optional a function to process all parameters before substitution takes place, e.g. mylib.encodeXML
thisObject	Object	Optional where to look for optional format function; default to the global namespace

Returns: undefined

Examples

Example 1

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
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.
string.substitute(
    "File '${name}' is not found in directory '${info.dir}'.",
    { name: "foo.html", info: { dir: "/temp" } }
);

Example 2

Use a transform function to modify the values:

// returns "file 'foo.html' is not found in directory '/temp'."
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 3

Use a formatter

// returns "thinger -- howdy"
string.substitute(
    "${0:postfix}", ["thinger"], null, {
        postfix: function(value, key){
            return value + " -- howdy";
        }
    }
);

trim(str)

Defined by dojo/string

Trims whitespace from both sides of the string

This version of trim() was taken from Steven Levithan's blog. The short yet performant version of this function is dojo/_base/lang.trim(), which is part of Dojo base. Uses String.prototype.trim instead, if available.

Parameter	Type	Description
str	String	String to be trimmed

Returns: String | string

Returns the trimmed string