UIZE JavaScript Framework

MODULES Uize.Array.Util

1. Introduction

The Uize.Array.Util module provides a number of miscellaneous utility methods for manipulating arrays.

DEVELOPERS: Chris van Rensburg

1.1. Examples

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

SEARCH FOR EXAMPLES

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

SEARCH

1.2. Implementation Info

The Uize.Array.Util module defines the Uize.Array.Util package under the Uize.Array namespace.

1.2.1. Features Introduced in This Module

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

STATIC METHODS

Uize.Array.Util.flatten | Uize.Array.Util.replaceContents | Uize.Array.Util.sum | Uize.Array.Util.swapContents

STATIC PROPERTIES

Uize.Array.Util.moduleName | Uize.Array.Util.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.Array.Util module is unit tested by the Uize.Test.Uize.Array.Util test module.

2. Static Methods

2.1. Uize.Array.Util.flatten

Flattens the elements of the specified source array and returns the flattened array.

SYNTAX

flattenedARRAY = Uize.Array.Util.flatten (sourceARRAY,depthINT,targetARRAYorBOOL);

VARIATION 1

flattenedARRAY = Uize.Array.Util.flatten (sourceARRAY,depthINT);

When the optional depthINT parameter is specified, then the depth level to which the source array should be flattened can be controlled. When the value 0 is specified for this parameter, the source array will remain unflattened. When the value 1 is specified, then this method will flatten an array to one level deep. When the value 2 is specified, then this method will flatten an array to two levels deep. When the depthINT parameter is not specified, then this method will flatten an array to infinite depth.

VARIATION 2

flattenedARRAY = Uize.Array.Util.flatten (sourceARRAY,depthINT,targetARRAYorBOOL);

When the optional targetARRAYorBOOL parameter is specified, then the target for the flattened contents of the source array can be controlled. When the value true is specified for the targetARRAYorBOOL parameter, then the target for the flattened contents of the source array will be a new array and the source array will not be modified. When the false is specified for the targetARRAYorBOOL parameter, then the flattened contents of the source array will replace the unflattened contents of the source array. When an array is specified for the targetARRAYorBOOL parameter, then the flattened contents of the source array will replace the contents of the specified target array.

2.1.1. Examples

2.1.1.1. Flatten an Array to One Level Deep

When the value 1 is specified for the optional depthINT parameter, then the source array will be flattened one level deep.

EXAMPLE

Uize.Array.Util.flatten ([0,[1,[2,[3,[4,[5,[6,6],5],4],3],2],1],0],1);

RESULT

[0,1,[2,[3,[4,[5,[6,6],5],4],3],2],1,0]

2.1.1.2. Flatten an Array to Two Levels Deep

When the value 2 is specified for the optional depthINT parameter, then the source array will be flattened one level deep.

EXAMPLE

Uize.Array.Util.flatten ([0,[1,[2,[3,[4,[5,[6,6],5],4],3],2],1],0],2);

RESULT

[0,1,2,[3,[4,[5,[6,6],5],4],3],2,1,0]

2.1.1.3. Flatten an Array to Infinite Depth

When the optional depthINT parameter is not specified, then the source array will be flattened to infinite depth (i.e. until all elements are no longer arrays).

EXAMPLE

Uize.Array.Util.flatten ([0,[1,[2,[3,[4,[5,[6,6],5],4],3],2],1],0]);

RESULT

[0,1,2,3,4,5,6,6,5,4,3,2,1,0]

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Array.Util.replaceContents

Replaces the contents of the first array with the contents of the second array, and returns a reference to the first array.

SYNTAX

array1ARRAY = Uize.Array.Util.replaceContents (array1ARRAY,array2ARRAY);

EXAMPLE

var
  foods = ['bacon','sausage','omelette'],
  vegetables = ['potato','beans','mushrooms']
;
Uize.Array.Util.replaceContents (foods,vegetables);
alert (foods); // displays the text "potato,beans,mushrooms"

In the above example, the contents of the foods array (which clearly contains some rather unhealthy food types) is being replaced with the contents of the healthier vegetables array. When the value of the foods array is then alerted, we see the text "potato,beans,mushrooms".

VARIATION

array1ARRAY = Uize.Array.Util.replaceContents (array1ARRAY);

When no array2ARRAY parameter is specified, or if the value undefined or null is specified for the array2ARRAY parameter, then the array specified by the array1ARRAY parameter will be emptied out.

NOTES

see the related Uize.Array.Util.swapContents static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Array.Util.sum

Returns the sum of all the elements of the specified source array.

SYNTAX

sumNUM = Uize.Array.Util.sum (sourceARRAY);

EXAMPLES

Uize.Array.Util.sum ([]);                     // returns 0
Uize.Array.Util.sum ([1]);                    // returns 1
Uize.Array.Util.sum ([1,2,3,4,5]);            // returns 15
Uize.Array.Util.sum (['1','2','3','4','5']);  // returns 15

When summing the elements of the source array, all element values will be coerced to numbers by invoking the valueOf intrinsic method on the values. So, the statement Uize.Array.Util.sum (['1','2','3','4','5']) is equivalent to the statement Uize.Array.Util.sum ([1,2,3,4,5]).

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Array.Util.swapContents

Swaps the contents of the two specified arrays, and returns a reference to the first array.

SYNTAX

array1ARRAY = Uize.Array.Util.swapContents (array1ARRAY,array2ARRAY);

EXAMPLE

var
  healthyFoods = ['bacon','sausage','omelette'],
  unhealthyFoods = ['potato','beans','mushrooms']
;
Uize.Array.Util.swapContents (healthyFoods,unhealthyFoods);
alert (healthyFoods);    // displays the text "potato,beans,mushrooms"
alert (unhealthyFoods);  // displays the text "bacon,sausage,omelette"

In the above example, the contents of the healthyFoods and unhealthyFoods arrays are clearly mixed up. In order to correct this, the contents of the two arrays can be swapped. We can't just swap the variable references around, since other code may already have references to the arrays. What we really want to do is fix their contents. We can do this using the Uize.Array.Util.swapContents method.

NOTES

see the related Uize.Array.Util.replaceContents static method

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Properties

3.1. Uize.Array.Util.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Array.Util.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module