Class NonEmptySet<T>

java.lang.Object
dmx.fun.NonEmptySet<T>
Type Parameters:
T - the type of elements in this set
All Implemented Interfaces:
Iterable<T>
@NullMarked public final class NonEmptySet<T> extends Object implements Iterable<T>
An immutable, non-empty set: a set 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 NonEmptySet<T> instead of Set<T> and eliminate runtime emptiness checks entirely.

Insertion order is preserved (backed by LinkedHashSet). The first element inserted is the head().

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

  • Method Details

    • of

      public static <T> NonEmptySet<T> of(T head, Set<? extends T> rest)
      Creates a NonEmptySet with the given head element and additional elements.

      If rest contains head, the duplicate is silently ignored.

      Type Parameters:
      T - the element type
      Parameters:
      head - the first (mandatory) element; must not be null
      rest - additional elements; must not be null; elements must not be null
      Returns:
      a new NonEmptySet
      Throws:
      NullPointerException - if head, rest, or any element in rest is null

    • singleton

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

    • fromSet

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

    • head

      public T head()
      Returns the guaranteed head element of this set (the first inserted element).
      Returns:
      the head element (never null)

    • size

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

    • contains

      public boolean contains(T element)
      Returns true if this set contains element.
      Parameters:
      element - the element to test; must not be null
      Returns:
      true if the element is present
      Throws:
      NullPointerException - if element is null

    • toSet

      public Set<T> toSet()
      Returns an unmodifiable Set containing all elements (head first, then tail in insertion order). The same instance is returned on repeated calls (lazily initialized, thread-safe).
      Returns:
      an unmodifiable set with all elements

    • map

      public <R> NonEmptySet<R> map(Function<? super T, ? extends R> mapper)
      Applies mapper to every element and returns a new NonEmptySet of the results. Duplicate mapped values are deduplicated; the head is always the mapped value of the original head.
      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 NonEmptySet of mapped values
      Throws:
      NullPointerException - if mapper is null or returns null

    • filter

      public Option<NonEmptySet<T>> filter(Predicate<? super T> predicate)
      Returns a new NonEmptySet containing elements that satisfy predicate, wrapped in Option.some(Object). Returns Option.none() if no elements pass the predicate.
      Parameters:
      predicate - a non-null predicate to test each element
      Returns:
      Some(filteredSet) if at least one element passes, None otherwise
      Throws:
      NullPointerException - if predicate is null

    • union

      public NonEmptySet<T> union(NonEmptySet<T> other)
      Returns a new NonEmptySet that is the union of this set and other. The result is always non-empty since both inputs are non-empty.
      Parameters:
      other - the other set; must not be null
      Returns:
      a new NonEmptySet containing all elements from both sets
      Throws:
      NullPointerException - if other is null

    • intersection

      public Option<NonEmptySet<T>> intersection(Set<? extends T> other)
      Returns a new NonEmptySet containing only elements present in both this set and other, wrapped in Option.some(Object). Returns Option.none() if the intersection is empty.
      Parameters:
      other - the set to intersect with; must not be null
      Returns:
      Some(intersection) if at least one common element exists, None otherwise
      Throws:
      NullPointerException - if other is null

    • toNonEmptyList

      public NonEmptyList<T> toNonEmptyList()
      Converts this set to a NonEmptyList of its elements in insertion order.
      Returns:
      a NonEmptyList<T> with the same elements

    • toNonEmptyMap

      public <V> NonEmptyMap<T,V> toNonEmptyMap(Function<? super T, ? extends V> valueMapper)
      Returns a NonEmptyMap by applying valueMapper to each element of this set. Elements become keys; mapped results become values. The head of this set is the head key of the returned map.
      Type Parameters:
      V - the value type
      Parameters:
      valueMapper - a non-null function to derive a value from each element; must not return null
      Returns:
      a new NonEmptyMap<T, V>
      Throws:
      NullPointerException - if valueMapper is null or returns null

    • iterator

      public Iterator<T> iterator()
      Returns an iterator over all elements (head first, then tail in insertion order).
      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