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>, SequencedCollection<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()	Deprecated, for removal: This API element is subject to removal in a future version. Use getFirstOrNull() instead
default ELEMENTTYPE	getFirst(ELEMENTTYPE aDefault)
default ELEMENTTYPE	getFirstOrNull()
default ELEMENTTYPE	getLast()	Deprecated, for removal: This API element is subject to removal in a future version. Use getLastOrNull() instead
default ELEMENTTYPE	getLast(ELEMENTTYPE aDefault)
default ELEMENTTYPE	getLastOrNull()
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()	Deprecated, for removal: This API element is subject to removal in a future version. Use removeFirstOrNull() instead
default ELEMENTTYPE	removeFirstOrNull()	Remove the first element of the list.
default ELEMENTTYPE	removeLast()	Deprecated, for removal: This API element is subject to removal in a future version.
default ELEMENTTYPE	removeLastOrNull()	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, addFirst, addLast, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, reversed, set, size, sort, spliterator, subList, toArray, toArray

Method Details

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
@Deprecated(forRemoval=true,
            since="11.1.5")
default ELEMENTTYPE getFirst()

Deprecated, for removal: This API element is subject to removal in a future version.

Use getFirstOrNull() instead

Note: this methods conflicts with a method added in Java SE 21 in class ArrayList. Therefore getFirstOrNull() should be used instead.

Specified by:

getFirst in interface List<ELEMENTTYPE>

Specified by:

getFirst in interface SequencedCollection<ELEMENTTYPE>

Returns:

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

See Also:

• getFirst(Object)
• ICommonsIterable.findFirst(Predicate)

getFirstOrNull

@Nullable
default ELEMENTTYPE getFirstOrNull()

Returns:

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

Since:

11.1.5

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:

• getFirstOrNull()
• ICommonsIterable.findFirst(Predicate)

getLast

@Nullable
@Deprecated(forRemoval=true,
            since="11.1.5")
default ELEMENTTYPE getLast()

Deprecated, for removal: This API element is subject to removal in a future version.

Use getLastOrNull() instead

Note: this methods conflicts with a method added in Java SE 21 in class ArrayList. Therefore getLastOrNull() should be used instead.

Specified by:

getLast in interface List<ELEMENTTYPE>

Specified by:

getLast in interface SequencedCollection<ELEMENTTYPE>

Returns:

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

See Also:

• getLast(Object)

getLastOrNull

@Nullable
default ELEMENTTYPE getLastOrNull()

Returns:

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

Since:

11.1.5

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:

• getLastOrNull()

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
@Deprecated(forRemoval=true,
            since="11.1.5")
default ELEMENTTYPE removeFirst()

Deprecated, for removal: This API element is subject to removal in a future version.

Use removeFirstOrNull() instead

Remove the first element of the list.
Note: this methods conflicts with a method added in Java SE 21 in class ArrayList. Therefore removeFirstOrNull() should be used instead.

Specified by:

removeFirst in interface List<ELEMENTTYPE>

Specified by:

removeFirst in interface SequencedCollection<ELEMENTTYPE>

Returns:

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

removeFirstOrNull

@Nullable
default ELEMENTTYPE removeFirstOrNull()

Remove the first element of the list.

Returns:

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

Since:

11.1.5

removeLast

@Nullable
@Deprecated(forRemoval=true,
            since="11.1.5")
default ELEMENTTYPE removeLast()

Deprecated, for removal: This API element is subject to removal in a future version.

Remove the last element of the list.
Note: this methods conflicts with a method added in Java SE 21 in class ArrayList. Therefore removeLastOrNull() should be used instead.

Specified by:

removeLast in interface List<ELEMENTTYPE>

Specified by:

removeLast in interface SequencedCollection<ELEMENTTYPE>

Returns:

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

removeLastOrNull

@Nullable
default ELEMENTTYPE removeLastOrNull()

Remove the last element of the list.

Returns:

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

Since:

11.1.5

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