API Preview tool | The Dojo Toolkit

dojo/_base/lang.js

Provides:
- dojo._base.lang
Requires:
- dojo.lib.kernel in common
dojo
- alias - dojo
Object.toString
- alias - Object.prototype.toString
dojo.isString
- parameters:
  - it: (typeof anything)
- returns
```
Boolean
```
- summary
```
Return true if it is a String
```
- type
```
Function
```

dojo.isArray

parameters:
- it: (typeof anything)
returns
```
Boolean
```

summary

Return true if it is an Array.
Does not work on Arrays created in other windows.

type
```
Function
```

dojo.isFunction
- parameters:
  - it: (typeof anything)
- summary
```
Return true if it is a Function
```
- type
```
Function
```

dojo.isObject

parameters:
- it: (typeof anything)

summary

Returns true if it is a JavaScript object (or an Array, a Function
or null)

type
```
Function
```

dojo.isArrayLike

parameters:
- it: (typeof anything)
returns
```
Boolean
```

summary

similar to dojo.isArray() but more permissive

description

Doesn't strongly test for "arrayness".  Instead, settles for "isn't
a string or number and has a length property". Arguments objects
and DOM collections will return true when passed to
dojo.isArrayLike(), but will return false when passed to
dojo.isArray().

return_summary

If it walks like a duck and quacks like a duck, return `true`

type
```
Function
```

dojo.isAlien

parameters:
- it: (typeof anything)
returns
```
Boolean
```

summary

Returns true if it is a built-in function or some other kind of
oddball that *should* report as a function but doesn't

type
```
Function
```

dojo.extend

parameters:
- constructor: (typeof Object)
- props: (typeof Object)
returns
```
Object
```

summary

Adds all properties and methods of props to constructor's
prototype, making them available to all instances created with
constructor.

type
```
Function
```

dojo._hitchArgs
- parameters:
  - scope
  - method: (typeof ,)
- returns
```
mixed
```
- type
```
Function
```

dojo.hitch

parameters:

scope: (typeof Object)

The scope to use when method executes. If method is a string,
scope is also the object containing method.

method: (typeof Function|String)

A function to be hitched to scope, or the name of the method in
scope to be hitched.

returns
```
Function
```

summary

Returns a function that will only ever execute in the a given scope.
This allows for easy use of object member functions
in callbacks and other places in which the &quot;this&quot; keyword may
otherwise not reference the expected scope.
Any number of default positional arguments may be passed as parameters
beyond &quot;method&quot;.
Each of these values will be used to &quot;placehold&quot; (similar to curry)
for the hitched function.

example

	dojo.hitch(foo, "bar")();
runs foo.bar() in the scope of foo

example

	dojo.hitch(foo, myFunction);
returns a function that runs myFunction in the scope of foo

example

Expansion on the default positional arguments passed along from
hitch. Passed args are mixed first, additional args after.
	var foo = { bar: function(a, b, c){ console.log(a, b, c); } };
	var fn = dojo.hitch(foo, "bar", 1, 2);
	fn(3); // logs "1, 2, 3"

example

	var foo = { bar: 2 };
	dojo.hitch(foo, function(){ this.bar = 10; })();
execute an anonymous function in scope of foo

type
```
Function
```

dojo.delegate

parameters:

obj: (typeof The)

object to delegate to for properties not found directly on the
return object or in props.

props: (typeof an)

object containing properties to assign to the returned object

summary

Returns a new object which &quot;looks&quot; to obj for properties which it
does not have a value for. Optionally takes a bag of properties to
seed the returned object with initially.

description

This is a small implementaton of the Boodman/Crockford delegation
pattern in JavaScript. An intermediate object constructor mediates
the prototype chain for the returned object, using it to delegate
down to obj for property lookup when object-local lookup fails.
This can be thought of similarly to ES4's "wrap", save that it does
not act on types but rather on pure objects.

return_summary
```
an Object of anonymous type
```

example

	var foo = { bar: "baz" };
	var thinger = dojo.delegate(foo, { thud: "xyzzy"});
	thinger.bar == "baz"; // delegated to foo
	foo.thud == undefined; // by definition
	thinger.thud == "xyzzy"; // mixed in from props
	foo.bar = "thonk";
	thinger.bar == "thonk"; // still delegated to foo's bar

type
```
Function
```

dojo._delegate
- type
```
Object
```

dojo._toArray

parameters:

obj: (typeof Object)

