Package software.kes.collectionviews

Interface ImmutableVector<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<?>>, Immutable, software.kes.enhancediterables.ImmutableFiniteIterable<A>, software.kes.enhancediterables.ImmutableIterable<A>, java.lang.Iterable<A>, java.util.RandomAccess, Vector<A>
    All Known Subinterfaces:
    ImmutableNonEmptyVector<A>
    public interface ImmutableVector<A>
extends Vector<A>, software.kes.enhancediterables.ImmutableFiniteIterable<A>, Immutable
    A Vector that is guaranteed at compile-time to be safe from mutation anywhere. In other words, it owns the sole reference to the underlying collection.

    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> VectorBuilder<A> builder()
      Creates a new VectorBuilder.
      static <A> VectorBuilder<A> builder​(int initialCapacity)
      Creates a new VectorBuilder with an initial capacity hint.
      default <B> ImmutableVector<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,​B>> cross​(ImmutableVector<B> other)
      Returns the cartesian product of this ImmutableVector with another ImmutableVector.
      default ImmutableVector<A> drop​(int count)
      Returns a new ImmutableVector that drops the first count elements of this ImmutableVector.
      default ImmutableVector<A> dropRight​(int count)
      Returns a new ImmutableVector that drops all except the last count elements of this ImmutableVector.
      default ImmutableVector<A> dropWhile​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
      Returns a new ImmutableVector that drops longest prefix of elements of this ImmutableVector that satisfy a predicate.
      default <B> ImmutableVector<B> fmap​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends B> f)
      Maps a function over this ImmutableVector.
      default software.kes.enhancediterables.ImmutableNonEmptyFiniteIterable<? extends ImmutableVector<A>> inits()
      Returns a NonEmptyIterable containing the inits of this ImmutableVector.
      default software.kes.enhancediterables.ImmutableFiniteIterable<? extends ImmutableNonEmptyVector<A>> magnetizeBy​(com.jnape.palatable.lambda.functions.Fn2<A,​A,​java.lang.Boolean> predicate)
      Returns an ImmutableFiniteIterable of contiguous groups of elements in this ImmutableVector that match a predicate pairwise.
      default ImmutableVector<A> reverse()
      Creates an ImmutableVector with this ImmutableVector's elements in reversed order.
      default ImmutableVector<A> slice​(int startIndex, int endIndexExclusive)
      Creates a slice of this ImmutableVector.
      default software.kes.enhancediterables.ImmutableFiniteIterable<? extends ImmutableNonEmptyVector<A>> slide​(int k)
      "Slides" a window of k elements across the ImmutableVector by one element at a time.
      default com.jnape.palatable.lambda.adt.hlist.Tuple2<ImmutableVector<A>,​ImmutableVector<A>> span​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
      Splits this ImmutableVector into a prefix/suffix pair according to a predicate.
      default com.jnape.palatable.lambda.adt.hlist.Tuple2<ImmutableVector<A>,​ImmutableVector<A>> splitAt​(int index)
      Splits this ImmutableVector into two at a given position.
      default software.kes.enhancediterables.ImmutableNonEmptyFiniteIterable<ImmutableVector<A>> tails()
      Returns a NonEmptyIterable containing the tails of this ImmutableVector.
      default ImmutableVector<A> take​(int count)
      Returns a new ImmutableVector containing at most the first count elements of this ImmutableVector.
      default ImmutableVector<A> takeRight​(int count)
      Returns a new ImmutableVector containing at most the last count elements of this ImmutableVector.
      default ImmutableVector<A> takeWhile​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
      Returns a new ImmutableVector containing the longest prefix of elements this ImmutableVector that satisfy a predicate.
      default ImmutableVector<A> toImmutable()
      Returns an ImmutableVector containing the same elements as this one.
      default com.jnape.palatable.lambda.adt.Maybe<? extends ImmutableNonEmptyVector<A>> toNonEmpty()
      Attempts to convert this ImmutableVector to an ImmutableNonEmptyVector.
      default ImmutableNonEmptyVector<A> toNonEmptyOrThrow()
      Attempts to convert this ImmutableVector to an ImmutableNonEmptyVector.
      default <B,​C>
      ImmutableVector<C>      		 zipWith​(com.jnape.palatable.lambda.functions.Fn2<A,​B,​C> fn, ImmutableVector<B> other)
      Zips together this ImmutableVector with another ImmutableVector by applying a zipping function.
      default ImmutableVector<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,​java.lang.Integer>> zipWithIndex()
      Zips this ImmutableVector with its indices.

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

        concat, concat, find, toArray, toCollection, zipWith, zipWith

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

        append, concat, concat, concat, cross, cross, filter, foldLeft, foldRight, intersperse, partition, prepend, prependAll, toFinite, zipWith

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

        coerce

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

        append, concat, concat, cross, cycle, distinct, filter, intersperse, partition, prepend, prependAll, toFinite, zipWith

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

        concat, concat, zipWith

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Method Detail

      • cross

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

        Does not make copies of any underlying collections.

        The returned ImmutableVector 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 ImmutableVector
        Parameters:
        other - an ImmutableVector of any type
        Returns:
        a ImmutableVector<Tuple2<A, B>>

      • drop

        default ImmutableVector<A> drop​(int count)
        Returns a new ImmutableVector that drops the first count elements of this ImmutableVector.

        Does not make copies of any underlying collections.

        Use caution when taking a small slice of a huge ImmutableVector that you no longer need. The smaller slice will hold onto a reference of the larger one, and will prevent it from being GC'ed.

        Specified by:
        drop in interface software.kes.enhancediterables.EnhancedIterable<A>
        Specified by:
        drop in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        drop in interface software.kes.enhancediterables.ImmutableFiniteIterable<A>
        Specified by:
        drop in interface software.kes.enhancediterables.ImmutableIterable<A>
        Specified by:
        drop in interface Vector<A>
        Parameters:
        count - the number of elements to drop from this ImmutableVector. Must be >= 0. May exceed size of this ImmutableVector, in which case, the result will be an empty ImmutableVector.
        Returns:
        an ImmutableVector<A>

      • dropRight

        default ImmutableVector<A> dropRight​(int count)
        Returns a new ImmutableVector that drops all except the last count elements of this ImmutableVector.

        Does not make copies of any underlying collections.

        Use caution when taking a small slice of a huge Vector that you no longer need. The smaller slice will hold onto a reference of the larger one, and will prevent it from being GC'ed.

        Specified by:
        dropRight in interface Vector<A>
        Parameters:
        count - the number of elements to drop from the end of this ImmutableVector. Must be >= 0. May exceed size of this ImmutableVector, in which case, the result will be an empty ImmutableVector.
        Returns:
        a ImmutableVector<A>

      • dropWhile

        default ImmutableVector<A> dropWhile​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
        Returns a new ImmutableVector that drops longest prefix of elements of this ImmutableVector that satisfy a predicate.

        Does not make copies of any underlying collections.

        Specified by:
        dropWhile in interface software.kes.enhancediterables.EnhancedIterable<A>
        Specified by:
        dropWhile in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        dropWhile in interface software.kes.enhancediterables.ImmutableFiniteIterable<A>
        Specified by:
        dropWhile in interface software.kes.enhancediterables.ImmutableIterable<A>
        Parameters:
        predicate - a predicate; 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:
        an ImmutableVector<A>

      • fmap

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

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

        Does not make any copies of underlying collections.

        This method is stack-safe, so a ImmutableVector 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.ImmutableFiniteIterable<A>
        Specified by:
        fmap in interface software.kes.enhancediterables.ImmutableIterable<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:
        an ImmutableVector<B> of the same size

      • inits

        default software.kes.enhancediterables.ImmutableNonEmptyFiniteIterable<? extends ImmutableVector<A>> inits()
        Returns a NonEmptyIterable containing the inits of this ImmutableVector.

        The first value will be this ImmutableVector and the final one will be an empty Vector, with the intervening values the results of successive applications of init.

        Specified by:
        inits in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        inits in interface software.kes.enhancediterables.ImmutableFiniteIterable<A>
        Specified by:
        inits in interface Vector<A>
        Returns:
        a NonEmptyIterable over all the inits of this ImmutableVector

      • magnetizeBy

        default software.kes.enhancediterables.ImmutableFiniteIterable<? extends ImmutableNonEmptyVector<A>> magnetizeBy​(com.jnape.palatable.lambda.functions.Fn2<A,​A,​java.lang.Boolean> predicate)
        Returns an ImmutableFiniteIterable of contiguous groups of elements in this ImmutableVector that match a predicate pairwise.
        Specified by:
        magnetizeBy in interface software.kes.enhancediterables.EnhancedIterable<A>
        Specified by:
        magnetizeBy in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        magnetizeBy in interface software.kes.enhancediterables.ImmutableFiniteIterable<A>
        Specified by:
        magnetizeBy in interface software.kes.enhancediterables.ImmutableIterable<A>
        Parameters:
        predicate - the predicate function. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.
        Returns:
        an ImmutableFiniteIterable<ImmutableNonEmptyVector<A>> containing the contiguous groups

      • reverse

        default ImmutableVector<A> reverse()
        Creates an ImmutableVector with this ImmutableVector'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.ImmutableFiniteIterable<A>
        Specified by:
        reverse in interface Vector<A>
        Returns:
        an ImmutableVector<A>

      • slice

        default ImmutableVector<A> slice​(int startIndex,
                                 int endIndexExclusive)
        Creates a slice of this ImmutableVector.

        Does not make copies of any underlying collections.

        Use caution when taking a small slice of a huge ImmutableVector that you no longer need. The smaller slice will hold onto a reference of the larger one, and will prevent it from being GC'ed. To avoid this situation, use Vector.copySliceFrom(int, int, java.lang.Iterable<A>) instead.

        Specified by:
        slice in interface Vector<A>
        Parameters:
        startIndex - the index of the element to begin the slice. Must be >= 0. May exceed the size of this ImmutableVector, in which case an empty ImmutableVector will be returned.
        endIndexExclusive - the end index (exclusive) of the slice. Must be >= startIndex. May exceed the size of this ImmutableVector, in which case the slice will contain as many elements as available.
        Returns:
        an ImmutableVector<A>

      • slide

        default software.kes.enhancediterables.ImmutableFiniteIterable<? extends ImmutableNonEmptyVector<A>> slide​(int k)
        "Slides" a window of k elements across the ImmutableVector by one element at a time.

        Example: Vector.of(1, 2, 3, 4, 5).slide(2); // [[1, 2], [2, 3], [3, 4], [4, 5]]

        Specified by:
        slide in interface software.kes.enhancediterables.EnhancedIterable<A>
        Specified by:
        slide in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        slide in interface software.kes.enhancediterables.ImmutableFiniteIterable<A>
        Specified by:
        slide in interface software.kes.enhancediterables.ImmutableIterable<A>
        Specified by:
        slide in interface Vector<A>
        Parameters:
        k - the number of elements in the sliding window. Must be >= 1.
        Returns:
        an FiniteIterable<ImmutableNonEmptyVector<A>>

      • span

        default com.jnape.palatable.lambda.adt.hlist.Tuple2<ImmutableVector<A>,​ImmutableVector<A>> span​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
        Splits this ImmutableVector into a prefix/suffix pair according to a predicate.

        Does not make copies of any underlying collections.

        Note that vector.span(p) is equivalent to, but possibly more efficient than tuple(vector.takeWhile(p), vector.dropWhile(p))

        Specified by:
        span in interface software.kes.enhancediterables.EnhancedIterable<A>
        Specified by:
        span in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        span in interface software.kes.enhancediterables.ImmutableFiniteIterable<A>
        Specified by:
        span in interface software.kes.enhancediterables.ImmutableIterable<A>
        Parameters:
        predicate - a predicate; 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 Tuple2 contains of ImmutableVectors, one of which containing the first index elements that satisfied the predicate, the second containing the other elements.

      • splitAt

        default com.jnape.palatable.lambda.adt.hlist.Tuple2<ImmutableVector<A>,​ImmutableVector<A>> splitAt​(int index)
        Splits this ImmutableVector into two at a given position.

        Does not make copies of any underlying collections.

        Note that vector.splitAt(n) is equivalent to, but possibly more efficient than tuple(vector.take(n), vector.drop(n))

        Specified by:
        splitAt in interface Vector<A>
        Parameters:
        index - the position at which to split. Must be >= 0;
        Returns:
        a Tuple2 contains of ImmutableVectors, one of which containing the first index elements, the second containing the other elements.

      • tails

        default software.kes.enhancediterables.ImmutableNonEmptyFiniteIterable<ImmutableVector<A>> tails()
        Returns a NonEmptyIterable containing the tails of this ImmutableVector.

        The first value will be this ImmutableVector and the final one will be an empty ImmutableVector, with the intervening values the results of successive applications of tail.

        Specified by:
        tails in interface software.kes.enhancediterables.EnhancedIterable<A>
        Specified by:
        tails in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        tails in interface software.kes.enhancediterables.ImmutableFiniteIterable<A>
        Specified by:
        tails in interface software.kes.enhancediterables.ImmutableIterable<A>
        Specified by:
        tails in interface Vector<A>
        Returns:
        a NonEmptyIterable over all the tails of this ImmutableVector

      • take

        default ImmutableVector<A> take​(int count)
        Returns a new ImmutableVector containing at most the first count elements of this ImmutableVector.

        Does not make copies of any underlying collections.

        Use caution when taking a small slice of a huge ImmutableVector that you no longer need. The smaller slice will hold onto a reference of the larger one, and will prevent it from being GC'ed. To avoid this situation, use Vector.copyFrom(int, Iterable) instead.

        Specified by:
        take in interface software.kes.enhancediterables.EnhancedIterable<A>
        Specified by:
        take in interface software.kes.enhancediterables.ImmutableIterable<A>
        Specified by:
        take in interface Vector<A>
        Parameters:
        count - the maximum number of elements to take from this ImmutableVector. Must be >= 0. May exceed size of this ImmutableVector.
        Returns:
        an ImmutableVector<A>

      • takeRight

        default ImmutableVector<A> takeRight​(int count)
        Returns a new ImmutableVector containing at most the last count elements of this ImmutableVector.

        Does not make copies of any underlying collections.

        Use caution when taking a small slice of a huge ImmutableVector that you no longer need. The smaller slice will hold onto a reference of the larger one, and will prevent it from being GC'ed. To avoid this situation, use Vector.copyFrom(int, Iterable) instead.

        Specified by:
        takeRight in interface Vector<A>
        Parameters:
        count - the maximum number of elements to take from this ImmutableVector. Must be >= 0. May exceed size of this Vector.
        Returns:
        an ImmutableVector<A>

      • takeWhile

        default ImmutableVector<A> takeWhile​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
        Returns a new ImmutableVector containing the longest prefix of elements this ImmutableVector that satisfy a predicate.

        Does not make copies of any underlying collections.

        Specified by:
        takeWhile in interface software.kes.enhancediterables.EnhancedIterable<A>
        Specified by:
        takeWhile in interface software.kes.enhancediterables.FiniteIterable<A>
        Specified by:
        takeWhile in interface software.kes.enhancediterables.ImmutableFiniteIterable<A>
        Specified by:
        takeWhile in interface software.kes.enhancediterables.ImmutableIterable<A>
        Parameters:
        predicate - a predicate; 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:
        an ImmutableVector<A>

      • toImmutable

        default ImmutableVector<A> toImmutable()
        Returns an ImmutableVector containing the same elements as this one.

        Since this is an ImmutableVector already, this method simply returns itself.

        Specified by:
        toImmutable in interface Vector<A>
        Returns:
        itself

      • toNonEmpty

        default com.jnape.palatable.lambda.adt.Maybe<? extends ImmutableNonEmptyVector<A>> toNonEmpty()
        Attempts to convert this ImmutableVector to an ImmutableNonEmptyVector.

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

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

        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.ImmutableFiniteIterable<A>
        Specified by:
        toNonEmpty in interface software.kes.enhancediterables.ImmutableIterable<A>
        Specified by:
        toNonEmpty in interface Vector<A>
        Returns:
        a Maybe<ImmutableNonEmptyVector<A>>

      • toNonEmptyOrThrow

        default ImmutableNonEmptyVector<A> toNonEmptyOrThrow()
        Attempts to convert this ImmutableVector to an ImmutableNonEmptyVector.

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

        If this ImmutableVector is empty, throws an IllegalArgumentException.

        Does not make copies of any underlying collections.

        Specified by:
        toNonEmptyOrThrow in interface Vector<A>
        Returns:
        an ImmutableNonEmptyVector<A>
        Throws:
        java.lang.IllegalArgumentException - if this ImmutableVector is empty

      • zipWith

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

        Applies the function to the successive elements of of each ImmutableVector 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 ImmutableVector
        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 ImmutableVector
        Returns:
        An ImmutableVector<C>

      • zipWithIndex

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

        Does not make copies of any underlying collections.

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

      • builder

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

      • builder

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