carray 3.0.1 → 3.0.2

data/ext/ca_kernel_iterator.h

@@ -528,7 +528,24 @@ int  ca_iter_state_init_l2 (ca_iter_state    *st,
    source carries a mask (= ca_has_mask(src)), or NULL otherwise.
    The mask layout matches the value layout (= same iteration order
    and same n).  Step 6+: kernels use the CA_FOR_EACH_UNMASKED macro
-   family (carray.h) to skip masked cells. */
+   family (carray.h) to skip masked cells.
+
+   The mask is an input.  What it points at is a copy taken when the
+   walk began, so writing through it changes nothing -- not even under
+   CA_KERNEL_WRITE, where the value half of the same yield is often a
+   live alias.  It also cannot express the thing an author would most
+   want it for: an unmasked source yields NULL, so there is nowhere to
+   record that a cell has become undefined.  A kernel authors its
+   output mask on its own output array instead:
+
+       if ( op_mask == NULL ) {
+         ca_create_mask(co);
+         op_mask = (boolean8_t *) co->mask->ptr;
+       }
+       op_mask[out_i] = 1;
+
+   which is what every kernel in carray does (carray_hold.c, and the
+   reduction kernels mkkernel emits). */
 int  ca_iter_state_next_slab (ca_iter_state *st,
                               char         **out_ptr,
                               boolean8_t   **out_mask,
@@ -603,6 +620,13 @@ void ca_iter_state_sync_slab (ca_iter_state *st);
    exactly once after a successful init (either level). */
 void ca_iter_state_finish (ca_iter_state *st);
 
+/* Raise unless rc is CA_ITER_OK.  The block macros call this on the value
+   ca_iter_state_init_l1 / _l2 returned, so an author who never looks at a
+   return code still hears about a request the iterator would not serve.
+   Returns rc when there is nothing to report, so it composes inside the
+   macros' comma expressions. */
+int ca_iter_check_init (int rc);
+
 /* ---- Phase C C.3: kernel author block macros ------------------------
    (PROPOSAL_CAPSTONE_PHASE_C.md D3.1 (A) do/while/for + D3.2 (C) 2 kinds)
 
@@ -617,17 +641,24 @@ void ca_iter_state_finish (ca_iter_state *st);
      surrounding scope.
    - `flags` arg propagates to init_l2 (= CA_KERNEL_WRITE supported).
      `sync_slab` is called automatically after each iteration; it's a
-     no-op when WRITE flag is absent.
-   - Init failure (ca_iter_state_init_l2 returns CA_ITER_ERR_*) is
-     silently discarded: the body runs zero times and finish is still
-     called.  Production kernels that need explicit error messages
-     (e.g., sum_ki's rc=%d raise) should drop down to the raw API
-     instead of using this macro.
+     no-op when WRITE flag is absent.  The mask cursor is an input even
+     under WRITE -- see ca_iter_state_next_slab above for why, and for
+     where an output mask is written instead.
+   - Init failure (ca_iter_state_init_l2 returns CA_ITER_ERR_*) raises:
+     the macro passes the code to ca_iter_check_init, which reports what
+     the iterator declined to do.  The body does not run and finish is
+     not reached, which is safe because a failed init allocates nothing.
+     Kernels that want to handle a refusal rather than propagate it
+     should drop down to the raw API and read the code themselves.
    - `break;` from inside the body exits the loop AND triggers finish
      correctly (= outer for's "increment" clause runs once on natural
      exit; `break` from the inner while breaks both).  `return` inside
      the body LEAKS resources (scratch_ptr, parent attach) — drop to
-     raw API if early return is needed.
+     raw API if early return is needed.  A body that raises leaks the
+     same way: the engine releases what it holds when the walk itself
+     raises (a gather or a write-back through the source's slots), but
+     the body runs in the caller's frame, where it has no hold on it.
+     An object-lane body calling back into Ruby is the case to watch.
    - Macros are not statement-equivalent (= they expand to nested for
      constructs).  Don't follow them with `else` etc. */
 
@@ -760,8 +791,9 @@ void ca_iter_state_finish (ca_iter_state *st);
    always-constant argument).  CA_SLAB_AXES is still FROZEN, because
    raw-API kernels pass it to ca_iter_state_init_l2 directly. */
 #define CA_FOR_EACH_SLAB(st, ca, axes, naxes, flags, p, m)                    \
-  for ( int __caf_init = (ca_iter_state_init_l2(&(st), (ca), CA_SLAB_AXES,    \
-                                                (axes), (naxes), (flags)),    \
+  for ( int __caf_init = (ca_iter_check_init(                                 \
+                            ca_iter_state_init_l2(&(st), (ca), CA_SLAB_AXES,  \
+                                                  (axes), (naxes), (flags))), \
                           1);                                                 \
         __caf_init;                                                           \
         __caf_init = 0, ca_iter_state_finish(&(st)) )                         \
@@ -777,16 +809,18 @@ void ca_iter_state_finish (ca_iter_state *st);
    Shape mismatch between ca_in / ca_out is NOT validated by the macro
    — caller responsibility (= typically output is `rb_ca_template_with_type`
    of input, guaranteeing same shape).  Init failure on either iter
-   silently skips the body. */
+   raises — see CA_FOR_EACH_SLAB above. */
 /* Policy fixed to CA_SLAB_AXES internally — see CA_FOR_EACH_SLAB above. */
 #define CA_FOR_EACH_SLAB_INOUT(st_in, st_out, ca_in, ca_out,                  \
                                axes, naxes,                                   \
                                p_in, p_out, m_in, m_out)                      \
   for ( int __cafi_init = (                                                   \
-            ca_iter_state_init_l2(&(st_in),  (ca_in),  CA_SLAB_AXES,          \
-                                  (axes), (naxes), 0),                        \
-            ca_iter_state_init_l2(&(st_out), (ca_out), CA_SLAB_AXES,          \
-                                  (axes), (naxes), CA_KERNEL_WRITE),          \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_in),  (ca_in),  CA_SLAB_AXES,        \
+                                    (axes), (naxes), 0)),                     \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_out), (ca_out), CA_SLAB_AXES,        \
+                                    (axes), (naxes), CA_KERNEL_WRITE)),       \
             1);                                                               \
         __cafi_init;                                                          \
         __cafi_init = 0,                                                      \
