carray 3.0.2 → 3.0.3

data/ext/caframe_csv_reader.c

@@ -0,0 +1,463 @@
+/* CSV body reader for CAFrame.from_csv.
+
+   CArray.__csv_read_body_as_string_cells__(text, sep, quote, ncol, keep)
+     -> [ncol, cells, records]
+   reads every record of text into one flat Array of nrow * ncol cells, row
+   after row: a String for a field, UNDEF for a missing one (an unquoted
+   empty field, or a cell a short row never reached).  keep, when not nil,
+   is the ascending Array of the indexes of the columns to read: a row then
+   has a cell for each of them only, and the fields of the others are passed
+   over without being copied out of the text.  records counts the
+   records read, blank lines included, as the Ruby tokenizer numbers them.
+   With ncol 0 the column count is the first record's, as for a file with no
+   header; a later record that is longer is then one this reader declines.
+
+   CArray.__csv_read_body_as_const_string_columns__(text, sep, quote, ncol, keep)
+     -> [ncol, buffer, [pairs, ...], records]
+   reads the same records into one fixlen-16 (start, end) pair entity per
+   column read, the layout CAConstString.wrap takes, with missing cells masked.
+   The pairs index buffer, which is text itself when no field held a doubled
+   quote, and text followed by those fields' unescaped bytes otherwise, so
+   the cells are not copied out of the text.
+
+   Both follow the rules of the Ruby tokenizer in
+   lib/carray/frame/csv_parser.rb, which stays the reference: a quoted field
+   may hold the separator, doubled quotes and line breaks; a line that is
+   empty, or only spaces and tabs with no separator, is not a row unless the
+   file has one column.  They answer nil, for the Ruby tokenizer to read the
+   text and say what is wrong, when the text is not UTF-8 or US-ASCII or has
+   an invalid byte, when a record is malformed or longer than ncol, and when
+   keep names no column or one past the last. */
+
+#include "carray.h"
+#include "carray_internal.h"
+#include "ruby/encoding.h"
+
+static int
+ca_csv_at (const char *s, long n, long p, const char *t, long tlen)
+{
+  return p + tlen <= n && memcmp(s + p, t, tlen) == 0;
+}
+
+/* The end of the line content that starts at p: the position of its "\n",
+   or n; *next is where the following line starts.  A "\r" before the "\n",
+   or at the end of the text, is not content. */
+static long
+ca_csv_line_end (const char *s, long n, long p, long *next)
+{
+  const char *nl = memchr(s + p, '\n', n - p);
+  long e = nl ? nl - s : n;
+  *next = nl ? e + 1 : n;
+  if ( e > p && s[e - 1] == '\r' ) {
+    e -= 1;
+  }
+  return e;
+}
+
+/* A growing list of (start, end) pairs.  A pair at or past the length of
+   the text indexes the unescaped tail; a missing cell is (-1, -1). */
+typedef struct {
+  int64_t *v;
+  long len, cap;           /* in pairs */
+} ca_csv_cell_ranges;
+
+static void
+ca_csv_push_cell_range (ca_csv_cell_ranges *a, int64_t start, int64_t end)
+{
+  if ( a->len == a->cap ) {
+    a->cap = a->cap ? 2 * a->cap : 4096;
+    REALLOC_N(a->v, int64_t, 2 * a->cap);
+  }
+  a->v[2 * a->len]     = start;
+  a->v[2 * a->len + 1] = end;
+  a->len++;
+}
+
+typedef struct {
+  ca_csv_cell_ranges cells;      /* row after row */
+  ca_csv_cell_ranges pending;    /* blank lines before the first record */
+  VALUE tail;              /* unescaped quoted fields, or Qnil */
+  VALUE keep;              /* the indexes of the columns to read, or Qnil */
+  char *kept;              /* keep as a byte per column, 1 for one read;
+                              NULL for every column, or before ncol is known */
+  long ncol;
+  long width;              /* the cells of a row: those of the columns read */
+  long records;
+} ca_csv_walk_t;
+
+/* Set w->kept and w->width from w->keep for w->ncol columns.  Returns 0 when
+   keep names no column or one past the last. */
+static int
+ca_csv_set_kept_columns (ca_csv_walk_t *w)
+{
+  long i;
+  w->kept = ALLOC_N(char, w->ncol);
+  memset(w->kept, 0, w->ncol);
+  for (i = 0; i < RARRAY_LEN(w->keep); i++) {
+    long j = NUM2LONG(rb_ary_entry(w->keep, i));
+    if ( j < 0 || j >= w->ncol ) {
+      return 0;
+    }
+    if ( ! w->kept[j] ) {
+      w->kept[j] = 1;
+      w->width++;
+    }
+  }
+  return w->width > 0;
+}
+
+/* Read every record of s into w.  Returns 0 when the text is one this
+   reader declines (see the header comment).  The cell ranges it grows are
+   the caller's to free, whether it returns or raises. */
+static int
+ca_csv_walk_records (const char *s, long n, const char *sp, long slen,
+             const char *qp, long qlen, ca_csv_walk_t *w)
+{
+  long ncol = w->ncol, p = 0;
+
+  if ( ! NIL_P(w->keep) && ncol > 0 && ! ca_csv_set_kept_columns(w) ) {
+    return 0;
+  }
+  while ( p < n ) {
+    long next, e = ca_csv_line_end(s, n, p, &next), k, fields = 0;
+    int blank = 1;
+
+    w->records += 1;
+
+    /* A blank line: empty, or only spaces and tabs with no separator. */
+    for (k = p; k < e; k++) {
+      if ( s[k] != ' ' && s[k] != '\t' ) {
+        blank = 0;
+        break;
+      }
+    }
+    if ( blank ) {
+      for (k = p; k + slen <= e; k++) {
+        if ( memcmp(s + k, sp, slen) == 0 ) {
+          blank = 0;
+          break;
+        }
+      }
+    }
+    if ( blank ) {
+      int64_t a = e > p ? p : -1, b = e > p ? e : -1;
+      if ( ncol == 1 ) {
+        if ( w->kept == NULL || w->kept[0] ) {
+          ca_csv_push_cell_range(&w->cells, a, b);
+        }
+      }
+      else if ( ncol == 0 ) {
+        /* Before the first record the column count is not known: keep the
+           line, a row if that record turns out to have one column. */
+        ca_csv_push_cell_range(&w->pending, a, b);
+      }
+      p = next;
+      continue;
+    }
+
+    for (;;) {
+      int64_t a = -1, b = -1;
+      /* The field of a column not read is passed over, its text not
+         unescaped. */
+      int read = w->kept == NULL || ( fields < ncol && w->kept[fields] );
+      if ( ca_csv_at(s, n, p, qp, qlen) ) {
+        /* A quoted field, which may run onto later lines. */
+        long q = p + qlen, start = q, tail0 = -1;
+        for (;;) {
+          const char *hit = NULL;
+          long r = q;
+          while ( r + qlen <= n ) {
+            const char *c = memchr(s + r, qp[0], n - r);
+            if ( c == NULL ) {
+              break;
+            }
+            r = c - s;
+            if ( ca_csv_at(s, n, r, qp, qlen) ) {
+              hit = c;
+              break;
+            }
+            r++;
+          }
+          if ( hit == NULL ) {
+            return 0;                           /* unterminated */
+          }
+          if ( ca_csv_at(s, n, r + qlen, qp, qlen) ) {
+            /* a doubled quote is a literal one */
+            if ( ! read ) {
+              q = r + 2 * qlen;
+              continue;
+            }
+            if ( NIL_P(w->tail) ) {
+              w->tail = rb_str_buf_new(256);
+            }
+            if ( tail0 < 0 ) {
+              tail0 = RSTRING_LEN(w->tail);
+              rb_str_cat(w->tail, s + start, r + qlen - start);
+            }
+            else {
+              rb_str_cat(w->tail, s + q, r + qlen - q);
+            }
+            q = r + 2 * qlen;
+            continue;
+          }
+          if ( tail0 < 0 ) {
+            a = start;
+            b = r;
+          }
+          else {
+            rb_str_cat(w->tail, s + q, r - q);
+            a = n + tail0;
+            b = n + RSTRING_LEN(w->tail);
+          }
+          p = r + qlen;
+          break;
+        }
+        e = ca_csv_line_end(s, n, p, &next);
+        if ( p != e && ! ca_csv_at(s, n, p, sp, slen) ) {
+          return 0;                             /* text after the closing quote */
+        }
+      }
+      else {
+        long r = p;
+        if ( slen == 1 && qlen == 1 ) {
+          const char sc = sp[0], qc = qp[0];
+          while ( r < e && s[r] != sc ) {
+            if ( s[r] == qc ) {
+              return 0;                         /* a quote in an unquoted field */
+            }
+            r++;
+          }
+        }
+        else {
+          while ( r < e && ! ca_csv_at(s, n, r, sp, slen) ) {
+            if ( ca_csv_at(s, n, r, qp, qlen) ) {
+              return 0;                         /* a quote in an unquoted field */
+            }
+            r++;
+          }
+        }
+        a = r > p ? p : -1;
+        b = r > p ? r : -1;
+        p = r;
+      }
+      if ( ++fields > ncol && ncol > 0 ) {
+        return 0;                               /* a row too long */
+      }
+      if ( read ) {
+        ca_csv_push_cell_range(&w->cells, a, b);
+      }
+      if ( p < e && ca_csv_at(s, n, p, sp, slen) ) {
+        p += slen;
+        continue;
+      }
+      break;
+    }
+    if ( ncol == 0 ) {
+      /* The first record sets the column count; the blank lines before it
+         are rows of a one-column file and nothing otherwise. */
+      ncol = fields;
+      if ( ! NIL_P(w->keep) ) {
+        /* Its fields were all read, the columns being unknown until now:
+           keep those of the columns read. */
+        long j, k = 0;
+        w->ncol = ncol;
+        if ( ! ca_csv_set_kept_columns(w) ) {
+          return 0;
+        }
+        for (j = 0; j < ncol; j++) {
+          if ( w->kept[j] ) {
+            w->cells.v[2 * k]     = w->cells.v[2 * j];
+            w->cells.v[2 * k + 1] = w->cells.v[2 * j + 1];
+            k++;
+          }
+        }
+        w->cells.len = k;
+      }
+      if ( ncol == 1 && w->pending.len > 0 ) {
+        long i;
+        for (i = 0; i < w->cells.len; i++) {
+          ca_csv_push_cell_range(&w->pending, w->cells.v[2 * i], w->cells.v[2 * i + 1]);
+        }
+        { ca_csv_cell_ranges t = w->cells; w->cells = w->pending; w->pending = t; }
+        w->pending.len = 0;
+      }
+    }
+    for (; fields < ncol; fields++) {
+      if ( w->kept == NULL || w->kept[fields] ) {
+        ca_csv_push_cell_range(&w->cells, -1, -1);
+      }
+    }
+    p = next;
+  }
+  w->ncol = ncol;
+  if ( NIL_P(w->keep) ) {
+    w->width = ncol;
+  }
+  return ncol > 0;                              /* 0: no record */
+}
+
+/* The arguments both readers take, checked; 0 for text they decline. */
+static int
+ca_csv_check_reader_args (VALUE text, VALUE vsep, VALUE vquote, VALUE vncol,
+                          VALUE keep, long *ncol)
+{
+  rb_encoding *enc;
+  Check_Type(text, T_STRING);
+  Check_Type(vsep, T_STRING);
+  Check_Type(vquote, T_STRING);
+  if ( ! NIL_P(keep) ) {
+    Check_Type(keep, T_ARRAY);
+  }
+  *ncol = NUM2LONG(vncol);
+  enc = rb_enc_get(text);
+  if ( ( enc != rb_utf8_encoding() && enc != rb_usascii_encoding() )
+       || rb_enc_str_coderange(text) == ENC_CODERANGE_BROKEN || *ncol < 0 ) {
+    return 0;
+  }
+  return RSTRING_LEN(vsep) >= 1 && RSTRING_LEN(vquote) >= 1;
+}
+
+/* What a reader makes of the walked records: the Ruby value it answers. */
+typedef VALUE (*ca_csv_build_result) (VALUE text, ca_csv_walk_t *w);
+
+typedef struct {
+  VALUE text, vsep, vquote, vncol;
+  ca_csv_walk_t w;
+  ca_csv_build_result build;
+} ca_csv_read_body_context;
+
+static VALUE
+ca_csv_read_body_walk_and_build (VALUE varg)
+{
+  ca_csv_read_body_context *c = (ca_csv_read_body_context *) varg;
+  if ( ! ca_csv_check_reader_args(c->text, c->vsep, c->vquote, c->vncol, c->w.keep,
+                                  &c->w.ncol) ) {
+    return Qnil;
+  }
+  if ( ! ca_csv_walk_records(RSTRING_PTR(c->text), RSTRING_LEN(c->text),
+                             RSTRING_PTR(c->vsep), RSTRING_LEN(c->vsep),
+                             RSTRING_PTR(c->vquote), RSTRING_LEN(c->vquote), &c->w) ) {
+    return Qnil;
+  }
+  return c->build(c->text, &c->w);
+}
+
+static VALUE
+ca_csv_read_body_free_cell_ranges (VALUE varg)
+{
+  ca_csv_read_body_context *c = (ca_csv_read_body_context *) varg;
+  xfree(c->w.cells.v);
+  xfree(c->w.pending.v);
+  xfree(c->w.kept);
+  return Qnil;
+}
+
+/* Walk the records of text and build the answer from them, with the cell
+   ranges freed however that ends: the walk and the build both allocate,
+   and so may raise. */
+static VALUE
+ca_csv_read_body (VALUE text, VALUE vsep, VALUE vquote, VALUE vncol, VALUE keep,
+                  ca_csv_build_result build)
+{
+  ca_csv_read_body_context c = {
+    text, vsep, vquote, vncol,
+    { { NULL, 0, 0 }, { NULL, 0, 0 }, Qnil, keep, NULL, 0, 0, 0 }, build
+  };
+  VALUE out = rb_ensure(ca_csv_read_body_walk_and_build, (VALUE) &c,
+                        ca_csv_read_body_free_cell_ranges, (VALUE) &c);
+  RB_GC_GUARD(c.w.tail);
+  return out;
+}
+
+static VALUE
+ca_csv_build_string_cells (VALUE text, ca_csv_walk_t *w)
+{
+  volatile VALUE out;
+  rb_encoding *enc = rb_enc_get(text);
+  const char *s = RSTRING_PTR(text);
+  long n = RSTRING_LEN(text), i;
+
+  out = rb_ary_new_capa(w->cells.len);
+  for (i = 0; i < w->cells.len; i++) {
+    int64_t a = w->cells.v[2 * i], b = w->cells.v[2 * i + 1];
+    VALUE cell;
+    if ( a < 0 ) {
+      cell = CA_UNDEF;
+    }
+    else if ( a < n ) {
+      cell = rb_enc_str_new(s + a, b - a, enc);
+    }
+    else {
+      cell = rb_enc_str_new(RSTRING_PTR(w->tail) + (a - n), b - a, enc);
+    }
+    rb_ary_push(out, cell);
+  }
+  return rb_ary_new3(3, LONG2NUM(w->ncol), out, LONG2NUM(w->records));
+}
+
+static VALUE
+ca_csv_build_const_string_columns (VALUE text, ca_csv_walk_t *w)
+{
+  volatile VALUE buffer, cols;
+  ca_size_t dim[1];
+  long nrow, i, j;
+
+  if ( NIL_P(w->tail) ) {
+    buffer = text;
+  }
+  else {
+    buffer = rb_str_buf_new(RSTRING_LEN(text) + RSTRING_LEN(w->tail));
+    rb_str_cat(buffer, RSTRING_PTR(text), RSTRING_LEN(text));
+    rb_str_cat(buffer, RSTRING_PTR(w->tail), RSTRING_LEN(w->tail));
+    rb_enc_copy(buffer, text);
+  }
+
+  nrow = w->cells.len / w->width;
+  dim[0] = (ca_size_t) nrow;
+  cols = rb_ary_new_capa(w->width);
+  for (j = 0; j < w->width; j++) {
+    CArray *pe;
+    int64_t *range;
+    boolean8_t *m = NULL;
+    VALUE col = rb_carray_new(CA_FIXLEN, 1, dim, 2 * sizeof(int64_t), NULL);
+    rb_ary_push(cols, col);
+    TypedData_Get_Struct(col, CArray, &carray_data_type, pe);
+    range = (int64_t *) pe->ptr;
+    for (i = 0; i < nrow; i++) {
+      int64_t a = w->cells.v[2 * (i * w->width + j)];
+      int64_t b = w->cells.v[2 * (i * w->width + j) + 1];
+      if ( a < 0 ) {
+        if ( m == NULL ) {
+          ca_create_mask(pe);
+          m = (boolean8_t *) pe->mask->ptr;
+        }
+        m[i] = 1;
+        a = b = 0;
+      }
+      range[2 * i]     = a;
+      range[2 * i + 1] = b;
+    }
+  }
+  return rb_ary_new3(4, LONG2NUM(w->ncol), buffer, cols, LONG2NUM(w->records));
+}
+
+static VALUE
+rb_ca_s_csv_read_body_as_string_cells (VALUE klass, VALUE text, VALUE vsep, VALUE vquote,
+                                       VALUE vncol, VALUE keep)
+{
+  return ca_csv_read_body(text, vsep, vquote, vncol, keep, ca_csv_build_string_cells);
+}
+
+static VALUE
+rb_ca_s_csv_read_body_as_const_string_columns (VALUE klass, VALUE text, VALUE vsep, VALUE vquote,
+                                               VALUE vncol, VALUE keep)
+{
+  return ca_csv_read_body(text, vsep, vquote, vncol, keep, ca_csv_build_const_string_columns);
+}
+
+void
+Init_caframe_csv_reader (void)
+{
+  rb_define_singleton_method(rb_cCArray, "__csv_read_body_as_string_cells__", rb_ca_s_csv_read_body_as_string_cells, 5);
+  rb_define_singleton_method(rb_cCArray, "__csv_read_body_as_const_string_columns__", rb_ca_s_csv_read_body_as_const_string_columns, 5);
+}

