carray 3.0.2 → 3.0.4

data/ext/ca_obj_face.c

@@ -19,16 +19,18 @@
     ca_face_lift           re-wrap a view as a Face when the source was
     ca_strip_face          walk down through Face parents to storage
     CAFace abstract class  organisational relay in the class hierarchy
-    storage_to_scalar /    per-obj_type dispatch for element decode (read)
-      scalar_to_storage    and encode (write) between surface and storage
+    storage_to_element /    per-obj_type dispatch for element decode (read)
+      element_to_storage    and encode (write) between surface and storage
     state-compatible /     homogeneity + portability registries used by
-      state-portable       promote_list / CAStack / MV producer
+      state-portable       promote_list / CAStack
+    memory_view            which Faces the MemoryView producer exports
 
 ---------------------------------------------------------------------------- */
 
 #include "ruby.h"
 #include "carray.h"
 #include "ca_obj_face.h"
+#include "carray_internal.h"
 
 /* ---- shared op helpers (thin-forward) ---- */
 
@@ -37,7 +39,7 @@ ca_face_attach (void *ap)
 {
   CAView *cav = (CAView *) ap;
   CArray    *ca  = (CArray *) ap;
-  ca_attach(cav->parent);
+  ca_attach(cav->parent);   /* window: a Face's attach slot; its detach slot releases */
   /* alias parent->ptr (Face has identical data layout, so copy is unneeded) */
   ca->ptr = cav->parent->ptr;
 }
@@ -100,6 +102,7 @@ void
 ca_face_xfer_stride (void *ap, ca_size_t *starts, ca_size_t *counts,
                             ca_size_t *strides, void *data, int dir)
 {
+  if ( ca_region_is_empty(((CArray *) ap)->ndim, counts) ) return;
   CAView *cav = (CAView *) ap;
   ca_xfer_stride(cav->parent, starts, counts, strides, data, dir);
 }
@@ -129,10 +132,18 @@ rb_ca_face_template (VALUE original_face, CArray *new_parent,
   TypedData_Get_Struct(original_face, CArray, &carray_data_type, src);
   tdata = ca_typeddata[src->obj_type];
 
-  /* Actual subclass size (incl. tail) — via TypedData's dsize callback */
-  size = (tdata && tdata->function.dsize)
-            ? tdata->function.dsize(src)
-            : sizeof(CAView);
+  /* The struct with its subclass tail.  struct_size is the struct alone;
+     a dsize callback also counts the buffers the struct points to (dim),
+     so it is only the fallback for a type registered without struct_size,
+     and copying that many bytes reads past the struct. */
+  if ( ca_func[src->obj_type].struct_size ) {
+    size = ca_func[src->obj_type].struct_size;
+  }
+  else {
+    size = (tdata && tdata->function.dsize)
+              ? tdata->function.dsize(src)
+              : sizeof(CAView);
+  }
 
   dst = (CArray *) xmalloc(size);
   /* CAREFUL: the whole-struct memcpy is how a C-tail Face
@@ -174,6 +185,44 @@ rb_ca_face_template (VALUE original_face, CArray *new_parent,
                                 dst);
 }
 
+VALUE
+ca_face_relift_entity (VALUE face, VALUE result)
+{
+  static ID id_copy_state = 0;
+  CArray *rc, *lc;
+  VALUE lifted;
+  if ( id_copy_state == 0 ) id_copy_state = rb_intern("copy_state");
+  TypedData_Get_Struct(result, CArray, &carray_data_type, rc);
+  lifted = rb_ca_face_template(face, rc, rc->dim);
+  rb_ca_set_parent(lifted, result);
+  if ( ca_has_mask(rc) ) {
+    /* The template starts without a mask. */
+    TypedData_Get_Struct(lifted, CArray, &carray_data_type, lc);
+    ca_copy_mask(lc, rc);
+  }
+  if ( rb_respond_to(face, id_copy_state) ) {
+    rb_funcall(lifted, id_copy_state, 1, face);
+  }
+  return lifted;
+}
+
+/* A lift moves a view built on a wrapper (a Face or the lazy marker) one
+ * level down, onto what the wrapper wraps, so the view no longer keeps the
+ * wrapper alive.  The view's mask was built over the wrapper's mask, which
+ * the wrapper owns and frees with itself; move it down the same level.
+ * The wrapper's mask is a same-shape refer of its parent's mask, so the
+ * mask view addresses the same cells there. */
+static void
+ca_lift_move_mask_down (CArray *view_ca, CArray *wp)
+{
+  CArray *below = ((CAView *) wp)->parent;
+  if ( view_ca->mask && wp->mask && ca_is_view(wp->mask)
+       && ((CAView *) wp->mask)->parent == below->mask
+       && ((CAView *) view_ca->mask)->parent == wp->mask ) {
+    ((CAView *) view_ca->mask)->parent = below->mask;
+  }
+}
+
 /* ca_face_lift(view, face_parent) — at the tail of user-facing entry
  * points (`ca[...]` etc.), when the operand was a Face, re-wrap the
  * resulting view as a Face of the same subclass.  Thin wrapper over
@@ -236,6 +285,7 @@ ca_face_lift (VALUE view, VALUE face_parent)
          && ! ca_test_flag(view_ca, CA_FLAG_MULTI_PARENTS) ) {
       ((CAView *) view_ca)->parent = ((CAView *) fp)->parent;   /* C pointer: one level */
       rb_ca_set_parent(view, rb_ca_parent(face_parent));        /* @parent ivar: lockstep */
