Pair.java

  1. /*
  2.  * *********************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 2023 by Tidalwave s.a.s. (http://tidalwave.it)
  8.  *
  9.  * *********************************************************************************************************************
  10.  *
  11.  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  12.  * the License. You may obtain a copy of the License at
  13.  *
  14.  *     http://www.apache.org/licenses/LICENSE-2.0
  15.  *
  16.  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
  17.  * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
  18.  * specific language governing permissions and limitations under the License.
  19.  *
  20.  * *********************************************************************************************************************
  21.  *
  22.  * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
  23.  * git clone https://github.com/tidalwave-it/thesefoolishthings-src
  24.  *
  25.  * *********************************************************************************************************************
  26.  */
  27. package it.tidalwave.util;

  28. import javax.annotation.Nonnegative;
  29. import javax.annotation.Nonnull;
  30. import javax.annotation.concurrent.Immutable;
  31. import javax.annotation.concurrent.NotThreadSafe;
  32. import java.util.Map;
  33. import java.util.concurrent.atomic.AtomicInteger;
  34. import java.util.function.IntFunction;
  35. import java.util.function.IntUnaryOperator;
  36. import java.util.stream.Collector;
  37. import java.util.stream.Collectors;
  38. import java.util.stream.IntStream;
  39. import java.util.stream.Stream;
  40. import java.util.stream.StreamSupport;
  41. import lombok.EqualsAndHashCode;
  42. import lombok.Getter;
  43. import lombok.RequiredArgsConstructor;
  44. import lombok.ToString;

  45. /***********************************************************************************************************************
  46.  *
  47.  * A value object that contains a pair of values. Some factory methods allow creating pairs out of existing collections
  48.  * or arrays associating an index.
  49.  *
  50.  * @author  Fabrizio Giudici
  51.  * @since   3.2-ALPHA-6
  52.  * @it.tidalwave.javadoc.draft
  53.  *
  54.  **********************************************************************************************************************/
  55. @Immutable @RequiredArgsConstructor(staticName = "of") @ToString @EqualsAndHashCode
  56. public class Pair<A, B>
  57.   {
  58.     /** A base 0 index rebaser. */
  59.     public static final IntUnaryOperator BASE_0 = i -> i;

  60.     /** A base 1 index rebaser. */
  61.     public static final IntUnaryOperator BASE_1 = i -> i + 1;

  62.     @Getter @Nonnull
  63.     public final A a;

  64.     @Getter @Nonnull
  65.     public final B b;

  66.     /*******************************************************************************************************************
  67.      *
  68.      * Creates a {@link Stream} of {@code Pair}s composed of a given fixed value and another element taken from another
  69.      * {@link Stream}.
  70.      *
  71.      * @param   <T>     the type of the value
  72.      * @param   <U>     the type of the {@code Stream}
  73.      * @param   value   the value
  74.      * @param   stream  the {@code Stream}
  75.      * @return          the {@code Stream} of {@code Pair}s
  76.      * @since           3.2-ALPHA-12
  77.      *
  78.      ******************************************************************************************************************/
  79.     @Nonnull
  80.     public static <T, U> Stream<Pair<T, U>> pairStream (@Nonnull final T value,
  81.                                                         @Nonnull final Stream<? extends U> stream)
  82.       {
  83.         return stream.map(object -> Pair.of(value, object));
  84.       }

  85.     /*******************************************************************************************************************
  86.      *
  87.      * Creates a {@link Stream} of {@code Pair}s composed of a given fixed value and an integer in the given range.
  88.      *
  89.      * @param   <T>     the type of the value
  90.      * @param   value   the value
  91.      * @param   from    the first value of the integer {@code Stream} (included)
  92.      * @param   to      the last value of the integer {@code Stream} (excluded)
  93.      * @return          the {@code Stream} of {@code Pair}s
  94.      * @since           3.2-ALPHA-12
  95.      *
  96.      ******************************************************************************************************************/
  97.     @Nonnull
  98.     public static <T> Stream<Pair<T, Integer>> pairRange (@Nonnull final T value,
  99.                                                           @Nonnegative final int from,
  100.                                                           @Nonnegative final int to)
  101.       {
  102.         return pairStream(value, IntStream.range(from, to).boxed());
  103.       }

  104.     /*******************************************************************************************************************
  105.      *
  106.      * Creates a {@link Stream} of {@code Pair}s composed of a given fixed value and an integer in the given range.
  107.      *
  108.      * @param   <T>     the type of the value
  109.      * @param   value   the value
  110.      * @param   from    the first value of the integer {@code Stream} (included)
  111.      * @param   to      the last value of the integer {@code Stream} (included)
  112.      * @return          the {@code Stream} of {@code Pair}s
  113.      * @since           3.2-ALPHA-12
  114.      *
  115.      ******************************************************************************************************************/
  116.     @Nonnull
  117.     public static <T> Stream<Pair<T, Integer>> pairRangeClosed (@Nonnull final T value,
  118.                                                                 @Nonnegative final int from,
  119.                                                                 @Nonnegative final int to)
  120.       {
  121.         return pairStream(value, IntStream.rangeClosed(from, to).boxed());
  122.       }

  123.     /*******************************************************************************************************************
  124.      *
  125.      * Returns a {@link Stream} out of the elements in a given array made of {@link Pair}s {@code (index, value)}.
  126.      *
  127.      * @param       <T>             the type of the elements
  128.      * @param       array           the array
  129.      * @return                      the stream
  130.      *
  131.      ******************************************************************************************************************/
  132.     @Nonnull
  133.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final T[] array)
  134.       {
  135.         return Pair.indexedPairStream(array, BASE_0);
  136.       }

  137.     /*******************************************************************************************************************
  138.      *
  139.      * Returns a {@link Stream} out of the elements in the array, made of {@link Pair}s {@code (index, value)}. The
  140.      * index can be rebased.
  141.      *
  142.      * @param       <T>               the type of the elements
  143.      * @param       array             the array
  144.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  145.      * @return                        the stream
  146.      *
  147.      ******************************************************************************************************************/
  148.     @Nonnull
  149.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final T[] array,
  150.                                                                   @Nonnull final IntUnaryOperator rebaser)
  151.       {
  152.         return Pair.indexedPairStream(array, rebaser, i -> i);
  153.       }

  154.     /*******************************************************************************************************************
  155.      *
  156.      * Returns a {@link Stream} out of the elements in a given array made of {@link Pair}s {@code (index, value)}. The
  157.      * index is transformed with the given function.
  158.      *
  159.      * @param       <I>               the type of the transformed index
  160.      * @param       <T>               the type of the elements
  161.      * @param       array             the array
  162.      * @param       indexTransformer  the transformer of the index
  163.      * @return                        the stream
  164.      *
  165.      ******************************************************************************************************************/
  166.     @Nonnull
  167.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final T[] array,
  168.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  169.       {
  170.         return Pair.indexedPairStream(array, BASE_0, indexTransformer);
  171.       }

  172.     /*******************************************************************************************************************
  173.      *
  174.      * Returns a {@link Stream} out of the elements in the array, made of {@link Pair}s {@code (index, value)}.  The
  175.      * index can be rebased and transformed with specific functions.
  176.      *
  177.      * @param       <T>               the type of the elements
  178.      * @param       <I>               the type of the transformed index
  179.      * @param       array             the array
  180.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  181.      * @param       indexTransformer  the transformer of the index
  182.      * @return                        the stream
  183.      *
  184.      ******************************************************************************************************************/
  185.     @Nonnull
  186.     public static <T, I> Stream<Pair<I, T>> indexedPairStream (@Nonnull final T[] array,
  187.                                                                @Nonnull final IntUnaryOperator rebaser,
  188.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  189.       {
  190.         return IntStream.range(0, array.length).mapToObj(i -> of(indexTransformer.apply(rebaser.applyAsInt(i)), array[i]));
  191.       }

  192.     /*******************************************************************************************************************
  193.      *
  194.      * Returns a {@link Stream} out of the elements in a given {@link Iterable} made of {@link Pair}s {@code (index,
  195.      * value)}.
  196.      *
  197.      * @param       <T>             the type of the elements
  198.      * @param       iterable        the iterable
  199.      * @return                      the stream
  200.      *
  201.      ******************************************************************************************************************/
  202.     @Nonnull
  203.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final Iterable<? extends T> iterable)
  204.       {
  205.         return Pair.indexedPairStream(iterable, BASE_0);
  206.       }

  207.     /*******************************************************************************************************************
  208.      *
  209.      * Returns a {@link Stream} out of the elements in a given {@link Iterable} made of {@link Pair}s {@code (index,
  210.      * value)}. The index can be rebased.
  211.      *
  212.      * @param       <T>               the type of the elements
  213.      * @param       iterable          the iterable
  214.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  215.      * @return                        the stream
  216.      *
  217.      ******************************************************************************************************************/
  218.     @Nonnull
  219.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final Iterable<? extends T> iterable,
  220.                                                                   @Nonnull final IntUnaryOperator rebaser)
  221.       {
  222.         return Pair.indexedPairStream(iterable, rebaser, i -> i);
  223.       }

  224.     /*******************************************************************************************************************
  225.      *
  226.      * Returns a {@link Stream} out of the elements in a given {@link Iterable} made of {@link Pair}s {@code (index,
  227.      * value)}. The index is transformed with the given function.
  228.      *
  229.      * @param       <I>               the type of the transformed index
  230.      * @param       <T>               the type of the elements
  231.      * @param       iterable          the iterable
  232.      * @param       indexTransformer  the transformer of the index
  233.      * @return                        the stream
  234.      *
  235.      ******************************************************************************************************************/
  236.     @Nonnull @SuppressWarnings("unchecked")
  237.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final Iterable<? extends T> iterable,
  238.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  239.       {
  240.         return Pair.indexedPairStream(iterable, BASE_0, indexTransformer);
  241.       }

  242.     /*******************************************************************************************************************
  243.      *
  244.      * Returns a {@link Stream} out of the elements returned by an iterable, made of {@link Pair}s
  245.      * {@code (index, value)}. The index is rebased and transformed with specific functions.
  246.      *
  247.      * @param       <T>               the type of the elements
  248.      * @param       <I>               the type of the transformed index
  249.      * @param       iterable          the iterable
  250.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  251.      * @param       indexTransformer  the transformer of the index
  252.      * @return                        the stream
  253.      *
  254.      ******************************************************************************************************************/
  255.     @Nonnull @SuppressWarnings("unchecked")
  256.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final Iterable<? extends T> iterable,
  257.                                                                @Nonnull final IntUnaryOperator rebaser,
  258.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  259.       {
  260.         return new Factory<I, T>().stream(iterable, rebaser, indexTransformer);
  261.       }

  262.     /*******************************************************************************************************************
  263.      *
  264.      * Returns a {@link Stream} out of the elements in a given {@link Stream} made of {@link Pair}s {@code (index,
  265.      * value)}.
  266.      *
  267.      * @param       <T>             the type of the elements
  268.      * @param       stream          the stream
  269.      * @return                      the stream
  270.      * @since       3.2-ALPHA-12
  271.      *
  272.      ******************************************************************************************************************/
  273.     @Nonnull @SuppressWarnings("unchecked")
  274.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final Stream<? extends T> stream)
  275.       {
  276.         return Pair.indexedPairStream(((Stream<T>)stream)::iterator);
  277.       }

  278.     /*******************************************************************************************************************
  279.      *
  280.      * Returns a {@link Stream} out of the elements in a given {@link Stream} made of {@link Pair}s {@code (index,
  281.      * value)}. The index can be rebased.
  282.      *
  283.      * @param       <T>               the type of the elements
  284.      * @param       stream            the stream
  285.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  286.      * @return                        the stream
  287.      * @since       3.2-ALPHA-12
  288.      *
  289.      ******************************************************************************************************************/
  290.     @Nonnull @SuppressWarnings("unchecked")
  291.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final Stream<? extends T> stream,
  292.                                                                   @Nonnull final IntUnaryOperator rebaser)
  293.       {
  294.         return Pair.indexedPairStream(((Stream<T>)stream)::iterator, rebaser);
  295.       }

  296.     /*******************************************************************************************************************
  297.      *
  298.      * Returns a {@link Stream} out of the elements in a given {@link Stream} made of {@link Pair}s {@code (index,
  299.      * value)}. The index is transformed with the given function.
  300.      *
  301.      * @param       <I>               the type of the transformed index
  302.      * @param       <T>               the type of the elements
  303.      * @param       stream            the stream
  304.      * @param       indexTransformer  the transformer of the index
  305.      * @return                        the stream
  306.      * @since       3.2-ALPHA-12
  307.      *
  308.      ******************************************************************************************************************/
  309.     @SuppressWarnings("unchecked")
  310.     @Nonnull
  311.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final Stream<? extends T> stream,
  312.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  313.       {
  314.         return Pair.indexedPairStream(((Stream<T>)stream)::iterator, indexTransformer);
  315.       }

  316.     /*******************************************************************************************************************
  317.      *
  318.      * Returns a {@link Stream} out of the elements returned by a Stream, made of {@link Pair}s
  319.      * {@code (index, value)}. The index is rebased and transformed with specific functions.
  320.      *
  321.      * @param       <T>               the type of the elements
  322.      * @param       <I>               the type of the transformed index
  323.      * @param       stream            the stream
  324.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  325.      * @param       indexTransformer  the transformer of the index
  326.      * @return                        the stream
  327.      * @since       3.2-ALPHA-12
  328.      *
  329.      ******************************************************************************************************************/
  330.     @SuppressWarnings("unchecked")
  331.     @Nonnull
  332.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final Stream<? extends T> stream,
  333.                                                                @Nonnull final IntUnaryOperator rebaser,
  334.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  335.       {
  336.         return Pair.indexedPairStream(((Stream<T>)stream)::iterator, rebaser, indexTransformer);
  337.       }

  338.     /*******************************************************************************************************************
  339.      *
  340.      * Returns a {@link Stream} out of the elements returned by a supplier, made of {@link Pair}s
  341.      * {@code (index, value)}.
  342.      *
  343.      * @param       <T>               the type of the elements
  344.      * @param       from              the first index (included)
  345.      * @param       to                the last index (excluded)
  346.      * @param       valueSupplier     the supplier of values
  347.      * @return                        the stream
  348.      *
  349.      ******************************************************************************************************************/
  350.     @Nonnull
  351.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnegative final int from,
  352.                                                                   @Nonnegative final int to,
  353.                                                                   @Nonnull final IntFunction<? extends T> valueSupplier)
  354.       {
  355.         return indexedPairStream(from, to, valueSupplier, BASE_0, i -> i);
  356.       }

  357.     /*******************************************************************************************************************
  358.      *
  359.      * Returns a {@link Stream} out of the elements returned by a supplier, made of {@link Pair}s
  360.      * {@code (index, value)}.
  361.      *
  362.      * @param       <T>               the type of the elements
  363.      * @param       from              the first index (included)
  364.      * @param       to                the last index (excluded)
  365.      * @param       valueSupplier     the supplier of values
  366.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  367.      * @return                        the stream
  368.      *
  369.      ******************************************************************************************************************/
  370.     @Nonnull
  371.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnegative final int from,
  372.                                                                   @Nonnegative final int to,
  373.                                                                   @Nonnull final IntFunction<? extends T> valueSupplier,
  374.                                                                   @Nonnull final IntUnaryOperator rebaser)
  375.       {
  376.         return indexedPairStream(from, to, valueSupplier, rebaser, i -> i);
  377.       }

  378.     /*******************************************************************************************************************
  379.      *
  380.      * Returns a {@link Stream} out of the elements returned by a supplier, made of {@link Pair}s
  381.      * {@code (index, value)}. The index can be rebased and transformed with specific functions.
  382.      *
  383.      * @param       <I>               the type of the transformed index
  384.      * @param       <T>               the type of the elements
  385.      * @param       from              the first index (included)
  386.      * @param       to                the last index (excluded)
  387.      * @param       valueSupplier     the supplier of values
  388.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  389.      * @param       indexTransformer  the transformer of the index
  390.      * @return                        the stream
  391.      *
  392.      ******************************************************************************************************************/
  393.     @Nonnull
  394.     public static <T, I> Stream<Pair<I, T>> indexedPairStream (@Nonnegative final int from,
  395.                                                                @Nonnegative final int to,
  396.                                                                @Nonnull final IntFunction<? extends T> valueSupplier,
  397.                                                                @Nonnull final IntUnaryOperator rebaser,
  398.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  399.       {
  400.         return IntStream.range(from, to).mapToObj(i -> Pair.of(indexTransformer.apply(rebaser.applyAsInt(i)),
  401.                                                                valueSupplier.apply(i)));
  402.       }

  403.     /*******************************************************************************************************************
  404.      *
  405.      * A {@link Collector} that produces a {@link Map} whose key is field {@code a} and value field {@code b}. Use
  406.      * with {@link Stream#collect(Collector)}.
  407.      *
  408.      * @param <A>   the type of the former element of the pair
  409.      * @param <B>   the type of the latter element of the pair
  410.      * @return      the {@code Collector}
  411.      *
  412.      ******************************************************************************************************************/
  413.     @Nonnull
  414.     public static <A, B> Collector<Pair<A, B>, ?, Map<A, B>> pairsToMap()
  415.       {
  416.         return Collectors.toMap(p -> p.a, p -> p.b);
  417.       }

  418.     /*******************************************************************************************************************
  419.      *
  420.      * Zips two streams into a stream of {@link Pair}s.
  421.      *
  422.      * @param   streamA     the first {@link Stream}
  423.      * @param   streamB     the second {@link Stream}
  424.      * @param   <A>         the type of elements of the first {@link Stream}
  425.      * @param   <B>         the type of elements of the second {@link Stream}
  426.      * @return              the zipped {@link Stream}
  427.      * @since   3.2-ALPHA-17 (since 3.2-ALPHA-12 was in {@code StreamOperations}
  428.      *
  429.      ******************************************************************************************************************/
  430.     @Nonnull
  431.     public static <A, B> Stream<Pair<A, B>> zip (@Nonnull final Stream<? extends A> streamA,
  432.                                                  @Nonnull final Stream<? extends B> streamB)
  433.       {
  434.         return StreamUtils.zip(streamA, streamB, Pair::of);
  435.       }

  436.     @NotThreadSafe
  437.     static final class Factory<I, T>
  438.       {
  439.         private final AtomicInteger n = new AtomicInteger(0);

  440.         @Nonnull
  441.         public Stream<Pair<I, T>> stream (@Nonnull final Iterable<? extends T> iterable,
  442.                                           @Nonnull final IntUnaryOperator rebaser,
  443.                                           @Nonnull final IntFunction<? extends I> indexFunction)
  444.           {
  445.             return StreamSupport.stream(iterable.spliterator(), false)
  446.                                 .map(o -> Pair.of(indexFunction.apply(rebaser.applyAsInt(n.getAndIncrement())), o));
  447.           }
  448.       }
  449.   }