ShapeRefC: add a length field with accessor and runtime checks

Author: stephengold

src/main/java/com/github/stephengold/joltjni/ShapeRefCArray.java

@@ -28,6 +28,13 @@ of this software and associated documentation files (the "Software"), to deal
  * @author xI-Mx-Ix
  */
 public class ShapeRefCArray extends JoltPhysicsObject {
+    // *************************************************************************
+    // fields
+
+    /**
+     * length (in references)
+     */
+    final private int length;
     // *************************************************************************
     // constructors
 
@@ -39,6 +46,7 @@ public class ShapeRefCArray extends JoltPhysicsObject {
     public ShapeRefCArray(int length) {
         assert length > 0 : "length=" + length;
 
+        this.length = length;
         long arrayVa = create(length);
         setVirtualAddress(arrayVa, () -> free(arrayVa));
     }
@@ -48,24 +56,40 @@ public ShapeRefCArray(int length) {
     /**
      * Access the reference at the specified index.
      *
-     * @param elementIndex the index (≥0)
+     * @param elementIndex the index (≥0, <length)
      * @return a new JVM object with the pre-existing native object assigned
      */
     public ShapeRefC get(int elementIndex) {
+        assert elementIndex >= 0 && elementIndex < length :
+                "Out of range:  index=" + elementIndex + " length=" + length;
+
         long arrayVa = va();
         long refVa = getRef(arrayVa, elementIndex);
         ShapeRefC result = new ShapeRefC(this, refVa);
 
         return result;
     }
 
+    /**
+     * Return the length of the array.
+     *
+     * @return the length (in references, &gt;0)
+     */
+    public int length() {
+        return length;
+    }
+
     /**
      * Store the specified reference at the specified index.
      *
-     * @param elementIndex the index at which to store the reference (&ge;0)
+     * @param elementIndex the index at which to store the reference (&ge;0,
+     * &lt;length)
      * @param ref the reference to store (not {@code null}, unaffected)
      */
     public void set(int elementIndex, ShapeRefC ref) {
+        assert elementIndex >= 0 && elementIndex < length :
+                "Out of range:  index=" + elementIndex + " length=" + length;
+
         long arrayVa = va();
         long refVa = ref.va();
         setRef(arrayVa, elementIndex, refVa);