1.1.1. Utility Belt Methods

1.1.2. Quarantined Code Execution

function foo () {
  var bar = 5;
  eval ('var baz = 10; alert (bar);');  // doesn't throw error, but we'd want it to
}

foo ();

function foo () {
  var bar = 5;
  Uize.eval ('var baz = 10; alert (bar);');  // throws an error, as we would like
}

foo ();

evalResultANYTYPE = Uize.eval (codeToEvalSTR);

function foo () {
  var bar = 5;
  Uize.eval ('bar = 10');  // throws an error, because bar is not declared inside eval'd code
  alert (bar);
}

foo ();

evalResultANYTYPE = Uize.laxEval (codeToEvalSTR);

function foo () {
  var bar = 5;
  Uize.laxEval ('bar = 10');  // doesn't throw an error, but doesn't set value of local scope bar
  alert (bar);  // alerts "5", because the quarantined eval'd code didn't set local bar variable
}

foo ();

quarantinedFunctionFUNC = Uize.quarantine (sourceFunctionFUNC);

var bar = 10;

function Foo () {
  var bar = 5;
  this.baz = function () {
    alert (bar);
  };
  this.qux = Uize.quarantine (this.baz);
}

var myFoo = new Foo ();

myFoo.baz ();  // alerts 5, because the baz method has access to the Foo scope
myFoo.qux ();  // alerts 10, because it is quarantined from the Foo scope, and global bar is 10

// code executed before quarantined code

Uize.quarantine (function () {
  // quarantined code execution
}) ();

// code executed after quarantined code

There are no dedicated showcase example pages for the Uize module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize module...

SEARCH

The Uize module defines the Uize package.

1.3.1. Features Introduced in This Module

1.3.2. Features Overridden in This Module

1.3.3. Features Inherited From Other Modules

1.3.4. Modules Directly Under This Namespace

1.3.5. Unit Tests

DIFFERENT USAGES

Add a Single Folder Organized Namespace

Uize.addFolderOrgNamespaces (namespaceSTR);

Add Multiple Folder Organized Namespaces, Specifing Them as a String Array

Uize.addFolderOrgNamespaces (namespacesARRAY);

Add Multiple Folder Organized Namespaces, Specifing Them as Multiple Arguments

Uize.addFolderOrgNamespaces (namespace1STR,namespace2STR,...,namespaceNSTR);

IMPLEMENTATION INFO

Calls the specified list of functions on the specified context, with an optional list of arguments.

The Uize.applyAll method can be useful for executing a list of event handlers, queued callbacks, a chain of constructors, etc.

DIFFERENT USAGES

Call Multiple Functions as Methods on a Context

Uize.applyAll (contextANYTYPE,functionsLIST);

Call Multiple Functions as Methods on a Context, with an Arguments List

Uize.applyAll (contextANYTYPE,functionsLIST,argumentsLIST);

Call Multiple Functions with an Arguments List

Uize.applyAll (0,functionsLIST,argumentsLIST);

2.2.1. Call Multiple Functions as Methods on a Context

Uize.applyAll (contextANYTYPE,functionsLIST);

2.2.2. Call Multiple Functions as Methods on a Context, with an Arguments List

Uize.applyAll (contextANYTYPE,functionsLIST,argumentsLIST);

2.2.3. Call Multiple Functions with an Arguments List

Uize.applyAll (0,functionsLIST,argumentsLIST);

NOTES

IMPLEMENTATION INFO

Recurses through the arbitrarily complex object specified, calling the specified method on all values that are not nully (null or undefined).

This method allows the following...

SYNTAX

Uize.callOn (objectSetARRAYorOBJ,methodSTRorFN);

EXAMPLE

function myPhantomMethod () {
  // do stuff
}

Uize.callOn (
  [instance1,instance2,instance3,instance4,instance5,instance6],myPhantomMethod
);

The above statement would be equivalent to...

function myPhantomMethod () {
  // do stuff
}

myPhantomMethod.call (instance1);
myPhantomMethod.call (instance2);
myPhantomMethod.call (instance3);
myPhantomMethod.call (instance4);
myPhantomMethod.call (instance5);
myPhantomMethod.call (instance6);

This method is most compelling when an object or array contains a dynamic set of instances on which a specific method needs to be called, or on which a specified function needs to be called as a method.

EXAMPLE

var dates = [
  new Date ('05/10/1986'),
  new Date ('01/12/1992'),
  new Date ('10/04/2003'),
  new Date ('07/01/2010')
];

Uize.callOn (
  dates,
  function () {this.setFullYear (this.getFullYear () - 1)}
);

In the above example, the call of the Uize.callOn method would shift all the dates in the dates array back by a year.

VARIATION 1

Uize.callOn (objectSetARRAYorOBJ,methodSTRorFN,argumentsARRAY);

When the optional argumentsARRAY parameter is specified, this set of arguments will be passed when calling the specified method on each of the objects in the set.

EXAMPLE

Uize.callOn (
  [instance1,instance2,instance3,instance4,instance5,instance6],'set',[{enabled:false}]
);

The above statement would be equivalent to...

instance1.set ({enabled:false});
instance2.set ({enabled:false});
instance3.set ({enabled:false});
instance4.set ({enabled:false});
instance5.set ({enabled:false});
instance6.set ({enabled:false});

VARIATION 2

Uize.callOn (instanceOBJ,methodSTRorFN);

When the instanceOBJ parameter is specified in place of the objectSetARRAYorOBJ parameter, and when the value of the instanceOBJ parameter is an instance of a Uize.Class subclass, then the specified method will be called on that instance. If the value of instanceOBJ is null or undefined, then no action will be taken. This is a convenient way to conditionally call a method on an object reference that may be null, when you might otherwise capture a local variable in order to avoid deep dereferencing twice.

INSTEAD OF...

if (page.children.possiblyNonExistentChildWidget) {
  page.children.possiblyNonExistentChildWidget.insertUi ();
}

OR...

var childWidget = page.children.possiblyNonExistentChildWidget;
if (childWidget) childWidget.insertUi ();

USE...

Uize.callOn (page.children.possiblyNonExistentChildWidget,'insertUi');

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is an object that can be extended with custom properties.

SYNTAX

canExtendBOOL = Uize.canExtend (valueANYTYPE);

A value is considered extendable if it is of type "function", or of type "object" and non-null. Function instances can be extended with custom propeerties, and non-null objects can also be extended with custom properties because this encompasses plain objects, instances of custom object classes, and list objects like instances of JavaScript's built-in Array object. Values that are not considered extendable are nully values like null and undefined, and values for JavaScript primitives, like string values, number values, and boolean values.

EXAMPLES

Uize.canExtend ({foo:'bar'});         // returns true
Uize.canExtend (['foo','bar']);       // returns true
Uize.canExtend (function () {});      // returns true
Uize.canExtend (new String ('foo'));  // returns true
Uize.canExtend (new Boolean (true));  // returns true
Uize.canExtend (new Number (42));     // returns true
Uize.canExtend (Uize.Widget);         // returns true
Uize.canExtend (Uize.Widget ());      // returns true

Uize.canExtend ('foo');               // returns false
Uize.canExtend (true);                // returns false
Uize.canExtend (42);                  // returns false
Uize.canExtend (null);                // returns false
Uize.canExtend (undefined);           // returns false

NOTES

IMPLEMENTATION INFO

Returns a string, that is the specified source string with its first letter capitalized.

SYNTAX

firstCharCapitalizedSTR = Uize.capFirstChar (sourceSTR);

Using this method on the value 'width' would produce the result 'Width'. This method is useful when concatenating one string to another, and where it is desirable for the new concatenated string to be camelCase. Consider the following example...

EXAMPLE

_classPrototype.displayPropertyValue = function (_propertyName) {
  this.setNodeValue (
    'valueOf' + Uize.capFirstChar (_propertyName),
    this.get (_propertyName)
  );
};

In the above example, the instance method displayPropertyValue is being defined for a hypothetical widget class. This method accepts a string parameter, being the name of a state property whose value should be displayed in the page in an implied node of the widget, and where the implied node's name is constructed from the prefix 'valueOf' and the name of the state property with its first letter capitalized. Using this method to display the value of a width state property, the value of this property would be displayed in the implied node named valueOfWidth.

NOTES

IMPLEMENTATION INFO

Returns an identical clone of the specified source object.

SYNTAX

clonedObjectOBJ = Uize.clone (objectToCloneOJ);

An object that is cloned from a source object using this method will not be conjoined to the source object.

Spawning an exact copy of an object is not as simple as copying that object's properties over to a new object. That simple approach works fine if the source object is simple and only contains properties with simple string or number types. But, if the source object contains properties that are references to other objects, then the simple approach will give rise to a clone that is not 100% discrete from its source. So, subsequent manipulations within the depths of the clone's structure may be reflected in the source object. The Uize.clone method makes sure to recurse the structure of the source object and create identical new data objects within the clone that match those in the source.

The Uize.clone method supports cloning values of the following types...

When you clone a value that is an instance of the String, Boolean, or Number objects, you get a new instance having the same value as the source - not a simple type of that value. For example, in JavaScript, 5 is not the same as new Number (5). So, when you use Uize.clone to clone new Number (5), you get a new Number instance with the value 5.

NOTES

IMPLEMENTATION INFO

Returns a value, being the result of constraining the specified value within the specified lower and upper limits.

SYNTAX

constrainedValueANYTYPE = Uize.constrain (valueANYTYPE,lowerLimitANYTYPE,upperLimitANYTYPE);

It is acceptable for the value of the lowerLimitANYTYPE parameter to be greater than the value of the upperLimitANYTYPE parameter, and the value of the valueANYTYPE parameter will still be constrained within the specified range - even if the lower and upper limits are swapped. So, for example, the statement Uize.constrain (percent,0,100) would be equivalent to Uize.constrain (percent,100,0).

EXAMPLES

// number constraining
Uize.constrain (-50,0,100);   // returns 0
Uize.constrain (-50,100,0);   // returns 0
Uize.constrain (0,0,100);     // returns 0
Uize.constrain (50,0,100);    // returns 50
Uize.constrain (100,0,100);   // returns 100
Uize.constrain (150,0,100);   // returns 100

// constraining with value types that are coerced to number
Uize.constrain (              // returns Uize.Class ({value:0})
  Uize.Class ({value:-50}),  // coerced to -50
  Uize.Class ({value:0}),    // coerced to 0
  Uize.Class ({value:1000})  // coerced to 100
);

// constraining with strings values
Uize.constrain ('a','b','y'); // returns 'b'
Uize.constrain ('m','b','y'); // returns 'm'
Uize.constrain ('z','b','y'); // returns 'y'

NOTES

IMPLEMENTATION INFO

Lets you copy the properties from one or more source objects into a freshly created object.

DIFFERENT USAGES

Create a Shallow Copy of a Source Object

freshOBJ = Uize.copy (sourceOBJ);

Copy Properties From Multiple Source Objects Into a Fresh Object

freshOBJ = Uize.copy (source1OBJ,source2OBJ,source3OBJ,...);

2.8.1. Create a Shallow Copy of a Source Object

freshOBJ = Uize.copy (sourceOBJ);

2.8.2. Copy Properties From Multiple Source Objects Into a Fresh Object

freshOBJ = Uize.copy (source1OBJ,source2OBJ,source3OBJ,...);

var obj = Uize.copy (
  {foo:'bar',baz:'qux'},
  {baz:'QUX',hello:'world'},
  {foo:'BAR'}
);

{
  foo:'BAR',
  baz:'QUX',
  hello:'world'
}

2.8.3. Null or Undefined Sources Are Ignored

var ajaxRequestParams = Uize.copy (
  ajaxRequestConfig,
  {
    svc:'feed',
    category:'popular',
    page:1,
    qty:50
  },
  hasAuth
    ? {authType:'password',user:userInfo.username,passwd:userInfo.password}
    : null
);

NOTES

IMPLEMENTATION INFO

Lets you copy properties into a target object from a source object.

SYNTAX

referenceToTargetOBJ = Uize.copyInto (targetOBJ,sourceOBJ);

After the property values from sourceOBJ have been copied into targetOBJ, a reference to targetOBJ is returned as the result of the method. This behavior is provided as a convenience, so that this method can be used in larger expressions where the copy is done in place and then the modified target object can be used further (similar in spirit to the in-place increment operator).

EXAMPLE

var
  targetObject = {
    foo:'How unoriginal!'
  },
  sourceObject = {
    bar:'Indeed!'
  }
;

Uize.copyInto (targetObject,sourceObject);

In the above example, after the code has been executed, targetObject will have both foo and bar properties while sourceObject will remain unchanged.

Of course, the JavaScript language allows in-place creation of anonymous objects using what's termed the "literal syntax", so you could also add properties to an object as shown in the example below...

var targetObject = {
  foo:'How unoriginal!'
};

Uize.copyInto (targetObject,{bar:'Indeed!'});

VARIATION

referenceToTargetOBJ = Uize.copyInto (targetOBJ,source1OBJ,source2OBJ,...);

The Uize.copyInto static method accepts an arbitrary number of parameters, so you can conveniently copy more than one source object into the target object.

All parameters after the targetOBJ parameter that are objects will have their properties copied into the target object, in the order in which those parameters appear in the arguments list (ie. left to right), so properties from source objects earlier in the list will be overwritten by values for those same properties from source objects later in the list.

EXAMPLE

var
  targetObject = {},
  sourceObject1 = {foo:'bar',hi:1},
  sourceObject2 = {bye:1,foo:'BAR'}
;
Uize.copyInto (targetObject,sourceObject1,sourceObject2);

In the above example, the targetObject variable will be an object with the contents {foo:'BAR',hi:1,bye:1}.

NOTES

IMPLEMENTATION INFO

Returns an array, being a copy of the specified list object.

SYNTAX

freshARRAY = Uize.copyList (listARRAYorOBJ);

While an array can be copied by using an expression like myArray.concat (), creating a copy of a list object such as a function's arguments object can be a little more cumbersome with an ugly expression like Array.prototype.slice.call (arguments) or [].slice.call (arguments) (if you're OK with creating an empty array for immediate garbage collection).

Expressions like this are hard to remember when you need to conjure them up, and they're equally unpleasant to make sense of when you see them in your code. The Uize.copyList method provides a more semantically elegant way to copy list objects, such as array instances, arguments objects, or any object with a length property whose value is a number - basically, any value that would produce the result true when passed to the Uize.isList static method.

EXAMPLE 1

Uize.copyList ({0:'foo',1:'bar',2:'baz',3:'qux',length:4});  // returns ['foo','bar','baz','qux']

In the above example, a list object is being copied to produce a fresh array containing the elements in the list object. This is a less common usage, but other objects that one may encounter during Web application development that are list objects and that you may want to create array copies of include things like DOM node lists / HTMLCollection instances.

