#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# ArrayList Class

Defined in: `collection/js/arraylist.js:11`
Module: arraylist
Parent Module: collection

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`

)

Defined in `collection/js/arraylist.js:11`

#### Parameters:

- `items` Array

  array of items this list will be responsible for

- Index
- Methods

## Item Index

### Methods

- _item
- add deprecated
- addMethod static
- each
- filter deprecated
- indexOf
- isEmpty
- item
- itemsAreEqual deprecated
- remove deprecated
- size
- some
- toJSON

## Methods

### `_item`

(

- `i`

)
Mixed protected

Defined in `collection/js/arraylist.js:138`

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

### `add`

(

- `item`
- `index`

)
ArrayList deprecated chainable

Provided by the arraylist-add module.

Defined in `collection/js/arraylist-add.js:13`

Deprecated: Use ModelList or a custom ArrayList subclass

Add a single item to the ArrayList. Does not prevent duplicates.

#### Parameters:

- `item` Mixed

  Item presumably of the same type as others in the ArrayList.

- `index` Number

  (Optional.) Number representing the position at which the item should be inserted.

#### Returns:

ArrayList: the instance.

### `addMethod`

(

- `dest`
- `name`

)
static

Defined in `collection/js/arraylist.js:156`

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.

#### Parameters:

- `dest` Object

  Object or prototype to receive the iterator method

- `name` String | String[]

  Name of method of methods to create

### `each`

(

- `fn`
- `context`

)
ArrayList chainable

Defined in `collection/js/arraylist.js:51`

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

### `filter`

(

- `validator`

)
ArrayList deprecated

Provided by the arraylist-filter module.

Defined in `collection/js/arraylist-filter.js:13`

Deprecated: Use ModelList or a custom subclass implementation

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:

- `validator` Function

  Boolean function to determine in or out.

#### Returns:

ArrayList: New instance based on who passed the validator.

### `indexOf`

(

- `needle`

)
Integer

Defined in `collection/js/arraylist.js:95`

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

### `isEmpty`

() Boolean

Defined in `collection/js/arraylist.js:116`

Is this instance managing any items?

#### Returns:

Boolean: true if 1 or more items are being managed

### `item`

(

- `i`

)
Mixed

Defined in `collection/js/arraylist.js:37`

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

### `itemsAreEqual`

(

- `a`
- `b`

)
Boolean deprecated

Provided by the arraylist-add module.

Defined in `collection/js/arraylist-add.js:68`

Deprecated: Use ModelList or a custom ArrayList subclass

Default comparator for items stored in this list. Used by remove().

#### Parameters:

- `a` Mixed

  item to test equivalence with.

- `b` Mixed

  other item to test equivalance.

#### Returns:

Boolean: true if items are deemed equivalent.

### `remove`

(

- `needle`
- `all`
- `comparator`

)
ArrayList deprecated chainable

Provided by the arraylist-add module.

Defined in `collection/js/arraylist-add.js:39`

Deprecated: Use ModelList or a custom ArrayList subclass

Removes first or all occurrences of an item to the ArrayList. If a comparator is not provided, uses itemsAreEqual method to determine matches.

#### Parameters:

- `needle` Mixed

  Item to find and remove from the list.

- `all` Boolean

  If true, remove all occurrences.

- `comparator` Function

  optional a/b function to test equivalence.

#### Returns:

ArrayList: the instance.

### `size`

() Integer

Defined in `collection/js/arraylist.js:106`

How many items are in this list?

#### Returns:

Integer: Number of items in the list

### `some`

(

- `fn`
- `context`

)
Boolean

Defined in `collection/js/arraylist.js:73`

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

### `toJSON`

() Array

Defined in `collection/js/arraylist.js:126`

Provides an array-like representation for JSON.stringify.

#### Returns:

Array: an array representation of the ArrayList