Class NonEmptyList<T>

java.lang.Object
dmx.fun.NonEmptyList<T>
Type Parameters:
T - the type of elements in this list
All Implemented Interfaces:
Iterable<T>
@NullMarked public final class NonEmptyList<T> extends Object implements Iterable<T>
An immutable, non-empty list: a list guaranteed at construction time to contain at least one element.

This type makes the non-emptiness constraint part of the static type system. APIs that require at least one item can declare NonEmptyList<T> instead of List<T> and eliminate runtime emptiness checks entirely.

NonEmptyList<T> pairs naturally with Validated's error accumulation, which always produces at least one error when invalid.

This class is @NullMarked: all elements and parameters are non-null by default.

  • Method Details

    • of

      public static <T> NonEmptyList<T> of(T head, List<? extends T> tail)
      Creates a NonEmptyList with the given head and tail.
      Type Parameters:
      T - the element type
      Parameters:
      head - the first (mandatory) element; must not be null
      tail - the remaining elements; must not be null; elements must not be null
      Returns:
      a new NonEmptyList
      Throws:
      NullPointerException - if head, tail, or any tail element is null

    • singleton

      public static <T> NonEmptyList<T> singleton(T head)
      Creates a NonEmptyList containing exactly one element.
      Type Parameters:
      T - the element type
      Parameters:
      head - the sole element; must not be null
      Returns:
      a singleton NonEmptyList
      Throws:
      NullPointerException - if head is null

    • fromList

      public static <T> Option<NonEmptyList<T>> fromList(List<? extends T> list)
      Attempts to construct a NonEmptyList from a plain List.
      Type Parameters:
      T - the element type
      Parameters:
      list - the source list; must not be null; elements must not be null
      Returns:
      Option.some(Object) wrapping the NonEmptyList if the list is non-empty, or Option.none() if the list is empty
      Throws:
      NullPointerException - if list or any element is null

    • head

      public T head()
      Returns the first element of this list.
      Returns:
      the head element (never null)

    • tail

      public List<T> tail()
      Returns an unmodifiable view of all elements after the head. May be empty if this is a singleton list.
      Returns:
      the tail (never null, may be empty)

    • toList

      public List<T> toList()
      Returns an unmodifiable List containing all elements (head followed by tail).
      Returns:
      a new unmodifiable list with all elements

    • size

      public int size()
      Returns the number of elements in this list. Always ≥ 1.
      Returns:
      the size

    • map

      public <R> NonEmptyList<R> map(Function<? super T, ? extends R> mapper)
      Applies mapper to every element and returns a new NonEmptyList of the results. The structure (head/tail split) is preserved.
      Type Parameters:
      R - the result element type
      Parameters:
      mapper - a non-null function to apply to each element; must not return null
      Returns:
      a new NonEmptyList of mapped values
      Throws:
      NullPointerException - if mapper is null or returns null

    • append

      public NonEmptyList<T> append(T element)
      Returns a new NonEmptyList with element appended at the end.
      Parameters:
      element - the element to append; must not be null
      Returns:
      a new NonEmptyList with the element appended
      Throws:
      NullPointerException - if element is null

    • prepend

      public NonEmptyList<T> prepend(T element)
      Returns a new NonEmptyList with element prepended at the front.
      Parameters:
      element - the element to prepend; must not be null
      Returns:
      a new NonEmptyList with the element prepended
      Throws:
      NullPointerException - if element is null

    • concat

      public NonEmptyList<T> concat(NonEmptyList<T> other)
      Returns a new NonEmptyList that is the concatenation of this list and other.
      Parameters:
      other - the list to append; must not be null
      Returns:
      a new NonEmptyList containing all elements of both lists
      Throws:
      NullPointerException - if other is null

    • toNonEmptySet

      public NonEmptySet<T> toNonEmptySet()
      Converts this list to a NonEmptySet, preserving the head element and deduplicating the tail in insertion order. Duplicate elements are silently dropped; the head is always retained.
      Returns:
      a NonEmptySet<T> with the same distinct elements

    • toStream

      public Stream<T> toStream()
      Returns a sequential Stream of all elements (head first, then tail). Does not materialize an intermediate list.
      Returns:
      a Stream<T> over all elements

    • collector

      public static <T> Collector<T, ?, Option<NonEmptyList<T>>> collector()
      Returns a Collector that accumulates a Stream<T> into an Option<NonEmptyList<T>>.

      Produces Option.some(Object) if the stream has at least one element, or Option.none() if the stream is empty.

      Type Parameters:
      T - the element type
      Returns:
      a Collector producing Option<NonEmptyList<T>>

    • toNonEmptyList

      public static <T> Collector<T, ?, Option<NonEmptyList<T>>> toNonEmptyList()
      Alias for collector().

      Returns a Collector that accumulates a Stream<T> into an Option<NonEmptyList<T>>. Produces Option.some(Object) if the stream has at least one element, or Option.none() if the stream is empty. 

      Option<NonEmptyList<String>> tags =
    Stream.of("java", "fp", "dmx-fun")
          .collect(NonEmptyList.toNonEmptyList());
// Some(["java", "fp", "dmx-fun"])

Option<NonEmptyList<String>> empty =
    Stream.<String>empty()
          .collect(NonEmptyList.toNonEmptyList());
// None
      Type Parameters:
      T - the element type
      Returns:
      a Collector producing Option<NonEmptyList<T>>

    • sequence

      public static <T> Option<NonEmptyList<T>> sequence(NonEmptyList<Option<T>> nel)
      Sequences a NonEmptyList of Options into an Option of a NonEmptyList.

      Returns Option.some(Object) containing all unwrapped values if every element is Option.some(Object); returns Option.none() as soon as any element is Option.none().

      Type Parameters:
      T - the element type
      Parameters:
      nel - a NonEmptyList<Option<T>>; must not be null
      Returns:
      Some(NonEmptyList<T>) if all options are present, None otherwise
      Throws:
      NullPointerException - if nel is null

    • iterator

      public Iterator<T> iterator()
      Returns an iterator over all elements (head first, then tail). Does not materialize an intermediate list.
      Specified by:
      iterator in interface Iterable<T>
      Returns:
      an iterator

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object