Package com.helger.commons.collection.impl

Interface ICommonsList<ELEMENTTYPE>

Type Parameters:

ELEMENTTYPE - The data type of the elements in the list.

All Superinterfaces:

Collection<ELEMENTTYPE>, ICloneable<ICommonsList<ELEMENTTYPE>>, ICommonsCollection<ELEMENTTYPE>, ICommonsIterable<ELEMENTTYPE>, IHasSize, Iterable<ELEMENTTYPE>, List<ELEMENTTYPE>

All Known Subinterfaces:

IErrorList

All Known Implementing Classes:

CommonsArrayList, CommonsCopyOnWriteArrayList, CommonsLinkedList, CommonsVector, ErrorList, NonBlockingStack, URLParameterList

public interface ICommonsList<ELEMENTTYPE>
extends List<ELEMENTTYPE>, ICommonsCollection<ELEMENTTYPE>, ICloneable<ICommonsList<ELEMENTTYPE>>

A special List interface with extended functionality based on ICommonsCollection.

Author:

Philip Helger

Method Summary

Modifier and Type	Method	Description
default <T> ICommonsList<T>	createInstance()	Create a new empty list.
default ICommonsList<ELEMENTTYPE>	getAll(Predicate<? super ELEMENTTYPE> aFilter)	Get all elements matching the provided filter.
default <DSTTYPE extends ELEMENTTYPE> ICommonsList<DSTTYPE>	getAllInstanceOf(Class<DSTTYPE> aDstClass)	Get all instances of the provided class that are contained in this list.
default <DSTTYPE> ICommonsList<DSTTYPE>	getAllMapped(Function<? super ELEMENTTYPE,DSTTYPE> aMapper)	Create a new list where all existing elements are mapped with the provided function.
default <DSTTYPE> ICommonsList<DSTTYPE>	getAllMapped(Predicate<? super ELEMENTTYPE> aFilter, Function<? super ELEMENTTYPE,DSTTYPE> aMapper)	Create a new list where all elements matching the filter are mapped with the provided function.
default List<ELEMENTTYPE>	getAsUnmodifiable()
default ELEMENTTYPE	getAtIndex(int nIndex, ELEMENTTYPE aDefault)	Get the element at the specified index or return the provided default value upon invalid index.
default ELEMENTTYPE	getFirst()
default ELEMENTTYPE	getFirst(ELEMENTTYPE aDefault)
default ELEMENTTYPE	getLast()
default ELEMENTTYPE	getLast(ELEMENTTYPE aDefault)
default ICommonsList<ELEMENTTYPE>	getSortedInline(Comparator<? super ELEMENTTYPE> aComparator)	Sort this line without creating a copy.
default ELEMENTTYPE	removeAndReturnElementAtIndex(int nIndex)	Remove the element at the specified index from the passed list.
default EChange	removeAtIndex(int nIndex)	Remove the element at the specified index from the passed list.
default ELEMENTTYPE	removeFirst()	Remove the first element of the list.
default ELEMENTTYPE	removeLast()	Remove the last element of the list.
default ICommonsList<ELEMENTTYPE>	reverse()	Reverse the order of this list.
default ELEMENTTYPE	setFirst(ELEMENTTYPE aNewElement)	Set the first element of this list.
default ELEMENTTYPE	setLast(ELEMENTTYPE aNewElement)	Set the last element of this list.
default ICommonsList<ELEMENTTYPE>	swapItems(int nFirstIndex, int nSecondIndex)	Swap list items.

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface com.helger.commons.lang.ICloneable

getClone

Methods inherited from interface com.helger.commons.collection.impl.ICommonsCollection

addAll, addAll, addAll, addAll, addAll, addAll, addAll, addAll, addAllMapped, addAllMapped, addAllMapped, addAllMapped, addAllMapped, addAllMapped, addIf, addIfNotNull, addObject, getAtIndex, getAtIndex, getAtIndex, getAtIndexMapped, getAtIndexMapped, getAtIndexMapped, getAtIndexMapped, getCopyAsList, getCount, getSorted, iterator2, removeAll, removeObject, set, setAll, setAll, setAllMapped, setAllMapped