@@ -827,9 +861,10 @@ void ca_iter_state_finish (ca_iter_state *st);
 
 #define CA_FOR_EACH_FIBER(st, ca, axis, flags, p, n)                          \
   for ( int __cff_init = (                                                    \
-            ca_iter_state_init_l2(&(st), (ca), CA_SLAB_AXES,                  \
-                                  (int8_t[]){(int8_t)(axis)}, 1,              \
-                                  (flags) | CA_KERNEL_FIBER_CONTIG),          \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st), (ca), CA_SLAB_AXES,                \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    (flags) | CA_KERNEL_FIBER_CONTIG)),       \
             (n) = (st).slab_dims[0],                                          \
             1);                                                               \
         __cff_init;                                                           \
@@ -839,9 +874,10 @@ void ca_iter_state_finish (ca_iter_state *st);
 
 #define CA_FOR_EACH_FIBER_MASKED(st, ca, axis, flags, p, n, m)                \
   for ( int __cffm_init = (                                                   \
-            ca_iter_state_init_l2(&(st), (ca), CA_SLAB_AXES,                  \
-                                  (int8_t[]){(int8_t)(axis)}, 1,              \
-                                  (flags) | CA_KERNEL_FIBER_CONTIG),          \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st), (ca), CA_SLAB_AXES,                \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    (flags) | CA_KERNEL_FIBER_CONTIG)),       \
             (n) = (st).slab_dims[0],                                          \
             1);                                                               \
         __cffm_init;                                                          \
@@ -864,13 +900,15 @@ void ca_iter_state_finish (ca_iter_state *st);
 #define CA_FOR_EACH_FIBER_INOUT(st_in, st_out, ca_in, ca_out, axis,           \
                                 flags, p_in, p_out, n)                        \
   for ( int __cffi_init = (                                                   \
-            ca_iter_state_init_l2(&(st_in),  (ca_in),  CA_SLAB_AXES,          \
-                                  (int8_t[]){(int8_t)(axis)}, 1,              \
-                                  (flags) | CA_KERNEL_FIBER_CONTIG),          \
-            ca_iter_state_init_l2(&(st_out), (ca_out), CA_SLAB_AXES,          \
-                                  (int8_t[]){(int8_t)(axis)}, 1,              \
-                                  ((flags) | CA_KERNEL_FIBER_CONTIG           \
-                                           | CA_KERNEL_WRITE)),               \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_in),  (ca_in),  CA_SLAB_AXES,        \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    (flags) | CA_KERNEL_FIBER_CONTIG)),       \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_out), (ca_out), CA_SLAB_AXES,        \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    ((flags) | CA_KERNEL_FIBER_CONTIG         \
+                                             | CA_KERNEL_WRITE))),            \
             (n) = (st_in).slab_dims[0],                                       \
             1);                                                               \
         __cffi_init;                                                          \
