carray 3.0.2 → 3.0.4

data/ext/carray_index_classifier.c

@@ -14,13 +14,15 @@
     - a single negative-index normaliser used by all handlers
     - fast paths (POINT / ADDRESS, ndim == argc, all-FIXNUM) at
       the top of the entry point
-    - single-character alphabetic Symbols (:a-:z / :A-:Z) reserved
-      for future contraction notation; the classifier raises
-      NotImplementedError when they appear.
+    - single-character alphabetic Symbols (:a-:z / :A-:Z) are
+      reserved and kept free of meaning; the classifier raises
+      IndexError when they appear.
 
 --------------------------------------------------------------------------- */
 
 #include "carray.h"
+#include <math.h>
+#include "carray_internal.h"   /* ca_index_in_range_at */
 #include "carray_index_classifier.h"
 
 /* Range accessor macros — carray_access.c keeps a private cache
@@ -85,17 +87,42 @@ typedef struct {
 static inline ca_size_t
 ca_classifier_normalize_axis_index (ca_size_t k, ca_size_t dim, int axis, int range_check)
 {
+  ca_size_t given = k;
   if ( k < 0 ) {
     k += dim;
   }
   if ( range_check && ( k < 0 || k >= dim ) ) {
-    rb_raise(rb_eIndexError,
-             "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-             axis, (ca_size_t) k, (ca_size_t) (dim - 1));
+    ca_index_out_of_range_at(given, dim, axis);
   }
   return k;
 }
 
+/* Whether a range picks no cells along an axis of length dim: an exclusive
+   range that ends where it starts, or an endless one that starts at the end
+   of the axis.  `last` has been counted from the end already; `start` has
+   not.  A range in CArray otherwise always picks a cell -- one ending
+   before its start reads backwards. */
+static inline int
+ca_classifier_range_is_empty (ca_size_t start, ca_size_t last, int excl,
+                              int endless, ca_size_t dim)
+{
+  ca_size_t s = ( start < 0 ) ? start + dim : start;
+  return endless ? ( s == dim ) : ( excl && s == last );
+}
+
+/* The first index of a run of cells along an axis.  A run of no cells may
+   start at the end of the axis (position n), as an empty slice at the end
+   of a Ruby Array does; a run with cells has to start on one. */
+static inline ca_size_t
+ca_classifier_run_start (ca_size_t idx, ca_size_t n, int axis, int empty)
+{
+  ca_size_t i = ( idx < 0 ) ? idx + n : idx;
+  if ( i < 0 || i > n || ( ! empty && i == n ) ) {
+    ca_index_out_of_range_at(idx, n, axis);
+  }
+  return i;
+}
+
 /* Flat-address normalisation for the `argc == 1, ndim > 1,
    Integer` path.  CA_CHECK_INDEX does not carry axis info in its
    message, which is the intended behaviour on the flat path. */
@@ -108,6 +135,129 @@ ca_classifier_normalize_flat_address (ca_size_t addr, ca_size_t elements, int ra
   return addr;
 }
 
