Package software.kes.collectionviews

Interface NonEmptySet<A>

Type Parameters:

A - the element type

All Superinterfaces:

software.kes.enhancediterables.EnhancedIterable<A>, software.kes.enhancediterables.FiniteIterable<A>, com.jnape.palatable.lambda.functor.Functor<A,software.kes.enhancediterables.EnhancedIterable<?>>, java.lang.Iterable<A>, software.kes.enhancediterables.NonEmptyFiniteIterable<A>, software.kes.enhancediterables.NonEmptyIterable<A>, Set<A>

All Known Subinterfaces:

ImmutableNonEmptySet<A>

public interface NonEmptySet<A>
extends software.kes.enhancediterables.NonEmptyFiniteIterable<A>, Set<A>

A Set that is guaranteed at compile-time to contain at least one element.

In addition to guarantees of Set, provides the following benefits:

• NonEmptyIterable.head() method that returns an element.
• Implements NonEmptyIterable.

Method Summary

Modifier and Type	Method	Description
static <A> ImmutableNonEmptySet<A>	copyFromOrThrow(int maxCount, A[] source)	Attempts to create an ImmutableNonEmptySet that is copied from an array, but with a maximum number of elements.
static <A> ImmutableNonEmptySet<A>	copyFromOrThrow(int maxCount, java.lang.Iterable<A> source)	Attempts to create an ImmutableNonEmptySet from any Iterable, but consuming a maximum number of elements.
static <A> ImmutableNonEmptySet<A>	copyFromOrThrow(A[] source)	Attempts to create an ImmutableNonEmptySet that is copied from an array.
static <A> ImmutableNonEmptySet<A>	copyFromOrThrow(java.lang.Iterable<A> source)	Attempts to create an ImmutableNonEmptySet from any Iterable.
default NonEmptySet<A>	distinct()	Since a NonEmptySet already contains only distinct values, this method always returns itself.
default boolean	isEmpty()	Tests whether this NonEmptySet is empty.
static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptySet<A>>	maybeCopyFrom(int maxCount, A[] source)	Attempts to create an ImmutableNonEmptySet that is copied from an array, but with a maximum number of elements.
static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptySet<A>>	maybeCopyFrom(int maxCount, java.lang.Iterable<A> source)	Attempts to create an ImmutableNonEmptySet that is copied from any Iterable, but consuming a maximum number of elements.
static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptySet<A>>	maybeCopyFrom(A[] source)	Attempts to create an ImmutableNonEmptySet that is copied from an array.
static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptySet<A>>	maybeCopyFrom(java.lang.Iterable<A> source)	Attempts to create an ImmutableNonEmptySet that is copied from any Iterable.
static <A> com.jnape.palatable.lambda.adt.Maybe<NonEmptySet<A>>	maybeWrap(java.util.Set<A> underlying)	Attempts to create a NonEmptySet that wraps a java.util.Set.
static <A> ImmutableNonEmptySet<A>	of(A first, A... more)	Creates a ImmutableNonEmptySet with the given elements.
default ImmutableNonEmptySet<A>	toImmutable()	Converts this NonEmptySet to an ImmutableNonEmptySet.
default com.jnape.palatable.lambda.adt.Maybe<? extends NonEmptySet<A>>	toNonEmpty()	Attempts to convert this Set to a NonEmptySet.
default NonEmptySet<A>	toNonEmptyOrThrow()	Attempts to convert this Set to a NonEmptySet.
static <A> NonEmptySet<A>	wrapOrThrow(java.util.Set<A> underlying)	Attempts to create a NonEmptySet that wraps a java.util.Set.

Methods inherited from interface software.kes.enhancediterables.EnhancedIterable

concat, take, toArray, toCollection, zipWith, zipWith

Methods inherited from interface software.kes.enhancediterables.FiniteIterable

append, concat, cross, cross, drop, dropWhile, filter, foldLeft, foldRight, inits, partition, prepend, slide, span, tails, takeWhile, zipWith

Methods inherited from interface com.jnape.palatable.lambda.functor.Functor

coerce

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface software.kes.enhancediterables.NonEmptyFiniteIterable

concat, concat, cross, cycle, fmap, init, intersperse, last, magnetizeBy, prependAll, reduceLeft, reduceRight, reverse, tail, toFinite, zipWith

Methods inherited from interface software.kes.enhancediterables.NonEmptyIterable

concat, head, iterator, zipWith

Methods inherited from interface software.kes.collectionviews.Set

contains, find, size

Method Detail

distinct

default NonEmptySet<A> distinct()

Since a NonEmptySet already contains only distinct values, this method always returns itself.

Specified by:

distinct in interface software.kes.enhancediterables.FiniteIterable<A>

Specified by:

distinct in interface software.kes.enhancediterables.NonEmptyFiniteIterable<A>

