UIZE JavaScript Framework

MODULES Uize.Data.Compare

1. Introduction

The Uize.Data.Compare module provides various utility methods for comparing the contents of data objects.

DEVELOPERS: Chris van Rensburg

1.1. Examples

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

SEARCH FOR EXAMPLES

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

SEARCH

1.2. Implementation Info

The Uize.Data.Compare module defines the Uize.Data.Compare package under the Uize.Data namespace.

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

STATIC METHODS

Uize.Data.Compare.clones | Uize.Data.Compare.conjoined | Uize.Data.Compare.identical | Uize.Data.Compare.intersection

STATIC PROPERTIES

Uize.Data.Compare.moduleName | Uize.Data.Compare.pathToResources

1.2.2. Features Overridden in This Module

No features have been overridden in this module.

1.2.3. Features Inherited From Other Modules

This module has no inherited features.

1.2.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.2.5. Unit Tests

The Uize.Data.Compare module is unit tested by the Uize.Test.Uize.Data.Compare test module.

2. Static Methods

2.1. Uize.Data.Compare.clones

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

SYNTAX

areClonesBOOL = Uize.Data.Compare.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

Uize.Data.Compare.clones (myObjectOBJ,myObjectOBJ) will return false, since they are one and the same and not clones.

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Data.Compare.conjoined

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

SYNTAX

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

NOTES

Uize.Data.Compare.conjoined (myObjectOBJ,myObjectOBJ) will return true, since they are one and the same (i.e. conjoined at the root).

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Data.Compare.identical

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

SYNTAX

areIdenticalBOOL = Uize.Data.Compare.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 (i.e. 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.Compare.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.3.1. optionsOBJ

An object, with multiple optional properties, specifying the criteria this method should use when comparing the two objects.

The value of the optionsOBJ parameter should be an object of the form...

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

2.3.1.1. equality

A string, specifying how the values of properties at any level of the objects' structure should be tested for equality.

The optional equality property of the optionsOBJ parameter can have the following values...

'type' - When the value 'type' is specified, the values of properties do not need to be equal - only be of the same type. This setting is useful when merely trying to determine if two objects have the same structure, but not that their values match. This could be used to determine if an object being interrogated conforms to some reference structure that might indicate the type of data it contains, but where the specific values are not important.
'loose' - When the value 'loose' is specified, then the values of all properties must be equal only according to a loose equality comparison, where strict type matching is not performed. According to this setting, the number value 1 would equal the string value '1', or the number value 0 would equal the string value '' (empty string) and the boolean value false.
'strict' - When the value 'strict' is specified (or when no value is specified for the equality property, or when no optionsOBJ parameter is specified), then the values of all properties must be equal according to a strict equality comparison, where strict type matching is performed. According to this setting, the number value 1 would NOT equal the string value '1', the number value 0 would NOT equal the string value '' (empty string), and so on.

2.3.1.2. allowConjoined

A boolean, specifying whether or not the two objects being compared may reference the same shared sub-object at any level of their structure.

By default (when no value is specified for the allowConjoined property, or when no optionsOBJ parameter is specified), two objects being compared will be considered identical even if they are conjoined and reference the same shared sub-object at some level of their structure. Therefore, the statement Uize.Data.Compare.identical (myObjectOBJ,myObjectOBJ) will return the value true.

Specifying the value false for this property will require that object references at any level of the structure of the two objects being compared are unique to each object. So, the statement Uize.Data.Compare.identical (myObjectOBJ,myObjectOBJ,{allowConjoined:false}) would produce the result false.

IMPORTANT

It should be noted that the two objects being compared could still have references to shared objects at different levels in their structure. To reliably test that two objects are identical and yet completely discrete, one can use the Uize.Data.Compare.clones static method.

NOTES

see also the Uize.Data.Compare.clones and Uize.Data.Compare.conjoined static methods

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Data.Compare.intersection

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

SYNTAX

intersectionOBJ = Uize.Data.Compare.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.Compare.intersection (employee1,employee2)
;

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

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Properties

3.1. Uize.Data.Compare.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Data.Compare.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module