Package org.threadly.util

Class Pair<L,​R>

  • Type Parameters:
    L - Type of 'left' object to be held
    R - Type of 'right' object to be held
    Direct Known Subclasses:
    MutablePair
    public class Pair<L,​R>
extends java.lang.Object
    A simple tuple implementation (every library needs one, right?). This is designed to be a minimal and light weight pair holder.
    Since:
    4.4.0

    • Constructor Summary

      Constructors 
      Constructor Description
      Pair​(L left, R right)
      Constructs a new pair, providing the left and right objects to be held.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static <L> void applyToLeft​(java.lang.Iterable<? extends Pair<? extends L,​?>> source, java.util.function.Consumer<? super L> consumer)
      Goes through source Iterable and provides all left entries to a given consumer.
      static <R> void applyToRight​(java.lang.Iterable<? extends Pair<?,​? extends R>> source, java.util.function.Consumer<? super R> consumer)
      Goes through source Iterable and provides all right entries to a given consumer.
      static <T> java.util.List<T> collectLeft​(java.util.Collection<? extends Pair<? extends T,​?>> source)
      Collect all the non-null left references into a new List.
      static <T> java.util.List<T> collectRight​(java.util.Collection<? extends Pair<?,​? extends T>> source)
      Collect all the non-null right references into a new List.
      static boolean containsLeft​(java.lang.Iterable<? extends Pair<?,​?>> search, java.lang.Object value)
      Simple search to see if a collection of pairs contains a given left value.
      static boolean containsRight​(java.lang.Iterable<? extends Pair<?,​?>> search, java.lang.Object value)
      Simple search to see if a collection of pairs contains a given right value.
      static <L,​R>
      java.util.List<Pair<L,​R>>      		 convertMap​(java.util.Map<? extends L,​? extends R> map)
      Convert a map into a list of Pair's where the left side of the pair contains the value and the right side is the corresponding value.
      boolean equals​(java.lang.Object o)  
      L getLeft()
      Getter to get the left reference stored in the pair.
      static <T> T getLeftFromRight​(java.lang.Iterable<? extends Pair<? extends T,​?>> search, java.lang.Object right)
      Get the left side of a pair by searching for a matching right side.
      R getRight()
      Getter to get the right reference stored in the pair.
      static <T> T getRightFromLeft​(java.lang.Iterable<? extends Pair<?,​? extends T>> search, java.lang.Object left)
      Get the right side of a pair by searching for a matching left side.
      int hashCode()  
      static <T> java.lang.Iterable<T> iterateLeft​(java.lang.Iterable<? extends Pair<? extends T,​?>> i)
      Convert a Pair Iterator into an iterator that returns the left items.
      static <T> java.util.Iterator<T> iterateLeft​(java.util.Iterator<? extends Pair<? extends T,​?>> i)
      Convert a Pair Iterator into an iterator that returns the left items.
      static <T> java.lang.Iterable<T> iterateRight​(java.lang.Iterable<? extends Pair<?,​? extends T>> i)
      Convert a Pair Iterator into an iterator that returns the right items.
      static <T> java.util.Iterator<T> iterateRight​(java.util.Iterator<? extends Pair<?,​? extends T>> i)
      Convert a Pair Iterator into an iterator that returns the right items.
      static <L,​R>
      Pair<java.util.List<L>,​java.util.List<R>>      		 split​(java.util.Collection<? extends Pair<? extends L,​? extends R>> source)
      Split a collection of pair's into a pair of two collections.
      java.lang.String toString()  
      static <OL,​NL,​OR,​NR>
      java.util.List<Pair<NL,​NR>>      		 transform​(java.util.Collection<? extends Pair<? extends OL,​? extends OR>> source, java.util.function.Function<? super OL,​? extends NL> leftTransformer, java.util.function.Function<? super OR,​? extends NR> rightTransformer)
      Function to assist in transforming a collection of pairs into a new resulting list.
      static <OL,​NL,​R>
      java.util.List<Pair<NL,​R>>      		 transformLeft​(java.util.Collection<? extends Pair<? extends OL,​? extends R>> source, java.util.function.Function<? super OL,​? extends NL> transformer)
      Function to assist in transforming the left side of pairs from one form to another.
      static <L,​OR,​NR>
      java.util.List<Pair<L,​NR>>      		 transformRight​(java.util.Collection<? extends Pair<? extends L,​? extends OR>> source, java.util.function.Function<? super OR,​? extends NR> transformer)
      Function to assist in transforming the right side of pairs from one form to another.

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • Pair

        public Pair​(L left,
            R right)
        Constructs a new pair, providing the left and right objects to be held.
        Parameters:
        left - Left reference
        right - Right reference

    • Method Detail

      • transformLeft

        public static <OL,​NL,​R> java.util.List<Pair<NL,​R>> transformLeft​(java.util.Collection<? extends Pair<? extends OL,​? extends R>> source,
                                                                                   java.util.function.Function<? super OL,​? extends NL> transformer)
        Function to assist in transforming the left side of pairs from one form to another. This will iterate through the source, applying the provided transformer function to each left side entry. The resulting list will contain new pair instances with the transformed left entries and the original right side entries.

        If both the left and right sides must be transformed please see transform(Collection, Function, Function).

        Type Parameters:
        OL - Original left side type for input source
        NL - Transformed left side type for resulting list
        R - Type of object held as pair's right reference
        Parameters:
        source - Source collection to be iterating over
        transformer - Function to apply to the left side entries
        Returns:
        New list of transformed pairs

      • transformRight

        public static <L,​OR,​NR> java.util.List<Pair<L,​NR>> transformRight​(java.util.Collection<? extends Pair<? extends L,​? extends OR>> source,
                                                                                    java.util.function.Function<? super OR,​? extends NR> transformer)
        Function to assist in transforming the right side of pairs from one form to another. This will iterate through the source, applying the provided transformer function to each right side entry. The resulting list will contain new pair instances with the transformed right entries and the original left side entries.

        If both the left and right sides must be transformed please see transform(Collection, Function, Function).

        Type Parameters:
        OR - Original right side type for input source
        NR - Transformed right side type for resulting list
        L - Type of object held as pair's left reference
        Parameters:
        source - Source collection to be iterating over
        transformer - Function to apply to the right side entries
        Returns:
        New list of transformed pairs

      • transform

        public static <OL,​NL,​OR,​NR> java.util.List<Pair<NL,​NR>> transform​(java.util.Collection<? extends Pair<? extends OL,​? extends OR>> source,
                                                                                          java.util.function.Function<? super OL,​? extends NL> leftTransformer,
                                                                                          java.util.function.Function<? super OR,​? extends NR> rightTransformer)
        Function to assist in transforming a collection of pairs into a new resulting list. This simply iterates over the provided collection and applies the left and right transformers to each pair. Returning a new list with the resulting transformed values contained in the pairs.
        Type Parameters:
        OL - Original left side type for input source
        OR - Original right side type for input source
        NL - Transformed left side type for resulting list
        NR - Transformed right side type for resulting list
        Parameters:
        source - Source collection to be iterating over
        leftTransformer - Function to apply to the left side entries
        rightTransformer - Function to apply to the right side entries
        Returns:
        New list of transformed pairs

      • applyToLeft

        public static <L> void applyToLeft​(java.lang.Iterable<? extends Pair<? extends L,​?>> source,
                                   java.util.function.Consumer<? super L> consumer)
        Goes through source Iterable and provides all left entries to a given consumer.
        Type Parameters:
        L - Type of object held as pair's left reference
        Parameters:
        source - Source to iterate through
        consumer - Consumer to provide left entries to

      • applyToRight

        public static <R> void applyToRight​(java.lang.Iterable<? extends Pair<?,​? extends R>> source,
                                    java.util.function.Consumer<? super R> consumer)
        Goes through source Iterable and provides all right entries to a given consumer.
        Type Parameters:
        R - Type of object held as pair's right reference
        Parameters:
        source - Source to iterate through
        consumer - Consumer to provide right entries to

      • convertMap

        public static <L,​R> java.util.List<Pair<L,​R>> convertMap​(java.util.Map<? extends L,​? extends R> map)
        Convert a map into a list of Pair's where the left side of the pair contains the value and the right side is the corresponding value.
        Type Parameters:
        L - Type of object held as pair's left reference
        R - Type of object held as pair's right reference
        Parameters:
        map - Map to source entries from
        Returns:
        A list of pairs sourced from the map's entries

      • split

        public static <L,​R> Pair<java.util.List<L>,​java.util.List<R>> split​(java.util.Collection<? extends Pair<? extends L,​? extends R>> source)
        Split a collection of pair's into a pair of two collections. This is more efficient than invoking getLeft() and getRight() separately. Similar to those functions, this will only collect non-null entries. If there is a null left or right entry then the indexes will no longer match each other between the two lists.
        Type Parameters:
        L - Type of object held as pair's left reference
        R - Type of object held as pair's right reference
        Parameters:
        source - Source collection of pairs
        Returns:
        Pair of two collections with the left and right halves

      • iterateLeft

        public static <T> java.lang.Iterable<T> iterateLeft​(java.lang.Iterable<? extends Pair<? extends T,​?>> i)
        Convert a Pair Iterator into an iterator that returns the left items. This has the minor advantage over collectLeft(Collection) in that the collection is not iterated / copied. Allowing for potential concurrent structures to provide their special iterator behavior through this, as well as avoiding a potential short term memory copy.
        Type Parameters:
        T - Type of object held as pair's left reference
        Parameters:
        i - Iterable to source pairs from
        Returns:
        An iterator that extracts out the left entry of each pair

      • iterateLeft

        public static <T> java.util.Iterator<T> iterateLeft​(java.util.Iterator<? extends Pair<? extends T,​?>> i)
        Convert a Pair Iterator into an iterator that returns the left items. This has the minor advantage over collectLeft(Collection) in that the collection is not iterated / copied. Allowing for potential concurrent structures to provide their special iterator behavior through this, as well as avoiding a potential short term memory copy.
        Type Parameters:
        T - Type of object held as pair's left reference
        Parameters:
        i - Iterator to source pairs from
        Returns:
        An iterator that extracts out the left entry of each pair

      • iterateRight

        public static <T> java.lang.Iterable<T> iterateRight​(java.lang.Iterable<? extends Pair<?,​? extends T>> i)
        Convert a Pair Iterator into an iterator that returns the right items. This has the minor advantage over collectRight(Collection) in that the collection is not iterated / copied. Allowing for potential concurrent structures to provide their special iterator behavior through this, as well as avoiding a potential short term memory copy.
        Type Parameters:
        T - Type of object held as pair's right reference
        Parameters:
        i - Iterable to source pairs from
        Returns:
        An iterator that extracts out the right entry of each pair

      • iterateRight

        public static <T> java.util.Iterator<T> iterateRight​(java.util.Iterator<? extends Pair<?,​? extends T>> i)
        Convert a Pair Iterator into an iterator that returns the right items. This has the minor advantage over collectRight(Collection) in that the collection is not iterated / copied. Allowing for potential concurrent structures to provide their special iterator behavior through this, as well as avoiding a potential short term memory copy.
        Type Parameters:
        T - Type of object held as pair's right reference
        Parameters:
        i - Iterator to source pairs from
        Returns:
        An iterator that extracts out the right entry of each pair

      • collectLeft

        public static <T> java.util.List<T> collectLeft​(java.util.Collection<? extends Pair<? extends T,​?>> source)
        Collect all the non-null left references into a new List. A simple implementation which iterates over a source collection and collects all non-null left references into a new list that can be manipulated or referenced.
        Type Parameters:
        T - Type of object held as pair's left reference
        Parameters:
        source - Source collection of pairs
        Returns:
        New list that contains non-null left references

      • collectRight

        public static <T> java.util.List<T> collectRight​(java.util.Collection<? extends Pair<?,​? extends T>> source)
        Collect all the non-null right references into a new List. A simple implementation which iterates over a source collection and collects all non-null right references into a new list that can be manipulated or referenced.
        Type Parameters:
        T - Type of object held as pair's right reference
        Parameters:
        source - Source collection of pairs
        Returns:
        New list that contains non-null right references

      • containsLeft

        public static boolean containsLeft​(java.lang.Iterable<? extends Pair<?,​?>> search,
                                   java.lang.Object value)
        Simple search to see if a collection of pairs contains a given left value. It is assumed that the iterator will not return any null elements.
        Parameters:
        search - Iterable to search over
        value - Value to be searching for from left elements
        Returns:
        true if the value is found as a left element from the iterable provided

      • containsRight

        public static boolean containsRight​(java.lang.Iterable<? extends Pair<?,​?>> search,
                                    java.lang.Object value)
        Simple search to see if a collection of pairs contains a given right value. It is assumed that the iterator will not return any null elements.
        Parameters:
        search - Iterable to search over
        value - Value to be searching for from right elements
        Returns:
        true if the value is found as a right element from the iterable provided

      • getRightFromLeft

        public static <T> T getRightFromLeft​(java.lang.Iterable<? extends Pair<?,​? extends T>> search,
                                     java.lang.Object left)
        Get the right side of a pair by searching for a matching left side. This iterates over the provided source, and once the first pair with a left that matches (via Object.equals(Object)), the right side is returned. If no match is found, null will be returned. Although the implementer must be aware that since nulls can be kept kept inside pairs, that does not strictly indicate a match failure.
        Type Parameters:
        T - Type of object held as pair's right reference
        Parameters:
        search - Iteratable to search through looking for a match
        left - Object to be looking searching for as a left reference
        Returns:
        Corresponding right reference or null if none is found

      • getLeftFromRight

        public static <T> T getLeftFromRight​(java.lang.Iterable<? extends Pair<? extends T,​?>> search,
                                     java.lang.Object right)
        Get the left side of a pair by searching for a matching right side. This iterates over the provided source, and once the first pair with a right that matches (via Object.equals(Object)), the left side is returned. If no match is found, null will be returned. Although the implementer must be aware that since nulls can be kept kept inside pairs, that does not strictly indicate a match failure.
        Type Parameters:
        T - Type of object held as pair's left reference
        Parameters:
        search - Iteratable to search through looking for a match
        right - Object to be looking searching for as a left reference
        Returns:
        Corresponding left reference or null if none is found

      • getLeft

        public L getLeft()
        Getter to get the left reference stored in the pair.
        Returns:
        Left reference

      • getRight

        public R getRight()
        Getter to get the right reference stored in the pair.
        Returns:
        Right reference

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

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