Package org.nasengolem.util.datastructures

Class CappedList<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<E>

org.nasengolem.util.datastructures.AbstractShrinkableList<E>

org.nasengolem.util.datastructures.CappedList<E>

Type Parameters:

E - the type of the elements in this list

All Implemented Interfaces:

Iterable<E>, Collection<E>, List<E>, RandomAccess, SequencedCollection<E>, Shrinkable

public class CappedList<E>
extends AbstractShrinkableList<E>
implements List<E>, RandomAccess, Shrinkable

Random-Access List implementation with a fixed capacity. This list can be used whenever the maximum size of a list is known in advance, making dynamic growth unnecessary.

Although the capacity is fixed, the list behaves as if it was dynamic. This means that methods like add are available, but will throw an IllegalStateException if the list is full. Adding elements to a full CappedList should therefore usually be avoided.

Some use cases for this list are datastructures that are limited due to real-world constraints or datastructures that get (partially) cleared on a regular basis.

Author:

Paul Steinbach

See Also:

• Collection
• AbstractShrinkableList
• ArrayList

Field Summary

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

Constructors

Constructor	Description
CappedList(int capacity)	Constructs a new CappedResizableList with the specified capacity.
CappedList(Collection<? extends E> collection, int capacity)	Constructs a CappedResizableList with the specified capacity.
CappedList(CappedList<? extends E> cappedList)	Copy constructor.

Method Summary

Modifier and Type	Method	Description
void	add(int index, E element)	Inserts the specified element at the specified position in this list, if the list is not full already.
boolean	addAll(int index, Collection<? extends E> c)	Inserts all elements of the specified collection into this list, starting at the specified position.
boolean	addAll(Collection<? extends E> c)	Appends all elements of the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator.
int	capacity()	Gets the capacity of this list.
E	get(int index)
boolean	isFull()	Returns true if this list is full.
E	remove(int index)	Removes the element at the specified position in this list.
E	set(int index, E element)
int	shrink(int newSize)	Shrinks the list to a new smaller size.
int	size()

Methods inherited from class org.nasengolem.util.datastructures.AbstractShrinkableList

removeLast, removeLast, removeRange

Methods inherited from class java.util.AbstractList

add, clear, equals, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, subList

Methods inherited from class java.util.AbstractCollection

contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.List

add, addFirst, addLast, clear, contains, containsAll, equals, getFirst, getLast, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, removeAll, removeFirst, removeLast, replaceAll, retainAll, reversed, sort, spliterator, subList, toArray, toArray

Constructor Details

CappedList

public CappedList(int capacity)

Constructs a new CappedResizableList with the specified capacity.

Parameters:

capacity - the capacity defining the maximum number of elements the list can store

Throws:

IllegalArgumentException - if the capacity is negative

CappedList

public CappedList(CappedList<? extends E> cappedList)

Copy constructor. Constructs a CappedResizableList with the same capacity and elements as the given CappedResizableList.

Parameters:

cappedList - the CappedResizableList to copy

Throws:

NullPointerException - if the cappedList is null

CappedList

public CappedList(Collection<? extends E> collection,
 int capacity)

Constructs a CappedResizableList with the specified capacity. The list contains the elements of the specified collection, in the order they are returned by the collection's iterator.

Parameters:

collection - the collection whose elements are to be placed into this list

capacity - the capacity defining the maximum number of elements the list can store

Throws:

IllegalArgumentException - if the capacity is smaller than the collections size

NullPointerException - if the collection is null

Method Details

shrink

public int shrink(int newSize)

Shrinks the list to a new smaller size. All elements at indices beyond the new size won't be visible anymore.

Specified by:

shrink in interface Shrinkable

Specified by:

shrink in class AbstractShrinkableList<E>

Parameters:

newSize - the new size of the list

Returns:

the old size of the list

Throws:

IllegalArgumentException - if the new size is negative or greater than the current size

get

public E get(int index)

Specified by:

get in interface List<E>

Specified by:

get in class AbstractList<E>

size

public int size()

Specified by:

size in interface Collection<E>

Specified by:

size in interface List<E>

Specified by:

size in class AbstractCollection<E>

Returns:

the number of elements in this list

set

public E set(int index,
 E element)

Specified by:

set in interface List<E>

Overrides:

set in class AbstractList<E>

isFull

public boolean isFull()

Returns true if this list is full. This means that no further elements can be added.

Returns:

true if this collection if full. This implementation returns size() == capacity().

add

public void add(int index,
 E element)

Inserts the specified element at the specified position in this list, if the list is not full already. The element currently at that position (if any) and any subsequent elements will then be shifted to the right (adds one to their indices).

Specified by:

add in interface List<E>

Overrides:

add in class AbstractList<E>

Parameters:

index - index at which the specified element is to be inserted

element - element to be inserted

addAll

public boolean addAll(int index,
 Collection<? extends E> c)

Inserts all elements of the specified collection into this list, starting at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in the list in the order that they are returned by the specified collection's iterator.

Specified by:

addAll in interface List<E>

Overrides:

addAll in class AbstractList<E>

Parameters:

index - index at which to insert the first element from the specified collection

c - collection containing elements to be added to this list

Returns:

true if this list changed as a result of the call

addAll

public boolean addAll(Collection<? extends E> c)

Appends all elements of the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator.

Specified by:

addAll in interface Collection<E>

Specified by:

addAll in interface List<E>

Overrides:

addAll in class AbstractCollection<E>

Parameters:

c - collection containing elements to be added to this list

Returns:

true if this list changed as a result of the call

Throws:

NullPointerException - if the specified collection is null

IllegalStateException - if the list reached its capacity

remove

public E remove(int index)

Removes the element at the specified position in this list. Shifts any subsequent elements to the left (subtracts one from their indices).

Specified by:

remove in interface List<E>

Overrides:

remove in class AbstractList<E>

Parameters:

index - the index of the element to be removed

Returns:

the element that was removed from the list

capacity

public int capacity()

Gets the capacity of this list. The capacity is the maximum number of elements this list can store.

Returns:

the capacity of this list