Iterators - DarthJDG/Mangler.js GitHub Wiki

Standard iterator

You can use the .each() utility function to call a callback function for each element of an iterable object. Built-in iterables are arrays, objects and mangler objects. You can break the iteration by returning false from the callback function. The callback function has the following signature:

function(key, value)

Arrays

The callback function is called for each array item, passing the parameters (index, item). For sparse arrays, undefined elements will be skipped.

sum = 0;
array = [1,2,3];

Mangler.each(array, function(index, item) {
	sum += item;
});

// sum = 6

Objects

The callback function is called for each of the object's own properties, passing the parameters (property_name, value). Due to the JavaScript language specifications, the exact order of property enumeration cannot be guaranteed.

sum = 0;
properties = [];

object = {
	one: 1,
	two: 2,
	three: 3
};

Mangler.each(object, function(property, value) {
	sum += value;
	properties.push(property);
});

// sum = 6
// properties = ['one', 'two', 'three']

Mangler objects

Iterating through a mangler object is the same as iterating through its .items[] property. Just like most utility functions, .each() can also be called as a mangler object method, without the first parameter.

m = Mangler(...);
callback = function(k, v) {...};

// The following calls are equivalent:
Mangler.each(m, callback);
Mangler.each(m.items, callback);
m.each(callback);

Other container objects

The list of iterable objects can be expanded by registering custom handler functions. The Mangler-natives module adds support for native typed arrays. If you want to make your own object instances iterable, read the advanced topic of Type handling.

Recursive iterator

With the .explore() function, you can recursively iterate all iterable objects and their iterable children. Returning false from the callback function will not break the iteration, but it will prevent recursive processing of the current iterable value, continuing with its sibling, skipping its children.

Mangler.explore(iterable, callback[, state])

• iterable is the root object to start from
• callback is the function to call for all values found
• state is an optional object to initialise the callback's parameter

Callback signature:

function(key, value[, state])

• key and value are the same as the standard iterator's
• state is an object containing information about the current step:
  • state.$path is a string describing the value's path from the root
  • state.$parent is the parent object containing the key/value pair
  • state.$parentPath is a string with the parent's path from the root

Given the following code:

data = [
	{
		child: { one: 1 }
	},
	{
		children: [{ two: 2 }, { three: 3 }]
	}
];

Mangler.explore(data, callback);

it will result in the following calls to the callback function:

// key        value                         state.$path

0             { child: ... }                '[0]'
'child'       { one: 1 }                    '[0].child'
'one'         1                             '[0].child.one'
1             { children: ... }             '[1]'
'children'    [{ two: 2 }, { three: 3 }]    '[1].children'
0             { two: 2 }                    '[1].children[0]'
'two'         2                             '[1].children[0].two'
1             { three: 3 }                  '[1].children[1]'
'three'       3                             '[1].children[1].three'

For more examples, look at .explore() in the API reference.