+NORETURN(static void ca_classifier_invalid_key (VALUE v, int axis));
+static void
+ca_classifier_invalid_key (VALUE v, int axis)
+{
+  volatile VALUE s = rb_inspect(v);
+  rb_raise(rb_eIndexError,
+           "%s: object '%s' is invalid for the index for reference at %i-dim",
+           ca_calling_method_name(), StringValueCStr(s), axis);
+}
+
+/* An Integer past int64 is past the end of any axis, but has no ca_size_t
+   to report through ca_index_out_of_range_at; it is reported as given. */
+NORETURN(static void ca_classifier_key_too_large (VALUE v, const char *where));
+static void
+ca_classifier_key_too_large (VALUE v, const char *where)
+{
+  volatile VALUE s = rb_inspect(v);
+  rb_raise(rb_eIndexError, "%s: index %s is out of range%s",
+           ca_calling_method_name(), StringValueCStr(s), where);
+}
+
+/* A key names a position when it holds an integer that fits ca_size_t
+   (int64): an Integer of that size, Bignum included (an axis of a view that
+   holds no memory can be longer than a Fixnum reaches), or a Float with no
+   fraction while it is exact (|v| <= 2**53; past that it cannot tell
+   neighbouring integers apart, and a count from `sum` is a Float).
+   Returns 1 with the position in *out, 2 for an Integer past int64 (past
+   every axis, which is no longer than int64), and 0 for anything else (a
+   Float with a fraction or past 2**53, NaN, Inf, a Rational, a String). */
+static int
+ca_classifier_key_position (VALUE v, ca_size_t *out)
+{
+  if ( FIXNUM_P(v) ) {
+    *out = (ca_size_t) FIX2LONG(v);
+    return 1;
+  }
+  if ( RB_FLOAT_TYPE_P(v) ) {
+    double d = RFLOAT_VALUE(v);
+    if ( isfinite(d) && d == floor(d) && fabs(d) <= 9007199254740992.0 ) {
+      *out = (ca_size_t) d;
+      return 1;
+    }
+    return 0;
+  }
+  if ( RB_TYPE_P(v, T_BIGNUM) ) {
+    uint64_t mag;
+    int sign = rb_integer_pack(v, &mag, 1, sizeof(mag), 0,
+                               INTEGER_PACK_NATIVE_BYTE_ORDER);
+    if ( sign == 2 || sign == -2
+         || ( sign > 0 && mag > (uint64_t) INT64_MAX )
+         || ( sign < 0 && mag > (uint64_t) INT64_MAX + 1 ) ) {
+      return 2;                         /* does not fit int64 */
+    }
+    *out = ( sign < 0 ) ? (ca_size_t) (0 - mag) : (ca_size_t) mag;
+    return 1;
+  }
+  return 0;
+}
+
+/* A key that has to name a position: a scalar key, or one inside a Range,
+   an Array form or a step.  `where` follows the value in the out-of-range
+   message. */
+static ca_size_t
+ca_classifier_key_int_where (VALUE v, int axis, const char *where)
+{
+  ca_size_t k;
+  switch ( ca_classifier_key_position(v, &k) ) {
+  case 1:
+    return k;
+  case 2:
+    ca_classifier_key_too_large(v, where);
+  default:
+    ca_classifier_invalid_key(v, axis);
+  }
+}
+
+static ca_size_t
+ca_classifier_key_int (VALUE v, int axis)
+{
+  char where[32];
+  snprintf(where, sizeof(where), " on axis %d", axis);
+  return ca_classifier_key_int_where(v, axis, where);
+}
+
+int
+ca_index_key_is_scalar (VALUE arg)
+{
+  return FIXNUM_P(arg) || RB_FLOAT_TYPE_P(arg) || RB_TYPE_P(arg, T_BIGNUM);
+}
+
+/* A step: an integer like any key, except that one past int64 is not past
+   anything -- it is a step larger than any axis, so it reaches one cell.
+   It is read as the largest int64 of its sign, which does the same. */
+static ca_size_t
+ca_classifier_key_step (VALUE v, int axis)
+{
+  ca_size_t k;
+  if ( ca_classifier_key_position(v, &k) == 2 ) {
+    return rb_big_sign(v) ? (ca_size_t) INT64_MAX : (ca_size_t) INT64_MIN;
+  }
+  return ca_classifier_key_int(v, axis);
+}
+
+/* An axis of length 0 has no cells: a range on it reads none when it starts
+   at 0 (as `[][0..-1]` does), and is out of range otherwise.  Returns 1 when
+   the axis was filled in. */
+static int
+ca_classifier_block_on_empty_axis (CAIndexInfo *info, int axis, ca_size_t dim,
+                                   ca_size_t start)
+{
+  if ( dim != 0 ) {
+    return 0;
+  }
+  if ( start != 0 ) {
+    ca_index_out_of_range_at(start, dim, axis);
+  }
+  info->index_type[axis]        = CA_IDX_BLOCK;
+  info->index[axis].block.start = 0;
+  info->index[axis].block.count = 0;
+  info->index[axis].block.step  = 1;
+  return 1;
+}
+
 /* -------------------------------------------------------------------- */
 /* Fast paths. */
 
