carray 3.0.0 → 3.0.2

data/{NEWS.md → CHANGELOG.v1.md}

@@ -2,7 +2,7 @@ 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.
+What follows is the history up to the 2.0.0 release; 2.0.1 went unrecorded.
 
 1.6.0 -> 2.0.0
 --------------

data/README.md

@@ -1,37 +1,23 @@
 # Ruby/CArray
 
-Ruby/CArray is an extension library for the multi-dimensional array class.
+Ruby/CArray is an extension library for the multi-dimensional array class. It provides arrays of a single, uniform data type, with indexing and slicing in many forms, element-wise arithmetic and mathematical functions, reductions and statistics over the whole array or along any axis, and broadcasting between shapes that differ in size-1 axes. The features listed below are in addition to these.
+
+## Status
+
+3.0.x still moves: behavior can change between releases — see [CHANGELOG.md](CHANGELOG.md). 3.1 is the first release meant to be depended on. Until then, treat it as a place to try things out.
 
 ## 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
+* Every array carries a per-element mask for missing values, respected by reductions and statistics
+* Views compose without copying — a write through the outermost view reaches the source data
+* MemoryView protocol on both sides: share buffers with other numerical libraries without copying
+* Kernel-style iteration: run a Ruby block over each sub-array spanning the axes you choose
+* Attach domain meaning (time, angle, quantity with units…) without changing storage — a Face
+* Define your own array class in pure Ruby while keeping the full CArray interface
+* Pack multiple values into one element as a record type
+* Comes with a DataFrame (`CAFrame`) whose columns are plain CArrays, so masks and views keep working on them
+
+Each of these is shown, briefly and with a runnable example, in [A tour of the features](docs/FeatureTour.md).
 
 ## Install
 
@@ -124,14 +110,28 @@ b.strip_mask(Float::NAN).sum(axis: 0)
 
 ## Documentation
 
-* [What is Ruby/CArray](docs/WhatIsCArray.md)
+* [Introduction](guides/users/introduction.md) — what Ruby/CArray is
+* [Getting started](guides/users/00_getting_started.md) — install, and a first array
+* [Creating arrays](guides/users/01_creating_arrays.md) — constructors, data types, filling
+* [Indexing and slicing](guides/users/02_indexing_and_slicing.md) — elements, rows, blocks, conditions
+* [Indexer reference](guides/users/16_indexer_reference.md) — every form `[]` accepts
+* [Element-wise operations](guides/users/03_elementwise.md) — arithmetic and mathematical functions
+* [Broadcasting](guides/users/07_broadcasting.md) — shapes that differ
+* [Views](guides/users/06_views.md) — referring to data without copying
+* [Reduction and statistics](guides/users/04_reduction_and_statistics.md) — summaries, whole or per axis
+* [Masks and missing values](guides/users/05_masks.md) — undefined elements, and how calculations treat them
+
+## Contributing
+
+Bug reports and feature requests are welcome — please open an issue.
+
+**Before opening a pull request, read [CONTRIBUTING.md](CONTRIBUTING.md).** It is short, and it says which form a contribution is best sent in. A small, self-contained bug fix is fine as a pull request. Anything larger is better started as an issue: code here gets rewritten as a matter of course, so a patch for a larger change is likely to end up reimplemented rather than merged, and describing the problem gets you further than writing one.
 
 ## Credits
 
-Up to version 2.0, CArray was authored by himotoyoshi.
+CArray is created and maintained by himotoyoshi.
 
-CArray 3.0 was designed and reviewed by a human developer; the implementation was
-produced in collaboration with AI coding tools.
+Versions up to 2.0 were written by the author. For version 3.0, the author provided the design, and most of the implementation was rewritten with AI coding tools; it has been verified primarily through the test suite and practical use.
 
 ## License
 

data/carray.gemspec

@@ -1,15 +1,18 @@
 Gem::Specification.new do |s|
   s.name        = "carray"
-  s.version     = "3.0.0"
+  s.version     = "3.0.2"
   s.authors      = ["himotoyoshi"]
   s.email       = ["himotoyoshi@users.noreply.github.com"]
-  s.summary     = "Multi-dimesional array class for Ruby"
+  s.summary     = "Multi-dimensional numerical array class for Ruby"
   s.description = <<-HERE