data/ext/carray.h

@@ -716,6 +716,12 @@ typedef struct {
                               0 = outer-axis stack (legacy default).
                               parent_ndim = K innermost (= old merge at=-1).
                               Set by ca_stack_setup_with_axis / preserved on clone. */
+  CArray  **mask_standins; /* NULL, or ALLOC_N(CArray*, n_parents) once the mask is
+                              built: the all-false masks standing in for parents that
+                              have none (owned, freed with the view) */
+  CArray   *mask_owner;    /* on the mask of a CAStack: that CAStack, whose stand-ins
+                              this mask reads until they give way to the parents'
+                              own masks (ca_multi_parent_mask_refresh); else NULL */
 } CAStack;
 
 /* CAMeld (ragged concatenate view along an existing axis).  Unlike CAStack
@@ -749,6 +755,8 @@ typedef struct {
   ca_size_t *seg_offset;   /* ALLOC_N(ca_size_t, K+1); prefix sum along meld_axis.
                               seg_offset[0]=0, seg_offset[k+1]=seg_offset[k]+parents[k]->dim[meld_axis],
                               seg_offset[K]=dim[meld_axis]. */
+  CArray  **mask_standins; /* as CAStack's: stand-in masks this view owns, or NULL */
+  CArray   *mask_owner;    /* as CAStack's */
 } CAMeld;
 
 /* Multi-parent view layout convention (CA_FLAG_MULTI_PARENTS).  A view that
@@ -786,9 +794,14 @@ typedef struct {
   VALUE     self;
 } CAObject;                /* 48 + 4*(ndim) (bytes) */
 