Specified by:

distinct in interface Set<A>

Returns:

itself

isEmpty

default boolean isEmpty()

Tests whether this NonEmptySet is empty.

Always returns false for NonEmptySets.

Specified by:

isEmpty in interface software.kes.enhancediterables.EnhancedIterable<A>

Specified by:

isEmpty in interface software.kes.enhancediterables.NonEmptyIterable<A>

Specified by:

isEmpty in interface Set<A>

Returns:

always false

toImmutable

default ImmutableNonEmptySet<A> toImmutable()

Converts this NonEmptySet to an ImmutableNonEmptySet.

This method will make a copy of the underlying data structure if necessary to guarantee immutability.

If this NonEmptySet is already an ImmutableNonEmptySet, no copies are made and this method is a no-op.

Specified by:

toImmutable in interface Set<A>

Returns:

an ImmutableNonEmptySet of the same type and containing the same elements

toNonEmpty

default com.jnape.palatable.lambda.adt.Maybe<? extends NonEmptySet<A>> toNonEmpty()

Attempts to convert this Set to a NonEmptySet.

Since this will always be successful for NonEmptySets, this method always returns itself wrapped in a Maybe.just(A).

Does not make copies of any underlying data structures.

Specified by:

toNonEmpty in interface software.kes.enhancediterables.EnhancedIterable<A>

Specified by:

toNonEmpty in interface software.kes.enhancediterables.FiniteIterable<A>

Specified by:

toNonEmpty in interface software.kes.enhancediterables.NonEmptyFiniteIterable<A>

Specified by:

toNonEmpty in interface software.kes.enhancediterables.NonEmptyIterable<A>

Specified by:

toNonEmpty in interface Set<A>

Returns:

this NonEmptySet wrapped in a Maybe.just(A)

toNonEmptyOrThrow

default NonEmptySet<A> toNonEmptyOrThrow()

Attempts to convert this Set to a NonEmptySet.

Since this will always be successful for NonEmptySets, this method always returns itself.

Does not make copies of any underlying data structures.

Specified by:

toNonEmptyOrThrow in interface Set<A>

Returns:

this NonEmptySet

of

@SafeVarargs
static <A> ImmutableNonEmptySet<A> of(A first,
                                      A... more)

Creates a ImmutableNonEmptySet with the given elements.

Type Parameters:

A - the element type

Parameters:

first - the first element

more - the remaining elements

Returns:

an ImmutableNonEmptySet<A>

maybeWrap

static <A> com.jnape.palatable.lambda.adt.Maybe<NonEmptySet<A>> maybeWrap(java.util.Set<A> underlying)

Attempts to create a NonEmptySet that wraps a java.util.Set.

Does not make any copies of the given Set. The created NonEmptySet will hold a reference to the given Set, but will not alter it in any way.

Bearers of the NonEmptySet will be unable to gain access to the underlying Set, it is safe to share.

Since no copy is made, be aware that anyone that holds a direct reference to the underlying Set can still mutate it. Mutating the underlying Set is not advised. Operations that change the size of the underlying Set will result in unpredictable behavior. Use Vector.copyFrom(java.lang.Iterable<A>) if you want to avoid this situation.

Type Parameters:

A - the element type

Parameters:

underlying - java.util.Set to wrap; not null

Returns:

a NonEmptySet<A> wrapped in a Maybe.just(A) if underlying is non-empty; Maybe.nothing() otherwise.

wrapOrThrow

static <A> NonEmptySet<A> wrapOrThrow(java.util.Set<A> underlying)

Attempts to create a NonEmptySet that wraps a java.util.Set. If it is not possible, throws an IllegalArgumentException.

Does not make any copies of the given Set. The created NonEmptySet will hold a reference to the given java.util.Set, but will not alter it in any way.

Bearers of the created NonEmptySet will be unable to gain access to the underlying Set, it is safe to share.

Since no copy is made, be aware that anyone that holds a direct reference to the underlying Set can still mutate it. Mutating the underlying Set is not advised. Operations that change the size of the underlying Set will result in unpredictable behavior. Use copyFromOrThrow(Iterable) if you want to avoid this situation.

Type Parameters:

A - the element type

Parameters:

underlying - java.util.Set to wrap; not null

Returns:

a NonEmptySet<A> if underlying is non-empty; throws an IllegalArgumentException otherwise

maybeCopyFrom

static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptySet<A>> maybeCopyFrom(java.lang.Iterable<A> source)

Attempts to create an ImmutableNonEmptySet that is copied from any Iterable.

The entire Iterable will be eagerly iterated. Be careful not to pass in an infinite Iterable or this method will not terminate.

If necessary to guarantee immutability, this method will make a copy of the data provided. If source already is an ImmutableNonEmptySet, it will be returned directly.

Type Parameters:

A - the element type

