Methods to make working with arrays more convenient and collection-like.

Methods

(inner) batchify(array, constrainedFunc, context)

Takes elements and fits them into subarrays (= batches) so that for each batch constrainedFunc returns true. Note that contrainedFunc should at least produce 1-length batches, otherwise an error is raised.

Parameters:
NameTypeDescription
arrayArray.<any>
constrainedFuncfunction
contextObject

bound to this when calling constrainedFunc

(inner) binarySearchFor(array, searchValue, converter, returnClosestElement) → {Object}

Returns the element equal to the given search value or undefined.

If defined, a converter function will be applied to compare an array element with the search value

If returnClosestElement is true, the element closest to the search value will be returned, even if it is not equal.

If false, only an exact match will be returned, otherwise undefined will be returned.

Parameters:
NameTypeDefaultDescription
arrayArray.<any>

The array in which to search

searchValueObject

The value to search for in array

converterfunction

The function used to compare array elements with searchValue

returnClosestElementBooleanfalse

Whether only exact matches should be returned

Returns:
Type: 
Object

(inner) clear(array)

Removes all items. Mutating.

Parameters:
NameTypeDescription
arrayArray.<any>

(inner) clone(array)

Returns a shallow copy of array.

Parameters:
NameTypeDescription
arrayArray.<any>

(inner) combinations(listOfListsOfValues) → {Array.<Array.<any>>}

Given a "listOfListsOfValues" in the form of an array of arrays, retrieve all the combinations by picking one item from each array. This basically creates a search tree, traverses it and gathers all node values whenever a leaf node is reached.

Parameters:
NameTypeDescription
listOfListsOfValuesArray.<Array.<any>>
Returns:
Type: 
Array.<Array.<any>>

(inner) combinationsPick(listOfListsOfValues, pickIndices)

Can be used to recursively create all combinations of elements in n arrays. Given a "listOfListsOfValues" in the form of an array of arrays and pickIndices list with the size of the number of arrays which indicates what values to pick from each of the arrays. Returns a list with two lists:

  1. values picked from each of the arrays, 2. the next pickIndices or null if at end (no more combinations possible). Needs to be called recursively to enumerate alls combinations.
// Example:
var searchSpace = [["a", "b", "c"], [1,2]];
arr.combinationsPick(searchSpace, [0,1]);
// => [["a",2], [1,0]]
arr.combinationsPick(searchSpace, [1,0]);
// => [["b",1], [1,1]]
Parameters:
NameTypeDescription
listOfListsOfValuesArray.<Array.<any>>
pickIndicesArray.<number>

(inner) compact(array) → {Array.<any>}

Returns a copy of array with falsy values removed.

Parameters:
NameTypeDescription
arrayArray.<any>
Returns:
Type: 
Array.<any>

(inner) count(array, item)

Returns the number of times item occurs in array.

Parameters:
NameTypeDescription
arrayArray.<any>
itemany

(inner) deepEquals(array, otherArray, m) → {boolean}

Returns true if each element in array is structurally equal (lang.obj.equals) to its corresponding element in otherArray.

Parameters:
NameTypeDescription
arrayArray.<any>
otherArrayArray.<any>
mArray.<any>

Gets populated with memorization when this function is called as part of obj.equal

Returns:
Type: 
boolean

(inner) doAndContinue(array, iterator, endFunc, context)

Iterates over array but instead of consecutively calling iterator, iterator gets passed in the invocation for the next iteration step as a function as first parameter. This allows to wait arbitrarily between operation steps, great for managing dependencies between tasks.

arr.doAndContinue([1,2,3,4], function(next, n) {
  alert("At " + n);
  setTimeout(next, 100);
}, function() { alert("Done"); })

If the elements are functions you can leave out the iterator:

arr.doAndContinue([
  function(next) { alert("At " + 1); next(); },
  function(next) { alert("At " + 2); next(); }
], null, function() { alert("Done"); });
Parameters:
NameTypeDescription
arrayArray.<any>

The array to iterate over

iteratorfunction

The function that is called for each element of array

endFuncfunction

A function called once after iterating over array

contextObject

Bound to this in iterator

(inner) drop(arr, n) → {Array.<any>}

