Package software.kes.collectionviews

Interface NonEmptyVector<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>, java.util.RandomAccess, Vector<A>
    All Known Subinterfaces:
    ImmutableNonEmptyVector<A>
    public interface NonEmptyVector<A>
extends software.kes.enhancediterables.NonEmptyFiniteIterable<A>, Vector<A>
    A Vector that is guaranteed at compile-time to contain at least one element.

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

    • Method Summary

      All Methods Static Methods Instance Methods Default Methods 
      Modifier and Type Method Description
      static <A> NonEmptyVectorBuilder<A> builder​(int initialCapacity, A first)
      Creates a new NonEmptyVectorBuilder with an initial capacity hint.
      static <A> NonEmptyVectorBuilder<A> builder​(A first)
      Creates a new NonEmptyVectorBuilder.
      static <A> ImmutableNonEmptyVector<A> copyFromOrThrow​(int maxCount, A[] source)
      Attempts to create an ImmutableNonEmptyVector that is copied from an array, but with a maximum number of elements.
      static <A> ImmutableNonEmptyVector<A> copyFromOrThrow​(int maxCount, java.lang.Iterable<A> source)
      Attempts to create an ImmutableNonEmptyVector from any Iterable, but consuming a maximum number of elements.
      static <A> ImmutableNonEmptyVector<A> copyFromOrThrow​(A[] source)
      Attempts to create an ImmutableNonEmptyVector that is copied from an array.
      static <A> ImmutableNonEmptyVector<A> copyFromOrThrow​(java.lang.Iterable<A> source)
      Attempts to create an ImmutableNonEmptyVector from any Iterable.
      default <B> NonEmptyVector<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,​B>> cross​(NonEmptyVector<B> other)
      Returns the cartesian product of this NonEmptyVector with another NonEmptyVector.
      static <A> ImmutableNonEmptyVector<A> fill​(int size, A value)
      Creates an ImmutableNonEmptyVector that repeats the same element size times.
      default <B> NonEmptyVector<B> fmap​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends B> f)
      Maps a function over this NonEmptyVector.
      default A head()
      Returns the first element.
      default ImmutableNonEmptyVector<java.lang.Integer> indices()
      Returns an ImmutableNonEmptyVector<Integer> that contains all the indices of this NonEmptyVector.
      default Vector<A> init()
      Returns the init of this NonEmptyVector.
      default boolean isEmpty()
      Tests whether this NonEmptyVector is empty.
      default java.util.Iterator<A> iterator()
      Returns an iterator over this NonEmptyVector's elements.
      default A last()
      Returns the last element.
      static <A> ImmutableNonEmptyVector<A> lazyFill​(int size, com.jnape.palatable.lambda.functions.Fn1<java.lang.Integer,​A> valueSupplier)
      Creates an ImmutableNonEmptyVector where elements are lazily evaluated.
      static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptyVector<A>> maybeCopyFrom​(int maxCount, A[] source)
      Attempts to create an ImmutableNonEmptyVector that is copied from an array, but with a maximum number of elements.
      static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptyVector<A>> maybeCopyFrom​(int maxCount, java.lang.Iterable<A> source)
      Attempts to create an ImmutableNonEmptyVector that is copied from any Iterable, but consuming a maximum number of elements.
      static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptyVector<A>> maybeCopyFrom​(A[] source)
      Attempts to create an ImmutableNonEmptyVector that is copied from an array.
      static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptyVector<A>> maybeCopyFrom​(java.lang.Iterable<A> source)
      Attempts to create an ImmutableNonEmptyVector that is copied from any Iterable.
      static <A> com.jnape.palatable.lambda.adt.Maybe<NonEmptyVector<A>> maybeWrap​(A[] underlying)
      Attempts to create a NonEmptyVector that wraps an array.
      static <A> com.jnape.palatable.lambda.adt.Maybe<NonEmptyVector<A>> maybeWrap​(java.util.List<A> underlying)
      Attempts to create a NonEmptyVector that wraps a java.util.List.
      static <A> ImmutableNonEmptyVector<A> nonEmptyCopyFrom​(int maxCount, software.kes.enhancediterables.NonEmptyIterable<A> source)
      Creates an ImmutableNonEmptyVector that is copied from any NonEmptyIterable, but consuming a maximum number of elements.
      static <A> ImmutableNonEmptyVector<A> nonEmptyCopyFrom​(software.kes.enhancediterables.NonEmptyIterable<A> source)
      Creates an ImmutableNonEmptyVector that is copied from any NonEmptyIterable.
      static <A> ImmutableNonEmptyVector<A> of​(A first, A... more)
      Creates a ImmutableNonEmptyVector with the given elements.
      static ImmutableNonEmptyVector<java.lang.Integer> range​(int size)
      Creates an ImmutableNonEmptyVector<Integer> containing elements 0..size - 1.
      default NonEmptyVector<A> reverse()
      Creates a NonEmptyVector with this NonEmptyVector's elements in reversed order.
      default Vector<A> tail()
      Returns the tail of this NonEmptyVector.
      default ImmutableNonEmptyVector<A> toImmutable()
      Converts this NonEmptyVector to an ImmutableNonEmptyVector.
      default com.jnape.palatable.lambda.adt.Maybe<? extends NonEmptyVector<A>> toNonEmpty()
      Attempts to convert this Vector to a NonEmptyVector.
      default NonEmptyVector<A> toNonEmptyOrThrow()
      Attempts to convert this Vector to a NonEmptyVector.
      static <A> NonEmptyVector<A> wrapOrThrow​(A[] underlying)
      Attempts to create a NonEmptyVector that wraps an array.
      static <A> NonEmptyVector<A> wrapOrThrow​(java.util.List<A> underlying)
      Attempts to create a NonEmptyVector that wraps a java.util.List.
      default <B,​C>
      NonEmptyVector<C>      		 zipWith​(com.jnape.palatable.lambda.functions.Fn2<A,​B,​C> fn, NonEmptyVector<B> other)
      Zips together this NonEmptyVector with another NonEmptyVector by applying a zipping function.
      default NonEmptyVector<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,​java.lang.Integer>> zipWithIndex()
      Zips this NonEmptyVector with its indices.

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

        concat, find, toArray, toCollection, zipWith, zipWith

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

        append, concat, cross, cross, dropWhile, filter, foldLeft, foldRight, partition, prepend, span, 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, distinct, intersperse, magnetizeBy, prependAll, reduceLeft, reduceRight, toFinite, zipWith

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

        concat, zipWith

    • Method Detail

      • cross

        default <B> NonEmptyVector<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,​B>> cross​(NonEmptyVector<B> other)
        Returns the cartesian product of this NonEmptyVector with another NonEmptyVector.

        Does not make copies of any underlying collections.

        The returned NonEmptyVector will have a size of size() × other.size(), but will allocate no extra memory (aside from a few bytes for housekeeping).

        Type Parameters:
        B - the type of the other NonEmptyVector
        Parameters:
        other - a NonEmptyVector of any type
        Returns:
        a NonEmptyVector<Tuple2<A, B>>

      • fmap

        default <B> NonEmptyVector<B> fmap​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends B> f)
        Maps a function over this NonEmptyVector.

        Returns a new NonEmptyVector of the same size (but possibly a different type).

        Does not make any copies of underlying collections.

        This method is stack-safe, so a NonEmptyVector can be mapped as many times as the heap permits.

        Specified by:
        fmap in interface software.kes.enhancediterables.EnhancedIterable<A>
        Specified by:
        fmap in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        fmap in interface com.jnape.palatable.lambda.functor.Functor<A,​software.kes.enhancediterables.EnhancedIterable<?>>
        Specified by:
        fmap in interface software.kes.enhancediterables.NonEmptyFiniteIterable<A>
        Specified by:
        fmap in interface software.kes.enhancediterables.NonEmptyIterable<A>
        Specified by:
        fmap in interface Vector<A>
        Type Parameters:
        B - The type of the elements contained in the output Vector.
        Parameters:
        f - a function from A to B. Not null. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.
        Returns:
        a NonEmptyVector<B> of the same size

      • head

        default A head()
        Returns the first element.
        Specified by:
        head in interface software.kes.enhancediterables.NonEmptyIterable<A>
        Returns:
        an element of type A

      • indices

        default ImmutableNonEmptyVector<java.lang.Integer> indices()
        Returns an ImmutableNonEmptyVector<Integer> that contains all the indices of this NonEmptyVector.
        Specified by:
        indices in interface Vector<A>
        Returns:
        an ImmutableNonEmptyVector<Integer>

      • init

        default Vector<A> init()
        Returns the init of this NonEmptyVector.

        The init of a NonEmptyVector is the same Vector with the last element dropped. May be empty.

        Does not make copies of any underlying collections.

        Specified by:
        init in interface software.kes.enhancediterables.NonEmptyFiniteIterable<A>
        Returns:
        a Vector<A>

      • isEmpty

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

        Always returns false for NonEmptyVectors.

        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 Vector<A>
        Returns:
        always false

      • iterator

        default java.util.Iterator<A> iterator()
        Returns an iterator over this NonEmptyVector's elements.
        Specified by:
        iterator in interface java.lang.Iterable<A>
        Specified by:
        iterator in interface software.kes.enhancediterables.NonEmptyIterable<A>
        Specified by:
        iterator in interface Vector<A>
        Returns:
        an Iterator.

      • last

        default A last()
        Returns the last element.
        Specified by:
        last in interface software.kes.enhancediterables.NonEmptyFiniteIterable<A>
        Returns:
        an element of type A

      • reverse

        default NonEmptyVector<A> reverse()
        Creates a NonEmptyVector with this NonEmptyVector's elements in reversed order.

        Does not make copies of any underlying collections.

        Specified by:
        reverse in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        reverse in interface software.kes.enhancediterables.NonEmptyFiniteIterable<A>
        Specified by:
        reverse in interface Vector<A>
        Returns:
        a NonEmptyVector<A>

      • tail

        default Vector<A> tail()
        Returns the tail of this NonEmptyVector.

        The tail of a NonEmptyVector is the same Vector with the first element dropped. May be empty.

        Does not make copies of any underlying collections.

        Specified by:
        tail in interface software.kes.enhancediterables.NonEmptyFiniteIterable<A>
        Specified by:
        tail in interface software.kes.enhancediterables.NonEmptyIterable<A>
        Returns:
        a Vector<A>

      • toImmutable

        default ImmutableNonEmptyVector<A> toImmutable()
        Converts this NonEmptyVector to an ImmutableNonEmptyVector.

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

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

        Specified by:
        toImmutable in interface Vector<A>
        Returns:
        an ImmutableNonEmptyVector of the same type and containing the same elements

      • toNonEmpty

        default com.jnape.palatable.lambda.adt.Maybe<? extends NonEmptyVector<A>> toNonEmpty()
        Attempts to convert this Vector to a NonEmptyVector.

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

        Does not make copies of any underlying collections.

        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 Vector<A>
        Returns:
        this NonEmptyVector wrapped in a Maybe.just(A)

      • toNonEmptyOrThrow

        default NonEmptyVector<A> toNonEmptyOrThrow()
        Attempts to convert this Vector to a NonEmptyVector.

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

        Does not make copies of any underlying collections.

        Specified by:
        toNonEmptyOrThrow in interface Vector<A>
        Returns:
        this NonEmptyVector

      • zipWith

        default <B,​C> NonEmptyVector<C> zipWith​(com.jnape.palatable.lambda.functions.Fn2<A,​B,​C> fn,
                                              NonEmptyVector<B> other)
        Zips together this NonEmptyVector with another NonEmptyVector by applying a zipping function.

        Applies the function to the successive elements of of each NonEmptyVector until one of them runs out of elements.

        Does not make copies of any underlying collections.

        Type Parameters:
        B - The element type of the other NonEmptyVector
        C - The element type of the result
        Parameters:
        fn - The zipping function. Not null. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.
        other - The other NonEmptyVector
        Returns:
        A NonEmptyVector<C>

      • zipWithIndex

        default NonEmptyVector<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,​java.lang.Integer>> zipWithIndex()
        Zips this NonEmptyVector with its indices.

        Does not make copies of any underlying collections.

        Specified by:
        zipWithIndex in interface Vector<A>
        Returns:
        a new NonEmptyVector containing pairs consisting of all elements of this NonEmptyVector paired with their index. Indices start at 0.

      • of

        @SafeVarargs
