ArrayList Class
Generic ArrayList class for managing lists of items and iterating operations over them. The targeted use for this class is for augmentation onto a class that is responsible for managing multiple instances of another class (e.g. NodeList for Nodes). The recommended use is to augment your class with ArrayList, then use ArrayList.addMethod to mirror the API of the constituent items on the list's API.
The default implementation creates immutable lists, but mutability can be provided via the arraylist-add submodule or by implementing mutation methods directly on the augmented class's prototype.
Constructor
Item Index
Methods
_item
-
i
Protected method for optimizations that may be appropriate for API
mirroring. Similar in functionality to item, but is used by
methods added with ArrayList.addMethod().
Parameters:
-
iIntegerIndex of item to fetch
Returns:
add
-
item -
index
Add a single item to the ArrayList. Does not prevent duplicates.
Parameters:
-
itemMixedItem presumably of the same type as others in the ArrayList.
-
indexNumber(Optional.) Number representing the position at which the item should be inserted.
Returns:
addMethod
-
dest -
name
Adds a pass through method to dest (typically the prototype of a list class) that calls the named method on each item in the list with whatever parameters are passed in. Allows for API indirection via list instances.
Accepts a single string name or an array of string names.
list.each( function ( item ) {
item.methodName( 1, 2, 3 );
} );
// becomes
list.methodName( 1, 2, 3 );Additionally, the pass through methods use the item retrieved by the
_item method in case there is any special behavior that is
appropriate for API mirroring.
If the iterated method returns a value, the return value from the added method will be an array of values with each value being at the corresponding index for that item. If the iterated method does not return a value, the added method will be chainable.
each
-
fn -
context
Execute a function on each item of the list, optionally providing a custom execution context. Default context is the item.
The callback signature is callback( item, index ).
Parameters:
-
fnFunctionthe function to execute
-
contextMixedoptional override 'this' in the function
Returns:
filter
-
validator
Create a new ArrayList (or augmenting class instance) from a subset of items as determined by the boolean function passed as the argument. The original ArrayList is unchanged.
The validator signature is validator( item ).
Parameters:
-
validatorFunctionBoolean function to determine in or out.
Returns:
indexOf
-
needle
Finds the first index of the needle in the managed array of items.
Parameters:
-
needleMixedThe item to search for
Returns:
isEmpty
()
Boolean
Is this instance managing any items?
Returns:
item
-
i
Get an item by index from the list. Override this method if managing a list of objects that have a different public representation (e.g. Node instances vs DOM nodes). The iteration methods that accept a user function will use this method for access list items for operation.
Parameters:
-
iIntegerindex to fetch
Returns:
itemsAreEqual
-
a -
b
Default comparator for items stored in this list. Used by remove().
Parameters:
-
aMixeditem to test equivalence with.
-
bMixedother item to test equivalance.
Returns:
remove
-
needle -
all -
comparator
Removes first or all occurrences of an item to the ArrayList. If a comparator is not provided, uses itemsAreEqual method to determine matches.
Parameters:
Returns:
size
()
Integer
How many items are in this list?
Returns:
some
-
fn -
context
Execute a function on each item of the list, optionally providing a custom execution context. Default context is the item.
The callback signature is callback( item, index ).
Unlike each, if the callback returns true, the
iteratation will stop.
Parameters:
-
fnFunctionthe function to execute
-
contextMixedoptional override 'this' in the function