Methods inherited from interface com.helger.commons.collection.impl.ICommonsIterable

containsAny, containsNone, containsOnly, findAll, findAllInstanceOf, findAllMapped, findAllMapped, findAllMapped, findFirst, findFirst, findFirstIndex, findFirstMapped, findFirstMapped, findLastIndex, forEachBreakable, forEachByIndex, forEachThrowing, getCount

Methods inherited from interface com.helger.commons.lang.IHasSize

isEmpty, isNotEmpty, size

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.List

add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, size, sort, spliterator, subList, toArray, toArray

Method Detail

createInstance

@Nonnull
@ReturnsMutableCopy
default <T> ICommonsList<T> createInstance()

Create a new empty list. Overwrite this if you don't want to use CommonsArrayList.

Type Parameters:

T - List element type

Returns:

A new empty list. Never null.

getAll

@Nonnull
@ReturnsMutableCopy
default ICommonsList<ELEMENTTYPE> getAll(@Nullable
                                         Predicate<? super ELEMENTTYPE> aFilter)

Get all elements matching the provided filter. If no filter is provided, the return value is same as ICloneable.getClone().

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

A non-null copy of this list containing all matching entries (or all entries if no filter is provided).

See Also:

ICommonsIterable.findAll(Predicate, java.util.function.Consumer)

getAllMapped

@Nonnull
@ReturnsMutableCopy
default <DSTTYPE> ICommonsList<DSTTYPE> getAllMapped(@Nonnull
                                                     Function<? super ELEMENTTYPE,DSTTYPE> aMapper)

Create a new list where all existing elements are mapped with the provided function.

Type Parameters:

DSTTYPE - The destination type to be mapped to

Parameters:

aMapper - The mapping function to be executed. May not be null.

Returns:

A new non-null list with all mapped elements.

See Also:

getAllMapped(Predicate, Function), ICommonsIterable.findAllMapped(Function, java.util.function.Consumer)

getAllMapped

@Nonnull
@ReturnsMutableCopy
default <DSTTYPE> ICommonsList<DSTTYPE> getAllMapped(@Nullable
                                                     Predicate<? super ELEMENTTYPE> aFilter,
                                                     @Nonnull
                                                     Function<? super ELEMENTTYPE,DSTTYPE> aMapper)

Create a new list where all elements matching the filter are mapped with the provided function.

Type Parameters:

DSTTYPE - The destination type to be mapped to

Parameters:

aFilter - The filter to be applied. Maybe null.

aMapper - The mapping function to be executed. May not be null.

Returns:

A new non-null list with all mapped elements. If no filter is provided the result is the same as of getAllMapped(Function).

See Also:

getAllMapped(Function), ICommonsIterable.findAllMapped(Predicate, Function, java.util.function.Consumer)

getAllInstanceOf

@Nonnull
@ReturnsMutableCopy
default <DSTTYPE extends ELEMENTTYPE> ICommonsList<DSTTYPE> getAllInstanceOf(@Nonnull
                                                                             Class<DSTTYPE> aDstClass)

Get all instances of the provided class that are contained in this list.

Type Parameters:

DSTTYPE - The destination type to be casted to

Parameters:

aDstClass - The class to search all instances of. May not be null.

Returns:

A list with all instances of the provided class, already casted. Never null.

See Also:

ICommonsIterable.findAllInstanceOf(Class, java.util.function.Consumer)

getFirst

@Nullable
default ELEMENTTYPE getFirst()

Returns:

The first element of the list or null if the list is empty.

See Also:

getFirst(Object), ICommonsIterable.findFirst(Predicate)

getFirst

@Nullable
default ELEMENTTYPE getFirst(@Nullable
                             ELEMENTTYPE aDefault)

Parameters:

aDefault - The default value to be returned if this list is empty. May be null.

Returns:

The first element of the list or the provided default value if the list is empty.

