Looping

Looping methods are functions that process the iterated values of the collection. Most change the store - in fact, most replace the store with a new instance.

Most of the looping functions take a single property that has the same input arguments. You can have as many or as few arguments as you want, but they are, in order:

  • memo: the current output -- for .reduce(..) and .reduceC() only.
  • item: an item.
  • key: its key.
  • store: the .value property of the collection. it's advisable NOT to change the store; its provided here for informational purposes only.
  • stopper: an object that allows you to interrupt the looping: see below.

This is based on the forEach/map/reduce patterns of the Array class, but it's found in other contexts as well. (Map has forEach for instance).

💡

All of these methods return the target Collection -- except reduce, that returns the loop methods' last output.

The Stopper

stopper is a class that provides methods that let you interrupt the looping.

  • stopper.stop(): interrupts the looping before the current key/value pair is used.
  • stopper.stopAfterThis() accepts the current value, then stops the looping.

The difference is shown in the last cycle between accepting the result of the current run of the loop function or tossing it out.

const numbers = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
numbers.map(item => item * 10);
console.log('numbers is now ', numbers.value);
const sumOfAll = numbers.reduce((memo, item) => memo + item, 0);
console.log('sum of all', sumOfAll);
const sumOfFive = numbers.reduce((memo, item, key, _store, stopper) => {
  if (key === 4) stopper.stopAfterThis();
  return memo + item;
}, 0);
console.log('sum of first five', sumOfFive);
const sumOfFour = numbers.reduce((memo, item, key, _store, stopper) => {
  if (key === 4) stopper.stop();
  return memo + item;
}, 0);
console.log("sum of first four", sumOfFive);
/**
numbers is now  [
  10, 20, 30, 40,  50,
  60, 70, 80, 90, 100
]
sum of all 550
sum of first five 150
sum of four 100
*/

forEach(looper): self

Iterates over the collections' content; returns the target collection. The return value of the looper is ignored.

map(looper): self

Asserts the result of the loop into the key of the collection. the store isn't changed til after the last loop. At that point it is replaced by a new instance of the same type.

If you call any method on the stopper it will shorten the size of the store -- tossing all the un-looped over values.

Any thrown error will leave the collection unchanged.

If you want to produce a new collection and leave the original values unchanged call const newCollection = myCollection.c.map(looper);

reduce(looper, initial): any

Reduce takes the initial in as the first "meta" argument. From then on, the output of the previous loop is the meta of the next loop. The output of the last loop is the output of reduce().

If initial is not passed in the first loop receives undefined as the memo. This differs from the Array.reduce in that Array.reduce uses the first element of the array as the first meta value if an initial value is not passed in -- meaning, loop executes from the second input onward.

this is the only method in this page that does not return the target collection or modify the target collection. As there is NO restriction on the memo format, there is no guarantee that it is the same type as the original store.

reduceC(looper, initial): collection

equivalent to create(myCollection.reduce(looper, initial)). Wraps the reduce result in a new collection.