Skip to content

Fix IntegerSequence range boundary iteration - #335

Open
SC-10749 wants to merge 9 commits into
apache:masterfrom
SC-10749:bugfix/integer-sequence-boundaries
Open

SC-10749 wants to merge 9 commits into
apache:masterfrom
SC-10749:bugfix/integer-sequence-boundaries

Conversation

@SC-10749

@SC-10749 SC-10749 commented Oct 22, 2026 •

Copy link
Copy Markdown

Summary

  • Keep Range.iterator() backed by IntegerSequence.Incrementor.
  • Fix counter overflow and exhaustion behavior, including ranges whose final increment passes the limit.
  • Clamp the incrementor count to the configured limit when the iterator is exhausted.
  • Add increasing and decreasing range regressions for the clamped count.

Validation

  • IntegerSequenceTest: 31 tests passed.
  • commons-math-legacy-core: all 305 tests passed with no failures or errors.
  • git diff --check passed.
  • Full mvn -B -ntp clean verify was attempted. UnivariatePeriodicInterpolatorTest.testSine fails in commons-math-legacy; the same failure was reproduced with the pre-PR IntegerSequence implementation.
  • GitHub currently reports no checks for this branch.

@aherbert

Copy link
Copy Markdown
Contributor

Thanks for the PR. The tests are valid. The code change should apply the fix to the Incrementor class. This change drops use of the Incrementor and creates a new Iterator implementation. Downstream classes that use the Incrementor will not benefit from the change.

@SC-10749

Copy link
Copy Markdown
Author

Thanks for the PR. The tests are valid. The code change should apply the fix to the Incrementor class. This change drops use of the Incrementor and creates a new Iterator implementation. Downstream classes that use the Incrementor will not benefit from the change.

Thanks for your review and feedback! I understand your point.
I will revise the fix directly inside the Incrementor class instead of introducing a new Iterator implementation, so that all downstream classes relying on Incrementor can get this fix.
I'll push the updated changes soon.

@aherbert aherbert left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update. Using a long count is fine but we must be sure not to increment it beyond the maximal count. If we do then the getCount method should return the maximal count, not a 32-bit truncation of the long.

I've added some notes on possible changes to improve the class.

}

count += nTimes * increment;
count += (long) nTimes * increment;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is existing strange behaviour in the IntegerSequence. It updates the member count then checks if any more are allowed. The purpose is to allow multiple increments when at least 1 increment is possible, and then check if multiple have exhausted the sequence to trigger the callback. But the sequence does not actually check if even 1 increment is possible. I would be inclined to refactor canIncrement to not call canincrement(1) but to directly check the current count:

public boolean canIncrement() {
    // Adjust as required for your new inclusive parameter
    return increment < 0 ?
        count > maximalCount :
        count < maximalCount;
}

This method can be called before any modification of the count member. This prevents successive calls to increment(int) from increasing the count far above the maximum allowed.

This is how broken the counter is:

IntegerSequence.Incrementor inc =
    IntegerSequence.Incrementor
        .create()
        .withIncrement(1 << 30)
        .withStart(0)
        .withMaximalCount(1 << 30)
        .withCallback(i -> {});
for (int i = 0; i < 10; i++) {
    inc.increment(1);
    System.out.println(inc.getCount());
}

prints:

1073741824
-2147483648
-1073741824
0
1073741824
-2147483648
-1073741824
0
1073741824
-2147483648

By changing the count to a long we will not get this behaviour any more. It will just keep incrementing the long. A request for the count using getCount will use the 32-bit truncation of the long, and possibly return 0 or a negative value for a positive integer sequence depending on where the long count has reached.

