Package no.digipost.collection

Interface NonEmptyList<E>

Type Parameters:

E - the type of elements in this list

All Superinterfaces:

Collection<E>, Iterable<E>, List<E>

public interface NonEmptyList<E>
extends List<E>

A non-empty list. Implementations of this interface must take care to ensure that instances will never in any circumstance be allowed to be empty.

Method Summary

Modifier and Type	Method	Description
static <E> Optional<NonEmptyList<E>>	copyOf(List<E> list)	Try to construct a non-empty list from copying the elements of a given list, which may be empty.
static <E> NonEmptyList<E>	copyOfUnsafe(List<E> nonEmptyList)	Unsafe construction of non-empty list from copying the elements of a possibly empty list.
default E	first()	Get the first element of this non-empty list.
static <E> Optional<E>	firstOf(List<E> list)	Utility for safe retrieval of the first element from an arbitrary list.
default boolean	hasMultipleElements()	Checks if this non-empty list has multiple elements, i.e.
default boolean	isEmpty()	A non-empty list is never empty, so this always returns true.
default boolean	isSingular()	Checks if the non-empty list contains only the required singular element, i.e.
static <E> NonEmptyList<E>	of(E singleElement)	Construct a non-empty list with one single element.
static <E> NonEmptyList<E>	of(E firstElement, E... remainingElements)	Construct a non-empty list containing a specific object as its first element, and any provided remaining elements.
static <E> NonEmptyList<E>	of(E firstElement, List<E> remainingElements)	Construct a non-empty list containing a specific object as its first element, and any elements contained in another list as its remaining elements.
static <E> Optional<NonEmptyList<E>>	of(List<E> list)	Try to construct a non-empty list from a given list, which may be empty.
static <E> NonEmptyList<E>	ofUnsafe(List<E> list)	Unsafe construction of non-empty list from a possibly empty list.
default NonEmptyStream<E>	stream()

Methods inherited from interface java.util.Collection

parallelStream, removeIf, toArray

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, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, size, sort, spliterator, subList, toArray, toArray

Method Detail

firstOf

static <E> Optional<E> firstOf(List<E> list)

Utility for safe retrieval of the first element from an arbitrary list.

Type Parameters:

E - the type of the elements in the list

Parameters:

list - the list to get the first element from

Returns:

an Optional with the first element of the list, or empty if the list was empty.

of

static <E> NonEmptyList<E> of(E singleElement)

Construct a non-empty list with one single element.

Type Parameters:

E - the type of the element

Parameters:

singleElement - the element to include in the list

Returns:

the non-empty list

of

@SafeVarargs
static <E> NonEmptyList<E> of(E firstElement,
                              E... remainingElements)

Construct a non-empty list containing a specific object as its first element, and any provided remaining elements.

Type Parameters:

E - the type of the elements

Parameters:

firstElement - the first element to include

remainingElements - the remaining elements to include

Returns:

the non-empty list

of

static <E> NonEmptyList<E> of(E firstElement,
                              List<E> remainingElements)

Construct a non-empty list containing a specific object as its first element, and any elements contained in another list as its remaining elements.

Type Parameters:

E - the type of the elements

Parameters:

firstElement - the first element to include

remainingElements - the remaining elements to include

Returns:

the non-empty list

of

static <E> Optional<NonEmptyList<E>> of(List<E> list)

Try to construct a non-empty list from a given list, which may be empty.

Type Parameters:

E - the type of elements in the list.

Parameters:

list - the list, which may be empty

Returns:

the resulting non-empty list, or Optional.empty() if the given list is empty

ofUnsafe

static <E> NonEmptyList<E> ofUnsafe(List<E> list)

Unsafe construction of non-empty list from a possibly empty list.

This method should only be used when the given list is guarantied to be empty, and thus offers a fail-fast way to introduce the non-empty quality on a type level. Use copyOf(List) if you need more flexibility in handling of a possible empty list.

Type Parameters:

E - the type of elements in the list.

Parameters:

list - the list

Returns:

the resulting non-empty list

Throws:

IllegalArgumentException - if the given list is empty

See Also:

copyOf(List)

copyOf

static <E> Optional<NonEmptyList<E>> copyOf(List<E> list)

Try to construct a non-empty list from copying the elements of a given list, which may be empty.

Type Parameters:

E - the type of elements in the list.

Parameters:

list - the list, which may be empty

Returns:

the resulting non-empty list, or Optional.empty() if the given list is empty

copyOfUnsafe

static <E> NonEmptyList<E> copyOfUnsafe(List<E> nonEmptyList)

Unsafe construction of non-empty list from copying the elements of a possibly empty list.

This method should only be used when the given list is guarantied to be empty, and thus offers a fail-fast way to introduce the non-empty quality on a type level. Use copyOf(List) if you need more flexibility in handling of a possible empty list.

Type Parameters:

E - the type of elements in the list.

Parameters:

nonEmptyList - the list

Returns:

the resulting non-empty list

Throws:

IllegalArgumentException - if the given list is empty

See Also:

copyOf(List)

stream

default NonEmptyStream<E> stream()

Specified by:

stream in interface Collection<E>

first

default E first()

Get the first element of this non-empty list. This method should never fail with an exception.

Returns:

the first element.

isEmpty

default boolean isEmpty()

A non-empty list is never empty, so this always returns true.

Specified by:

isEmpty in interface Collection<E>

Specified by:

isEmpty in interface List<E>

Returns:

always true

isSingular

default boolean isSingular()

Checks if the non-empty list contains only the required singular element, i.e. if the size of the list is exactly 1.

Returns:

true if the list contains only one element, false otherwise.

hasMultipleElements

default boolean hasMultipleElements()

Checks if this non-empty list has multiple elements, i.e. 2 or more elements. This is functionally equivalent of checking if NonEmptyList.size() > 1, but this method should be preferred as implementations may provide more efficient way than checking the actual amount.

Returns:

true if the list contains more than one element, or false if only a single element is contained.

Implementation Note:

Implementations of NonEmptyList should override this default method if they can provide a more efficient way to determine if there are more than one element.