Parameters:
NameTypeDescription
arrArray.<any>
nnumber
Returns:

arr without the first n elements.

Type: 
Array.<any>

(inner) dropWhile(arr, fun, context)

Return elements from arr in a list starting from fun being falsy while iterating over arr.

Parameters:
NameTypeDescription
arrArray.<any>
funfunction
contextObject

bound to this when calling fun

(inner) equals(array, otherArray) → {boolean}

Returns true if each element in array is equal (==) to its corresponding element in otherArray.

Parameters:
NameTypeDescription
arrayArray.<any>
otherArrayArray.<any>
Returns:
Type: 
boolean

(inner) filterByKey(arr, key) → {Array.<any>}

Returns only the Objects in arr that have key as property.

Parameters:
NameTypeDescription
arrArray.<any>
keystring
Returns:
Type: 
Array.<any>

(inner) findAndGet(arr, iterator) → {Object}

Find the first occurence for which iterator returns a truthy value and return this value, i.e. unlike find the iterator result and not the element of the list is returned.

Parameters:
NameTypeDescription
arrArray.<any>
iteratorfunction
Returns:
Type: 
Object

(inner) first()

Returns the first element of an array.

(inner) genN(n, generator) → {Array.<any>}

Creates an array with the result of generator called n times.

arr.genN(3, num.random) => [46,77,95]

Parameters:
NameTypeDescription
nnumber
generatorfunction
Returns:
Type: 
Array.<any>

(inner) grep(arr, test) → {Array.<any>}

Returns an array that contains all elements of arr that contain/satisfy test. grep stringifies all elements in arr.

Parameters:
NameTypeDescription
arrArray.<any>
testString | RegEx
Returns:
Type: 
Array.<any>

(inner) groupBy(array, iterator, context)

Applies iterator to each element in array and puts the return value into a collection associated to its stringified representation.

// Example: Groups characters by how often they occur in a string
var chars = arr.from("Hello World");
arr.groupBy(arr.uniq(chars), function(c) {
return arr.count(chars, c); })
=> {
  "1": ["H","e"," ","W","r","d"],
  "2": ["o"],
  "3": ["l"]
}
Parameters:
NameTypeDescription
arrayArray.<any>
iteratorfunction
contextObject

Bound to this when calling iterator

See
  • lively.lang/Group

(inner) groupByKey(array, key)

Parameters:
NameTypeDescription
arrayArray.<any>
keystring
See
  • lively.lang/array~groupBy

(inner) histogram(data, binSpec)

When called without binspec, returns data partitioned into lists containing two elements each. binspec can be an array of n numbers. If given, histogram will create n-1 bins, using the provided values in binspec as threshholds. The n-1 bins will be returned as a list. T

Parameters:
NameTypeDescription
dataArray.<number>

The data to be partitioned

binSpecArray.<number>

The threshholds used to partition the data. binspec should be sorted ascending.

(inner) interpose(array, delim) → {Array.<any>}

