Global

Methods

controlledLoop(data, controlleropt, optionsopt) → {controlled-loop}

Creates a controlled-loop instance.
This is not a Class and does not need the new operator

Examples

All parameters

var myArray = [1,2,3,4,5,6,7,8,9,10];
var doubleValue = function(v){console.log(v*2); return v*2;};
var myOptions = {increment:2, startAt:1};
var loop = controlledLoop(myArray, doubleValue, myOptions);
// => creates a controlled-loop that will iterate over even numbered values in the array and double them.
// => Outputs to the console:
// 4
// 8
// 12
// 16
// 20

Without options

var myArray = [1,2,3,4,5,6,7,8,9,10];
var doubleValue = function(v){ console.log(v*2); return v*2;};
var loop = controlledLoop(myArray, doubleValue);
// => Outputs to the console:
// 2
// 4
// 6
// 8
// 10
// 12
// 14
// 16
// 18
// 20

Without controller as an option

var myobj = {a:1, b:2, c:3, d:4, e:5, f:6, g:7, h:8, i:9, j:10};
var myOptions = {keys:['a','d','e','h'], controller: function(v,k){ console.log("Key: "+k); console.log("Value: "+v);}}
var loop = controlledLoop(myobj, myOptions);
// => Outputs to the console:
// Key: a
// Value: 1
// Key: d
// Value: 4
// Key: e
// Value: 5
// Key: h
// Value: 8

Without options or controller

var myArray = [1,2,3,4,5,6,7,8,9,10];
var loop = controlledLoop(myArray);
// => creates a controlled-loop that will iterate over all values in the array and echo the value.
Parameters:
Name Type Attributes Description
data array | object
controller Controller <optional>

The callback function, the default function is just an echo
options Options <optional>

Additional options.
Returns:

the controlled loop instance

Type
controlled-loop

References

Controller

Default Value:
  • function(value){ return value }

The controller/callback to be passed into a controlledLoop function

Type:
  • function

Options

Properties:
Name Type Attributes Default Description
increment number <optional>
 1

How much to increment the position within the options.keys by each time controlled-loop.next, controlled-loop.previous, or controlled-loop.run are called.
startAt StartAt <optional>
 0

Where to start at within the data if you do not wish for the first element processed to be key 0.
keys array <optional>

The object or array keys to iterate through. Can be used for a partial list or sorted list of keys, etc. If not provide, [Object.keys()]{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys} will be used. If the initial data is an array with missing elements (e.g. var a=[]; a[0]=1; a[1]=2; a[12]=3), only the defined keys will be run (e.g. keys=[0,1,12]).
reverse boolean <optional>

whether to start the loop in reverse
apply boolean | * <optional>

if true then the 'controller' function will be Function.apply() using the 'data'. If any other non-falsy value, the function will be applied to that.
controller function <optional>
 function(v){ return v; }

The controller function can be passed in as an options property also. If a controller is passed in both places, this one will take precedence.

The options object to be passed into a controlledLoop function. All properties are optional

Type:
  • Object

StartAt

Default Value:
  • 0

The StartAt number is used in the initial options and as a parameter for reset() and reverse()

The controlled loop maintains an internal array of the keys and its current position within that array.

By default, on initialization or reset(), the current position will be such that when you use next() it will go to position 0 with the keys array (or the end if going in reverse).

If you wish to the first element processed to be something other than 0, then use a StartAt. For example, if you are incrementing by 3 and want the first element processed to be the 3rd key, the StartAt option would be 2 (0,1,2).

This is calculated as such:
Normal: position = 0 + StartAt - Increment
Reversed: position = (length-1) - StartAt + Increment

So it is possible that on initialization or reset() that both next() and previous() are possible

Type:
  • number
Example

Starting at the 3rd item

var myArray = [1,2,3,4,5,6,7,8,9,10];
var myOptions = {increment:3, startAt:2};
var loop=controlledLoop(myArray,myOptions);
loop.next();
// => { value:3, key: 2, done: false, donep:true}

loop.reverse(true, 2).next();
// => { value:8, key: 7, done: false, donep:true}

ReturnValue

Properties:
Name Type Description
value *

the value returned by the controller. Will be undefined if the process tries to run an "out-of-bounds" data (e.g. using next() after reaching the end of the data)
key string | number

the data key which was processed by the controller. Will be undefined if the process tries to run an "out-of-bounds" data
done isDone

whether you have hit the end of the the data going forward. Attempting next(), or similar will return as "out-of-bounds" result but not move the internal position.
donep isDone

whether you have hit the end of the the data going backwards. Attempting previous(), or similar, will return as "out-of-bounds" result but not move the internal position.

The return value from any function which runs the controller (e.g. next(), previous(), repeat(), getLastReturn())

Type:
  • Object

isDone

A boolean whether processing has reached the end of the data.

If the increment is greater than 1, then the position may not be at the last item in the data.

It means that you cannot move by the increment amount without going "out-of-bounds" (0 or length-1).

Type:
  • boolean
Example
var myArray = [1,2,3,4,5,6,7,8,9,10]; // last = 9
var myOptions = {increment:5};
var loop=controlledLoop(myArray,myOptions);
loop.next();
// => { value: 1, key: 0, done: false, donep: true}
// internal position = 0
// You cannot use previous() because 0-5=-5 which is "out of bounds"

loop.next();
// => { value: 6, key: 5, done: true, donep: false}
// internal position = 5
// You cannot use next() because 5+5=10 which is "out-of bounds"

Status

Properties:
Name Type Description
position number

where the internal marker is (the current index in the keys array)
end number

The index of the last item in the keys array (length-1)
done isDone

Whether it is currently complete moving forward
donep isDone

Whether it is currently complete moving backward
increment number

the current increment amount
values array

An array of the values returned by the controller
keys array

the keys for the loop data
reversed boolean

Whether the loop is reversed
paused boolean

Whether the loop is paused
applied boolean

Whether the controller calls are being applied to an object
target boolean

The target the controller is being applied to
Type:
  • object