@@ -888,13 +926,15 @@ void ca_iter_state_finish (ca_iter_state *st);
 #define CA_FOR_EACH_FIBER_INOUT_MASKED(st_in, st_out, ca_in, ca_out, axis,    \
                                        flags, p_in, p_out, n, m)              \
   for ( int __cffim_init = (                                                  \
-            ca_iter_state_init_l2(&(st_in),  (ca_in),  CA_SLAB_AXES,          \
-                                  (int8_t[]){(int8_t)(axis)}, 1,              \
-                                  (flags) | CA_KERNEL_FIBER_CONTIG),          \
-            ca_iter_state_init_l2(&(st_out), (ca_out), CA_SLAB_AXES,          \
-                                  (int8_t[]){(int8_t)(axis)}, 1,              \
-                                  ((flags) | CA_KERNEL_FIBER_CONTIG           \
-                                           | CA_KERNEL_WRITE)),               \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_in),  (ca_in),  CA_SLAB_AXES,        \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    (flags) | CA_KERNEL_FIBER_CONTIG)),       \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_out), (ca_out), CA_SLAB_AXES,        \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    ((flags) | CA_KERNEL_FIBER_CONTIG         \
+                                             | CA_KERNEL_WRITE))),            \
             (n) = (st_in).slab_dims[0],                                       \
             1);                                                               \
         __cffim_init;                                                         \
@@ -909,6 +949,73 @@ void ca_iter_state_finish (ca_iter_state *st);
             ca_iter_state_sync_slab(&(st_in)),                                \
             ca_iter_state_sync_slab(&(st_out)) )
 
+/* PAIR forms: two sources read together along the same axis.
+
+   The INOUT forms cover input + output.  These cover input + input, which
+   is what a routine taking two vectors of the same length wants -- a
+   correlation, a dot product, a distance.  Neither state gets
+   CA_KERNEL_WRITE, and `flags` must not carry it: use the INOUT forms to
+   write.
+
+   Both fibers are contig-delivered, so the pair may be handed straight to
+   a C routine that walks it itself.  The MASKED form yields BOTH mask
+   cursors: which cells a pair of fibers may be used at is a question about
+   both of them, and the INOUT forms answer only about the input.
+
+   Shape agreement is guarded the way the INOUT forms guard it (ndim,
+   elements, fiber length), and the body is skipped on mismatch.  The two
+   sources may be the same array. */
+
+#define CA_FOR_EACH_FIBER_PAIR(st_a, st_b, ca_a, ca_b, axis,                  \
+                               flags, p_a, p_b, n)                            \
+  for ( int __cffp_init = (                                                   \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_a), (ca_a), CA_SLAB_AXES,            \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    (flags) | CA_KERNEL_FIBER_CONTIG)),       \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_b), (ca_b), CA_SLAB_AXES,            \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    (flags) | CA_KERNEL_FIBER_CONTIG)),       \
+            (n) = (st_a).slab_dims[0],                                        \
+            1);                                                               \
+        __cffp_init;                                                          \
+        __cffp_init = 0,                                                      \
+          ca_iter_state_finish(&(st_a)),                                      \
+          ca_iter_state_finish(&(st_b)) )                                     \
+    for ( ; (st_a).src->ndim     == (st_b).src->ndim                          \
+         && (st_a).src->elements == (st_b).src->elements                      \
+         && (st_a).slab_dims[0]  == (st_b).slab_dims[0]                       \
+         && ca_iter_state_next_slab_axes(&(st_a), &(p_a), NULL)               \
+         && ca_iter_state_next_slab_axes(&(st_b), &(p_b), NULL);              \
+            ca_iter_state_sync_slab(&(st_a)),                                 \
+            ca_iter_state_sync_slab(&(st_b)) )
+
+#define CA_FOR_EACH_FIBER_PAIR_MASKED(st_a, st_b, ca_a, ca_b, axis,           \
+                                      flags, p_a, p_b, n, m_a, m_b)           \
+  for ( int __cffpm_init = (                                                  \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_a), (ca_a), CA_SLAB_AXES,            \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    (flags) | CA_KERNEL_FIBER_CONTIG)),       \
+            ca_iter_check_init(                                               \
+              ca_iter_state_init_l2(&(st_b), (ca_b), CA_SLAB_AXES,            \
+                                    (int8_t[]){(int8_t)(axis)}, 1,            \
+                                    (flags) | CA_KERNEL_FIBER_CONTIG)),       \
+            (n) = (st_a).slab_dims[0],                                        \
+            1);                                                               \
+        __cffpm_init;                                                         \
+        __cffpm_init = 0,                                                     \
+          ca_iter_state_finish(&(st_a)),                                      \
+          ca_iter_state_finish(&(st_b)) )                                     \
+    for ( ; (st_a).src->ndim     == (st_b).src->ndim                          \
+         && (st_a).src->elements == (st_b).src->elements                      \
+         && (st_a).slab_dims[0]  == (st_b).slab_dims[0]                       \
+         && ca_iter_state_next_slab_axes(&(st_a), &(p_a), &(m_a))             \
+         && ca_iter_state_next_slab_axes(&(st_b), &(p_b), &(m_b));            \
+            ca_iter_state_sync_slab(&(st_a)),                                 \
+            ca_iter_state_sync_slab(&(st_b)) )
+
 /* ---- Phase D: per-data_type reduction macro suite ----------------------- */
 
 /* CA_SLAB_REDUCE_T(T, ...): generic per-data_type slab reduction.  T is the

data/ext/ca_obj_array.c

@@ -825,26 +825,17 @@ rb_ca_s_allocate (VALUE klass)
   return TypedData_Make_Struct(klass, CArray, &carray_data_type, ca);
 }
 
-/* @overload  initialize(data_type, dim, bytes=0) { ... }
+/* Reads the (data_type, dim, bytes: nil) argument list that CArray.new
+   and CArray.__empty__ share.  The two differ only in whether the buffer
+   is filled, so the rule for reading their arguments -- the optional
+   bytes for a fixlen, the refusal of a Class, the guess of the data type,
+   the demand that dim be an Array -- is written once here. */
 
