UIZE JavaScript Framework

MODULES Uize.Data.Matches

SEARCHEXAMPLESSOURCEDEPSTEST

1. Introduction

The Uize.Data.Matches module provides methods for finding matching elements in arrays or matching properties in objects.

DEVELOPERS: Chris van Rensburg

1.1. In a Nutshell

The Uize.Data.Matches module provides methods for performing the following types of matching operations...

iterating over matches
removing or retaining matches
counting matches
getting the keys or values for all matches
getting the key or value of the first match

1.1.1. Iterating Over Matches

To make it easy to iterate over matches in a source array, object, or range, the Uize.Data.Matches module provides the Uize.Data.Matches.forEach static method.

The Uize.Data.Matches.forEach method can be used to iterate over matching elements of an array, iterate over matching properties of an object, or iterate over matching values of a range. In its most basic usage, the Uize.Data.Matches.forEach method lets you specify a source, a matcher, and an iterator.

TYPICAL USAGE

Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

EXAMPLE

Uize.Data.Matches.forEach (
);

The Uize.Data.Matches.forEach method is versatile and supports a number of different usages. For more in-depth info, consult the method's reference documentation.

1.1.2. Removing or Retaining Matches

The Uize.Data.Matches module offers methods for processing an array, object, or range, and either removing or retaining matches.

The Uize.Data.Matches.remove method can be used to remove matches, while the Uize.Data.Matches.retain method can be used to retain matches.

Both of these methods support...

processing a source array, object, or range (see Specifying a Source)
finding matches by value and/or key/index (see Specifying a Matcher)
removing or retaining a maximum number of matches (see Limiting the Number of Matches)
modifying the original source or outputting the result to a newly created or specified target (see Specifying a Target)

1.1.2.1. Removing Matches

Matches can be removed from an array, object, or number range, using the Uize.Data.Matches.remove method.

TYPICAL USAGE

var result = Uize.Data.Matches.remove (sourceARRAYorOBJorINT,matcherFUNCorSTRorREGEXPorBOOL);

EXAMPLE

var sparseArray = [];
sparseArray [1] = 'orange';
sparseArray [5] = 'peach';
sparseArray [8] = 'apple';
sparseArray [11] = 'pear';

var denseArray = Uize.Data.Matches.remove (sparseArray,'value === undefined'};
alert (denseArray.join ('|')); // alerts the text "orange|peach|apple|pear"

In the above example, the sparsely populated array named sparseArray is being created and populated with four elements. There are gaps between the assigned elements of sparseArray, and the elements in these gaps will all have the value undefined. The Uize.Data.Matches.remove method is being used to produce a densely populated array from the sparseArray by removing every element whose value is undefined. You'll notice that we're matching items using a value matcher regular expression rather than a function. This is nice and concise.

The Uize.Data.Matches.remove method is versatile and supports a number of different usages. For more in-depth info, consult the method's reference documentation.

1.1.2.2. Retaining Matches

.

EXAMPLE

1.1.3. Counting Matches

.

EXAMPLE

1.1.4. Getting the Keys or Values of All Matches

documnt...

EXAMPLE

1.1.5. Getting the Key or Value of the First Match

.

EXAMPLE

1.1.6. Specifying a Source

.

1.1.6.1. Specifying an Array Source

.

1.1.6.2. Specifying an Object Source

.

1.1.6.3. Specifying a Range Source

.

1.1.7. Specifying a Matcher

.

1.1.7.1. Matching Items Using a Matcher Function

.

1.1.7.2. Matching Items Using a Matcher Expression String

.

1.1.7.3. Matching Items Using a Value Matcher Regular Expression

.

1.1.7.4. Matching All Items

.

1.1.7.5. Matching No Items

.

1.1.7.6. Matching by Value

.

1.1.7.7. Matching by Key / Index

.

1.1.7.8. Matching by Key and Value

.

1.1.8. Limiting the Number of Matches

.

1.1.9. Specifying a Target

.

1.2. Examples

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

SEARCH FOR EXAMPLES

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

SEARCH

1.3. Implementation Info

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

1.3.1. Features Introduced in This Module

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

STATIC METHODS

Uize.Data.Matches.count | Uize.Data.Matches.firstKey | Uize.Data.Matches.firstValue | Uize.Data.Matches.forEach | Uize.Data.Matches.keys | Uize.Data.Matches.remove | Uize.Data.Matches.retain | Uize.Data.Matches.values

STATIC PROPERTIES

Uize.Data.Matches.moduleName | Uize.Data.Matches.pathToResources

1.3.2. Features Overridden in This Module

No features have been overridden in this module.

1.3.3. Features Inherited From Other Modules

This module has no inherited features.

1.3.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.3.5. Unit Tests

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

2. Static Methods

2.1. Uize.Data.Matches.count

Returns an integer, representing the number of elements in the specified source array, or properties in the specified source object, or values in the specified source range, that match the specified matching criteria.

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Data.Matches.firstKey

Returns the key/index of the first element in the specified source array, or property in the specified source object, or value in the specified source range, that matches the specified matching criteria.

NOTES

see also the companion Uize.Data.Matches.firstValue static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Data.Matches.firstValue

Returns the value of the first element in the specified source array, or property in the specified source object, or value in the specified source range, that matches the specified matching criteria.

NOTES

see also the companion Uize.Data.Matches.firstKey static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Data.Matches.forEach

