Package software.kes.enhancediterables

Interface ImmutableIterable<A>

    • Method Summary

      All Methods Static Methods Instance Methods Default Methods 
      Modifier and Type Method Description
      default ImmutableNonEmptyIterable<A> append​(A element)
      Lazily appends an element to the end of this ImmutableIterable, yielding a new ImmutableNonEmptyIterable.
      default ImmutableIterable<A> concat​(ImmutableIterable<A> other)
      Lazily concatenates another ImmutableIterable to the end of this ImmutableIterable, yielding a new ImmutableIterable.
      default ImmutableNonEmptyIterable<A> concat​(ImmutableNonEmptyIterable<A> other)
      Lazily concatenates an ImmutableNonEmptyIterable to the end of this ImmutableIterable, yielding a new ImmutableNonEmptyIterable.
      static <A> ImmutableFiniteIterable<A> copyFrom​(int maxCount, java.lang.Iterable<A> source)
      Creates an ImmutableFiniteIterable by copying elements from an Iterable.
      static <A> ImmutableFiniteIterable<A> copyFrom​(java.util.Collection<A> source)
      Creates an ImmutableFiniteIterable by copying elements from a Collection.
      static <A> ImmutableFiniteIterable<A> copyFrom​(FiniteIterable<A> source)
      Creates an ImmutableFiniteIterable by copying elements from a FiniteIterable.
      default ImmutableIterable<A> drop​(int count)
      Returns a new ImmutableIterable that drops the first count elements of this ImmutableIterable.
      default ImmutableIterable<A> dropWhile​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
      Returns a new ImmutableIterable that skips the first contiguous group of elements of this ImmutableIterable that satisfy a predicate.
      static <A> ImmutableFiniteIterable<A> emptyImmutableIterable()
      Creates an empty ImmutableIterable.
      default ImmutableIterable<A> filter​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
      Returns a new ImmutableIterable that contains all elements of this ImmutableIterable that satisfy a predicate.
      default <B> ImmutableIterable<B> fmap​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends B> f)
      Returns a new ImmutableIterable by applying a function to all elements of this ImmutableIterable.
      default ImmutableIterable<A> intersperse​(A separator)
      Returns a new ImmutableIterable with the provided separator value injected between each value of this ImmutableIterable.
      default ImmutableIterable<? extends ImmutableNonEmptyIterable<A>> magnetizeBy​(com.jnape.palatable.lambda.functions.Fn2<A,​A,​java.lang.Boolean> predicate)
      Returns an Iterable of contiguous groups of elements in this ImmutableIterable that match a predicate pairwise.
      static <A> ImmutableNonEmptyFiniteIterable<A> of​(A first, A... more)
      Creates an ImmutableIterable containing the given elements.
      default <B,​C>
      com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends ImmutableIterable<B>,​? extends ImmutableIterable<C>>      		 partition​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends com.jnape.palatable.lambda.adt.coproduct.CoProduct2<B,​C,​?>> function)
      Partitions this ImmutableIterable given a disjoint mapping function.
      default ImmutableNonEmptyIterable<A> prepend​(A element)
      Lazily prepends an element to the front of this ImmutableIterable, yielding a new ImmutableNonEmptyIterable.
      default ImmutableIterable<A> prependAll​(A separator)
      Returns a new ImmutableIterable with the provided separator value injected before each value of this ImmutableIterable.
      static <A> ImmutableNonEmptyIterable<A> repeat​(A element)
      Returns an infinite ImmutableNonEmptyIterable that repeatedly iterates a given element.
      default ImmutableIterable<? extends ImmutableNonEmptyFiniteIterable<A>> slide​(int k)
      "Slides" a window of k elements across the ImmutableIterable by one element at a time.
      default com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends ImmutableIterable<A>,​? extends ImmutableIterable<A>> span​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
      Returns a Tuple2 where the first slot is the front contiguous elements of this ImmutableIterable matching a predicate and the second slot is all the remaining elements.
      default ImmutableNonEmptyIterable<? extends ImmutableIterable<A>> tails()
      Returns an ImmutableNonEmptyIterable containing all of the subsequences of tail elements of this ImmutableIterable, ordered by size, starting with the full list.
      default ImmutableFiniteIterable<A> take​(int count)
      Returns a new ImmutableFiniteIterable that takes the first count elements of this ImmutableIterable.
      default ImmutableIterable<A> takeWhile​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
      Returns a new ImmutableIterable that limits to the first contiguous group of elements of this FiniteIterable that satisfy a predicate.
      default com.jnape.palatable.lambda.adt.Maybe<? extends ImmutableFiniteIterable<A>> toFinite()
      Converts this ImmutableIterable to an ImmutableFiniteIterable if there is enough information to do so without iterating it.
      default com.jnape.palatable.lambda.adt.Maybe<? extends ImmutableNonEmptyIterable<A>> toNonEmpty()
      Converts this ImmutableIterable to a ImmutableNonEmptyIterable if it contains one or more elements.
      default <B,​C>
      ImmutableFiniteIterable<C>      		 zipWith​(com.jnape.palatable.lambda.functions.Fn2<A,​B,​C> fn, ImmutableFiniteIterable<B> other)
      Zips together this ImmutableIterable with an ImmutableFiniteIterable by applying a zipping function.
      default <B,​C>
      ImmutableIterable<C>      		 zipWith​(com.jnape.palatable.lambda.functions.Fn2<A,​B,​C> fn, ImmutableIterable<B> other)
      Zips together this ImmutableIterable with another ImmutableIterable by applying a zipping function.

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

        coerce

      • Methods inherited from interface java.lang.Iterable

        forEach, iterator, spliterator

    • Method Detail

      • append

        default ImmutableNonEmptyIterable<A> append​(A element)
        Lazily appends an element to the end of this ImmutableIterable, yielding a new ImmutableNonEmptyIterable.
        Specified by:
        append in interface EnhancedIterable<A>
        Parameters:
        element - the element to append
        Returns:
        a ImmutableNonEmptyIterable<A>

      • concat

        default ImmutableIterable<A> concat​(ImmutableIterable<A> other)
        Lazily concatenates another ImmutableIterable to the end of this ImmutableIterable, yielding a new ImmutableIterable.
        Parameters:
        other - the other ImmutableIterable
        Returns:
        an ImmutableIterable<A>

      • drop

        default ImmutableIterable<A> drop​(int count)
        Returns a new ImmutableIterable that drops the first count elements of this ImmutableIterable.
        Specified by:
        drop in interface EnhancedIterable<A>
        Parameters:
        count - the number of elements to drop from this ImmutableIterable. Must be >= 0. May exceed size of this ImmutableIterable, in which case, the result will be an empty ImmutableIterable.
        Returns:
        an ImmutableIterable<A>

      • dropWhile

        default ImmutableIterable<A> dropWhile​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
        Returns a new ImmutableIterable that skips the first contiguous group of elements of this ImmutableIterable that satisfy a predicate.

        Iteration begins at the first element for which the predicate evaluates to false.

        Specified by:
        dropWhile in interface EnhancedIterable<A>
        Parameters:
        predicate - a predicate; should be referentially transparent and not have side-effects
        Returns:
        a ImmutableIterable<A>

      • filter

        default ImmutableIterable<A> filter​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
        Returns a new ImmutableIterable that contains all elements of this ImmutableIterable that satisfy a predicate.
        Specified by:
        filter in interface EnhancedIterable<A>
        Parameters:
        predicate - a predicate; should be referentially transparent and not have side-effects
        Returns:
        a ImmutableIterable<A>

      • fmap

        default <B> ImmutableIterable<B> fmap​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends B> f)
        Returns a new ImmutableIterable by applying a function to all elements of this ImmutableIterable.
        Specified by:
        fmap in interface EnhancedIterable<A>
        Specified by:
        fmap in interface com.jnape.palatable.lambda.functor.Functor<A,​EnhancedIterable<?>>
        Type Parameters:
        B - the type returned by f
        Parameters:
        f - a function from A to B. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.
        Returns:
        a ImmutableIterable<B>

      • intersperse

        default ImmutableIterable<A> intersperse​(A separator)
        Returns a new ImmutableIterable with the provided separator value injected between each value of this ImmutableIterable.

        If this ImmutableIterable contains fewer than two elements, it is left untouched.

        Specified by:
        intersperse in interface EnhancedIterable<A>
        Parameters:
        separator - the separator value
        Returns:
        a ImmutableIterable<A>

      • magnetizeBy

        default ImmutableIterable<? extends ImmutableNonEmptyIterable<A>> magnetizeBy​(com.jnape.palatable.lambda.functions.Fn2<A,​A,​java.lang.Boolean> predicate)
        Returns an Iterable of contiguous groups of elements in this ImmutableIterable that match a predicate pairwise.
        Specified by:
        magnetizeBy in interface EnhancedIterable<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 ImmutableIterable<ImmutableNonEmptyIterable<A>> containing the contiguous groups

      • partition

        default <B,​C> com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends ImmutableIterable<B>,​? extends ImmutableIterable<C>> partition​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends com.jnape.palatable.lambda.adt.coproduct.CoProduct2<B,​C,​?>> function)
        Partitions this ImmutableIterable given a disjoint mapping function.

        Note that while the returned tuple must be constructed eagerly, the left and right iterables contained therein are both lazy, so comprehension over infinite iterables is supported.

        Specified by:
        partition in interface EnhancedIterable<A>
        Type Parameters:
        B - the output left Iterable element type, as well as the CoProduct2 A type
        C - the output right Iterable element type, as well as the CoProduct2 B type
        Parameters:
        function - the mapping function
        Returns:
        a Tuple2<ImmutableIterable&lt;B&gt;, ImmutableIterable&lt;C&gt;>

      • prepend

        default ImmutableNonEmptyIterable<A> prepend​(A element)
        Lazily prepends an element to the front of this ImmutableIterable, yielding a new ImmutableNonEmptyIterable.
        Specified by:
        prepend in interface EnhancedIterable<A>
        Parameters:
        element - the element to prepend
        Returns:
        an ImmutableNonEmptyIterable<A>

      • prependAll

        default ImmutableIterable<A> prependAll​(A separator)
        Returns a new ImmutableIterable with the provided separator value injected before each value of this ImmutableIterable.

        If this ImmutableIterable is empty, it is left untouched.

        Specified by:
        prependAll in interface EnhancedIterable<A>
        Parameters:
        separator - the separator value
        Returns:
        a ImmutableIterable<A>

      • slide

        default ImmutableIterable<? extends ImmutableNonEmptyFiniteIterable<A>> slide​(int k)
        "Slides" a window of k elements across the ImmutableIterable by one element at a time.

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

        Specified by:
        slide in interface EnhancedIterable<A>
        Parameters:
        k - the number of elements in the sliding window. Must be >= 1.
        Returns:
        an ImmutableIterable<ImmutableNonEmptyFiniteIterable<A>>

      • span

        default com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends ImmutableIterable<A>,​? extends ImmutableIterable<A>> span​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
        Returns a Tuple2 where the first slot is the front contiguous elements of this ImmutableIterable matching a predicate and the second slot is all the remaining elements.
        Specified by:
        span in interface EnhancedIterable<A>
        Parameters:
        predicate - a predicate; should be referentially transparent and not have side-effects
        Returns:
        a Tuple2<ImmutableIterable&lt;B&gt;, ImmutableIterable&lt;C&gt;>

      • tails

        default ImmutableNonEmptyIterable<? extends ImmutableIterable<A>> tails()
        Returns an ImmutableNonEmptyIterable containing all of the subsequences of tail elements of this ImmutableIterable, ordered by size, starting with the full list. Example: ImmutableIterable.of(1, 2, 3).tails(); // [[1, 2, 3], [2, 3], [3], []]
        Specified by:
        tails in interface EnhancedIterable<A>
        Returns:
        an ImmutableNonEmptyIterable<ImmutableIterable<A>>

      • take

        default ImmutableFiniteIterable<A> take​(int count)
        Returns a new ImmutableFiniteIterable that takes the first count elements of this ImmutableIterable.
        Specified by:
        take in interface EnhancedIterable<A>
        Parameters:
        count - the number of elements to take from this EnhancedIterable. Must be >= 0. May exceed size of this ImmutableIterable, in which case, the result will contain as many elements available.
        Returns:
        an ImmutableFiniteIterable<A>

      • takeWhile

        default ImmutableIterable<A> takeWhile​(com.jnape.palatable.lambda.functions.Fn1<? super A,​? extends java.lang.Boolean> predicate)
        Returns a new ImmutableIterable that limits to the first contiguous group of elements of this FiniteIterable that satisfy a predicate.

        Iteration ends at, but does not include, the first element for which the predicate evaluates to false.

        Specified by:
        takeWhile in interface EnhancedIterable<A>
        Parameters:
        predicate - a predicate; should be referentially transparent and not have side-effects
        Returns:
        a ImmutableIterable<A>

      • toFinite

        default com.jnape.palatable.lambda.adt.Maybe<? extends ImmutableFiniteIterable<A>> toFinite()
        Converts this ImmutableIterable to an ImmutableFiniteIterable if there is enough information to do so without iterating it.

        Note that if this method returns nothing(), it does NOT necessarily mean this ImmutableIterable is infinite.

        Specified by:
        toFinite in interface EnhancedIterable<A>
        Returns:
        a Maybe<ImmutableFiniteIterable<A>

      • toNonEmpty

        default com.jnape.palatable.lambda.adt.Maybe<? extends ImmutableNonEmptyIterable<A>> toNonEmpty()
        Converts this ImmutableIterable to a ImmutableNonEmptyIterable if it contains one or more elements.
        Specified by:
        toNonEmpty in interface EnhancedIterable<A>
        Returns:
        a Maybe<ImmutableNonEmptyIterable<A>

      • zipWith

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

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

        Type Parameters:
        B - the element type of the other Iterable
        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 Iterable
        Returns:
        an ImmutableIterable<C>

      • zipWith

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

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

        Type Parameters:
        B - the element type of the other Iterable
        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 Iterable
        Returns:
        an ImmutableFiniteIterable<C>

      • copyFrom

        static <A> ImmutableFiniteIterable<A> copyFrom​(FiniteIterable<A> source)
        Creates an ImmutableFiniteIterable by copying elements from a FiniteIterable.

        If source is already an ImmutableFiniteIterable, this method will return it without copying.

        Type Parameters:
        A - the element type
        Parameters:
        source - the source to copy from
        Returns:
        an ImmutableFiniteIterable<A>

      • copyFrom

        static <A> ImmutableFiniteIterable<A> copyFrom​(java.util.Collection<A> source)
        Creates an ImmutableFiniteIterable by copying elements from a Collection.
        Type Parameters:
        A - the element type
        Parameters:
        source - the source to copy from
        Returns:
        an ImmutableFiniteIterable<A>

      • copyFrom

        static <A> ImmutableFiniteIterable<A> copyFrom​(int maxCount,
                                               java.lang.Iterable<A> source)
        Creates an ImmutableFiniteIterable by copying elements from an Iterable.

        If source is already an ImmutableIterable, no copying will be performed.

        Type Parameters:
        A - the element type
        Parameters:
        maxCount - the maximum number of elements to take from the supplied Iterable. Must be >= 0. May exceed size of the Iterable, in which case, the result will contain as many elements available.
        source - the source to copy from
        Returns:
        an ImmutableFiniteIterable<A>

      • emptyImmutableIterable

        static <A> ImmutableFiniteIterable<A> emptyImmutableIterable()
        Creates an empty ImmutableIterable.
        Type Parameters:
        A - the element type
        Returns:
        an ImmutableFiniteIterable<A>

      • of

        @SafeVarargs
static <A> ImmutableNonEmptyFiniteIterable<A> of​(A first,
                                                 A... more)
        Creates an ImmutableIterable containing the given elements.

        Note that this method actually returns an ImmutableNonEmptyFiniteIterable, which is also an ImmutableIterable.

        Type Parameters:
        A - the element type
        Parameters:
        first - the first element
        more - the remaining elements
        Returns:
        an ImmutableNonEmptyFiniteIterable<A>

      • repeat

        static <A> ImmutableNonEmptyIterable<A> repeat​(A element)
        Returns an infinite ImmutableNonEmptyIterable that repeatedly iterates a given element.
        Type Parameters:
        A - the element type
        Parameters:
        element - the value to repeat
        Returns:
        an ImmutableNonEmptyIterable<A>