-/* 
-  CAObjectMask is an internal class 
-  used only as mask array of CAObject.
+/*
+  CAObjectMask is an internal class used only as the mask array of a
+  CAObject.  Its bits live in the CAObject's mask hooks (mask_copy_data,
+  mask_fetch_addr, ...) when it has them, and in `cache` -- the mask
+  buffer of the CAObject's internal data array -- always.  Like the mask
+  of any view it is cold at rest: ptr is NULL, and every read and write
+  goes through its slots to the hooks.  An attach publishes the cache in
+  ptr, and `holds` counts the attaches not yet detached.
 */
 
 typedef struct {
@@ -807,6 +820,8 @@ typedef struct {
                               ext/ca_array_pool.c. */
   /* -------------*/
   VALUE     array;
+  char     *cache;
+  long      holds;
 } CAObjectMask;
 
 /* CARepeat (Phase R migration): structurally identical to CAStride.
@@ -862,7 +877,7 @@ int8_t ca_promote_type (int8_t a, int8_t b);
 /* Infer a data_type code from a Ruby *value* (literal Numeric, true/false,
    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 then_else and by ca_lazy_wrap_scalar's bool-self corner case.
+   Used by rb_ca_cast_self_or_other.
    CArray is not accepted (callers should use ca->data_type directly). */
 int8_t ca_value_to_data_type (VALUE obj);
 
@@ -985,21 +1000,21 @@ extern VALUE rb_cCArrayObject;
 #define CA_CHECK_DATA_TYPE(data_type) \
   do { \
     if ( data_type <= CA_NONE || data_type >= CA_NTYPE ) { \
-      rb_raise(rb_eRuntimeError, "invalid data_type id %i", data_type);     \
+      rb_raise(rb_eArgError, "invalid data_type id %i", data_type);     \
     } \
     if ( ! ca_valid[data_type] ) { \
-      rb_raise(rb_eRuntimeError, "data_type %s is disabled", ca_type_name[data_type]);    \
+      rb_raise(rb_eCADataTypeError, "data_type %s is disabled", ca_type_name[data_type]);    \
     } \
   } 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_eRuntimeError, "invalid numeric data type"); \