*/
public int getCount() {
return count;
return (int) count;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be documented as returning the current count, or maximalCount if the sequence has exhausted the configured range. This would match the behaviour of the value passed to the callback when the sequence is exhausted.

Then fix the return. Using a 32-bit truncation of a long can return nonsense results (see comment on increment(int).

@@ -354,7 +378,7 @@
@Override
public Integer next() {
if (canIncrement(0)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Call canIncrement()

this.start = start;
this.max = max;
this.step = step;
this.step = Incrementor.checkIncrement(step);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need more validation here. The step should be appropriately signed to match the sign of the difference (max - start). Otherwise you get stupid behaviour:

IntegerSequence.Incrementor inc =
    IntegerSequence.Incrementor
        .create()
        .withStart(0)
        .withMaximalCount(1)
        .withIncrement(-1)
        .withCallback(i -> {});
for (int i = 0; i < 10; i++) {
    inc.increment(1);
    System.out.println(inc.getCount());
}

prints

-1
-2
-3
-4
-5
-6
-7
-8
-9
-10

Without the callback which ignores the sequence exhaustion then this raises an exception immediately as the count is updated to -1 and the check to test for a negative increment if the count is above the maximal count fails.


final int s = (max - start) / step + 1;
final int s = (max - start) / this.step + 1;
this.size = s < 0 ? 0 : s;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will be negative if (max - start) overflows a positive integer. I think in this case the result should be set at Integer.MAX_VALUE not 0.

}

/**
* Gets the number of elements contained in the range.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be documented to return a positive value in [0, Integer.MAX_VALUE]. It should be noted that the size may be larger than this if the range between the maximalCount and the start cannot be represented as a positive integer.

@aherbert aherbert left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If an exhausted flag is being used then it should be the reference for whether the iterator can continue. There is duplication of logic to check exhausted that should be refactored to a single method.

*/
public boolean canIncrement() {
return canIncrement(1);
if (exhausted) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the count is only ever changed in conjunction with checking for exhaustion, can this simply return the value of the exhausted flag?

}

if (!canIncrement(0)) {
if (exhausted || !canIncrement(0)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should not have to call canIncrement(0) as the exhausted flag has been set.

*/
public boolean canIncrement(int nTimes) {
final int finalCount = count + nTimes * increment;
final long finalCount = count + (long) nTimes * increment;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This logic should be captured once in a method:

private static boolean isExhausted(long newCount) {
    if (inclusive) {
        return increment < 0 ?
            newCount >= maximalCount :
            newCount <= maximalCount;
    }
    return increment < 0 ?
        newCount > maximalCount :
        newCount < maximalCount;
}

The method should be called from canIncrement(int nTimes), and also to set the exhausted flag within increment() and increment(int). If the count is only ever changed and the exhausted flag updated at the same time, then it can be used within canIncrement(). This should not impact any iterator as the logic is invoked once, just at a different time in the iteration of hasNext() and next().

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This logic should be in a method isExhausted(long)

@SC-10749

Copy link
Copy Markdown
Author

Updated in commit 07e1c25. The Incrementor now uses the exhausted flag through the single canIncrement(int) path: canIncrement() delegates to canIncrement(0), and repeated exhaustion checks use canIncrement(). No other files were changed in this update. Local Maven execution remains blocked by the current Java/Maven environment, but git diff --check passed.

@aherbert aherbert left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The logic to check exhausted must be centralised. It can be used to check if an increment of nTimes triggered the count exceeded callback in the current increment by using an equivalent of isExhausted(count + increment * (nTimes - 1)).

}

final long newCount = count + (long) nTimes * increment;
if (increment < 0 ? newCount <= maximalCount : newCount >= maximalCount) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not use the inclusive flag. If you refactor the check for exhausted to a method this should use:

if (isExhausted(newCount)) {

This sets the behaviour for the futher calls to the instance (canIncrement, increment; and next).

*/
public boolean canIncrement(int nTimes) {
final int finalCount = count + nTimes * increment;
final long finalCount = count + (long) nTimes * increment;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This logic should be in a method isExhausted(long)

*/
public boolean canIncrement() {
return canIncrement(1);
return canIncrement(0);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should return !exhausted.

final boolean crossedLimit = increment < 0 ?
(inclusive ? newCount < maximalCount : newCount <= maximalCount) :
(inclusive ? newCount > maximalCount : newCount >= maximalCount);
if (inclusive && value == maximalCount || crossedLimit) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should use isExhausted(newCount)

}

if (!canIncrement(0)) {
if (!canIncrement()) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This must trigger if the current call exceeded the allowed maximum. This is the reason for the canIncrement(0) logic in the original code.

In the logic above the exhausted flag is set to determine the behaviour for further calls. To determine the behaviour for this call we must use the newCount flag and check if it went beyond the allowed limit. This is equivalent to checking if an increment (nTimes - 1) would prevent further increment. So we can call:

if (isExhausted(newCount - increment)) {
    // An increment of (nTimes - 1) would reach the limit ...

This is overly complex for the increment() logic as it would always be false for this check when it calls increment(1). So that method can be updated to have an implementation:

public void increment() {
    if (exhausted) {
        maxCountCallback.trigger(maximalCount);
        return;
    }
    final long newCount = count + increment;
    if (isExhausted(newCount)) {
        count = maximalCount;
        // Set behaviour for further calls
        exhausted = true;
    } else {
        count = newCount;
    }
}

}

if (!canIncrement()) {
if (isExhausted(newCount) || isExhausted(newCount - increment)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replace isExhausted(newCount) with exhausted

}

/**
* Checks whether incrementing the counter {@code nTimes} is allowed.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you fix this javadoc. It refers to nTimes which is not related to this method.

I think the javadoc is wrong. It should state that the result is true if the counter is not exhausted, i.e. the count is below the configured maximum. A call to increment is allowed but it may trigger the max count callback if the next increment causes the count to reach the configured limit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants