Pair.java

  1. /*
  2.  * *************************************************************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 2025 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 the License.
  12.  * 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 an "AS IS" BASIS, WITHOUT WARRANTIES OR
  17.  * CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License.
  18.  *
  19.  * *************************************************************************************************************************************************************
  20.  *
  21.  * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
  22.  * git clone https://github.com/tidalwave-it/thesefoolishthings-src
  23.  *
  24.  * *************************************************************************************************************************************************************
  25.  */
  26. package it.tidalwave.util;

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

  44. /***************************************************************************************************************************************************************
  45.  *
  46.  * A value object that contains a pair of values. Some factory methods allow creating pairs out of existing collections or arrays associating an index.
  47.  *
  48.  * @param   <A>     the type of the former element
  49.  * @param   <B>     the type of the latter element
  50.  * @author  Fabrizio Giudici
  51.  * @since   3.2-ALPHA-6
  52.  * @it.tidalwave.javadoc.draft
  53.  *
  54.  **************************************************************************************************************************************************************/
  55. @Getter /* @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.     @Nonnull
  63.     public final A a;

  64.     @Nonnull
  65.     public final B b;

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

  79.     /***********************************************************************************************************************************************************
  80.      * {@return a new {@link Stream} of {@code Pair}s composed of a given fixed value and an integer in the given range}.
  81.      * @param   <T>     the type of the value
  82.      * @param   value   the value
  83.      * @param   from    the first value of the integer {@code Stream} (included)
  84.      * @param   to      the last value of the integer {@code Stream} (excluded)
  85.      * @return          the {@code Stream} of {@code Pair}s
  86.      **********************************************************************************************************************************************************/
  87.     @Nonnull
  88.     public static <T> Stream<Pair<T, Integer>> pairRange (@Nonnull final T value, /* @Nonnegative */ final int from, /* @Nonnegative */ final int to)
  89.       {
  90.         return pairStream(value, IntStream.range(from, to).boxed());
  91.       }

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

  105.     /***********************************************************************************************************************************************************
  106.      * {@return a new {@link Stream} out of the elements in a given array made of {@link Pair}s {@code (index, value)}}.
  107.      * @param       <T>             the type of the elements
  108.      * @param       array           the array
  109.      * @see         #isEven(Pair)
  110.      * @see         #isOdd(Pair)
  111.      **********************************************************************************************************************************************************/
  112.     @Nonnull
  113.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final T[] array)
  114.       {
  115.         return indexedPairStream(array, BASE_0);
  116.       }

  117.     /***********************************************************************************************************************************************************
  118.      * {@return a new {@link Stream} out of the elements in the array, made of {@link Pair}s {@code (index, value)}}. The index can be rebased.
  119.      * @param       <T>               the type of the elements
  120.      * @param       array             the array
  121.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  122.      * @see         #isEven(Pair)
  123.      * @see         #isOdd(Pair)
  124.      **********************************************************************************************************************************************************/
  125.     @Nonnull
  126.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final T[] array, @Nonnull final IntUnaryOperator rebaser)
  127.       {
  128.         return indexedPairStream(array, rebaser, i -> i);
  129.       }

  130.     /***********************************************************************************************************************************************************
  131.      * {@return a new {@link Stream} out of the elements in a given array made of {@link Pair}s {@code (index, value)}}. The index is transformed with the given
  132.      * function.
  133.      * @param       <I>               the type of the transformed index
  134.      * @param       <T>               the type of the elements
  135.      * @param       array             the array
  136.      * @param       indexTransformer  the transformer of the index
  137.      **********************************************************************************************************************************************************/
  138.     @Nonnull
  139.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final T[] array, @Nonnull final IntFunction<? extends I> indexTransformer)
  140.       {
  141.         return indexedPairStream(array, BASE_0, indexTransformer);
  142.       }

  143.     /***********************************************************************************************************************************************************
  144.      * {@return a new {@link Stream} out of the elements in the array, made of {@link Pair}s {@code (index, value)}}. The index can be rebased and transformed
  145.      * with specific functions.
  146.      * @param       <T>               the type of the elements
  147.      * @param       <I>               the type of the transformed index
  148.      * @param       array             the array
  149.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  150.      * @param       indexTransformer  the transformer of the index
  151.      **********************************************************************************************************************************************************/
  152.     @Nonnull
  153.     public static <T, I> Stream<Pair<I, T>> indexedPairStream (@Nonnull final T[] array,
  154.                                                                @Nonnull final IntUnaryOperator rebaser,
  155.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  156.       {
  157.         return IntStream.range(0, array.length).mapToObj(i -> of(indexTransformer.apply(rebaser.applyAsInt(i)), array[i]));
  158.       }

  159.     /***********************************************************************************************************************************************************
  160.      * {@return a new {@link Stream} out of the elements in a given {@link Iterable} made of {@link Pair}s {@code (index, value)}}.
  161.      * @param       <T>               the type of the elements
  162.      * @param       iterable          the iterable
  163.      * @see         #isEven(Pair)
  164.      * @see         #isOdd(Pair)
  165.      **********************************************************************************************************************************************************/
  166.     @Nonnull
  167.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final Iterable<? extends T> iterable)
  168.       {
  169.         return indexedPairStream(iterable, BASE_0);
  170.       }

  171.     /***********************************************************************************************************************************************************
  172.      * {@return a new {@link Stream} out of the elements in a given {@link Iterable} made of {@link Pair}s {@code (index, value)}}. The index can be rebased.
  173.      * @param       <T>               the type of the elements
  174.      * @param       iterable          the iterable
  175.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  176.      * @see         #isEven(Pair)
  177.      * @see         #isOdd(Pair)
  178.      **********************************************************************************************************************************************************/
  179.     @Nonnull
  180.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final Iterable<? extends T> iterable, @Nonnull final IntUnaryOperator rebaser)
  181.       {
  182.         return indexedPairStream(iterable, rebaser, i -> i);
  183.       }

  184.     /***********************************************************************************************************************************************************
  185.      * {@return a new {@link Stream} out of the elements in a given {@link Iterable} made of {@link Pair}s {@code (index, value)}}. The index is transformed
  186.      * with the given function.
  187.      * @param       <I>               the type of the transformed index
  188.      * @param       <T>               the type of the elements
  189.      * @param       iterable          the iterable
  190.      * @param       indexTransformer  the transformer of the index
  191.      **********************************************************************************************************************************************************/
  192.     @Nonnull
  193.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final Iterable<? extends T> iterable,
  194.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  195.       {
  196.         return indexedPairStream(iterable, BASE_0, indexTransformer);
  197.       }

  198.     /***********************************************************************************************************************************************************
  199.      * {@return a new {@link Stream} out of the elements returned by an iterable, made of {@link Pair}s {@code (index, value)}}. The index is rebased and
  200.      * transformed with specific functions.
  201.      * @param       <T>               the type of the elements
  202.      * @param       <I>               the type of the transformed index
  203.      * @param       iterable          the iterable
  204.      * @param       rebaser           the rebaser of the index (BASE_0, BASE_1 or a similar function)
  205.      * @param       indexTransformer  the transformer of the index
  206.      **********************************************************************************************************************************************************/
  207.     @Nonnull
  208.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final Iterable<? extends T> iterable,
  209.                                                                @Nonnull final IntUnaryOperator rebaser,
  210.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  211.       {
  212.         return new Factory<I, T>().stream(iterable, rebaser, indexTransformer);
  213.       }

  214.     /***********************************************************************************************************************************************************
  215.      * {@return a new {@link Stream} out of the elements in a given {@link Stream} made of {@link Pair}s {@code (index, value)}}.
  216.      * @param       <T>               the type of the elements
  217.      * @param       stream            the stream
  218.      * @since       3.2-ALPHA-12
  219.      **********************************************************************************************************************************************************/
  220.     @Nonnull @SuppressWarnings("unchecked")
  221.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final Stream<? extends T> stream)
  222.       {
  223.         return indexedPairStream(((Stream<T>)stream)::iterator);
  224.       }

  225.     /***********************************************************************************************************************************************************
  226.      * {@return a new {@link Stream} out of the elements in a given {@link Stream} made of {@link Pair}s {@code (index, value)}}. The index can be rebased.
  227.      * @param       <T>               the type of the elements
  228.      * @param       stream            the stream
  229.      * @param       rebaser           the rebaser of the index ({@link #BASE_0}, {@link #BASE_1} or a similar function)
  230.      * @since       3.2-ALPHA-12
  231.      **********************************************************************************************************************************************************/
  232.     @Nonnull @SuppressWarnings("unchecked")
  233.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (@Nonnull final Stream<? extends T> stream, @Nonnull final IntUnaryOperator rebaser)
  234.       {
  235.         return indexedPairStream(((Stream<T>)stream)::iterator, rebaser);
  236.       }

  237.     /***********************************************************************************************************************************************************
  238.      * {@return a new {@link Stream} out of the elements in a given {@link Stream} made of {@link Pair}s {@code (index, value)}}. The index is transformed with
  239.      * the given function.
  240.      * @param       <I>               the type of the transformed index
  241.      * @param       <T>               the type of the elements
  242.      * @param       stream            the stream
  243.      * @param       indexTransformer  the transformer of the index
  244.      * @since       3.2-ALPHA-12
  245.      **********************************************************************************************************************************************************/
  246.     @SuppressWarnings("unchecked")
  247.     @Nonnull
  248.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final Stream<? extends T> stream,
  249.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  250.       {
  251.         return indexedPairStream(((Stream<T>)stream)::iterator, indexTransformer);
  252.       }

  253.     /***********************************************************************************************************************************************************
  254.      * {@return a new {@link Stream} out of the elements returned by a Stream, made of {@link Pair}s {@code (index, value)}}. The index is rebased and
  255.      * transformed with specific functions.
  256.      * @param       <T>               the type of the elements
  257.      * @param       <I>               the type of the transformed index
  258.      * @param       stream            the stream
  259.      * @param       rebaser           the rebaser of the index ({@link #BASE_0}, {@link #BASE_1} or a similar function)
  260.      * @param       indexTransformer  the transformer of the index
  261.      * @since       3.2-ALPHA-12
  262.      **********************************************************************************************************************************************************/
  263.     @SuppressWarnings("unchecked")
  264.     @Nonnull
  265.     public static <I, T> Stream<Pair<I, T>> indexedPairStream (@Nonnull final Stream<? extends T> stream,
  266.                                                                @Nonnull final IntUnaryOperator rebaser,
  267.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  268.       {
  269.         return indexedPairStream(((Stream<T>)stream)::iterator, rebaser, indexTransformer);
  270.       }

  271.     /***********************************************************************************************************************************************************
  272.      * {@return a new {@link Stream} out of the elements returned by a supplier, made of {@link Pair}s {@code (index, value)}}.
  273.      * @param       <T>               the type of the elements
  274.      * @param       from              the first index (included)
  275.      * @param       to                the last index (excluded)
  276.      * @param       valueSupplier     the supplier of values
  277.      **********************************************************************************************************************************************************/
  278.     @Nonnull
  279.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (/* @Nonnegative */ final int from,
  280.                                                                   /* @Nonnegative */ final int to,
  281.                                                                   @Nonnull final IntFunction<? extends T> valueSupplier)
  282.       {
  283.         return indexedPairStream(from, to, valueSupplier, BASE_0, i -> i);
  284.       }

  285.     /***********************************************************************************************************************************************************
  286.      * {@return a new {@link Stream} out of the elements returned by a supplier, made of {@link Pair}s  {@code (index, value)}}.
  287.      * @param       <T>               the type of the elements
  288.      * @param       from              the first index (included)
  289.      * @param       to                the last index (excluded)
  290.      * @param       valueSupplier     the supplier of values
  291.      * @param       rebaser           the rebaser of the index ({@link #BASE_0}, {@link #BASE_1} or a similar function)
  292.      **********************************************************************************************************************************************************/
  293.     @Nonnull
  294.     public static <T> Stream<Pair<Integer, T>> indexedPairStream (/* @Nonnegative */ final int from,
  295.                                                                   /* @Nonnegative */ final int to,
  296.                                                                   @Nonnull final IntFunction<? extends T> valueSupplier,
  297.                                                                   @Nonnull final IntUnaryOperator rebaser)
  298.       {
  299.         return indexedPairStream(from, to, valueSupplier, rebaser, i -> i);
  300.       }

  301.     /***********************************************************************************************************************************************************
  302.      * {@return a new {@link Stream} out of the elements returned by a supplier, made of {@link Pair}s  {@code (index, value)}}. The index can be rebased and
  303.      * transformed with specific functions.
  304.      * @param       <I>               the type of the transformed index
  305.      * @param       <T>               the type of the elements
  306.      * @param       from              the first index (included)
  307.      * @param       to                the last index (excluded)
  308.      * @param       valueSupplier     the supplier of values
  309.      * @param       rebaser           the rebaser of the index ({@link #BASE_0}, {@link #BASE_1} or a similar function)
  310.      * @param       indexTransformer  the transformer of the index
  311.      **********************************************************************************************************************************************************/
  312.     @Nonnull
  313.     public static <T, I> Stream<Pair<I, T>> indexedPairStream (/* @Nonnegative */ final int from,
  314.                                                                /* @Nonnegative */ final int to,
  315.                                                                @Nonnull final IntFunction<? extends T> valueSupplier,
  316.                                                                @Nonnull final IntUnaryOperator rebaser,
  317.                                                                @Nonnull final IntFunction<? extends I> indexTransformer)
  318.       {
  319.         return IntStream.range(from, to).mapToObj(i -> Pair.of(indexTransformer.apply(rebaser.applyAsInt(i)), valueSupplier.apply(i)));
  320.       }

  321.     /***********************************************************************************************************************************************************
  322.      * {@return a new {@link Collector} that produces a {@link Map} whose key is field {@code a} and value field {@code b}}.
  323.      * Use with {@link Stream#collect(Collector)}.
  324.      * @param <A>                     the type of the former element of the pair
  325.      * @param <B>                     the type of the latter element of the pair
  326.      * @return                        the {@code Collector}
  327.      **********************************************************************************************************************************************************/
  328.     @Nonnull
  329.     public static <A, B> Collector<Pair<A, B>, ?, Map<A, B>> pairsToMap()
  330.       {
  331.         return Collectors.toMap(p -> p.a, p -> p.b);
  332.       }

  333.     /***********************************************************************************************************************************************************
  334.      * {@return a new stream of {@link Pair}s created by “zipping” together two existing streams}.
  335.      * @param   streamA               the first {@link Stream}
  336.      * @param   streamB               the second {@link Stream}
  337.      * @param   <A>                   the type of elements of the first {@link Stream}
  338.      * @param   <B>                   the type of elements of the second {@link Stream}
  339.      * @since   3.2-ALPHA-17 (since 3.2-ALPHA-12 was in {@code StreamOperations}
  340.      **********************************************************************************************************************************************************/
  341.     @Nonnull
  342.     public static <A, B> Stream<Pair<A, B>> zip (@Nonnull final Stream<? extends A> streamA, @Nonnull final Stream<? extends B> streamB)
  343.       {
  344.         return StreamUtils.zip(streamA, streamB);
  345.       }

  346.     /***********************************************************************************************************************************************************
  347.      * {@return {@code true} if the given pair with an integer member has an even integer}.
  348.      * @param   pair                  the pair
  349.      * @since   5.0-ALPHA-3
  350.      * @see     #indexedPairStream(Object[])
  351.      **********************************************************************************************************************************************************/
  352.     public static boolean isEven (@Nonnull final Pair<Integer, ?> pair)
  353.       {
  354.         return pair.a % 2 == 0;
  355.       }

  356.     /***********************************************************************************************************************************************************
  357.      * {@return {@code true} if the given pair with an integer member has an odd integer}.
  358.      * @param   pair                  the pair
  359.      * @since   5.0-ALPHA-3
  360.      * @see     #indexedPairStream(Object[])
  361.      **********************************************************************************************************************************************************/
  362.     public static boolean isOdd (@Nonnull final Pair<Integer, ?> pair)
  363.       {
  364.         return pair.a % 2 != 0;
  365.       }

  366.     /***********************************************************************************************************************************************************
  367.      * A factory for indexed streams.
  368.      **********************************************************************************************************************************************************/
  369.     /* @NotThreadSafe */
  370.     static final class Factory<I, T>
  371.       {
  372.         private final AtomicInteger n = new AtomicInteger(0);

  373.         @Nonnull
  374.         public Stream<Pair<I, T>> stream (@Nonnull final Iterable<? extends T> iterable,
  375.                                           @Nonnull final IntUnaryOperator rebaser,
  376.                                           @Nonnull final IntFunction<? extends I> indexFunction)
  377.           {
  378.             return StreamSupport.stream(iterable.spliterator(), false)
  379.                                 .map(o -> Pair.of(indexFunction.apply(rebaser.applyAsInt(n.getAndIncrement())), o));
  380.           }
  381.       }
  382.   }