See Also:

getFirst(), ICommonsIterable.findFirst(Predicate)

getLast

@Nullable
default ELEMENTTYPE getLast()

Returns:

The last element of the list or null if the list is empty.

See Also:

getLast(Object)

getLast

@Nullable
default ELEMENTTYPE getLast(@Nullable
                            ELEMENTTYPE aDefault)

Parameters:

aDefault - The default value to be returned if this list is empty. May be null.

Returns:

The last element of the list or null if the list is empty.

See Also:

getLast()

getAtIndex

@Nullable
default ELEMENTTYPE getAtIndex(@Nonnegative
                               int nIndex,
                               @Nullable
                               ELEMENTTYPE aDefault)

Description copied from interface: ICommonsCollection

Get the element at the specified index or return the provided default value upon invalid index.

Specified by:

getAtIndex in interface ICommonsCollection<ELEMENTTYPE>

Parameters:

nIndex - The index to access. Should be ≥ 0.

aDefault - The value to be returned, if the index is out of bounds. May be null.

Returns:

The default parameter if the element cannot be accessed

See Also:

ICommonsCollection.getAtIndex(int)

setFirst

@Nullable
default ELEMENTTYPE setFirst(@Nullable
                             ELEMENTTYPE aNewElement)

Set the first element of this list.

Parameters:

aNewElement - The new element at index 0.

Returns:

The previous element. May be null.

See Also:

List.set(int, Object)

setLast

@Nullable
default ELEMENTTYPE setLast(@Nullable
                            ELEMENTTYPE aNewElement)

Set the last element of this list.

Parameters:

aNewElement - The new element at index size()-1.

Returns:

The previous element. May be null.

See Also:

List.set(int, Object)

removeAtIndex

@Nonnull
default EChange removeAtIndex(int nIndex)

Remove the element at the specified index from the passed list. This works if the list is not null and the index is ≥ 0 and < list.size()

Parameters:

nIndex - The index to be removed. May be arbitrary.

Returns:

EChange.CHANGED if removal was successful

See Also:

removeAndReturnElementAtIndex(int)

removeAndReturnElementAtIndex

@Nullable
default ELEMENTTYPE removeAndReturnElementAtIndex(int nIndex)

Remove the element at the specified index from the passed list. This works if the list is not null and the index is ≥ 0 and < list.size()

Parameters:

nIndex - The index to be removed. May be arbitrary.

Returns:

null if removal failed or the removed element. Note: the removed element may also be null so it may be tricky to determine if removal succeeded or not!

See Also:

removeAtIndex(int)

removeFirst

@Nullable
default ELEMENTTYPE removeFirst()

Remove the first element of the list.

Returns:

null if the list is empty or the previously contained element at index 0.

removeLast

@Nullable
default ELEMENTTYPE removeLast()

Remove the last element of the list.

Returns:

null if the list is empty or the previously contained element at index size()-1.

getAsUnmodifiable

@Nonnull
@CodingStyleguideUnaware
default List<ELEMENTTYPE> getAsUnmodifiable()

Specified by:

getAsUnmodifiable in interface ICommonsCollection<ELEMENTTYPE>

Returns:

An unmodifiable version of this collection. Never null .

See Also:

Collections

getSortedInline

@Nonnull
default ICommonsList<ELEMENTTYPE> getSortedInline(@Nonnull
                                                  Comparator<? super ELEMENTTYPE> aComparator)

Sort this line without creating a copy.

Parameters:

aComparator - The comparator used for sorting. May not be null.

Returns:

this for chaining

reverse

@Nonnull
default ICommonsList<ELEMENTTYPE> reverse()

Reverse the order of this list.

Returns:

this for chaining

swapItems

@Nonnull
default ICommonsList<ELEMENTTYPE> swapItems(int nFirstIndex,
                                            int nSecondIndex)

Swap list items.

Parameters:

nFirstIndex - The first index to swap.

nSecondIndex - The second index to swap.

Returns:

this for chaining

Since:

8.6.0