carray 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7f462cc0db93ae6cbe718b64ba1761c4f1aab048835566be238d1f958328c92
-  data.tar.gz: 46289071d0a636d9025de050abeecd1e57223b28dc54bf1acef0e578df3365ce
+  metadata.gz: 7deb551fcc14866b90ad75e9d74ce716922de103148507bcb8b53c039b9afa48
+  data.tar.gz: d8efa03d7f0852a15223329545c5ad3bb0abfcb0c48191978b1e0e6755d50f6b
 SHA512:
-  metadata.gz: f36a13c5ae4a15f264577301683bf03fbc8367f017da1ec39831fe9d8b7161ec0f2721a16909a6d166ca6c784f8062a352f9b1b9f4b4e8135071de27c112579b
-  data.tar.gz: 9cc760bcdb5c9108c7c341b9dd98e12330cf8931cd8ef28d09e603cab984959b287ee9d9e0dc0cb5673e1ad53bd9343ea0e2cf88647ebb81b6b9b557214e9914
+  metadata.gz: d1b4817095544fa7fae956207a3356f3300afab2b3e6b25b2c646e8c52b6db9a3ce9553131bb80ba5899f8d393de9dfd9f8136f1a8224402a372076f74556e89
+  data.tar.gz: 859f3082f6c44a5f340fbf5ddd057e52f2fcacbadf5c5452c117b15faf683c9f915dc1f47ee59ba2fa37fa416fbf050b4747fbb1934971a472e74861c3b32ec4

data/.yardopts

@@ -5,28 +5,8 @@
 --exclude lib/carray/autoload.rb
 --exclude 'lib/carray/autoload/'
 --readme README.md
---files NEWS.md,TODO.md 
-lib/carray.rb 
-ext/ruby_carray.c 
-ext/ca_obj_array.c 
-ext/ca_obj_bitarray.c 
-ext/ca_obj_bitfield.c 
-ext/ca_obj_block.c 
-ext/carray_attribute.c 
-ext/carray_call_cfunc.c 
-ext/carray_cast.c 
-ext/carray_class.c 
-ext/carray_conversion.c 
-ext/carray_copy.c 
-ext/carray_core.c 
-ext/carray_data_type.c 
-ext/carray_element.c 
-ext/carray_generate.c 
-ext/carray_loop.c
-ext/carray_mask.c 
-ext/carray_operator.c 
-ext/carray_order.c 
-ext/carray_sort_addr.c 
-ext/carray_test.c 
-ext/carray_utils.c 
-
+--files CHANGELOG.md,NEWS.md
+lib/carray.rb
+lib/carray/**/*.rb
+yard-stubs/**/*.rb
+ext/carray_operator.c

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+Releases from 3.0.0 onward are recorded here. For the pre-3.0 history
+(1.4.x through 2.0.1) see [NEWS.md](NEWS.md).
+
+## 3.0.0 — 2026-08-25
+
+First public release. Earlier versions existed on RubyGems, but the library
+was developed for the author's own use; 3.0 is where it is packaged,
+documented and tested as something other people can pick up. It is not
+source-compatible with 2.0.1.
+
+See [README.md](README.md) for what the library does, and [docs/](docs/)
+and [guides/](guides/) for the reference and the guides.
+
+**Requires Ruby 3.0 or later** (3.1 for the MemoryView-backed paths).

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2020 Hiroki Motoyoshi.
+Copyright (c) 2005-2026 himotoyoshi.
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/NEWS.md

@@ -1,6 +1,9 @@
 ChangeLog of Ruby/CArray
 ========================
 
+Releases from 3.0.0 onward are in [CHANGELOG.md](CHANGELOG.md).
+What follows is the history up to 2.0.1.
+
 1.6.0 -> 2.0.0
 --------------
 

data/README.md

@@ -1,56 +1,140 @@
-Ruby/CArray
-===========
+# Ruby/CArray
 
 Ruby/CArray is an extension library for the multi-dimensional array class.
 