static <A> ImmutableNonEmptyVector<A> of​(A first,
                                         A... more)
        Creates a ImmutableNonEmptyVector with the given elements.
        Type Parameters:
        A - the element type
        Parameters:
        first - the first element
        more - the remaining elements
        Returns:
        an ImmutableNonEmptyVector<A>

      • builder

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

      • builder

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

      • maybeWrap

        static <A> com.jnape.palatable.lambda.adt.Maybe<NonEmptyVector<A>> maybeWrap​(A[] underlying)
        Attempts to create a NonEmptyVector that wraps an array.

        Does not make any copies of the given array. The created NonEmptyVector will hold on to a reference to the array, but will never alter it in any way.

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

        Since no copy is made, be aware that anyone that holds a direct reference to the array can still mutate it. Use Vector.copyFrom(java.lang.Iterable<A>) instead if you want to avoid this situation.

        Type Parameters:
        A - the element type
        Parameters:
        underlying - the array to wrap; not null
        Returns:
        a NonEmptyVector<A> wrapped in a Maybe.just(A) if underlying is non-empty; Maybe.nothing() otherwise.

      • maybeWrap

        static <A> com.jnape.palatable.lambda.adt.Maybe<NonEmptyVector<A>> maybeWrap​(java.util.List<A> underlying)
        Attempts to create a NonEmptyVector that wraps a java.util.List.

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

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

        Since no copy is made, be aware that anyone that holds a direct reference to the List can still mutate it. Mutating the List is not advised. Operations that change the size of the underlying List 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.List to wrap; not null
        Returns:
        a NonEmptyVector<A> wrapped in a Maybe.just(A) if underlying is non-empty; Maybe.nothing() otherwise.

      • wrapOrThrow

        static <A> NonEmptyVector<A> wrapOrThrow​(A[] underlying)
        Attempts to create a NonEmptyVector that wraps an array. If it is not possible, throws an IllegalArgumentException.

        Does not make any copies of the given array. The created NonEmptyVector will hold on to a reference to the array, but will never alter it in any way.

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

        Since no copy is made, be aware that anyone that holds a direct reference to the array can still mutate it. Use copyFromOrThrow(Object[]) instead if you want to avoid this situation.

        Type Parameters:
        A - the element type
        Parameters:
        underlying - array to wrap; not null
        Returns:
        a NonEmptyVector<A> if underlying is non-empty; throws an IllegalArgumentException otherwise

      • wrapOrThrow

        static <A> NonEmptyVector<A> wrapOrThrow​(java.util.List<A> underlying)
        Attempts to create a NonEmptyVector that wraps a java.util.List. If it is not possible, throws an IllegalArgumentException.

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

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

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

        Type Parameters:
        A - the element type
        Parameters:
        underlying - List to wrap; not null
        Returns:
        a NonEmptyVector<A> if underlying is non-empty; throws an IllegalArgumentException otherwise

      • maybeCopyFrom

        static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptyVector<A>> maybeCopyFrom​(java.lang.Iterable<A> source)
        Attempts to create an ImmutableNonEmptyVector 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 ImmutableNonEmptyVector, 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 ImmutableNonEmptyVector<A> wrapped in a Maybe.just(A) if source is non-empty; Maybe.nothing() otherwise.

      • maybeCopyFrom

        static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptyVector<A>> maybeCopyFrom​(A[] source)
        Attempts to create an ImmutableNonEmptyVector 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 ImmutableNonEmptyVector<A> wrapped in a Maybe.just(A) if source is non-empty; Maybe.nothing() otherwise.

      • maybeCopyFrom

        static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptyVector<A>> maybeCopyFrom​(int maxCount,
                                                                                          java.lang.Iterable<A> source)
        Attempts to create an ImmutableNonEmptyVector 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 ImmutableVector and its size is less than or equal to maxCount, in which case it will be returned directly.

        If source is an ImmutableVector that is greater than maxCount in size, a copy will always be made, therefore making it memory-safe to take a small slice of a huge Vector that you no longer need.

        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 ImmutableNonEmptyVector<A> wrapped in a Maybe.just(A) if source is non-empty; Maybe.nothing() otherwise.

      • maybeCopyFrom

        static <A> com.jnape.palatable.lambda.adt.Maybe<ImmutableNonEmptyVector<A>> maybeCopyFrom​(int maxCount,
                                                                                          A[] source)
        Attempts to create an ImmutableNonEmptyVector 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 ImmutableNonEmptyVector<A> wrapped in a Maybe.just(A) if source is non-empty; Maybe.nothing() otherwise.

      • copyFromOrThrow

        static <A> ImmutableNonEmptyVector<A> copyFromOrThrow​(java.lang.Iterable<A> source)
        Attempts to create an ImmutableNonEmptyVector 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 ImmutableVector, 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 ImmutableNonEmptyVector<A>

      • copyFromOrThrow

        static <A> ImmutableNonEmptyVector<A> copyFromOrThrow​(A[] source)
        Attempts to create an ImmutableNonEmptyVector 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 ImmutableNonEmptyVector<A>

      • copyFromOrThrow

        static <A> ImmutableNonEmptyVector<A> copyFromOrThrow​(int maxCount,
                                                      java.lang.Iterable<A> source)
        Attempts to create an ImmutableNonEmptyVector 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 ImmutableVector and its size is less than or equal to maxCount, in which case it will be returned directly.

        If source is an ImmutableVector that is greater than maxCount in size, a copy will always be made, therefore making it memory-safe to take a small slice of a huge Vector that you no longer need.

        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 ImmutableNonEmptyVector<A>

      • copyFromOrThrow

        static <A> ImmutableNonEmptyVector<A> copyFromOrThrow​(int maxCount,
                                                      A[] source)
        Attempts to create an ImmutableNonEmptyVector 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 ImmutableNonEmptyVector<A>

      • fill

        static <A> ImmutableNonEmptyVector<A> fill​(int size,
                                           A value)
        Creates an ImmutableNonEmptyVector that repeats the same element size times.

        Uses O(1) memory.

        Type Parameters:
        A - the element type
        Parameters:
        size - the number of elements. Must be >= 1.
        value - the value that will be repeated all elements of the ImmutableNonEmptyVector
        Returns:
        an ImmutableVector<A> of size elements, with each element having the value value

      • lazyFill

        static <A> ImmutableNonEmptyVector<A> lazyFill​(int size,
                                               com.jnape.palatable.lambda.functions.Fn1<java.lang.Integer,​A> valueSupplier)
        Creates an ImmutableNonEmptyVector where elements are lazily evaluated.

        Uses O(1) memory.

        Type Parameters:
        A - the element type
        Parameters:
        size - the number of elements. Must be >= 1.
        valueSupplier - a function that accepts an index and returns the computed value for that index. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.
        Returns:
        an ImmutableNonEmptyVector<A>

      • nonEmptyCopyFrom

        static <A> ImmutableNonEmptyVector<A> nonEmptyCopyFrom​(software.kes.enhancediterables.NonEmptyIterable<A> source)
        Creates an ImmutableNonEmptyVector that is copied from any NonEmptyIterable.

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

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

        Type Parameters:
        A - the element type
        Parameters:
        source - a NonEmptyIterable<A> that will be iterated eagerly in its entirety; not null
        Returns:
        an ImmutableNonEmptyVector<A>

      • nonEmptyCopyFrom

        static <A> ImmutableNonEmptyVector<A> nonEmptyCopyFrom​(int maxCount,
                                                       software.kes.enhancediterables.NonEmptyIterable<A> source)
        Creates an ImmutableNonEmptyVector that is copied from any NonEmptyIterable, but consuming a maximum number of elements.

        The NonEmptyIterable 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 untransformed ImmutableNonEmptyVector and its size is less than or equal to maxCount, in which case it will be returned directly.

        If source is an ImmutableNonEmptyVector that is greater than maxCount in size, a copy will always be made, therefore making it memory-safe to take a small slice of a huge Vector that you no longer need.

        Type Parameters:
        A - the element type
        Parameters:
        maxCount - the maximum number of elements to consume from the source. Must be >= 1.
        source - a NonEmptyIterable<A> that will be iterated eagerly for up to maxCount elements. Not null. It is safe for source to be infinite.
        Returns:
        an ImmutableNonEmptyVector that contains at most maxCount elements

      • range

        static ImmutableNonEmptyVector<java.lang.Integer> range​(int size)
        Creates an ImmutableNonEmptyVector<Integer> containing elements 0..size - 1. In other words, each element of the returned Vector will contains its index.

        Uses O(1) memory.

        Parameters:
        size - the number of elements. Must be >= 1.
        Returns:
        an ImmutableNonEmptyVector<Integer>