/** Returns a new array that contains an element of arra and delim alternating.

Parameters:
NameTypeDescription
arrayArray.<any>
delimany
Returns:
Type: 
Array.<any>

(inner) intersect(array1, array2)

Rerturns the intersection of array1 and array2 according to set semantic.

Parameters:
NameTypeDescription
array1Array.<any>
array2Array.<any>

(inner) invoke(array, method, arg1, arg2, arg3, arg4, arg5, arg6)

Calls method on each element in array, passing all arguments. Often a handy way to avoid verbose map calls.

Parameters:
NameTypeDescription
arrayArray.<any>
methodfunction

The method to invoke on all elements of array

arg1any
arg2any
arg3any
arg4any
arg5any
arg6any

(inner) isSorted(array, descending) → {boolean}

Returns a boolean indicating whether or not array is sorted.

Parameters:
NameTypeDescription
arrayArray.<any>
descendingboolean

indicating if array should be checked for descending or ascending order

Returns:

wether array is sorted or not

Type: 
boolean

(inner) isSubset(list1, list2) → {boolean}

Returns wether all elements in list1 are in list2.

Parameters:
NameTypeDescription
list1Array.<any>
list2Array.<any>
Returns:
Type: 
boolean

(inner) last()

Returns the last element of an array.

(inner) mask(array, mask) → {Array.<any>}

Return an array containing all elements or array for which mask contains a truthy value at the same index.

Parameters:
NameTypeDescription
arrayArray.<any>

The array which should be subsetted.

maskArray.<Boolean>

Array used for masking array.

Returns:
Type: 
Array.<any>

(inner) max(array, iterator, context)

Return the element of array which has the highest value according to iterator.

Parameters:
NameTypeDescription
arrayArray.<any>
iteratorfunction
contextObject

bound to this when calling iterators

(inner) min(array, iterator, context)

Return the element of array which has the smallest value according to iterator.

Parameters:
NameTypeDescription
arrayArray.<any>
iteratorfunction
contextObject

bound to this when calling iterators

(inner) mutableCompact(array) → {Array.<any>}

Returns array with falsy values removed.

Parameters:
NameTypeDescription
arrayArray.<any>
Returns:
Type: 
Array.<any>

(inner) nestedDelay(array, iterator, waitSecs, endFunc, context, optSynchronChunks)

Calls iterator for every element in array and waits between iterator calls waitSecs. Eventually endFunc is called. When passing a number n as optSynchronChunks, only every nth iteration is delayed.

Parameters:
NameTypeDescription
arrayArray.<any>

The array to iterate

iteratorfunction
waitSecsnumber

The number of seconds to wait between invocations of iterator

endFuncfunction

A function called once after iterating over array

contextObject

Bound to this in iterator

optSynchronChunksnumber

Only wait after each nth element

(inner) partition(array, iterator, context)

Partition array according to a condition specified in iterator. Creates two partitions (condition is either true or false).

Parameters:
NameTypeDescription
arrayArray.<any>
iteratorfunction
contextObject

bound to this when calling iterator

(inner) permutations(array)

Returns the number of permutations of the elements in array.

Parameters:
NameTypeDescription
arrayArray.<any>
Returns:

number

(inner) pluck(array, property)

Returns property or undefined from each element of array. For quick maps and similar to invoke.

Parameters:
NameTypeDescription
arrayArray.<any>
propertystring

The property to return

(inner) pushAll(array, items) → {Array.<any>}

Appends all items to array. Mutating.

Parameters:
NameTypeDescription
arrayArray.<any>
itemsArray.<any>
Returns:

array

Type: 
Array.<any>

(inner) pushAllAt(array, items, idx)

Inserts all items at idx. Mutating.

Parameters:
NameTypeDescription
arrayArray.<any>
itemsArray.<anu>
idxnumber

(inner) pushAt(array, item, index)

Inserts item at index. Mutating.

Parameters:
NameTypeDescription
arrayArray.<any>
itemany
indexnumber

(inner) pushIfNotIncluded(array, item)

Only appends item if its not already in array. Mutating.

Parameters:
NameTypeDescription
arrayArray.<any>
itemany

(inner) range(begin, end, step) → {Array.<number>}

Creates an array containing elements from begin until end with step-sized steps.

Parameters:
NameTypeDescription
beginnumber

First element

endnumber

Last element

stepnumber

step size

Returns:
Type: 
Array.<number>

(inner) reject(array, func, context) → {Array.<any>}

Returns an array of all elements of array for which func is falsy.

Parameters:
NameTypeDescription
arrayArray.<Obejct>

The array which should be subsetted.

funcfunction

Function that is used for testing.

contextObject

Acts as this when calling func.

Returns:
Type: 
Array.<any>

(inner) rejectByKey(array, key) → {Array.<any>}

Returns an array of all elements of array that do not have key as property.

Parameters:
NameTypeDescription
arrayArray.<any>
keystring
Returns:
Type: 
Array.<any>

(inner) reMatches(arr, re, stringifier)

Returns the matches of re for the elements in arr. Might include null items if re did not match.

Parameters:
NameTypeDescription
arrArray.<any>
re*

The refular expression to use

stringifier*

Used to stringify the elements of arr. Defaults to String.

(inner) remove(array, item) → {any}

Removes the first occurrence of item in array. Mutating.

Parameters:
NameTypeDescription
arrayArray.<any>
itemany
Returns:

item

Type: 
any

(inner) removeAt(array, index)

Remove the element of array at index. Mutating.

Parameters:
NameTypeDescription
arrayArray.<any>
indexnumber

(inner) replaceAt(array, item, index)

Replace the element array[index] with item. Mutating.

Parameters:
NameTypeDescription
arrayArray.<any>
itemany
indexnumber

(inner) rotate(array, times) → {Array.<any>}

Shift the elements in array to the left times times.

Parameters:
NameTypeDescription
arrayArray.<any>
timesnumber
Returns:
  • A copy of array rotated times times
Type: 
Array.<any>

(inner) shuffle(array)

Randomizes the order of elements in array. Non-mutating.

Parameters:
NameTypeDescription
arrayArray.<any>

(inner) sortBy(array, iterator, context)

Sorts array according to the elements value of iterator.

Parameters:
NameTypeDescription
arrayArray.<any>

the array to sort

iteratorfunction

the function to use to sort array

contextObject

Used as this when calling iterator

(inner) sortByKey(array, key)

Sorts array by the values of a given key.

Parameters:
NameTypeDescription
arrayArray.<any>

the array to sort

keystring

the key to sort by

(inner) sum(array)

Return the sum of the elements of array.

Parameters:
NameTypeDescription
arrayArray.<number>

(inner) swap(array, index1, index2)

Swap the element at array[index1] with the one at array[index2]. Mutating.

Parameters:
NameTypeDescription
arrayArray.<any>
index1number
index2number

(inner) take(arr, n) → {Array.<any>}

Parameters:
NameTypeDescription
arrArray.<any>
nnumber
Returns:

The first n elements of arr.

Type: 
Array.<any>

(inner) takeWhile(arr, fun, context)

Return elements from arr in a list until fun is falsy while iterating over arr.

Parameters:
NameTypeDescription
arrArray.<any>
funfunction
contextObject

bound to this when calling fun

(inner) toTuples(array, tupleLength)

Decomposes array into sub-arrays with at most tupleLength elements.

Parameters:
NameTypeDescription
arrayArray.<any>
tupleLengthnumber

description

(inner) union(array1, array2)

Rerturns the union of array1 and array2 according to set semantic.

Parameters:
NameTypeDescription
array1Array.<any>
array2Array.<any>

(inner) uniq(array, sorted) → {Array.<any>}

Returns array without duplicates.

Parameters:
NameTypeDescription
arrayArray.<any>
sortedboolean

Wether array is sorted. Used for optimizations.

Returns:
Type: 
Array.<any>

(inner) uniqBy(array, comparator, context) → {Array.<any>}

Like arr.uniq but with custom equality comparator(a,b).

Parameters:
NameTypeDescription
arrayArray.<any>
comparatorfunction

Function used to determine if a equals b

contextObject

Used as this when calling comparator.

Returns:
Type: 
Array.<any>

(inner) uniqByKey(array, key) → {Array.<any>}

Like arr.uniq but with equality based on array[index].key.

Parameters:
NameTypeDescription
arrayArray.<any>
keystring
Returns:
Type: 
Array.<any>

(inner) withN(n, obj) → {Array.<any>}

Returns an array filled with obj for n times.

Parameters:
NameTypeDescription
nnumber

Length of the array to create

objObject

Object with which the array is to be filled

Returns:
Type: 
Array.<any>

(inner) without(array, elem) → {Array.<any>}

Returns a copy of array without elem.

Parameters:
NameTypeDescription
arrayArray.<any>
elemObject
Returns:
Type: 
Array.<any>

(inner) withoutAll(array, otherArr) → {Array.<any>}

Returns a copy of array without all elements in otherArr.

Parameters:
NameTypeDescription
arrayArray.<any>
otherArrArray.<any>
Returns:
Type: 
Array.<any>

(inner) zip(arguments) → {Array.<any>}

Takes any number of lists as arguments. Combines them elment-wise.

arr.zip([1,2,3], ["a", "b", "c"], ["A", "B"])
=> [[1,"a","A"],[2,"b","B"],[3,"c",undefined]]
Parameters:
NameTypeDescription
arguments

Any number of lists

Returns:
Type: 
Array.<any>