the object to &quot;arrayify&quot;. We expect the object to have, at a
minimum, a length property which corresponds to integer-indexed
properties.

offset: (typeof Number)

the location in obj to start iterating from. Defaults to 0.
Optional.

startWith: (typeof Array)

An array to pack with the properties of obj. If provided,
properties in obj are appended at the end of startWith and
startWith is the returned array.

summary

Converts an array-like object (i.e. arguments, DOMCollection) to an
array. Returns a new Array with the elements of obj.

type
```
Function
```

dojo.partial

parameters:
- method: (typeof Function|String)
returns
```
Function
```

summary

similar to hitch() except that the scope object is left to be
whatever the execution context eventually becomes.

description

Calling dojo.partial is the functional equivalent of calling:
	dojo.hitch(null, funcName, ...);

type
```
Function
```

dojo._extraNames
- alias - dojo._extraNames
dojo._extraNames.length
- alias - dojo._extraNames.length

dojo.clone

parameters:
- o: (typeof anything)
returns
```
anything|Node|Date|RegExp|Object
```

summary

Clones objects (including DOM nodes) and all children.
Warning: do not clone cyclic structures.

type
```
Function
```

dojo.trim

parameters:
- str: (typeof String)
```
String to be trimmed
```
returns
```
String
```

summary

Trims whitespace from both sides of the string

return_summary
```
String
Returns the trimmed string
```

description

This version of trim() was selected for inclusion into the base due
to its compact size and relatively good performance
(see [Steven Levithan's blog](http://blog.stevenlevithan.com/archives/faster-trim-javascript)
Uses String.prototype.trim instead, if available.
The fastest but longest version of this function is located at
dojo.string.trim()

type
```
Function
```

dojo.replace

parameters:

tmpl: (typeof String)
```
String to be used as a template.
```

map: (typeof Object|Function)

If an object, it is used as a dictionary to look up substitutions.
If a function, it is called for every substitution with following
parameters: a whole match, a name, an offset, and the whole template
string (see https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/replace
for more details).

pattern: (typeof RegEx)

Optional regular expression objects that overrides the default pattern.
Must be global and match one item. The default is: /\{([^\}]+)\}/g,
which matches patterns like that: &quot;{xxx}&quot;, where &quot;xxx&quot; is any sequence
of characters, which doesn't include &quot;}&quot;.

returns
```
String
```

summary

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

return_summary
```
String
Returns the substituted string.
```

example

	// uses a dictionary for substitutions:
	dojo.replace("Hello, {name.first} {name.last} AKA {nick}!",
	  {
	    nick: "Bob",
	    name: {
	      first:  "Robert",
	      middle: "X",
	      last:   "Cringely"
	    }
	  });
	// returns: Hello, Robert Cringely AKA Bob!

example

	// uses an array for substitutions:
	dojo.replace("Hello, {0} {2}!",
	  ["Robert", "X", "Cringely"]);
	// returns: Hello, Robert Cringely!

example

	// uses a function for substitutions:
	function sum(a){
	  var t = 0;
	  dojo.forEach(a, function(x){ t += x; });
	  return t;
	}
	dojo.replace(
	  "{count} payments averaging {avg} USD per payment.",
	  dojo.hitch(
	    { payments: [11, 16, 12] },
	    function(_, key){
	      switch(key){
	        case "count": return this.payments.length;
	        case "min":   return Math.min.apply(Math, this.payments);
	        case "max":   return Math.max.apply(Math, this.payments);
	        case "sum":   return sum(this.payments);
	        case "avg":   return sum(this.payments) / this.payments.length;
	      }
	    }
	  )
	);
	// prints: 3 payments averaging 13 USD per payment.

example

	// uses an alternative PHP-like pattern for substitutions:
	dojo.replace("Hello, ${0} ${2}!",
	  ["Robert", "X", "Cringely"], /\$\{([^\}]+)\}/g);
	// returns: Hello, Robert Cringely!

type
```
Function
```

dojo._base.lang
- type
```
Object
```
dojo._base
- type
```
Object
```

dojo/_base/lang.js

Provides:

Requires:

dojo

Object.toString

dojo.isString

dojo.isArray

dojo.isFunction

dojo.isObject

dojo.isArrayLike

dojo.isAlien

dojo.extend

dojo._hitchArgs

dojo.hitch

dojo.delegate

dojo._delegate

dojo._toArray

dojo.partial

dojo._extraNames

dojo._extraNames.length

dojo.clone

dojo.trim

dojo.replace

dojo._base.lang

dojo._base