Class ArrayList
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
ArrayList
(
items
)
- Parameters:
-
items
< Array >
array of items this list will be responsible for
Methods
protected
mixed
_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:
-
i
< Integer >
Index of item to fetch
- Returns:
mixed
- The item appropriate for pass through API methods
static
void
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.
- Parameters:
-
dest
< Object >
Object or prototype to receive the iterator method
-
name
< String | Array >
Name of method of methods to create
ArrayList
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:
-
fn
< Function >
the function to execute
-
context
< mixed >
optional override 'this' in the function
- Returns:
ArrayList
- this instance
Chainable: This method is chainable.
Integer
indexOf
(
needle
)
Finds the first index of the needle in the managed array of items.
- Parameters:
-
needle
< mixed >
The item to search for
- Returns:
Integer
- Array index if found. Otherwise -1
Boolean
isEmpty
(
)
Is this instance managing any items?
- Returns:
Boolean
- true if 1 or more items are being managed
mixed
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:
-
i
< Integer >
index to fetch
- Returns:
mixed
- the item at the requested index
Integer
size
(
)
How many items are in this list?
- Returns:
Integer
- Number of items in the list
Boolean
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:
-
fn
< Function >
the function to execute
-
context
< mixed >
optional override 'this' in the function
- Returns:
Boolean
- True if the function returned true on an item