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, @Nonnull final Stream<U> stream)
  81.       {
  82.         return stream.map(object -> Pair.of(value, object));
  83.       }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  415.     @NotThreadSafe
  416.     static final class Factory<I, T>
  417.       {
  418.         private final AtomicInteger n = new AtomicInteger(0);

  419.         @Nonnull
  420.         public <I, T> Stream<Pair<I, T>> stream (@Nonnull final Iterable<T> iterable,
  421.                                                  @Nonnull final IntUnaryOperator rebaser,
  422.                                                  @Nonnull final IntFunction<I> indexFunction)
  423.           {
  424.             return StreamSupport.stream(iterable.spliterator(), false)
  425.                                 .map(o -> Pair.of(indexFunction.apply(rebaser.applyAsInt(n.getAndIncrement())), o));
  426.           }
  427.       }
  428.   }