EXAMPLE 2

function alertReversedSortedArgs () {
  alert (Uize.copyList (arguments).sort ().reverse ());  // alerts the text "qux,foo,baz,bar"
}

alertReversedSortedArgs ('foo','bar','baz','qux');

In the above example, the alertReversedSortedArgs function is alerting the reverse-sorted list of arguments that are passed to it. Because the arguments object is not a true array, the Array object's sort and reverse instance methods can't be called on it, but if the arguments list object is copied using the Uize.copyList method, then the sort and reverse methods can be called on the new array that is returned by this method.

NOTES

IMPLEMENTATION INFO

Returns the specified default value if the first argument is nully (ie. its value is null or undefined).

SYNTAX

defaultedValueANYTYPE = Uize.defaultNully (valueANYTYPE,defaultANYTYPE);

In JavaScript, the values null and undefined are technically different, but in many instances in your code you may wish to treat them as equivalent, often when you are defaulting arguments of functions or properties of objects. While you can test to see if a value is either null or undefined by simply comparing the value to undefined in a loose equality (eg. if (myValue == undefined) {...}), certain tools like jslint may complain about that, forcing you to do two explicit strict equality checks (as in if (myValue === null || myValue === undefined) {...}). The Uize.defaultNully method provides a convenient way to perform this type of test and defaulting.

INSTEAD OF...

function (myArgument0,myArgument1) {
  if (myArgument0 === null || myArgument0 === undefined) {
    myArgument0 = 'some default value';
  }
  // do more stuff
}

USE...

function (myArgument0,myArgument1) {
  myArgument0 = Uize.defaultNully (myArgument0,'some default value');
  // do more stuff
}

NOTES

IMPLEMENTATION INFO

Empties out the specified source object or array and returns a reference to the source.

SYNTAX

sourceOBJorARRAY = Uize.emptyOut (sourceOBJorARRAY);

Using this method to empty out an array is equivalent to setting the array's length to 0, while using this method to empty out an object results in all the object's properties being deleted. When the value null or undefined is specified for the sourceOBJorARRAY parameter, then this method will do nothing and simply return the value of the sourceOBJorARRAY parameter.

EXAMPLE

Uize.copyInto (Uize.emptyOut (userData),userDataDefaults);

In the above example, a userData object has accumulated a large amount of user data and we wish to reset it to some initial default state. Because references to the object may be shared by many parts of an application's code, we want to re-initiatialize it by modifying its contents, restoring its state to that of the userDataDefaults object. The Uize.emptyOut method lets us first empty out the object, after which it is passed as the source for the Uize.copyInto method call where we copy back in the contents of the userDataDefaults object.

NOTES

IMPLEMENTATION INFO

Returns a string, being the specified source string escaped so that it can be used as a literal match when constructing a regular expression string.

SYNTAX

escapedRegExpLiteralSTR = Uize.escapeRegExpLiteral (regExpLiteralSTR);

Using this method, any string can be escaped so that it can be used in creating a regular expression where that string can be matched as a literal match. Strings may sometimes contain special regular expression characters, such as the ( (open parenthesis), ) (close parenthesis), . (period), ? (question mark), and other characters that have special meaning in the context of regular expression strings. If you wanted to use a regular expression to match a string that contained any of these special characters, then the special characters would have to be escaped. The Uize.escapeRegExpLiteral method takes care of this for you. Consider the following example...

EXAMPLE

function replaceAllCaseInsensitive (sourceStr,toReplaceStr,replacementStr) {
  return sourceStr.replace (
    new RegExp (Uize.escapeRegExpLiteral (toReplaceStr),'gi'),
    replacementStr
  );
}

In the above example, we are defining a function that will replace all occurrences of a specified string within a source string with the specified replacement string, and where matching is case insensitive.

Now, the replace instance method of JavaScript's String object can accept a string as a match parameter, but when a string is specified the replacement is not case insensitive and is only for the first occurrence. So, we have to use a regular expression to specify what to replace, so that we can make use of the "g" (global) and "i" (case insensitive) regular expression switches. The problem, however, with using a regular expression is that the string to replace may contain regular expression special characters, so we can't just use it as is when creating the RegExp instance - we have to escape the special characters. So, we use the Uize.escapeRegExpLiteral method to escape the string to replace before supplying it to the RegExp object's constructor.

The Uize.escapeRegExpLiteral method can be used to escape any string that is to be treated as a literal match - even literals that are to be combined with other regular expression logic to form more complex regular expressions.

NOTES

IMPLEMENTATION INFO

Lets you perform quarantined code evaluation of the specified JavaScript code string, using JavaScript strict mode.

SYNTAX

evalResultANYTYPE = Uize.eval (codeToEvalSTR);

The Uize.eval method imposes JavaScript strict mode on the code being evaluated. If you need to evaluate code in non-strict mode, use the companion Uize.laxEval method. The Uize.eval method returns any result that was produced by the code being evaluated.

For a detailed discussion of quarantining and to see examples, consult the section Quarantined Code Execution.

NOTES

IMPLEMENTATION INFO

Returns the first record in the specified records array whose contents is a superset of the contents of the specified match object. If no matching record can be found, then this method will return the value null.

SYNTAX

recordOBJ = Uize.findRecord (recordsARRAY,matchOBJ);

This method uses the Uize.findRecordNo static method in its implementation, so consult the reference for that method for further details and for an example.

NOTES

IMPLEMENTATION INFO

Returns an integer, indicating the index in the specified records array of the first record whose contents is a superset of the contents of the specified match object.

SYNTAX

recordNoINT = Uize.findRecordNo (recordsARRAY,matchOBJ);

If no matching record can be found, then this method will return the value -1, unless the optional defaultNoNONNULL parameter is specified.

EXAMPLE

var
  fruits = [
    {
      type:'Apple',
      variety:'Braeburn',
      color:'red'
    },
    {
      type:'Orange',
      variety:'Navel',
      color:'orange'
    },
    {
      type:'Apple',
      variety:'Granny Smith',
      color:'green'
    },
    {
      type:'Apple',
      variety:'Red Delicious',
      color:'red'
    }
  ],
  greenAppleRecordNo = Uize.findRecordNo (fruits,{type:'Apple',variety:'Granny Smith'})
;

In the above example, the variable greenAppleRecordNo will have the value 2.

VARIATION

recordNoINT = Uize.findRecordNo (recordsARRAY,matchOBJ,defaultNoNONNULL);

When the optional defaultNoNONNULL parameter is specified, then the value of this parameter, coerced to a number, will be returned as the result if no match is found. If the value null or undefined is specified for the defaultNoNONNULL parameter, or if its value coerced to a number produces the special value NaN, then it will be treated as -1.

NOTES

IMPLEMENTATION INFO

Iterates over the specified array, arguments object, object, or length range, calling the specified iteration handler for each element or property.

DIFFERENT USAGES

Iterate Over the Elements of An Array

Uize.forEach (sourceARRAY,iterationHandlerSTRorFUNC);

Iterate Over the Arguments of an Arguments Object

Uize.forEach (argumentsOBJ,iterationHandlerSTRorFUNC);

Iterate Over the Properties of an Object

Uize.forEach (sourceOBJ,iterationHandlerSTRorFUNC);

Iterate Over the Integers in a Zero-based Value Range

Uize.forEach (rangeLengthINT,iterationHandlerSTRorFUNC);

Provide a Context for the Iteration Handler

Uize.forEach (sourceARRAYorOBJorINT,iterationHandlerSTRorFUNC,contextANYTYPE);

Iterate Even Over Unassigned Elements of an Array

Uize.forEach (
  sourceARRAYorOBJorINT,
  iterationHandlerSTRorFUNC,
  contextANYTYPE,
  allArrayElementsBOOL
);

2.17.1. Iterate Over the Elements of An Array

Uize.forEach (sourceARRAY,iterationHandlerSTRorFUNC);

var fruits = ['apple','banana','grape','melon','peach','watermelon'];

function createFruitWidget (fruit) {
  // create a widget for the fruit
}

Uize.forEach (fruits,createFruitWidget);

2.17.2. Iterate Over the Arguments of an Arguments Object

Uize.forEach (argumentsOBJ,iterationHandlerSTRorFUNC);

function multiplyAll () {
  var result = 1;
  Uize.forEach (arguments,function (arg) {result *= arg});
  return result;
}

2.17.3. Iterate Over the Properties of an Object

Uize.forEach (sourceOBJ,iterationHandlerSTRorFUNC);

function uppserCaseKeys (obj) {
  Uize.forEach (
    obj,
    function (value,key,source) {
      delete source [key];
      source [key.toUpperCase ()] = value;
    }
  );
}

2.17.4. Iterate Over the Integers in a Zero-based Value Range

Uize.forEach (rangeLengthINT,iterationHandlerSTRorFUNC);

function factorial (n) {
  var result = 1;
  Uize.forEach (n,function (i) {result *= (i + 1)});
  return result;
}

2.17.5. Provide a Context for the Iteration Handler

Uize.forEach (sourceARRAYorOBJorINT,iterationHandlerSTRorFUNC,contextANYTYPE);

Uize.forEach (listItems,listWidget.addItem,listWidget);

2.17.6. Iterate Even Over Unassigned Elements of an Array

// create a sparsely populated array, with a length of 5
var sourceArray = new Array (5);
sourceArray [2] = 'apple';
sourceArray [4] = 'pear';

var valuesSeenA = [];
Uize.forEach (sourceArray,function (value) {valuesSeenA.push (value)});
alert (valuesSeenA);  // alerts "apple,pear"

var valuesSeenB = [];
Uize.forEach (sourceArray,function (value) {valuesSeenB.push (value)},0,true);
alert (valuesSeenB);  // alerts "undefined,undefined,apple,undefined,pear"

2.17.7. Parameters

var fruits = ['apple','banana','grape','melon','peach','watermelon'];
Uize.forEach (
  fruits,
  function (value,key,source) {source [key] = value.toUpperCase ()}
);

['APPLE','BANANA','GRAPE','MELON','PEACH','WATERMELON']

var fruits = ['apple','banana','grape','melon','peach','watermelon'];
Uize.forEach (fruits,'source [key] = value.toUpperCase ()');

['APPLE','BANANA','GRAPE','MELON','PEACH','WATERMELON']

2.17.8. Key Benefits

for (var fruitNo = -1; fruitNo < fruits.length; fruitNo++) {
  createFruitWidget (fruits [fruitNo]);
}

Uize.forEach (fruits,createFruitWidget);

for (var fruitId in fruitsById) {
  createFruitWidget (fruitsById [fruitId]);
}

Uize.forEach (fruitsById,createFruitWidget);

Uize.forEach (fruitsById,function (value,key) {console.log (key + ': ' + value)});

Uize.forEach (fruitsById,"console.log (key + ': ' + value)");

for (var fruitNo = 0; fruitNo < fruits.length; fruitNo++) {
  // do stuff
}

for (var fruitNo = -1, fruitsLength = fruits.length; ++fruitNo < fruitsLength;) {
  // do stuff
}

var results = [];
Uize.forEach (
  5,
  function (value,key,source) {results.push ({value:value,key:key,source:source})}
);

[
  {value:0,key:0,source:5},
  {value:1,key:1,source:5},
  {value:2,key:2,source:5},
  {value:3,key:3,source:5},
  {value:4,key:4,source:5}
]

2.17.9. Some Limitations

NOTES

IMPLEMENTATION INFO

Resolves the specified value to a class, or returns the value undefined if the specified value is null or undefined.

SYNTAX

classOBJ = Uize.getClass (valueANYTYPE);

The Uize.getClass method resolves a value to a class using the following steps...

The Uize.getClass method can be used to resolve either an instance of a class, or a class itself, to a class.

EXAMPLES

// when called with null or undefined

  Uize.getClass (null);                 // returns undefined
  Uize.getClass (undefined);            // returns undefined

// when called with JavaScript primitives

  Uize.getClass (42);                   // returns Number
  Uize.getClass (NaN);                  // returns Number
  Uize.getClass (Infinity);             // returns Number
  Uize.getClass (true);                 // returns Boolean
  Uize.getClass ('foo');                // returns String

// when called with instances of JavaScript objects

  Uize.getClass (new Object ());        // returns Object
  Uize.getClass (new Number (42));      // returns Number
  Uize.getClass (new Boolean (true));   // returns Boolean
  Uize.getClass (new String ('foo'));   // returns String
  Uize.getClass (new RegExp ('\\d+'));  // returns RegExp

// when called with implicitly created instances of JavaScript objects

  Uize.getClass ({foo:'bar'});          // returns Object
  Uize.getClass (['foo','bar']);        // returns Array
  Uize.getClass (/\d+/);                // returns RegExp

// when called with instances of Uize.Class subclasses

  Uize.getClass (Uize.Widget.Bar ());   // returns Uize.Widget.Bar
  Uize.getClass (new Uize.Fade);        // returns Uize.Fade

// when called with object constructors or Uize.Class subclasses

  Uize.getClass (Object);               // returns Object
  Uize.getClass (Number);               // returns Number
  Uize.getClass (Boolean);              // returns Boolean
  Uize.getClass (String);               // returns String
  Uize.getClass (Uize.Widget.Bar);      // returns Uize.Widget.Bar

IMPLEMENTATION INFO

Returns a string value, being an ID that is globally unique in the current window context.

SYNTAX

guidSTR = Uize.getGuid ();

When an instance of a Uize.Class subclass is created, its instanceId instance property is set to a value returned by this method. This method may also be useful in the implementations of subclasses, in situations where it is necessary to stash something in a context shared by different modules of code that need to be able to interoperate without conflicts.

IMPLEMENTATION INFO

Returns an object reference, being a reference to the module of the specified name, or returns the value undefined if no such module is defined.

SYNTAX

moduleOBJ = Uize.getModuleByName (moduleNameSTR);

EXAMPLE

