feat: enable the contain* family of joiners

- Move UnfinishedJoiners to Joiners
- Score corruption was caused when a duplicate was encounter, causing
the forEach iterator to skip the remaining elements in its current
downstream iterator and proceed to the next downstream iterator instead.
It now exhausts the current downstream iterator beforce proceeding to
the next one.
- Due to the existance of duplicates, the implemented randomIterator is
not completely fair; to create a fair random iterator, all the elements
must be put into a set first.

Author: Christopher-Chianelli

core/src/main/java/ai/timefold/solver/core/api/score/stream/Joiners.java

@@ -1,5 +1,6 @@
 package ai.timefold.solver.core.api.score.stream;
 
+import java.util.SequencedCollection;
 import java.util.function.BiFunction;
 import java.util.function.BiPredicate;
 import java.util.function.Function;
@@ -256,6 +257,93 @@ public final class Joiners {
                 .and(Joiners.greaterThan(leftEndMapping, rightStartMapping));
     }
 
+    /**
+     * Joins every A and B where a value of property on B is contained in the collection of properties on A.
+     * <p>
+     * For example:
+     * <ul>
+     * <li>{@code ["A", "B"]} containing {@code "A"} is {@code true}</li>
+     * <li>{@code ["A"]} containing {@code "A"} is {@code true}</li>
+     * <li>{@code ["X", "Y"]} containing {@code "A"} is {@code false}</li>
+     * <li>{@code []} containing {@code "A"} is {@code false}</li>
+     * <li>{@code ["A", "B"]} containing {@code null} is {@code false}</li>
+     * <li>{@code []} containing {@code null} is {@code false}</li>
+     * </ul>
+     *
+     * @param leftMapping mapping function to apply to A
+     * @param rightMapping mapping function to apply to B
+     * @param <A> the type of object on the left
+     * @param <B> the type of object on the right
+     * @param <Property_> the type of the property to compare
+     */
+    public static <A, B, Property_> @NonNull BiJoiner<A, B> containing(
+            @NonNull Function<A, SequencedCollection<Property_>> leftMapping,
+            @NonNull Function<B, Property_> rightMapping) {
+        return new DefaultBiJoiner<>(leftMapping, JoinerType.CONTAINING, rightMapping);
+    }
+
+    /**
+     * Joins every A and B where a value of property on A is contained in the collection of properties on B.
+     * <p>
+     * For example:
+     * <ul>
+     * <li>{@code "A"} contained in {@code ["A", "B"]} is {@code true}</li>
+     * <li>{@code "A"} contained in {@code ["A"]} is {@code true}</li>
+     * <li>{@code "A"} contained in {@code ["X", "Y"]} is {@code false}</li>
+     * <li>{@code "A"} contained in {@code []} is {@code false}</li>
+     * <li>{@code null} contained in {@code ["A", "B"]} is {@code false}</li>
+     * <li>{@code null} contained in {@code []} is {@code false}</li>
+     * </ul>
+     *
+     * @param leftMapping mapping function to apply to A
+     * @param rightMapping mapping function to apply to B
+     * @param <A> the type of object on the left
+     * @param <B> the type of object on the right
+     * @param <Property_> the type of the property to compare
+     */
+    public static <A, B, Property_> @NonNull BiJoiner<A, B> containedIn(@NonNull Function<A, Property_> leftMapping,
+            @NonNull Function<B, SequencedCollection<Property_>> rightMapping) {
+        return new DefaultBiJoiner<>(leftMapping, JoinerType.CONTAINED_IN, rightMapping);
+    }
+
+    /**
+     * As defined by {@link #containingAnyOf(Function, Function)} with both arguments using the same mapping.
+     *
+     * @param mapping mapping function to apply to both A and B
+     * @param <A> the type of both objects
+     * @param <Property_> the type of the property to compare
+     */
+    public static <A, Property_> @NonNull BiJoiner<A, A> containingAnyOf(
+            @NonNull Function<A, SequencedCollection<Property_>> mapping) {
+        return containingAnyOf(mapping, mapping);
+    }
+
+    /**
+     * Joins every A and B where a collection of properties on A overlaps with a collection of properties on B.
+     * <p>
+     * For example:
+     * <ul>
+     * <li>{@code ["A", "B"]} intersecting {@code ["A", "B"]} is {@code true}</li>
+     * <li>{@code ["A", "B"]} intersecting {@code ["A"]} is {@code true}</li>
+     * <li>{@code ["A"]} intersecting {@code ["A", "B"]} is {@code true}</li>
+     * <li>{@code ["A", "B"]} intersecting {@code ["X", "Y"]} is {@code false}</li>
+     * <li>{@code ["A", "B"]} intersecting {@code []} is {@code false}</li>
+     * <li>{@code []} intersecting {@code ["A", "B"]} is {@code false}</li>
+     * <li>{@code []} intersecting {@code []} is {@code false}</li>
+     * </ul>
+     *
+     * @param leftMapping mapping function to apply to A
+     * @param rightMapping mapping function to apply to B
+     * @param <A> the type of object on the left
+     * @param <B> the type of object on the right
+     * @param <Property_> the type of the property to compare
+     */
+    public static <A, B, Property_> @NonNull BiJoiner<A, B> containingAnyOf(
+            @NonNull Function<A, SequencedCollection<Property_>> leftMapping,
+            @NonNull Function<B, SequencedCollection<Property_>> rightMapping) {
+        return new DefaultBiJoiner<>(leftMapping, JoinerType.CONTAINING_ANY_OF, rightMapping);
+    }
+
     // ************************************************************************
     // TriJoiner
     // ************************************************************************
