org.apache.commons.collections4.list

Class GrowthList<E>

java.lang.Object

org.apache.commons.collections4.collection.AbstractCollectionDecorator<E>

org.apache.commons.collections4.list.AbstractListDecorator<E>

org.apache.commons.collections4.list.AbstractSerializableListDecorator<E>

org.apache.commons.collections4.list.GrowthList<E>

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.List<E>

public class GrowthList<E>
extends AbstractSerializableListDecorator<E>

Decorates another List to make it seamlessly grow when indices larger than the list size are used on add and set, avoiding most IndexOutOfBoundsExceptions.

This class avoids errors by growing when a set or add method would normally throw an IndexOutOfBoundsException. Note that IndexOutOfBoundsException IS returned for invalid negative indices.

Trying to set or add to an index larger than the size will cause the list to grow (using null elements). Clearly, care must be taken not to use excessively large indices, as the internal list will grow to match.

Trying to use any method other than add or set with an invalid index will call the underlying list and probably result in an IndexOutOfBoundsException.

Take care when using this list with null values, as null is the value added when growing the list.

All sub-lists will access the underlying list directly, and will throw IndexOutOfBoundsExceptions.

This class differs from LazyList because here growth occurs on set and add, where LazyList grows on get. However, they can be used together by decorating twice.

Since:

3.2

See Also:

LazyList, Serialized Form

Constructor Summary

Constructors

Constructor and Description
GrowthList() Constructor that uses an ArrayList internally.
GrowthList(int initialSize) Constructor that uses an ArrayList internally.

Method Summary

Modifier and Type	Method and Description
void	add(int index, E element) Decorate the add method to perform the growth behaviour.
boolean	addAll(int index, java.util.Collection<? extends E> coll) Decorate the addAll method to perform the growth behaviour.
static <E> GrowthList<E>	growthList(java.util.List<E> list) Factory method to create a growth list.
E	set(int index, E element) Decorate the set method to perform the growth behaviour.

Methods inherited from class org.apache.commons.collections4.list.AbstractListDecorator

equals, get, hashCode, indexOf, lastIndexOf, listIterator, listIterator, remove, subList

Methods inherited from class org.apache.commons.collections4.collection.AbstractCollectionDecorator

add, addAll, clear, contains, containsAll, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

add, addAll, clear, contains, containsAll, isEmpty, iterator, remove, removeAll, replaceAll, retainAll, size, sort, spliterator, toArray, toArray

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Constructor Detail

GrowthList

public GrowthList()

Constructor that uses an ArrayList internally.

GrowthList

public GrowthList(int initialSize)

Constructor that uses an ArrayList internally.

Parameters:

initialSize - the initial size of the ArrayList

Throws:

java.lang.IllegalArgumentException - if initial size is invalid

Method Detail

growthList

public static <E> GrowthList<E> growthList(java.util.List<E> list)

Factory method to create a growth list.

Type Parameters:

E - the type of the elements in the list

Parameters:

list - the list to decorate, must not be null

Returns:

a new growth list

Throws:

java.lang.NullPointerException - if list is null

Since:

4.0

add

public void add(int index,
                E element)

Decorate the add method to perform the growth behaviour.

If the requested index is greater than the current size, the list will grow to the new size. Indices between the old size and the requested size will be filled with null.

If the index is less than the current size, the value will be added to the underlying list directly. If the index is less than zero, the underlying list is called, which will probably throw an IndexOutOfBoundsException.

Specified by:

add in interface java.util.List<E>

Overrides:

add in class AbstractListDecorator<E>

Parameters:

index - the index to add at

element - the object to add at the specified index

Throws:

java.lang.UnsupportedOperationException - if the underlying list doesn't implement set

java.lang.ClassCastException - if the underlying list rejects the element

java.lang.IllegalArgumentException - if the underlying list rejects the element

addAll

public boolean addAll(int index,
                      java.util.Collection<? extends E> coll)

Decorate the addAll method to perform the growth behaviour.

If the requested index is greater than the current size, the list will grow to the new size. Indices between the old size and the requested size will be filled with null.

If the index is less than the current size, the values will be added to the underlying list directly. If the index is less than zero, the underlying list is called, which will probably throw an IndexOutOfBoundsException.

Specified by:

addAll in interface java.util.List<E>

Overrides:

addAll in class AbstractListDecorator<E>

Parameters:

index - the index to add at

coll - the collection to add at the specified index

Returns:

true if the list changed

Throws:

java.lang.UnsupportedOperationException - if the underlying list doesn't implement set

java.lang.ClassCastException - if the underlying list rejects the element

java.lang.IllegalArgumentException - if the underlying list rejects the element

set

public E set(int index,
             E element)

Decorate the set method to perform the growth behaviour.

If the requested index is greater than the current size, the list will grow to the new size. Indices between the old size and the requested size will be filled with null.

If the index is less than the current size, the value will be set onto the underlying list directly. If the index is less than zero, the underlying list is called, which will probably throw an IndexOutOfBoundsException.

Specified by:

set in interface java.util.List<E>

Overrides:

set in class AbstractListDecorator<E>

Parameters:

index - the index to set

element - the object to set at the specified index

Returns:

the object previously at that index

Throws:

java.lang.UnsupportedOperationException - if the underlying list doesn't implement set

java.lang.ClassCastException - if the underlying list rejects the element

java.lang.IllegalArgumentException - if the underlying list rejects the element