Returns a boolean, indicating whether or not the two specified objects are identical clones of one another.

SYNTAX

areClonesBOOL = Uize.Data.clones (object1OBJ,object2OBJ);

Identical clones have identical structure, possess all the same values for corresponding simple valued properties, but may not share objects (so, object type properties' values may not be shared, either at a corresponding place in their structure, or at different places in their structure).

NOTES

Returns a boolean, indicating whether or not the two specified objects share any object references.

SYNTAX

areConjoinedBOOL = Uize.Data.conjoined (object1OBJ,object2OBJ);

NOTES

Returns an object with only the properties of the source object that are specified by an array of property names.

SYNTAX

filteredOBJ = Uize.Data.filter (sourceObjectOBJ,propertyNamesARRAY);

This method can be useful when receiving an info package of which only a subset needs to be stored or passed on to a subsequent process.

EXAMPLE

var someNodeStyle = {
  color:'#fff',
  left:'10px',
  top:'-50px',
  position:'absolute',
  display:'none',
  width:'200px',
  height:'300px',
  overflow:'hidden'
};
Uize.Node.setStyle (
  'someOtherNode',Uize.Data.filter (someNodeStyle,['left','top','width','height'])
);

In this example, a node style object that is being used for some node is being filtered for just its dimensions and positioning properties, to then be applied to some other node.

Without this method, the setStyle method call would look like...

Uize.Node.setStyle (
  'someOtherNode',
  {
    left:someNodeStyle.left,
    top:someNodeStyle.top,
    width:someNodeStyle.width,
    height:someNodeStyle.height
  }
);

Returns an array of records from the specified record set that match the specified criteria.

SYNTAX

matchingRecordsARRAY = Uize.Data.findRecords (recordsARRAY,matchOBJ);

EXAMPLE

var
  employees = [
    {firstName:'John',lastName:'Wilkey',department:'engineering'},
    {firstName:'Marie',lastName:'Stevenson',department:'finance'},
    {firstName:'Craig',lastName:'Pollack',department:'finance'},
    {firstName:'Nick',lastName:'Arendsen',department:'engineering'},
    {firstName:'Mark',lastName:'Strathley',department:'engineering'}
  ],
  financeEmployees = Uize.Data.findRecords (employees,{department:'finance'})
;

In the above example, the variable financeEmployees would be an array with the value...

[
  {firstName:'Marie',lastName:'Stevenson',department:'finance'},
  {firstName:'Craig',lastName:'Pollack',department:'finance'}
]

If the records in your record set are arrays, rather than objects, then you can specify a match object where the keys are numerical indexes representing the array element index / column index, as in...

EXAMPLE

var
  employees = [
    ['John','Wilkey','engineering'],
    ['Marie','Stevenson','finance'],
    ['Craig','Pollack','finance'],
    ['Nick','Arendsen','engineering'],
    ['Mark','Strathley','engineering']
  ],
  financeEmployees = Uize.Data.findRecords (employees,{2:'finance'})
;

In the above example, the financeEmployees variable would have the same value as in the previous example.

NOTES

Returns an array of the values for the specified column of the specified record set.

SYNTAX

columnValuesARRAY = Uize.Data.getColumn (rowsARRAY,columnNameSTR);

EXAMPLE

var
  peopleNames = [
    {first:'John',last:'Wilkey'},
    {first:'Marie',last:'Stevenson'},
    {first:'Craig',last:'Pollack'}
  ],
  firstNames = Uize.Data.getColumn (peopleNames,'first'),
  lastNames = Uize.Data.getColumn (peopleNames,'last')
;

In the above example, the variable firstNames would be an array with the value ['John','Marie','Craig'] and the variable lastNames would be an array with the value ['Wilkey','Stevenson','Pollack'].

The records / rows in the record set do not need to be objects - they can also be arrays.

EXAMPLE

var
  peopleNames = [
    ['John','Wilkey'],
    ['Marie','Stevenson'],
    ['Craig','Pollack']
  ],
  firstNames = Uize.Data.getColumn (peopleNames,0),
  lastNames = Uize.Data.getColumn (peopleNames,1)
;

In the above example, the firstNames and lastNames variables would have the same values as in the previous example.

VARIATION

columnValuesARRAY = Uize.Data.getColumn (rowsARRAY,columnNameSTR,onlyUniquesBOOL);

When the value true is specified for the optional onlyUniquesBOOL parameter, then this method will only return the unique values for the specified column.

EXAMPLE

var
  employees = [
    {firstName:'John',lastName:'Wilkey',department:'engineering'},
    {firstName:'Marie',lastName:'Stevenson',department:'finance'},
    {firstName:'Craig',lastName:'Pollack',department:'finance'},
    {firstName:'Nick',lastName:'Arendsen',department:'engineering'},
    {firstName:'Mark',lastName:'Strathley',department:'engineering'}
  ],
  departments = Uize.Data.getColumn (employees,'department',true)
;

In the above example, the variable departments would be an array with the value ['engineering','finance'].

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

SYNTAX

keysARRAY = Uize.Data.getKeys (objectOBJ);

EXAMPLE

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

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

NOTES

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

SYNTAX

lookupOBJ = Uize.Data.getLookup (valuesARRAY);

EXAMPLE

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

After the above code is executed, the value of the fruitsLookup variable will be an object with the contents...

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

VARIATION

lookupOBJ = Uize.Data.getLookup (valuesARRAY,lookupValueANYTYPE);

By default, the Uize.Data.getLookup method creates an object whose properties all have the boolean value true. The optional lookupValueANYTYPE parameter lets you specify the value that should be assigned to each of the properties in the lookup object.

EXAMPLE

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

In the above example, the value 1 is being specified for the optional lookupValueANYTYPE. After the above code is executed, the value of the fruitsLookup variable will be an object with the contents...

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

2.7.1. 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.Data.getLookup (masterList)
  ;
  for (var valueNo = -1; ++valueNo < values.length;) {
    var value = values [valueNo];
    if (masterListLookup [value]) result.push (value);
  }
  return result;
}

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.

