Package fj.data

Class Zipper<A>

  • All Implemented Interfaces:
    java.lang.Iterable<Zipper<A>>

    public final class Zipper<A>
    extends java.lang.Object
    implements java.lang.Iterable<Zipper<A>>
    Provides a pointed stream, which is a non-empty zipper-like stream structure that tracks an index (focus) position in a stream. Focus can be moved forward and backwards through the stream, elements can be inserted before or after the focused position, and the focused item can be deleted.

    Based on the pointedlist library by Jeff Wheeler.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Zipper​(Stream<A> left, A focus, Stream<A> right)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean atEnd()
      Returns whether the focus is on the last element.
      boolean atStart()
      Returns whether the focus is on the first element.
      <B> Zipper<B> cobind​(F<Zipper<A>,​B> f)
      Maps over variations of this zipper, such that the given function is applied to each variation (comonad pattern).
      Zipper<A> cycleNext()
      Move the focus to the next element.
      Zipper<A> cyclePrevious()
      Move the focus to the previous element.
      Option<Zipper<A>> deleteLeft()
      Possibly deletes the element at the focus, then moves the element on the left into focus.
      Option<Zipper<A>> deleteLeftCycle()
      Possibly deletes the element at the focus, then move the element on the left into focus.
      Zipper<A> deleteOthers()
      Deletes all elements in the zipper except the focus.
      Option<Zipper<A>> deleteRight()
      Possibly deletes the element at the focus, then moves the element on the right into focus.
      Option<Zipper<A>> deleteRightCycle()
      Possibly deletes the element at the focus, then move the element on the right into focus.
      static <A> Equal<Zipper<A>> eq​(Equal<A> e)
      An Equal instance for Zippers.
      boolean equals​(java.lang.Object other)  
      Option<Zipper<A>> find​(F<A,​java.lang.Boolean> p)
      Moves the focus to the element matching the given predicate, if present.
      A focus()
      Returns the focus element of this zipper.
      <B> B foldRight​(F<A,​F<B,​B>> f, B z)
      Performs a right-fold reduction across this zipper.
      static <A> Option<Zipper<A>> fromStream​(Stream<A> a)
      Possibly create a zipper if the provided stream has at least one element, otherwise None.
      static <A> Option<Zipper<A>> fromStreamEnd​(Stream<A> a)
      Possibly create a zipper if the provided stream has at least one element, otherwise None.
      int hashCode()  
      int index()
      Returns the index of the focus.
      Zipper<A> insertLeft​(A a)
      Inserts an element to the left of the focus, then moves the focus to the new element.
      Zipper<A> insertRight​(A a)
      Inserts an element to the right of the focus, then moves the focus to the new element.
      java.util.Iterator<Zipper<A>> iterator()
      Returns an iterator of all the positions of this Zipper, starting from the leftmost position.
      Stream<A> lefts()
      Returns a Stream of the elements to the left of focus.
      int length()
      Returns the length of this zipper.
      <B> Zipper<B> map​(F<A,​B> f)
      Maps the given function across the elements of this zipper (covariant functor pattern).
      static <A> F<java.lang.Integer,​F<Zipper<A>,​Option<Zipper<A>>>> move()
      A first-class version of the move function.
      Option<Zipper<A>> move​(int n)
      Move the focus to the specified index.
      Option<Zipper<A>> next()
      Possibly moves the focus to the next element in the list.
      static <A> F<Zipper<A>,​Option<Zipper<A>>> next_()
      First-class version of the next() function.
      static <A> Ord<Zipper<A>> ord​(Ord<A> o)
      An Ord instance for Zippers.
      P3<Stream<A>,​A,​Stream<A>> p()
      Returns the product-3 representation of this Zipper.
      static <A> F<Zipper<A>,​P3<Stream<A>,​A,​Stream<A>>> p_()
      A first-class function that yields the product-3 representation of a given Zipper.
      Zipper<Zipper<A>> positions()
      Creates a zipper of variations of this zipper, in which each element is focused, with this zipper as the focus of the zipper of zippers (comonad pattern).
      Option<Zipper<A>> previous()
      Possibly moves the focus to the previous element in the list.
      static <A> F<Zipper<A>,​Option<Zipper<A>>> previous_()
      First-class version of the previous() function.
      Zipper<A> replace​(A a)
      Replaces the element in focus with the given element.
      Stream<A> rights()
      Returns a Stream of the elements to the right of focus.
      static <A> Show<Zipper<A>> show​(Show<A> s)
      A Show instance for Zippers.
      static <A> Zipper<A> single​(A a)
      Creates a new zipper with a single element.
      Stream<A> toStream()
      Returns the Stream representation of this zipper.
      Zipper<A> tryNext()
      Attempts to move the focus to the next element, or throws an error if there are no more elements.
      Zipper<A> tryPrevious()
      Attempts to move the focus to the previous element, or throws an error if there are no more elements.
      static <A> F3<Stream<A>,​A,​Stream<A>,​Zipper<A>> zipper()
      First-class constructor of zippers.
      static <A> Zipper<A> zipper​(Stream<A> left, A focus, Stream<A> right)
      Creates a new Zipper with the given streams before and after the focus, and the given focused item.
      static <A> Zipper<A> zipper​(P3<Stream<A>,​A,​Stream<A>> p)
      Creates a new Zipper from the given triple.
      <B,​C>
      Zipper<C>
      zipWith​(Zipper<B> bs, F<A,​F<B,​C>> f)
      Zips this Zipper with another, applying the given function lock-step over both zippers in both directions.
      <B,​C>
      Zipper<C>
      zipWith​(Zipper<B> bs, F2<A,​B,​C> f)
      Zips this Zipper with another, applying the given function lock-step over both zippers in both directions.
      Zipper<P2<A,​java.lang.Boolean>> zipWithFocus()
      Zips the elements of this zipper with a boolean that indicates whether that element has focus.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
    • Field Detail

      • left

        private final Stream<A> left
      • focus

        private final A focus
      • right

        private final Stream<A> right
    • Constructor Detail

    • Method Detail

      • zipper

        public static <A> Zipper<A> zipper​(Stream<A> left,
                                           A focus,
                                           Stream<A> right)
        Creates a new Zipper with the given streams before and after the focus, and the given focused item.
        Parameters:
        left - The stream of elements before the focus.
        focus - The element under focus.
        right - The stream of elements after the focus.
        Returns:
        a new Zipper with the given streams before and after the focus, and the given focused item.
      • zipper

        public static <A> Zipper<A> zipper​(P3<Stream<A>,​A,​Stream<A>> p)
        Creates a new Zipper from the given triple.
        Parameters:
        p - A triple of the elements before the focus, the focus element, and the elements after the focus, respectively.
        Returns:
        a new Zipper created from the given triple.
      • zipper

        public static <A> F3<Stream<A>,​A,​Stream<A>,​Zipper<A>> zipper()
        First-class constructor of zippers.
        Returns:
        A function that yields a new zipper given streams on the left and right and a focus element.
      • p

        public P3<Stream<A>,​A,​Stream<A>> p()
        Returns the product-3 representation of this Zipper.
        Returns:
        the product-3 representation of this Zipper.
      • p_

        public static <A> F<Zipper<A>,​P3<Stream<A>,​A,​Stream<A>>> p_()
        A first-class function that yields the product-3 representation of a given Zipper.
        Returns:
        A first-class function that yields the product-3 representation of a given Zipper.
      • ord

        public static <A> Ord<Zipper<A>> ord​(Ord<A> o)
        An Ord instance for Zippers.
        Parameters:
        o - An Ord instance for the element type.
        Returns:
        An Ord instance for Zippers.
      • equals

        public final boolean equals​(java.lang.Object other)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • eq

        public static <A> Equal<Zipper<A>> eq​(Equal<A> e)
        An Equal instance for Zippers.
        Parameters:
        e - An Equal instance for the element type.
        Returns:
        An Equal instance for Zippers.
      • show

        public static <A> Show<Zipper<A>> show​(Show<A> s)
        A Show instance for Zippers.
        Parameters:
        s - A Show instance for the element type.
        Returns:
        A Show instance for Zippers.
      • map

        public <B> Zipper<B> map​(F<A,​B> f)
        Maps the given function across the elements of this zipper (covariant functor pattern).
        Parameters:
        f - A function to map across this zipper.
        Returns:
        A new zipper with the given function applied to all elements.
      • foldRight

        public <B> B foldRight​(F<A,​F<B,​B>> f,
                               B z)
        Performs a right-fold reduction across this zipper.
        Parameters:
        f - The function to apply on each element of this zipper.
        z - The beginning value to start the application from.
        Returns:
        the final result after the right-fold reduction.
      • single

        public static <A> Zipper<A> single​(A a)
        Creates a new zipper with a single element.
        Parameters:
        a - The focus element of the new zipper.
        Returns:
        a new zipper with a single element which is in focus.
      • fromStream

        public static <A> Option<Zipper<A>> fromStream​(Stream<A> a)
        Possibly create a zipper if the provided stream has at least one element, otherwise None. The provided stream's head will be the focus of the zipper, and the rest of the stream will follow on the right side.
        Parameters:
        a - The stream from which to create a zipper.
        Returns:
        a new zipper if the provided stream has at least one element, otherwise None.
      • fromStreamEnd

        public static <A> Option<Zipper<A>> fromStreamEnd​(Stream<A> a)
        Possibly create a zipper if the provided stream has at least one element, otherwise None. The provided stream's last element will be the focus of the zipper, following the rest of the stream in order, to the left.
        Parameters:
        a - The stream from which to create a zipper.
        Returns:
        a new zipper if the provided stream has at least one element, otherwise None.
      • focus

        public A focus()
        Returns the focus element of this zipper.
        Returns:
        the focus element of this zipper.
      • next

        public Option<Zipper<A>> next()
        Possibly moves the focus to the next element in the list.
        Returns:
        An optional zipper with the focus moved one element to the right, if there are elements to the right of focus, otherwise None.
      • tryNext

        public Zipper<A> tryNext()
        Attempts to move the focus to the next element, or throws an error if there are no more elements.
        Returns:
        A zipper with the focus moved one element to the right, if there are elements to the right of focus, otherwise throws an error.
      • previous

        public Option<Zipper<A>> previous()
        Possibly moves the focus to the previous element in the list.
        Returns:
        An optional zipper with the focus moved one element to the left, if there are elements to the left of focus, otherwise None.
      • tryPrevious

        public Zipper<A> tryPrevious()
        Attempts to move the focus to the previous element, or throws an error if there are no more elements.
        Returns:
        A zipper with the focus moved one element to the left, if there are elements to the left of focus, otherwise throws an error.
      • next_

        public static <A> F<Zipper<A>,​Option<Zipper<A>>> next_()
        First-class version of the next() function.
        Returns:
        A function that moves the given zipper's focus to the next element.
      • previous_

        public static <A> F<Zipper<A>,​Option<Zipper<A>>> previous_()
        First-class version of the previous() function.
        Returns:
        A function that moves the given zipper's focus to the previous element.
      • insertLeft

        public Zipper<A> insertLeft​(A a)
        Inserts an element to the left of the focus, then moves the focus to the new element.
        Parameters:
        a - A new element to insert into this zipper.
        Returns:
        A new zipper with the given element in focus, and the current focus element on its right.
      • insertRight

        public Zipper<A> insertRight​(A a)
        Inserts an element to the right of the focus, then moves the focus to the new element.
        Parameters:
        a - A new element to insert into this zipper.
        Returns:
        A new zipper with the given element in focus, and the current focus element on its left.
      • deleteLeft

        public Option<Zipper<A>> deleteLeft()
        Possibly deletes the element at the focus, then moves the element on the left into focus. If no element is on the left, focus on the element to the right. Returns None if the focus element is the only element in this zipper.
        Returns:
        A new zipper with this zipper's focus element removed, or None if deleting the focus element would cause the zipper to be empty.
      • deleteRight

        public Option<Zipper<A>> deleteRight()
        Possibly deletes the element at the focus, then moves the element on the right into focus. If no element is on the right, focus on the element to the left. Returns None if the focus element is the only element in this zipper.
        Returns:
        A new zipper with this zipper's focus element removed, or None if deleting the focus element would cause the zipper to be empty.
      • deleteOthers

        public Zipper<A> deleteOthers()
        Deletes all elements in the zipper except the focus.
        Returns:
        A new zipper with the focus element as the only element.
      • length

        public int length()
        Returns the length of this zipper.
        Returns:
        the length of this zipper.
      • atStart

        public boolean atStart()
        Returns whether the focus is on the first element.
        Returns:
        true if the focus is on the first element, otherwise false.
      • atEnd

        public boolean atEnd()
        Returns whether the focus is on the last element.
        Returns:
        true if the focus is on the last element, otherwise false.
      • positions

        public Zipper<Zipper<A>> positions()
        Creates a zipper of variations of this zipper, in which each element is focused, with this zipper as the focus of the zipper of zippers (comonad pattern).
        Returns:
        a zipper of variations of the provided zipper, in which each element is focused, with this zipper as the focus of the zipper of zippers.
      • cobind

        public <B> Zipper<B> cobind​(F<Zipper<A>,​B> f)
        Maps over variations of this zipper, such that the given function is applied to each variation (comonad pattern).
        Parameters:
        f - The comonadic function to apply for each variation of this zipper.
        Returns:
        A new zipper, with the given function applied for each variation of this zipper.
      • zipWithFocus

        public Zipper<P2<A,​java.lang.Boolean>> zipWithFocus()
        Zips the elements of this zipper with a boolean that indicates whether that element has focus. All of the booleans will be false, except the focused element.
        Returns:
        A new zipper of pairs, with each element of this zipper paired with a boolean that is true if that element has focus, and false otherwise.
      • move

        public Option<Zipper<A>> move​(int n)
        Move the focus to the specified index.
        Parameters:
        n - The index to which to move the focus.
        Returns:
        A new zipper with the focus moved to the specified index, or none if there is no such index.
      • move

        public static <A> F<java.lang.Integer,​F<Zipper<A>,​Option<Zipper<A>>>> move()
        A first-class version of the move function.
        Returns:
        A function that moves the focus of the given zipper to the given index.
      • find

        public Option<Zipper<A>> find​(F<A,​java.lang.Boolean> p)
        Moves the focus to the element matching the given predicate, if present.
        Parameters:
        p - A predicate to match.
        Returns:
        A new zipper with the nearest matching element focused if it is present in this zipper.
      • index

        public int index()
        Returns the index of the focus.
        Returns:
        the index of the focus.
      • cycleNext

        public Zipper<A> cycleNext()
        Move the focus to the next element. If the last element is focused, loop to the first element.
        Returns:
        A new zipper with the next element focused, unless the last element is currently focused, in which case the first element becomes focused.
      • cyclePrevious

        public Zipper<A> cyclePrevious()
        Move the focus to the previous element. If the first element is focused, loop to the last element.
        Returns:
        A new zipper with the previous element focused, unless the first element is currently focused, in which case the last element becomes focused.
      • deleteLeftCycle

        public Option<Zipper<A>> deleteLeftCycle()
        Possibly deletes the element at the focus, then move the element on the left into focus. If no element is on the left, focus on the last element. If the deletion will cause the list to be empty, return None.
        Returns:
        A new zipper with the focused element removed, and focus on the previous element to the left, or the last element if there is no element to the left.
      • deleteRightCycle

        public Option<Zipper<A>> deleteRightCycle()
        Possibly deletes the element at the focus, then move the element on the right into focus. If no element is on the right, focus on the first element. If the deletion will cause the list to be empty, return None.
        Returns:
        A new zipper with the focused element removed, and focus on the next element to the right, or the first element if there is no element to the right.
      • replace

        public Zipper<A> replace​(A a)
        Replaces the element in focus with the given element.
        Parameters:
        a - An element to replace the focused element with.
        Returns:
        A new zipper with the given element in focus.
      • toStream

        public Stream<A> toStream()
        Returns the Stream representation of this zipper.
        Returns:
        A stream that contains all the elements of this zipper.
      • lefts

        public Stream<A> lefts()
        Returns a Stream of the elements to the left of focus.
        Returns:
        a Stream of the elements to the left of focus.
      • rights

        public Stream<A> rights()
        Returns a Stream of the elements to the right of focus.
        Returns:
        a Stream of the elements to the right of focus.
      • zipWith

        public <B,​C> Zipper<C> zipWith​(Zipper<B> bs,
                                             F2<A,​B,​C> f)
        Zips this Zipper with another, applying the given function lock-step over both zippers in both directions. The structure of the resulting Zipper is the structural intersection of the two Zippers.
        Parameters:
        bs - A Zipper to zip this one with.
        f - A function with which to zip together the two Zippers.
        Returns:
        The result of applying the given function over this Zipper and the given Zipper, location-wise.
      • zipWith

        public <B,​C> Zipper<C> zipWith​(Zipper<B> bs,
                                             F<A,​F<B,​C>> f)
        Zips this Zipper with another, applying the given function lock-step over both zippers in both directions. The structure of the resulting Zipper is the structural intersection of the two Zippers.
        Parameters:
        bs - A Zipper to zip this one with.
        f - A function with which to zip together the two Zippers.
        Returns:
        The result of applying the given function over this Zipper and the given Zipper, location-wise.
      • iterator

        public java.util.Iterator<Zipper<A>> iterator()
        Returns an iterator of all the positions of this Zipper, starting from the leftmost position.
        Specified by:
        iterator in interface java.lang.Iterable<A>
        Returns:
        An iterator of all the positions of this Zipper, starting from the leftmost position.