@@ -366,6 +454,53 @@ public final class Joiners {
                 .and(Joiners.greaterThan(leftEndMapping, rightStartMapping));
     }
 
+    /**
+     * As defined by {@link #containing(Function, Function)}.
+     *
+     * @param <A> the type of the first object on the left
+     * @param <B> the type of the second object on the left
+     * @param <C> the type of the object on the right
+     * @param <Property_> the type of the collection elements
+     * @param leftMapping mapping function to apply to (A,B)
+     * @param rightMapping mapping function to apply to C
+     */
+    public static <A, B, C, Property_> @NonNull TriJoiner<A, B, C> containing(
+            @NonNull BiFunction<A, B, SequencedCollection<Property_>> leftMapping,
+            @NonNull Function<C, Property_> rightMapping) {
+        return new DefaultTriJoiner<>(leftMapping, JoinerType.CONTAINING, rightMapping);
+    }
+
+    /**
+     * As defined by {@link #containedIn(Function, Function)}.
+     *
+     * @param <A> the type of the first object on the left
+     * @param <B> the type of the second object on the left
+     * @param <C> the type of the object on the right
+     * @param <Property_> the type of the collection elements
+     * @param leftMapping mapping function to apply to (A,B)
+     * @param rightMapping mapping function to apply to C
+     */
+    public static <A, B, C, Property_> @NonNull TriJoiner<A, B, C> containedIn(@NonNull BiFunction<A, B, Property_> leftMapping,
+            @NonNull Function<C, SequencedCollection<Property_>> rightMapping) {
+        return new DefaultTriJoiner<>(leftMapping, JoinerType.CONTAINED_IN, rightMapping);
+    }
+
+    /**
+     * As defined by {@link #containingAnyOf(Function, Function)}.
+     *
+     * @param <A> the type of the first object on the left
+     * @param <B> the type of the second object on the left
+     * @param <C> the type of the object on the right
+     * @param <Property_> the type of the collection elements
+     * @param leftMapping mapping function to apply to (A,B)
+     * @param rightMapping mapping function to apply to C
+     */
+    public static <A, B, C, Property_> @NonNull TriJoiner<A, B, C> containingAnyOf(
+            @NonNull BiFunction<A, B, SequencedCollection<Property_>> leftMapping,
+            @NonNull Function<C, SequencedCollection<Property_>> rightMapping) {
+        return new DefaultTriJoiner<>(leftMapping, JoinerType.CONTAINING_ANY_OF, rightMapping);
+    }
+
     // ************************************************************************
     // QuadJoiner
     // ************************************************************************
@@ -483,6 +618,57 @@ public final class Joiners {
                 .and(Joiners.greaterThan(leftEndMapping, rightStartMapping));
     }
 
+    /**
+     * As defined by {@link #containing(Function, Function)}.
+     *
+     * @param <A> the type of the first object on the left
+     * @param <B> the type of the second object on the left
+     * @param <C> the type of the third object on the left
+     * @param <D> the type of the object on the right
+     * @param <Property_> the type of the collection elements
+     * @param leftMapping mapping function to apply to (A,B,C)
+     * @param rightMapping mapping function to apply to D
+     */
+    public static <A, B, C, D, Property_> @NonNull QuadJoiner<A, B, C, D> containing(
+            @NonNull TriFunction<A, B, C, SequencedCollection<Property_>> leftMapping,
+            @NonNull Function<D, Property_> rightMapping) {
+        return new DefaultQuadJoiner<>(leftMapping, JoinerType.CONTAINING, rightMapping);
+    }
+
+    /**
+     * As defined by {@link #containedIn(Function, Function)}.
+     *
+     * @param <A> the type of the first object on the left
+     * @param <B> the type of the second object on the left
+     * @param <C> the type of the third object on the left
+     * @param <D> the type of the object on the right
+     * @param <Property_> the type of the collection elements
+     * @param leftMapping mapping function to apply to (A,B,C)
+     * @param rightMapping mapping function to apply to D
+     */
+    public static <A, B, C, D, Property_> @NonNull QuadJoiner<A, B, C, D> containedIn(
+            @NonNull TriFunction<A, B, C, Property_> leftMapping,
+            @NonNull Function<D, SequencedCollection<Property_>> rightMapping) {
+        return new DefaultQuadJoiner<>(leftMapping, JoinerType.CONTAINED_IN, rightMapping);
+    }
+
+    /**
+     * As defined by {@link #containingAnyOf(Function, Function)}.
+     *
+     * @param <A> the type of the first object on the left
+     * @param <B> the type of the second object on the left
+     * @param <C> the type of the third object on the left
+     * @param <D> the type of the object on the right
+     * @param <Property_> the type of the collection elements
+     * @param leftMapping mapping function to apply to (A,B,C)
+     * @param rightMapping mapping function to apply to D
+     */
+    public static <A, B, C, D, Property_> @NonNull QuadJoiner<A, B, C, D> containingAnyOf(
+            @NonNull TriFunction<A, B, C, SequencedCollection<Property_>> leftMapping,
+            @NonNull Function<D, SequencedCollection<Property_>> rightMapping) {
+        return new DefaultQuadJoiner<>(leftMapping, JoinerType.CONTAINING_ANY_OF, rightMapping);
+    }
+
     // ************************************************************************
     // PentaJoiner
     // ************************************************************************
