refactor(reader): replace hand-rolled index guards with Objects.checkIndex (ADR 0003 Phase E)

dfa1 · claude · dfa1 · commit a5ce8380979f · 2026-06-20T08:36:15.000+02:00
The ~14 consumer-access getters in the Lazy*/Generic array families and
ExtensionStorage hand-rolled the same bounds check:

    if (i &lt; 0 || i &gt;= length) {
        throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
    }

Collapse each onto the JDK built-in Objects.checkIndex(i, length). This is the
consumer-access carve-out from ADR 0003 Phase E: a caller's bad accessor index
is consumer misuse and correctly stays IndexOutOfBoundsException (cf. List.get),
distinct from the untrusted-parse offsets that route through IoBounds and throw
VortexException. Objects.checkIndex is an @IntrinsicCandidate, so the JIT inlines
it to the same check — no regression on these scalar accessors.

12 files, 14 guards. reader 679 green; checkstyle + javadoc clean.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java
@@ -9,6 +9,7 @@
 import java.math.BigDecimal;
 import java.math.BigInteger;
 import java.nio.ByteOrder;
+import java.util.Objects;
 import java.util.Optional;
 
 /// Fallback [Array] for dtypes that lack a dedicated concrete subtype.
@@ -109,9 +110,7 @@ public Optional<MemorySegment> segmentIfPresent() {
     ///                                     shape isn't the single-buffer layout
     /// @throws IndexOutOfBoundsException if `i` is outside `[0, length())`
     public BigDecimal getDecimal(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         if (!(dtype instanceof DType.Decimal d)) {
             throw new VortexException("getDecimal called on non-decimal dtype: " + dtype);
         }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantBoolArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantBoolArray.java
@@ -2,6 +2,8 @@
 
 import io.github.dfa1.vortex.core.DType;
 
+import java.util.Objects;
+
 /// Metadata-only [BoolArray] for `vortex.constant` columns.
 ///
 /// Holds a single boolean value broadcast across `length` logical rows. No
@@ -16,9 +18,7 @@ public record LazyConstantBoolArray(DType dtype, long length, boolean value) imp
 
     @Override
     public boolean getBoolean(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         return value;
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantByteArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantByteArray.java
@@ -3,6 +3,7 @@
 import io.github.dfa1.vortex.core.DType;
 import io.github.dfa1.vortex.core.PType;
 
+import java.util.Objects;
 import java.util.function.LongBinaryOperator;
 
 /// Metadata-only [ByteArray] for `vortex.constant` columns.
@@ -19,17 +20,13 @@ public record LazyConstantByteArray(DType dtype, long length, byte value) implem
 
     @Override
     public byte getByte(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         return value;
     }
 
     @Override
     public int getInt(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         boolean unsigned = dtype instanceof DType.Primitive p && p.ptype() == PType.U8;
         return unsigned ? Byte.toUnsignedInt(value) : (int) value;
     }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantDecimalArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantDecimalArray.java
@@ -9,6 +9,7 @@
 import java.lang.foreign.ValueLayout;
 import java.math.BigDecimal;
 import java.math.BigInteger;
+import java.util.Objects;
 
 /// Metadata-only decimal array for `vortex.constant` columns.
 ///
@@ -27,9 +28,7 @@ public record LazyConstantDecimalArray(DType dtype, long length, BigDecimal valu
     /// @param i row index, `0 <= i < length`
     /// @return the constant [java.math.BigDecimal] value
     public BigDecimal getDecimal(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         return value;
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantDoubleArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantDoubleArray.java
@@ -2,6 +2,7 @@
 
 import io.github.dfa1.vortex.core.DType;
 
+import java.util.Objects;
 import java.util.function.DoubleBinaryOperator;
 import java.util.function.DoubleConsumer;
 
@@ -17,9 +18,7 @@ public record LazyConstantDoubleArray(DType dtype, long length, double value) im
 
     @Override
     public double getDouble(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         return value;
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantFloatArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantFloatArray.java
@@ -2,6 +2,7 @@
 
 import io.github.dfa1.vortex.core.DType;
 
+import java.util.Objects;
 import java.util.function.DoubleBinaryOperator;
 
 /// Metadata-only [FloatArray] for `vortex.constant` columns.
@@ -16,9 +17,7 @@ public record LazyConstantFloatArray(DType dtype, long length, float value) impl
 
     @Override
     public float getFloat(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         return value;
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantIntArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantIntArray.java
@@ -2,6 +2,7 @@
 
 import io.github.dfa1.vortex.core.DType;
 
+import java.util.Objects;
 import java.util.function.IntBinaryOperator;
 import java.util.function.IntConsumer;
 
@@ -18,9 +19,7 @@ public record LazyConstantIntArray(DType dtype, long length, int value) implemen
 
     @Override
     public int getInt(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         return value;
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantLongArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantLongArray.java
@@ -2,6 +2,7 @@
 
 import io.github.dfa1.vortex.core.DType;
 
+import java.util.Objects;
 import java.util.function.LongBinaryOperator;
 import java.util.function.LongConsumer;
 
@@ -22,9 +23,7 @@ public record LazyConstantLongArray(DType dtype, long length, long value) implem
 
     @Override
     public long getLong(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         return value;
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantShortArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantShortArray.java
@@ -3,6 +3,7 @@
 import io.github.dfa1.vortex.core.DType;
 import io.github.dfa1.vortex.core.PType;
 
+import java.util.Objects;
 import java.util.function.LongBinaryOperator;
 
 /// Metadata-only [ShortArray] for `vortex.constant` columns.
@@ -19,17 +20,13 @@ public record LazyConstantShortArray(DType dtype, long length, short value) impl
 
     @Override
     public short getShort(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         return value;
     }
 
     @Override
     public int getInt(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         boolean unsigned = dtype instanceof DType.Primitive p && p.ptype() == PType.U16;
         return unsigned ? Short.toUnsignedInt(value) : (int) value;
     }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java
@@ -9,6 +9,7 @@
 import java.math.BigDecimal;
 import java.math.BigInteger;
 import java.nio.ByteOrder;
+import java.util.Objects;
 import java.util.Optional;
 
 /// Lazy `vortex.decimal` array.
@@ -40,9 +41,7 @@ public record LazyDecimalArray(DType dtype, long length, MemorySegment buf, int
     /// @throws VortexException             if the dtype isn't a [DType.Decimal]
     /// @throws IndexOutOfBoundsException if `i` is outside `[0, length())`
     public BigDecimal getDecimal(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         if (!(dtype instanceof DType.Decimal d)) {
             throw new VortexException("LazyDecimalArray: non-decimal dtype " + dtype);
         }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java
@@ -6,6 +6,7 @@
 import java.lang.foreign.MemorySegment;
 import java.lang.foreign.SegmentAllocator;
 import java.math.BigDecimal;
+import java.util.Objects;
 
 /// Lazy `vortex.decimal_byte_parts` reassembly.
 ///
@@ -30,9 +31,7 @@ public record LazyDecimalBytePartsArray(DType dtype, long length, Array msp) imp
     ///                                     mantissa cell is null
     /// @throws IndexOutOfBoundsException if `i` is outside `[0, length())`
     public BigDecimal getDecimal(long i) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
         if (!(dtype instanceof DType.Decimal d)) {
             throw new VortexException("LazyDecimalBytePartsArray: non-decimal dtype " + dtype);
         }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java
@@ -12,6 +12,7 @@
 
 import java.nio.ByteBuffer;
 import java.time.Instant;
+import java.util.Objects;
 
 /// Low-level storage helpers for extension decode paths.
 public final class ExtensionStorage {
@@ -87,8 +88,6 @@ public static Instant instantFromRaw(long raw, TimeUnit unit) {
     /// @param i      row index to check
     /// @param length array length
     public static void checkBounds(long i, long length) {
-        if (i < 0 || i >= length) {
-            throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
-        }
+        Objects.checkIndex(i, length);
     }
 }