Parameters:

source - an Iterable<A> that may be iterated eagerly in its entirety; not null

Returns:

an ImmutableNonEmptySet<A> wrapped in a Maybe.just(A) if source is non-empty; Maybe.nothing() otherwise.

maybeCopyFrom

static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptySet<A>> maybeCopyFrom(A[] source)

Attempts to create an ImmutableNonEmptySet that is copied from an array.

Type Parameters:

A - the element type

Parameters:

source - the array to copy from. Not null. This method will not alter or hold on to a reference of this array.

Returns:

an ImmutableNonEmptySet<A> wrapped in a Maybe.just(A) if source is non-empty; Maybe.nothing() otherwise.

maybeCopyFrom

static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptySet<A>> maybeCopyFrom(int maxCount,
                                                                                       java.lang.Iterable<A> source)

Attempts to create an ImmutableNonEmptySet that is copied from any Iterable, but consuming a maximum number of elements.

The Iterable will be eagerly iterated, but only up to a maximum of maxCount elements. If maxCount elements are not available, then the all of the elements available will be returned.

This method will make a copy of the data provided, unless source is an ImmutableNonEmptySet and its size is equal to maxCount, in which case it will be returned directly.

Type Parameters:

A - the element type

Parameters:

maxCount - the maximum number of elements to consume from the source. Must be >= 0. If 0, this method will always return Maybe.nothing().

source - an Iterable<A> that will be iterated eagerly for up to maxCount elements. Not null. It is safe for source to be infinite.

Returns:

an ImmutableNonEmptySet<A> wrapped in a Maybe.just(A) if source is non-empty; Maybe.nothing() otherwise.

maybeCopyFrom

static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptySet<A>> maybeCopyFrom(int maxCount,
                                                                                       A[] source)

Attempts to create an ImmutableNonEmptySet that is copied from an array, but with a maximum number of elements.

Type Parameters:

A - the element type

Parameters:

maxCount - the maximum number of elements to copy from the array. Must be >= 0. If 0, this method will always return Maybe.nothing().

source - the array to copy from. Not null. This method will not alter or hold on to a reference of this array.

Returns:

an ImmutableNonEmptySet<A> wrapped in a Maybe.just(A) if source is non-empty; Maybe.nothing() otherwise.

copyFromOrThrow

static <A> ImmutableNonEmptySet<A> copyFromOrThrow(java.lang.Iterable<A> source)

Attempts to create an ImmutableNonEmptySet from any Iterable. If the Iterable is empty, throws an IllegalArgumentException.

The entire Iterable will be eagerly iterated. Be careful not to pass in an infinite Iterable or this method will not terminate.

If necessary to guarantee immutability, this method will make a copy of the data provided. If source already is an ImmutableNonEmptySet, it will be returned directly.

Type Parameters:

A - the element type

Parameters:

source - an Iterable<A> that will be iterated eagerly in its entirety; not null

Returns:

an ImmutableNonEmptySet<A>

copyFromOrThrow

static <A> ImmutableNonEmptySet<A> copyFromOrThrow(A[] source)

Attempts to create an ImmutableNonEmptySet that is copied from an array. If the array is empty, throws an IllegalArgumentException.

Type Parameters:

A - the element type

Parameters:

source - the array to copy from. Not null. This method will not alter or hold on to a reference of this array.

Returns:

an ImmutableNonEmptySet<A>

copyFromOrThrow

static <A> ImmutableNonEmptySet<A> copyFromOrThrow(int maxCount,
                                                   java.lang.Iterable<A> source)

Attempts to create an ImmutableNonEmptySet from any Iterable, but consuming a maximum number of elements. If the Iterable is empty, throws an IllegalArgumentException.

The Iterable will be eagerly iterated, but only up to a maximum of maxCount elements. If maxCount elements are not available, then the all of the elements available will be returned.

This method will make a copy of the data provided, unless source is an ImmutableNonEmptySet and its size is equal to maxCount, in which case it will be returned directly.

Type Parameters:

A - the element type

Parameters:

maxCount - the maximum number of elements to consume from the source. Must be >= 1.

source - an Iterable<A> that will be iterated eagerly for up to maxCount elements. Not null. It is safe for source to be infinite.

Returns:

an ImmutableNonEmptySet<A>

copyFromOrThrow

static <A> ImmutableNonEmptySet<A> copyFromOrThrow(int maxCount,
                                                   A[] source)

Attempts to create an ImmutableNonEmptySet that is copied from an array, but with a maximum number of elements. If the array is empty, throws an IllegalArgumentException.

Type Parameters:

A - the element type

Parameters:

maxCount - the maximum number of elements to copy from the array. Must be >= 1.

source - the array to copy from. Not null. This method will not alter or hold on to a reference of this array.

Returns:

an ImmutableNonEmptySet<A>