-Features
---------
+## Features
+
+* Multidimensional arrays holding values of a single, uniform data type
+* Indexing and slicing in many ways — by position, range, boolean mask, or
+  index/address arrays
+* Element-wise arithmetic, mathematical and transcendental functions
+* Reduction and statistics computed over the whole array or along any axis
+* Built-in per-element mask on every array to represent missing values, properly
+  accounted for in reductions and statistics
+* A rich family of views onto the original data — for indexing, reshaping, and
+  reinterpreting elements — without copying
+* Views compose into chains of any depth, and writing through them reaches all the
+  way back to the source data
+* Explicit broadcasting: operating on arrays of different shapes by stretching
+  size-1 axes to match, without ever adding axes implicitly
+* Fast reductions built on compiler auto-vectorization
+* Kernel-style iteration from Ruby: drive a Ruby block over each sub-array spanning
+  chosen axes
+* Faces: a mechanism for building extended data types on top of CArray (time,
+  categorical and variable-length string columns are such types)
+* Easily define record types that bind several data together as one element
+* User-defined array classes, written in Ruby, that share the full CArray interface
+  so your own type behaves like a CArray everywhere
+* A DataFrame (`CAFrame`) whose columns are plain CArrays — it adds names and row
+  operations (select, filter, sort, join, group-by, CSV I/O) and hands a column
+  back as the array itself, so masks, views and Faces keep working on it
+* Writing per-axis methods and functions in C extensions with ease — a single
+  kernel runs across every view type, with no per-view branching to write yourself
+* MemoryView protocol support — interoperate with other numerical libraries as both
+  producer and consumer
+
+## Install
+
+```
+gem install carray
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem "carray"
+```
+
+Requires Ruby 3.0 or later.
+
+On a multi-core machine, parallel `make` cuts install time noticeably:
+
+```
+MAKEFLAGS="-j$(nproc)" gem install carray                     # Linux
+MAKEFLAGS="-j$(sysctl -n hw.ncpu)" gem install carray         # macOS
+```
+
+## Quick example
+
+```ruby
+require "carray"
+
+# --- create a 2x3 array ---
+a = CArray.float64(2, 3) { |i, j| i * 3 + j }
+#  => [ [ 0, 1, 2 ],
+#       [ 3, 4, 5 ] ]
+
+# --- reductions over the whole array or along an axis ---
+a.sum                      #  => 15.0          over the whole array
+a.sum(axis: 0)             #  => [ 3, 5, 7 ]   sum down each column
+a.sum(axis: 1)             #  => [ 3, 12 ]     sum across each row
+
+# --- element-wise operations and functions ---
+a + 1
+#  => [ [ 1, 2, 3 ],
+#       [ 4, 5, 6 ] ]
+
+a.exp
+#  => [ [  1.000,   2.718,   7.389 ],
+#       [ 20.086,  54.598, 148.413 ] ]
+
+# --- select by condition ---
+a[(a % 2).eq(0)]           #  => [ 0, 2, 4 ]   the even elements
+
+# --- views share storage with the original ---
+a.reshape(3, 2)
+#  => [ [ 0, 1 ],
+#       [ 2, 3 ],
+#       [ 4, 5 ] ]
+
+a.transpose
+#  => [ [ 0, 3 ],
+#       [ 1, 4 ],
+#       [ 2, 5 ] ]
+
+a[0, nil]                  #  => [ 0, 1, 2 ]   the first row
+a[nil, 0]                  #  => [ 0, 3 ]      the first column
+
+a[nil, 1..2]               #  a block view of the last two columns
+#  => [ [ 1, 2 ],
+#       [ 4, 5 ] ]
+
+# --- writing through a view updates the original ---
+a[0, nil] = -1
+a
+#  => [ [ -1, -1, -1 ],
+#       [  3,  4,  5 ] ]
+
+# --- missing values ---
+b = CArray.float64(2, 3) { |i, j| i * 3 + j }
+b[0, 1] = UNDEF            #  mark some missing values
+b[1, 2] = UNDEF
+b
+#  => [ [ 0, _, 2 ],
+#       [ 3, 4, _ ] ]
+
+b.sum                      #  => 9            missing values are ignored
+b.sum(axis: 0)             #  => [ 3, 4, 2 ]  (column sums)
+b.sum(axis: 1)             #  => [ 2, 7 ]     (row sums)
 
-* Collection class for multidimensional array storing the value with uniform data type
-* Element-wise mathematical operations and functions
-* Statistical operation for the elements
-* Various methods for referencing data elements
-* Internally included element-wise mask to handle missing values
-* Indirect data manipulation to referent by virtual array 
-* Special iterators (dimension, block, window, categorical)
-* User-defined array class with same multi-dimensional interfaces as CArray
-* Accessing the partial data in fixed length data via data_class interface
-* Wrapping the memory block owned by the other object (such as NArray).
+# the mask is not NaN: dropping it to NaN lets IEEE rules take over instead
+b.strip_mask(Float::NAN).sum(axis: 0)
+#  => [ 3, NaN, NaN ]      NaN propagates rather than being ignored
+```
 
