Array

An ordered collection of values with fast random access, push(...values), and pop(), but can be slow to splice when sufficiently massive.

The shim-array module provides extensions so it hosts all the expressiveness of other collections. The shim-array module shims some ECMAScript 5 methods onto the array prototype if they are not natively implemented.

Properties

length

The number of items in this collection.

Methods

push(...values)

Adds values to the end of a collection.

pop()

Removes a value from the end of a collection, and returns that value.

shift()

Removes a value from the beginning of a collection, and returns that value.

unshift(...values)

Adds values to the beginning of a collection.

peek()

Returns the value at the beginning of a collection, the value that would be returned by shift().

poke(value)

Replaces the value at the beginning of a collection, the value that would be returned by shift().

peekBack()

Returns the value at the end of a collection, the value that would be returned by pop().

pokeBack(value)

Replaces the value at the end of a collection, the value that would be returned by pop().

has(value)

Whether an equivalent value exists in this collection.

has(value, equals?)

Returns whether an equivalent value exists in this collection.

delete(value)

Deletes the first equivalent value. Returns whether the key was found and successfully deleted.

delete(value, equals?)

Seeks out and deletes an equivalent value. Returns whether the value was found and successfully deleted.

get(key|index, default?)

Gets the value for a key in a map.

set(key, value)

Sets the value for a given key.

addEach(values|map)

Copies values or entries from another collection into this collection, and then returns this.

deleteEach(values|keys, equals?)

Deletes every value or every value for each key. Returns the number of successful deletions.

deleteAll(value, equals?)

Deletes every value equivalent to the given value from the collection.

swap(start, length, values?)

Replaces a length of values from a starting position with the given values.

clear()

Deletes all of the values in the collection.

find(value, equals?, start?)

Finds the first equivalent value.

findValue(value, equals?, start?)

Finds the first equivalent value.

findLast(value, equals?, start?)

Finds the last equivalent value, searching from the right.

findLastValue(value, equals?, start?)

Finds the last equivalent value, searching from the right.

group(callback, thisp?, equals?)

Returns an array of [key, class] entries where every value from the collection is placed into the same equivalence class if they return the same key through the given callback.

any()

Returns whether any value in the collection is truthy.

all()

Returns whether all values in the collection are truthy.

one()

Returns one, arbitrary value from this collection, or undefined if there are none.

only()

Returns the only value in this collection, or undefined if there is more than one value, or if there are no values in the collection.

sorted(compare?)

Returns a sorted array of the values in this collection.

reversed()

Returns a copy of this collection with the values in reverse order.

sum(zero?)

Returns the sum of all values in this collection.

average()

Returns the arithmetic mean of the collection, by computing its sum and the count of values and returning the quotient.

min()

Returns the smallest value in this collection.

max()

Returns the largest value in this collection.

zip(...iterables)

Returns an array of the respective values in this collection and in each collection provided as an argument.

enumerate(start?)

Returns an array of [index, value] entries for each value in this collection, counting all values from the given index.

flatten()

Assuming that this is a collection of collections, returns a new collection that contains all the values of each nested collection in order.

toArray()

Returns an array of each value in this collection.

toObject()

Returns an object with each property name and value corresponding to the entries in this collection.

equals(value, equals?)

Returns whether this collection is equivalent to the given collection.

compare(value, compare?)

Compares two values and returns a number having the same relative value to zero.

clone(depth?, memo?)

Creates a deep replica of this collection.

constructClone(values?)

Creates a shallow clone of this collection.

addRangeChangeListener(listener, token?, beforeChange?)

Adds a listener for when values are added or removed at any position.

removeRangeChangeListener(listener, token?, beforeChange?)

Unregisters a range change listener provided by addRangeChangeListener.

dispatchRangeChange(plus, minus, index, beforeChange?)

Informs range change listeners that values were removed then added at an index.

addBeforeRangeChangeListener(listener, token?)

Adds a listener for before values are added or removed at any position.

removeBeforeRangeChangeListener(listener, token?)

Unregisters a range change listener provided by addBeforeRangeChangeListener or addRangeChangeListener with the beforeChange flag.

dispatchBeforeRangeChange(plus, minus, index)

Informs range change listeners that values will be removed then added at an index.

addMapChangeListener(listener, token?, beforeChange?)

Adds a listener for when the value for a key changes, or when entries are added or removed.

addBeforeMapChangeListener(listener, token?)

Adds a listener for before map entries are created, deleted, or updated.

removeMapChangeListener(listener, token?, beforeChange?)

Unregisters a map change listener provided by addMapChangeListener.

removeBeforeMapChangeListener(listener, token?)

Unregisters a map change listener provided by addBeforeMapChangeListener or addMapChangeListener with the beforeChange flag.

dispatchMapChange(key, value, beforeChange?)

Informs map change listeners that an entry was created, deleted, or updated.

dispatchBeforeMapChange(key, value)

Informs map change listeners that an entry will be created, deleted, or updated.

addOwnPropertyChangeListener(key, listener, beforeChange?)

Adds a listener for an owned property with the given name.

addBeforeOwnPropertyChangeListener(name, listener)

Adds a listener for before a property changes.

removeOwnPropertyChangeListener(name, listener, beforeChange?)

Unregisters a property change listener provided by addOwnPropertyChangeListener.

removeBeforeOwnPropertyChangeListener(key, listener)

Unregisters a property change listener provided by addBeforeOwnPropertyChangeListener or addOwnPropertyChangeListener with the beforeChange flag.

dispatchOwnPropertyChange(key, value, beforeChange?)

Informs property change listeners that the value for a property name has changed.

dispatchBeforeOwnPropertyChange(key, value)

Informs property change listeners that the value for a property name will change.

makePropertyObservable(name)

May perform internal changes necessary to dispatch property changes for a particular name.

makeObservable()

Makes changes observable for this collection.

Usage

require("collections/shim-array");
require("collections/listen/array-changes");
  • Array()
  • Array(length)
  • Array(...values)
  • Array.from(values)
Source code