alert (Uize.Widget == Uize.getModuleByName ('Uize.Widget');  // displays the text "true"

In the above example, sssuming that the Uize.Widget module is loaded at the time that the code is executed, the alert statement will display the text "true".

2.20.1. Graceful Failure

VARIATION

modulesByNameOBJ = Uize.getModuleByName ('*');

When the special value '*' (wildcard character) is specified for the moduleNameSTR parameter, then the Uize.getModuleByName method returns an object that serves as a lookup table for all the modules that have been built, where each property's name is the name of a module and each property's value is a reference to the module.

Module name to module reference mappings are added to the object in the order in which the modules are built. Therefore, if you write a for...in loop to iterate through the properties of the object, then you can build up an array of the names of the modules that have been built, in the correct dependency order. And if you execute such code in a Web page, then you can build up a list of all the modules that were built for that page. If the page only loads in a few modules using script tags that are in the page's initial HTML, then the list resulting from executing your code will give an indication of how many additional modules were loaded in dynamically by the module loader mechanism. The list of all the modules built on a page can be used as the basis for creating a JavaScript library file (see JavaScript Libraries).

EXAMPLE

var
  modulesByName = Uize.getModuleByName ('*'),
  modulesBuilt = []
;
for (var moduleName in modulesByName) {
  modulesBuilt.push (moduleName)
}

After the above code has been executed, the modulesBuilt array will contain the names of all the modules that have been built, listed in the order in which they were built.

NOTES

IMPLEMENTATION INFO

Returns a string, representing the relative path from the current document to the folder containing the specified JavaScript module.

SYNTAX

pathToModuleSTR = Uize.getPathToLibrary (moduleFilenameSTR);

Whereas the Uize.pathToResources static property specifies the relative path to the folder containing the "Uize.js" JavaScript module, this method can be used to find the relative path to a different JavaScript module that is being sourced into the document. This can be useful when the JavaScript module implementing a Uize.Class subclass does not reside in the same folder alongside the "Uize.js" file.

This method is useful in the implementation of Uize.Class subclasses that may wish to, in their implementation, make use of image and other support resources located inside the folder that contains the class's JavaScript module. By using this method, a subclass' implementation does not need to know whether or not the document using it is being loaded through HTTP or from the local file system and does not need to impose extra requirements on developers regarding where its JavaScript module is located in relation to documents using it.

VARIATION

pathToModuleSTR = Uize.getPathToLibrary (moduleFilenameSTR,moduleTokenSTR);

When the optional moduleTokenSTR parameter is specified, then the value returned by this method will be the value of the src property for the script tag that sources in the module specified by the moduleFilenameSTR parameter, but with the module filename replaced by the substitution token specified by the moduleTokenSTR parameter. Consider the following example...

EXAMPLE

<script type="text/javascript" src="../js/Uize.js?bld=123"></script>

<script type="text/javascript">
  alert (Uize.getPathToLibrary ('Uize.js','[MODULE]'));  // alerts "../js/[MODULE]?bld=123"
</script>

In the above example, the script tag that sources in the "Uize.js" module has the value "../js/Uize.js?bld=123" specified for its src attribute. By specifying the value '[MODULE]' for the optional moduleTokenSTR parameter in the Uize.getPathToLibrary method call, the text "Uize.js" is replaced with the text "[MODULE]", and the value returned by the Uize.getPathToLibrary method is '../js/[MODULE]?bld=123'.

NOTES

IMPLEMENTATION INFO

Returns a reference to the global object.

SYNTAX

globalOBJ = Uize.global ();

The Uize.global method should be used in situations where you need to access or assign properties on the global object, or to call methods on the global object, and where you need that code to be able to run inside a browser as well as other environments like WSH (Windows Script Host) or NodeJS.

In cases where you need to work with properties of the global object inside a browser, you would typically just reference the window object. However, in non-browser environments where you might run your JavaScript code, the window object is not applicable and usually not defined. To be entirely safe, use the Uize.global method - it will return the window object when you're running the code in a browser, and in other environments it will return their equivalent of the global object.

EXAMPLES

// assign a value to a global property
Uize.global ().myGlobalProperty = 'foo';

// access a global property
alert (Uize.global ().myGlobalProperty);

// delete a global property
delete Uize.global ().myGlobalProperty;

If you are going to be calling the Uize.global method multiple times inside some code to access or assign values to global properties, you can create a local variable that is a reference to the global object. So, the above example could be re-written as...

var _global = Uize.global ();

// assign a value to a global property
_global.myGlobalProperty = 'foo';

// access a global property
alert (_global.myGlobalProperty);

// delete a global property
delete _global.myGlobalProperty;

2.22.1. Defeating Scope Chain Overrides

var foo = 'global scope';

function MyObject () {
  var foo = 'local scope';

  this.alertLocalScopeFoo = function () {
    alert (foo);
  };

  this.alertGlobalScopeFoo = function () {
    alert (Uize.global ().foo);
  };
}

var myObjectInstance = new MyObject ();

myObjectInstance.alertLocalScopeFoo ();   // alerts "local scope"
myObjectInstance.alertGlobalScopeFoo ();  // alerts "global scope"

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value lies within the specified lower and upper limits.

SYNTAX

inRangeBOOL = Uize.inRange (valueANYTYPE,lowerLimitANYTYPE,upperLimitANYTYPE);

It is acceptable for the value of the lowerLimitANYTYPE parameter to be greater than the value of the upperLimitANYTYPE parameter, and the value of the valueANYTYPE parameter will still be constrained within the specified range - even if the lower and upper limits are swapped. So, for example, the statement Uize.inRange (percent,0,100) would be equivalent to Uize.inRange (percent,100,0).

EXAMPLES

// number constraining
Uize.inRange (-50,0,100);     // returns false
Uize.inRange (-50,100,0);     // returns false
Uize.inRange (0,0,100);       // returns true
Uize.inRange (50,0,100);      // returns true
Uize.inRange (100,0,100);     // returns true
Uize.inRange (150,0,100);     // returns false

// inRange testing with value types that are coerced to number
Uize.inRange (                // returns false
  Uize.Class ({value:-50}),  // coerced to -50
  Uize.Class ({value:0}),    // coerced to 0
  Uize.Class ({value:1000})  // coerced to 100
);

// inRange testing with strings values
Uize.inRange ('a','b','y');   // returns false
Uize.inRange ('a','m','y');   // returns false
Uize.inRange ('z','b','y');   // returns false

// in Range testing with dates
Uize.inRange (                // returns false
  new Date ('01/01/1999'),
  new Date ('01/01/2000'),
  new Date ('01/01/2010')
);
Uize.inRange (                // returns true
  new Date ('01/01/2005'),
  new Date ('01/01/2000'),
  new Date ('01/01/2010')
);
Uize.inRange (                // returns false
  new Date ('01/01/2011'),
  new Date ('01/01/2000'),
  new Date ('01/01/2010')
);

2.23.1. Support for Different Value Types

// testing a number against a number range
Uize.inRange (-50,0,100);

// testing a string against a string range
Uize.inRange ('a','b','y');

// testing a date against a date range
Uize.inRange (
  new Date ('01/01/1999'),
  new Date ('01/01/2000'),
  new Date ('01/01/2010')
);

// testing an object against a range expressed using objects
Uize.inRange (
  Uize.Class ({value:-50}),  // coerced to -50
  Uize.Class ({value:0}),    // coerced to 0
  Uize.Class ({value:1000})  // coerced to 100
);

NOTES

IMPLEMENTATION INFO

Returns an integer, indicating the index in the specified array of the first occurrence of the specified value, or returns a string, indicating the name of first property that has the specified value.

DIFFERENT USAGES

Find a Value in an Array

indexINT = Uize.indexIn (sourceARRAY,valueANYTYPE);

Find a Value in an Array, Scanning Backwards From the End

indexINT = Uize.indexIn (sourceARRAY,valueANYTYPE,fromEndBOOL);

Find a Value in an Array, Using Non-strict Comparison

indexINT = Uize.indexIn (sourceARRAY,valueANYTYPE,fromEndBOOL,strictEqualityBOOL);

Find a Property in an Object Having a Specific Value

keySTR = Uize.indexIn (sourceOBJECT,valueANYTYPE,fromEndBOOL,strictEqualityBOOL);

2.24.1. Find a Value in an Array

indexINT = Uize.indexIn (sourceARRAY,valueANYTYPE);

Uize.indexIn (['a','b','c'],'c');      // returns 2
Uize.indexIn (['a','b'],'c');          // returns -1 (no match)
Uize.indexIn (['a','b','b'],'b');      // returns 1 (first occurrence)
Uize.indexIn ([1,7,42,'42',42],'42');  // returns 3 (first strict match)
Uize.indexIn ([1,7,42],'42');          // returns -1 (no strict match)

2.24.2. Find a Value in an Array, Scanning Backwards From the End

indexINT = Uize.indexIn (sourceARRAY,valueANYTYPE,fromEndBOOL);

Uize.indexIn (['a','b','c'],'c',true);      // returns 2
Uize.indexIn (['a','b'],'c',true);          // returns -1 (no match)
Uize.indexIn (['a','b','b'],'b',true);      // returns 2 (first occurrence, from end)
Uize.indexIn ([1,7,42,'42',42],'42',true);  // returns 3 (first strict match, from end)
Uize.indexIn ([1,7,42],'42',true);          // returns -1 (no strict match)

2.24.3. Find a Value in an Array, Using Non-strict Comparison

indexINT = Uize.indexIn (sourceARRAY,valueANYTYPE,fromEndBOOL,strictEqualityBOOL);

Uize.indexIn ([5,9],'9',false,true);       // returns -1 (no strict match)
Uize.indexIn ([5,9,'9'],'9',false,false);  // returns 1 (first non-strict match)
Uize.indexIn ([5,9,'9'],'9',false,true);   // returns 2 (first strict match)
Uize.indexIn ([5,9,'9'],9,false,true);     // returns 1 (first strict match)
Uize.indexIn ([5,'9',9],'9',true,true);    // returns 1 (first strict match, from end)
Uize.indexIn ([5,'9',9],9,true,true);      // returns 2 (first strict match, from end)
Uize.indexIn ([5,'9',9],'9',true,false);   // returns 2 (first non-strict match, from end)
Uize.indexIn ([5,9,'9'],9,true,false);     // returns 2 (first non-strict match, from end)

2.24.4. Find a Property in an Object Having a Specific Value

keySTR = Uize.indexIn (sourceOBJECT,valueANYTYPE,fromEndBOOL,strictEqualityBOOL);

Uize.indexIn (
  {p0:5,p1:9},'9',false,true          // returns -1 (no strict match)
);
Uize.indexIn (
  {p0:5,p1:9,p2:'9'},'9',false,false  // returns 'p1' (first non-strict match)
);
Uize.indexIn (
  {p0:5,p1:9,p2:'9'},'9',false,true   // returns 'p2' (first strict match)
);
Uize.indexIn (
  {p0:5,p1:9,p2:'9'},9,false,true     // returns 'p1' (first strict match)
);
Uize.indexIn (
  {p0:5,p1:'9',p2:9},'9',true,true    // returns 'p1' (first strict match, from end)
);
Uize.indexIn (
  {p0:5,p1:'9',p2:9},9,true,true      // returns 'p2' (first strict match, from end)
);
Uize.indexIn (
  {p0:5,p1:'9',p2:9},'9',true,false   // returns 'p2' (first non-strict match, from end)
);
Uize.indexIn (
  {p0:5,p1:9,p2:'9'},9,true,false     // returns 'p2' (first non-strict match, from end)
);

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is a function arguments object.

SYNTAX

isArgumentsBOOL = Uize.isArguments (valueANYTYPE);

A value is considered an arguments object if, and only if, the value is a reference to an instance of JavaScript's built-in Arguments object. Arguments objects are created when calling functions in JavaScript and are referenced within a called function by the special arguments keyword.

While an arguments object is listy in nature (ie. it is an object having a length property whose value is a number), listy objects that are not instances of JavaScript's Arguments object are not considered arguments objects by the Uize.isArguments method. So, for example, the array ['foo','bar'] is not considered an arguments object, nor is the listy object {0:'foo',1:'bar',length:2}.

The Uize.isArguments method is useful when wanting to distinguish between an arguments object and other listy objects in order to conditionalize the behavior for a function.

EXAMPLES

Uize.isArguments ((function () {return arguments}) ('foo','bar'));  // return true
Uize.isArguments ((function () {return arguments}) ());             // return true

Uize.isArguments (['foo','bar']);                                   // return false
Uize.isArguments ({0:'foo',1:'bar',length:2});                      // return false
Uize.isArguments ({foo:'bar'});                                     // return false
Uize.isArguments (function () {});                                  // return false
Uize.isArguments (/foo/gi);                                         // return false
Uize.isArguments ('foo');                                           // return false
Uize.isArguments (true);                                            // return false
Uize.isArguments (42);                                              // return false
Uize.isArguments (undefined);                                       // return false
Uize.isArguments (null);                                            // return false

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is an instance of the JavaScript Array class.

SYNTAX

isArrayBOOL = Uize.isArray (valueANYTYPE);

This method is a useful abstraction to deal with the fact that the instanceof Array test fails on arrays that are passed across frames, iframes, or windows. The method returns true if the instanceof Array test passes, or if the specified value is an object and has a property named splice that is a function (the splice method is unique to arrays and its name is unique enough that the likelihood of an object having this property and it being a function is quite low).

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is a boolean.

SYNTAX

isBooleanBOOL = Uize.isBoolean (valueANYTYPE);

This method tests if the specified value is a boolean primitive, so this method will return false if the value being tested is an instance of JavaScript's built-in Boolean object.

EXAMPLES

Uize.isBoolean (true);                 // returns true
Uize.isBoolean (false);                // returns true

Uize.isBoolean (new Boolean (true));   // returns false
Uize.isBoolean ('true');               // returns false
Uize.isBoolean (5);                    // returns false
Uize.isBoolean (NaN);                  // returns false
Uize.isBoolean (null);                 // returns false
Uize.isBoolean (undefined);            // returns false
Uize.isBoolean ();                     // returns false
Uize.isBoolean ({foo:'bar'});          // returns false
Uize.isBoolean (['foo','bar']);        // returns false
Uize.isBoolean (Uize.Widget ());       // returns false
Uize.isBoolean (function () {});       // returns false
// etc.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified object or array is empty.

SYNTAX

isEmptyBOOL = Uize.isEmpty (valueANYTYPE);

The valueANYTYPE parameter can be an Object reference, an Array reference, a Function reference, or any other type. For object type values that are references to Object instances, the Uize.isEmpty method returns true if the object has no keys. For an array type value, Uize.isEmpty returns true if the array has no elements (ie. a length of 0). For any other type of value, Uize.isEmpty returns true if the value is equivalent to false.

EXAMPLES

Uize.isEmpty ({});                   // returns true
Uize.isEmpty ([]);                   // returns true
Uize.isEmpty ('');                   // returns true
Uize.isEmpty (0);                    // returns true
Uize.isEmpty (false);                // returns true
Uize.isEmpty (null);                 // returns true
Uize.isEmpty (undefined);            // returns true
Uize.isEmpty (NaN);                  // returns true

Uize.isEmpty ({blah:0});             // returns false
Uize.isEmpty (['blah']);             // returns false
Uize.isEmpty ('blah');               // returns false
Uize.isEmpty (1);                    // returns false
Uize.isEmpty (true);                 // returns false
Uize.isEmpty (function () {});       // returns false

For object type values that are references to instances of objects other than Object (such as the String, Boolean, and Number objects, or Uize.Class subclasses), the object type value will first be resolved to a value by calling the valueOf Instrinsic Method of the object, and this resolved value will then be evaluated according the rules described above. Consider the following examples...

EXAMPLES

Uize.isEmpty (new String (''));         // returns true
Uize.isEmpty (new Number (0));          // returns true
Uize.isEmpty (new Boolean (false));     // returns true
Uize.isEmpty (Uize.Class ({value:0}));  // returns true

Uize.isEmpty (new String ('blah'));     // returns false
Uize.isEmpty (new Number (0));          // returns false
Uize.isEmpty (new Boolean (true));      // returns false
Uize.isEmpty (Uize.Class ({value:1}));  // returns false

Using Uize.isEmpty (objectOrArray) has better performance than the expression !Uize.totalKeys (objectOrArray), because the latter expression iterates through all the keys of the object or elements of the array to count the total.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is a function.

SYNTAX

isFunctionBOOL = Uize.isFunction (valueANYTYPE);

This method is a useful abstraction to deal with some issues with detecting function type values using the traditional typeof value == 'function' approach in different Web browsers, as listed below...

2.29.1. Regular Expressions Masquerading as Functions

alert (/(\d+)/ ('Space 1999 was an awesome show') [1]);  // alerts the text "1999"

2.29.2. Functions From Other Windows

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value can be found within the specified array (or values of an object's properties).

SYNTAX

isInBOOL = Uize.isIn (sourceARRAYorOBJ,valueANYTYPE);

VARIATION

isInBOOL = Uize.isIn (sourceARRAYorOBJ,valueANYTYPE,strictEqualityBOOL);

By default, this method tests for a match using strict equality. When the value false is specified for the optional strictEqualityBOOL parameter, then this method will test for a match using loose equality (ie. where the string value '1' would be considered equal to the number value 1, or the number value 0 would be considered equal to the boolean value false).

EXAMPLE

Uize.isIn ([0,1,2,3,4,5],'3');               // returns false
Uize.isIn ([0,1,2,3,4,5],'3',false);         // returns true
Uize.isIn ({prop1:'foo',prop2:1},'foo');     // returns true
Uize.isIn ({prop1:'foo',prop2:1},'1');       // returns false
Uize.isIn ({prop1:'foo',prop2:1},'1',false); // returns true (non-strict equality test)

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is a reference to an instance of a UIZE class.

SYNTAX

isInstanceBOOL = Uize.isInstance (valueANYTYPE);

This method can be useful when implementing methods that may be called on a class as well as on an instance of a class.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is considered a list.

SYNTAX

isListBOOL = Uize.isList (valueANYTYPE);

A list is considered to be a non-null value of type 'object' that has a length property whose value is a number. By this definition, an instance of JavaScript's built-in Array object is considered to be a list. Also by this definition, a NodeList instance as returned by the document.getElementsByTagName method is considered to be a list, since it is a non-null object type value with a number type length property.

The Uize.isList method is useful when implementing methods that are to conditionalize their behavior based upon the type of a parameter, and where an iteration behavior is desired for list type values. If a value is considered to be a list, its list items can be iterated over using a standard JavaScript for loop, using the length property to determine how many items should be iterated over, and indexing into the list using JavaScript's [] (square brackets) notation.

EXAMPLES

alert (Uize.isList (['foo','bar','hello','world']));        // alerts "true"
alert (Uize.isList (document.getElementsByTagName ('a')));  // alerts "true"

alert (Uize.isList ({foo:'bar',hello:'world'}));            // alerts "false"
alert (Uize.isList (42));                                   // alerts "false"
alert (Uize.isList (true));                                 // alerts "false"
alert (Uize.isList ('foo');                                 // alerts "false"
alert (Uize.isList (null);                                  // alerts "false"
alert (Uize.isList (undefined);                             // alerts "false"
alert (Uize.isList (/\d+/));                                // alerts "false"
alert (function () {});                                     // alerts "false"

// an object is only considered a list once it has a length property that is a number
var fooObj = {0:'foo',1:'bar',2:'hello',3:'world'};
alert (Uize.isList (fooObj));                               // alerts "false"
fooObj.length = '4';
alert (Uize.isList (fooObj));                               // alerts "false"
fooObj.length = 4;
alert (Uize.isList (fooObj));                               // alerts "true"

// the arguments variable inside functions is considered to be a list
function fooFunc () {
  alert (Uize.isList (arguments));                         // alerts "true"
}
fooFunc ('foo','bar','hello','world');

NOTES

IMPLEMENTATION INFO

Returns a boolean value, indicating whether or not the specified value is the JavaScript special value NaN.

SYNTAX

isNaNBOOL = Uize.isNaN (valueANYTYPE);

2.33.1. There's Something About NaN

// using the Uize.isNaN method, you get these results...

Uize.isNaN (NaN);               // returns true

Uize.isNaN (function () {});    // returns false (a function is not NaN)
Uize.isNaN (new Number (NaN));  // returns false (a Number object is not NaN)
Uize.isNaN (new Date ('foo'));  // returns false (a Date object is not NaN)
Uize.isNaN (undefined);         // returns false
Uize.isNaN (null);              // returns false
Uize.isNaN ('foo');             // returns false
Uize.isNaN ('');                // returns false
Uize.isNaN ('42');              // returns false
Uize.isNaN (42);                // returns false
Uize.isNaN (true);              // returns false
Uize.isNaN ({});                // returns false
Uize.isNaN ([]);                // returns false


// in contrast, JavaScript's built-in isNaN function produces these results

isNaN (NaN);                    // returns true (hallelujah!)

isNaN (undefined);              // returns true (undefined coerces to NaN)
isNaN ('foo');                  // returns true ('foo' coerces to NaN)
isNaN ({});                     // returns true ({} coerces to NaN)
isNaN (function () {});         // returns true (a function coerces to NaN)
isNaN (new Number (NaN));       // returns true (new Number (NaN) coerces to NaN)
isNaN (new Date ('foo'));       // returns true (an invalid date coerces to NaN)

isNaN (null);                   // returns false (null coerces to 0)
isNaN ('42');                   // returns false ('42' coerces to 42)
isNaN (true);                   // returns false (true coerces to 1)
isNaN ('');                     // returns false ('' coerces to 0)
isNaN ([]);                     // returns false ([] coerces to '', which coerces to 0)

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is null or undefined.

SYNTAX

isNullyBOOL = Uize.isNully (valueANYTYPE);

In JavaScript, the values null and undefined are technically different, but in many instances in your code you may wish to treat them as equivalent, often when you are defaulting arguments of functions or properties of objects. Now, you can test to see if a value is either null or undefined by simply comparing the value to undefined in a loose equality (eg. if (myValue == undefined) {...}), but certain tools like jslint may complain about that, forcing you to do two explicit strict equality checks (as in if (myValue === null || myValue === undefined) {...}). This can be tedious when you have a long deferencing, so the Uize.isNully method can be useful and more concise in such cases.

INSTEAD OF...

if (myObject.subObject.property === null || myObject.subObject.property === undefined) {
  // ...
}

USE...

if (Uize.isNully (myObject.subObject.property)) {
  // ...
}

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is a number.

SYNTAX

isNumberBOOL = Uize.isNumber (valueANYTYPE);

This method is a useful abstraction to deal with the fact that the division of zero by zero in JavaScript yields a special kind of value know as NaN. Unfortunately, in the implementation of this special value, the result chosen for when the typeof operator is applied to it is 'number' (ie. typeof NaN == 'number' produces true). The Uize.isNumber method checks that both the type of the parameter is 'number' and also that the parameter is not NaN.

Also note that this method tests if the specified value is a number primitive, so this method will return false if the value being tested is an instance of JavaScript's built-in Number object.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is an object.

SYNTAX

isObjectBOOL = Uize.isObject (valueANYTYPE);

Using JavaScript's built-in typeof operator, the type of the value null is reported as being 'object'. This can be less than useful when trying to conditionalize code to operate on object type values by dereferencing properties, as attempting to dereference properties off the value null will produce JavaScript errors. The Uize.isObject method provides a more useful and semantically more intuitive way of testing if a value is a non-null object.

INSTEAD OF...

if (typeof myValue == 'object' && myValue !== null) {
  // ...
}

USE...

if (Uize.isObject (myValue)) {
  // ...
}

Note that because arrays in JavaScript are derived from the language's built-in Object object, array values are reported as being objects by this method.

EXAMPLES

Uize.isObject ({foo:'bar'});          // returns true
Uize.isObject (['foo','bar']);        // returns true
Uize.isObject (new Boolean (false));  // returns true
Uize.isObject (new String ('foo'));   // returns true
Uize.isObject (new Number (5));       // returns true
Uize.isObject (new Date);             // returns true
Uize.isObject (Uize.Widget ());       // returns true

Uize.isObject (null);                 // returns false
Uize.isObject (undefined);            // returns false
Uize.isObject ();                     // returns false
Uize.isObject (5);                    // returns false
Uize.isObject (NaN);                  // returns false
Uize.isObject ('foo');                // returns false
Uize.isObject (true);                 // returns false
Uize.isObject (function () {});       // returns false

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is a plain object (an instance of JavaScript's built-in Object object).

SYNTAX

isPlainObjectBOOL = Uize.isPlainObject (valueANYTYPE);

Plain objects are often used as very simple data structures in JavaScript. Sometimes it is desirable to conditionalize the behavior of a function or method, based upon whether an object type value is a plain data structure object or an instance of a custom object (such as an instance of a Date object, or an instance of a Uize.Class subclass). In such cases, the Uize.isPlainObject method provides a convenient way to detect if a value is a reference to a plain object.

EXAMPLES

Uize.isPlainObject ({});                   // returns true
Uize.isPlainObject ({foo:'bar'});          // returns true
Uize.isPlainObject (new Object ());        // returns true

Uize.isPlainObject (['foo','bar']);        // returns false
Uize.isPlainObject (new Boolean (false));  // returns false
Uize.isPlainObject (new String ('foo'));   // returns false
Uize.isPlainObject (new Number (5));       // returns false
Uize.isPlainObject (new Date);             // returns false
Uize.isPlainObject (Uize.Widget ());       // returns false
Uize.isPlainObject (null);                 // returns false
Uize.isPlainObject (undefined);            // returns false
Uize.isPlainObject ();                     // returns false
Uize.isPlainObject (5);                    // returns false
Uize.isPlainObject (NaN);                  // returns false
Uize.isPlainObject ('foo');                // returns false
Uize.isPlainObject (true);                 // returns false
Uize.isPlainObject (function () {});       // returns false

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is one of JavaScript's built-in primitive types: string, boolean, or number.

SYNTAX

isPrimitiveBOOL = Uize.isPrimitive (valueANYTYPE);

EXAMPLES

Uize.isPrimitive (true);                 // returns true
Uize.isPrimitive (false);                // returns true
Uize.isPrimitive ('foo');                // returns true
Uize.isPrimitive ('');                   // returns true
Uize.isPrimitive (42);                   // returns true
Uize.isPrimitive (0);                    // returns true

Uize.isPrimitive (new Boolean (true));   // returns false
Uize.isPrimitive (new String (foo));     // returns false
Uize.isPrimitive (new Number (42));      // returns false
Uize.isPrimitive (null);                 // returns false
Uize.isPrimitive (undefined);            // returns false
Uize.isPrimitive ();                     // returns false
Uize.isPrimitive ({foo:'bar'});          // returns false
Uize.isPrimitive (['foo','bar']);        // returns false
Uize.isPrimitive (Uize.Widget ());       // returns false
Uize.isPrimitive (function () {});       // returns false
// etc.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is a regular expression (ie. an instance of JavaScript's built-in RegExp object).

SYNTAX

isRegExpBOOL = Uize.isRegExp (valueANYTYPE);

EXAMPLES

Uize.isRegExp (/^\d+$/);                // returns true
Uize.isRegExp (new RegExp ('^\\d+$'));  // returns true

Uize.isRegExp (true);                   // returns false
Uize.isRegExp ('foo');                  // returns false
Uize.isRegExp (42);                     // returns false
Uize.isRegExp (new Boolean (true));     // returns false
Uize.isRegExp (new String (foo));       // returns false
Uize.isRegExp (new Number (42));        // returns false
Uize.isRegExp (null);                   // returns false
Uize.isRegExp (undefined);              // returns false
Uize.isRegExp ();                       // returns false
Uize.isRegExp ({foo:'bar'});            // returns false
Uize.isRegExp (['foo','bar']);          // returns false
Uize.isRegExp (Uize.Widget ());         // returns false
Uize.isRegExp (function () {});         // returns false
// etc.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is the same as another value in a strict equality test, but also supporting comparison of the JavaScript special value NaN.

SYNTAX

isSameAsBOOL = Uize.isSameAs (valueANYTYPE,otherValueANYTYPE);

EXAMPLES

Uize.isSameAs ('foo','foo');          // returns true
Uize.isSameAs ('','');                // returns true
Uize.isSameAs (42,42);                // returns true
Uize.isSameAs (Infinity,Infinity);    // returns true
Uize.isSameAs (NaN,NaN);              // returns true
Uize.isSameAs (false,false);          // returns true
Uize.isSameAs (null,null);            // returns true
Uize.isSameAs (undefined,undefined);  // returns true

Uize.isSameAs (null,undefined);       // returns false
Uize.isSameAs (null,NaN);             // returns false
Uize.isSameAs ('',0);                 // returns false
Uize.isSameAs (1,true);               // returns false
Uize.isSameAs ('true',true);          // returns false
Uize.isSameAs ('foo','');             // returns false
Uize.isSameAs ('null',null);          // returns false
Uize.isSameAs ('42',42);              // returns false
Uize.isSameAs ({},{});                // returns false (different object references)
Uize.isSameAs ([],[]);                // returns false (different array references)

2.40.1. NaN is the Same as NaN

var
  valueA = NaN,
  valueB = NaN
;
alert (valueA === valueB);              // alerts "false"
alert (Uize.isSameAs (valueA,valueB));  // alerts "true"

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified value is a string.

SYNTAX

isStringBOOL = Uize.isString (valueANYTYPE);

This method tests if the specified value is a string primitive, so this method will return false if the value being tested is an instance of JavaScript's built-in String object.

EXAMPLES

Uize.isString ('foo');                // returns true
Uize.isString ('');                   // returns true

Uize.isString (new String ('foo'));   // returns false
Uize.isString (5);                    // returns false
Uize.isString (NaN);                  // returns false
Uize.isString (true);                 // returns false
Uize.isString (null);                 // returns false
Uize.isString (undefined);            // returns false
Uize.isString ();                     // returns false
Uize.isString ({foo:'bar'});          // returns false
Uize.isString (['foo','bar']);        // returns false
Uize.isString (Uize.Widget ());       // returns false
Uize.isString (function () {});       // returns false
// etc.

NOTES

IMPLEMENTATION INFO

Returns an array, representing the keys (property names) of the specified object.

SYNTAX

keysARRAY = Uize.keys (objectOBJ);

EXAMPLE

var
  personRecord = {
    firstName:'John',
    lastName:'Wilkey',
    addressStreet:'1 Shiny House Way',
    addressCity:'Richville',
    addressState:'CA',
    addressZip:'91234'
  },
  myKeys = Uize.keys (personRecord)
;

After the above code has executed, the myKeys variable will have the value ['firstName', 'lastName', 'addressStreet', 'addressCity', 'addressState', 'addressZip'].

NOTES

IMPLEMENTATION INFO

Lets you perform quarantined code evaluation of the specified JavaScript code string, but not in JavaScript strict mode.

SYNTAX

evalResultANYTYPE = Uize.laxEval (codeToEvalSTR);

The Uize.laxEval method evaluates the specified code string in non-strict mode. If you would prefer to evaluate code in JavaScript strict mode, use the companion Uize.eval method. The Uize.laxEval method returns any result that was produced by the code being evaluated.

For a detailed discussion of quarantining and to see examples, consult the section Quarantined Code Execution.

NOTES

IMPLEMENTATION INFO

Returns a lookup object, where each key is a value from the specified values array.

DIFFERENT USAGES

Create a Lookup From a Values Array

lookupOBJ = Uize.lookup (valuesARRAY);

Create a Lookup Object With a Custom Lookup Value

lookupOBJ = Uize.lookup (valuesARRAY,lookupValueANYTYPE);

Create a Safe Lookup Object From a Values Array

safeLookupOBJ = Uize.lookup (valuesARRAY,lookupValueANYTYPE,safeBOOL);

Add More Entries to a Lookup Object

lookupOBJ = Uize.lookup (valuesARRAY,lookupValueANYTYPE,targetLookupOBJ);

Create an Empty Safe Lookup Object

emptyLookupOBJ = Uize.lookup (null,1,true);

2.44.1. Create a Lookup From a Values Array

lookupOBJ = Uize.lookup (valuesARRAY);

var
  fruits = ['apple','peach','pear','banana','orange','mango'],
  fruitsLookup = Uize.lookup (fruits)
;

{apple:true,peach:true,pear:true,banana:true,orange:true,mango:true}

2.44.2. Create a Lookup Object With a Custom Lookup Value

lookupOBJ = Uize.lookup (valuesARRAY,lookupValueANYTYPE);

var
  fruits = ['apple','peach','pear','banana','orange','mango'],
  foodsLookup = Uize.lookup (fruits,'fruit')
;

{apple:'fruit',peach:'fruit',pear:'fruit',banana:'fruit',orange:'fruit',mango:'fruit'}

2.44.3. Create a Safe Lookup Object From a Values Array

safeLookupOBJ = Uize.lookup (valuesARRAY,lookupValueANYTYPE,safeBOOL);

var
  values = ['foo','bar'],
  unsafeLookup = Uize.lookup (values),
  safeLookup = Uize.lookup (values,true,true)
;
if (unsafeLookup ['valueOf']) alert ('unsafe');
if (!safeLookup ['valueOf']) alert ('safe');

2.44.4. Add More Entries to a Lookup Object

lookupOBJ = Uize.lookup (valuesARRAY,lookupValueANYTYPE,targetLookupOBJ);

var
  fruits = ['apple','apricot','orange','peach','pear','watermelon'],
  vegetables = ['beet','broccoli','cauliflower','onion','potato','squash'],
  grains = ['barley','maize','oats','quinoa','rice','sorghum','wheat']
  foodLookup = Uize.lookup (fruits,'fruit')
;
Uize.lookup (vegetables,'vegetable',foodLookup); // stitch in keys for vegetables
Uize.lookup (grains,'grain',foodLookup);         // stitch in keys for grains

alert (foodLookup ['apricot']);   // alerts "fruit"
alert (foodLookup ['broccoli']);  // alerts "vegetable"
alert (foodLookup ['quinoa']);    // alerts "grain"

2.44.5. Create an Empty Safe Lookup Object

emptyLookupOBJ = Uize.lookup (null,1,true);

2.44.6. A Real World Example

function getValuesInMasterList (values,masterList) {
  var result = [];
  for (var valueNo = -1; ++valueNo < values.length;) {
    var value = values [valueNo];
    if (Uize.isIn (masterList,value)) result.push (value);
  }
  return result;
}

function getValuesInMasterList (values,masterList) {
  var
    result = [],
    masterListLookup = Uize.lookup (masterList)
  ;
  for (var valueNo = -1; ++valueNo < values.length;) {
    var value = values [valueNo];
    if (masterListLookup [value]) result.push (value);
  }
  return result;
}

NOTES

IMPLEMENTATION INFO

Iterates through the specified array (or object), executing the specified mapper expression or function for each element (or object property), and packages the results into an array (or object).

SYNTAX

mappedARRAYorOBJ = Uize.map (sourceARRAYorOBJorINT,mapperSTRorFUNC);

The Uize.map method is very vertatile and can be used to accomplish a wide array of different tasks. Sure, you could do all the things you could do with Uize.map by writing your own loops. This method serves as a convenience, making certain operations more concise in application code.

The example below, which takes a source array of strings and produces a new array of those strings uppercased, illustrates the difference between writing your own iterator and using the Uize.map method.

INSTEAD OF...

var newArray = [];
for (var elementNo = 0; elementNo < sourceArray.length; elementNo++) {
  newArray.push (sourceArray [elementNo].toUpperCase ());
}

USE...

var newArray = Uize.map (sourceArray,'value.toUpperCase ()');

OR USING A FUNCTION...

var newArray = Uize.map (
  sourceArray,function (value) {return value.toUpperCase ()}
);

Another example below - which generates an array seeded with the values 0 to 99 - further illustrates the convenience of the Uize.map method...

INSTEAD OF...

var newArray = [];
for (var elementNo = 0; elementNo < 100; elementNo++) {
  newArray.push (elementNo);
}

USE...

var newArray = Uize.map (100,'key');

OR USING A FUNCTION...

var newArray = Uize.map (100,function (value,key) {return key});

2.45.1. Key Benefits

VARIATION

mappedARRAYorOBJ = Uize.map (
  sourceARRAYorOBJorINT,
  mapperSTRorFUNC,
  targetARRAYorOBJorBOOL
);

By default, the Uize.map method maps values of the source array or object and packages the result into a new array or object. Specifying the optional targetARRAYorOBJorBOOL parameter allows you to explicitly specify a target for the operation, into which the mapped values will be packaged.

2.45.2. Parameters

2.45.3. More Examples

Uize.map (array,'+value',false);

Uize.map (array,'value + ""',false);

Uize.map (surveyQuestions,'value || "--- no answer provided ---"',false);

var uppercased = Uize.map (array,'value.toUpperCase ()');

Uize.map (array,'"prefix_" + value',false);

var copyOfFoo = Uize.map (foo,'value');

var range0to99 = Uize.map (100,'key');

var range1to100 = Uize.map (100,'key + 1');

var squaresOf0to99 = Uize.map (100,'Math.sqrt (key)');

var squaresOfArray = Uize.map (array,Math.sqrt);

var capLetters = Uize.map (26,'String.fromCharCode (65 + key)');

var powersOf2 = Uize.map (10,'Math.pow (2,key)');

var fibonacci = Uize.map (30,'key > 1 ? this [key - 2] + this [key - 1] : key');

var smoothed = Uize.map (
  array,
  'key && key < this.length - 1 ? (this [key-1] + value + this [key+1]) / 3 : value'
);

Uize.map (logArray,'console.log (value)');

Uize.map (logArray,'console.log (key + ": " + value)');

var coordsStyleProperties = Uize.map (coords,'value + "px"');

// EXAMPLE
// this... {left:0,top:50,width:100,height:175}
// produces this... {left:'0px',top:'50px',width:'100px',height:'175px'}

var maxStringLength = Uize.max (Uize.map (stringsArray,'value.length'));

NOTES

IMPLEMENTATION INFO

Returns the maximum value from the specified array or object.

SYNTAX

var maxValueNUM = Uize.max (valuesARRAYorOBJ);

When an object is specified for the valuesARRAYorOBJ parameter, then the maximum property value in the object will be returned.

EXAMPLE

var
  employeeSalaries = {
    'John Anderson':80000,
    'Peter Hendriks':56000,
    'Jacob Previn':75000,
    'Scarlet Sjedsondorf':63000
  },
  maxEmployeeSalary = Uize.max (employeeSalaries)
;

In the above example, the variable maxEmployeeSalary will be left with the value 80000.

NOTES

IMPLEMENTATION INFO

Returns an object that is created by melding together the specified keys array and values array.

SYNTAX

resultOBJ = Uize.meldKeysValues (keysARRAY,valuesARRAY);

The Uize.meldKeysValues method iterates through the elements of the keysARRAY and valuesARRAY arrays in lock step, assigning properties to the resulting object using an element from the keys array as property name and an element from the values array as property value.

If you obtained a keys array from an object using the Uize.keys method, and if you also obtained a values array from that same object using the Uize.values method, then you could use the Uize.meldKeysValues method with those keys and values arrays to recreate the original object.

EXAMPLE

var
  foodInfoKeys = ['apple','banana','beet','corn','potato','rice']
  foodInfoValues = ['fruit','fruit','vegetable','grain','vegetable','grain'],
  foodInfo = Uize.meldKeysValues (foodInfoKeys,foodInfoValues)
;

In the above example, keys from the foodInfoKeys array are being melded with values from the foodInfoValues array to form a value for the foodInfo object. After this code has executed, the foodInfo object will have the following contents...

{
  apple:'fruit',
  banana:'fruit',
  beet:'vegetable',
  corn:'grain',
  onion:'vegetable',
  rice:'grain'
}

2.47.1. Surplus Keys or Values Ignored

var object = Uize.meldKeysValues (['foo','hello'],['bar']);

var object = Uize.meldKeysValues (['foo'],['bar','world']);

NOTES

IMPLEMENTATION INFO

Merges the contents of multiple source objects together into a fresh object.

SYNTAX

freshOBJ = Uize.merge (source1OBJ,source2OBJ,source3OBJ,...);

EXAMPLE

var result = Uize.merge (
  {foo:{bar:{hello:'world'}}},
  {foo:{bar:{boo:'yah'}}},
  null,
  {foo:{baz:'qux'},voo:'doo'}
);

RESULT

{
  foo:{
    bar:{
      hello:'world',
      boo:'yah'
    },
    baz:'qux'
  },
  voo:'doo'
}

2.48.1. Same Merging Behavior as the Uize.mergeInto Method

NOTES

IMPLEMENTATION INFO

Merges the contents of one or more source objects into the specified target object, and returns the target object as the result.

DIFFERENT USAGES

Merge the Contents of a Source Object Into a Target Object

targetOBJ = Uize.mergeInto (targetOBJ,sourceOBJ);

Merge Multiple Source Objects Into a Target Object

targetOBJ = Uize.mergeInto (targetOBJ,source1OBJ,source2OBJ,...,sourceNOBJ);

2.49.1. Merge the Contents of a Source Object Into a Target Object

targetOBJ = Uize.mergeInto (targetOBJ,sourceOBJ);

var
  targetObject = {
    foo:'bar',
    anArray:[0,1,2],
    junk:{
      hey:'there',
      moreJunk:{
        simple:'simon'
      }
    }
  },
  sourceObject = {
    foo:'BAR',
    anArray:['a','b','c'],
    junk:{
      boo:'yah',
      moreJunk:{
        peter:'pan',
        evenMoreJunk:{
          silly:'sausage'
        }
      }
    }
  }
;
Uize.mergeInto (targetObject,sourceObject);

{
  foo:'BAR',
  anArray:['a','b','c'],
  junk:{
    hey:'there',
    moreJunk:{
      simple:'simon',
      peter:'pan',
      evenMoreJunk:{
        silly:'sausage'
      }
    },
    boo:'yah'
  }
}

2.49.2. Merge Multiple Source Objects Into a Target Object

targetOBJ = Uize.mergeInto (targetOBJ,source1OBJ,source2OBJ,...,sourceNOBJ);

var
  targetObject = {
    foo:'bar',
    anArray:[0,1,2],
    junk:{
      hey:'there',
      moreJunk:{
        simple:'simon'
      }
    }
  },
  sourceObject1 = {
    foo:'BAR',
    anArray:['a','b','c'],
    junk:{
      boo:'yah',
      moreJunk:{
        peter:'pan',
        evenMoreJunk:{
          silly:'sausage'
        }
      }
    }
  },
  sourceObject2 = {
    hello:'world',
    anArray:['A','B','C'],
    junk:{
      yo:'wassup'
    }
  },
  sourceObject3 = {
    foo:'BAR!!!',
    junk:{
      moreJunk:{
        evenMoreJunk:{
          bite:'me'
        }
      }
    }
  }
;
Uize.mergeInto (targetObject,sourceObject1,sourceObject2,sourceObject3);

{
  foo:'BAR!!!',
  anArray:['A','B','C'],
  hello:'world',
  junk:{
    hey:'there',
    moreJunk:{
      simple:'simon',
      peter:'pan',
      evenMoreJunk:{
        silly:'sausage',
        bite:'me'
      },
    },
    boo:'yah',
    yo:'wassup'
  }
}

2.49.3. Merging Rules

var result = Uize.mergeInto (
  {foo:{bar:{hello:'world'}}},
  {foo:{bar:{boo:'yah'}}}
);

{foo:{bar:{hello:'world',boo:'yah'}}}

function CustomObject (value) {this.value = value}

var
  customObject1 = new CustomObject (5),
  customObject2 = new CustomObject (42)
;
customObject1.foo = 'bar';
customObject2.hello = 'world';

var result = Uize.mergeInto (
  {prop:customObject1},
  {prop:customObject2}
);

var
  targetObject = {foo:'bar'},
  sourceObject = {aMissingNode:{hello:'world'}}
;
Uize.mergeInto (targetObject,sourceObject);

alert (targetObject.aMissingNode === sourceObject.aMissingNode);  // alerts "true"

var
  targetObject = {someProperty:'foo'},
  sourceObject = {someProperty:{hello:'world'}}
;
Uize.mergeInto (targetObject,sourceObject);

alert (targetObject.someProperty === sourceObject.someProperty);  // alerts "true"

Uize.mergeInto (
  {foo:'bar',junk:{hello:'world'}},
  null,
  {foo:'BAR'},
  undefined,
  {junk:{simple:'simon'}}
);

{foo:'BAR',junk:{hello:'world',simple:'simon'}}

NOTES

IMPLEMENTATION INFO

Returns the minimum value from the specified array or object.

SYNTAX

var minValueNUM = Uize.min (valuesARRAYorOBJ);

When an object is specified for the valuesARRAYorOBJ parameter, then the minimum property value in the object will be returned.

EXAMPLE

var
  employeeSalaries = {
    'John Anderson':80000,
    'Peter Hendriks':56000,
    'Jacob Previn':75000,
    'Scarlet Sjedsondorf':63000
  },
  minEmployeeSalary = Uize.min (employeeSalaries)
;

In the above example, the variable minEmployeeSalary will be left with the value 56000.

NOTES

IMPLEMENTATION INFO

Lets you declare a module in the UIZE JavaScript Framework.

DIFFERENT USAGES

Declare a Module by Specifying a Module Definition Object

Uize.module (moduleDefinitionOBJ);

Declare a Namespace Module by Specifying Just the Namespace as a String

Uize.module (namespaceSTR);

2.51.1. Declare a Module by Specifying a Module Definition Object

Uize.module (moduleDefinitionOBJ);

{
  name:moduleNameSTR,           // omit for anonymous modules
  superclass:superclassNameSTR, // omit for package modules, or if host is superclass
  required:modulesSTRorARRAY,   // omit when only host and superclass are required
  builder:builderFUNC           // omit for library modules and namespace modules
}

2.51.2. Declare a Namespace Module by Specifying Just the Namespace as a String

Uize.module (namespaceSTR);

Uize.module ({name:'MyCompanyName.MySectionNamespace'});

Uize.module ('MyCompanyName.MySectionNamespace');

For an in-depth discussion of modules, consult the guide JavaScript Modules.

NOTES

IMPLEMENTATION INFO

Loads the specified JavaScript module (specified by its module name) and calls the specified callback function once the module has been loaded.

SYNTAX

Uize.moduleLoader (moduleNameSTR,callbackFUNC);

The callback specified by the callbackFUNC parameter is called with a single parameter that represents the code of the module specified by the moduleNameSTR parameter, unless the module loader loads modules by adding script tags to the page (in which case the callback is called with no parameters).

EXAMPLE

Uize.moduleLoader = function (_moduleToLoad,_callback) {
  m._commObject.request ({
    url:[m.get ('env').service + 'getjs',{filename:_moduleToLoad + '.js'}],
    returnType:'json',
    requestMethod:'GET',
    callback:function (_responseObject) {
      _callback (_responseObject.moduleCode);
    }
  });
};

For an in-depth discussion of modules, consult the guide JavaScript Modules.

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Returns a string, representing the URL path from where the specified JavaScript module (specified by its module name) can be loaded.

SYNTAX

moduleUrlSTR = Uize.moduleUrlResolver (moduleNameSTR);

By overriding this static method, you have the flexibility to have different types of modules load from different locations. A classic example would be loading modules of the UIZE JavaScript Framework from a shared CDN (Content Delivery Network) location, while loading modules that are in your own Web site's namespace from the same machine that serves the pages. Consider the following example...

EXAMPLE

Uize.moduleUrlResolver = function (_moduleName) {
  var _modulePath = Uize.modulePathResolver (_moduleName);
  return (
    moduleName.indexOf ('MyDomain.') == 0
      ? '/js/' + _modulePath + '.js'
      : 'http://www.some-cdn.com/uize-js/' + _modulePath + '.js'
  );
};

In the above example, a custom module URL resolver is being specified. It looks at the module name, determines if the module name is in the namespace for the Web site (MyDomain in this example), and returns a root relative URL. Otherwise, assuming that all other modules are part of the UIZE JavaScript Framework and are stored on a CDN, it returns a URL for where the module would be located on that CDN Web site.

The module URL returned by your function will be used by the built-in Uize.moduleLoader module loader function. If you override the built-in module loader by specifying your own value for the Uize.moduleLoader static method, then the Uize.moduleUrlResolver static method will only be applicable if your custom module loader uses this method. Similarly, the built-in Uize.moduleUrlResolver implementation uses the Uize.moduleUrlTemplate static property. So, if you supply your own custom module URL resolver by overriding the Uize.moduleUrlResolver static method, then it is your choice as to whether or not you use the value of the Uize.moduleUrlTemplate property.

For an in-depth discussion of modules, consult the guide JavaScript Modules.

NOTES

IMPLEMENTATION INFO

Returns a function that is an object constructor that will construct an object using the specified constructor function, with JavaScript's new operator being optional when creating instances of the object.

SYNTAX

objectConstructorFUNC = Uize.noNew (constructorFunctionFUNC);

Normally, when creating instances of objects in JavaScript, the new operator must be used in conjunction with the constructor function, as in the statement var date = new Date (). The Uize.noNew method can be used to wrap any existing object constructor function, to create an object constructor where JavaScript's new operator will be optional when creating an instance of the object by calling the constructor.

EXAMPLE

// define the Food object
var Food = Uize.noNew (
  function (name,type) {
    this.name = name;
    this.type = type;
  }
);

// create an instance of Food using the new operator
var apple = new Food ('apple','fruit');
alert (apple.type);  // alerts the text "fruit"

// create an instance of Food without using the new operator
var rice = Food ('rice','grain');
alert (rice.type);  // alerts the text "grain"

In the above example, the Food object is being defined by using the Uize.noNew method to wrap a constructor function. Then, one instance of this object is created using the new operator, while another instance is created without using new. Both instances are fully fledged Food object instances and behave in exactly the same way.

2.55.1. Properties Aren't Transferred

// define Food object
function Food (name,type) {
  this.name = name;
  this.type = type;
}

// define instance methods
Food.prototype.isFruit = function () {return this.type == 'fruit'};
Food.prototype.isGrain = function () {return this.type == 'grain'};

// define static methods
Food.isFruit = function (food) {return food && food.isFruit ()};
Food.isGrain = function (food) {return food && food.isGrain ()};

// wrap Food constructor to make new operator optional -- TOO LATE!!!
Food = Uize.noNew (Food);

// define Food object, already wrapped to make new operator optional
var Food = Uize.noNew (
  function (name,type) {
    this.name = name;
    this.type = type;
  }
);

// define instance methods
Food.prototype.isFruit = function () {return this.type == 'fruit'};
Food.prototype.isGrain = function () {return this.type == 'grain'};

// define static methods
Food.isFruit = function (food) {return food && food.isFruit ()};
Food.isGrain = function (food) {return food && food.isGrain ()};

IMPLEMENTATION INFO

A dummy function that performs no operation and returns no value (which is effectively the same as returning the value undefined).

SYNTAX

resultUNDEF = Uize.nop ();

The Uize.nop method is named after the NOP (No Operation Performed) assembly language instruction. This method can be provided as a callback to methods that require a callback function and may fail if one is not provided, but where you don't need anything to be executed in the callback. You could always provide your own empty anonymous function, but Uize.nop is provided for your convenience and it can be shared across all instances where an empty function needs to be provided.

EXAMPLE

serviceRequest ({
  serviceParams:{
    // service params here
  },
  callback:Uize.nop
});

NOTES

IMPLEMENTATION INFO

Returns an integer, representing the current time in milliseconds since 1970 (POSIX time).

SYNTAX

nowMsINT = Uize.now ();

The Uize.now method is optimized to use the Date.now static method that is supported by JavaScript's built-in Date object in newer versions of the language. If this method is not available, then the Uize.now method falls back to using the less performant +new Date approach, which involves construction of a Date object instance each time.

The Uize.now method can be useful when capturing start and end times in order to measure the duration of operations. Consider the following example...

EXAMPLE

var start = Uize.now ();

// ... ... ... ... ... ... ... ... ... ... ...
// do some stuff that may take a bunch of time
// ... ... ... ... ... ... ... ... ... ... ...

var duration = Uize.now () - start;

Using the above template, the value of the duration variable will indicate how long it took to perform the operations in the block between assigning the value for the start variable and the value for the duration variable.

IMPLEMENTATION INFO

Lets you conveniently create a JavaScript package with a specified set of statics (static methods and/or static properties) in a single statement.

SYNTAX

packageFUNC = Uize.package (staticsOBJ);

The Uize.package method provides a more concise way of defining and returning a package function inside a module's builder function.

INSTEAD OF...

builder:function () {
  'use strict';

  var _package = function () {};

  _package.staticMethod1 = function () {
    // implementation
  };

  _package.staticMethod2 = function () {
    // implementation
  };

  return _package;
}

USE...

builder:function () {
  'use strict';

  return Uize.package ({
    staticMethod1:function () {
      // implementation
    },

    staticMethod2:function () {
      // implementation
    }
  });
}

For a more in-depth discussion of package modules, consult the JavaScript Modules guide.

NOTES

IMPLEMENTATION INFO

Returns an object, that is the specified key and value, paired up together in the same object.

SYNTAX

keyValueOBJ = Uize.pairUp (keySTRorNUM,valueANYTYPE);

EXAMPLE

Uize.pairUp ('foo','bar');  // returns the object {foo:'bar'}
Uize.pairUp (0,'zero');     // returns the object {0:'zero'}
Uize.pairUp (1,true);       // returns the object {1:true}

VARIATION 1

keyValueOBJ = Uize.pairUp (
  key1STRorNUM,value1ANYTYPE,
  key2STRorNUM,value2ANYTYPE,
  ...,
  keyNSTRorNUM,valueNANYTYPE
);

When an arbitrary number of arguments are specified for the Uize.pairUp method, then the method will pair up all the arguments as key/value pairs to form a single object, where all the even index arguments are treated as the keys, and where all the odd index arguments are treated as the values. For example, the statement Uize.pairUp ('foo','bar','hello','world') would return the object {foo:'bar',hello:'world'}.

VARIATION 2

keyValueOBJ = Uize.pairUp (keyAndValuePairsARRAY);

When a keyAndValuePairsARRAY parameter is specified when calling the Uize.pairUp method, then the Uize.pairUp method operates on the array in the same way as it would an arbitrary number of arguments. For example, the statement Uize.pairUp (['foo','bar','hello','world']) would return the object {foo:'bar',hello:'world'}. Therefore, if you have an array that represents a set of key / value pairs, you can call the Uize.pairUp method to combine the keys and values together to form an object without having to resort to using the apply method in order to use the arbitrary arguments variation of the Uize.pairUp method.

INSTEAD OF...

Uize.pairUp.apply (0,myKeyValuePairsArray);

USE...

Uize.pairUp (myKeyValuePairsArray);

2.59.1. Why This Method is Useful

var object = {};
object [key] = value;
doSomethingWithAnObject (object);

doSomethingWithAnObject (Uize.pairUp (key,value));

function fadeNodeBorderColor (node,edge,startColor,endColor) {
  var styleProperty = 'border' + edge + 'Color';
  Uize.Fx.fadeStyle (
    node,
    Uize.pairUp (styleProperty,startColor),
    Uize.pairUp (styleProperty,endColor),
    1000
  );
}

NOTES

IMPLEMENTATION INFO

Pushes / appends the elements from the specified source list onto the end of the specified target list, and returns the target list as the result.

SYNTAX

targetListARRAYorOBJ = Uize.push (targetListARRAYorOBJ,sourceListARRAYorOBJ);

While the elements from a source list object can be appended at the end of a target array with an expression like targetArray.push.apply (targetArray,sourceList), appending the elements from a source list object at the end of a target list object is even a little more cumbersome with ugly expressions like Array.prototype.push.apply (targetList,sourceList) or [].push.apply (targetList,sourceList) (if you're OK with creating an empty array for immediate garbage collection).

Expressions like this are hard to remember when you need to conjure them up, and they're equally unpleasant to make sense of when you see them in your code. The Uize.push method provides a more semantically elegant way to push the elements of a source list onto the end of a target list, allowing both the source and target to be list objects like array instances, arguments objects, or any object with a length property whose value is a number - basically, any value that would produce the result true when passed to the Uize.isList static method.

EXAMPLE 1

Uize.push (allOfTheNodes,document.getElementsByTagName ('div'));

In the above example, the elements from the HTMLCollection object returned by the document.getElementById method are being pushed onto the end of the allOfTheNodes array.

EXAMPLE 2

var
  registeredFruits = [],
  fruitRegistered = {}
;

function registerFruits () {
  Uize.push (registeredFruits,arguments);
  Uize.lookup (arguments,1,fruitRegistered);
}

registerFruits ('apple','pear','peach');
registerFruits ('banana','orange','mango');

alert (registeredFruits);       // alerts "apple,pear,peach,banana,orange,mango"
alert (fruitRegistered.apple);  // alerts "1"
alert (fruitRegistered.mango);  // alerts "1"

In the above example, the registerFruits variadic function allows any number of fruits to be registered by specifying the names of the fruits using an arbitrarily long arguments list. The function uses the Uize.push method to push the contents of the arguments list object onto the end of the registeredFruits array. It also uses the Uize.lookup method to add entries for the fruits being added to the fruitRegistered lookup object, by specifying the fruitRegistered object as the target for the lookup creation operation.

NOTES

IMPLEMENTATION INFO

Returns a function, being a quarantined version of the supplied function.

SYNTAX

quarantinedFunctionFUNC = Uize.quarantine (sourceFunctionFUNC);

For a detail discussion on this method and to see examples, consult the section Quarantined Nested Functions. For a more general discussion on quarantining, consult the section Quarantined Code Execution.

NOTES

IMPLEMENTATION INFO

Returns a boolean, indicating whether or not the specified record's contents is a superset of the contents of the specified match object.

SYNTAX

isMatchBOOL = Uize.recordMatches (recordOBJ,matchOBJ);

EXAMPLE

Uize.recordMatches (
  {
    firstName:'Jack',
    lastName:'Lerchner',
    department:'engineering',
    jobTitle:'UI Engineer',
    status:'contract'
  }
  {jobTitle:'UI Engineer',status:'fulltime'}
);

In the above example, the expression would produce the result false, because the value of the status property in the matchOBJ parameter does not match the value for that property in the recordOBJ parameter.

NOTES

IMPLEMENTATION INFO

Ensures that all of the specified modules are loaded before calling the specified callback function, loading required modules as necessary.

The Uize.require method can be used to load required modules, as necessary, before executing code that depends on those modules being loaded.

DIFFERENT USAGES

Require a Single Module

Uize.require (moduleNameSTR,callbackFUNC);

Require Multiple Modules

Uize.require (moduleNamesARRAY,callbackFUNC);

Require Modules With No Callback

Uize.require (moduleNameSTRorModuleNamesARRAY);

2.63.1. Require a Single Module

Uize.require (moduleNameSTR,callbackFUNC);

Uize.require (
  'Uize.Widget.Bar.Slider',
  function (Slider) {
    var mySlider = Slider ({
      minValue:-50,
      maxValue:50,
      value:0
    });
  }
);

Uize.require (
  'Uize.Widget.Bar.Slider',
  function () {
    var mySlider = Uize.Widget.Bar.Slider ({
      minValue:-50,
      maxValue:50,
      value:0
    });
  }
);

2.63.2. Require Multiple Modules

Uize.require (moduleNamesARRAY,callbackFUNC);

Uize.require (
  [
    'Uize.Widget.Bar.Slider',
    'Uize.Data.Csv',
    'Uize.Color'
  ],
  function (
    Uize_Widget_Bar_Slider,
    Uize_Data_Csv,
    Uize_Color
  ) {
    // reference the Uize.Widget.Bar.Slider module by Uize_Widget_Bar_Slider
    // reference the Uize.Data.Csv module by Uize_Data_Csv
    // reference the Uize.Color module by Uize_Color
  }
);

2.63.3. Require Modules With No Callback

Uize.require (moduleNameSTRorModuleNamesARRAY);

Uize.require ([
  'Uize.Widget.Bar.Slider',
  'Uize.Data.Csv',
  'Uize.Color'
]);

2.63.4. The callbackFUNC Parameter

Uize.require (
  [
    'MyNamespace.MyModule1',
    'MyNamespace.MyModule2'
  ],
  function (
    MyNamespace_MyModule1,
    MyNamespace_MyModule2
  ) {
    // reference the MyNamespace.MyModule1 module by MyNamespace_MyModule1
    // reference the MyNamespace.MyModule2 module by MyNamespace_MyModule2
  }
);

2.63.5. Requiring Nothing

Uize.require (
  [],
  function () {
    // code here is executed immediately, because no modules need to be loaded
  }
);

2.63.6. Equivalent to Anonymous Modules

Uize.module ({
  required:[
    'MyNamespace.MyModule1',
    'MyNamespace.MyModule2'
  ],
  builder:function () {
    // code here can rely on MyNamespace.MyModule1 and MyNamespace.MyModule2 being loaded
  }
});

Uize.require (
  [
    'MyNamespace.MyModule1',
    'MyNamespace.MyModule2'
  ],
  function () {
    // code here can rely on MyNamespace.MyModule1 and MyNamespace.MyModule2 being loaded
  }
);

For an in-depth discussion of modules, consult the guide JavaScript Modules.

NOTES

IMPLEMENTATION INFO

Resolves the specified matcher to a function that can be passed two arguments, value and key, and that returns a value derived from one or both of those inputs.

SYNTAX

matcherFUNC = Uize.resolveMatcher (matcherANYTYPE);

The Uize.resolveMatcher method is intended to be used in the implementation of other methods that want to allow a matcher to be specified in several different forms (such as an expression string, for example), but always want to use the matcher as a function. Examples of such methods include the various methods of the Uize.Data.Matches module, such as the Uize.Data.Matches.remove method whose second argument is a matcher. The Uize.resolveMatcher method allows such methods to be versatile in how they let matchers be specified.

EXAMPLE

function findMatches (array,matcher) {
  matcher = Uize.resolveMatcher (matcher);
  var matches = [];
  for (var elementNo = -1; ++elementNo < array.length;) {
    var elementValue = array [elementNo];
    if (matcher (elementValue)) {
      matches.push (elementValue);
    }
  }
  return matches;
}

In the above example, we are implementing a simple function to find the elements in an array that match a specified matcher and return those matches in a new array. The second argument of the function is a matcher. To allow users of the function to specify a matcher using an expression string short form, we resolve the value of the matcher argument using the Uize.resolveMatcher method and re-assign the resolved value to the matcher argument. Once resolved, we can now count on the matcher being a function and we can call it in the loop that iterates over the source array. Now a caller can call this function with statements like...

findMatches (possibleNumbers,'typeof value == "number"');
findMatches (possibleIdentifiers,/^[_\$a-zA-Z][_\$a-zA-Z0-9]*$/);

2.64.1. How Different Matcher Types are Resolved

var isValidIdentifier = Uize.resolveMatcher (/^[_\$a-zA-Z][_\$a-zA-Z0-9]*$/);

alert (isValidIdentifier (''));         // alerts "false"
alert (isValidIdentifier ('fooVar'));   // alerts "true"
alert (isValidIdentifier ('$foo'));     // alerts "true"
alert (isValidIdentifier ('3rdVar'));   // alerts "false"
alert (isValidIdentifier ('_4thVar'));  // alerts "true"

NOTES

IMPLEMENTATION INFO

Resolves the specified module definition object by defaulting its properties and expanding them as necessary, returning the resolved definition object.

SYNTAX

moduleDefinitionOBJ = Uize.resolveModuleDefinition (moduleDefinitionOBJ);

The Uize.resolveModuleDefinition method is not intended for use in general application development but is intended for specialized build processes, such as dependency tracing performed during the creation of JavaScript packages.

For an in-depth discussion of modules, consult the guide JavaScript Modules.

NOTES

IMPLEMENTATION INFO

Resolves the specified transformer to a function that can be passed two arguments, value and key, and that returns a value derived from one or both of those inputs.

SYNTAX

transformerFUNC = Uize.resolveTransformer (transformerANYTYPE);

The Uize.resolveTransformer method is intended to be used in the implementation of other methods that want to allow a transformer to be specified in several different forms (such as an expression string, for example), but always want to use the transformer as a function. An example of one such method is the Uize.map method, whose second argument is a mapper transformer. The Uize.resolveTransformer method allows such methods to be versatile in how they let transformers be specified.

EXAMPLE

function simpleArrayMap (array,mapper) {
  mapper = Uize.resolveTransformer (mapper);
  var result = [];
  for (var elementNo = array.length; --elementNo >= 0;) {
    result [elementNo] = mapper (array [elementNo]);
  }
  return result;
}

In the above example, we are implementing a simple array mapper function. The second argument of the function is a mapper. To allow users of the function to specify a mapper using an expression string short form, we resolve the value of the mapper argument using the Uize.resolveTransformer method and re-assign the resolved value to the mapper argument. Once resolved, we can now count on the mapper being a function and we can call it in the loop that processes the source array. Now a caller can call this function with a statement like simpleArrayMap (fruits,'value.toLowerCase ()').

2.66.1. How Different Transformer Types are Resolved

var squared = Uize.resolveTransformer ('value * value');

alert (squared (3));  // alerts the text "9"

var isValidIdentifier = Uize.resolveTransformer (/^[_\$a-zA-Z][_\$a-zA-Z0-9]*$/);

alert (isValidIdentifier (''));         // alerts "false"
alert (isValidIdentifier ('fooVar'));   // alerts "true"
alert (isValidIdentifier ('$foo'));     // alerts "true"
alert (isValidIdentifier ('3rdVar'));   // alerts "false"
alert (isValidIdentifier ('_4thVar'));  // alerts "true"

var whatFoodType = Uize.resolveTransformer ({
  apple:'fruit',
  banana:'fruit',
  beet:'vegetable',
  corn:'grain',
  onion:'vegetable',
  rice:'grain'
});

alert (whatFoodType ('apple'));   // alerts "fruit"
alert (whatFoodType ('onion'));   // alerts "vegetable"
alert (whatFoodType ('rice'));    // alerts "grain"
alert (whatFoodType ('burger'));  // alerts "burger"

NOTES

IMPLEMENTATION INFO

A dummy function that always returns the boolean value false, and that can be useful as an event handler or in other situations.

SYNTAX

falseBOOL = Uize.returnFalse ();

This method can be assigned to event handlers to cancel their default action, as in the following example...

EXAMPLE

myNode.onclick = Uize.returnFalse;

If you are cancelling the default action for many nodes in a page, then using this static method allows you to share a single function - by reference - across all these nodes.

NOTES

IMPLEMENTATION INFO

A dummy function that always returns the boolean value true, and that can be useful as an event handler or in other situations.

SYNTAX

trueBOOL = Uize.returnTrue ();

This method can be assigned to event handlers to enable their default action, as in the following example...

EXAMPLE

myNode.onclick = Uize.returnTrue;

If you are enabling the default action for many nodes in a page, then using this static method allows you to share a single function - by reference - across all these nodes.

NOTES

IMPLEMENTATION INFO

A dummy function that accepts a single argument x and returns the value of that argument unchanged.

SYNTAX

xANYTYPE = Uize.returnX (xANYTYPE);

NOTES

IMPLEMENTATION INFO

Returns a reverse lookup object, where each key is a value from the specified source object, and where the value for each key is the associated key from the specified source.

DIFFERENT USAGES

Create a Reverse Lookup From an Object

reverseLookupOBJ = Uize.reverseLookup (hashOBJ);

Create a Reverse Lookup From a Values Array

reverseLookupOBJ = Uize.reverseLookup (valuesARRAY);

Create a Safe Reverse Lookup Object

reverseLookupOBJ = Uize.reverseLookup (hashOBJorValuesARRAY,safeBOOL);

Add More Entries to a Reverse Lookup Object

targetOBJ = Uize.reverseLookup (hashOBJorValuesARRAY,targetOBJ);

Create a Bi-directional Lookup

reverseLookupOBJ = Uize.reverseLookup (lookupOBJ,lookupOBJ);

2.70.1. Create a Reverse Lookup From an Object

reverseLookupOBJ = Uize.reverseLookup (hashOBJ);

var
  entitiesNamesToCodes = {quot:34,amp:38,lt:60,gt:62,nbsp:160,copy:169,reg:174},
  entitiesCodesToNames = Uize.reverseLookup (entitiesNamesToCodes)
;

{34:'quot',38:'amp',60:'lt',62:'gt',160:'nbsp',169:'copy',174:'reg'}

2.70.2. Create a Reverse Lookup From a Values Array

reverseLookupOBJ = Uize.reverseLookup (valuesARRAY);

var
  frontRunnerLineup = [
    'John Backsberg',
    'Adrian Gullipeg',
    'Sasha Djenduriba',
    'Clark Holstrom',
    'Michael Anderson',
    'Henry Pratt',
    'Jacob Zimbalist',
    'Steven P. McLoughlan',
    'Chris Gates',
    'Richard Crumb'
  ],
  frontRunnerLineupReverseLookup = Uize.reverseLookup (frontRunnerLineup)
;

{
  'John Backsberg':0,
  'Adrian Gullipeg':1,
  'Sasha Djenduriba':2,
  'Clark Holstrom':3,
  'Michael Anderson':4,
  'Henry Pratt':5,
  'Jacob Zimbalist':6,
  'Steven P. McLoughlan':7,
  'Chris Gates':8,
  'Richard Crumb':9
}

2.70.3. Create a Safe Reverse Lookup Object

reverseLookupOBJ = Uize.reverseLookup (hashOBJorValuesARRAY,safeBOOL);

var
  entitiesNamesToCodes = {quot:34,amp:38,lt:60,gt:62,nbsp:160,copy:169,reg:174},
  entitiesCodesToNames = Uize.reverseLookup (entitiesNamesToCodes),
  entitiesCodesToNamesSafe = Uize.reverseLookup (entitiesNamesToCodes,true)
;

if (entitiesCodesToNames ['valueOf']) {
  alert ('valueOf appears to be an HTML entity char code');
}

if (entitiesCodesToNamesSafe ['valueOf']) {
  alert ('you will not see this alert statement');
}

2.70.4. Add More Entries to a Reverse Lookup Object

targetOBJ = Uize.reverseLookup (hashOBJorValuesARRAY,targetOBJ);

var entitiesCodesToNames = Uize.reverseLookup ({quot:34,amp:38,lt:60,gt:62});
Uize.reverseLookup ({nbsp:160,copy:169,reg:174},entitiesCodesToNames);

alert (entitiesCodesToNames [38]);   // alerts "amp"
alert (entitiesCodesToNames [169]);  // alerts "copy"

2.70.5. Create a Bi-directional Lookup

reverseLookupOBJ = Uize.reverseLookup (lookupOBJ,lookupOBJ);

var entitiesBiDiLookup = {quot:34, amp:38, lt:60, gt:62, nbsp:160, copy:169, reg:174};
Uize.reverseLookup (entitiesBiDiLookup,entitiesBiDiLookup);

alert (entitiesBiDiLookup ['amp']);  // alerts "38"
alert (entitiesBiDiLookup [38]);     // alerts "amp"

var foodsLookup = {apple:'fruit',banana:'fruit',corn:'grain',rice:'grain'};
Uize.reverseLookup (foodsLookup,foodsLookup);

alert (foodsLookup ['apple']);  // alerts "fuit"
alert (foodsLookup ['grain']);  // alerts "rice"

NOTES

IMPLEMENTATION INFO

Returns an integer, representing the amount of time (in milliseconds) that has elapsed since the specified date.

SYNTAX

elapsedMsINT = Uize.since (dateOBJorINT);

The value provided for the dateOBJorINT parameter can be either a reference to an instance of JavaScript's built-in Date object, or an integer representing milliseconds since 1970 (POSIX time). The Uize.since method provides a semantically elegant way of dealing with the timing of processes in JavaScript and is provided merely as syntactic sugar.

INSTEAD OF...

var start = Uize.now ();

// ... ... ... ... ... ... ... ... ... ... ...
// do some stuff that may take a bunch of time
// ... ... ... ... ... ... ... ... ... ... ...

var duration = Uize.now () - start;

USE...

var start = Uize.now ();

// ... ... ... ... ... ... ... ... ... ... ...
// do some stuff that may take a bunch of time
// ... ... ... ... ... ... ... ... ... ... ...

var duration = Uize.since (start);

NOTES

IMPLEMENTATION INFO

Lets you substitute one or more specified substitution values into a specified source string.

SYNTAX

resultSTR = Uize.substituteInto (
  sourceANYTYPE,         // a string, or other type that will be coerced to a string
  substitutionsANYTYPE,  // an object, array, or simple type substitution value
  tokenNamingSTR         // optional, specifies a custom token naming scheme
);

2.72.1. Parameters

Uize.substituteInto ('My name is [#name]',{name:'Eric'});
Uize.substituteInto ('My name is [#0]',['Eric']);
Uize.substituteInto ('My name is [#0]','Eric');

Uize.substituteInto ('My name is [#name]',{name:'Eric'});
Uize.substituteInto ('My name is [#name]',{name:'Eric'},'[#KEY]');
Uize.substituteInto ('My name is [name]',{name:'Eric'},'[KEY]');
Uize.substituteInto ('My name is {name}',{name:'Eric'},'{KEY}');
Uize.substituteInto ('My name is <%name%>',{name:'Eric'},'<%KEY%>');
Uize.substituteInto ('My name is ##name##',{name:'Eric'},'##KEY##');
Uize.substituteInto ('My name is [[name]]',{name:'Eric'},'[[KEY]]');

VARIATION

resultSTR = Uize.substituteInto (sourceANYTYPE,substitutionsOBJorARRAY);

When the optional tokenNamingSTR parameter is omitted, then its value will be defaulted to '[#KEY]'.

2.72.2. Examples

Uize.substituteInto (
  ''My name is [#name], and I am a [#occupation].',
  {name:'Eric',occupation:'viking'}
);

'My name is Eric, and I am a viking.'

Uize.substituteInto (
  'An [#fruit]. Oh, an [#fruit]!! Please, give me an [#fruit].',
  {fruit:'apple'}
);

'An apple. Oh, an apple!! Please, give me an apple.'

Uize.substituteInto (
  'An orange. Oh, an orange!! Please, give me an orange.',
  {fruit:'apple'}
);

'An orange. Oh, an orange!! Please, give me an orange.'

Uize.substituteInto (
  'An [#fruit]. Oh, an [#fruit]!! Please, give me an [#fruit].',
  {vegetable:'artichoke'}
);

'An [#fruit]. Oh, an [#fruit]!! Please, give me an [#fruit].'

Uize.substituteInto (
  'Welcome, {firstName} of {state}, {country}',
  {firstName:'Chris',state:'California',country:'USA'},
  '{KEY}'
);

'Welcome, Chris of California, USA'

Uize.substituteInto (
  'Welcome, firstName of state, country',
  {firstName:'Chris',state:'California',country:'USA'},
  'KEY'
);

'Welcome, Chris of California, USA'

Uize.substituteInto (
  '[#month]/[#date]/[#year] FLIGHTS: [#flights]',
  {
    month:9,
    date:11,
    year:Uize.Class ({value:2001}),
    flights:['AA11','UA175','AA77','UA93']
  }
);

'9/11/2001 FLIGHTS: AA11,UA175,AA77,UA93'

Uize.substituteInto ('Welcome, [#0] of [#1], [#2]',['Chris','California','USA']);

'Welcome, Chris of California, USA'

Uize.substituteInto ('[#token1][#token2]',{token1:'[#token2]foo',token2:'bar'});

'[#token2]foobar'

Uize.substituteInto (
  'This is a case of comparing [#fruit] to [#FRUIT].',
  {fruit:'apples',FRUIT:'oranges'}
);

'This is a case of comparing apples to oranges.'

Uize.substituteInto (
  'This is a case of comparing [#fruit] to [# fruit ].',
  {fruit:'apples',' fruit ':'oranges'}
);

'This is a case of comparing apples to oranges.'

Uize.substituteInto ('My name is [#0].','Eric');

'My name is Eric.'

Uize.substituteInto (Uize.Class ({value:'My name is [#name].'}),{name:'Eric'});

'My name is Eric.'

NOTES

IMPLEMENTATION INFO

Returns a number, that is the specified value coerced to a number type value, with optional defaulting if the value can't be successfully coerced to a number.

DIFFERENT USAGES

Coerce a Value to a Number

valueNUMBER = Uize.toNumber (valueANYTYPE);

Coerce a Value to a Number, With Defaulting

valueNUMBER = Uize.toNumber (valueANYTYPE,defaultANYTYPE);

2.73.1. How a Value is Coerced to Number

Uize.toNumber ('');  // returns NaN

Uize.toNumber (null);       // returns NaN
Uize.toNumber (undefined);  // returns NaN

Uize.toNumber ([]);   // returns NaN
Uize.toNumber ([1]);  // returns NaN

// these objects can be successfully coerced to a number

Uize.toNumber (new Number (5));                    // returns 5
Uize.toNumber (new String ('5'));                  // returns 5
Uize.toNumber (new Boolean (true));                // returns 1
Uize.toNumber (Uize.Class ({value:5}));            // returns 5
Uize.toNumber (Uize.Class ({value:'5'}));          // returns 5
Uize.toNumber (Uize.Class ({value:true}));         // returns 1
Uize.toNumber ({valueOf:function () {return 5}});  // returns 5


// these objects will be coerced to NaN

Uize.toNumber ({});                                // returns NaN
Uize.toNumber ({foo:'bar'});                       // returns NaN
Uize.toNumber (new XMLHttpRequest);                // returns NaN
Uize.toNumber (/\d+/);                             // returns NaN

function repeatStr (string,times) {
  times = Uize.toNumber (times,1);
  var result = '';
  for (var repeatNo = -1; ++repeatNo < times;) {
    result += string;
  }
  return result;
}

repeatStr ('Foo',2);                       // returns "FooFoo"
repeatStr ('Foo','2');                     // returns "FooFoo"
repeatStr ('Foo',Uize.Class ({value:2}));  // returns "FooFoo"
repeatStr ('Foo',function () {return 2});  // returns "FooFoo"
repeatStr ('Foo',true);                    // returns "Foo"
repeatStr ('Foo',false);                   // returns ""

repeatStr ('Foo');                         // returns "Foo"
repeatStr ('Foo',NaN);                     // returns "Foo"
repeatStr ('Foo','bar');                   // returns "Foo"
repeatStr ('Foo',null);                    // returns "Foo"
repeatStr ('Foo',undefined);               // returns "Foo"

var Rectangle = Uize.Class.subclass ();

Rectangle.stateProperties ({
  width:{
    conformer:Uize.toNumber,
    value:0
  },
  height:{
    conformer:Uize.toNumber,
    value:0
  }
});

var rect = Rectangle ({width:'5',height:'10'});

myInstance.get ('width');                          // returns 5
myInstance.get ('height');                         // returns 10

myInstance.set ('width',true);
myInstance.get ('width');                          // returns 1

myInstance.set ('height',function () {return 7});
myInstance.get ('height');                         // returns 7

myInstance.set ('width',Uize.Class ({value:12}));
myInstance.get ('width');                          // returns 12

2.73.2. Coerce a Value to a Number

valueNUMBER = Uize.toNumber (valueANYTYPE);

// values that can be coerced successfully to a number

Uize.toNumber (5);                                              // returns 5
Uize.toNumber (Infinity);                                       // returns Infinity
Uize.toNumber (true);                                           // returns 1
Uize.toNumber (false);                                          // returns 0
Uize.toNumber ('-1.234');                                       // returns -1.234
Uize.toNumber ('Infinity');                                     // returns Infinity
Uize.toNumber ('0xff');                                         // returns 255
Uize.toNumber (function () {return 5});                         // returns 5
Uize.toNumber (function () {return '5'});                       // returns 5
Uize.toNumber (Uize.Class ({value:5}));                         // returns 5
Uize.toNumber (Uize.Class ({value:'5'}));                       // returns 5
Uize.toNumber (new Number (5));                                 // returns 5
Uize.toNumber (new String ('5'));                               // returns 5
Uize.toNumber (new Boolean (true));                             // returns 1
Uize.toNumber (function () {return Uize.Class ({value:5})});    // returns 5
Uize.toNumber (function () {return Uize.Class ({value:'5'})});  // returns 5


// values that cannot be coerced to a number

Uize.toNumber ('foo');                                          // returns NaN
Uize.toNumber (NaN);                                            // returns NaN
Uize.toNumber ({});                                             // returns NaN
Uize.toNumber ([1]);                                            // returns NaN
Uize.toNumber (/\d+/);                                          // returns NaN
Uize.toNumber (undefined);                                      // returns NaN
Uize.toNumber (null);                                           // returns NaN
Uize.toNumber ('');                                             // returns NaN
Uize.toNumber (Uize.Class ({value:Uize.Class ({value:5})}));    // returns NaN
Uize.toNumber (Uize.Class ({value:function () {return 5}}));    // returns NaN
Uize.toNumber (function () {return function () {return 5}});    // returns NaN

2.73.3. Coerce a Value to a Number, With Defaulting

valueNUMBER = Uize.toNumber (valueANYTYPE,defaultANYTYPE);

// values that can be coerced successfully to a number

Uize.toNumber (5,99);                                              // returns 5
Uize.toNumber (Infinity,99);                                       // returns Infinity
Uize.toNumber (true,99);                                           // returns 1
Uize.toNumber (false,99);                                          // returns 0
Uize.toNumber ('-1.234',99);                                       // returns -1.234
Uize.toNumber ('Infinity',99);                                     // returns Infinity
Uize.toNumber ('0xff',99);                                         // returns 255
Uize.toNumber (function () {return 5},99);                         // returns 5
Uize.toNumber (function () {return '5'},99);                       // returns 5
Uize.toNumber (Uize.Class ({value:5}),99);                         // returns 5
Uize.toNumber (Uize.Class ({value:'5'}),99);                       // returns 5
Uize.toNumber (new Number (5),99);                                 // returns 5
Uize.toNumber (new String ('5'),99);                               // returns 5
Uize.toNumber (new Boolean (true),99);                             // returns 1
Uize.toNumber (function () {return Uize.Class ({value:5})},99);    // returns 5
Uize.toNumber (function () {return Uize.Class ({value:'5'})},99);  // returns 5

// values that cannot be coerced to a number

Uize.toNumber ('foo',99);                                          // returns 99
Uize.toNumber (NaN,99);                                            // returns 99
Uize.toNumber ({},99);                                             // returns 99
Uize.toNumber ([1],99);                                            // returns 99
Uize.toNumber (/\d+/,99);                                          // returns 99
Uize.toNumber (undefined,99);                                      // returns 99
Uize.toNumber (null,99);                                           // returns 99
Uize.toNumber ('',99);                                             // returns 99
Uize.toNumber (Uize.Class ({value:Uize.Class ({value:5})}),99);    // returns 99
Uize.toNumber (Uize.Class ({value:function () {return 5}}),99);    // returns 99
Uize.toNumber (function () {return function () {return 5}},99);    // returns 99

NOTES

IMPLEMENTATION INFO

Returns a string, providing summary info for the class on which the method is called.

SYNTAX

classSummarySTR = MyClass.toString ();

The string returned by this method provides a summary that includes the class' name and the state of its state properties. Among other things, this method provides a convenient and lightweight way to gather information about Uize.Class subclasses during debugging and troubleshooting. The Uize.toString static intrinsic method is invoked automatically in certain contexts in order to convert a class reference to a string form, such as when alerting a class using the alert global function.

EXAMPLE

alert (page.children.slider.Class);

In the above example, if the page widget has a slider child widget that is an instance of the class Uize.Widget.Bar.Slider, then the output of the alert statement could look something like...

EXAMPLE OUTPUT

[class Uize.Widget.Bar.Slider]

built : true
busy : inherit
busyInherited : false
confirm : undefined
container : undefined
decimalPlacesToDisplay : undefined
enabled : inherit
enabledInherited : true
html : undefined
idPrefix : undefined
idPrefixConstruction : undefined
inDrag : false
increments : 1
inform : undefined
insertionMode: undefined
localized : undefined
maxValidValue : undefined
maxValue : 100
minValidValue : undefined
minValue : 0
name : undefined
nodeMap : undefined
orientation : vertical
parent : undefined
restTime : 250
scaleFunc : [object Function]
value : 0
valueFunc : [object Function]
wired : false

In certain contexts, providing a reference to a Uize.Class subclass as a parameter to some method will result in the Uize.Class.valueOf static intrinsic method of that class being invoked in order to coerce it to a simple value. If it is your desire to have the class summary be used rather than the class' value, then you should explicitly call the Uize.toString static intrinsic method, as follows...

EXAMPLE

Uize.Node.setInnerHtml ('classSummaryForDebug',page.children.slider.Class.toString ());
Uize.Node.setInnerHtml ('classCurrentValue',page.children.slider.Class);

In this example, the classSummaryForDebug node will contain the summary info for the Uize.Widget.Bar.Slider class, while the classCurrentValue node will just show the class' current value.

NOTES

Returns an integer, representing the total number of keys in the specified object.

SYNTAX

totalKeysINT = Uize.totalKeys (objectOBJ);

Using the Uize.totalKeys method to determine the number of keys an object has is more efficient than using the expression Uize.keys (myObject).length, because the Uize.totalKeys method doesn't populate an array. Furthermore, to determine if an object is empty, you could use the expression !Uize.totalKeys (myObject), but it would be more efficient to use the convenient Uize.isEmpty static method.

NOTES

IMPLEMENTATION INFO

Returns an array, representing the property values of the specified object.

SYNTAX

valuesARRAY = Uize.values (objectOBJ);

EXAMPLE

var
  personRecord = {
    firstName:'John',
    lastName:'Wilkey',
    addressStreet:'1 Shiny House Way',
    addressCity:'Richville',
    addressState:'CA',
    addressZip:'91234'
  },
  myValues = Uize.keys (personRecord)
;

After the above code has executed, the myValues variable will have the value ['John', 'Wilkey', '1 Shiny House Way', 'Richville', 'CA', '91234'].

VARIATION

valuesARRAY = Uize.values (objectARRAY);

When an objectARRAY parameter is specified in place of an objectOBJ parameter, then the value of the objectARRAY parameter will be returned as the result. This behavior makes this method useful for canonicalizing what could be an object or an array to an array of values.

NOTES

IMPLEMENTATION INFO

The Uize.globalEval static method has been deprecated in favor of the newly added Uize.laxEval static method.

Uize.globalEval >> BECOMES >> Uize.laxEval

The Uize.laxEval method is essentially just a renaming of the deprecated Uize.globalEval method and behaves in exactly the same way. The old name was deemed to be misleading.

While the Uize.globalEval method could be used to evaluate JavaScript code outside of the scope of the current function, that scope was actually a root level function defined in the global scope - the evaluated code itself could not truly be evaluated at the very root of the global scope. The spirit of the method was never so much about evaluating code in the global scope as it was about evaluating the code in a way that was quarantined from the current scope (see Quarantined Code Evaluation), so as not to risk side effects of local variable access and closure memory reference implications that would arise from evaluating the code within the current function's scope.

IMPLEMENTATION INFO

A string, representing a template to be used when generating URLs for loading JavaScript modules dynamically.

EXAMPLE

Uize.moduleUrlTemplate = 'http://www.somedomain.com/js/[#modulePath]';

For an in-depth discussion of modules, consult the guide JavaScript Modules.

NOTES

IMPLEMENTATION INFO

A string, representing the relative path from the current document to the folder containing the Uize module's JavaScript library.

This property is useful in the implementation of Uize.Class subclasses that are to reside in the same folder alongside the Uize module's JavaScript file and that may wish to, in their implementation, make use of image and other support resources located inside that folder.

By using this property, a subclass' implementation does not need to know whether or not the document using it is being loaded through HTTP or from the local file system and does not need to impose extra requirements on developers regarding where its JavaScript library is located in relation to documents using it.

NOTES

IMPLEMENTATION INFO