-Requirements
-------------
+## Documentation
 
-* Ruby 2.4.0 or later
-* C compiler 
-  + IEEE754 floating point number
-  + C99 complex number
+* [What is Ruby/CArray](docs/WhatIsCArray.md)
 
-What is Ruby/CArray 
-------------------
+## Credits
 
-Ruby/CArray is an extension library for the multi-dimensional numerical array class. The name "CArray" comes from a wrapper's meaning to a numerical array handled by the C language. CArray stores integers or floating-point numbers in memory block and treats them collectively to ensure efficient performance. Therefore, Ruby/CArray is suitable for numerical computation and data analysis. 
+Up to version 2.0, CArray was authored by himotoyoshi.
 
-#### Multi-dimensional uniform array ####
+CArray 3.0 was designed and reviewed by a human developer; the implementation was
+produced in collaboration with AI coding tools.
 
-CArray is a collection class that can store the array of values with a uniform data type of one of fixed-width integer (8,16,32,64bits), floating-point number (32,64bits), complex number (64,128bits), fixed-length string, ruby object. These values are stored in memory block as binary data. CArray has multi-dimensional interfaces for the array to access their values. The multi-dimensional array has the attributes of the dimension size (1,2,3,...) and the shape of dimension ([dim0], [dim0,dim1], [dim0,dim1,dim2],...) which define the size of array. 
-
-#### Collective mathematical operations ####
-
-CArray supports the collective calculation for the element-wise arithmetic operations and elementary mathematical functions. Additionally, some basic statistical summarization along specific dimensions are also provided.
-
-#### Referencing data and virtual arrays ####
-
-CArray provides various methods for referencing data, such as addressing, slicing, selection by condition, address mapping, grid reference, transposing, shifting, rolling, data type conversion, reshaping, and so on. These data referencing are realized by the creation of virtual arrays, so-called 'view'. The virtual array doesn't have its data and retrieves the data from the referent only on-demand, including dereferencing, copying, or calculation. Since virtual array classes are sub-class of CArray, it has the same interfaces to access data as CArray. The changes in a virtual array by storing data are also reflected in the referent (if not a read_only array). Multiple heterogeneous chains of reference are also allowed, although the trade-offs with performance must be carefully considered.
-
-#### Built-in element-wise mask handling ####
-
-CArray possesses masked states about each element (so-called "element-wise mask"). By referring the element-wise mask, CArray can perform mathematical and statistical calculations on the data with missing values by appropriate handling of masked elements. , which include the propagation of mask state to result in element-wise arithmetics and ignoring the masked elements in a statistical calculation, and so on.
-
-#### User-defined array ####
-
-Users can define a new virtual array class in Ruby level or C-extension level with TemplateMethod pattern. They are defined as a subclass of CAObject in Ruby level and as a subclass of CAVirtual in C-extension level. In particular, at the Ruby level, you can easily define a CArray-like class by implementing just a few template methods.
-
-License
--------
+## License
 
 MIT (after version 1.5.0)
+
+Copyright (C) 2005-2026 himotoyoshi

data/carray.gemspec