+    rb_raise(rb_eCADataTypeError, "invalid numeric data type"); \
   }
 
 #define CA_CHECK_RANK(ndim) \
   if ( ndim <= 0 || ndim > CA_RANK_MAX ) { \
-    rb_raise(rb_eRuntimeError, "invalid ndim"); \
+    rb_raise(rb_eArgError, "invalid ndim"); \
   }
 
 #define CA_CHECK_DIM(ndim, dim)     \
@@ -1007,44 +1022,46 @@ extern VALUE rb_cCArrayObject;
     int8_t i_; \
     for (i_=0; i_<ndim; i_++) { \
       if ( dim[i_] < 0 ) { \
-        rb_raise(rb_eRuntimeError, "negative size dimension at %i-dim", i_);  \
+        rb_raise(rb_eArgError, "negative size dimension at %i-dim", i_);  \
       } \
     } \
   }
 
+/* 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_eRuntimeError, "invalid bytes"); \
+    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_eRuntimeError, "invalid bytes"); \
+      rb_raise(rb_eArgError, "invalid bytes"); \
     } \
   }
 
+/* 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
+   index is ("index", "address") and the value given. */
+NORETURN(void ca_index_out_of_range (ca_size_t idx, ca_size_t n, const char *what));
+
+/* Normalise `index` in place against `dim` (a negative one counts from the
+   end) and raise through ca_index_out_of_range when it falls outside. */
 #define CA_CHECK_INDEX(index, dim) \
   do { \
-    if ( index < 0 ) {       \
-      index += (dim);     \
+    ca_size_t ca_check_index_given_ = (index); \
+    if ( (index) < 0 ) {       \
+      (index) += (dim);     \
     } \
-    if ( index < 0 || index >= (dim) ) { \
-      rb_raise(rb_eIndexError, "index out of range ( %" PRId64 " <=> 0..%" PRId64 " )", (int64_t) index, (int64_t) dim-1); \
+    if ( (index) < 0 || (index) >= (dim) ) { \
+      ca_index_out_of_range(ca_check_index_given_, (dim), "index"); \
     } \
   } while (0)
 
-#define CA_CHECK_BOUND(ca, idx) \
-  { \
-    int8_t i; \
-    for (i=0; i<ca->ndim; i++) { \
-      if ( idx[i] < 0 || idx[i] >= ca->dim[i] )  { \
-        rb_raise(rb_eRuntimeError, "index out of range at %i-dim ( %i <=> 0..%i )", i, idx[i], ca->dim[i]-1); \
-      } \
-    } \
-  }
-
 /* -------------------------------------------------------------------- */
 
 /* complex <-> Ruby Complex conversion
@@ -1070,6 +1087,10 @@ extern VALUE rb_cCArrayObject;
 #  endif
 #endif
 
+/* A string as a complex cell: a real number read as Float() reads it
+   (nan / inf included), else as Complex() does; anything else raises. */
+double complex ca_str_to_cmplx (VALUE str);
+
 static inline double complex
 rb_carray_num2cmplx (VALUE num)
 {
@@ -1079,6 +1100,12 @@ rb_carray_num2cmplx (VALUE num)
   if ( RB_FLOAT_TYPE_P(num) || RB_INTEGER_TYPE_P(num) ) {
     return (double complex) NUM2DBL(num);
   }
+  if ( RB_TYPE_P(num, T_STRING) ) {
+    return ca_str_to_cmplx(num);
+  }
+  if ( NIL_P(num) ) {
+    rb_raise(rb_eTypeError, "can't convert nil into Complex");
+  }
   if ( rb_respond_to(num, rb_intern("to_c")) ) {
     VALUE c = rb_funcall(num, rb_intern("to_c"), 0);
     return CMPLX(NUM2DBL(rb_complex_real(c)), NUM2DBL(rb_complex_imag(c)));
@@ -1125,6 +1152,7 @@ double    OBJ2DBL (VALUE v);
    object->int/float cast loop so an unparseable cell becomes UNDEF instead
    of a silent 0.0 (float) or a raise (int).  See ext/carray_cast.c. */
 int   ca_obj2dbl_ok   (VALUE v, double *out);
+int   ca_obj2cmplx_ok (VALUE v, double complex *out);
 int   rb_obj2long_ok  (VALUE v, long *out);
 int   rb_obj2ulong_ok (VALUE v, unsigned long *out);
 int   rb_obj2ll_ok    (VALUE v, long long *out);
@@ -1293,6 +1321,10 @@ VALUE    rb_ca_farray (VALUE self);
 
 /* --- ca_obj_stride.c --- */
 
+/* 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. */
 int       ca_stride_setup (CAStride *ca, int8_t obj_type, CArray *parent,
                            int8_t data_type, ca_size_t bytes,
                            int8_t ndim, ca_size_t *dim,
@@ -1459,6 +1491,7 @@ int     ca_is_object_type (void *ap);
 
 void    ca_check_type (void *ap, int8_t data_type);
 #define ca_check_data_type(ap, data_type) ca_check_type(ap, data_type)
+void    ca_check_uninitialized (void *ap);  /* initialize / initialize_copy entry */
 void    ca_check_ndim (void *ap, int ndim);
 void    ca_check_shape (void *ap, int ndim, ca_size_t *dim);
 void    ca_check_same_data_type (void *ap1, void *ap2);
@@ -1474,7 +1507,7 @@ int     ca_is_valid_index (void *ap, ca_size_t *idx);
 
 /* API : allocate, attach, update, sync, detach */
 
-/* Attach lifecycle contract (R1-R5).  Ownership-based, and NOT transitive.
+/* Attach lifecycle contract (R1-R6).  Ownership-based, and NOT transitive.
    This block is the canonical statement of the contract; the other documents
    copy it.  guides/devel/04_attach_lifecycle.md discusses it at length.
 
@@ -1493,6 +1526,14 @@ int     ca_is_valid_index (void *ap, ca_size_t *idx);
      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.
+     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
+                     called from inside the window) needs an ensure of its
+                     own.
 */
 
 void    ca_allocate (void *ap);
@@ -1500,6 +1541,7 @@ void    ca_attach (void *ca);
 void    ca_update (void *ca);
 void    ca_sync (void *ca);
 void    ca_detach (void *ca);
+void    ca_sync_detach (void *ca);
 
 void    ca_allocate_n (int n, ...);
 void    ca_attach_n (int n, ...);
@@ -1672,6 +1714,7 @@ void    ca_parse_range_without_check (VALUE arg, ca_size_t size,
                         ca_size_t *offset, ca_size_t *count, ca_size_t *step);
 
 int     ca_equal (void *ap, void *bp);
+int     ca_eql_storage (void *ap, void *bp);
 void    ca_zerodiv(void)  __attribute__((noreturn));
 /* ca_rand removed in 3.0; use rb_random_real/rb_random_ulong_limited instead */
 ca_size_t ca_bounds_normalize_index (int8_t bounds, ca_size_t size0, ca_size_t k);