+      ca_lift_move_mask_down(view_ca, fp);
     }
   }
 
@@ -245,6 +295,12 @@ ca_face_lift (VALUE view, VALUE face_parent)
   lifted = rb_ca_face_template(face_parent, view_ca, view_ca->dim);
   /* Pin view as a GC root of lifted so the slice is not collected. */
   rb_ca_set_parent(lifted, view);
+  /* The Face the view was taken from is off the parent chain now; keep it
+     for the attributes set on it.  A fresh result the ordering kernels
+     re-wrap is not a view of it and takes none. */
+  if ( ca_is_view(view_ca) ) {
+    rb_ca_set_lifted_from(lifted, face_parent);
+  }
 
   /* Optional Ruby callback for ivar / state carry.  Faces holding
      semantic state in the struct tail (CATime / CATimedelta
@@ -322,6 +378,7 @@ ca_lazy_marker_lift (VALUE view, VALUE marker)
        && ! ca_test_flag(view_ca, CA_FLAG_MULTI_PARENTS) ) {
     ((CAView *) view_ca)->parent = ((CAView *) mp)->parent;  /* C pointer */
     rb_ca_set_parent(view, rb_ca_parent(marker));            /* @parent ivar */
+    ca_lift_move_mask_down(view_ca, mp);
   }
 
   return rb_ca_lazy_marker_new(view);
@@ -419,37 +476,62 @@ rb_ca_face_s_allocate_forbidden (VALUE klass)
            "(CATime / CATimedelta / ...)");
 }
 
-/* Face-local C dispatch table for storage_to_scalar (the read/decode
+VALUE
+ca_face_storage_value (CArray *ca, VALUE raw)
+{
+  CArray *storage;
+  CArray  as_storage;
+  if ( ca->data_type != CA_FIXLEN || TYPE(raw) != T_STRING ) {
+    return raw;
+  }
+  storage = ca_strip_face(ca);
+  if ( storage == NULL
+       || storage->data_type == CA_FIXLEN
+       || ca_is_object_type(storage)
+       || RSTRING_LEN(raw) != storage->bytes ) {
+    return raw;
+  }
+  if ( storage->data_type == CA_BOOLEAN ) {
+    return *(uint8_t *) RSTRING_PTR(raw) ? Qtrue : Qfalse;
+  }
+  /* The cell lives in a String's buffer, not in the storage: read it
+     through a stand-in that carries only the storage's type. */
+  as_storage.data_type = storage->data_type;
+  as_storage.bytes     = storage->bytes;
+  return ca_ptr2obj(&as_storage, RSTRING_PTR(raw));
+}
+
+/* Face-local C dispatch table for storage_to_element (the read/decode
    direction).  Sized to CA_OBJ_TYPE_MAX so any registered obj_type can be
    indexed directly; file-scope zero-init leaves unregistered slots NULL. */
-ca_face_storage_to_scalar_fn ca_face_storage_to_scalar_table[CA_OBJ_TYPE_MAX];
+ca_face_storage_to_element_fn ca_face_storage_to_element_table[CA_OBJ_TYPE_MAX];
 
 void
-ca_face_register_storage_to_scalar (int obj_type, ca_face_storage_to_scalar_fn fn)
+ca_face_register_storage_to_element (int obj_type, ca_face_storage_to_element_fn fn)
 {
   if ( obj_type < 0 || obj_type >= CA_OBJ_TYPE_MAX ) {
     rb_raise(rb_eArgError,
-             "ca_face_register_storage_to_scalar: obj_type %d out of range",
+             "ca_face_register_storage_to_element: obj_type %d out of range",
              obj_type);
   }
-  ca_face_storage_to_scalar_table[obj_type] = fn;
+  ca_face_storage_to_element_table[obj_type] = fn;
 }
 
-/* Face-local C dispatch table for scalar_to_storage (the write/encode
+/* Face-local C dispatch table for element_to_storage (the write/encode
    direction), the mirror of the decode table above.  Unregistered slots
    stay NULL; a Face without a C fast path relies on the Ruby fallback in
-   ca_face_scalar_to_storage (carray_cast.c). */
-ca_face_scalar_to_storage_fn ca_face_scalar_to_storage_table[CA_OBJ_TYPE_MAX];
+   ca_face_element_to_storage (carray_cast.c). */
+ca_face_element_to_storage_fn ca_face_element_to_storage_table[CA_OBJ_TYPE_MAX];
 
 void