SYNTAX

reverseLookupOBJ = Uize.Data.getReverseLookup (hashOBJ);

EXAMPLE 1

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

After the above code is executed, the value of the htmlEntitiesReverseLookup variable will be an object with the contents...

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

By creating a reverse lookup, this code can lookup up an entity's character code from its name, or its name from its character code.

VARIATION

reverseLookupOBJ = Uize.Data.getReverseLookup (valuesARRAY);

The Uize.Data.getReverseLookup method can also be used to create a reverse lookup object for an array. When a valuesARRAY parameter is specified in place of the hashOBJ parameter, a reverse lookup object is generated where each of the values in the array is a key in the object, and the value corresponding to each key is the index of the value in the array.

EXAMPLE 2

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.Data.getReverseLookup (frontRunnerLineup)
;

After the above code is executed, the value of the frontRunnerLineupReverseLookup variable will be an object with the contents...

[
  '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
]

Now the code can look up a front-runner from the front-runner lineup using an index, or the code can determine if a particular person is in the front-runner lineup and what their finishing place is using the generated reverse lookup.

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

SYNTAX

totalKeysINT = Uize.Data.getTotalKeys (objectOBJ);

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

NOTES

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

SYNTAX

valuesARRAY = Uize.Data.getValues (objectOBJ);

EXAMPLE

