Functions Iterable

The iterable functions here will work with Arrays or any of the iterable collection types in this library. They will also work with any custom iterable that defines a constructor property that will work without using new.

These functions are also used as the basis of the methods used by the iterable collections.

All of these functions return a new value. None of them will mutate the original iterable.

All functions that take multiple arguments and the iterable last are auto-curried, so you can generate a new function using partial application.

Example:

const double = map(x => x * 2); // will double all the numbers in an iterable

The functions

• isIterable(obj) - returns true if an object is iterable.
• isArray(obj) - returns true if object is an array.
• all(search, iter) - search can be a function, RegExp, or any value (including objects). If every item in the iterable passes, returns true.
• any(search, iter) - search can be a function, RegExp, or any value (including objects). If any item in the iterable passes, returns true.
• ap(other, iter) - applies all the functions in an iterable of functions to all the items of iter.
• append(item, iter) - adds an item to the end of iter.
• at(index, iter) - returns Option, Some if there is a value at the index and None if there is not.
• atUnsafe(index, iter) - like at, but unwraps the value from the Option. May return a null or undefined value.
• average(iter) - returns Option, Some containing the average value of an iterable full of numbers and None if the iterable is empty.
• chain(fn, iter) - flattens an iterable, then maps its elements according to fn.
• compact(iter) - removes all null, undefined, and NaN values from an iterable.
• concat(...iters) - concatenates iterables into a single iterable of the first argument's type.
• concatToArray(...iters) - concatenates iterables into a single Array.
• copyWithin(iter, target[, start, end]) - shallow copies part of an iterable to another location in the same iterable and returns it without modifying its length.
• count(search, iter) - search can be a function, RegExp, or any value (including objects). Returns the count of items in the iterable that satisfy search.
• difference(iter1, iter2) - returns an iterable containing the difference between the first and second arguments.
• each(fn, iter) - runs fn on each item in the iterable.
• eachWithIndex(fn, iter) - same as each, but the callback takes both the item and its index.
• entries(iter) - returns an Array of Arrays, each containing a pair of the item's index and the item itself.
• exclude(pred, iter) - alias for reject
• find(pred, iter) - finds an item in the iterable based on the predicate function. Returns an Option, in case the item is not found. Pred can be a predicate function, a RegExp, or any value (including objects).
• findIndex(pred, iter) - returns an Option containing the index of the found item, or None if it is not found. Pred can be a predicate function, a RegExp, or any value (including objects).
• first(iter) - returns an Option, Some of the first value in the iterable if it is not empty, otherwise None.
• flatten(iter) - flattens an iterable of iterables into a single iterable of the container's type.
• flatMap(fn, iter) - alias for chain.
• fold(fn, initial, iter) - alias for reduce.
• foldLeft(fn, initial, iter) - alias for reduce.
• foldRight(fn, initial, iter) - alias for reduceRight.
• forEach(fn, iter) - alias for eachWithIndex.
• from(index, iter) - returns a slice of the iterable from index to the end.
• get(index) - alias for at.
• includes(value, iter) - Returns true if iter contains value. Works with any value, including objects.
• indexOf(iter, value[, start]) - returns Option, Some of the first index of value if it is found, otherwise None.
• insert(item, index, iter) - inserts item at index of iter
• intersection(iter1, iter2) - returns an iterable containing the intersection of the two iterables.
• isEmpty(iter) - returns true if an iterator contains no values.
• isEqual(iter1, iter2) - returns true if both iterables contain the same values. Checks objects by value (deep equality), not by reference.
• join(sep, iter) - joins all the values in an iterator into a string, calling toString on each element, separating elements by sep.
• keys(iter) - returns the keys of an iterable
• last(iter) - returns an Option, Some of the last value in an iterator or None if it is empty.
• length(iter) - returns the length of an iterator.
• map(fn, iter) - returns a new iterator of the same type with values mapped from the original using fn.
• mapWithIndex(fn, iter) - same as map, but also passes the index number into the mapping function.
• max(iter) - returns Option, Some of the max value of an iterable full of numbers or None if it is empty.
• median(iter) - returns Some of the median value of an iterable full of numbers or None if the iterable is empty.
• min(iter) - returns Some of the min value of an iterable full of numbers or None if it is empty.
• none(search, iter) - returns true if none of the items in the array match search, which can be a function, RegExp, or any value (including an object).
• pluck(numItems, iter) - returns an iterable of the first numItems items in iter.
• pop(iter) - alias for last.
• prepend(item, iter) - prepends item to the front of iter.
• product(iter) - returns Option, Some of all the values of an iterable full of numbers multiplied together, None if it is empty.
• push(item, iter) - alias for append.
• reduce(fn, initial, iter) - generates a single value from the values in the iterable. Must supply initial value in addition to reducer function.
• reduceRight(fn, initial, iter) - same as reduce, but traverses the iterable backwards.
• reject(fn, iter) - the opposite of filter - values that pass the predicate will be removed from the result.
• remove(search, iter) - removes all items that match search from the iterable. search can be a function, RegExp, or any value (including an object).
• reverse(iter) - reverses an iterable.
• sample(iter) - returns a random value from the iterable.
• shift(iter) - alias for first.
• shuffle(iter) - uses the Fisher-Yates algorithm to shuffle an iterable.
• slice(iter, [start,] end[, step]) - Python-style slicing. If you pass an iterable and a single argument it will take that as the end value. step defaults to 1. Can use negative indices and a negative step value to reverse the slice.
• some(search, iter) - alias for any.
• sort(iter[, { key, fn, reversed }]) - returns a sorted iterable. If you provide no additional arguments, it will properly sort numbers, strings, or booleans (unlike the native JavaScript Array.prototype.sort). If you provide a key in the options object, it will sort objects based on the value of that key (again, properly sorting numbers, strings, and booleans). If you need more control, provide a function for fn. Only use one of key or fn. If you want the sort order reversed, set reversed to true.
• splice(iter[, start, deleteCount, ...items]) - insert or remove items from an iterable. start and deleteCount default to 0. Providing one or more items will cause them to be inserted at start. If deleteCount is set to something other than 0, that many items will be removed from the returned iterable.
• removeAt(iter, start[, end]) - removes items from iter starting at index start and going until end (non-inclusive) or the end of the iterable.
• sum(iter) - returns Option, Some of the value of all numbers added together or None for an empty iterable.
• symmetricDifference(iter1, iter2) - returns a new iterable containing the symmetric difference of its arguments.
• take(index, iter) - alias for pluck.
• to(index, iter) - returns a new iterable containing the items from the beginning of iter to index (non-inclusive).
• toArray(iter) - converts any iterable to an Array.
• union(iter1, iter2) - returns the union of its arguments.
• unique(iter) - strips out duplicate entries from an iterable.
• unshift(iter) - alias for prepend.
• update(updater, index, iter) - uses the function updater to update the value of iter at index. If index is not in iter the iterable will be returned unchanged.
• values(iter) - returns an array of the values of an iterable.
• zip(iters) - zips a series of iterators; for example, zip([1, 2, 3], ["a", "b", "c"]) returns [[1, "a"], [2, "b"], [3, "c"]]. This method is unsafe, as you may have null values. Use only if you know all your iterables are the same length.