-ca_face_register_scalar_to_storage (int obj_type, ca_face_scalar_to_storage_fn fn)
+ca_face_register_element_to_storage (int obj_type, ca_face_element_to_storage_fn fn)
 {
   if ( obj_type < 0 || obj_type >= CA_OBJ_TYPE_MAX ) {
     rb_raise(rb_eArgError,
-             "ca_face_register_scalar_to_storage: obj_type %d out of range",
+             "ca_face_register_element_to_storage: obj_type %d out of range",
              obj_type);
   }
-  ca_face_scalar_to_storage_table[obj_type] = fn;
+  ca_face_element_to_storage_table[obj_type] = fn;
 }
 
 /* -- Face state homogeneity check -- */
@@ -473,15 +555,10 @@ ca_face_register_state_compatible (int obj_type, ca_face_state_compatible_fn fn)
 static int
 ca_face_has_ruby_state_check (VALUE va)
 {
-  static ID id_face_state_compatible_p = 0;
-  static ID id_method = 0;
-  static ID id_owner  = 0;
+  ID id_face_state_compatible_p = rb_intern("face_state_compatible?");
+  ID id_method                  = rb_intern("method");
+  ID id_owner                   = rb_intern("owner");
   VALUE m, owner;
-  if ( id_face_state_compatible_p == 0 ) {
-    id_face_state_compatible_p = rb_intern("face_state_compatible?");
-    id_method                  = rb_intern("method");
-    id_owner                   = rb_intern("owner");
-  }
   m = rb_funcall(va, id_method, 1, ID2SYM(id_face_state_compatible_p));
   owner = rb_funcall(m, id_owner, 0);
   return ( owner != rb_cCArray ) ? 1 : 0;
@@ -524,6 +601,31 @@ rb_ca_face_state_compatible_p (VALUE self, VALUE other)
   return ca_face_state_compatible(self, a, other, b) ? Qtrue : Qfalse;
 }
 