-Constructs a new CArray object of <i>data_type</i>, which has the
-ndim and the dimensions specified by an <code>Array</code> of
-<code>Integer</code> or an argument list of <code>Integer</code>.
-The byte size of each element for the fixed length data type
-(<code>data_type == CA_FIXLEN</code>) is specified optional argument
-<i>bytes</i>. Otherwise, this optional argument has no
-effect. If the block is given, the new CArray
-object will be initialized by the value returned from the block.
-*/
-
-static VALUE
-rb_ca_initialize (int argc, VALUE *argv, VALUE self)
+static void
+ca_scan_construct_args (int argc, VALUE *argv, int8_t *data_type,
+                        ca_size_t *bytes, int8_t *ndim, ca_size_t *dim)
 {
   volatile VALUE rtype, rdim, ropt, rbytes = Qnil;
-  CArray *ca;
-  int8_t data_type, ndim;
-  ca_size_t dim[CA_RANK_MAX];
-  ca_size_t bytes;
   int8_t i;
 
   rb_scan_args(argc, argv, "21", (VALUE *)&rtype, (VALUE *) &rdim, (VALUE *) &ropt);
@@ -863,13 +854,36 @@ rb_ca_initialize (int argc, VALUE *argv, VALUE self)
              rtype, rtype, rtype);
   }
 
-  rb_ca_guess_type_and_bytes(rtype, rbytes, &data_type, &bytes);
+  rb_ca_guess_type_and_bytes(rtype, rbytes, data_type, bytes);
 
   Check_Type(rdim, T_ARRAY);