@@ -1,19 +1,8 @@
-Gem::Specification::new do |s|
-
-  version = "2.0.1"
-
-  files = Dir.glob("**/*") + [".yardopts"] -
-                             [ 
-                               Dir.glob("carray-*.gem"), 
-                               Dir.glob("ext/**/{Makefile,mkmf.log}"),
-                               Dir.glob("**/*.{o,so,bundle}"),
-                               Dir.glob("**/*~"),
-                               Dir.glob("doc/**/*"),
-                               Dir.glob("test/**/*"),
-                             ].flatten
-
-  s.platform    = Gem::Platform::RUBY
+Gem::Specification.new do |s|
   s.name        = "carray"
+  s.version     = "3.0.0"
+  s.authors      = ["himotoyoshi"]
+  s.email       = ["himotoyoshi@users.noreply.github.com"]
   s.summary     = "Multi-dimesional array class for Ruby"
   s.description = <<-HERE
     Ruby/CArray is an extension library for the multi-dimensional numerical array
@@ -22,13 +11,22 @@ Gem::Specification::new do |s|
     memory block and treats them collectively to ensure efficient performance.
     Therefore, Ruby/CArray is suitable for numerical computation and data analysis.
   HERE
-  s.version     = version
-  s.author      = "Hiroki Motoyoshi"
-  s.email       = ""
-  s.license     = 'MIT'
-  s.homepage    = 'https://github.com/himotoyoshi/carray'
-  s.files       = files
-  s.extensions  = [ "ext/extconf.rb" ] 
-  s.required_ruby_version = ">= 2.4.0"
+  s.homepage    = "https://github.com/himotoyoshi/carray"
+  s.license     = "MIT"
+  s.platform    = Gem::Platform::RUBY
+  s.required_ruby_version = ">= 3.0"
+  s.files       = [
+    *Dir.glob("lib/**/*.rb"),
+    *(Dir.glob("ext/*.c") - %w[ext/carray_kernels.c ext/carray_cast_func.c ext/carray_math.c]),
+    *Dir.glob("ext/*.h"),
+    *Dir.glob("ext/*.rb"),
+    "LICENSE",
+    "README.md",
+    "NEWS.md",
+    "CHANGELOG.md",
+    ".yardopts",
+    "carray.gemspec",
+  ].select { |f| File.file?(f) }
+  s.extensions  = ["ext/extconf.rb"]
+  s.require_paths = ["lib", "ext"]
 end
-

data/ext/ca_array_pool.c