+/* -- Face MemoryView export -- */
+
+/* A Face is exported through MemoryView only when its storage bytes carry
+   its values without the Face (a struct record, fixed-width bytes).  Zero
+   (the default) refuses the export: the consumer would see the storage
+   with nothing to say what it means. */
+static int8_t ca_face_memory_view_table[CA_OBJ_TYPE_MAX];
+
+void
+ca_face_register_memory_view (int obj_type, int exportable)
+{
+  if ( obj_type < 0 || obj_type >= CA_OBJ_TYPE_MAX ) {
+    rb_raise(rb_eArgError,
+             "ca_face_register_memory_view: obj_type %d out of range",
+             obj_type);
+  }
+  ca_face_memory_view_table[obj_type] = exportable ? 1 : 0;
+}
+
+int
+ca_face_memory_view_exportable (CArray *ca)
+{
+  return ca_face_memory_view_table[ca->obj_type] == 1;
+}
+
 /* -- Face state portability -- */
 
 /* int8_t per slot to distinguish "unregistered" (-1, dispatch falls
@@ -576,16 +678,11 @@ ca_face_register_state_portable (int obj_type, int portable)
 static int
 ca_face_class_has_portable_method (VALUE klass)
 {
-  static ID id_face_state_portable_p = 0;
-  static ID id_method = 0;
-  static ID id_owner  = 0;
+  ID id_face_state_portable_p = rb_intern("face_state_portable?");
+  ID id_method                = rb_intern("method");
+  ID id_owner                 = rb_intern("owner");
   VALUE m, owner;
   if ( NIL_P(klass) ) return 0;
-  if ( id_face_state_portable_p == 0 ) {
-    id_face_state_portable_p = rb_intern("face_state_portable?");
-    id_method                = rb_intern("method");
-    id_owner                 = rb_intern("owner");
-  }
   if ( !rb_respond_to(klass, id_face_state_portable_p) ) return 0;
   m = rb_funcall(klass, id_method, 1, ID2SYM(id_face_state_portable_p));
   owner = rb_funcall(m, id_owner, 0);
@@ -595,6 +692,132 @@ ca_face_class_has_portable_method (VALUE klass)
   return ( owner != rb_singleton_class(rb_cCArray) ) ? 1 : 0;
 }
 
+/* The conversion a refusal of a Face whose cells encode its values points
+   at: a string Face gives its strings with #to_string, any other its values
+   with to_type(:object). */
+const char *
+ca_face_conversion_hint (VALUE face)
+{
+  return rb_respond_to(face, rb_intern("to_string"))
+    ? "#to_string gives its strings"
+    : "to_type(:object) gives its values";
+}
+
+/* The method that gives the storage under a Face, for a refusal to point
+   at: #ticks for a time or a duration, #codes for a categorical.  NULL for
+   a Face that names its storage some other way, or not at all. */
+const char *
+ca_face_storage_method (VALUE face)
+{
+  static const char *names[] = { "ticks", "codes" };
+  size_t i;
+  for (i = 0; i < sizeof(names) / sizeof(names[0]); i++) {
+    if ( rb_respond_to(face, rb_intern(names[i])) ) {
+      return names[i];
+    }
+  }
+  return NULL;
+}
+
+/* ca.face_storage_method -- the name of the method that gives the storage
+   under ca (ca_face_storage_method), as a String, or nil.  For refusals
+   written in Ruby. */
+static VALUE
+rb_ca_face_storage_method (VALUE self)
+{
+  const char *name = ca_face_storage_method(self);
+  return name ? rb_str_new_cstr(name) : Qnil;
+}
+
+/* Refuse to order (or, with verb "count", to count by value) a Face whose
+   storage does not hold its values in order, pointing at what does: its
+   values, or its storage when that is what is meant. */
+void
+ca_face_refuse_order (const char *name, VALUE face, const char *verb)
+{
+  const char *storage = ca_face_storage_method(face);
+  if ( storage ) {
+    rb_raise(rb_eArgError,
+             "%s: %s is not orderable by storage (a cell encodes the value "
+             "rather than being it); %s its values instead -- %s -- or %s "
+             "its storage, which #%s gives",
+             name, rb_obj_classname(face), verb,
+             ca_face_conversion_hint(face), verb, storage);
+  }
+  rb_raise(rb_eArgError,
+           "%s: %s is not orderable by storage (a cell encodes the value "
+           "rather than being it); %s its values instead -- %s",
+           name, rb_obj_classname(face), verb,
+           ca_face_conversion_hint(face));
+}
+
+/* The rule every family that orders, compares, searches or hashes the cells
+   of a Face reference keeps: the storage stands for the values only when the
+   Face declares ORDERABLE_STORAGE.  A fixlen storage is no exception -- its
+   bytes are an order only when the Face says so (CAFixlenString).  Returns
+   when the Face is ORDERABLE; refuses otherwise (ca_face_refuse_order).  A
+   family that can order by a key asks ca_face_orders_by_itself first. */
+void
+ca_face_require_orderable (VALUE face, const char *name, const char *verb)
+{
+  CArray *ca;
+  TypedData_Get_Struct(face, CArray, &carray_data_type, ca);
+  if ( ! ca_test_flag(ca, CA_FLAG_FACE_ORDERABLE_STORAGE) ) {
+    ca_face_refuse_order(name, face, verb);
+  }
+}
+
+/* Whether a Face is ordered by its own #order rather than by its storage:
+   it is not ORDERABLE and answers #order itself (CAConstString, CARecord),
+   so a family that orders by a key can take that order.  CArray#order is
+   not one: it sorts the storage and comes back to the gate. */
+int
+ca_face_orders_by_itself (VALUE face)
+{
+  ID id_order  = rb_intern("order");
+  ID id_method = rb_intern("method");
+  ID id_owner  = rb_intern("owner");
+  CArray *ca;
+  VALUE m;
+  TypedData_Get_Struct(face, CArray, &carray_data_type, ca);
+  if ( ca_test_flag(ca, CA_FLAG_FACE_ORDERABLE_STORAGE) ) {
+    return 0;
+  }
+  m = rb_funcall(face, id_method, 1, ID2SYM(id_order));
+  return ( rb_funcall(m, id_owner, 0) != rb_cCArray ) ? 1 : 0;
+}
+
+/* Refuse a numeric operation (arithmetic, math, a reduction) on a Face,
+   whose cells encode its values rather than being numbers, pointing at what
+   gives numbers.  Returns when `self` is not a Face. */
+void
+ca_face_refuse_numeric (VALUE self, const char *name, VALUE eclass)
+{
+  CArray *ca;
+  if ( ! rb_obj_is_carray(self) ) {
+    return;
+  }
+  GetCArray(self, ca);
+  if ( ! ca_is_face(ca) ) {
+    return;
+  }
+  {
+    const char *storage = ca_face_storage_method(self);
+    if ( storage ) {
+      rb_raise(eclass,
+               "%s: %s does not define it (a cell encodes the value rather "
+               "than being a number); compute on its values instead -- %s -- "
+               "or on its storage, which #%s gives",
+               name, rb_obj_classname(self), ca_face_conversion_hint(self),
+               storage);
+    }
+  }
+  rb_raise(eclass,
+           "%s: %s does not define it (a cell encodes the value rather than "
+           "being a number); compute on its values instead -- %s",
+           name, rb_obj_classname(self), ca_face_conversion_hint(self));
+}
+
 VALUE
 ca_face_operand_descend (VALUE operand, const char *name)
 {
@@ -609,16 +832,203 @@ ca_face_operand_descend (VALUE operand, const char *name)
   if ( ca_test_flag(op, CA_FLAG_FACE_COMPARABLE_STORAGE) ) {
     return rb_ca_strip_face_value(operand);
   }
+  {
+    const char *storage = ca_face_storage_method(operand);
+    if ( storage ) {
+      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 -- %s -- or compare the storage "
+               "of both sides, which #%s gives",
+               name, rb_obj_classname(operand),
+               ca_face_conversion_hint(operand), storage);
+    }
+  }
   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));