@@ -131,8 +281,8 @@ ca_classifier_try_point_fast_path (ca_classifier_ctx_t *ctx)
   for (i = 0; i < ctx->argc; i++) {
     ca_size_t k = FIX2LONG(ctx->argv[i]);
     if ( ctx->info->range_check ) {
-      /* Bignum is rejected by FIXNUM_P above; the slow path's
-         rb_obj_is_kind_of(arg, rb_cInteger) picks it up so the
+      /* Bignum and Float are rejected by FIXNUM_P above; the slow path's
+         integer-key branch picks them up so the
          Integer semantics are preserved end-to-end. */
       k = ca_classifier_normalize_axis_index(k, ctx->ca_dim[i], (int) i,
                                    ctx->info->range_check);
@@ -162,12 +312,13 @@ ca_classifier_try_address_fast_path (ca_classifier_ctx_t *ctx)
 
 /* -------------------------------------------------------------------- */
 /* Single-character alphabetic Symbols (`:a`-`:z` / `:A`-`:Z`) are
-   reserved for future contraction notation.  Raises
-   NotImplementedError rather than the generic IndexError.  The
-   caller passes any Symbol that is not `:_` / `:%`; a
-   non-reserved Symbol returns without action. */
+   reserved: no index form gives them a meaning, and none should
+   until one is decided.  Raises IndexError saying so, rather than
+   the generic "invalid as the index" message.  The caller passes
+   any Symbol that is not `:_` / `:%`; a non-reserved Symbol
+   returns without action. */
 static inline void
-ca_classifier_check_reserved_contraction_symbol (VALUE sym)
+ca_classifier_check_reserved_symbol (VALUE sym)
 {
   const char *name;
   if ( ! SYMBOL_P(sym) ) return;
@@ -177,9 +328,8 @@ ca_classifier_check_reserved_contraction_symbol (VALUE sym)
        && ( ( name[0] >= 'a' && name[0] <= 'z' )
             || ( name[0] >= 'A' && name[0] <= 'Z' ) )
        && name[0] != '_' /* :_ is iterator marker, handled separately */ ) {
-    rb_raise(rb_eNotImpError,
-             "symbol :%s is reserved for future contraction notation "
-             "(not yet implemented)",
+    rb_raise(rb_eIndexError,
+             "symbol :%s is reserved",
              name);
   }
 }
@@ -207,40 +357,38 @@ ca_classifier_axis_from_range (ca_classifier_ctx_t *ctx, int axis, VALUE arg)
   iv_end  = CA_CLASSIFIER_RANGE_END(arg);
   iv_excl = CA_CLASSIFIER_RANGE_EXCL(arg);
 
-  start = NIL_P(iv_beg) ? 0  : NUM2SIZE(iv_beg);
-  last  = NIL_P(iv_end) ? -1 : NUM2SIZE(iv_end);
+  start = NIL_P(iv_beg) ? 0  : ca_classifier_key_int(iv_beg, axis);
+  last  = NIL_P(iv_end) ? -1 : ca_classifier_key_int(iv_end, axis);
   excl  = RTEST(iv_excl);
 
-  info->index_type[axis] = CA_IDX_BLOCK;
-
-  if ( info->range_check ) {
-    /* Inlined CA_CHECK_INDEX_AT so the format string stays
-       byte-identical with the surrounding helpers. */
-    if ( start < 0 ) start += dim;
-    if ( start < 0 || start >= dim ) {
-      rb_raise(rb_eIndexError,
-               "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-               axis, (ca_size_t) start, (ca_size_t) (dim - 1));
-    }
+  if ( ca_classifier_block_on_empty_axis(info, axis, dim, start) ) {
+    return;
   }
+  info->index_type[axis] = CA_IDX_BLOCK;
 
   if ( last < 0 ) {
     last += dim;  /* don't use CA_CHECK_INDEX for excl */
   }
-  if ( excl && start == last ) {
+  /* No cells: an exclusive range that ends where it starts, or an endless
+     one that starts at the end of the axis. */
+  if ( ca_classifier_range_is_empty(start, last, excl, NIL_P(iv_end), dim) ) {
+    if ( info->range_check ) {
+      start = ca_classifier_run_start(start, dim, axis, 1);
+    }
     info->index[axis].block.start = start;
     info->index[axis].block.count = 0;
     info->index[axis].block.step  = 1;
     return;
   }
+  if ( info->range_check ) {
+    start = ca_index_in_range_at(start, dim, axis);
+  }
   if ( excl ) {
     last += ( last >= start ) ? -1 : 1;
   }
   if ( info->range_check ) {
     if ( last < 0 || last >= dim ) {
-      rb_raise(rb_eIndexError,
-               "index %" PRId64 " is out of range (0..%" PRId64 ") at %i-dim",
-               (ca_size_t) last, (ca_size_t) (dim - 1), axis);
+      ca_index_out_of_range_at(last, dim, axis);
     }
   }
   count = llabs(last - start) + 1;
@@ -250,80 +398,89 @@ ca_classifier_axis_from_range (ca_classifier_ctx_t *ctx, int axis, VALUE arg)
   info->index[axis].block.step  = step;
 }
 
-#ifdef HAVE_RB_ARITHMETIC_SEQUENCE_EXTRACT
-/* ArithSeq → BLOCK */
+/* A run of cells from `iv_beg` toward `iv_end` (inclusive unless excl)
+   taking every `step`-th: an ArithmeticSequence, or the `[range, step]`
+   form.  The step says the direction, as it does for Ruby: one that points
+   away from the end reads nothing, and an endless run with a negative
+   step goes down to the first cell.  A begin of nil starts at the end the
+   step walks from. */
 static void
-ca_classifier_axis_from_arithseq (ca_classifier_ctx_t *ctx, int axis, VALUE arg)
+ca_classifier_block_stepped (ca_classifier_ctx_t *ctx, int axis,
+                             VALUE iv_beg, VALUE iv_end, int excl, ca_size_t step)
 {
-  ca_size_t   start, last, count, step, bound;
-  int         excl;
-  volatile VALUE iv_beg, iv_end, iv_excl;
-  rb_arithmetic_sequence_components_t x;
+  ca_size_t   start, last, count, bound, s;
+  int         endless = NIL_P(iv_end);
   CAIndexInfo *info = ctx->info;
   ca_size_t   dim   = ctx->ca_dim[axis];
 
-  rb_arithmetic_sequence_extract(arg, &x);
-  iv_beg = x.begin;
-  iv_end = x.end;
-  iv_excl = x.exclude_end;
-  step   = NUM2SIZE(x.step);
-
-  start = NIL_P(iv_beg) ? 0  : NUM2SIZE(iv_beg);
-  last  = NIL_P(iv_end) ? -1 : NUM2SIZE(iv_end);
-  excl  = RTEST(iv_excl);
-
   if ( step == 0 ) {
-    rb_raise(rb_eRuntimeError,
+    rb_raise(rb_eArgError,
              "step in index equals to 0 in block reference");
   }
-
-  info->index_type[axis] = CA_IDX_BLOCK;
-
-  /* CAREFUL: always range-check start on the ArithSeq path,
-     ignoring info->range_check.  An ArithSeq with a negative or
-     out-of-range start silently produces an empty region if this
-     check is deferred, which upstream callers do not expect. */
-  if ( start < 0 ) start += dim;
-  if ( start < 0 || start >= dim ) {
-    rb_raise(rb_eIndexError,
-             "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-             axis, (ca_size_t) start, (ca_size_t) (dim - 1));
+  start = NIL_P(iv_beg) ? ( step < 0 ? dim - 1 : 0 )
+                        : ca_classifier_key_int(iv_beg, axis);
+  last  = endless ? ( step < 0 ? 0 : dim - 1 )
+                  : ca_classifier_key_int(iv_end, axis);
+  if ( NIL_P(iv_beg) && dim == 0 ) {
+    start = 0;
   }
-
-  if ( last < 0 ) {
+  if ( ca_classifier_block_on_empty_axis(info, axis, dim, start) ) {
+    return;
+  }
+  info->index_type[axis] = CA_IDX_BLOCK;
+  if ( ! endless && last < 0 ) {
     last += dim;
   }
-  if ( excl && start == last ) {
-    info->index[axis].block.start = start;
+  /* CAREFUL: start is range-checked here whatever info->range_check says.
+     A run that starts outside the axis would otherwise read as an empty
+     region, which upstream callers do not expect. */
+  s = ( start < 0 ) ? start + dim : start;
+  if ( ( endless && step > 0 && s == dim ) || ( ! endless && excl && s == last ) ) {
+    info->index[axis].block.start = ca_classifier_run_start(start, dim, axis, 1);
     info->index[axis].block.count = 0;
     info->index[axis].block.step  = 1;
     return;
   }
-  if ( excl ) {
+  start = ca_index_in_range_at(start, dim, axis);
+  if ( excl && ! endless ) {
     last += ( last >= start ) ? -1 : 1;
   }
   if ( last < 0 || last >= dim ) {
-    rb_raise(rb_eIndexError,
-             "index %" PRId64 " is out of range (0..%" PRId64 ") at %i-dim",
-             (ca_size_t) last, (ca_size_t) (dim - 1), axis);
+    ca_index_out_of_range_at(last, dim, axis);
   }
-  if ( (last - start) * (long long) step < 0 ) {
-    count = 1;
+  if ( (last > start && step < 0) || (last < start && step > 0) ) {
+    info->index[axis].block.start = start;
+    info->index[axis].block.count = 0;
+    info->index[axis].block.step  = 1;
+    return;
   }
-  else {
-    count = llabs(last - start) / llabs((long long) step) + 1;
+  /* start and last are both inside the axis, so their distance fits; the
+     step is taken by magnitude unsigned, since -step overflows at its
+     minimum.  (count - 1) * step below is then at most that distance. */
+  {
+    unsigned long long span  = (unsigned long long)
+                               (last >= start ? last - start : start - last);
+    unsigned long long ustep = step < 0 ? 0ULL - (unsigned long long) step
+                                        : (unsigned long long) step;
+    count = (ca_size_t) (span / ustep) + 1;
   }
   bound = start + (count - 1) * step;
-  if ( bound < 0 ) bound += dim;  /* CA_CHECK_INDEX_AT signature */
-  if ( bound < 0 || bound >= dim ) {
-    rb_raise(rb_eIndexError,
-             "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-             axis, (ca_size_t) bound, (ca_size_t) (dim - 1));
-  }
+  bound = ca_index_in_range_at(bound, dim, axis);
   info->index[axis].block.start = start;
   info->index[axis].block.count = count;
   info->index[axis].block.step  = step;
 }
+
+#ifdef HAVE_RB_ARITHMETIC_SEQUENCE_EXTRACT
+/* ArithSeq → BLOCK */
+static void
+ca_classifier_axis_from_arithseq (ca_classifier_ctx_t *ctx, int axis, VALUE arg)
+{
+  rb_arithmetic_sequence_components_t x;
+  rb_arithmetic_sequence_extract(arg, &x);
+  ca_classifier_block_stepped(ctx, axis, x.begin, x.end, RTEST(x.exclude_end),
+                              ca_classifier_key_step(x.step, axis));
+}
 #endif
 
 /* T_ARRAY → BLOCK.  Accepts [nil] / [Range] / [Integer] (len 1),
@@ -350,13 +507,9 @@ ca_classifier_axis_from_array (ca_classifier_ctx_t *ctx, int axis, VALUE arg)
     }
     /* [Integer] */
     {
-      ca_size_t start = NUM2SIZE(a0);
-      if ( start < 0 ) start += dim;
-      if ( start < 0 || start >= dim ) {
-        rb_raise(rb_eIndexError,
-                 "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-                 axis, (ca_size_t) start, (ca_size_t) (dim - 1));
-      }
+      ca_size_t given = ca_classifier_key_int(a0, axis);
+      ca_size_t start = given;
+      start = ca_index_in_range_at(start, dim, axis);
       info->index[axis].block.start = start;
       info->index[axis].block.count = 1;
       info->index[axis].block.step  = 1;
@@ -369,75 +522,24 @@ ca_classifier_axis_from_array (ca_classifier_ctx_t *ctx, int axis, VALUE arg)
     VALUE a1 = rb_ary_entry(arg, 1);
 
     if ( NIL_P(a0) ) {                    /* [nil, step] */
-      ca_size_t start = 0, last, count, step, bound;
-      step = NUM2SIZE(a1);
-      if ( step == 0 ) {
-        rb_raise(rb_eRuntimeError,
-                 "step in index equals to 0 in block reference");
-      }
-      last = dim - 1;
-      count = ( step < 0 ) ? 1 : (last / step + 1);
-      bound = start + (count - 1) * step;
-      if ( bound < 0 ) bound += dim;
-      if ( bound < 0 || bound >= dim ) {
-        rb_raise(rb_eIndexError,
-                 "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-                 axis, (ca_size_t) bound, (ca_size_t) (dim - 1));
-      }
-      info->index[axis].block.start = start;
-      info->index[axis].block.count = count;
-      info->index[axis].block.step  = step;
-      return;
-    }
-
-    if ( rb_obj_is_kind_of(a0, rb_cRange) ) {  /* [Range, step] */
-      ca_size_t   start, last, count, step, bound;
-      int         excl;
-      volatile VALUE iv_beg, iv_end, iv_excl;
-      iv_beg  = CA_CLASSIFIER_RANGE_BEG(a0);
-      iv_end  = CA_CLASSIFIER_RANGE_END(a0);
-      iv_excl = CA_CLASSIFIER_RANGE_EXCL(a0);
-      start = NIL_P(iv_beg) ? 0  : NUM2SIZE(iv_beg);
-      last  = NIL_P(iv_end) ? -1 : NUM2SIZE(iv_end);
-      excl  = RTEST(iv_excl);
-      step  = NUM2SIZE(a1);
+      ca_size_t start = 0, count, step;
+      step = ca_classifier_key_step(a1, axis);
       if ( step == 0 ) {
-        rb_raise(rb_eRuntimeError,
+        rb_raise(rb_eArgError,
                  "step in index equals to 0 in block reference");
       }
-      if ( start < 0 ) start += dim;
-      if ( start < 0 || start >= dim ) {
-        rb_raise(rb_eIndexError,
-                 "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-                 axis, (ca_size_t) start, (ca_size_t) (dim - 1));
-      }
-      if ( last < 0 ) last += dim;
-      if ( excl && start == last ) {
-        info->index[axis].block.start = start;
-        info->index[axis].block.count = 0;
-        info->index[axis].block.step  = 1;
-        return;
-      }
-      if ( excl ) {
-        last += ( last >= start ) ? -1 : 1;
-      }
-      if ( last < 0 || last >= dim ) {
-        rb_raise(rb_eIndexError,
-                 "index %" PRId64 " is out of range (0..%" PRId64 ") at %i-dim",
-                 (ca_size_t) last, (ca_size_t) (dim - 1), axis);
+      /* every cell of the axis from the first at that step: none of an
+         axis of length 0.  A negative step from the first cell reaches only
+         it. */
+      if ( dim == 0 ) {
+        count = 0;
+        step  = 1;
       }
-      if ( (last - start) * (long long) step < 0 ) {
+      else if ( step < 0 ) {
         count = 1;
       }
       else {
-        count = llabs(last - start) / llabs((long long) step) + 1;
-      }
-      bound = start + (count - 1) * step;
-      if ( bound < 0 ) bound += dim;
-      if ( bound < 0 || bound >= dim ) {
-        rb_raise(rb_eIndexError,
-                 "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-                 axis, (ca_size_t) bound, (ca_size_t) (dim - 1));
+        count = (dim - 1) / step + 1;
       }
       info->index[axis].block.start = start;
       info->index[axis].block.count = count;
@@ -445,23 +547,32 @@ ca_classifier_axis_from_array (ca_classifier_ctx_t *ctx, int axis, VALUE arg)
       return;
     }
 
+    if ( rb_obj_is_kind_of(a0, rb_cRange) ) {  /* [Range, step] */
+      ca_classifier_block_stepped(ctx, axis,
+                                  CA_CLASSIFIER_RANGE_BEG(a0),
+                                  CA_CLASSIFIER_RANGE_END(a0),
+                                  RTEST(CA_CLASSIFIER_RANGE_EXCL(a0)),
+                                  ca_classifier_key_step(a1, axis));
+      return;
+    }
+
     /* [start, count] */
     {
       ca_size_t start, count, bound;
-      start = NUM2SIZE(a0);
-      count = NUM2SIZE(a1);
-      bound = start + (count - 1);
-      if ( start < 0 ) start += dim;
-      if ( start < 0 || start >= dim ) {
+      ca_size_t given;
+      given = ca_classifier_key_int(a0, axis);
+      count = ca_classifier_key_int(a1, axis);
+      /* The start counts from the end when negative; the last cell is
+         counted from that start and has to be inside as it is.  A count
+         of 0 may start at the end of the axis. */
+      start = ca_classifier_run_start(given, dim, axis, count == 0);
+      if ( count > 0 &&
+           ( __builtin_add_overflow(start, count - 1, &bound) || bound >= dim ) ) {
         rb_raise(rb_eIndexError,
-                 "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-                 axis, (ca_size_t) start, (ca_size_t) (dim - 1));
-      }
-      if ( bound < 0 ) bound += dim;
-      if ( bound < 0 || bound >= dim ) {
-        rb_raise(rb_eIndexError,
-                 "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-                 axis, (ca_size_t) bound, (ca_size_t) (dim - 1));
+                 "%s: index [%" PRId64 ", %" PRId64 "] is out of range for "
+                 "length %" PRId64 " on axis %i",
+                 ca_calling_method_name(), (ca_size_t) given, (ca_size_t) count,
+                 (ca_size_t) dim, axis);
       }
       info->index[axis].block.start = start;
       info->index[axis].block.count = count;
@@ -471,26 +582,28 @@ ca_classifier_axis_from_array (ca_classifier_ctx_t *ctx, int axis, VALUE arg)
   }
 
   if ( len == 3 ) {                      /* [start, count, step] */
-    ca_size_t start, count, step, bound;
-    start = NUM2SIZE(rb_ary_entry(arg, 0));
-    count = NUM2SIZE(rb_ary_entry(arg, 1));
-    step  = NUM2SIZE(rb_ary_entry(arg, 2));
+    ca_size_t given, start, count, step, bound;
+    given = ca_classifier_key_int(rb_ary_entry(arg, 0), axis);
+    count = ca_classifier_key_int(rb_ary_entry(arg, 1), axis);
+    step  = ca_classifier_key_step(rb_ary_entry(arg, 2), axis);
     if ( step == 0 ) {
-      rb_raise(rb_eRuntimeError,
+      rb_raise(rb_eArgError,
                "step in index equals to 0 in block reference");
     }
-    bound = start + (count - 1) * step;
-    if ( start < 0 ) start += dim;
-    if ( start < 0 || start >= dim ) {
-      rb_raise(rb_eIndexError,
-               "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-               axis, (ca_size_t) start, (ca_size_t) (dim - 1));
-    }
-    if ( bound < 0 ) bound += dim;
-    if ( bound < 0 || bound >= dim ) {
+    /* The start counts from the end when negative; the last cell is
+       counted from that start and has to be inside as it is, not a bound
+       that wraps back in from either end.  A count of 0 may start at the
+       end of the axis. */
+    start = ca_classifier_run_start(given, dim, axis, count == 0);
+    if ( count > 0 &&
+         ( __builtin_mul_overflow(count - 1, step, &bound) ||
+           __builtin_add_overflow(start, bound, &bound) ||
+           bound < 0 || bound >= dim ) ) {
       rb_raise(rb_eIndexError,
-               "index out of range at %i-dim ( %" PRId64 " <=> 0..%" PRId64 " )",
-               axis, (ca_size_t) bound, (ca_size_t) (dim - 1));
+               "%s: index [%" PRId64 ", %" PRId64 ", %" PRId64 "] is out of "
+               "range for length %" PRId64 " on axis %i",
+               ca_calling_method_name(), (ca_size_t) given, (ca_size_t) count,
+               (ca_size_t) step, (ca_size_t) dim, axis);
     }
     info->index[axis].block.start = start;
     info->index[axis].block.count = count;
@@ -519,8 +632,8 @@ ca_classifier_dispatch_axis_arg (ca_classifier_ctx_t *ctx, int axis, VALUE arg,
   CAIndexInfo *info = ctx->info;
   ca_size_t   dim   = ctx->ca_dim[axis];
 
-  if ( rb_obj_is_kind_of(arg, rb_cInteger) ) {
-    ca_size_t k = NUM2SIZE(arg);
+  if ( ca_index_key_is_scalar(arg) ) {
+    ca_size_t k = ca_classifier_key_int(arg, axis);
     info->index_type[axis] = CA_IDX_SCALAR;
     if ( info->range_check ) {
       k = ca_classifier_normalize_axis_index(k, dim, axis, info->range_check);
@@ -563,11 +676,11 @@ ca_classifier_dispatch_axis_arg (ca_classifier_ctx_t *ctx, int axis, VALUE arg,
                "symbol :_ (newaxis) is handled at the [] / []= level, "
                "not valid in scan_index");
     }
-    ca_classifier_check_reserved_contraction_symbol(arg);  /* raises if reserved */
+    ca_classifier_check_reserved_symbol(arg);  /* raises if reserved */
     rb_raise(rb_eIndexError,
-             "symbol :%s is invalid as the index for slab iterator "
+             "symbol :%"PRIsVALUE" is invalid as the index for slab iterator "
              "(use :> instead)",
-             rb_id2name(SYM2ID(arg)));
+             rb_sym2str(arg));
   }
   if ( rb_obj_is_carray(arg) ) {
     /* CArray (boolean / integer) at an axis position → GRID.
@@ -584,12 +697,7 @@ ca_classifier_dispatch_axis_arg (ca_classifier_ctx_t *ctx, int axis, VALUE arg,
              "(should be boolean or integer)",
              ca_type_name[ci->data_type], axis);
   }
-  {
-    VALUE inspect = rb_inspect(arg);
-    rb_raise(rb_eIndexError,
-             "object '%s' is invalid for the index for reference at %i-dim",
-             StringValuePtr(inspect), axis);
-  }
+  ca_classifier_invalid_key(arg, axis);
 }
 
 /* -------------------------------------------------------------------- */
@@ -599,66 +707,117 @@ ca_classifier_dispatch_axis_arg (ca_classifier_ctx_t *ctx, int axis, VALUE arg,
    rubber marker is honoured; a second one falls through to the
    per-axis dispatcher and raises. */
 
-static void
-ca_classifier_expand_rubber_dim (ca_classifier_ctx_t *ctx)
+/* Expand the rubber marker (`false` or `:~`) of a key list for an
+   array of ndim axes into as many nils as it stands for, writing the
+   list into out (CA_RANK_MAX slots).  Returns the new count, or -1 when
+   the list has no rubber marker (out is then untouched).  Only the first
+   marker is honoured; a later one is left for the axis reader to refuse. */
+long
+ca_index_expand_rubber (int ndim, long argc, const VALUE *argv, VALUE *out)
 {
   long i, j;
-  long argc      = ctx->argc;
-  VALUE *argv    = ctx->argv;
   int rubber_pos = -1;
-  long expanded_argc;
-  int  rndim;
+  int rndim;
 
+  ca_classifier_sym_cache_init();
   for (i = 0; i < argc; i++) {
     if ( argv[i] == Qfalse || argv[i] == ca_classifier_sym_tilde ) {
-      rubber_pos = (int) i;    /* :~ is an alias for the `false` rubber marker */
-      /* Only the first rubber marker is honoured; later occurrences fall
-         through to the per-axis dispatcher and raise. */
+      rubber_pos = (int) i;
       break;
     }
   }
-
   if ( rubber_pos < 0 ) {
-    /* No rubber dim — validate argc == ndim and pass through. */
-    if ( argc != ctx->ca_ndim ) {
-      rb_raise(rb_eIndexError,
-               "number of indices exceeds the ndim of carray (%i > %i)",
-               (int) argc, ctx->ca_ndim);
-    }
-    return;
+    return -1;
   }
-
-  if ( argc > ctx->ca_ndim + 1 ) {
+  if ( argc > ndim + 1 ) {
     rb_raise(rb_eIndexError,
-             "index specification exceeds the ndim of carray (%i)",
-             ctx->ca_ndim);
+             "index specification exceeds the ndim of carray (%i)", ndim);
   }
-
-  /* rndim = number of nils the rubber expands to.
-   *
-   * CAREFUL: rndim == 0 is a valid outcome — the rubber consumes
-   * nothing when argc == ndim + 1 (e.g. `[false, 0, 1]` on
-   * ndim = 2 collapses to `[0, 1]`).  Clamping only at the
-   * negative side preserves that path. */
-  rndim = ctx->ca_ndim - (int)argc + 1;
+  /* CAREFUL: rndim == 0 is a valid outcome -- the rubber consumes nothing
+     when argc == ndim + 1 (e.g. `[false, 0, 1]` on ndim = 2 collapses to
+     `[0, 1]`).  Clamping only at the negative side preserves that path. */
+  rndim = ndim - (int) argc + 1;
   if ( rndim < 0 ) rndim = 0;
-  expanded_argc = argc - 1 + rndim;
-
   j = 0;
   for (i = 0; i < argc; i++) {
     if ( i == rubber_pos ) {
       int k;
       for (k = 0; k < rndim; k++) {
-        ctx->argv_expanded[j++] = Qnil;
+        out[j++] = Qnil;
       }
     } else {
-      ctx->argv_expanded[j++] = argv[i];
+      out[j++] = argv[i];
     }
   }
-  ctx->argc = expanded_argc;
+  return j;
+}
+
+static void
+ca_classifier_expand_rubber_dim (ca_classifier_ctx_t *ctx)
+{
+  long n = ca_index_expand_rubber(ctx->ca_ndim, ctx->argc, ctx->argv,
+                                  ctx->argv_expanded);
+  if ( n < 0 ) {
+    /* No rubber dim -- validate argc == ndim and pass through. */
+    if ( ctx->argc != ctx->ca_ndim ) {
+      rb_raise(rb_eIndexError,
+               "%i indices given for a carray of ndim %i",
+               (int) ctx->argc, ctx->ca_ndim);
+    }
+    return;
+  }
+  ctx->argc = n;
   ctx->argv = ctx->argv_expanded;
 }
 
+/* Read one key along an axis of length dim, as the indexer reads it when
+   the key is not a CArray: an Integer, nil, a Range, an
+   ArithmeticSequence or an Array form.  Fills *start / *count / *step and
+   returns CA_IDX_SCALAR (count 1), CA_IDX_ALL (the whole axis) or
+   CA_IDX_BLOCK.  Anything else raises IndexError.  grid and CASelectAxis
+   read their non-CArray keys through this, so a key means the same cells
+   whichever view the indexer builds. */
+int
+ca_index_axis_key (VALUE arg, ca_size_t dim, int axis,
+                   ca_size_t *start, ca_size_t *count, ca_size_t *step)
+{
+  ca_classifier_ctx_t ctx;
+  CAIndexInfo info;
+  ca_size_t dims[CA_RANK_MAX];
+  int is_grid = 0;
+
+  ca_classifier_sym_cache_init();
+  if ( axis < 0 || axis >= CA_RANK_MAX ) {   /* rank-check: an axis number, not a rank */
+    rb_raise(rb_eArgError, "axis %d is out of range", axis);
+  }
+  dims[axis]   = dim;
+  ctx.ca_ndim  = axis + 1;
+  ctx.ca_dim   = dims;
+  ctx.info     = &info;
+  info.range_check = 1;
+  if ( rb_obj_is_carray(arg) || arg == ca_classifier_sym_gt ) {
+    ca_classifier_invalid_key(arg, axis);
+  }
+  ca_classifier_dispatch_axis_arg(&ctx, axis, arg, &is_grid);
+  switch ( info.index_type[axis] ) {
+  case CA_IDX_SCALAR:
+    *start = info.index[axis].scalar;
+    *count = 1;
+    *step  = 1;
+    return CA_IDX_SCALAR;
+  case CA_IDX_ALL:
+    *start = 0;
+    *count = dim;
+    *step  = 1;
+    return CA_IDX_ALL;
+  default:
+    *start = info.index[axis].block.start;
+    *count = info.index[axis].block.count;
+    *step  = info.index[axis].block.step;
+    return CA_IDX_BLOCK;
+  }
+}
+
 /* -------------------------------------------------------------------- */
 /* Final REG decision — walks info->index_type[] and decides
    POINT / BLOCK / ITERATOR / GRID. */
@@ -718,16 +877,13 @@ ca_classifier_try_argc1_special (ca_classifier_ctx_t *ctx)
     return 1;
   }
 
-  /* T_STRING: "@name" → ATTRIBUTE, "field" → MEMBER. */
+  /* T_STRING: "field" → MEMBER. */
   if ( TYPE(arg) == T_STRING ) {
-    const char *s = StringValuePtr(arg);
-    if ( s[0] == '@' ) {
-      info->type   = CA_REG_ATTRIBUTE;
-      info->symbol = rb_str_new2(s + 1);
-    } else {
-      info->type   = CA_REG_MEMBER;
-      info->symbol = ID2SYM(rb_intern(s));
-    }
+    info->type   = CA_REG_MEMBER;
+    /* A dynamic Symbol: the collector reclaims it, so indexing with
+       strings that name no member does not grow the symbol table. */
+    StringValueCStr(arg);
+    info->symbol = rb_to_symbol(arg);
     return 1;
   }
 
@@ -744,8 +900,26 @@ ca_classifier_try_argc1_special (ca_classifier_ctx_t *ctx)
       return 1;
     }
     if ( ca_is_boolean_type(cs) ) {
+      /* A boolean selector of more than one axis states a shape, and has
+         to have the array's; a 1-D one picks by position among all the
+         cells. */
+      if ( cs->ndim > 1 ) {
+        int k, same = ( cs->ndim == ctx->ca_ndim );
+        for (k = 0; same && k < cs->ndim; k++) {
+          same = ( cs->dim[k] == ctx->ca_dim[k] );
+        }
+        if ( ! same ) {
+          volatile VALUE sshape = rb_ary_new(), ashape = rb_ary_new();
+          for (k = 0; k < cs->ndim; k++)     rb_ary_push(sshape, SIZE2NUM(cs->dim[k]));
+          for (k = 0; k < ctx->ca_ndim; k++) rb_ary_push(ashape, SIZE2NUM(ctx->ca_dim[k]));
+          rb_raise(rb_eArgError,
+                   "boolean selector of shape %"PRIsVALUE" for an array of shape "
+                   "%"PRIsVALUE" (a selector states its shape; use .flatten to "
+                   "select by position)", sshape, ashape);
+        }
+      }
       if ( ctx->ca_elements != cs->elements ) {
-        rb_raise(rb_eRuntimeError,
+        rb_raise(rb_eArgError,
                  "mismatch of # of elements ( %" PRId64 " <=> %" PRId64 " ) "
                  "in reference by selection",
                  (ca_size_t) cs->elements,
@@ -761,10 +935,11 @@ ca_classifier_try_argc1_special (ca_classifier_ctx_t *ctx)
              ca_type_name[cs->data_type]);
   }
 
-  /* ndim > 1 with Integer → ADDRESS.  Fixnum was caught by the
-     fast path; this branch handles Bignum. */
-  if ( ctx->ca_ndim > 1 && rb_obj_is_kind_of(arg, rb_cInteger) ) {
-    ca_size_t addr = NUM2SIZE(arg);
+  /* ndim > 1 with an integer key → ADDRESS.  Fixnum was caught by the
+     fast path; this branch handles Bignum and Float. */
+  if ( ctx->ca_ndim > 1
+       && ca_index_key_is_scalar(arg) ) {
+    ca_size_t addr = ca_classifier_key_int_where(arg, 0, "");
     info->type = CA_REG_ADDRESS;
     info->ndim = 1;
     if ( info->range_check ) {
@@ -826,7 +1001,7 @@ rb_ca_scan_index_v2 (int ca_ndim, ca_size_t *ca_dim, ca_size_t ca_elements,
   /* argv[0] = multi-char Symbol → METHOD_CALL.  Single-char
      specials (:_ / :%) fall through the strlen check and are
      handled downstream (argc == 1 special / fast paths / main
-     loop).  Single-char alphabetic reserved-contraction Symbols
+     loop).  Single-char alphabetic reserved Symbols
      also fall through here and are raised later by the per-axis
      dispatcher's SYMBOL_P branch. */
   if ( SYMBOL_P(argv[0]) ) {
@@ -878,7 +1053,7 @@ rb_ca_scan_index_v2 (int ca_ndim, ca_size_t *ca_dim, ca_size_t ca_elements,
        here would raise on legitimate grid regions. */
     if ( ! is_grid && ctx.ca_ndim != info->ndim ) {
       rb_raise(rb_eIndexError,
-               "number of indices does not equal to the ndim (%i != %i)",
+               "%i indices given for a carray of ndim %i",
                info->ndim, ctx.ca_ndim);
     }
 
@@ -886,6 +1061,7 @@ rb_ca_scan_index_v2 (int ca_ndim, ca_size_t *ca_dim, ca_size_t ca_elements,
   }
 }
 
+#ifdef CARRAY_DEV_BUILD
 /* -------------------------------------------------------------------- */
 /* Debug / test surface: CArray._scan_index_v2(dim_array, idx_array)
    returns a plain [type_int, index_array] pair rather than the
@@ -911,8 +1087,8 @@ rb_ca_s_scan_index_v2 (VALUE self, VALUE rdim, VALUE ridx)
     elements *= dim[i];
   }
 
-  CA_CHECK_RANK(ndim);
-  CA_CHECK_DIM(ndim, dim);
+  CA_CHECK_RANK_GIVEN(ndim);
+  CA_CHECK_DIM_GIVEN(ndim, dim);
 
   info.range_check = 1;
   rb_ca_scan_index_v2(ndim, dim, elements,
@@ -1001,7 +1177,7 @@ rb_ca_s_scan_index_v2 (VALUE self, VALUE rdim, VALUE ridx)
                                     info.index[i].symbol.spec));
             break;
           default:
-            rb_raise(rb_eRuntimeError, "unknown index spec");
+            rb_raise(rb_eIndexError, "unknown index spec");
         }
       }
       break;
@@ -1011,11 +1187,14 @@ rb_ca_s_scan_index_v2 (VALUE self, VALUE rdim, VALUE ridx)
 
   return rb_ary_new3(2, INT2NUM(info.type), rindex);
 }
+#endif
 
 void
 Init_carray_index_classifier (void)
 {
   ca_classifier_sym_cache_init();
+#ifdef CARRAY_DEV_BUILD
   rb_define_singleton_method(rb_cCArray, "_scan_index_v2",
                              rb_ca_s_scan_index_v2, 2);
+#endif
 }