Iterates over elements in the specified source array, or properties in the specified source object, or values in the specified source range, that match the specified matching criteria.

DIFFERENT USAGES

Iterate Over Matching Elements of an Array

Uize.Data.Matches.forEach (sourceARRAY,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

Iterate Over Matching Properties of an Object

Uize.Data.Matches.forEach (sourceOBJ,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

Iterate Over Matching Values of a Range

Uize.Data.Matches.forEach (sourceINT,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

Iterate Over up to a Maximum Number of Matches

Uize.Data.Matches.forEach (
  sourceARRAYorOBJorINT,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC,maxMatchesINT
);

Iterate Over All of the Items of a Source

Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,true,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,null,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,undefined,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,function () {return true},iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,Uize.returnTrue,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,'true',iteratorFUNC);

Iterate Over None of the Items of a Source

Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,false,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,function () {return false},iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,Uize.returnFalse,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,'false',iteratorFUNC);

2.4.1. Iterate Over Matching Elements of an Array

In a typical use case, this method can be used to iterate over matching elements of an array by specifying an array as the first parameter.

SYNTAX

Uize.Data.Matches.forEach (sourceARRAY,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

2.4.2. Iterate Over Matching Properties of an Object

SYNTAX

Uize.Data.Matches.forEach (sourceOBJ,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

2.4.3. Iterate Over Matching Values of a Range

SYNTAX

Uize.Data.Matches.forEach (sourceINT,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

2.4.4. Iterate Over up to a Maximum Number of Matches

SYNTAX

Uize.Data.Matches.forEach (
  sourceARRAYorOBJorINT,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC,maxMatchesINT
);

2.4.5. Iterate Over All of the Items of a Source

SYNTAX

Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,true,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,null,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,undefined,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,function () {return true},iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,Uize.returnTrue,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,'true',iteratorFUNC);

2.4.6. Iterate Over None of the Items of a Source

SYNTAX

Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,false,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,function () {return false},iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,Uize.returnFalse,iteratorFUNC);
Uize.Data.Matches.forEach (sourceARRAYorOBJorINT,'false',iteratorFUNC);

IMPLEMENTATION INFO

this feature was introduced in this module

2.5. Uize.Data.Matches.keys

Returns the keys/indexes for elements in the specified source array, or properties in the specified source object, or values in the specified source range, that match the specified matching criteria.

NOTES

see also the companion Uize.Data.Matches.values static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.6. Uize.Data.Matches.remove

Removes elements in the specified source array, or properties in the specified source object, or values in the specified source range, that match the specified matching criteria.

DIFFERENT USAGES

Remove All Matching Elements of an Array

Uize.Data.Matches.remove (sourceARRAY,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

Remove All Matching Properties of an Object

Uize.Data.Matches.remove (sourceOBJ,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

Remove All Matching Values of a Range

Uize.Data.Matches.remove (sourceINT,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

Remove up to a Maximum Number of Matches

Uize.Data.Matches.remove (
  sourceARRAYorOBJorINT,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC,maxMatchesINT
);

Remove All of the Items of a Source

Uize.Data.Matches.remove (sourceARRAYorOBJorINT,true,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,null,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,undefined,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,function () {return true},iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,Uize.returnTrue,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,'true',iteratorFUNC);

Remove None of the Items of a Source

Uize.Data.Matches.remove (sourceARRAYorOBJorINT,false,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,function () {return false},iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,Uize.returnFalse,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,'false',iteratorFUNC);

2.6.1. Remove All Matching Elements of an Array

In a typical use case, this method can be used to remove matching elements of an array by specifying an array as the first parameter.

SYNTAX

Uize.Data.Matches.remove (sourceARRAY,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

2.6.2. Remove All Matching Properties of an Object

SYNTAX

Uize.Data.Matches.remove (sourceOBJ,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

2.6.3. Remove All Matching Values of a Range

SYNTAX

Uize.Data.Matches.remove (sourceINT,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC);

2.6.4. Remove up to a Maximum Number of Matches

SYNTAX

Uize.Data.Matches.remove (
  sourceARRAYorOBJorINT,matcherFUNCorSTRorREGEXPorBOOL,iteratorFUNC,maxMatchesINT
);

2.6.5. Remove All of the Items of a Source

SYNTAX

Uize.Data.Matches.remove (sourceARRAYorOBJorINT,true,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,null,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,undefined,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,function () {return true},iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,Uize.returnTrue,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,'true',iteratorFUNC);

2.6.6. Remove None of the Items of a Source

SYNTAX

Uize.Data.Matches.remove (sourceARRAYorOBJorINT,false,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,function () {return false},iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,Uize.returnFalse,iteratorFUNC);
Uize.Data.Matches.remove (sourceARRAYorOBJorINT,'false',iteratorFUNC);

NOTES

see also the companion Uize.Data.Matches.retain static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.7. Uize.Data.Matches.retain

Retains elements in the specified source array, or properties in the specified source object, or values in the specified source range, that match the specified matching criteria.

NOTES

see also the companion Uize.Data.Matches.remove static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.8. Uize.Data.Matches.values

Returns the values for elements in the specified source array, or properties in the specified source object, or values in the specified source range, that match the specified matching criteria.

NOTES

see also the companion Uize.Data.Matches.keys static method

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Properties

3.1. Uize.Data.Matches.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Data.Matches.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module