+           "the receiver's space first -- %s",
+           name, rb_obj_classname(operand), ca_face_conversion_hint(operand));
+  return Qnil;   /* not reached */
+}
+
+/* Whether two arrays, at least one a Face other than a record array, are
+   equal (`==`, strict = 0) or the same key (`eql?`, strict = 1).
+
+   A Face equals only a Face of its own class.  When the two share their
+   state (a time array's unit) and the storage holds the values in their
+   order, equal storage is equal values, so the storage is compared.
+   Otherwise `==` compares the values themselves (two time arrays of
+   different units, two const strings over different pools, two
+   categoricals with differently ordered labels), and `eql?`, which has to
+   agree with #hash, answers false. */
+int
+ca_face_equal (VALUE va, VALUE vb, int strict)
+{
+  CArray *a, *b;
+  int8_t i;
+  TypedData_Get_Struct(va, CArray, &carray_data_type, a);
+  TypedData_Get_Struct(vb, CArray, &carray_data_type, b);
+  if ( ! ca_is_face(a) || ! ca_is_face(b) ) {
+    return 0;
+  }
+  if ( rb_obj_class(va) != rb_obj_class(vb) ) {
+    return 0;
+  }
+  if ( a->ndim != b->ndim ) {
+    return 0;
+  }
+  for (i = 0; i < a->ndim; i++) {
+    if ( a->dim[i] != b->dim[i] ) {
+      return 0;
+    }
+  }
+  if ( ca_face_state_compatible(va, a, vb, b)
+       && ( strict || ca_test_flag(a, CA_FLAG_FACE_ORDERABLE_STORAGE) ) ) {
+    return strict ? ca_eql_storage(ca_strip_face(a), ca_strip_face(b))
+                  : ca_equal(ca_strip_face(a), ca_strip_face(b));
+  }
+  if ( strict ) {
+    return 0;
+  }
+  return RTEST(rb_equal(rb_funcall(va, rb_intern("to_a"), 0),
+                        rb_funcall(vb, rb_intern("to_a"), 0)));
+}
+
+/* An operand Face whose storage is not even in the order of its values
+   (a CAConstString, a CACategorical) is read by its values: its strings
+   (#to_string) or, for any other, its values (to_type(:object)).  Any
+   other operand is returned as it is. */
+static VALUE
+ca_face_operand_values (VALUE operand)
+{
+  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) || op->obj_type == CA_OBJ_RECORD
+       || ca_test_flag(op, CA_FLAG_FACE_ORDERABLE_STORAGE) ) {
+    return operand;
+  }
+  if ( rb_respond_to(operand, rb_intern("to_string")) ) {
+    return rb_funcall(operand, rb_intern("to_string"), 0);
+  }
+  return rb_funcall(operand, rb_intern("to_type"), 1, INT2NUM(CA_OBJECT));
+}
+
+/* Bring `operand` into the storage space of `reference`, a Face, so the
+   two can be compared, searched, counted or hashed cell by cell.  Every
+   family that takes an operand against a Face goes through here; the
+   family keeps its own gate on the reference (ORDERABLE, a record's own
+   rules) and its own handling of a scalar operand afterwards.
+
+   - A record reference takes records of its own data_class (stripped to
+     their bytes) and plain operands as they are; any other Face operand is
+     refused with TypeError.
+   - A COMPARABLE reference stores its values as they are, so a plain
+     operand is taken as it is, a Face whose cells are its values is
+     stripped, a string or categorical Face is read by its values, and a
+     Face whose cells encode its values in order (a time) is refused
+     (ca_face_operand_descend).
+   - A reference whose storage is not in the order of its values refuses,
+     naming the conversion that gives its values.
+   - A reference with to_comparable brings any operand into its own space
+     (a unit, an instant), and refuses what it cannot convert.
+   - Any other reference has no way to read the operand in its space, and
+     refuses it.
+   UNDEF is undefined in every space, so it passes as it is and the entry
+   answers it as it does for a plain array. */
+VALUE
+ca_face_reconcile_operand (VALUE reference, VALUE operand, const char *name)
+{
+  CArray *ca;
+  if ( operand == CA_UNDEF ) {
+    return operand;
+  }
+  TypedData_Get_Struct(reference, CArray, &carray_data_type, ca);
+  if ( ca->obj_type == CA_OBJ_RECORD ) {
+    if ( RTEST(rb_obj_is_carray(operand)) ) {
+      CArray *op;
+      TypedData_Get_Struct(operand, CArray, &carray_data_type, op);
+      if ( ca_is_face(op) ) {
+        if ( op->obj_type != CA_OBJ_RECORD ) {
+          rb_raise(rb_eTypeError,
+                   "%s: can not take a %s operand for a record array of "
+                   "%"PRIsVALUE, name, rb_obj_classname(operand),
+                   rb_ca_data_class(reference));
+        }
+        if ( rb_ca_data_class(operand) != rb_ca_data_class(reference) ) {
+          rb_raise(rb_eTypeError,
+                   "%s: can not take a record array of %"PRIsVALUE
+                   " for a record array of %"PRIsVALUE, name,
+                   rb_ca_data_class(operand), rb_ca_data_class(reference));
+        }
+        return rb_ca_strip_face_value(operand);
+      }
+    }
+    return operand;
+  }
+  if ( ca_test_flag(ca, CA_FLAG_FACE_COMPARABLE_STORAGE) ) {
+    return ca_face_operand_descend(ca_face_operand_values(operand), name);
+  }
+  ca_face_require_orderable(reference, name, "compare");
+  if ( rb_respond_to(reference, rb_intern("to_comparable")) ) {
+    return rb_ca_strip_face_value(rb_funcall(reference,
+                                             rb_intern("to_comparable"),
+                                             1, operand));
+  }
+  {
+    const char *storage = ca_face_storage_method(reference);
+    if ( storage ) {
+      rb_raise(rb_eArgError,
+               "%s: %s is not comparable by storage and has no to_comparable "
+               "to bring the operand into its space; compare the storage of "
+               "both sides, which #%s gives",
+               name, rb_obj_classname(reference), storage);
+    }
+  }
+  rb_raise(rb_eArgError,
+           "%s: %s is not comparable by storage and has no to_comparable "
+           "to bring the operand into its space",
+           name, rb_obj_classname(reference));
   return Qnil;   /* not reached */
 }
 
