carray 3.0.3 → 3.0.4

data/ext/carray.h

@@ -347,14 +347,12 @@ typedef struct {
   void   (*detach)       (void *ap);
   void   (*fill_data)    (void *ap, void *data);
   void   (*create_mask)  (void *ap);
-  /* xfer protocol.  Added at struct end so existing
-     positional initializers leave it NULL automatically.  dir = CA_XFER_GET /
-     CA_XFER_PUT. */
+  /* xfer protocol.  dir = CA_XFER_GET / CA_XFER_PUT. */
   void   (*xfer_index)   (void *ap, ca_size_t *idx, void *data, int dir);
   void   (*xfer_addrs)   (void *ap, ca_size_t n, ca_size_t *addrs,
                           void *data, int dir);
-  /* fold_stride: one compose-fold hop
-     for sometimes-fold participants (CAWindow now; CAGrid/CSA/CATile later).
+  /* fold_stride: one compose-fold hop for the views that fold only
+     sometimes (CAWindow, CAGrid, CASelectAxis, CAStack, CAMeld).
      Compose *f into next_parent's byte space and return 1, or decline
      (leave *f / *next_parent untouched) and return 0 -> this view is the
      fold boundary.  CAStride family leaves this NULL (handled open-inline
@@ -637,6 +635,13 @@ typedef struct {
                                        (count[k] == parent->dim[k] && start[k]
                                        == 0 for k >= 1).  Embedded region
                                        must be contig in parent storage. */
+  /* A window over a parent that has no mask: the all-false mask its own
+     mask reads instead, so that masking the out-of-bounds cells gives the
+     parent no mask.  Owned by this window; NULL otherwise. */
+  CArray     *mask_standin;
+  /* On the mask of a window: the window whose mask it is, which holds the
+     stand-in and the parent whose mask replaces it.  NULL otherwise. */
+  CArray     *mask_owner;
 } CAWindow;                /* 56 + 16*(ndim) + 1*(bytes) + 1*ndim + 24*ndim (bytes) */
 
 /* CAShift is a pure typedef of CAWindow.  CAShift construction maps (shift[], roll[], fill,
@@ -681,17 +686,17 @@ typedef struct {
                               dim[k] = parent->dim[k] * reps[k]. */
 } CATile;                /* 56 + 8*(ndim) (bytes) */
 
-typedef CATile CARoll;   /* T.4 will land CARoll-specific constructor +
-                            obj_type CA_OBJ_ROLL.  Until then CARoll path
-                            is just CATile (= typedef body identical). */
+typedef CATile CARoll;   /* same layout as CATile, its own obj_type
+                            CA_OBJ_ROLL (ext/ca_obj_roll.c) */
 
