carray 3.0.3 → 3.0.4

data/ext/ca_obj_binop.c

@@ -177,6 +177,7 @@ ca_binop_setup (CABinOp *ca, CArray *left, CArray *right, uint16_t op_id)
 CABinOp *
 ca_binop_new (CArray *left, CArray *right, uint16_t op_id)
 {
+  /* check: the setup checks nothing */
   CABinOp *ca = (CABinOp *) ca_array_alloc(CA_OBJ_BINOP, left->ndim);
   ca_binop_setup(ca, left, right, op_id);
   return ca;
@@ -227,7 +228,7 @@ ca_binop_func_xfer_index (void *ap, ca_size_t *idx, void *data, int dir)
   ca_size_t s;
 
   if ( dir != CA_XFER_GET ) {
-    rb_raise(rb_eRuntimeError, "CABinOp is read-only (xfer_index PUT)");
+    ca_refuse_read_only();
   }
 
   s = ca->bytes;
@@ -322,7 +323,7 @@ ca_binop_eval (CABinOp *bo, const ca_lazy_req_t *req, void *data)
     boolean8_t *slab_mask = NULL;
     void *mscratch = NULL;
 
-    if ( ca_binop_is_trapping(bo->op_id, bo->data_type) ) {
+    if ( ca_op_raises_on_cell(CA_OP_KIND_BINOP, bo->op_id, bo->data_type) ) {
       CArray *ops[2];
       ops[0] = bo->parent;
       ops[1] = bo->right;
@@ -356,7 +357,7 @@ ca_binop_func_xfer_stride (void *ap, ca_size_t *starts, ca_size_t *counts,
   if ( ca_region_is_empty(((CArray *) ap)->ndim, counts) ) return;
   ca_lazy_req_t req;
   if ( dir != CA_XFER_GET ) {
-    rb_raise(rb_eRuntimeError, "CABinOp is read-only (xfer_stride PUT)");
+    ca_refuse_read_only();
   }
   ca_lazy_req_region(&req, ap, starts, counts, strides);
   ca_binop_eval((CABinOp *) ap, &req, data);
@@ -370,7 +371,7 @@ ca_binop_func_xfer_addrs (void *ap, ca_size_t n, ca_size_t *addrs,
 {
   ca_lazy_req_t req;
   if ( dir != CA_XFER_GET ) {
-    rb_raise(rb_eRuntimeError, "CABinOp is read-only (xfer_addrs PUT)");
+    ca_refuse_read_only();
   }
   ca_lazy_req_addrs(&req, n, addrs);
   ca_binop_eval((CABinOp *) ap, &req, data);
@@ -393,15 +394,7 @@ static void
 ca_binop_func_allocate (void *ap)
 {
   CABinOp *ca = (CABinOp *) ap;
-  ca->ptr = xmalloc(ca_length(ca));
-  /* CA_OBJECT cells are VALUEs and this buffer is about to be marked as
-     soon as the view is, so it must not be handed to the GC as raw
-     xmalloc garbage. */
-  if ( ca->data_type == CA_OBJECT ) {
-    VALUE *p = (VALUE *) ca->ptr;
-    ca_size_t i;
-    for ( i = 0; i < ca->elements; i++ ) *p++ = Qnil;
-  }
+  ca->ptr = ca_alloc_cells((CArray *) ca);
 }
 
 static void
@@ -418,19 +411,11 @@ ca_binop_func_attach (void *ap)
   int8_t    k;
   ca_size_t s;
 
-  ca->ptr = xmalloc(ca_length(ca));
+  ca->ptr = ca_alloc_cells((CArray *) ca);
 
   s = ca->bytes;
   for ( k = ca->ndim - 1; k >= 0; k-- ) { native[k] = s; s *= ca->dim[k]; }
   for ( k = 0; k < ca->ndim; k++ ) starts[k] = 0;
-  /* CA_OBJECT cells are VALUEs and this buffer is about to be marked as
-     soon as the view is, so it must not be handed to the GC as raw
-     xmalloc garbage. */
-  if ( ca->data_type == CA_OBJECT ) {
-    VALUE *p = (VALUE *) ca->ptr;
-    ca_size_t i;
-    for ( i = 0; i < ca->elements; i++ ) *p++ = Qnil;
-  }
   ca_binop_func_xfer_stride(ca, starts, ca->dim, native, ca->ptr, CA_XFER_GET);
 }
 
@@ -452,7 +437,7 @@ NORETURN(static void ca_binop_func_fill_data (void *ap, void *ptr));
 static void
 ca_binop_func_fill_data (void *ap, void *ptr)
 {
-  rb_raise(rb_eRuntimeError, "CABinOp is read-only (fill_data)");
+  ca_refuse_read_only();
 }
 
 /* Build out.mask: the operands' masks ORed on each read (CAMaskOfOperands), so
@@ -605,8 +590,7 @@ rb_ca_binop_build (VALUE l_cary, VALUE r_cary, uint16_t op_id)
   /* No kernel for that data_type (fixlen arithmetic, ...): raise as the
      eager binop does, before a view is built over it. */
   if ( ca_binop_kernel_lookup_vv(op_id, l_in_dt) == ca_binop_not_implement ) {
-    rb_raise(rb_eCADataTypeError,
-             "invalid data_type for binop (not implemented)");
+    ca_op_refuse_unimplemented(l_cary, l_in_dt, rb_eCADataTypeError);
   }
 
   if ( l_in_dt != l->data_type ) {
@@ -694,6 +678,7 @@ rb_ca_binop_build (VALUE l_cary, VALUE r_cary, uint16_t op_id)
 static VALUE
 rb_ca_binop_s_build (VALUE klass, VALUE l_cary, VALUE r_cary, VALUE op_id_val)
 {
+  /* fits: an operation number from the library's own table */
   uint16_t op_id = (uint16_t) NUM2UINT(op_id_val);
   (void) klass;
   return rb_ca_binop_build(l_cary, r_cary, op_id);
@@ -708,7 +693,7 @@ rb_ca_binop_trapping (VALUE self)
 {
   CABinOp *bo;
   TypedData_Get_Struct(self, CABinOp, &cabinop_data_type, bo);
-  return ca_binop_is_trapping(bo->op_id, bo->data_type) ? Qtrue : Qfalse;
+  return ca_op_raises_on_cell(CA_OP_KIND_BINOP, bo->op_id, bo->data_type) ? Qtrue : Qfalse;
 }
 
 static VALUE
@@ -729,6 +714,7 @@ rb_ca_binop_right (VALUE self)
 }
 
 /* Test instrumentation (mirrors CAMonOp counters). */
+#ifdef CARRAY_DEV_BUILD
 static VALUE
 rb_ca_binop_s_reset_scratch_counter (VALUE klass)
 {
@@ -754,6 +740,7 @@ rb_ca_binop_s_materialise_count (VALUE klass)
 {
   return SIZE2NUM(ca_binop_materialise_call_count);
 }
+#endif /* CARRAY_DEV_BUILD */
 
 static VALUE
 rb_ca_binop_s_allocate (VALUE klass)
@@ -834,6 +821,7 @@ Init_ca_obj_binop (void)
                                 rb_ca_binop_right, 0);
 
   /* Test instrumentation, not user-facing. */
+#ifdef CARRAY_DEV_BUILD
   rb_define_singleton_method(rb_cCABinOp, "__reset_scratch_counter__",
                              rb_ca_binop_s_reset_scratch_counter, 0);
   rb_define_singleton_method(rb_cCABinOp, "__scratch_count__",
@@ -842,4 +830,5 @@ Init_ca_obj_binop (void)
                              rb_ca_binop_s_reset_materialise_counter, 0);
   rb_define_singleton_method(rb_cCABinOp, "__materialise_count__",
                              rb_ca_binop_s_materialise_count, 0);
+#endif
 }

data/ext/ca_obj_bitarray.c

@@ -98,6 +98,7 @@ ca_bitarray_setup (CABitarray *ca, CArray *parent)
 
   /* The bits of one byte would share that byte's one mask cell, so a bit
      view takes no masked array and holds no mask of its own. */
+  /* mask: the constructor asks first, before it allocates (ca == NULL) */
   if ( ca_has_mask(parent) ) {
     rb_raise(rb_eArgError,
              "bitarray: the array has a mask, which a bit view can not "
@@ -395,7 +396,7 @@ ca_bitarray_func_allocate (void *ap)
 {
   CABitarray *ca = (CABitarray *) ap;
   ca_attach(ca->parent);
-  ca->ptr = xmalloc(ca_length(ca));
+  ca->ptr = ca_alloc_cells((CArray *) ca);
 }
 
 static void
@@ -403,7 +404,7 @@ ca_bitarray_func_attach (void *ap)
 {
   CABitarray *ca = (CABitarray *) ap;
   ca_attach(ca->parent);
-  ca->ptr = xmalloc(ca_length(ca));
+  ca->ptr = ca_alloc_cells((CArray *) ca);
   ca_bitarray_attach(ca);
 }
 

data/ext/ca_obj_bitfield.c

@@ -205,7 +205,7 @@ ca_bitfield_setup (CABitfield *ca, CArray *parent,
     data_type = CA_UINT64;
   }
 
-  CA_CHECK_BYTES(data_type, bytes);
+  CA_CHECK_BYTES_GIVEN(data_type, bytes);
 
   if ( bitlen > bytes * 8 ||
        ( ( data_type == CA_BOOLEAN ) && ( bitlen > 1 ) ) ) {
@@ -273,9 +273,6 @@ ca_bitfield_setup (CABitfield *ca, CArray *parent,
 
   memcpy(ca->dim, parent->dim, ndim * sizeof(ca_size_t));
 
-  if ( ca_has_mask(parent) ) {
-    ca_create_mask(ca);
-  }
 
   return 0;
 }
@@ -288,6 +285,7 @@ ca_bitfield_new (CArray *parent, ca_size_t offset, ca_size_t bitlen,
   ca_bitfield_setup(NULL, parent, offset, bitlen, data_type);
   ca = (CABitfield *) ca_array_alloc(CA_OBJ_BITFIELD, parent->ndim);
   ca_bitfield_setup(ca, parent, offset, bitlen, data_type);
+  ca_fill_or_free((CArray *) ca, ca_view_inherit_mask, (VALUE) ca);
   return ca;
 }
 
@@ -452,7 +450,7 @@ ca_bitfield_func_allocate (void *ap)
 {
   CABitfield *ca = (CABitfield *) ap;
   ca_attach(ca->parent);
-  ca->ptr = xmalloc(ca_length(ca));
+  ca->ptr = ca_alloc_cells((CArray *) ca);
 }
 
 static void
@@ -460,7 +458,7 @@ ca_bitfield_func_attach (void *ap)
 {
   CABitfield *ca = (CABitfield *) ap;
   ca_attach(ca->parent);
-  ca->ptr = xmalloc(ca_length(ca));
+  ca->ptr = ca_alloc_cells((CArray *) ca);
   ca_bitfield_attach(ca);
 }
 
@@ -708,6 +706,7 @@ rb_ca_bitfield_initialize_copy (VALUE self, VALUE other)
   }
   ca_bitfield_setup(ca, cs->parent, cs->bit_start, cs->bit_length,
                     cs->data_type);
+  ca_view_inherit_mask((VALUE) ca);
 
   return self;
 }

data/ext/ca_obj_block.c

@@ -124,6 +124,12 @@ ca_block_setup (CABlock *ca, CArray *parent, int8_t ndim, ca_size_t *dim,
     }
   }
 
+  /* ca == NULL asks for the checks above only, so that a constructor can
+     run them before it allocates. */
+  if ( ca == NULL ) {
+    return 0;
+  }
+
   /* strides[k] = step[k] * Pi_{j>k} size0[j] * parent->bytes */
   suffix = parent->bytes;
   for (i = ndim - 1; i >= 0; i--) {
@@ -141,10 +147,9 @@ ca_block_setup (CABlock *ca, CArray *parent, int8_t ndim, ca_size_t *dim,
     }
   }
 
-  /* CAREFUL: the CABlock tail (offset / start / step / count / size0)
-     must be filled BEFORE ca_stride_setup.  ca_stride_setup may auto-
-     dispatch ca_create_mask when the parent has a mask, and
-     ca_block_func_create_mask reads those tail fields.
+  /* The CABlock tail (offset / start / step / count / size0) is filled
+     here; ca_block_func_create_mask reads it when the constructor takes
+     the parent's mask (ca_view_inherit_mask) after this setup.
 
      Pool path: start/step/count/size0 already point into _pool (wired
      by ca_block_pool_init); only memcpy the values.  Non-pool path:
@@ -161,10 +166,10 @@ ca_block_setup (CABlock *ca, CArray *parent, int8_t ndim, ca_size_t *dim,
   memcpy(ca->count, count, ndim * sizeof(ca_size_t));
   memcpy(ca->size0, dim,   ndim * sizeof(ca_size_t));
 
-  ca_stride_setup((CAStride *) ca, CA_OBJ_BLOCK, parent,
-                  parent->data_type, parent->bytes,
-                  ndim, count, strides,
-                  base_offset_elements * parent->bytes);
+  ca_stride_setup_view((CAStride *) ca, CA_OBJ_BLOCK, parent,
+                       parent->data_type, parent->bytes,
+                       ndim, count, strides,
+                       base_offset_elements * parent->bytes);
 
   return 0;
 }
@@ -174,8 +179,11 @@ ca_block_new (CArray *parent, int8_t ndim, ca_size_t *dim,
               ca_size_t *start, ca_size_t *step, ca_size_t *count,
               ca_size_t offset)
 {
-  CABlock *ca = (CABlock *) ca_array_alloc(CA_OBJ_BLOCK, ndim);
+  CABlock *ca;
+  ca_block_setup(NULL, parent, ndim, dim, start, step, count, offset);
+  ca = (CABlock *) ca_array_alloc(CA_OBJ_BLOCK, ndim);
   ca_block_setup(ca, parent, ndim, dim, start, step, count, offset);
+  ca_fill_or_free((CArray *) ca, ca_view_inherit_mask, (VALUE) ca);
   return ca;
 }
 
@@ -265,6 +273,7 @@ rb_cb_initialize_copy (VALUE self, VALUE other)
   }
   ca_block_setup(ca, cs->parent, cs->ndim, cs->size0,
                  cs->start, cs->step, cs->count, cs->offset);
+  ca_view_inherit_mask((VALUE) ca);
   rb_ca_set_parent(self, rb_ca_parent(other));
   return self;
 }

data/ext/ca_obj_byte_swap.c

@@ -193,7 +193,7 @@ VALUE rb_cCAByteSwap;
 int
 ca_byte_swap_setup (CAByteSwap *ca, CArray *parent, VALUE data_class)
 {
-  CA_CHECK_DATA_TYPE(parent->data_type);
+  CA_CHECK_DATA_TYPE_GIVEN(parent->data_type);
 
   if ( parent->data_type == CA_OBJECT ) {
     rb_raise(rb_eCADataTypeError, "object array can't be byte-swapped");
@@ -223,9 +223,6 @@ ca_byte_swap_setup (CAByteSwap *ca, CArray *parent, VALUE data_class)
   ca->nosync    = 0;
   ca->data_class = data_class;   /* Qnil if parent has no data_class */
 
-  if ( ca_has_mask(parent) ) {
-    ca_create_mask(ca);
-  }
   if ( ca_is_scalar(parent) ) {
     ca_set_flag(ca, CA_FLAG_SCALAR);
   }
@@ -240,6 +237,7 @@ ca_byte_swap_new (CArray *parent, VALUE data_class)
   ca_byte_swap_setup(NULL, parent, data_class);
   ca = (CAByteSwap *) ca_array_alloc(CA_OBJ_BYTE_SWAP, parent->ndim);
   ca_byte_swap_setup(ca, parent, data_class);
+  ca_fill_or_free((CArray *) ca, ca_view_inherit_mask, (VALUE) ca);
   return ca;
 }
 
@@ -464,7 +462,7 @@ ca_byte_swap_func_allocate (void *ap)
 {
   CAByteSwap *ca = (CAByteSwap *) ap;
   ca_attach(ca->parent);
-  ca->ptr = xmalloc(ca_length(ca));
+  ca->ptr = ca_alloc_cells((CArray *) ca);
 }
 
 static void
@@ -472,7 +470,7 @@ ca_byte_swap_func_attach (void *ap)
 {
   CAByteSwap *ca = (CAByteSwap *) ap;
   ca_attach(ca->parent);
-  ca->ptr = xmalloc(ca_length(ca));
+  ca->ptr = ca_alloc_cells((CArray *) ca);
   memcpy(ca->ptr, ca->parent->ptr, ca_length(ca));
   ca_byte_swap_apply(ca, ca->ptr);
 }
@@ -664,6 +662,7 @@ rb_ca_byte_swap_initialize_copy (VALUE self, VALUE other)
     ca_array_pool_alloc(ca, CA_OBJ_BYTE_SWAP, cs->parent->ndim);
   }
   ca_byte_swap_setup(ca, cs->parent, cs->data_class);
+  ca_view_inherit_mask((VALUE) ca);
   return self;
 }
 

data/ext/ca_obj_const_string.c

@@ -31,6 +31,7 @@
 --------------------------------------------------------------------------- */
 
 #include "carray.h"
+#include "ruby/util.h"
 #include "carray_internal.h"
 #include "ca_obj_face.h"
 #include <ruby/encoding.h>
@@ -122,6 +123,12 @@ ca_const_string_setup (CAConstString *ca, CArray *parent, VALUE buffer, int enco
              "(parent.data_type must be CA_FIXLEN with bytes == 16)");
   }
 
+  /* ca == NULL asks for the checks above only, so that a constructor can
+     run them before it allocates. */
+  if ( ca == NULL ) {
+    return 0;
+  }
+
   ca->obj_type    = CA_OBJ_CONST_STRING;
   /* FIXLEN surface auto-gates mkkernel numeric dispatch. */
   ca->data_type   = CA_FIXLEN;
@@ -143,9 +150,6 @@ ca_const_string_setup (CAConstString *ca, CArray *parent, VALUE buffer, int enco
   ca->buffer      = buffer;
   ca->encoding_id = encoding_id;
 
-  if ( ca_has_mask(parent) ) {
-    ca_create_mask((CArray *) ca);
-  }
 
   if ( ca_is_scalar(parent) ) {
     ca_set_flag(ca, CA_FLAG_SCALAR);
@@ -160,8 +164,11 @@ ca_const_string_setup (CAConstString *ca, CArray *parent, VALUE buffer, int enco
 CAConstString *
 ca_const_string_new (CArray *parent, VALUE buffer, int encoding_id)
 {
-  CAConstString *ca = (CAConstString *) ca_array_alloc(CA_OBJ_CONST_STRING, parent->ndim);
+  CAConstString *ca;
+  ca_const_string_setup(NULL, parent, buffer, encoding_id);
+  ca = (CAConstString *) ca_array_alloc(CA_OBJ_CONST_STRING, parent->ndim);
   ca_const_string_setup(ca, parent, buffer, encoding_id);
+  ca_fill_or_free((CArray *) ca, ca_view_inherit_mask, (VALUE) ca);
   return ca;
 }
 
@@ -574,7 +581,9 @@ rb_ca_const_string_copy (VALUE self)
 
   ca_detach((CArray *) ca);
 
-  return rb_ca_const_string_wrap(vout, rb_str_freeze(newbuf), ca->encoding_id);
+  vout = rb_ca_const_string_wrap(vout, rb_str_freeze(newbuf), ca->encoding_id);
+  rb_ca_inherit_attr(vout, self);
+  return vout;
 }
 
 /* to_ca descends to the same compacting copy.  The result is detached
@@ -649,6 +658,7 @@ ca_const_string_scan_begin_pair (VALUE va, ca_const_string_scan_t *a,
   ca_const_string_scan_begin(va, a);
   x.self = vb;
   x.s    = b;
+  /* protect: ends the first scan, which is not an array */
   rb_protect(ca_const_string_scan_begin_body, (VALUE) &x, &tag);
   if ( tag ) {
     ca_const_string_scan_end(a);
@@ -894,13 +904,12 @@ rb_ca_const_string_search (VALUE self, VALUE query)
    byte-for-byte faithful to `to_object.sort` with no collation
    loss. */
 
-/* qsort comparator context — single-threaded under the GVL (thread-safety is
-   a non-goal; see project memory), so a file-static context is safe. */
-static ca_const_string_scan_t *ca_const_string_sort_ctx;
-
+/* The scan is passed to the comparator, not held in a static: Ractors
+   sort at the same time. */
 static int
-ca_const_string_byte_cmp (const void *a, const void *b)
+ca_const_string_byte_cmp (const void *a, const void *b, void *ctx)
 {
+  ca_const_string_scan_t *scan = (ca_const_string_scan_t *) ctx;
   ca_size_t ia = *(const ca_size_t *) a;
   ca_size_t ib = *(const ca_size_t *) b;
   /* sort raises on masked input, so record() always sets these here; the
@@ -908,13 +917,21 @@ ca_const_string_byte_cmp (const void *a, const void *b)
   const char *pa = NULL, *pb = NULL;
   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);
+  ca_const_string_record(scan, ia, &pa, &la);
+  ca_const_string_record(scan, ib, &pb, &lb);
   c = memcmp(pa, pb, (size_t) (la < lb ? la : lb));
   if ( c != 0 ) return c;
   return (la > lb) - (la < lb);
 }
 
+static int
+ca_const_string_index_cmp (const void *a, const void *b)
+{
+  ca_size_t ia = *(const ca_size_t *) a;
+  ca_size_t ib = *(const ca_size_t *) b;
+  return (ia > ib) - (ia < ib);
+}
+
 /* compute the ascending sort permutation; raises on masked input (matches
    base CArray#sort).  caller xfree()s the returned index array. */
 static ca_size_t *
@@ -928,9 +945,19 @@ ca_const_string_sort_perm (ca_const_string_scan_t *s)
   }
   idx = ALLOC_N(ca_size_t, s->n);
   for ( i = 0; i < s->n; i++ ) idx[i] = i;
-  ca_const_string_sort_ctx = s;
-  qsort(idx, (size_t) s->n, sizeof(ca_size_t), ca_const_string_byte_cmp);
-  ca_const_string_sort_ctx = NULL;
+  ruby_qsort(idx, (size_t) s->n, sizeof(ca_size_t), ca_const_string_byte_cmp, s);
+  /* qsort is not stable.  Equal strings keep their order, as CArray's own
+     sort does, so each run of them is put back in position order.  Breaking
+     the tie inside the comparator instead doubles the sort on columns with
+     many repeats. */
+  for ( i = 0; i < s->n; ) {
+    ca_size_t j = i + 1;
+    while ( j < s->n && ca_const_string_byte_cmp(&idx[i], &idx[j], s) == 0 ) j++;
+    if ( j - i > 1 ) {
+      qsort(idx + i, (size_t) (j - i), sizeof(ca_size_t), ca_const_string_index_cmp);
+    }
+    i = j;
+  }
   return idx;
 }
 
@@ -1005,6 +1032,128 @@ ca_const_string_extremum (VALUE self, int want_max)
 static VALUE rb_ca_const_string_min (VALUE self) { return ca_const_string_extremum(self, 0); }
 static VALUE rb_ca_const_string_max (VALUE self) { return ca_const_string_extremum(self, 1); }
 
+/* ------------------------------------------------------------------- */
+/* Native factorize: categorize's discovery pass, read from the bytes.  The
+   storage cells are byte ranges, so the fixlen lane of
+   CArray#__factorize_appearance__ would tell ranges apart, not strings.  A
+   String is made per distinct value only, after the scan's window closes. */
+
+static uint64_t
+ca_const_string_hash_bytes (const char *p, int64_t len)
+{
+  uint64_t h = 1469598103934665603ULL;            /* FNV-1a */
+  int64_t i;
+  for ( i = 0; i < len; i++ ) {
+    h ^= (unsigned char) p[i];
+    h *= 1099511628211ULL;
+  }
+  return h;
+}
+
+/* CAConstString#__factorize_appearance__ -> [codes, levels], as the CArray
+   method answers: codes are the narrowest unsigned type holding the k codes
+   and the type-max sentinel, which masked cells store; levels are the k
+   distinct Strings in first-appearance order. */
+static VALUE
+rb_ca_const_string_factorize_appearance (VALUE self)
+{
+  ca_const_string_scan_t s;
+  CAConstString *ca;
+  volatile VALUE vcodes, levels;
+  CArray *co;
+  uint32_t *codes, *slot;
+  int64_t *lev_start, *lev_len;
+  size_t cap = 16, mask_bits;
+  ca_size_t n, i, k = 0;
+  int8_t code_dt;
+  VALUE  slot_holder = 0, start_holder = 0, len_holder = 0;
+
+  TypedData_Get_Struct(self, CAConstString, &catext_data_type, ca);
+  n = ca->elements;
+  if ( (uint64_t) n >= 0xFFFFFFFFULL ) {
+    rb_raise(rb_eArgError, "categorize: too many elements for uint32 codes");
+  }
+  while ( cap < (size_t) n * 2 ) {
+    cap <<= 1;
+  }
+  mask_bits = cap - 1;
+  /* Everything the scan writes is allocated before its window opens, and
+     held by the collector: opening the window reads the offsets, which
+     can raise for a parent that answers in Ruby. */
+  vcodes    = rb_carray_new(CA_UINT32, ca->ndim, ca->dim, 0, NULL);
+  TypedData_Get_Struct(vcodes, CArray, &carray_data_type, co);
+  codes     = (uint32_t *) co->ptr;
+  slot      = ALLOCV_N(uint32_t, slot_holder, cap);  /* code + 1; 0 is empty */
+  MEMZERO(slot, uint32_t, cap);
+  lev_start = ALLOCV_N(int64_t, start_holder, n > 0 ? n : 1);
+  lev_len   = ALLOCV_N(int64_t, len_holder, n > 0 ? n : 1);
+
+  ca_const_string_scan_begin(self, &s);
+  for ( i = 0; i < s.n; i++ ) {
+    const char *p;
+    int64_t len;
+    size_t j;
+    if ( ! ca_const_string_record(&s, i, &p, &len) ) {
+      codes[i] = 0xFFFFFFFFu;
+      continue;
+    }
+    j = (size_t) ca_const_string_hash_bytes(p, len) & mask_bits;
+    for (;;) {
+      uint32_t c = slot[j];
+      if ( c == 0 ) {
+        lev_start[k] = (int64_t) (p - s.buf);
+        lev_len[k]   = len;
+        slot[j]      = (uint32_t) (k + 1);
+        codes[i]     = (uint32_t) k;
+        k++;
+        break;
+      }
+      if ( lev_len[c - 1] == len && memcmp(s.buf + lev_start[c - 1], p, (size_t) len) == 0 ) {
+        codes[i] = c - 1;
+        break;
+      }
+      j = (j + 1) & mask_bits;
+    }
+  }
+  ca_const_string_scan_end(&s);
+  ALLOCV_END(slot_holder);
+
+  /* The buffer is the column's frozen String, alive past the window. */
+  levels = rb_ary_new_capa(k);
+  {
+    const char *buf = RSTRING_PTR(ca->buffer);
+    rb_encoding *enc = rb_enc_from_index(ca->encoding_id);
+    for ( i = 0; i < k; i++ ) {
+      rb_ary_push(levels, rb_enc_str_new(buf + lev_start[i], lev_len[i], enc));
+    }
+  }
+  ALLOCV_END(start_holder);
+  ALLOCV_END(len_holder);
+
+  if      ( k <= 0xFF )   { code_dt = CA_UINT8;  }
+  else if ( k <= 0xFFFF ) { code_dt = CA_UINT16; }
+  else                    { code_dt = CA_UINT32; }
+  if ( code_dt != CA_UINT32 ) {
+    VALUE vnarrow = rb_carray_new(code_dt, ca->ndim, ca->dim, 0, NULL);
+    CArray *cn;
+    TypedData_Get_Struct(vnarrow, CArray, &carray_data_type, cn);
+    if ( code_dt == CA_UINT8 ) {
+      uint8_t *cp = (uint8_t *) cn->ptr;
+      for ( i = 0; i < n; i++ ) {
+        cp[i] = codes[i] == 0xFFFFFFFFu ? (uint8_t) 0xFF : (uint8_t) codes[i];
+      }
+    }
+    else {
+      uint16_t *cp = (uint16_t *) cn->ptr;
+      for ( i = 0; i < n; i++ ) {
+        cp[i] = codes[i] == 0xFFFFFFFFu ? (uint16_t) 0xFFFF : (uint16_t) codes[i];
+      }
+    }
+    vcodes = vnarrow;
+  }
+  return rb_ary_new3(2, vcodes, levels);
+}
+
 /* ------------------------------------------------------------------- */
 
 static VALUE
@@ -1028,6 +1177,7 @@ rb_ca_const_string_initialize_copy (VALUE self, VALUE other)
     ca_array_pool_alloc(ca, CA_OBJ_CONST_STRING, cs->parent->ndim);
   }
   ca_const_string_setup(ca, cs->parent, cs->buffer, cs->encoding_id);
+  ca_view_inherit_mask((VALUE) ca);
   return self;
 }
 
@@ -1080,10 +1230,14 @@ Init_ca_obj_const_string (void)
   /* 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);
+  rb_define_private_method(rb_cCAConstString, "sort_addr_by_bytes",
+                           rb_ca_const_string_sort_index, 0);
+  rb_define_private_method(rb_cCAConstString, "min_string_by_bytes",
+                           rb_ca_const_string_min, 0);
+  rb_define_private_method(rb_cCAConstString, "__factorize_appearance__",
+                           rb_ca_const_string_factorize_appearance, 0);
+  rb_define_private_method(rb_cCAConstString, "max_string_by_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_element(CA_OBJ_CONST_STRING, rb_ca_const_string_storage_to_element);