+/* The reference and the operand of a comparison (an operator, count(v), a
+   search, linear_section) brought into one space.  A time reference answers
+   both through comparable_pair: it keeps itself when the operand sits on its
+   grid, and otherwise meets the operand in the finer unit the two share,
+   where to_comparable would refuse a value off its grid.  Every other
+   reference keeps itself and reconciles the operand
+   (ca_face_reconcile_operand).  An assignment, which has to land on the
+   reference's grid, uses ca_face_reconcile_operand. */
+void
+ca_face_reconcile_pair (volatile VALUE *pref, volatile VALUE *poperand,
+                        const char *name)
+{
+  static ID id_comparable_pair = 0;
+  VALUE ref = *pref, operand = *poperand;
+  CArray *ca;
+  if ( id_comparable_pair == 0 ) {
+    id_comparable_pair = rb_intern("comparable_pair");
+  }
+  TypedData_Get_Struct(ref, CArray, &carray_data_type, ca);
+  if ( operand != CA_UNDEF
+       && ca->obj_type != CA_OBJ_RECORD
+       && ! ca_test_flag(ca, CA_FLAG_FACE_COMPARABLE_STORAGE)
+       && ca_test_flag(ca, CA_FLAG_FACE_ORDERABLE_STORAGE)
+       && rb_respond_to(ref, id_comparable_pair) ) {
+    VALUE pair = rb_funcall(ref, id_comparable_pair, 1, operand);
+    *pref     = rb_ary_entry(pair, 0);
+    *poperand = rb_ca_strip_face_value(rb_ary_entry(pair, 1));
+    return;
+  }
+  *poperand = ca_face_reconcile_operand(ref, operand, name);
+}
+
 int
 ca_face_state_portable (int obj_type, VALUE klass)
 {
@@ -635,6 +1045,84 @@ ca_face_state_portable (int obj_type, VALUE klass)
   return 1;   /* default portable */
 }
 
