feat: add replaceValue... methods to MutableSolutionView (#2180)

triceo · web-flow · commit 6c99a5b6ed5f · 2026-03-13T08:00:14.000+01:00
In addition to moveValue...
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/move/MoveDirector.java b/core/src/main/java/ai/timefold/solver/core/impl/move/MoveDirector.java
@@ -1,5 +1,7 @@
 package ai.timefold.solver.core.impl.move;
 
+import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
 import java.util.function.BiFunction;
@@ -197,6 +199,29 @@ public final <Entity_, Value_> Value_ moveValueBetweenLists(
         return element;
     }
 
+    @Override
+    public <Entity_, Value_> Value_ replaceValue(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
+            Entity_ sourceEntity, int sourceIndex, Entity_ destinationEntity, int destinationIndex) {
+        if (destinationEntity == sourceEntity) {
+            return replaceValue(variableMetaModel, sourceEntity, sourceIndex, destinationIndex);
+        }
+
+        var variableDescriptor = extractVariableDescriptor(variableMetaModel);
+        var toReplace = (Value_) variableDescriptor.getElement(destinationEntity, destinationIndex);
+        externalScoreDirector.beforeListVariableElementUnassigned(variableDescriptor, toReplace);
+        externalScoreDirector.beforeListVariableChanged(variableDescriptor, destinationEntity, destinationIndex,
+                destinationIndex + 1);
+        externalScoreDirector.beforeListVariableChanged(variableDescriptor, sourceEntity, sourceIndex, sourceIndex + 1);
+        var toMove = variableDescriptor.removeElement(sourceEntity, sourceIndex);
+        variableDescriptor.setElement(destinationEntity, destinationIndex, toMove);
+        externalScoreDirector.afterListVariableChanged(variableDescriptor, sourceEntity, sourceIndex, sourceIndex);
+        externalScoreDirector.afterListVariableChanged(variableDescriptor, destinationEntity, destinationIndex,
+                destinationIndex + 1);
+        externalScoreDirector.afterListVariableElementUnassigned(variableDescriptor, toReplace);
+        externalScoreDirector.triggerVariableListeners();
+        return toReplace;
+    }
+
     @SuppressWarnings("unchecked")
     @Override
     public final <Entity_, Value_> Value_ moveValueInList(
@@ -207,32 +232,104 @@ public final <Entity_, Value_> Value_ moveValueInList(
                     "When moving values in the same list, sourceIndex (%d) and destinationIndex (%d) must be different."
                             .formatted(sourceIndex, destinationIndex));
         } else if (sourceIndex < 0 || destinationIndex < 0) {
-            throw new IllegalArgumentException(
-                    "The sourceIndex (%d) and destinationIndex (%d) must both be >= 0."
-                            .formatted(sourceIndex, destinationIndex));
+            throw new IndexOutOfBoundsException("The sourceIndex (%d) and destinationIndex (%d) must both be >= 0."
+                    .formatted(sourceIndex, destinationIndex));
         }
 
-        var fromIndex = Math.min(sourceIndex, destinationIndex);
-        var toIndex = Math.max(sourceIndex, destinationIndex) + 1;
-
         var variableDescriptor = extractVariableDescriptor(variableMetaModel);
         var list = variableDescriptor.getValue(sourceEntity);
         var listSize = list.size();
         if (sourceIndex >= listSize) {
-            throw new IllegalArgumentException(
-                    "The sourceIndex (%d) must be less than the list size (%d).".formatted(sourceIndex, listSize));
-        } else if (destinationIndex > listSize) { // destinationIndex == listSize is allowed (append to the end of the list)
-            throw new IllegalArgumentException(
-                    "The destinationIndex (%d) must be less than or equal to the list size (%d)."
-                            .formatted(destinationIndex, listSize));
+            throw new IndexOutOfBoundsException("The sourceIndex (%d) must be less than the list size (%d)."
+                    .formatted(sourceIndex, listSize));
+        } else if (destinationIndex >= listSize) {
+            throw new IndexOutOfBoundsException("The destinationIndex (%d) must be less than the list size (%d)."
+                    .formatted(destinationIndex, listSize));
         }
 
+        var fromIndex = Math.min(sourceIndex, destinationIndex);
+        var toIndex = Math.max(sourceIndex, destinationIndex) + 1;
         externalScoreDirector.beforeListVariableChanged(variableDescriptor, sourceEntity, fromIndex, toIndex);
-        var element = (Value_) list.remove(sourceIndex);
-        list.add(destinationIndex, element);
+        moveInList(list, sourceIndex, destinationIndex);
         externalScoreDirector.afterListVariableChanged(variableDescriptor, sourceEntity, fromIndex, toIndex);
         externalScoreDirector.triggerVariableListeners();
-        return element;
+        return (Value_) list.get(destinationIndex);
+    }
+
+    @Override
+    public <Entity_, Value_> Value_ replaceValue(
+            PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel, Entity_ entity, int sourceIndex,
+            int destinationIndex) {
+        if (sourceIndex == destinationIndex) {
+            throw new IllegalArgumentException(
+                    "When replacing values in the same list, sourceIndex (%d) and destinationIndex (%d) must be different."
+                            .formatted(sourceIndex, destinationIndex));
+        } else if (sourceIndex < 0 || destinationIndex < 0) {
+            throw new IndexOutOfBoundsException("The sourceIndex (%d) and destinationIndex (%d) must both be >= 0."
+                    .formatted(sourceIndex, destinationIndex));
+        }
+
+        var variableDescriptor = extractVariableDescriptor(variableMetaModel);
+        var fromIndex = Math.min(sourceIndex, destinationIndex);
+        var toIndex = Math.max(sourceIndex, destinationIndex) + 1;
+        var list = variableDescriptor.getValue(entity);
+        var toReplace = (Value_) list.get(destinationIndex);
+        externalScoreDirector.beforeListVariableElementUnassigned(variableDescriptor, toReplace);
+        externalScoreDirector.beforeListVariableChanged(variableDescriptor, entity, fromIndex, toIndex);
+        if (destinationIndex > sourceIndex) {
+            // Remove from sourceIndex after setting the destination to preserve index validity.
+            list.set(destinationIndex, list.get(sourceIndex));
+            list.remove(sourceIndex);
+        } else {
+            list.set(destinationIndex, list.remove(sourceIndex));
+        }
+        externalScoreDirector.afterListVariableChanged(variableDescriptor, entity, fromIndex, toIndex - 1);
+        externalScoreDirector.afterListVariableElementUnassigned(variableDescriptor, toReplace);
+        externalScoreDirector.triggerVariableListeners();
+        return toReplace;
+    }
+
+    /**
+     * Moves the element at index {@code from} to index {@code to} in a list,
+     * choosing the faster of two strategies based on the move's distance and position within the list.
+     *
+     * <p>
+     * <b>Strategy selection</b> (lo = min(from, to), d = |from − to|):
+     * <ul>
+     * <li>Use {@code Collections.rotate} when {@code d * 8 < n − lo}
+     * (distance is small relative to the remaining tail).</li>
+     * <li>Use {@code remove + add} otherwise.</li>
+     * </ul>
+     *
+     * <p>
+     * <b>Why position matters</b>: {@code remove+add} shifts {@code (n−1−from) + (n−1−to)} elements in total.
+     * When one endpoint is near the tail, one of those copies is nearly free,
+     * making {@code remove+add} cheap even for large lists.
+     * {@code rotate} always pays for the full sublist span,
+     * so it only wins when that span is short relative to what {@code removeAdd} would have to copy.
+     *
+     * <p>
+     * The threshold constant 8 was determined empirically by benchmarking on HotSpot
+     * with a microbenchmark that performed moves of varying distances and positions within lists of varying sizes.
+     *
+     * @param list the list to mutate; assumes {@link ArrayList}
+     * @param from index of the element to move
+     * @param to index the element should occupy after the move
+     */
+    private static <T> void moveInList(List<T> list, int from, int to) {
+        var distance = Math.abs(from - to);
+        if (distance == 1) {
+            Collections.swap(list, from, to);
+            return;
+        }
+        var distanceTimesEight = distance * 8L; // Long prevents unlikely yet possible overflow.
+        var lowerIndex = Math.min(from, to);
+        var tailLength = list.size() - lowerIndex;
+        if (distanceTimesEight < tailLength) {
+            Collections.rotate(list.subList(lowerIndex, lowerIndex + distance + 1), from < to ? -1 : 1);
+        } else {
+            list.add(to, list.remove(from));
+        }
     }
 
     @Override
