Package: groovy.lang

## [Java] Class ListWithDefault<T>

- groovy.lang.ListWithDefault

- All Implemented Interfaces and Traits:
    List

      public final class ListWithDefault<T>
      extends Object
      implements List

  A wrapper for List which automatically grows the list when either get(int) or getAt(int) is called with an index greater than or equal to `size()`.

  Since:
    1.8.7

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public boolean` | `add(T t)` {@inheritDoc}
    `` | `public void` | `add(int i, T t)` {@inheritDoc}
    `` | `public boolean` | `addAll(Collection<? extends T> ts)` {@inheritDoc}
    `` | `public boolean` | `addAll(int i, Collection<? extends T> ts)` {@inheritDoc}
    `` | `public void` | `clear()` {@inheritDoc}
    `` | `public boolean` | `contains(Object o)` {@inheritDoc}
    `` | `public boolean` | `containsAll(Collection<?> objects)` {@inheritDoc}
    `` | `public boolean` | `equals(Object obj)` {@inheritDoc}
    `` | `public T` | `get(int index)` Returns the element at the given index but grows the list if needed.
    `` | `public T` | `getAt(int index)` Overwrites subscript operator handling by redirecting to get(int).
    `` | `public List<T>` | `getDelegate()` Returns a copy of the wrapped list.
    `` | `public Closure` | `getInitClosure()` Returns a clone of the initialization closure.
    `` | `public int` | `hashCode()` {@inheritDoc}
    `` | `public int` | `indexOf(Object o)` {@inheritDoc}
    `` | `public boolean` | `isEmpty()` {@inheritDoc}
    `` | `public boolean` | `isLazyDefaultValues()` Indicates whether missing values are initialized lazily.
    `` | `public Iterator<T>` | `iterator()` {@inheritDoc}
    `` | `public int` | `lastIndexOf(Object o)` {@inheritDoc}
    `` | `public ListIterator<T>` | `listIterator()` {@inheritDoc}
    `` | `public ListIterator<T>` | `listIterator(int i)` {@inheritDoc}
    `<T>` | `public static ListWithDefault<T>` | `newInstance(List<T> items, boolean lazyDefaultValues, Closure initClosure)` Creates a new list wrapper with the supplied defaulting behavior.
    `` | `public boolean` | `remove(Object o)` {@inheritDoc}
    `` | `public T` | `remove(int i)` {@inheritDoc}
    `` | `public boolean` | `removeAll(Collection<?> objects)` {@inheritDoc}
    `` | `public boolean` | `retainAll(Collection<?> objects)` {@inheritDoc}
    `` | `public T` | `set(int i, T t)` {@inheritDoc}
    `` | `public int` | `size()` {@inheritDoc}
    `` | `public ListWithDefault<T>` | `subList(int fromIndex, int toIndex)` Returns a view of a portion of this list.
    `` | `public Object[]` | `toArray()` {@inheritDoc}
    `<U>` | `public U[]` | `toArray(U[] ts)` {@inheritDoc}

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### public boolean add(T t)

      {@inheritDoc}

    - #### public void add(int i, T t)

      {@inheritDoc}

    - #### public boolean addAll(Collection<? extends T> ts)

      {@inheritDoc}

    - #### public boolean addAll(int i, Collection<? extends T> ts)

      {@inheritDoc}

    - #### public void clear()

      {@inheritDoc}

    - #### public boolean contains(Object o)

      {@inheritDoc}

    - #### public boolean containsAll(Collection<?> objects)

      {@inheritDoc}

    - #### public boolean equals(Object obj)

      {@inheritDoc}

    - #### public T get(int index)

      Returns the element at the given index but grows the list if needed. If the requested `index` is greater than or equal to `size()`, the list will grow to the new size and a default value calculated using the `initClosure` will be used to populate the missing value and returned.

      If `lazyDefaultValues` is `true` any gaps when growing the list are filled with nulls. Subsequent attempts to retrieve items from the list from those gap index values will, upon finding null, call the `initClosure` to populate the list for the given list value. Hence, when in this mode, nulls cannot be stored in this list. If `lazyDefaultValues` is `false` any gaps when growing the list are filled eagerly by calling the `initClosure` for all gap indexes during list growth. No calls to `initClosure` are made except during list growth and it is ok to store null values in the list when in this mode.

      This implementation breaks the contract of List.get as it a) possibly modifies the underlying list and b) does NOT throw an IndexOutOfBoundsException when `index < 0 || index >= size()`.

      Parameters:
        `index` - an index (might be greater or equal to `size()`, or smaller than 0)
      Returns:
        the value at the given `index` or the default value

    - #### public T getAt(int index)

      Overwrites subscript operator handling by redirecting to get(int).

      Parameters:
        `index` - an index (might be greater or equal to `size()`, or smaller than 0)
      Returns:
        the value at the given `index` or the default value

    - #### public List<T> getDelegate()

      Returns a copy of the wrapped list.

      Returns:
        a copy of the delegate list

    - #### public Closure getInitClosure()

      Returns a clone of the initialization closure.

      Returns:
        the initialization closure

    - #### public int hashCode()

      {@inheritDoc}

    - #### public int indexOf(Object o)

      {@inheritDoc}

    - #### public boolean isEmpty()

      {@inheritDoc}

    - #### public boolean isLazyDefaultValues()

      Indicates whether missing values are initialized lazily.

      Returns:
        `true` if defaults are created lazily

    - #### public Iterator<T> iterator()

      {@inheritDoc}

    - #### public int lastIndexOf(Object o)

      {@inheritDoc}

    - #### public ListIterator<T> listIterator()

      {@inheritDoc}

    - #### public ListIterator<T> listIterator(int i)

      {@inheritDoc}

    - #### <T> public static ListWithDefault<T> newInstance(List<T> items, boolean lazyDefaultValues, Closure initClosure)

      Creates a new list wrapper with the supplied defaulting behavior.

      Parameters:
        `items` - the source items
        `lazyDefaultValues` - whether default values are created lazily
        `initClosure` - the closure used to create default values
      Type Parameters:
        `T` - the element type
      Returns:
        the new wrapper

    - #### public boolean remove(Object o)

      {@inheritDoc}

    - #### public T remove(int i)

      {@inheritDoc}

    - #### public boolean removeAll(Collection<?> objects)

      {@inheritDoc}

    - #### public boolean retainAll(Collection<?> objects)

      {@inheritDoc}

    - #### public T set(int i, T t)

      {@inheritDoc}

    - #### public int size()

      {@inheritDoc}

    - #### public ListWithDefault<T> subList(int fromIndex, int toIndex)

      Returns a view of a portion of this list. This method returns a list with the same lazy list settings as the original list.

      Parameters:
        `fromIndex` - low endpoint of the subList (inclusive)
        `toIndex` - upper endpoint of the subList (exclusive)
      Returns:
        a view of a specified range within this list, keeping all lazy list settings

    - #### public Object[] toArray()

      {@inheritDoc}

    - #### <U> public U[] toArray(U[] ts)

      {@inheritDoc}