+VALUE
+ca_face_list_class (VALUE list, const char *who)
+{
+  long n = RARRAY_LEN(list), i;
+  int any_face = 0, all_face = 1;
+  VALUE face_class = Qnil, face = Qnil;
+  CArray *ref = NULL;
+
+  for ( i = 0; i < n; i++ ) {
+    VALUE p = rb_ary_entry(list, i);
+    CArray *ca;
+    rb_check_carray_object(p);
+    TypedData_Get_Struct(p, CArray, &carray_data_type, ca);
+    if ( ! ca_is_face(ca) ) { all_face = 0; continue; }
+    any_face = 1;
+    if ( NIL_P(face_class) ) {
+      face_class = rb_obj_class(p);
+      face = p;
+      ref = ca;
+    }
+    else if ( rb_obj_class(p) != face_class ) {
+      all_face = 0;
+    }
+  }
+  if ( ! any_face ) return Qnil;
+  if ( ! all_face ) {
+    const char *storage = ca_face_storage_method(face);
+    if ( ref->obj_type == CA_OBJ_STRING ) {
+      rb_raise(rb_eArgError,
+               "%s: cannot mix Face and non-Face arrays, or arrays of "
+               "different Face classes; convert them first to one Face "
+               "class or to no Face (CArray.string(a) makes a CAString of "
+               "an object array of Strings)",
+               who);
+    }
+    if ( storage ) {
+      rb_raise(rb_eArgError,
+               "%s: cannot mix Face and non-Face arrays, or arrays of "
+               "different Face classes; convert them first to one Face "
+               "class or to no Face, or combine their storage (#%s gives "
+               "the storage of a %s)",
+               who, storage, rb_obj_classname(face));
+    }
+    rb_raise(rb_eArgError,
+             "%s: cannot mix Face and non-Face arrays, or arrays of "
+             "different Face classes; convert them first to one Face "
+             "class or to no Face",
+             who);
+  }
+  if ( n > 1 && ! ca_face_state_portable(ref->obj_type, face_class) ) {
+    rb_raise(rb_eArgError,
+             "%s: %s state is not portable across several arrays (each "
+             "keeps its values in storage of its own); convert them first "
+             "(%s)",
+             who, rb_class2name(face_class),
+             ca_face_conversion_hint(face));
+  }
+  for ( i = 1; i < n; i++ ) {
+    VALUE p = rb_ary_entry(list, i);
+    CArray *ca;
+    TypedData_Get_Struct(p, CArray, &carray_data_type, ca);
+    if ( ! ca_face_state_compatible(rb_ary_entry(list, 0), ref, p, ca) ) {
+      rb_raise(rb_eArgError,
+               "%s: Face state mismatch (the %s at index %ld differs from "
+               "index 0)", who, rb_class2name(face_class), i);
+    }
+  }
+  return face_class;
+}
+
+VALUE
+ca_face_strip_one (VALUE v)
+{
+  CArray *c;
+  TypedData_Get_Struct(v, CArray, &carray_data_type, c);
+  return ca_is_face(c) ? rb_ca_parent(v) : v;
+}
+
 /* CArray.face_state_portable? — class method on CArray.  Subclasses
    (Face classes) override by defining their own `def self.face_state_portable?`.
    This default returns true (= 1) for non-Face CArray classes; the actual
@@ -645,6 +1133,57 @@ rb_ca_s_face_state_portable_p (VALUE klass)
   return Qtrue;
 }
 
+/* ca.orderable_storage? -- whether ca's storage holds its values, in
+   their order, so that a lookup may compare the storage: true for an array
+   that is not a Face and for a Face that declares
+   CA_FLAG_FACE_ORDERABLE_STORAGE, false for a Face whose cells encode the
+   value (a const string's ranges, a categorical's codes). */
+static VALUE
+rb_ca_orderable_storage_p (VALUE self)
+{
+  CArray *ca;
+  GetCArray(self, ca);
+  if ( ! ca_is_face(ca) ) return Qtrue;
+  return ca_test_flag(ca, CA_FLAG_FACE_ORDERABLE_STORAGE) ? Qtrue : Qfalse;
+}
+
+/* ca.comparable_storage? -- whether ca's storage holds its values as
+   they are, so that a plain operand may be compared with the storage: true
+   for an array that is not a Face and for a Face that declares
+   CA_FLAG_FACE_COMPARABLE_STORAGE. */
+static VALUE
+rb_ca_comparable_storage_p (VALUE self)
+{
+  CArray *ca;
+  GetCArray(self, ca);
+  if ( ! ca_is_face(ca) ) return Qtrue;
+  return ca_test_flag(ca, CA_FLAG_FACE_COMPARABLE_STORAGE) ? Qtrue : Qfalse;
+}
+
+/* ca.face_storage -- the storage under a Face (ca itself when it is not
+   a Face). */
+static VALUE
+rb_ca_face_storage (VALUE self)
+{
+  return rb_ca_strip_face_value(self);
+}
+
+/* ca.reconcile_operand(operand, name) -- operand brought into ca's
+   storage space by the rule every operand family follows
+   (ca_face_reconcile_operand for a Face, ca_face_operand_descend for an
+   array that is not one).  For the families written in Ruby. */
+static VALUE
+rb_ca_reconcile_operand (VALUE self, VALUE operand, VALUE rname)
+{
+  CArray *ca;
+  const char *name = StringValueCStr(rname);
+  GetCArray(self, ca);
+  if ( ca_is_face(ca) ) {
+    return ca_face_reconcile_operand(self, operand, name);
+  }
+  return ca_face_operand_descend(operand, name);
+}
+
 /* CArray#face_lift(face_parent) — Ruby surface for ca_face_lift.
    Used by CArray.stack to re-wrap a raw CAStack with the homogeneous
    Face class carried by face_parent (typically list[0] after the
@@ -666,21 +1205,19 @@ rb_ca_face_lift_method (VALUE self, VALUE face_parent)
 
 /* ca_face_reconcile_comparison(pself, pother) — Face gate for the element-
  * wise comparison operators (< <= > >=, eq, ne; <=> composes from > and <).
- * Mirrors the search query gate (PROPOSAL_FACE_ORDERING_GATE): when the LHS
+ * Mirrors the search query gate (docs/authoring/FaceOrderingSearch.md): when the LHS
  * is a Face over NUMERIC storage, memcmp on the surface fixlen bytes would
  * mis-order the storage, so descend to storage (ORDERABLE licenses that the
  * numeric order equals the surface order) and reconcile the RHS:
  *
- *   - RHS is a Face: COMPARABLE self strips it; else it must respond to
- *     to_comparable (reconcile to self's reference, e.g. unit alignment,
- *     which may raise on loss); else raise.
- *   - RHS is plain (bare number / non-Face array / Scalar): a direct storage
- *     compare, which only a COMPARABLE self licenses -- a non-COMPARABLE
- *     Face (e.g. a unit-bearing CATime) rejects it.
+ *   the RHS goes through ca_face_reconcile_operand: a COMPARABLE self takes
+ *   a plain RHS or a COMPARABLE Face, a self with to_comparable brings any
+ *   RHS into its space, and anything else is refused.
  *
- * A Face over FIXLEN storage (CARecord / string faces) is left untouched:
+ * A Face over FIXLEN storage (CARecord / string faces) keeps its Face:
  * memcmp on its bytes is already the correct order/equality, same as a plain
- * fixlen array.  Both operands are rebound to storage via *pself / *pother.
+ * fixlen array; only the RHS is reconciled.  Both operands are rebound via
+ * *pself / *pother.
  * No-op when self is not a Face. */
 void
 ca_face_reconcile_comparison (volatile VALUE *pself, volatile VALUE *pother)