-    Ruby/CArray is an extension library for the multi-dimensional numerical array
-    class. The name "CArray" comes from the meaning of a wrapper 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.
+    Ruby/CArray adds multi-dimensional numerical arrays to Ruby. Elements are held
+    in a single flat memory block, so whole-array work -- element-wise arithmetic,
+    reductions along any axis, sorting, searching -- runs in C. Slicing, transposing,
+    reshaping, and selecting by a boolean condition all return views that share
+    storage with the original array and can be chained freely; nothing is copied
+    until you ask for a copy. Any array, view included, can carry a mask marking
+    individual elements as undefined, and arrays are exchanged with other numerical
+    libraries without copying through Ruby's MemoryView protocol.
   HERE
   s.homepage    = "https://github.com/himotoyoshi/carray"
   s.license     = "MIT"
@@ -17,13 +20,14 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= 3.0"
   s.files       = [
     *Dir.glob("lib/**/*.rb"),
+    *Dir.glob("yard-stubs/**/*.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",
+    "CHANGELOG.v1.md",
     ".yardopts",
     "carray.gemspec",
   ].select { |f| File.file?(f) }

data/ext/ca_axis_dispatch.c

@@ -339,13 +339,27 @@ ca_axis_dispatch_scatter_cb (ca_size_t off, int oob, ca_size_t n, void *vctx)
 /* Callback context for fill_value (broadcast a single value).  parent is set
    when the value goes through the parent's own fill_stride instead of a
    buffer this side has attached. */
+/* Same size as the window ca_fill_stride_via_addrs collects into. */
+#define CA_AXIS_FILL_ADDR_WINDOW 1024
+
 typedef struct {
   const void *val;
   ca_size_t   bytes;
   char       *parent_ptr;
   CArray     *parent;
+  ca_size_t   window[CA_AXIS_FILL_ADDR_WINDOW];
+  ca_size_t   nw;
 } ca_axis_fill_ctx_t;
 
+static void
+ca_axis_dispatch_fill_flush (ca_axis_fill_ctx_t *c)
+{
+  if ( c->nw ) {
+    ca_fill_addrs(c->parent, c->nw, c->window, (void *) c->val);
+    c->nw = 0;
+  }
+}
+
 static void
 ca_axis_dispatch_fill_value_cb (ca_size_t off, int oob, ca_size_t n, void *vctx)
 {
@@ -354,11 +368,25 @@ ca_axis_dispatch_fill_value_cb (ca_size_t off, int oob, ca_size_t n, void *vctx)
   if ( c->parent ) {
     /* One slab is one contiguous run of parent cells, which is a region the
        parent can fill for itself -- no borrowed buffer, so nothing outside
-       the run is read or written. */
+       the run is read or written.  A run of one cell is not worth a call of
+       its own, though: when the innermost selected axis picks individual
+       indices every run is one cell, and the same cell count that costs the
+       parent eight calls on an outer axis cost it one per cell here.  Collect
+       those and hand them over as a list.  The value is the same for every
+       cell and the walk visits each cell once, so batching cannot change
+       which cells are written. */
     ca_size_t count = n / c->bytes;
-    ca_size_t step  = 1;
-    ca_fill_stride(c->parent, off / c->bytes, 1, &count, &step,
-                   (void *) c->val);
+    if ( count == 1 ) {
+      c->window[c->nw++] = off / c->bytes;
+      if ( c->nw == CA_AXIS_FILL_ADDR_WINDOW ) {
+        ca_axis_dispatch_fill_flush(c);
+      }
+    }
+    else {
+      ca_size_t step = 1;
+      ca_fill_stride(c->parent, off / c->bytes, 1, &count, &step,
+                     (void *) c->val);
+    }
   }
   else {
     ca_axis_dispatch_fill_slab(c->parent_ptr + off, c->val, c->bytes, n);
@@ -895,6 +923,7 @@ ca_axis_dispatch_fill_value_via_parent (CArray          *parent,
   ca_axis_dispatch_for_each_slab(parent, parent_axis_dims, axes, ndim,
                                  bytes, total_elements,
                                  ca_axis_dispatch_fill_value_cb, &ctx);
+  ca_axis_dispatch_fill_flush(&ctx);
 }
 
 /* ==========================================================================