@@ -276,15 +373,11 @@ public <Entity_, Value_> void swapValuesInList(PlanningListVariableMetaModel<Sol
         }
 
         var variableDescriptor = extractVariableDescriptor(variableMetaModel);
-        var leftElement = variableDescriptor.getElement(entity, leftIndex);
-        var rightElement = variableDescriptor.getElement(entity, rightIndex);
-
         var fromIndex = Math.min(leftIndex, rightIndex);
         var toIndex = Math.max(leftIndex, rightIndex) + 1;
         externalScoreDirector.beforeListVariableChanged(variableDescriptor, entity, fromIndex, toIndex);
         var list = variableDescriptor.getValue(entity);
-        list.set(leftIndex, rightElement);
-        list.set(rightIndex, leftElement);
+        Collections.swap(list, leftIndex, rightIndex);
         externalScoreDirector.afterListVariableChanged(variableDescriptor, entity, fromIndex, toIndex);
         externalScoreDirector.triggerVariableListeners();
     }
diff --git a/core/src/main/java/ai/timefold/solver/core/preview/api/move/MutableSolutionView.java b/core/src/main/java/ai/timefold/solver/core/preview/api/move/MutableSolutionView.java
@@ -131,7 +131,6 @@ <Entity_, Value_> void unassignValue(PlanningListVariableMetaModel<Solution_, En
      *        Acceptable values range from zero to one less than list size.
      *        All values after the index are shifted to the left.
      * @return the removed value
-     * @throws IndexOutOfBoundsException if the index is out of bounds
      */
     <Entity_, Value_> Value_ unassignValue(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
             Entity_ entity, int index);
@@ -171,12 +170,44 @@ <Entity_, Value_> void changeVariable(PlanningVariableMetaModel<Solution_, Entit
      *        All values at or after the index are shifted to the right.
      *        To append to the end of the list, use the list size as index.
      * @return the value that was moved
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if sourceEntity == destinationEntity
      */
     <Entity_, Value_> Value_ moveValueBetweenLists(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
             Entity_ sourceEntity, int sourceIndex, Entity_ destinationEntity, int destinationIndex);
 
+    /**
+     * Replaces a value in one entity's {@link PlanningListVariable planning list variable} with a value taken from another.
+     * The value is removed from {@code sourceEntity} at {@code sourceIndex}, shifting all later values to the left.
+     * The removed value is then assigned to {@code destinationEntity} at {@code destinationIndex},
+     * overwriting the pre-existing value and unassigning it.
+     * This means that the sourceEntity's list will be one item shorter after the move,
+     * while the destinationEntity's list size remains unchanged.
+     *
+     * @param variableMetaModel Describes the variable to be changed.
+     * @param sourceEntity The entity from which the replacement value will be taken and removed.
+     * @param sourceIndex The index in the sourceEntity's list variable which contains the value to be moved and
+     *        removed;
+     *        Acceptable values range from zero to one less than the source list size.
+     *        All values at or after the index are shifted to the left.
+     * @param destinationEntity The entity in which the value at {@code destinationIndex} will be replaced (overwritten).
+     * @param destinationIndex The index in the destinationEntity's list variable whose current value will be overwritten;
+     *        Acceptable values range from zero to one less than the destination list size.
+     * @return the value that was replaced
+     * @see #moveValueBetweenLists(PlanningListVariableMetaModel, Object, int, Object, int) Similar operation that moves the
+     *      value to the destination without removing the pre-existing value.
+     */
+    <Entity_, Value_> Value_ replaceValue(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
+            Entity_ sourceEntity, int sourceIndex, Entity_ destinationEntity, int destinationIndex);
+
+    /**
+     * As defined by {@link #replaceValue(PlanningListVariableMetaModel, Object, int, Object, int)},
+     * but using {@link PositionInList} to specify the positions.
+     */
+    default <Entity_, Value_> Value_ replaceValue(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
+            PositionInList source, PositionInList destination) {
+        return replaceValue(variableMetaModel, source.entity(), source.index(), destination.entity(), destination.index());
+    }
+
     /**
      * As defined by {@link #moveValueBetweenLists(PlanningListVariableMetaModel, Object, int, Object, int)},
      * but using {@link PositionInList} to specify the source and destination positions.
@@ -205,14 +236,47 @@ default <Entity_, Value_> Value_ moveValueBetweenLists(
      *        Acceptable values range from zero to one less than list size.
      *        All values at or after the index are shifted to the right.
      * @return the value that was moved
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if sourceIndex == destinationIndex
+     * @see #replaceValue(PlanningListVariableMetaModel, Object, int, int) Similar operation that replaces the value at
+     *      the destination index instead.
      * @see #shiftValue(PlanningListVariableMetaModel, Object, int, int) Equivalent operation using offset calculation instead
      *      of index arithmetics.
      */
     <Entity_, Value_> Value_ moveValueInList(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
             Entity_ sourceEntity, int sourceIndex, int destinationIndex);
 
+    /**
+     * Moves a value within one entity's {@link PlanningListVariable planning list variable}.
+     * Behaves as if the value is first put in the destinationIndex,
+     * and then removed from the sourceIndex, shifting all later values to the left
+     * The value previously at the destinationIndex is unassigned.
+     *
+     * @param variableMetaModel Describes the variable to be changed.
+     * @param entity The entity in which the value at {@code destinationIndex} will be replaced (overwritten).
+     * @param sourceIndex The index in the entity's list variable which contains the value to be moved and removed;
+     *        Acceptable values range from zero to one less than the list size.
+     *        All values at or after the index are shifted to the left.
+     * @param destinationIndex The index in the entity's list variable whose current value will be overwritten;
+     *        Acceptable values range from zero to one less than the list size.
+     * @return the value that was replaced
+     * @throws IllegalArgumentException if sourceIndex == destinationIndex
+     * @see #moveValueInList(PlanningListVariableMetaModel, Object, int, int) Similar operation that moves the value to the
+     *      destination index instead.
+     * @see #shiftValue(PlanningListVariableMetaModel, Object, int, int) Equivalent operation using offset calculation instead
+     *      of index arithmetic.
+     */
+    <Entity_, Value_> Value_ replaceValue(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
+            Entity_ entity, int sourceIndex, int destinationIndex);
+
+    /**
+     * As defined by {@link #replaceValue(PlanningListVariableMetaModel, Object, int, int)},
+     * but using {@link PositionInList} to specify the source position.
+     */
+    default <Entity_, Value_> Value_ replaceValue(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
+            PositionInList source, int destinationIndex) {
+        return replaceValue(variableMetaModel, source.entity(), source.index(), destinationIndex);
+    }
+
     /**
      * Moves a value within one entity's {@link PlanningListVariable planning list variable},
      * by the given offset.
@@ -225,7 +289,6 @@ <Entity_, Value_> Value_ moveValueInList(PlanningListVariableMetaModel<Solution_
      *        The offset must not be zero.
      *        The offset must not move the value out of bounds.
      * @return the value that was moved
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if sourceIndex == destinationIndex
      * @see #moveValueInList(PlanningListVariableMetaModel, Object, int, int) Equivalent operation using index arithmetics
      *      instead of offset calculation.
@@ -252,7 +315,6 @@ default <Entity_, Value_> Value_ shiftValue(PlanningListVariableMetaModel<Soluti
      * @param rightEntity The second entity whose variable value is to be swapped.
      * @param rightIndex The index in the right entity's list variable which contains the other value to be swapped;
      *        Acceptable values range from zero to one less than list size.
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if leftEntity == rightEntity while leftIndex == rightIndex
      */
     <Entity_, Value_> void swapValuesBetweenLists(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
@@ -267,7 +329,6 @@ <Entity_, Value_> void swapValuesBetweenLists(PlanningListVariableMetaModel<Solu
      *        Acceptable values range from zero to one less than list size.
      * @param rightIndex The index in the entity's list variable which contains the other value to be swapped;
      *        Acceptable values range from zero to one less than list size.
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if leftIndex == rightIndex
      */
     <Entity_, Value_> void swapValuesInList(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
diff --git a/core/src/test/java/ai/timefold/solver/core/impl/move/MoveDirectorTest.java b/core/src/test/java/ai/timefold/solver/core/impl/move/MoveDirectorTest.java