@@ -698,54 +1235,30 @@ ca_face_reconcile_comparison (volatile VALUE *pself, volatile VALUE *pother)
 
   storage = ca_strip_face(sc);
   if ( storage->data_type == CA_FIXLEN ) {
-    /* genuine fixlen semantics: memcmp is the correct comparison, leave
-       the Face(s) in place (same result as a plain fixlen array). */
+    /* genuine fixlen semantics: memcmp is the correct comparison, so self
+       keeps its Face (same result as a plain fixlen array) and only the
+       operand is brought to bytes of the same meaning. */
+    *pother = ca_face_reconcile_operand(self, other, "comparison");
     return;
   }
 
-  if ( ! ca_test_flag(sc, CA_FLAG_FACE_ORDERABLE_STORAGE) ) {
-    rb_raise(rb_eArgError,
-             "comparison: Face operand (%s) is not orderable by storage; "
-             "use ca.parent to descend to storage",
-             rb_obj_classname(self));
-  }
+  ca_face_require_orderable(self, "comparison", "compare");
 
   {
-    VALUE self_ref = self;   /* reference before stripping (for to_comparable) */
-    int   comparable = ca_test_flag(sc, CA_FLAG_FACE_COMPARABLE_STORAGE);
-    int   other_is_face = 0;
-
-    if ( rb_obj_is_kind_of(other, rb_cCArray) ) {
-      CArray *oc;
-      TypedData_Get_Struct(other, CArray, &carray_data_type, oc);
-      other_is_face = ca_is_face(oc);
-    }
-
-    if ( comparable ) {
-      /* directly comparable Face reference: strip a Face operand, take a
-         plain operand as-is (storage compare is licensed). */
-      if ( other_is_face ) {
-        other = rb_ca_strip_face_value(other);
-      }
-    }
-    else if ( rb_respond_to(self_ref, rb_intern("to_comparable")) ) {
-      /* non-COMPARABLE Face reference: the reference brings the operand into
-         its own space (unit alignment / instant lift), whatever the operand
-         type -- Face CArray, our Scalar, a Ruby Time / DateTime, etc.  The
-         reference's to_comparable raises if it cannot reconcile it. */
-      other = rb_funcall(self_ref, rb_intern("to_comparable"), 1, other);
-      other = rb_ca_strip_face_value(other);
+    /* A Ruby Array is a list of values (to_comparable reads it cell by
+       cell), not one value, so it keeps the length it was given. */
+    int other_was_scalar = ! RTEST(rb_obj_is_carray(other))
+                           && ! RB_TYPE_P(other, T_ARRAY);
+    volatile VALUE ref = self, op = other;
+    ca_face_reconcile_pair(&ref, &op, "comparison");
+    /* The reconcile lifts a scalar operand to a length-1 array; unwrap it
+       so the comparison stays array-vs-scalar instead of a shape check
+       against [1] (which only a 1-D reference would pass). */
+    if ( other_was_scalar && RTEST(rb_obj_is_carray(op)) ) {
+      op = rb_ca_fetch_addr(op, 0);
     }
-    else {
-      rb_raise(rb_eArgError,
-               "comparison: non-comparable Face reference (%s) has no "
-               "to_comparable to reconcile the operand; use ca.parent to "
-               "compare the hidden storage explicitly",
-               rb_obj_classname(self_ref));
-    }
-
-    *pself  = rb_ca_strip_face_value(self);
-    *pother = other;
+    *pself  = rb_ca_strip_face_value(ref);
+    *pother = op;
   }
 }
 
@@ -771,4 +1284,14 @@ Init_ca_face (void)
   rb_define_singleton_method(rb_cCArray, "face_state_portable?",
                              rb_ca_s_face_state_portable_p, 0);
   rb_define_method(rb_cCArray, "face_lift", rb_ca_face_lift_method, 1);
+  rb_define_private_method(rb_cCArray, "orderable_storage?",
+                           rb_ca_orderable_storage_p, 0);
+  rb_define_private_method(rb_cCArray, "comparable_storage?",
+                           rb_ca_comparable_storage_p, 0);
+  rb_define_private_method(rb_cCArray, "face_storage",
+                           rb_ca_face_storage, 0);
+  rb_define_private_method(rb_cCArray, "reconcile_operand",
+                           rb_ca_reconcile_operand, 2);
+  rb_define_private_method(rb_cCArray, "face_storage_method",
+                           rb_ca_face_storage_method, 0);
 }