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.

Implementation Note:

In general, constructing a NonEmptyList from another mutable container source (e.g. an existing list or array), and then changing the contents of the source, results in undefined behavior of the non-empty list. The only guarantee is that the non-empty list will never be empty, but the behavior when mutating a list on which the non-empty list is based on should not be relied on.

If you need to construct non-empty lists based on another container you need to further mutate, consider using one of the copyOf constructors, which will copy the given references so that any subsequent changes to the to the given source container will not be reflected in the created non-empty list. (As usual, this is a shallow copy, meaning that the instances themselves can of course be mutated by anything.)

Method Summary

Modifier and Type	Method	Description
static <E> Optional<NonEmptyList<E>>	copyOf(E[] array)	Try to construct a non-empty list from copying the elements of a given array, which may be empty.
static <E> Optional<NonEmptyList<E>>	copyOf(Collection<E> collection)	Try to construct a non-empty list from copying the elements of a given collection, which may be empty.
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(E[] nonEmptyArray)	Unsafe construction of non-empty list from copying the elements of an array assumed to be non-empty.
static <E> NonEmptyList<E>	copyOfUnsafe(Collection<E> nonEmptyCollection)	Unsafe construction of non-empty list from copying the elements of a collection assumed to be non-empty.
static <E> NonEmptyList<E>	copyOfUnsafe(List<E> nonEmptyList)	Unsafe construction of non-empty list from copying the elements of a list assumed to be non-empty.
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> Optional<NonEmptyList<E>>	of(E[] array)	Try to construct a non-empty list from a given array, which may be empty.
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(E[] nonEmptyArray)	Try to construct a non-empty list from a given array, which is assumed is not empty.
static <E> NonEmptyList<E>	ofUnsafe(List<E> nonEmptyList)	Try to construct a non-empty list from a given list, which is assumed is not empty.
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 Details

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

of

static <E> Optional<NonEmptyList<E>> of(E[] array)

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

Type Parameters:

E - the type of elements in the array.

Parameters:

array - the array, which may be empty

Returns:

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

ofUnsafe

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

Try to construct a non-empty list from a given list, which is assumed is not empty.

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 of(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, which is assumed not to be empty

Returns:

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

Throws:

IllegalArgumentException - if the given list is empty

ofUnsafe

static <E> NonEmptyList<E> ofUnsafe(E[] nonEmptyArray)

Try to construct a non-empty list from a given array, which is assumed is not empty.

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 of(Object[]) if you need more flexibility in handling of a possible empty list.

Type Parameters:

E - the type of elements in the array.

Parameters:

nonEmptyArray - the array, which is assumed not to be empty

Returns:

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

Throws:

IllegalArgumentException - if the given array is empty

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

copyOf

static <E> Optional<NonEmptyList<E>> copyOf(Collection<E> collection)

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

Type Parameters:

E - the type of elements in the collection.

Parameters:

collection - the collection, which may be empty

Returns:

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

copyOf

static <E> Optional<NonEmptyList<E>> copyOf(E[] array)

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

Type Parameters:

E - the type of elements in the array.

Parameters:

array - the array, which may be empty

Returns:

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

copyOfUnsafe

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

Unsafe construction of non-empty list from copying the elements of a list assumed to be non-empty.

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, which is assumed not to be empty

Returns:

the resulting non-empty list

Throws:

IllegalArgumentException - if the given list is empty

See Also:

• copyOf(List)

copyOfUnsafe

static <E> NonEmptyList<E> copyOfUnsafe(Collection<E> nonEmptyCollection)

Unsafe construction of non-empty list from copying the elements of a collection assumed to be non-empty.

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

Type Parameters:

E - the type of elements in the list.

Parameters:

nonEmptyCollection - the collection, which is assumed not to be empty

Returns:

the resulting non-empty list

Throws:

IllegalArgumentException - if the given list is empty

See Also:

• copyOf(Collection)

copyOfUnsafe

static <E> NonEmptyList<E> copyOfUnsafe(E[] nonEmptyArray)

Unsafe construction of non-empty list from copying the elements of an array assumed to be non-empty.

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

Type Parameters:

E - the type of elements in the array.

Parameters:

nonEmptyArray - the array, which is assumed not to be empty

Returns:

the resulting non-empty list

Throws:

IllegalArgumentException - if the given array is empty

See Also:

• copyOf(Object[])

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.