Package software.kes.collectionviews

Interface Set<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>
    All Known Subinterfaces:
    ImmutableNonEmptySet<A>, ImmutableSet<A>, NonEmptySet<A>
    public interface Set<A>
extends software.kes.enhancediterables.FiniteIterable<A>
    A finite, unordered view of a collection that contains no duplicate elements.

    A Set guarantees the following:

    • A size() method that executes in O(1).
    • A contains(A) method that tests an value for membership in O(1).
    • An isEmpty() method that executes in O(1).
    • Iteration will always terminate.
    • Protected from mutation by the bearer.
    • The bearer cannot gain access to a reference to the underlying collection.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      static <A> SetBuilder<A> builder()
      Creates a new SetBuilder.
      static <A> SetBuilder<A> builder​(int initialCapacity)
      Creates a new SetBuilder with an initial capacity hint.
      boolean contains​(A element)
      Tests if an element is a member of this Set.
      static <A> ImmutableSet<A> copyFrom​(int maxCount, A[] source)
      Returns a new ImmutableSet that is copied from an array.
      static <A> ImmutableSet<A> copyFrom​(int maxCount, java.lang.Iterable<A> source)
      Creates an ImmutableSet that is copied from any Iterable, but consuming a maximum number of elements.
      static <A> ImmutableSet<A> copyFrom​(A[] source)
      Creates an ImmutableSet that is copied from an array.
      static <A> ImmutableSet<A> copyFrom​(java.lang.Iterable<A> source)
      Creates an ImmutableSet that is copied from any Iterable.
      default Set<A> distinct()
      Since a Set already contains only distinct values, this method always returns itself.
      static <A> ImmutableSet<A> empty()
      Returns an empty ImmutableSet.
      default com.jnape.palatable.lambda.adt.Maybe<A> find​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
      Finds an element of this Set that satisfies a predicate, if any.
      default boolean isEmpty()
      Tests whether this Set is empty.
      static <A> ImmutableNonEmptySet<A> of​(A first, A... more)
      Creates a ImmutableNonEmptySet with the given elements.
      int size()
      Returns the size of this Set.
      default ImmutableSet<A> toImmutable()
      Converts this Set to an ImmutableSet.
      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> Set<A> wrap​(java.util.Set<A> underlying)
      Creates a Set that wraps a java.util.Set.

      • Methods inherited from interface software.kes.enhancediterables.EnhancedIterable

        concat, concat, take, toArray, toCollection, zipWith, zipWith

      • Methods inherited from interface software.kes.enhancediterables.FiniteIterable

        append, concat, concat, concat, cross, cross, cycle, drop, dropWhile, filter, fmap, foldLeft, foldRight, inits, intersperse, magnetizeBy, partition, prepend, prependAll, reverse, slide, span, tails, takeWhile, toFinite, zipWith

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

        coerce

      • Methods inherited from interface java.lang.Iterable

        forEach, iterator, spliterator

    • Method Detail

      • contains

        boolean contains​(A element)
        Tests if an element is a member of this Set.
        Parameters:
        element - the element to test
        Returns:
        true if element is a member of this Set, false otherwise

      • size

        int size()
        Returns the size of this Set.

        Executes in O(1).

        Specified by:
        size in interface software.kes.enhancediterables.FiniteIterable<A>
        Returns:
        the number of elements in this Set

      • distinct

        default Set<A> distinct()
        Since a Set already contains only distinct values, this method always returns itself.
        Specified by:
        distinct in interface software.kes.enhancediterables.FiniteIterable<A>
        Returns:
        itself

      • find

        default com.jnape.palatable.lambda.adt.Maybe<A> find​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
        Finds an element of this Set that satisfies a predicate, if any.
        Specified by:
        find in interface software.kes.enhancediterables.EnhancedIterable<A>
        Parameters:
        predicate - a predicate; not null
        Returns:
        an element wrapped in a Maybe.just(A) if a matching element is found; Maybe.nothing() otherwise.

      • isEmpty

        default boolean isEmpty()
        Tests whether this Set is empty.

        Executes in O(1).

        Specified by:
        isEmpty in interface software.kes.enhancediterables.EnhancedIterable<A>
        Returns:
        true if this Set is empty, false otherwise.

      • toImmutable

        default ImmutableSet<A> toImmutable()
        Converts this Set to an ImmutableSet. Converts this Set to an ImmutableSet.

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

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

        Returns:
        an ImmutableSet 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.

        If successful, returns a NonEmptySet containing the same elements as this one, wrapped in a Maybe.just(A).

        If this Set is empty, returns Maybe.nothing().

        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>
        Returns:
        a Maybe<NonEmptySet<A>>

      • toNonEmptyOrThrow

        default NonEmptySet<A> toNonEmptyOrThrow()
        Attempts to convert this Set to a NonEmptySet.

        If successful, returns a NonEmptySet containing the same elements as this one. Use this if you are confident that this Set is not empty.

        If this Set is empty, throws an IllegalArgumentException.

        Does not make copies of any underlying data structures.

        Returns:
        a NonEmptySet<A>
        Throws:
        java.lang.IllegalArgumentException - if this Set is empty

      • empty

        static <A> ImmutableSet<A> empty()
        Returns an empty ImmutableSet.
        Type Parameters:
        A - the element type
        Returns:
        an empty ImmutableSet<A>

      • 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>

      • builder

        static <A> SetBuilder<A> builder()
        Creates a new SetBuilder.
        Type Parameters:
        A - the element type
        Returns:
        an empty SetBuilder

      • builder

        static <A> SetBuilder<A> builder​(int initialCapacity)
        Creates a new SetBuilder with an initial capacity hint.
        Type Parameters:
        A - the element type
        Parameters:
        initialCapacity - an initial capacity hint. Must be >= 0.
        Returns:
        an empty SetBuilder

      • wrap

        static <A> Set<A> wrap​(java.util.Set<A> underlying)
        Creates a Set that wraps a java.util.Set.

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

        Bearers of the created Set will be unable to gain access to the underlying Set, so 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 copyFrom(java.lang.Iterable<A>) if you want to avoid this situation.

        Type Parameters:
        A - the element type
        Parameters:
        underlying - Set to wrap; not null
        Returns:
        a Set<A>

      • copyFrom

        static <A> ImmutableSet<A> copyFrom​(java.lang.Iterable<A> source)
        Creates an ImmutableSet 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 ImmutableSet, 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 ImmutableSet<A>

      • copyFrom

        static <A> ImmutableSet<A> copyFrom​(A[] source)
        Creates an ImmutableSet 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 ImmutableSet<A>

      • copyFrom

        static <A> ImmutableSet<A> copyFrom​(int maxCount,
                                    java.lang.Iterable<A> source)
        Creates an ImmutableSet 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 ImmutableSet and its size 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.
        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 ImmutableSet that contains at most maxCount elements

      • copyFrom

        static <A> ImmutableSet<A> copyFrom​(int maxCount,
                                    A[] source)
        Returns a new ImmutableSet that is copied from an array.
        Type Parameters:
        A - the element type
        Parameters:
        maxCount - the maximum number of elements to copy from the array. Must be >= 0.
        source - the array to copy from. Not null. This method will not alter or hold on to a reference of this array.
        Returns:
        an ImmutableSet<A>