var
  personRecord = {
    firstName:'John',
    lastName:'Wilkey',
    addressStreet:'1 Shiny House Way',
    addressCity:'Richville',
    addressState:'CA',
    addressZip:'91234'
  },
  myValues = Uize.getKeys (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.Data.getValues (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

Returns a boolean, indicating whether or not the two specified objects are identical in their contents.

SYNTAX

areIdenticalBOOL = Uize.Data.identical (object1OBJ,object2OBJ);

This method recurses through the two objects specified by the object1OBJ and object2OBJ parameters, testing that they have the same structure and property values. The two parameters can be arbitrarily complex data trees, or simple type values (ie. string, number, boolean). In order to be considered identical, the two objects must have the same structure and the same values at all levels of their structure.

VARIATION

areIdenticalBOOL = Uize.Data.identical (object1OBJ,object2OBJ,optionsOBJ);

When the optional optionsOBJ parameter is specified, comparison options can be specified to determine the criteria this method uses when comparing the two objects.

2.11.1. optionsOBJ

{
  equality : equalitySTR,             // 'type' | 'loose' | 'strict' (default)
  allowConjoined : allowConjoinedBOOL // false | true (default)
}

NOTES

Returns an object that represents the key-value intersection / commonality between the two specified objects.

SYNTAX

intersectionOBJ = Uize.Data.intersection (object1OBJ,object2OBJ);

EXAMPLE

var
  employee1 = {
    firstName:'John',
    lastName:'Wilkey',
    startYear:'2008',
    department:'engineering'
  },
  employee2 = {
    firstName:'John',
    lastName:'Henderson',
    startYear:'2008',
    department:'finance'
  },
  employeeInCommon = Uize.Data.intersection (employee1,employee2)
;

In the above example, the variable employeeInCommon would have the value {firstName:'John',startYear:'2008'}.

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

SYNTAX

isEmptyBOOL = Uize.Data.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.Data.isEmpty method returns true if the object has no keys. For an array type value, Uize.Data.isEmpty returns true if the array has no elements (ie. a length of 0). For any other type of value, Uize.Data.isEmpty returns true if the value is equivalent to false.

EXAMPLES

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

Uize.Data.isEmpty ({blah:0});             // returns false
Uize.Data.isEmpty (['blah']);             // returns false
Uize.Data.isEmpty ('blah');               // returns false
Uize.Data.isEmpty (1);                    // returns false
Uize.Data.isEmpty (true);                 // returns false
Uize.Data.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 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.Data.isEmpty (new String (''));      // returns true
Uize.Data.isEmpty (new Number (0));       // returns true
Uize.Data.isEmpty (new Boolean (false));  // returns true
Uize.Data.isEmpty (new Uize ({value:0}))  // returns true

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

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

NOTES

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.Data.map (mapperSTRorFUNC,sourceARRAYorOBJorINT);

The Uize.Data.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.Data.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.Data.map method.

INSTEAD OF...

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

USE...

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

OR USING A FUNCTION...

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

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

INSTEAD OF...

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

USE...

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

OR USING A FUNCTION...

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

2.14.1. Key Benefits

VARIATION

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

By default, the Uize.Data.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.14.2. Parameters

2.14.3. More Examples

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Returns the maximum value from the specified array or object.

SYNTAX

var maxValueNUM = Uize.Data.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.Data.max (employeeSalaries)
;

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

NOTES

Returns the minimum value from the specified array or object.

SYNTAX

var minValueNUM = Uize.Data.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.Data.min (employeeSalaries)
;

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

NOTES

Returns an array, being a reordered version of the specified source array, using the specified reordering mode.

SYNTAX

reorderedARRAY = Uize.Data.reorderArray (sourceARRAY,reorderingModeSTR);

VARIATION 1

reorderedARRAY =
  Uize.Data.reorderArray (sourceARRAY,reorderingModeSTR,targetARRAYorBOOL)
;

By default, the Uize.Data.reorderArray method packages the reordered array elements into a new array and does not modify the source array (ie. it's non-destructive). Specifying the optional targetARRAYorBOOL parameter allows you to explicitly specify a target for the operation, into which the reordered elements will be packaged.

VARIATION 2

jumbledARRAY = Uize.Data.reorderArray (sourceARRAY);

When only a sourceARRAY parameter is specified, then the default behavior is to reorder the source array using the 'jumble' mode and package the results into a new array.

2.17.1. Parameters