@@ -0,0 +1,91 @@
+/* ---------------------------------------------------------------------------
+
+  CArray pool framework primitives.  Collapses the per-class
+  `dim` / `strides` / per-view-tail metadata allocations into a
+  single `_pool` buffer, owned by the CArray struct and freed in
+  one xfree.  Reduces the number of xmalloc / xfree pairs per
+  CArray lifecycle and keeps the metadata cache-adjacent.
+
+  Primary motivation: CABlock and CAWindow view creation.  Those
+  two carry the most per-instance metadata (dim + strides + per-
+  axis tail), so consolidating their allocations into one pool
+  buffer roughly doubles clone throughput.  Other view types and
+  entities adopted the same primitives for uniform alloc/free
+  discipline; the perf gain on those is modest.
+
+  Internal C API (no Ruby surface, no Init function).  Three
+  entry points:
+
+    ca_array_alloc       struct + pool in one allocation; used by
+                         the C `*_new` constructors that build a
+                         CArray from C without a Ruby wrapper.
+    ca_array_pool_alloc  pool only; used by `*_initialize_copy`
+                         where TypedData_Make_Struct has already
+                         allocated the C struct.
+    ca_array_free        frees both struct and pool; dispatched
+                         from per-class free callbacks.
+
+  Per obj_type, two function-pointer hooks are registered into
+  `ca_func[obj_type]`: `pool_bytes(ndim)` computes the pool size,
+  and `pool_init(ca, ndim)` wires the struct's `dim` / `strides` /
+  tail pointers into the freshly allocated pool.  See the per-view
+  Init_* setup for examples.
+
+  Mixed dispatch: an obj_type that has not yet registered the pool
+  hooks falls through to its legacy per-field ALLOC_N path
+  (`ca->_pool == NULL`); existing CArrays from such classes continue
+  to free correctly because `ca_array_free` is a no-op when
+  `_pool` is NULL.  This kept the migration incremental and
+  remains safe in mixed object-graph scenarios.
+
+  See devel/PROPOSAL_CARRAY_POOL_STANDARDIZATION.md for the design.
+
+---------------------------------------------------------------------------- */
+
+#include "carray.h"
+#include <string.h>
+
+/* Allocate struct + pool in one shot, then run pool_init.
+ *
+ * Called by per-class C `*_new` constructors. */
+void *
+ca_array_alloc (int8_t obj_type, int8_t ndim)
+{
+  ca_operation_function_t *func = &ca_func[obj_type];
+  CArray *ca = xmalloc(func->struct_size);
+  memset(ca, 0, func->struct_size);
+  ca_array_pool_alloc(ca, obj_type, ndim);
+  return ca;
+}
+
+/* Allocate just the _pool buffer and run pool_init.  The C struct
+ * itself is assumed already allocated (e.g. by TypedData_Make_Struct
+ * via `*_s_allocate`).
+ *
+ * Called by per-class `*_initialize_copy` and by ca_array_alloc above. */
+void
+ca_array_pool_alloc (void *ap, int8_t obj_type, int8_t ndim)
+{
+  CArray *ca = (CArray *) ap;
+  ca_operation_function_t *func = &ca_func[obj_type];
+  ca->ndim  = ndim;
+  ca->_pool = xmalloc(func->pool_bytes(ndim));
+  func->pool_init(ca, ndim);
+}
+
+/* Free struct + pool in one shot.  Safe when `ca->_pool == NULL`
+ * (the pool xfree is skipped, the struct xfree always runs); this
+ * lets the per-class free callback dispatch here uniformly whether
+ * or not its obj_type has migrated to pool registration.
+ *
+ * Called by per-class free_* callbacks (= `func->free_object`). */
+void
+ca_array_free (void *ap)
+{
+  CArray *ca = (CArray *) ap;
+  if (ca->_pool) {
+    xfree(ca->_pool);
+    ca->_pool = NULL;
+  }
+  xfree(ca);
+}

data/ext/ca_axis_descriptor.h