@@ -608,7 +794,60 @@ public final class Joiners {
                 .and(Joiners.greaterThan(leftEndMapping, rightStartMapping));
     }
 
-    private Joiners() {
+    /**
+     * As defined by {@link #containing(Function, Function)}.
+     *
+     * @param <A> the type of the first object on the left
+     * @param <B> the type of the second object on the left
+     * @param <C> the type of the third object on the left
+     * @param <D> the type of the fourth object on the left
+     * @param <E> the type of the object on the right
+     * @param <Property_> the type of the collection elements
+     * @param leftMapping mapping function to apply to (A,B,C,D)
+     * @param rightMapping mapping function to apply to E
+     */
+    public static <A, B, C, D, E, Property_> @NonNull PentaJoiner<A, B, C, D, E> containing(
+            @NonNull QuadFunction<A, B, C, D, SequencedCollection<Property_>> leftMapping,
+            @NonNull Function<E, Property_> rightMapping) {
+        return new DefaultPentaJoiner<>(leftMapping, JoinerType.CONTAINING, rightMapping);
+    }
+
+    /**
+     * As defined by {@link #containedIn(Function, Function)}.
+     *
+     * @param <A> the type of the first object on the left
+     * @param <B> the type of the second object on the left
+     * @param <C> the type of the third object on the left
+     * @param <D> the type of the fourth object on the left
+     * @param <E> the type of the object on the right
+     * @param <Property_> the type of the collection elements
+     * @param leftMapping mapping function to apply to (A,B,C,D)
+     * @param rightMapping mapping function to apply to E
+     */
+    public static <A, B, C, D, E, Property_> @NonNull PentaJoiner<A, B, C, D, E> containedIn(
+            @NonNull QuadFunction<A, B, C, D, Property_> leftMapping,
+            @NonNull Function<E, SequencedCollection<Property_>> rightMapping) {
+        return new DefaultPentaJoiner<>(leftMapping, JoinerType.CONTAINED_IN, rightMapping);
     }
 
+    /**
+     * As defined by {@link #containingAnyOf(Function, Function)}.
+     *
+     * @param <A> the type of the first object on the left
+     * @param <B> the type of the second object on the left
+     * @param <C> the type of the third object on the left
+     * @param <D> the type of the fourth object on the left
+     * @param <E> the type of the object on the right
+     * @param <Property_> the type of the collection elements
+     * @param leftMapping mapping function to apply to (A,B,C,D)
+     * @param rightMapping mapping function to apply to E
+     */
+    public static <A, B, C, D, E, Property_> @NonNull PentaJoiner<A, B, C, D, E> containingAnyOf(
+            @NonNull QuadFunction<A, B, C, D, SequencedCollection<Property_>> leftMapping,
+            @NonNull Function<E, SequencedCollection<Property_>> rightMapping) {
+        return new DefaultPentaJoiner<>(leftMapping, JoinerType.CONTAINING_ANY_OF, rightMapping);
+    }
+
+    private Joiners() {
+    }
 }

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/ContainedInIndexer.java

@@ -1,28 +1,28 @@
 package ai.timefold.solver.core.impl.bavet.common.index;
 
-import java.util.Collection;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.Map;
 import java.util.NoSuchElementException;
 import java.util.Objects;
+import java.util.SequencedCollection;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
 import java.util.random.RandomGenerator;
 
-import ai.timefold.solver.core.impl.score.stream.UnfinishedJoiners;
+import ai.timefold.solver.core.api.score.stream.Joiners;
 import ai.timefold.solver.core.impl.util.ListEntry;
 
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
- * As defined by {@link UnfinishedJoiners#containedIn(Function, Function)}
+ * As defined by {@link Joiners#containedIn(Function, Function)}
  */
 @NullMarked
-final class ContainedInIndexer<T, Key_, KeyCollection_ extends Collection<Key_>> implements Indexer<T> {
+final class ContainedInIndexer<T, Key_, KeyCollection_ extends SequencedCollection<Key_>> implements Indexer<T> {
 
     private final KeyUnpacker<Key_> modifyKeyUnpacker;
     private final KeyUnpacker<KeyCollection_> queryKeyUnpacker;