-  ndim = RARRAY_LEN(rdim);
-  for (i=0; i<ndim; i++) {
+  *ndim = RARRAY_LEN(rdim);
+  for (i=0; i<*ndim; i++) {
     dim[i] = NUM2SIZE(rb_ary_entry(rdim, i));
   }
+}
+
+/* @overload  initialize(data_type, dim, bytes=0) { ... }
+
+Constructs a new CArray object of <i>data_type</i>, which has the
+ndim and the dimensions specified by an <code>Array</code> of
+<code>Integer</code> or an argument list of <code>Integer</code>.
+The byte size of each element for the fixed length data type
+(<code>data_type == CA_FIXLEN</code>) is specified optional argument
+<i>bytes</i>. Otherwise, this optional argument has no
+effect. If the block is given, the new CArray
+object will be initialized by the value returned from the block.
+*/
+
+static VALUE
+rb_ca_initialize (int argc, VALUE *argv, VALUE self)
+{
+  CArray *ca;
+  int8_t data_type, ndim;
+  ca_size_t dim[CA_RANK_MAX];
+  ca_size_t bytes;
+
+  ca_scan_construct_args(argc, argv, &data_type, &bytes, &ndim, dim);
 
   TypedData_Get_Struct(self, CArray, &carray_data_type, ca);
   if ( ca_func[CA_OBJ_ARRAY].pool_init ) {
@@ -1438,6 +1452,33 @@ rb_ca_s_alloc_uninit (VALUE klass, VALUE rtype, VALUE rshape)
   return rb_carray_new(data_type, ndim, dim, bytes, NULL);
 }
 
+/* Internal primitive behind CArray.empty(data_type, dim, bytes: nil) in
+   lib/carray/construct.rb, which also routes the compatibility spelling
+   CArray.empty(*shape).  It is CArray.new with the fill left out: the
+   arguments are read by the same function, and the buffer comes from
+   rb_carray_new (= no MEMZERO) rather than rb_carray_new_safe.  A block
+   is refused -- filling is what CArray.new is for.  CA_OBJECT still
+   falls through to the zero-VALUE init inside carray_setup_i (= required
+   for GC), so any data_type is safe to ask for. */
+
+static VALUE
+rb_ca_s_empty (int argc, VALUE *argv, VALUE klass)
+{
+  int8_t data_type, ndim;
+  ca_size_t dim[CA_RANK_MAX];
+  ca_size_t bytes;
+
+  if ( rb_block_given_p() ) {
+    rb_raise(rb_eArgError,
+             "CArray.empty does not take a block "
+             "(its contents are left undefined); use CArray.new to fill.");
+  }
+
+  ca_scan_construct_args(argc, argv, &data_type, &bytes, &ndim, dim);
+
+  return rb_carray_new(data_type, ndim, dim, bytes, NULL);
+}
+
 void
 Init_ca_obj_array (void)
 {
@@ -1449,6 +1490,7 @@ Init_ca_obj_array (void)
   rb_define_method(rb_cCArray, "initialize", rb_ca_initialize, -1);
   rb_define_singleton_method(rb_cCArray, "__alloc_uninit__",
                              rb_ca_s_alloc_uninit, 2);
+  rb_define_singleton_method(rb_cCArray, "__empty__", rb_ca_s_empty, -1);
 
   rb_define_singleton_method(rb_cCArray, "fixlen", rb_ca_s_fixlen, -1);
   rb_define_singleton_method(rb_cCArray, "boolean", rb_ca_s_boolean, -1);

data/ext/ca_obj_block.c

@@ -269,8 +269,10 @@ rb_cb_initialize_copy (VALUE self, VALUE other)
 }
 
 /* Per-axis accessor macro: defines a method that returns the named
-   CABlock tail array (size0 / start / step / count) as a Ruby Array.
-   `offset` is a single Integer and uses its own accessor below. */
+   CABlock tail array (size0 / start / step) as a Ruby Array.
+   `offset` is a single Integer and uses its own accessor below.
+   `count` has no accessor: it is what `shape` already answers, and the
+   name belongs to CArray#count. */
 #define rb_cb_get_attr_ary(name)                    \
 rb_cb_ ## name (VALUE self)                         \
 {                                                   \
@@ -288,7 +290,6 @@ rb_cb_ ## name (VALUE self)                         \
 static VALUE rb_cb_get_attr_ary(size0)
 static VALUE rb_cb_get_attr_ary(start)
 static VALUE rb_cb_get_attr_ary(step)
-static VALUE rb_cb_get_attr_ary(count)
 
 static VALUE
 rb_cb_offset (VALUE self)
@@ -376,7 +377,6 @@ Init_ca_obj_block (void)
   rb_define_method(rb_cCABlock, "size0",  rb_cb_size0, 0);
   rb_define_method(rb_cCABlock, "start",  rb_cb_start, 0);
   rb_define_method(rb_cCABlock, "step",   rb_cb_step, 0);
-  rb_define_method(rb_cCABlock, "count",  rb_cb_count, 0);
   rb_define_method(rb_cCABlock, "offset", rb_cb_offset, 0);
 
   rb_define_method(rb_cCABlock, "idx2addr0",   rb_cb_idx2addr0, -1);

data/ext/ca_obj_const_string.c

@@ -38,10 +38,10 @@
 typedef struct {
   /* === CAView prefix === */
   int16_t    obj_type;
-  int8_t     data_type;        /* CA_FIXLEN surface (numeric gate); storage is int64 */
+  int8_t     data_type;        /* CA_FIXLEN surface (numeric gate); storage is fixlen-16 */
   int8_t     ndim;
   int32_t    flags;            /* CA_FLAG_IS_FACE set */
-  ca_size_t  bytes;            /* sizeof(int64_t) = 8 (one offset per element) */
+  ca_size_t  bytes;            /* 2 * sizeof(int64_t) = 16 (one (start,end) pair per element) */
   ca_size_t  elements;
   ca_size_t *dim;
   char      *ptr;
@@ -299,6 +299,54 @@ rb_ca_const_string_wrap (VALUE parent_val, VALUE buffer, int encoding_id)
     rb_raise(rb_eTypeError, "CAConstString.wrap: buffer: must be a String");
   }
 
+  /* This is the one door through which already-built offsets enter, so it
+     validates rather than assumes.  Everything downstream -- the per-cell
+     decode, the native byte scans, the sort comparator -- reads `buf + start`
+     for `end - start` bytes on the strength of these pairs; an out-of-range
+     one is an out-of-bounds read of the heap, not a wrong answer.  Refuse it
+     here, while the input is still in the caller's hands, rather than letting
+     it surface as an IndexError from a decode or as a crash from a scan.
+
+     A masked cell is exempt: its bytes may be anything at all, that being the
+     CArray mask contract, and no reader dereferences them (the scan skips on
+     the mask before touching an offset; `.value`, the explicit strip, raises
+     from the decode). */
+  {
+    ca_size_t i, n;
+    int64_t *pair;
+    boolean8_t *m;
+
+    ca_attach(parent);
+    ca_update_mask(parent);
+    n    = parent->elements;
+    pair = (int64_t *) parent->ptr;
+    m    = parent->mask ? (boolean8_t *) parent->mask->ptr : NULL;
+    for ( i = 0; i < n; i++ ) {
+      int64_t start = pair[2 * i], end = pair[2 * i + 1];
+      if ( m && m[i] ) {
+        continue;
+      }
+      if ( start < 0 || end < start || end > (int64_t) RSTRING_LEN(buffer) ) {
+        ca_detach(parent);
+        rb_raise(rb_eArgError,
+                 "CAConstString.wrap: element %lld has range [%lld,%lld), "
+                 "outside the %ld-byte buffer",
+                 (long long) i, (long long) start, (long long) end,
+                 (long) RSTRING_LEN(buffer));
+      }
+    }
+    ca_detach(parent);
+  }
+
+  /* Take ownership of the offsets, the way CACategorical.from_codes takes
+     ownership of its codes.  Without this the Face is read-only but its
+     storage is not, so `cs.parent[i] = <anything>` walks straight past the
+     check above and back into an out-of-bounds read.  The flag rather than
+     #freeze, for the reason from_codes gives: freeze would propagate through
+     views and Faces.  A caller that wants to keep a mutable entity of its own
+     passes `.copy`. */
+  ca_set_flag(parent, CA_FLAG_READ_ONLY);
+
   ca  = ca_const_string_new(parent, rb_str_freeze(buffer), encoding_id);
   obj = TypedData_Wrap_Struct(rb_cCAConstString, &catext_data_type, ca);
   rb_ca_set_parent(obj, parent_val);   /* pin parent VALUE for GC */
@@ -397,10 +445,13 @@ rb_ca_const_string_encoding (VALUE self)
   return rb_enc_from_encoding(rb_enc_from_index(ca->encoding_id));
 }
 
-/* `CAConstString#buffer` — returns the frozen internal byte buffer
-   (length-prefix format).  Exposes the defining tail state for
-   introspection and the Arrow-boundary component-buffer export
-   path. */
+/* `CAConstString#buffer` — returns the frozen internal byte buffer: a pure
+   concatenation of the element bytes, with no per-record length prefix (=
+   the Arrow values buffer).  Exposes the defining tail state for
+   introspection and the Arrow-boundary component-buffer export path.  The
+   ranges that index it live in the storage, one (start,end) int64 pair per
+   element; `wrap` is where a hand-built pair array is checked against a
+   buffer. */
 static VALUE
 rb_ca_const_string_buffer (VALUE self)
 {
@@ -540,7 +591,7 @@ ca_const_string_scan_end (ca_const_string_scan_t *s)
    so element i occupies s->off[2*i] (start) .. s->off[2*i+1] (end).
    The buffer is a pure concatenation; length = end - start. */
 static inline int
-ca_const_string_record (ca_const_string_scan_t *s, ca_size_t i, const char **pp, int32_t *plen)
+ca_const_string_record (ca_const_string_scan_t *s, ca_size_t i, const char **pp, int64_t *plen)
 {
   int64_t start, end;
   if ( s->m && s->m[i] ) {
@@ -549,7 +600,7 @@ ca_const_string_record (ca_const_string_scan_t *s, ca_size_t i, const char **pp,
   start = s->off[2 * i];
   end   = s->off[2 * i + 1];
   *pp   = s->buf + start;
-  *plen = (int32_t) (end - start);
+  *plen = (int64_t) (end - start);
   return 1;
 }
 
@@ -598,7 +649,7 @@ rb_ca_const_string_byte_length (VALUE self)
   CArray *co;
   int64_t *op;
   const char *p;
-  int32_t len;
+  int64_t len;
   ca_size_t i;
 
   ca_const_string_scan_begin(self, &s);
@@ -633,7 +684,7 @@ ca_const_string_predicate (VALUE self, VALUE query, int op)
   boolean8_t *out;
   const char *qp, *p;
   long qlen;
-  int32_t len;
+  int64_t len;
   ca_size_t i;
 
   if ( TYPE(query) != T_STRING ) {
@@ -686,7 +737,7 @@ rb_ca_const_string_eq (VALUE self, VALUE other)
        they are read only when both records are valid, but GCC cannot prove
        that -- initialize to keep -Wmaybe-uninitialized quiet and defensive. */
     const char *pa = NULL, *pb = NULL;
-    int32_t la = 0, lb = 0;
+    int64_t la = 0, lb = 0;
     ca_size_t i;
 
     ca_const_string_scan_begin(self, &a);
@@ -717,7 +768,7 @@ rb_ca_const_string_count (VALUE self, VALUE query)
   ca_const_string_scan_t s;
   const char *qp, *p;
   long qlen;
-  int32_t len;
+  int64_t len;
   ca_size_t i, c = 0;
 
   if ( TYPE(query) != T_STRING ) {
@@ -747,7 +798,7 @@ rb_ca_const_string_search (VALUE self, VALUE query)
   ca_const_string_scan_t s;
   const char *qp, *p;
   long qlen;
-  int32_t len;
+  int64_t len;
   ca_size_t i;
   VALUE result = Qnil;
 
@@ -786,7 +837,7 @@ ca_const_string_byte_cmp (const void *a, const void *b)
   /* sort raises on masked input, so record() always sets these here; the
      initializers keep -Wmaybe-uninitialized quiet and stay defensive. */
   const char *pa = NULL, *pb = NULL;
-  int32_t la = 0, lb = 0;
+  int64_t la = 0, lb = 0;
   int c;
   ca_const_string_record(ca_const_string_sort_ctx, ia, &pa, &la);
   ca_const_string_record(ca_const_string_sort_ctx, ib, &pb, &lb);
@@ -836,9 +887,15 @@ rb_ca_const_string_sort_index (VALUE self)
   return vout;
 }
 
-/* CAConstString#sort is defined in Ruby (lib/carray/const_string.rb) as `self[sort_index]`,
-   i.e. a no-copy view over the offset source (buffer + offsets shared, only
-   the gather order changes) — consistent with CArray#sort being a view. */
+/* The ordering surface is defined in Ruby (lib/carray/const_string.rb) on
+   top of these three: a storage cell is a byte range, so storage order is
+   insertion order rather than string order, and every member has to read
+   the bytes.  What is native here is the flat form, which is the common one
+   for a string column and which a byte scan does an order of magnitude
+   faster than decoding a Ruby String per cell; the per-axis forms go
+   through #to_string.  These are spelled as internals because the public
+   names carry CArray's meanings: what the permutation below answers is
+   sort_addr (view-flat addresses in sorted order), not sort_index. */
 
 /* CAConstString#min / #max → the byte-min / byte-max element as a frozen String,
    skipping masked elements; nil if empty or all masked. */
@@ -847,7 +904,7 @@ ca_const_string_extremum (VALUE self, int want_max)
 {
   ca_const_string_scan_t s;
   const char *p, *bestp = NULL;
-  int32_t len, bestlen = 0;
+  int64_t len, bestlen = 0;
   ca_size_t i;
   int found = 0;
 
@@ -894,9 +951,9 @@ rb_ca_const_string_initialize_copy (VALUE self, VALUE other)
   CAConstString *ca, *cs;
   TypedData_Get_Struct(self,  CAConstString, &catext_data_type, ca);
   TypedData_Get_Struct(other, CAConstString, &catext_data_type, cs);
-  /* T.0/T.1: shallow re-setup (shares buffer + offset-source).  T.3 will
-     replace this with compacting deep copy (rebased offsets + compacted
-     buffer + detach). */
+  /* Shallow re-setup: shares the buffer and the offset source, which is the
+     documented `dup` semantics for a view.  `copy` is the compacting deep
+     copy (rebased offsets, compacted buffer, detached). */
   if ( ca_func[CA_OBJ_CONST_STRING].pool_init ) {
     ca_array_pool_alloc(ca, CA_OBJ_CONST_STRING, cs->parent->ndim);
   }
@@ -949,11 +1006,13 @@ Init_ca_obj_const_string (void)
   rb_define_method(rb_cCAConstString, "search",           rb_ca_const_string_search, 1);
   rb_define_method(rb_cCAConstString, "find_value_index",  rb_ca_const_string_search, 1);
 
-  /* native sort_index / min / max (§3.7), byte-memcmp comparator.
-     sort / sort_copy are defined in Ruby on top of sort_index. */
-  rb_define_method(rb_cCAConstString, "sort_index", rb_ca_const_string_sort_index, 0);
-  rb_define_method(rb_cCAConstString, "min",        rb_ca_const_string_min, 0);
-  rb_define_method(rb_cCAConstString, "max",        rb_ca_const_string_max, 0);
+  /* Native flat sort permutation / min / max (§3.7), byte-memcmp
+     comparator.  The public ordering surface is built on these in
+     lib/carray/const_string.rb; see the comment above their definitions. */
+  rb_define_method(rb_cCAConstString, "__sort_addr_bytes__",
+                                      rb_ca_const_string_sort_index, 0);
+  rb_define_method(rb_cCAConstString, "__min_bytes__", rb_ca_const_string_min, 0);
+  rb_define_method(rb_cCAConstString, "__max_bytes__", rb_ca_const_string_max, 0);
 
   /* Y-pilot: Face-local C-level fast path for per-cell scalar fetch. */
   ca_face_register_storage_to_scalar(CA_OBJ_CONST_STRING, rb_ca_const_string_storage_to_scalar);

data/ext/ca_obj_face.c

@@ -595,6 +595,30 @@ ca_face_class_has_portable_method (VALUE klass)
   return ( owner != rb_singleton_class(rb_cCArray) ) ? 1 : 0;
 }
 
+VALUE
+ca_face_operand_descend (VALUE operand, const char *name)
+{
+  CArray *op;
+  if ( ! RTEST(rb_obj_is_carray(operand)) ) {
+    return operand;
+  }
+  TypedData_Get_Struct(operand, CArray, &carray_data_type, op);
+  if ( ! ca_is_face(op) ) {
+    return operand;
+  }
+  if ( ca_test_flag(op, CA_FLAG_FACE_COMPARABLE_STORAGE) ) {
+    return rb_ca_strip_face_value(operand);
+  }
+  rb_raise(rb_eArgError,
+           "%s: cannot take a %s operand: its storage is not its surface "
+           "(a cell encodes the value rather than being it), so comparing "
+           "the storage would compare the encoding. Convert the operand to "
+           "the receiver's space first -- #to_string for a string Face -- "
+           "or pass .parent on both sides to work in storage space",
+           name, rb_obj_classname(operand));
+  return Qnil;   /* not reached */
+}
+
 int
 ca_face_state_portable (int obj_type, VALUE klass)
 {