@@ -0,0 +1,186 @@
+/* ---------------------------------------------------------------------------
+
+  ca_axis_descriptor.h
+
+  Per-axis descriptor framework (D1 + D2 + D3) — shared C-level vocabulary
+  that lets CSA, CAGrid, CASelectAxis, CAWindow, CAShift, and future
+  per-axis-mixed views describe each axis the same way so a common
+  attach dispatch engine (D3, ca_axis_dispatch.c) can drive them
+  uniformly.
+
+  See devel/PROPOSAL_AXIS_DESCRIPTOR_FRAMEWORK.md for the design.
+
+  Status: TWO-TIER FREEZE CONTRACT (3.0 onward), the same split
+  ca_kernel_iterator.h declares, for the same reason: this header is
+  installed and reachable from `#include "carray.h"`, so what it declares
+  is visible to downstream gems whether or not they were meant to use it.
+
+    FROZEN (additions only; renaming or re-laying-out is a 3.x break):
+      - ca_axis_kind_t and the layout of ca_axis_desc_t
+
+      Not because view authors were invited to build descriptors, but
+      because ca_iter_state -- whose slab-delivery fields ARE frozen
+      author contract -- embeds ca_axis_desc_t descs[CA_RANK_MAX] by
+      value.  The type is already part of that struct's layout, so it
+      cannot move or shrink without breaking kernels that were promised
+      stability.  It is frozen by consequence, not by invitation.
+
+    INTERNAL (free to change across 3.x; no downstream contract):
+      - every function below: ca_axis_dispatch_gather / _attach /
+        _scatter / _fill_value / _fill_value_via_parent, and the
+        ca_*_describe_axes producers
+
+      An external obj_type cannot participate in this engine anyway:
+      ca_iter_register_source_kind accepts CA_ITER_SRC_ATTACH only and
+      raises on CA_ITER_SRC_DESCRIPTOR, precisely because the engine
+      looks describe_axes up in its own table and an external type has no
+      way to supply one.  A contract nobody outside can invoke is a
+      contract not worth keeping, so these stay free to move.
+
+  In-tree consumers (ca_obj_grid.c, ca_obj_select.c, ca_obj_select_axis.c,
+  ca_obj_window.c, ca_iter_substrate.h, ca_kernel_iterator.c) pick this up
+  transitively from carray.h without an explicit include.
+
+  --------------------------------------------------------------------------- */
+
+#ifndef CA_AXIS_DESCRIPTOR_H
+#define CA_AXIS_DESCRIPTOR_H 1
+
+/* Depends on int8_t / uint8_t / ca_size_t typedefs from carray.h.
+   When this header is included from carray.h mid-file, those typedefs
+   are already in scope by the time we reach the include site. */
+
+/* ---- D1: per-axis descriptor types ----------------------------------------
+
+   STRIDE = linear stride axis: parent index = start + i*step,
+            i in [0, count).  Subsumes nil / Integer / Range index args.
+   INDEX  = integer index axis:  parent index = indices[i],
+            i in [0, count).  Subsumes integer-array (CAGrid)
+            and boolean-mask-after-snapshot (CASelectAxis) axes.
+   SHIFT  = bound-aware stride axis (CAWindow/CAShift, Tier 2.B):
+            parent index = start + i*step normalised by `policy`
+            (CA_BOUNDS_FILL / PERIODIC / REFLECT / NEAREST / ...)
+            against `size0` (= parent dim along this axis).  When
+            normalisation fails (still out of range, e.g. FILL
+            policy), the engine writes `bound_fill` to the gather
+            buffer (or skips the parent write on scatter). */
+typedef enum {
+  CA_AXIS_KIND_STRIDE = 0,
+  CA_AXIS_KIND_INDEX  = 1,
+  CA_AXIS_KIND_SHIFT  = 2
+} ca_axis_kind_t;
+
+typedef struct {
+  ca_axis_kind_t  kind;
+  ca_size_t       count;     /* output size contributed by this axis */
+  /* STRIDE / SHIFT fields (unused / undefined when kind == INDEX) */
+  ca_size_t       start;
+  ca_size_t       step;
+  /* INDEX-only field (unused / NULL when kind != INDEX).
+     Ownership: borrowed from the producer view; lifetime tied to
+     the view that produced the descriptor array.  Consumer (D3
+     dispatch) must not free or mutate. */
+  ca_size_t      *indices;
+  /* SHIFT-only fields (unused / undefined when kind != SHIFT) */
+  ca_size_t       size0;     /* parent dim along this axis (bounds check) */
+  uint8_t         policy;    /* CA_BOUNDS_FILL / PERIODIC / REFLECT / ... */
+} ca_axis_desc_t;
+
+/* ---- D2: producer interface ----------------------------------------------
+
+   Both implementations write ndim entries into `out` (caller-allocated)
+   and `out_parent_dims` (caller-allocated, sized CA_RANK_MAX).  See
+   devel/PROPOSAL_AXIS_DESCRIPTOR_FRAMEWORK.md §5 Framework Phase 1 and
+   devel/PROPOSAL_FLAT_INDEX_VIEWS.md §2.3 for rationale.
+
+   `out_parent_dims[k]` is the **effective** parent dim along descriptor
+   axis k — for CSA / CAGrid this is just `parent->dim[k]`, but for
+   flat-index views (CASelect / CAMapping, Tier 2.A.3+) it is
+   `{parent->elements}` (a single-axis flat view of parent).  This
+   decouples descriptor.ndim from parent.ndim so the engine can drive
+   views whose iteration axes don't match the parent's physical shape.
+
+   Pointer arguments are typed `void *` here to avoid pulling the
+   private CASelectAxis / CAGrid struct definitions (which live in
+   their respective .c files) into this header.  Each implementation
+   casts to its concrete type inside the .c file. */
+void ca_select_axis_describe_axes (void *ca, ca_axis_desc_t *out,
+                                   ca_size_t *out_parent_dims);
+void ca_grid_describe_axes        (void *ca, ca_axis_desc_t *out,
+                                   ca_size_t *out_parent_dims);
+
+/* ---- D3: common attach engine --------------------------------------------
+
+   Drives gather from `parent` into an output buffer driven by the
+   per-axis descriptor array.  Caller must have parent attached before
+   invoking.
+
+   `parent_axis_dims[ndim]` carries the effective parent dim per
+   descriptor axis (see producer interface above).  The engine never
+   reads `parent->dim` directly — it only reads `parent->ptr` for
+   data access — which is what allows flat-index views to lie about
+   parent's apparent shape (Tier 2.A, PROPOSAL_FLAT_INDEX_VIEWS.md).
+
+   `bound_fill` is the bytes-wide value written into gather output
+   cells whose SHIFT axes resolve to an out-of-bounds parent index
+   (Tier 2.B, PROPOSAL_BOUND_AWARE_VIEWS.md).  Pass NULL when no
+   SHIFT axis is present (CSA / CAGrid / CASelect / CAMapping); the
+   engine ignores it.  On scatter, the engine simply skips parent
+   writes for OOB cells regardless of bound_fill.
+
+   _gather — caller provides out_buf (must be sized total_elements*bytes)
+   _attach — wrapper that mallocs the buffer; caller xfrees
+
+   Returns a 1-byte placeholder when total_elements == 0 (the
+   _attach variant); _gather becomes a no-op in that case.
+
+   Forward-declare struct _CArray so these declarations can sit in a
+   stand-alone header without dragging in the full CArray definition. */
+struct _CArray;
+void  ca_axis_dispatch_gather  (struct _CArray  *parent,
+                                const ca_size_t *parent_axis_dims,
+                                ca_axis_desc_t  *axes,
+                                int8_t           ndim,
+                                ca_size_t        bytes,
+                                ca_size_t        total_elements,
+                                const void      *bound_fill,
+                                char            *out_buf);
+char *ca_axis_dispatch_attach  (struct _CArray  *parent,
+                                const ca_size_t *parent_axis_dims,
+                                ca_axis_desc_t  *axes,
+                                int8_t           ndim,
+                                ca_size_t        bytes,
+                                ca_size_t        total_elements,
+                                const void      *bound_fill);
+void  ca_axis_dispatch_scatter (struct _CArray  *parent,
+                                const ca_size_t *parent_axis_dims,
+                                ca_axis_desc_t  *axes,
+                                int8_t           ndim,
+                                ca_size_t        bytes,
+                                ca_size_t        total_elements,
+                                const char      *in_buf);
+/* Broadcast scatter: write the single value `val` (bytes wide) into
+   every selected parent cell.  See D6 of the framework piece.
+   (SHIFT axis OOB cells are skipped — fill semantics aren't
+   meaningful for broadcast-write since the destination value already
+   IS the broadcast value.) */
+void  ca_axis_dispatch_fill_value (struct _CArray  *parent,
+                                   const ca_size_t *parent_axis_dims,
+                                   ca_axis_desc_t  *axes,
+                                   int8_t           ndim,
+                                   ca_size_t        bytes,
+                                   ca_size_t        total_elements,
+                                   const void      *val);
+
+/* As above, but each slab is handed to the parent as a region of its own via
+   ca_fill_stride, so a parent that has to be materialised to be addressed is
+   never gathered and written back whole to set the cells this view selected. */
+void  ca_axis_dispatch_fill_value_via_parent (struct _CArray  *parent,
+                                              const ca_size_t *parent_axis_dims,
+                                              ca_axis_desc_t  *axes,
+                                              int8_t           ndim,
+                                              ca_size_t        bytes,
+                                              ca_size_t        total_elements,
+                                              const void      *val);
+
+#endif /* CA_AXIS_DESCRIPTOR_H */