feat: enable sorting on ValueRangeManager

zepfred · zepfred · commit 16d52c791489 · 2025-11-03T10:33:48.000-03:00
diff --git a/core/src/main/java/ai/timefold/solver/core/api/domain/valuerange/ValueRange.java b/core/src/main/java/ai/timefold/solver/core/api/domain/valuerange/ValueRange.java
@@ -8,6 +8,7 @@
 
 import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 import ai.timefold.solver.core.api.domain.variable.PlanningVariable;
+import ai.timefold.solver.core.impl.domain.valuerange.sort.ValueRangeSorter;
 
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -45,6 +46,14 @@ public interface ValueRange<T> {
      */
     boolean contains(@Nullable T value);
 
+    /**
+     * The sorting operation copies the current value range and sorts it using the provided sorter.
+     *
+     * @param sorter never null, the value range sorter
+     * @return A new instance of the value range, with the data sorted.
+     */
+    ValueRange<T> sort(ValueRangeSorter<T> sorter);
+
     /**
      * Select in random order, but without shuffling the elements.
      * Each element might be selected multiple times.
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/AbstractCountableValueRange.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/AbstractCountableValueRange.java
@@ -5,6 +5,9 @@
 import ai.timefold.solver.core.api.domain.valuerange.CountableValueRange;
 import ai.timefold.solver.core.api.domain.valuerange.ValueRange;
 import ai.timefold.solver.core.api.domain.valuerange.ValueRangeFactory;
+import ai.timefold.solver.core.impl.domain.valuerange.sort.ValueRangeSorter;
+
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Abstract superclass for {@link CountableValueRange} (and therefore {@link ValueRange}).
@@ -13,6 +16,7 @@
  * @see ValueRange
  * @see ValueRangeFactory
  */
+@NullMarked
 public abstract class AbstractCountableValueRange<T> implements CountableValueRange<T> {
 
     /**
@@ -33,4 +37,10 @@ public boolean isEmpty() {
         return getSize() == 0L;
     }
 
+    @Override
+    public ValueRange<T> sort(ValueRangeSorter<T> sorter) {
+        // The sorting operation is not supported by default
+        // and must be explicitly implemented by the child classes if needed.
+        throw new UnsupportedOperationException();
+    }
 }
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/AbstractUncountableValueRange.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/AbstractUncountableValueRange.java
@@ -3,6 +3,7 @@
 import ai.timefold.solver.core.api.domain.valuerange.CountableValueRange;
 import ai.timefold.solver.core.api.domain.valuerange.ValueRange;
 import ai.timefold.solver.core.api.domain.valuerange.ValueRangeFactory;
+import ai.timefold.solver.core.impl.domain.valuerange.sort.ValueRangeSorter;
 
 /**
  * Abstract superclass for {@link ValueRange} that is not a {@link CountableValueRange}).
@@ -16,4 +17,8 @@
 @Deprecated(forRemoval = true, since = "1.1.0")
 public abstract class AbstractUncountableValueRange<T> implements ValueRange<T> {
 
+    @Override
+    public ValueRange<T> sort(ValueRangeSorter<T> sorter) {
+        throw new UnsupportedOperationException();
+    }
 }
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/ValueRangeCache.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/ValueRangeCache.java
@@ -8,6 +8,7 @@
 import java.util.Random;
 import java.util.Set;
 
+import ai.timefold.solver.core.impl.domain.valuerange.sort.ValueRangeSorter;
 import ai.timefold.solver.core.impl.heuristic.selector.common.iterator.CachedListRandomIterator;
 import ai.timefold.solver.core.impl.util.CollectionUtils;
 
@@ -25,16 +26,19 @@ public final class ValueRangeCache<Value_>
 
     private final List<Value_> valuesWithFastRandomAccess;
     private final Set<Value_> valuesWithFastLookup;
+    private final CacheType cacheType;
 
-    private ValueRangeCache(int size, Set<Value_> emptyCacheSet) {
+    private ValueRangeCache(int size, Set<Value_> emptyCacheSet, CacheType cacheType) {
         this.valuesWithFastRandomAccess = new ArrayList<>(size);
         this.valuesWithFastLookup = emptyCacheSet;
+        this.cacheType = cacheType;
     }
 
-    private ValueRangeCache(Collection<Value_> collection, Set<Value_> emptyCacheSet) {
+    private ValueRangeCache(Collection<Value_> collection, Set<Value_> emptyCacheSet, CacheType cacheType) {
         this.valuesWithFastRandomAccess = new ArrayList<>(collection);
         this.valuesWithFastLookup = emptyCacheSet;
         this.valuesWithFastLookup.addAll(valuesWithFastRandomAccess);
+        this.cacheType = cacheType;
     }
 
     public void add(@Nullable Value_ value) {
@@ -72,6 +76,20 @@ public Iterator<Value_> iterator(Random workingRandom) {
         return new CachedListRandomIterator<>(valuesWithFastRandomAccess, workingRandom);
     }
 
+    /**
+     * Creates a copy of the cache and apply a sorting operation.
+     *
+     * @param sorter never null, the sorter
+     */
+    public ValueRangeCache<Value_> sort(ValueRangeSorter<Value_> sorter) {
+        var valuesWithFastRandomAccessSorted = new ArrayList<>(valuesWithFastRandomAccess);
+        sorter.sort(valuesWithFastRandomAccessSorted);
+        return switch (cacheType) {
+            case USER_VALUES -> Builder.FOR_USER_VALUES.buildCache(valuesWithFastRandomAccessSorted);
+            case TRUSTED_VALUES -> Builder.FOR_TRUSTED_VALUES.buildCache(valuesWithFastRandomAccessSorted);
+        };
+    }
+
     public enum Builder {
 
         /**
@@ -80,12 +98,13 @@ public enum Builder {
         FOR_USER_VALUES {
             @Override
             public <Value_> ValueRangeCache<Value_> buildCache(int size) {
-                return new ValueRangeCache<>(size, CollectionUtils.newIdentityHashSet(size));
+                return new ValueRangeCache<>(size, CollectionUtils.newIdentityHashSet(size), CacheType.USER_VALUES);
             }
 
             @Override
             public <Value_> ValueRangeCache<Value_> buildCache(Collection<Value_> collection) {
-                return new ValueRangeCache<>(collection, CollectionUtils.newIdentityHashSet(collection.size()));
+                return new ValueRangeCache<>(collection, CollectionUtils.newIdentityHashSet(collection.size()),
+                        CacheType.USER_VALUES);
             }
 
         },
@@ -100,12 +119,13 @@ public <Value_> ValueRangeCache<Value_> buildCache(Collection<Value_> collection
         FOR_TRUSTED_VALUES {
             @Override
             public <Value_> ValueRangeCache<Value_> buildCache(int size) {
-                return new ValueRangeCache<>(size, CollectionUtils.newHashSet(size));
+                return new ValueRangeCache<>(size, CollectionUtils.newHashSet(size), CacheType.TRUSTED_VALUES);
             }
 
             @Override
             public <Value_> ValueRangeCache<Value_> buildCache(Collection<Value_> collection) {
-                return new ValueRangeCache<>(collection, CollectionUtils.newHashSet(collection.size()));
+                return new ValueRangeCache<>(collection, CollectionUtils.newHashSet(collection.size()),
+                        CacheType.TRUSTED_VALUES);
             }
 
         };
@@ -116,4 +136,9 @@ public <Value_> ValueRangeCache<Value_> buildCache(Collection<Value_> collection
 
     }
 
+    private enum CacheType {
+        USER_VALUES,
+        TRUSTED_VALUES
+    }
+
 }
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/EmptyValueRange.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/EmptyValueRange.java
@@ -4,7 +4,9 @@
 import java.util.NoSuchElementException;
 import java.util.Random;
 
+import ai.timefold.solver.core.api.domain.valuerange.ValueRange;
 import ai.timefold.solver.core.impl.domain.valuerange.AbstractCountableValueRange;
+import ai.timefold.solver.core.impl.domain.valuerange.sort.ValueRangeSorter;
 
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.NullMarked;
@@ -43,6 +45,12 @@ public long getSize() {
         return (Iterator<T>) EmptyIterator.INSTANCE;
     }
 
+    @Override
+    public ValueRange<T> sort(ValueRangeSorter<T> sorter) {
+        // Sorting operation ignored
+        return this;
+    }
+
     @Override
     public boolean contains(@Nullable T value) {
         return false;
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/collection/ListValueRange.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/collection/ListValueRange.java
@@ -1,11 +1,14 @@
 package ai.timefold.solver.core.impl.domain.valuerange.buildin.collection;
 
+import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Random;
 
+import ai.timefold.solver.core.api.domain.valuerange.ValueRange;
 import ai.timefold.solver.core.impl.domain.valuerange.AbstractCountableValueRange;
 import ai.timefold.solver.core.impl.domain.valuerange.ValueRangeCache;
+import ai.timefold.solver.core.impl.domain.valuerange.sort.ValueRangeSorter;
 import ai.timefold.solver.core.impl.heuristic.selector.common.iterator.CachedListRandomIterator;
 
 import org.jspecify.annotations.NullMarked;
@@ -55,6 +58,13 @@ public boolean contains(@Nullable T value) {
         return cache.contains(value);
     }
 
+    @Override
+    public ValueRange<T> sort(ValueRangeSorter<T> sorter) {
+        var newList = new ArrayList<>(list);
+        sorter.sort(newList);
+        return new ListValueRange<>(newList, isValueImmutable);
+    }
+
     @Override
     public Iterator<T> createOriginalIterator() {
         return list.iterator();
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/collection/SetValueRange.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/collection/SetValueRange.java
@@ -5,8 +5,10 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 
+import ai.timefold.solver.core.api.domain.valuerange.ValueRange;
 import ai.timefold.solver.core.impl.domain.valuerange.AbstractCountableValueRange;
 import ai.timefold.solver.core.impl.domain.valuerange.ValueRangeCache;
+import ai.timefold.solver.core.impl.domain.valuerange.sort.ValueRangeSorter;
 
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -59,6 +61,12 @@ public boolean contains(@Nullable T value) {
         return set.contains(value);
     }
 
+    @Override
+    public ValueRange<T> sort(ValueRangeSorter<T> sorter) {
+        var sortedSet = sorter.sort(set);
+        return new SetValueRange<>(sortedSet);
+    }
+
     @Override
     public Iterator<T> createOriginalIterator() {
         return set.iterator();
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/composite/CompositeCountableValueRange.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/composite/CompositeCountableValueRange.java
@@ -4,8 +4,10 @@
 import java.util.List;
 import java.util.Random;
 
+import ai.timefold.solver.core.api.domain.valuerange.ValueRange;
 import ai.timefold.solver.core.impl.domain.valuerange.AbstractCountableValueRange;
 import ai.timefold.solver.core.impl.domain.valuerange.ValueRangeCache;
+import ai.timefold.solver.core.impl.domain.valuerange.sort.ValueRangeSorter;
 
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -18,13 +20,13 @@ public final class CompositeCountableValueRange<T> extends AbstractCountableValu
 
     public CompositeCountableValueRange(List<? extends AbstractCountableValueRange<T>> childValueRangeList) {
         var maximumSize = 0L;
-        var isValueImmutable = true;
+        var isImmutable = true;
         for (AbstractCountableValueRange<T> childValueRange : childValueRangeList) {
-            isValueImmutable &= childValueRange.isValueImmutable();
+            isImmutable &= childValueRange.isValueImmutable();
             maximumSize += childValueRange.getSize();
         }
         // To eliminate duplicates, we immediately expand the child value ranges into a cache.
-        var cacheBuilder = isValueImmutable ? ValueRangeCache.Builder.FOR_TRUSTED_VALUES
+        var cacheBuilder = isImmutable ? ValueRangeCache.Builder.FOR_TRUSTED_VALUES
                 : ValueRangeCache.Builder.FOR_USER_VALUES;
         this.cache = cacheBuilder.buildCache((int) maximumSize);
         for (var childValueRange : childValueRangeList) {
@@ -35,7 +37,12 @@ public CompositeCountableValueRange(List<? extends AbstractCountableValueRange<T
             }
             childValueRange.createOriginalIterator().forEachRemaining(cache::add);
         }
+        this.isValueImmutable = isImmutable;
+    }
+
+    private CompositeCountableValueRange(ValueRangeCache<T> cache, boolean isValueImmutable) {
         this.isValueImmutable = isValueImmutable;
+        this.cache = cache;
     }
 
     @Override
@@ -53,6 +60,12 @@ public T get(long index) {
         return cache.get((int) index);
     }
 
+    @Override
+    public ValueRange<T> sort(ValueRangeSorter<T> sorter) {
+        var sortedCache = this.cache.sort(sorter);
+        return new CompositeCountableValueRange<>(sortedCache, isValueImmutable);
+    }
+
     @Override
     public boolean contains(@Nullable T value) {
         return cache.contains(value);
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/composite/NullAllowingCountableValueRange.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/buildin/composite/NullAllowingCountableValueRange.java
@@ -4,7 +4,9 @@
 import java.util.Random;
 
 import ai.timefold.solver.core.api.domain.valuerange.CountableValueRange;
+import ai.timefold.solver.core.api.domain.valuerange.ValueRange;
 import ai.timefold.solver.core.impl.domain.valuerange.AbstractCountableValueRange;
+import ai.timefold.solver.core.impl.domain.valuerange.sort.ValueRangeSorter;
 import ai.timefold.solver.core.impl.domain.valuerange.util.ValueRangeIterator;
 import ai.timefold.solver.core.impl.solver.random.RandomUtils;
 
@@ -25,11 +27,6 @@ public NullAllowingCountableValueRange(CountableValueRange<T> childValueRange) {
         size = childValueRange.getSize() + 1L;
     }
 
-    @Override
-    public boolean isValueImmutable() {
-        return super.isValueImmutable();
-    }
-
     AbstractCountableValueRange<T> getChildValueRange() {
         return childValueRange;
     }
@@ -56,6 +53,11 @@ public boolean contains(T value) {
         return childValueRange.contains(value);
     }
 
+    @Override
+    public ValueRange<T> sort(ValueRangeSorter<T> sorter) {
+        return childValueRange.sort(sorter);
+    }
+
     @Override
     public @NonNull Iterator<T> createOriginalIterator() {
         return new OriginalNullValueRangeIterator(childValueRange.createOriginalIterator());
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/sort/SelectionSorterAdapter.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/sort/SelectionSorterAdapter.java
@@ -0,0 +1,34 @@
+package ai.timefold.solver.core.impl.domain.valuerange.sort;
+
+import java.util.List;
+import java.util.Set;
+import java.util.SortedSet;
+
+import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSetSorter;
+import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorter;
+
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+public record SelectionSorterAdapter<Solution_, T>(Solution_ solution,
+        SelectionSorter<Solution_, T> selectionSorter) implements ValueRangeSorter<T> {
+
+    public static <Solution_, T> ValueRangeSorter<T> of(Solution_ solution, SelectionSorter<Solution_, T> selectionSorter) {
+        return new SelectionSorterAdapter<>(solution, selectionSorter);
+    }
+
+    @Override
+    public void sort(List<T> selectionList) {
+        selectionSorter.sort(solution, selectionList);
+    }
+
+    @Override
+    @SuppressWarnings({ "rawtypes", "unchecked" })
+    public SortedSet<T> sort(Set<T> selectionSet) {
+        if (!(selectionSorter instanceof SelectionSetSorter selectionSetSorter)) {
+            throw new IllegalStateException(
+                    "Impossible state: the sorting operation cannot be performed because the sorter does not support sorting collection sets.");
+        }
+        return selectionSetSorter.sort(solution, selectionSet);
+    }
+}
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/sort/ValueRangeSorter.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/valuerange/sort/ValueRangeSorter.java
@@ -0,0 +1,31 @@
+package ai.timefold.solver.core.impl.domain.valuerange.sort;
+
+import java.util.List;
+import java.util.Set;
+import java.util.SortedSet;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Basic contract for sorting a range of elements.
+ * 
+ * @param <T> the value range type
+ */
+@NullMarked
+public interface ValueRangeSorter<T> {
+
+    /**
+     * Apply an in-place sorting operation.
+     * 
+     * @param selectionList never null, a {@link List} of value that will be sorted.
+     */
+    void sort(List<T> selectionList);
+
+    /**
+     * Creates a copy of the provided set and sort the data.
+     * 
+     * @param selectionSet never null, a {@link Set} of values that will be used as input for sorting.
+     */
+    SortedSet<T> sort(Set<T> selectionSet);
+
+}
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/common/decorator/ComparatorFactorySelectionSorter.java b/core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/common/decorator/ComparatorFactorySelectionSorter.java
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/common/decorator/ComparatorSelectionSorter.java b/core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/common/decorator/ComparatorSelectionSorter.java
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/common/decorator/SelectionSetSorter.java b/core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/common/decorator/SelectionSetSorter.java
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/common/decorator/SelectionSorter.java b/core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/common/decorator/SelectionSorter.java
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/score/director/ValueRangeManager.java b/core/src/main/java/ai/timefold/solver/core/impl/score/director/ValueRangeManager.java