-/* CAStack: outer-axis-only stack view of K uniform-shape parents.  shape = (K, *parent_shape),
-   axis 0 maps to parent index, axes 1..ndim-1 are per-parent contig.
+/* CAStack: stack view of K uniform-shape parents.  The K axis sits at
+   k_axis in the view's shape (0 by default: shape = (K, *parent_shape));
+   the other axes are the parents' own.
    - parents stored as Ruby Array @parents on the wrapper object (= GC
      anchor); C-side tail `parents[]` is alias pointer array.
    - CAView.parent points to parents[0] (= legacy compat for paths that
      deref ca->parent without CAStack awareness).
-   - dim[0] = n_parents; dim[1..ndim-1] = parents[0]->dim[0..ndim-2]. */
+   - dim[k_axis] = n_parents; the other dims are parents[0]->dim in order. */
 typedef struct {
   int16_t   obj_type;
   int8_t    data_type;
@@ -699,7 +704,7 @@ typedef struct {
   int32_t   flags;
   ca_size_t bytes;
   ca_size_t elements;      /* = n_parents * parents[0]->elements */
-  ca_size_t *dim;          /* ALLOC_N(ndim) = [n_parents, *parent->dim] */
+  ca_size_t *dim;          /* ALLOC_N(ndim): parent->dim with n_parents at k_axis */
   char     *ptr;
   CArray   *mask;
   char     *_pool;         /* framework-managed pool buffer (NULL = legacy ALLOC_N path).
@@ -731,8 +736,7 @@ typedef struct {
      shape[meld_axis] = sum_k parents[k]->dim[meld_axis]
    All other axes must match across parents (uniform check at constructor).
 
-   v0.1 stub: external-axis (meld_axis == 0) structural xfer_stride path only.
-   Other paths raise NotImplementedError. */
+   meld_axis may be any axis. */
 typedef struct {
   int16_t   obj_type;
   int8_t    data_type;
@@ -869,8 +873,10 @@ extern const char *  ca_type_name[CA_NTYPE];
 extern const int ca_cast_table[CA_NTYPE][CA_NTYPE];
 extern const int ca_cast_table2[CA_NTYPE][CA_NTYPE];
 
-/* data_type promotion reducer — pure function over ca_cast_table.  Used by
-   CArray.result_type and by the lazy view layer.  See ext/carray_cast.c
+/* data_type promotion reducer over ca_cast_table.  Used by
+   CArray.result_type and by the lazy view layer.  Raises ArgumentError for
+   a code outside the data types, and CArray::DataTypeError for a pair with
+   no common type.  See ext/carray_cast.c
    for the definition; this is the single source of the promotion rule. */
 int8_t ca_promote_type (int8_t a, int8_t b);
 
@@ -878,7 +884,8 @@ int8_t ca_promote_type (int8_t a, int8_t b);
    Complex, etc.) — distinct from rb_ca_guess_type which interprets the
    object as a data_type *representation* (e.g. T_FIXNUM as a data_type code).
    Used by rb_ca_cast_self_or_other.
-   CArray is not accepted (callers should use ca->data_type directly). */
+   A CArray, like any object it does not recognise, answers CA_OBJECT;
+   callers holding a CArray use ca->data_type. */
 int8_t ca_value_to_data_type (VALUE obj);
 
 /* Infer a data_type code from a MemoryView producer by parsing its format,
@@ -930,8 +937,6 @@ extern const rb_data_type_t cabyteswap_data_type;
 /* cafield_data_type was retired in 3.0 (Phase F: CAField is now a
    CAStride subclass; use castride_data_type). */
 extern const rb_data_type_t cagrid_data_type;
-/* camapping_data_type was retired in 3.0 (R.3: CAMapping removed; a[mapper]
-   now builds a CAGrid/CAStride normalize chain). */
 extern const rb_data_type_t caobject_data_type;
 extern const rb_data_type_t careduce_data_type;
 extern const rb_data_type_t carefer_data_type;
@@ -942,7 +947,6 @@ extern const rb_data_type_t cawindow_data_type;
 extern const rb_data_type_t carray_mask_data_type;
 extern const rb_data_type_t cablock_mask_data_type;
 extern const rb_data_type_t cagrid_mask_data_type;
-extern const rb_data_type_t camapping_mask_data_type;
 extern const rb_data_type_t careduce_mask_data_type;
 extern const rb_data_type_t carefer_mask_data_type;
 extern const rb_data_type_t caselect_mask_data_type;
@@ -999,50 +1003,59 @@ extern VALUE rb_cCArrayObject;
 
 #define CA_CHECK_DATA_TYPE(data_type) \
   do { \
-    if ( data_type <= CA_NONE || data_type >= CA_NTYPE ) { \
-      rb_raise(rb_eArgError, "invalid data_type id %i", data_type);     \
+    int ca_dt_ = (data_type); \
+    if ( ca_dt_ <= CA_NONE || ca_dt_ >= CA_NTYPE ) { \
+      rb_raise(rb_eArgError, "invalid data_type id %i", ca_dt_);     \
     } \
-    if ( ! ca_valid[data_type] ) { \
-      rb_raise(rb_eCADataTypeError, "data_type %s is disabled", ca_type_name[data_type]);    \
+    if ( ! ca_valid[ca_dt_] ) { \
+      rb_raise(rb_eCADataTypeError, "data_type %s is disabled", ca_type_name[ca_dt_]);    \
     } \
   } while (0)
 
 #define CA_CHECK_DATA_TYPE_NUMERIC(data_type) \
-  if ( data_type <= CA_NONE || data_type >= CA_NTYPE || !ca_valid[data_type] || data_type == CA_FIXLEN || data_type == CA_OBJECT ) { \
-    rb_raise(rb_eCADataTypeError, "invalid numeric data type"); \
-  }
+  do { \
+    int ca_dt_ = (data_type); \
+    if ( ca_dt_ <= CA_NONE || ca_dt_ >= CA_NTYPE || !ca_valid[ca_dt_] || \
+         ca_dt_ == CA_FIXLEN || ca_dt_ == CA_OBJECT ) { \
+      rb_raise(rb_eCADataTypeError, "invalid numeric data type"); \
+    } \
+  } while (0)
 
 #define CA_CHECK_RANK(ndim) \
-  if ( ndim <= 0 || ndim > CA_RANK_MAX ) { \
-    rb_raise(rb_eArgError, "invalid ndim"); \
-  }
+  do { \
+    if ( (ndim) <= 0 || (ndim) > CA_RANK_MAX ) { \
+      rb_raise(rb_eArgError, "invalid ndim"); \
+    } \
+  } while (0)
 
 #define CA_CHECK_DIM(ndim, dim)     \
-  { \
+  do { \
     int8_t i_; \
-    for (i_=0; i_<ndim; i_++) { \
-      if ( dim[i_] < 0 ) { \
+    for (i_=0; i_<(ndim); i_++) { \
+      if ( (dim)[i_] < 0 ) { \
         rb_raise(rb_eArgError, "negative size dimension at %i-dim", i_);  \
       } \
     } \
-  }
+  } while (0)
 
 /* A fixlen cell is at least one byte wide.  A zero-width cell has one
    possible value, and a strided view of it cannot say which cell is which:
    its byte strides are all zero. */
 #define CA_CHECK_BYTES(data_type, bytes) \
-  if ( data_type == CA_FIXLEN ) { \
-    if ( bytes <= 0 ) {                            \
-      rb_raise(rb_eArgError,                   \
-               "invalid bytes (a fixlen needs bytes: of 1 or more)"); \
+  do { \
+    if ( (data_type) == CA_FIXLEN ) { \
+      if ( (bytes) <= 0 ) {                            \
+        rb_raise(rb_eArgError,                   \
+                 "invalid bytes (a fixlen needs bytes: of 1 or more)"); \
+      } \
     } \
-  } \
-  else { \
-    bytes = ca_sizeof[data_type]; \
-    if ( bytes <= 0 ) {           \
-      rb_raise(rb_eArgError, "invalid bytes"); \
+    else { \
+      (bytes) = ca_sizeof[(data_type)]; \
+      if ( (bytes) <= 0 ) {           \
+        rb_raise(rb_eArgError, "invalid bytes"); \
+      } \
     } \
-  }
+  } while (0)
 
 /* An index into `n` places, counted from the end when negative, outside of
    which IndexError is raised naming the method the user called, `what` the
@@ -1108,6 +1121,10 @@ rb_carray_num2cmplx (VALUE num)
   }
   if ( rb_respond_to(num, rb_intern("to_c")) ) {
     VALUE c = rb_funcall(num, rb_intern("to_c"), 0);
+    if ( ! RB_TYPE_P(c, T_COMPLEX) ) {
+      rb_raise(rb_eTypeError, "can't convert %"PRIsVALUE" to Complex (%"PRIsVALUE"#to_c gives %"PRIsVALUE")",
+               rb_obj_class(num), rb_obj_class(num), rb_obj_class(c));
+    }
     return CMPLX(NUM2DBL(rb_complex_real(c)), NUM2DBL(rb_complex_imag(c)));
   }
   if ( rb_respond_to(num, rb_intern("to_f")) ) {
@@ -1184,8 +1201,7 @@ enum {
   CA_IDX_SCALAR,
   CA_IDX_ALL,
   CA_IDX_BLOCK,
-  CA_IDX_SYMBOL,
-  CA_IDX_REPEAT
+  CA_IDX_SYMBOL
 }; /* CA_INDEX_TYPE */
 
 typedef union {
@@ -1254,14 +1270,14 @@ VALUE    rb_carray_new_safe (int8_t data_type,
    already hold a freshly decoded buffer and want to avoid a copy.  The
    buffer must be ruby_xmalloc()'d and at least elements*bytes long; it
    is freed with xfree() when the array is collected.  data_type must not
-   be CA_OBJECT. */
+   be CA_OBJECT.  When the call raises (a bad argument), the buffer stays
+   the caller's. */
 CArray  *carray_new_adopt (int8_t data_type,
                            int8_t ndim, ca_size_t *dim, ca_size_t bytes, char *ptr);
 VALUE    rb_carray_new_adopt (int8_t data_type,
                               int8_t ndim, ca_size_t *dim, ca_size_t bytes, char *ptr);
 
-/* Capstone helper: allocate
-   a reduction-output CArray for kernel_iterator authors.  Computes
+/* Allocate a reduction-output CArray for kernel_iterator authors.  Computes
    output shape = self.dim with slab axes removed (ascending order),
    collapses to shape [1] when fully reduced.  See
    ext/carray_core.c for docstring + semantics. */
@@ -1272,10 +1288,10 @@ VALUE    rb_ca_new_reduced (VALUE self, int8_t *slab_axes,
 VALUE    rb_ca_new_reduced_bytes (VALUE self, int8_t *slab_axes, int8_t naxes,
                                   int32_t data_type, ca_size_t bytes, int keep_axis);
 
-/* Capstone helper: parse
-   variadic axis argv into validated int8_t array.  Accepts Integer
-   args or a single Array arg, normalises negative axes (Python-style),
-   range / duplicate / overflow checks all raise ArgumentError.
+/* Parse variadic axis argv into a validated int8_t array.  Accepts Integer
+   args or a single Array arg (no argument = every axis), counts negative
+   axes from the end, and raises ArgumentError for an axis out of range or
+   given twice.
    Returns the validated naxes. */
 int8_t   rb_ca_parse_reduce_axes (int argc, VALUE *argv,
                                   CArray *ca, int8_t *out_axes);
@@ -1321,7 +1337,11 @@ VALUE    rb_ca_farray (VALUE self);
 
 /* --- ca_obj_stride.c --- */
 
-/* ca_stride_setup with ca == NULL runs its checks and returns 0 without
+/* The strides and base_offset are taken as given: they are not checked
+   against the parent's extent, so a view that reaches outside it reads
+   and writes outside it.
+
+   ca_stride_setup with ca == NULL runs its checks and returns 0 without
    writing.  ca_stride_new calls it that way before it allocates, so a
    rejected argument leaves no struct behind; a subclass constructor can
    do the same through its own setup function. */
@@ -1394,8 +1414,16 @@ void    ca_broadcast_pair (volatile VALUE *self, volatile VALUE *other);
      ca_install_obj_type(klass, &td, mask_klass, &mask_td,
                          &my_func, sizeof(my_func));
 
+   The table must reach at least through xfer_all: xfer_index, xfer_addrs
+   and xfer_all have no default.  fold_stride may be NULL (the view is a
+   fold boundary); xfer_stride, the pool slots, fill_addrs and fill_stride
+   fall back to a default when NULL.  A shorter table raises RuntimeError.
    A func_size larger than this build's struct means the caller was compiled
-   against a newer carray; that is reported rather than truncated. */
+   against a newer carray; that is reported rather than truncated.
+
+   The obj_type parameters of ca_array_alloc, ca_array_pool_alloc,
+   ca_stride_setup and ca_stride_new are int8_t, so an obj_type is numbered
+   below 128: an install that would number one at 128 or above raises. */
 
 int
 ca_install_obj_type (VALUE klass,
@@ -1462,19 +1490,24 @@ int     ca_is_mask_array (void *ap);
 #define GetCArray(obj, ca) \
     TypedData_Get_Struct((obj), CArray, &carray_data_type, (ca))
 
-/* True iff ca_attach(ca) is essentially O(1) — entity arrays (already
-   attached), CAWrap, CScalar, and CAStride-family views whose composed
-   strides are row-major contiguous (alias-attach path).  Used by
-   kernel_iterator's L1 alias decision (ca_iter_can_alias level 1) and
-   by overlay-view dispatch.  The name says the structural property
-   (= aliasable without materialise), not the perf characteristic. */
+/* True when ca_attach(ca) gives ca->ptr the cells in place, without
+   materialising: entity arrays, CAWrap, CScalar, and CAStride-family
+   views whose composed strides are row-major contiguous over an attached
+   root (alias-attach path).  It is not the same as "attach is O(1)": a
+   Face attaches in O(1) by borrowing its parent and answers false, and a
+   CASource entity that publishes its ptr only while attached answers
+   true.  Used by the kernel iterator's alias decision, the sweep engine,
+   and the views and mask paths that skip a sync when nothing was copied. */
 int     ca_attach_is_alias (void *ap);
 
 /* OR operand masks into
    ca_out->mask without ca_attach on operand masks (= gathers via
-   ca_xfer_all into arena scratch then byte OR-folds).  ca_out must be
-   a freshly templated entity.  For bang variant where ca_out IS one of
-   the operands, the existing mask is preserved as initial accumulator. */
+   ca_xfer_all into arena scratch then byte OR-folds).  ca_out's mask is
+   written through its ptr, so ca_out is an entity or an attached view.
+   Each operand other than a scalar has ca_out's number of elements
+   (ArgumentError otherwise); n is at most 8.  For bang variant where
+   ca_out IS one of the operands, the existing mask is preserved as
+   initial accumulator. */
 void    ca_mask_overlay_safe (CArray *ca_out, int n, ...);
 
 #define ca_is_caobject(ca) ( (ca)->obj_type == CA_OBJ_OBJECT )
@@ -1524,20 +1557,30 @@ int     ca_is_valid_index (void *ap, ca_size_t *idx);
                      internally (views carry an attach refcount; entities do
                      not).
      R5 (traffic)    Attach hands you a buffer, not a live array.  Use x->ptr;
-                     a view derived from x composes past the buffer to the
-                     root.
+                     a view derived from x may read past the buffer to the
+                     root (a CAStride-family view over a CAStride-family x
+                     does) or read the buffer (others), so writes to the
+                     buffer are not seen through derived views until x is
+                     synced.
      R6 (raising)    ca_allocate and ca_attach that raise have taken
                      nothing; ca_allocate_n and ca_attach_n take all of
                      their arrays or none.  Close a window with
                      ca_sync_detach, which detaches even when the sync
                      raises -- ca_sync then ca_detach leaves the window open
-                     on a raise.  Anything between that can raise (Ruby
+                     on a raise.  ca_sync_detach syncs, so it raises on a
+                     read-only array; a window that only read closes with
+                     ca_detach.  Anything between that can raise (Ruby
                      called from inside the window) needs an ensure of its
                      own.
 */
 
+/* ca_allocate opens a window for writing every cell: what the cells held
+   before is not kept, also when the array is already attached (object cells
+   are reset to 0 and the mask is cleared). */
 void    ca_allocate (void *ap);
 void    ca_attach (void *ca);
+/* Re-gather an attached view's buffer from its parent (one level: a parent
+   that holds its own buffer is read as it is). */
 void    ca_update (void *ca);
 void    ca_sync (void *ca);
 void    ca_detach (void *ca);
@@ -1549,17 +1592,70 @@ void    ca_update_n (int n, ...);
 void    ca_sync_n (int n, ...);
 void    ca_detach_n (int n, ...);
 
+/* API : lending the addresses of cells
+
+   A kernel that reads cells by address itself -- a stencil reading
+   a[i-1][j] and a[i+1][j] from its own loop -- needs, for each array, a
+   pointer to cell (0, ..., 0) and the byte distance between neighbours
+   along each axis.  ca_with_address_bases lends that for the duration of
+   `body`, whatever the arrays are, and puts back what the kernel wrote:
+
+     - an entity, or a view the engine can fold down to one (a slice, a
+       transpose, a reshape), is addressed in place;
+     - any other view (a selection, a conversion, a lazy expression) has
+       the cells the kernel touches copied into a buffer, which is lent
+       instead and, for a writable array, sent back afterwards: only the
+       cells the kernel changed, through the view.
+
+   `box_start[i]` / `box_count[i]` (ndim values each) say which cells
+   array i's kernel touches -- its loop range, widened by how far the
+   kernel reaches (one cell each way for a[i-1] .. a[i+1]).  They decide
+   what the second case copies; the first case lends the whole array
+   either way.  Pass NULL for `box_start` and `box_count` (or for an
+   entry of them) to lend the whole array.  A box outside the array is
+   refused.  Address only the box, whichever way the array was lent.
+
+   `writable[i]` says whether the kernel writes array i (NULL: none is
+   written); a read-only array is refused for writing.  An object array
+   is refused (its cells are Ruby values, not numbers), and so is a view
+   with a mask that reinterprets the element size (its mask cells do not
+   map one to one onto the parent's).
+
+   A masked array also lends its mask: one boolean8_t per cell (nonzero =
+   masked), addressed with mask_strides the same way.  A write to the
+   mask is put back like a write to a cell.  `mask` is NULL for an array
+   with no mask.
+
+   `body` may raise: the arrays are still written back and closed.
+   Returns what `body` returns.  The CArray pointers must stay alive for
+   the call (keep the VALUEs they came from). */
+typedef struct {
+  char       *ptr;                        /* cell (0, ..., 0) */
+  ca_size_t   strides[CA_RANK_MAX];       /* byte step along each axis */
+  boolean8_t *mask;                       /* NULL when no mask */
+  ca_size_t   mask_strides[CA_RANK_MAX];  /* byte step in the mask */
+  int         writable;
+} ca_address_basis_t;
+
+VALUE   ca_with_address_bases (int32_t n, CArray **arrays, const int *writable,
+                               const ca_size_t *const *box_start,
+                               const ca_size_t *const *box_count,
+                               VALUE (*body)(ca_address_basis_t *bases,
+                                             VALUE arg),
+                               VALUE arg);
+
 /* API : copying */
 
 void   *ca_clone (void *ap);          /* use rb_obj_clone() */
+/* A CA_OBJECT copy holds VALUEs the GC does not see until the struct is
+   wrapped, and wrapping allocates: for an object array use rb_ca_copy, which
+   keeps them alive and returns the wrapped copy. */
 CArray *ca_copy (void *ap);           /* use rb_ca_copy() */
 CArray *ca_template (void *ap);       /* use rb_ca_template() */
 CArray *ca_template_safe (void *ap);  /* use rb_ca_template() */
 CArray *ca_template_safe2 (void *ap, int8_t data_type, ca_size_t bytes);
                                       /* use rb_ca_template() */
 
-/* ca_paste / ca_clip / ca_cut (sub-region copy in/out) removed in 3.0; see
-   lib/extras/crop_paste.rb for the Ruby thin wrapper replacements. */
 void    ca_fill (void *ap, void *ptr);
 
 /* API : fetch, store */
@@ -1580,9 +1676,10 @@ void    ca_xfer_addrs (void *ap, ca_size_t n, ca_size_t *addrs, void *data, int
    opportunistic engine dispatch. */
 int     ca_xfer_addrs_is_sequential_run (ca_size_t n, ca_size_t *addrs,
                                          ca_size_t *base_out);
-/* Y.1.e: resolve cand through identity CAStride compose-fold to find an
+/* Resolve cand through identity CAStride compose-fold to find an
    attached root.  Returns cand if cand->ptr is set, cand is not CAStride
-   family, or no identity compose-fold path exists; otherwise returns the
+   family, or no identity compose-fold path exists (the cells differ from
+   the root's in data type, width or position); otherwise returns the
    resolved root (which has ptr).  Used by view xfer_addrs slots to lift
    parent->ptr gate through view CAStride layers (= chain pattern). */
 CArray *ca_resolve_attached_root_via_identity (CArray *cand);
@@ -1658,6 +1755,8 @@ void    ca_fill_stride_whole (void *ap, void *ptr);
 extern VALUE CA_UNDEF;
 extern VALUE CA_UNSPECIFIED;
 
+/* The mask's buffer, which a view's mask has only while attached: NULL
+   otherwise. */
 boolean8_t *ca_mask_ptr (void *ap);
 int     ca_has_mask (void *ap);
 int     ca_is_any_masked (void *ap);
@@ -1674,7 +1773,7 @@ void    ca_copy_mask_overwrite (void *ap, ca_size_t elements, int n, ...);
 ca_size_t ca_count_masked (void *ap);
 ca_size_t ca_count_not_masked (void *ap);
 void    ca_unmask (void *ap, char *fill_value);
-CArray *ca_unmasked_copy (void *ap, char *fill_value);
+CArray *ca_unmask_copy (void *ap, char *fill_value);
 
 /* API : cast, conversion */
 
@@ -1688,7 +1787,7 @@ void    ca_ptr2val (void *ap1, void *ptr1, int8_t data_type2, void *ptr2);
 void    ca_val2ptr (int8_t data_type1, void *ptr1, void *ap2, void *ptr2);
 void    ca_val2val (int8_t data_type1, void *ptr1, int8_t data_type2, void *ptr2);
 VALUE   ca_ptr2obj (void *ap, void *ptr);            /* use rb_ca_ptr2obj() */
-void    ca_obj2ptr (void *ap, VALUE obj, void *ptr); /* use rb_ca_ptr2obj() */
+void    ca_obj2ptr (void *ap, VALUE obj, void *ptr); /* use rb_ca_obj2ptr() */
 
 #define ca_wrap_writable(obj, data_type) \
   (obj = rb_ca_wrap_writable(obj, INT2NUM(data_type)), (CArray*) DATA_PTR(obj))
@@ -1738,6 +1837,8 @@ void    rb_check_carray_object (VALUE arg);
 
 /* specific Data_Wrap_Struct for carray */
 VALUE   ca_wrap_struct (void *ap);
+/* As ca_wrap_struct, under the class klass.  klass is not checked: it must
+   be a CArray class whose instances share ap's TypedData. */
 VALUE   ca_wrap_struct_as (void *ap, VALUE klass);
 
 /* query data_type */
@@ -1746,7 +1847,8 @@ void    rb_ca_guess_type_and_bytes (VALUE rtype, VALUE rbytes,
                                     int8_t *data_type, ca_size_t *bytes);
 int     rb_ca_is_type (VALUE arg, int type);
 
-/* scan index */ 
+/* scan index.  info->range_check is read, not written: set it (1 to check
+   each index against ca_dim) before the call. */
 void    rb_ca_scan_index (int ca_ndim, ca_size_t *ca_dim, ca_size_t elements,
                           long argc, VALUE *argv, CAIndexInfo *info);
 
@@ -1853,9 +1955,13 @@ VALUE   rb_ca_fill_copy (VALUE self, VALUE val);
 /* address calculation */
 VALUE   rb_ca_addr2index (VALUE self, VALUE raddr);
 
-/* elemental access like ca[i,j,k] or ca[addr] */
+/* A cell's bytes (self's data type, self->bytes wide) as the value ca[i]
+   gives for that cell: true or false for a boolean, the element for a
+   Face, a record for a struct.  The mask is not consulted. */
 VALUE   rb_ca_ptr2obj (VALUE self, void *ptr);
 #define rb_ca_fetch_ptr(self, ptr) rb_ca_ptr2obj(self, ptr)
+
+/* elemental access like ca[i,j,k] or ca[addr] */
 VALUE   rb_ca_fetch_index (VALUE self, ca_size_t *idx);
 VALUE   rb_ca_fetch_addr (VALUE self, ca_size_t addr);
 VALUE   rb_ca_fetch (VALUE self, VALUE index);