Skip to content

Add side effect annotations #278

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mernst merged 4 commits into from
May 26, 2026
Merged

Add side effect annotations #278

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
47ca0c6
Add side effect annotations
mernst May 26, 2026
4fd7c3e
Fixes
mernst May 26, 2026
7b82ab1
Fix
mernst May 26, 2026
2a483d4
Fix imports
mernst May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 134 additions & 1 deletion src/java.base/share/classes/java/lang/Math.java
View file
Open in desktop

Large diffs are not rendered by default.

174 changes: 174 additions & 0 deletions src/java.base/share/classes/java/lang/StrictMath.java
View file
Open in desktop

Large diffs are not rendered by default.

45 changes: 43 additions & 2 deletions src/java.base/share/classes/java/math/BigInteger.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -887,6 +887,7 @@ private static BigInteger largePrime(int bitLength, int certainty, Random rnd) {
* exhaustion of available heap space, or could run for a long time.
* @since 1.5
*/
@SideEffectFree
public BigInteger nextProbablePrime() {
if (this.signum < 0)
throw new ArithmeticException("start < 0: " + this);
Expand Down Expand Up @@ -1202,6 +1203,7 @@ private static void reportOverflow() {
* @param val value of the BigInteger to return.
* @return a BigInteger with the specified value.
*/
@SideEffectFree
public static BigInteger valueOf(long val) {
// If -MAX_CONSTANT < val < MAX_CONSTANT, return stashed constant
if (val == 0)
Expand Down Expand Up @@ -1341,6 +1343,7 @@ private static BigInteger valueOf(int[] val) {
* @param val value to be added to this BigInteger.
* @return {@code this + val}
*/
@SideEffectFree
public BigInteger add(BigInteger val) {
if (val.signum == 0)
return this;
Expand Down Expand Up @@ -1543,6 +1546,7 @@ private static int[] subtract(int[] big, long val) {
* @param val value to be subtracted from this BigInteger.
* @return {@code this - val}
*/
@SideEffectFree
public BigInteger subtract(BigInteger val) {
if (val.signum == 0)
return this;
Expand Down Expand Up @@ -1601,6 +1605,7 @@ private static int[] subtract(int[] big, int[] little) {
* @param val value to be multiplied by this BigInteger.
* @return {@code this * val}
*/
@SideEffectFree
public BigInteger multiply(BigInteger val) {
return multiply(val, false, false, 0);
}
Expand All @@ -1625,6 +1630,7 @@ public BigInteger multiply(BigInteger val) {
* @see #multiply
* @since 19
*/
@SideEffectFree
public BigInteger parallelMultiply(BigInteger val) {
return multiply(val, false, true, 0);
}
Expand Down Expand Up @@ -2427,6 +2433,7 @@ private BigInteger squareToomCook3(boolean parallel, int depth) {
* @return {@code this / val}
* @throws ArithmeticException if {@code val} is zero.
*/
@SideEffectFree
public BigInteger divide(BigInteger val) {
if (val.mag.length < BURNIKEL_ZIEGLER_THRESHOLD ||
mag.length - val.mag.length < BURNIKEL_ZIEGLER_OFFSET) {
Expand Down Expand Up @@ -2464,6 +2471,7 @@ private BigInteger divideKnuth(BigInteger val) {
* is the final element.
* @throws ArithmeticException if {@code val} is zero.
*/
@SideEffectFree
public BigInteger[] divideAndRemainder(BigInteger val) {
if (val.mag.length < BURNIKEL_ZIEGLER_THRESHOLD ||
mag.length - val.mag.length < BURNIKEL_ZIEGLER_OFFSET) {
Expand Down Expand Up @@ -2493,6 +2501,7 @@ private BigInteger[] divideAndRemainderKnuth(BigInteger val) {
* @return {@code this % val}
* @throws ArithmeticException if {@code val} is zero.
*/
@SideEffectFree
public BigInteger remainder(BigInteger val) {
if (val.mag.length < BURNIKEL_ZIEGLER_THRESHOLD ||
mag.length - val.mag.length < BURNIKEL_ZIEGLER_OFFSET) {
Expand Down Expand Up @@ -2552,6 +2561,7 @@ private BigInteger[] divideAndRemainderBurnikelZiegler(BigInteger val) {
* @throws ArithmeticException {@code exponent} is negative. (This would
* cause the operation to yield a non-integer value.)
*/
@SideEffectFree
public BigInteger pow(int exponent) {
if (exponent < 0) {
throw new ArithmeticException("Negative exponent");
Expand Down Expand Up @@ -2685,6 +2695,7 @@ public BigInteger pow(int exponent) {
* {@code sqrt(-1)}.)
* @since 9
*/
@SideEffectFree
public BigInteger sqrt() {
if (this.signum < 0) {
throw new ArithmeticException("Negative BigInteger");
Expand All @@ -2708,6 +2719,7 @@ public BigInteger sqrt() {
* @see #sqrt()
* @since 9
*/
@SideEffectFree
public BigInteger[] sqrtAndRemainder() {
BigInteger s = sqrt();
BigInteger r = this.subtract(s.square());
Expand All @@ -2723,6 +2735,7 @@ public BigInteger[] sqrtAndRemainder() {
* @param val value with which the GCD is to be computed.
* @return {@code GCD(abs(this), abs(val))}
*/
@SideEffectFree
public BigInteger gcd(BigInteger val) {
if (val.signum == 0)
return this.abs();
Expand Down Expand Up @@ -2804,6 +2817,7 @@ private static int bitLength(int[] val, int len) {
*
* @return {@code abs(this)}
*/
@SideEffectFree
public BigInteger abs() {
return (signum >= 0 ? this : this.negate());
}
Expand All @@ -2813,6 +2827,7 @@ public BigInteger abs() {
*
* @return {@code -this}
*/
@SideEffectFree
public BigInteger negate() {
return new BigInteger(this.mag, -this.signum);
}
Expand All @@ -2823,6 +2838,7 @@ public BigInteger negate() {
* @return -1, 0 or 1 as the value of this BigInteger is negative, zero or
* positive.
*/
@Pure
public @IntRange(from = -1, to = 1) int signum() {
return this.signum;
}
Expand All @@ -2839,6 +2855,7 @@ public BigInteger negate() {
* @throws ArithmeticException {@code m} &le; 0
* @see #remainder
*/
@SideEffectFree
public BigInteger mod(BigInteger m) {
if (m.signum <= 0)
throw new ArithmeticException("BigInteger: modulus not positive");
Expand All @@ -2860,6 +2877,7 @@ public BigInteger mod(BigInteger m) {
* prime</i> to {@code m}.
* @see #modInverse
*/
@SideEffectFree
public BigInteger modPow(BigInteger exponent, BigInteger m) {
if (m.signum <= 0)
throw new ArithmeticException("BigInteger: modulus not positive");
Expand Down Expand Up @@ -3421,6 +3439,7 @@ private BigInteger mod2(int p) {
* has no multiplicative inverse mod m (that is, this BigInteger
* is not <i>relatively prime</i> to m).
*/
@SideEffectFree
public BigInteger modInverse(BigInteger m) {
if (m.signum != 1)
throw new ArithmeticException("BigInteger: modulus not positive");
Expand Down Expand Up @@ -3455,6 +3474,7 @@ public BigInteger modInverse(BigInteger m) {
* @return {@code this << n}
* @see #shiftRight
*/
@SideEffectFree
public BigInteger shiftLeft(int n) {
if (signum == 0)
return ZERO;
Expand Down Expand Up @@ -3526,6 +3546,7 @@ private static void shiftLeftImplWorker(int[] newArr, int[] oldArr, int newIdx,
* @return {@code this >> n}
* @see #shiftLeft
*/
@SideEffectFree
public BigInteger shiftRight(int n) {
if (signum == 0)
return ZERO;
Expand Down Expand Up @@ -3623,6 +3644,7 @@ int[] javaIncrement(int[] val) {
* @param val value to be AND'ed with this BigInteger.
* @return {@code this & val}
*/
@SideEffectFree
public BigInteger and(BigInteger val) {
int[] result = new int[Math.max(intLength(), val.intLength())];
for (int i=0; i < result.length; i++)
Expand All @@ -3640,6 +3662,7 @@ public BigInteger and(BigInteger val) {
* @param val value to be OR'ed with this BigInteger.
* @return {@code this | val}
*/
@SideEffectFree
public BigInteger or(BigInteger val) {
int[] result = new int[Math.max(intLength(), val.intLength())];
for (int i=0; i < result.length; i++)
Expand All @@ -3657,6 +3680,7 @@ public BigInteger or(BigInteger val) {
* @param val value to be XOR'ed with this BigInteger.
* @return {@code this ^ val}
*/
@SideEffectFree
public BigInteger xor(BigInteger val) {
int[] result = new int[Math.max(intLength(), val.intLength())];
for (int i=0; i < result.length; i++)
Expand All @@ -3673,6 +3697,7 @@ public BigInteger xor(BigInteger val) {
*
* @return {@code ~this}
*/
@SideEffectFree
public BigInteger not() {
int[] result = new int[intLength()];
for (int i=0; i < result.length; i++)
Expand All @@ -3691,6 +3716,7 @@ public BigInteger not() {
* @param val value to be complemented and AND'ed with this BigInteger.
* @return {@code this & ~val}
*/
@SideEffectFree
public BigInteger andNot(BigInteger val) {
int[] result = new int[Math.max(intLength(), val.intLength())];
for (int i=0; i < result.length; i++)
Expand All @@ -3711,6 +3737,7 @@ public BigInteger andNot(BigInteger val) {
* @return {@code true} if and only if the designated bit is set.
* @throws ArithmeticException {@code n} is negative.
*/
@Pure
public boolean testBit(int n) {
if (n < 0)
throw new ArithmeticException("Negative bit address");
Expand Down Expand Up @@ -3797,6 +3824,7 @@ public BigInteger flipBit(int n) {
*
* @return index of the rightmost one bit in this BigInteger.
*/
@Pure
public int getLowestSetBit() {
int lsb = lowestSetBitPlusTwo - 2;
if (lsb == -2) { // lowestSetBit not initialized yet
Expand Down Expand Up @@ -3828,6 +3856,7 @@ public int getLowestSetBit() {
* @return number of bits in the minimal two's-complement
* representation of this BigInteger, <em>excluding</em> a sign bit.
*/
@Pure
public int bitLength() {
int n = bitLengthPlusOne - 1;
if (n == -1) { // bitLength not initialized yet
Expand Down Expand Up @@ -3862,6 +3891,7 @@ public int bitLength() {
* @return number of bits in the two's complement representation
* of this BigInteger that differ from its sign bit.
*/
@Pure
public int bitCount() {
int bc = bitCountPlusOne - 1;
if (bc == -1) { // bitCount not initialized yet
Expand Down Expand Up @@ -3932,6 +3962,7 @@ public boolean isProbablePrime(int certainty) {
* @return -1, 0 or 1 as this BigInteger is numerically less than, equal
* to, or greater than {@code val}.
*/
@Pure
public @IntRange(from = -1, to = 1) int compareTo(BigInteger val) {
if (signum == val.signum) {
return switch (signum) {
Expand Down Expand Up @@ -4053,7 +4084,6 @@ public boolean equals(@Nullable Object x) {
* {@code val}. If they are equal, either may be returned.
*/
@Pure
@StaticallyExecutable
public BigInteger min(BigInteger val) {
return (compareTo(val) < 0 ? this : val);
}
Expand All @@ -4066,7 +4096,6 @@ public BigInteger min(BigInteger val) {
* {@code val}. If they are equal, either may be returned.
*/
@Pure
@StaticallyExecutable
public BigInteger max(BigInteger val) {
return (compareTo(val) > 0 ? this : val);
}
Expand All @@ -4079,6 +4108,7 @@ public BigInteger max(BigInteger val) {
*
* @return hash code for this BigInteger.
*/
@Pure
public int hashCode() {
int hashCode = 0;

Expand All @@ -4105,6 +4135,7 @@ public int hashCode() {
* @see Character#forDigit
* @see #BigInteger(java.lang.String, int)
*/
@SideEffectFree
public String toString(@IntRange(from = 2, to = 36) int radix) {
if (signum == 0)
return "0";
Expand Down Expand Up @@ -4299,6 +4330,7 @@ private static BigInteger getRadixConversionCache(@IntRange(from = 2, to = 36) i
* @see Character#forDigit
* @see #BigInteger(java.lang.String)
*/
@SideEffectFree
public String toString() {
return toString(10);
}
Expand All @@ -4317,6 +4349,7 @@ public String toString() {
* this BigInteger.
* @see #BigInteger(byte[])
*/
@SideEffectFree
public byte[] toByteArray() {
int byteLen = bitLength()/8 + 1;
byte[] byteArray = new byte[byteLen];
Expand Down Expand Up @@ -4350,6 +4383,7 @@ public byte[] toByteArray() {
* @see #intValueExact()
* @jls 5.1.3 Narrowing Primitive Conversion
*/
@Pure
public @PolyValue int intValue(@PolyValue BigInteger this) {
int result = 0;
result = getInt(0);
Expand All @@ -4372,6 +4406,7 @@ public byte[] toByteArray() {
* @see #longValueExact()
* @jls 5.1.3 Narrowing Primitive Conversion
*/
@Pure
public @PolyValue long longValue(@PolyValue BigInteger this) {
long result = 0;

Expand All @@ -4396,6 +4431,7 @@ public byte[] toByteArray() {
* @return this BigInteger converted to a {@code float}.
* @jls 5.1.3 Narrowing Primitive Conversion
*/
@Pure
public @PolyValue float floatValue(@PolyValue BigInteger this) {
if (signum == 0) {
return 0.0f;
Expand Down Expand Up @@ -4481,6 +4517,7 @@ public byte[] toByteArray() {
* @return this BigInteger converted to a {@code double}.
* @jls 5.1.3 Narrowing Primitive Conversion
*/
@Pure
public @PolyValue double doubleValue(@PolyValue BigInteger this) {
if (signum == 0) {
return 0.0;
Expand Down Expand Up @@ -4979,6 +5016,7 @@ private byte[] magSerializedForm() {
* @see BigInteger#longValue
* @since 1.8
*/
@Pure
public long longValueExact() {
if (mag.length <= 2 && bitLength() <= 63)
return longValue();
Expand All @@ -4998,6 +5036,7 @@ public long longValueExact() {
* @see BigInteger#intValue
* @since 1.8
*/
@Pure
public int intValueExact() {
if (mag.length <= 1 && bitLength() <= 31)
return intValue();
Expand All @@ -5017,6 +5056,7 @@ public int intValueExact() {
* @see BigInteger#shortValue
* @since 1.8
*/
@Pure
public short shortValueExact() {
if (mag.length <= 1 && bitLength() <= 31) {
int value = intValue();
Expand All @@ -5038,6 +5078,7 @@ public short shortValueExact() {
* @see BigInteger#byteValue
* @since 1.8
*/
@Pure
public byte byteValueExact() {
if (mag.length <= 1 && bitLength() <= 31) {
int value = intValue();
Expand Down
2 changes: 2 additions & 0 deletions src/java.base/share/classes/java/util/AbstractCollection.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
import org.checkerframework.checker.index.qual.NonNegative;
import org.checkerframework.checker.index.qual.PolyGrowShrink;
import org.checkerframework.checker.lock.qual.GuardSatisfied;
import org.checkerframework.checker.nonempty.qual.EnsuresNonEmpty;
import org.checkerframework.checker.nonempty.qual.EnsuresNonEmptyIf;
import org.checkerframework.checker.nonempty.qual.PolyNonEmpty;
import org.checkerframework.checker.nullness.qual.Nullable;
Expand Down Expand Up @@ -276,6 +277,7 @@ private static <T> T[] finishToArray(T[] r, Iterator<?> it) {
* @throws IllegalArgumentException {@inheritDoc}
* @throws IllegalStateException {@inheritDoc}
*/
@EnsuresNonEmpty("this")
// @SideEffectsOnly("this")
@DoesNotUnrefineReceiver("modifiability")
public boolean add(@GuardSatisfied AbstractCollection<E> this, E e) {
Expand Down
Loading