MODULES Uize.Array.Order
1. Introduction
The Uize.Array.Order module provides utility methods for reordering the elements of arrays, with support for reversing, jumbling, inside to out, etc.
DEVELOPERS: Chris van Rensburg
1.1. In a Nutshell
1.1.1. Reordering Ins't Sorting
Unlike sorting an array based upon its elements' values, the methods of the Uize.Array.Order module allow you to reorder the elements according to different patterns - without respect to the element values.
As an example, the Uize.Array.Order.reverse method reverses the order of the elements in an array.
1.1.2. Types of Reordering
1.1.2.1. Reverse
The elements in an array can be reversed by using the Uize.Array.Order.reverse method, or by using the Uize.Array.Order.reorder method and specifying the value 'reverse' for the method's reorderingModeSTR parameter.
EXAMPLE
Uize.Array.Order.reverse ([1,2,3,4,5,6,7,8]); // returns the array [8,7,6,5,4,3,2,1]
While JavaScript's built-in Array object does provide a reverse instance method, the Uize.Array.Order.reverse method offers a versatile target facility that is lacking with the built-in reverse method, which always modifies the source array.
For a more in-depth explanation, consult the reference for the Uize.Array.Order.reverse method.
1.1.2.2. Jumble
The elements of an array can be jumbled (randomly shuffled) by using the Uize.Array.Order.jumble static method, or by using the Uize.Array.Order.reorder method and specifying the value 'jumbled' for the method's reorderingModeSTR parameter.
EXAMPLE
Uize.Array.Order.jumble ([1,2,3,4,5,6,7,8]); // returns an array like [2,8,4,1,6,3,7,5]
For a more in-depth explanation, consult the reference for the Uize.Array.Order.jumble method.
1.1.2.3. Inside to Out
The elements of an array can be reordered from inside to out by using the Uize.Array.Order.insideOut static method, or by using the Uize.Array.Order.reorder method and specifying the value 'inside out' for the method's reorderingModeSTR parameter.
EXAMPLE
Uize.Array.Order.insideOut ([1,2,3,4,5,6,7,8]); // returns the array [4,5,3,6,2,7,1,8]
For a more in-depth explanation, consult the reference for the Uize.Array.Order.insideOut method.
1.1.2.4. Outside to In
The elements of an array can be reordered from outside to in by using the Uize.Array.Order.insideOut static method, or by using the Uize.Array.Order.reorder method and specifying the value 'outside in' for the method's reorderingModeSTR parameter.
EXAMPLE
Uize.Array.Order.outsideIn ([1,2,3,4,5,6,7,8]); // returns the array [1,8,2,7,3,6,4,5]
For a more in-depth explanation, consult the reference for the Uize.Array.Order.outsideIn method.
1.1.3. Versatile Target
The methods of the Uize.Array.Order module support a versatile target facility that allows the processed elements of the source array to be targeted either to the source array, to a fresh array, or to a specified target array.
With JavaScript's built-in Array object, some instance methods will modify the source array while others will create a fresh array. For example, the splice and reverse methods will modify the source array. On the other hand, the concat and slice methods return new arrays. In contrast, the methods of the Uize.Array.Order module let you specify the target behavior for the processed elements of the source array. A target is specified using the optional targetARRAYorBOOL parameter. Essentially three behaviors are supported: 1) modify the source array, 2) create a fresh array, or 3) use a specified target array.
For a more in-depth discussion, consult the reference for the targetARRAYorBOOL value type.
1.2. Examples
The following example pages are good showcases for the Uize.Array.Order module...
| Sequenced Show - This demo shows how you can sequence the appearance of thumbnails in a grid, with thumbnails filling in from the top left and bottom right corners. | |
| Sequenced Show Using Swap - See how thumbnails in a grid of thumbnails can be revealed in a choreographed manner, with a JavaScript animation effect for revealing each thumbnail. |
SEARCH FOR EXAMPLES
Use the link below to search for example pages on the UIZE Web site that reference the Uize.Array.Order module...
SEARCH
1.3. Implementation Info
The Uize.Array.Order module defines the Uize.Array.Order package under the Uize.Array namespace.
1.3.1. Features Introduced in This Module
The features listed in this section have been introduced in this module.
STATIC METHODS
Uize.Array.Order.insideOut | Uize.Array.Order.jumble | Uize.Array.Order.outsideIn | Uize.Array.Order.reorder | Uize.Array.Order.reverse
STATIC PROPERTIES
Uize.Array.Order.moduleName | Uize.Array.Order.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.Array.Order module is unit tested by the Uize.Test.Uize.Array.Order test module.
2. Static Methods
2.1. Uize.Array.Order.insideOut
Returns an array, being the specified source array reordered from inside to out.
SYNTAX
reorderedARRAY = Uize.Array.Order.insideOut (sourceARRAY);
When an array is reordered from inside to out, the new order is formed by starting with the inner elements and moving outwards in both directions to reach the start and the end of the array. Consider the following example...
EXAMPLE
Uize.Array.Order.insideOut ([1,2,3,4,5,6,7,8]); // returns the array [4,5,3,6,2,7,1,8]
In the above example, at the center of the array being reordered are the values 4 and 5. These are the first two elements of the reordered array. Moving outwards in both directions, the next two values are 3 and 6, so these are the next two elements in the reordered array. Moving outwards further, the next two values are 2 and 7, which become the next two elements in the reordered array. Finally, we get to the first and last values in the array being reordered, 1 and 9, which become the last two elements of the reordered array.
VARIATION
reorderedARRAY = Uize.Array.Order.insideOut (sourceARRAY,targetARRAYorBOOL);
When the optional targetARRAYorBOOL parameter is specified, the target destination for the reordered elements can be controlled (for more info, see the reference for the targetARRAYorBOOL value type).
NOTES
see the related Uize.Array.Order.jumble, Uize.Array.Order.outsideIn, Uize.Array.Order.reorder, and Uize.Array.Order.reverse static methods |
IMPLEMENTATION INFO
| this feature was introduced in this module |
2.2. Uize.Array.Order.jumble
Returns an array, being a jumbled (randomly shuffled) version of the specified source array.
SYNTAX
reorderedARRAY = Uize.Array.Order.jumble (sourceARRAY);
EXAMPLE
Uize.Array.Order.jumble ([1,2,3,4,5,6,7,8]); // returns an array like [2,8,4,1,6,3,7,5]
In the above example, the order of the elements in the jumbled array will very likely be different for every different time that the Uize.Array.Order.jumble method is called.
VARIATION
reorderedARRAY = Uize.Array.Order.jumble (sourceARRAY,targetARRAYorBOOL);
When the optional targetARRAYorBOOL parameter is specified, the target destination for the jumbled elements can be controlled (for more info, see the reference for the targetARRAYorBOOL value type).
NOTES
see the related Uize.Array.Order.insideOut, Uize.Array.Order.outsideIn, Uize.Array.Order.reorder, and Uize.Array.Order.reverse static methods |
IMPLEMENTATION INFO
| this feature was introduced in this module |
2.3. Uize.Array.Order.outsideIn
Returns an array, being the specified source array reordered from outside to in.
SYNTAX
reorderedARRAY = Uize.Array.Order.outsideIn (sourceARRAY);
When an array is reordered from outside to in, the new order is formed by starting with the start and the end of the array and moving inwards in both directions to reach the inner elements. Consider the following example...
EXAMPLE
Uize.Array.Order.outsideIn ([1,2,3,4,5,6,7,8]); // returns the array [1,8,2,7,3,6,4,5]
In the above example, at the start and end of the array being reordered are the values 1 and 8. These are the first two elements of the reordered array. Moving inwards in both directions, the next two values are 2 and 7, so these are the next two elements in the reordered array. Moving inwards further, the next two values are 3 and 6, which become the next two elements in the reordered array. Finally, we get to the inner values in the array being reordered, 4 and 5, which become the last two elements of the reordered array.
VARIATION
reorderedARRAY = Uize.Array.Order.outsideIn (sourceARRAY,targetARRAYorBOOL);
When the optional targetARRAYorBOOL parameter is specified, the target destination for the reordered elements can be controlled (for more info, see the reference for the targetARRAYorBOOL value type).
NOTES
see the related Uize.Array.Order.insideOut, Uize.Array.Order.jumble, Uize.Array.Order.reorder, and Uize.Array.Order.reverse static methods |
IMPLEMENTATION INFO
| this feature was introduced in this module |
2.4. Uize.Array.Order.reorder
Returns an array, being a reordered version of the specified source array, using the specified reordering mode.
SYNTAX
reorderedARRAY = Uize.Array.Order.reorder (sourceARRAY,reorderingModeSTR);
VARIATION 1
reorderedARRAY = Uize.Array.Order.reorder (sourceARRAY,reorderingModeSTR,targetARRAYorBOOL) ;
By default, the Uize.Array.Order.reorder method packages the reordered array elements into a new array and does not modify the source array (i.e. it's non-destructive). Specifying the optional targetARRAYorBOOL parameter allows us to explicitly specify a target for the operation, into which the reordered elements will be packaged.
VARIATION 2
jumbledARRAY = Uize.Array.Order.reorder (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.4.1. reorderingModeSTR
The reorderingModeSTR parameter is a string, specifying the reordering mode that should be employed, and can have the following values...
'jumbled' (default) - reorders the specified source array in the same way as the Uize.Array.Order.jumble static method |
|
'reverse' - reorders the specified source array in the same way as the Uize.Array.Order.reverse static method |
|
'inside out' - reorders the specified source array in the same way as the Uize.Array.Order.insideOut static method |
|
'outside in' - reorders the specified source array in the same way as the Uize.Array.Order.outsideIn static method |
|
'normal' - leaves the order of elements unchanged |
NOTES
see the related Uize.Array.Order.insideOut, Uize.Array.Order.jumble, Uize.Array.Order.outsideIn, and Uize.Array.Order.reverse static methods |
IMPLEMENTATION INFO
| this feature was introduced in this module |
2.5. Uize.Array.Order.reverse
Returns an array, being a reversed version of the specified source array.
SYNTAX
reorderedARRAY = Uize.Array.Order.reverse (sourceARRAY);
EXAMPLE
Uize.Array.Order.reverse ([1,2,3,4,5,6,7,8]); // returns the array [8,7,6,5,4,3,2,1]
VARIATION
reorderedARRAY = Uize.Array.Order.reverse (sourceARRAY,targetARRAYorBOOL);
When the optional targetARRAYorBOOL parameter is specified, the target destination for the reversed elements can be controlled (for more info, see the reference for the targetARRAYorBOOL value type).
NOTES
see the related Uize.Array.Order.insideOut, Uize.Array.Order.jumble, Uize.Array.Order.outsideIn, and Uize.Array.Order.reorder static methods |
IMPLEMENTATION INFO
| this feature was introduced in this module |
3. Value Types
For the sake of not redundantly describing the value types for certain method parameters and return values repeatedly, some common value types are described here.
3.1. sourceARRAY
An array reference, specifying an array that should be processed by an array method.
Values of this type can be accepted by the Uize.Array.Order.insideOut, Uize.Array.Order.jumble, Uize.Array.Order.outsideIn, Uize.Array.Order.reorder, and Uize.Array.Order.reverse static methods.
3.1.1. Array-like Values
Methods that accept parameters of the sourceARRAY value type can also support array-like objects, such as collections of DOM nodes - provided that the source array is not also specified as the target for reordered elements.
3.2. targetARRAYorBOOL
An array reference or boolean value, which lets you specify where the result of an array method's processing should be packaged.
Values of this type can be accepted by the Uize.Array.Order.insideOut, Uize.Array.Order.jumble, Uize.Array.Order.outsideIn, Uize.Array.Order.reorder, and Uize.Array.Order.reverse static methods.
VALUES
When the boolean value true is specified (the default value for the targetARRAYorBOOL parameter if it is omitted), then the result of an array method's processing will be packaged into a new array. |
|
When the boolean value false is specified (not the same as not specifying a value), then the result of an array method's processing will be packaged into the source array that was supplied to the array method in its sourceARRAY parameter (i.e. the method won't use a different target). |
|
When an array is explicitly specified, then the result of an array method's processing will be packaged into the specified target array. This is convenient if you already have an array into which you wish to package the result. Incidentally, specifying the source array that you supplied to an array method as also the target array has the same effect as specifying the value false for targetARRAYorBOOL (i.e. use the source as the target, don't use a different target). |