carray 2.0.1 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7f462cc0db93ae6cbe718b64ba1761c4f1aab048835566be238d1f958328c92
-  data.tar.gz: 46289071d0a636d9025de050abeecd1e57223b28dc54bf1acef0e578df3365ce
+  metadata.gz: 3fd3c3099973bb94e29628f609cf27b65ccd9f318a5a707273fd86586e89e9a2
+  data.tar.gz: c9a01c64bc228fd8c4e92d2ef01043678608fa31f68a2a357f3ace5bf9f8b7af
 SHA512:
-  metadata.gz: f36a13c5ae4a15f264577301683bf03fbc8367f017da1ec39831fe9d8b7161ec0f2721a16909a6d166ca6c784f8062a352f9b1b9f4b4e8135071de27c112579b
-  data.tar.gz: 9cc760bcdb5c9108c7c341b9dd98e12330cf8931cd8ef28d09e603cab984959b287ee9d9e0dc0cb5673e1ad53bd9343ea0e2cf88647ebb81b6b9b557214e9914
+  metadata.gz: 84056c479f21558ffac49f051d4efdd6d34f4e7fa18218f097ab7ecabc3a7791782060358605c26265a90928ae2911253e5f6f6ca31acd3b70f3e069b5001bf5
+  data.tar.gz: a20917afb47f7c2ed0e3968678bd834680f41ceacf05d2c3771729d381ba7cb9a93c8e89aeca9f609a5811b9168b33fc446c1bd0cedc28c590c65eb02b070e2d

data/.yardopts

@@ -1,32 +1,13 @@
 --markup markdown
+--output-dir .yard-html
 --markup-provider redcarpet
 --no-private
 --exclude lib/carray/obsolete.rb
 --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,CHANGELOG.v1.md
+lib/carray.rb
+lib/carray/**/*.rb
+yard-stubs/**/*.rb
+ext/carray_operator.c

data/CHANGELOG.md

@@ -0,0 +1,338 @@
+# Changelog
+
+Releases from 3.0.0 onward are recorded here. There is no separate NEWS
+file: this is where to look for what changed between the version you have
+and a newer one. The 1.x history, up to the 2.0.0 release, is in
+[CHANGELOG.v1.md](CHANGELOG.v1.md); 2.0.1 went unrecorded.
+
+<!-- Newest first, at both levels: a new release section goes above the
+     ones below it, and a new entry goes directly under its own release
+     heading -- not at the end of the section. The kind of change is
+     carried by the `- Fix:` / `- Change:` / `- New:` that opens the
+     entry; there are no per-kind subheadings.
+
+     A section is written newest-first while the release is open, and
+     sorted into New, Change, Fix when it closes -- in the same commit
+     that drops `(unreleased)`. Within Change, the ones that ask the
+     reader to change code come first. It is a reading order rather than
+     a classification: where it is not obvious, either place will do.
+
+     An entry says three things and stops: what changed, what to do about
+     it (the migration, the replacement, the condition under which nothing
+     changes), and what is excluded. It does not say how the code was
+     broken, name the internals that were fixed, break down where the
+     speed came from, or argue the design -- those belong in the commit
+     message. Two to six lines.
+
+     It is written for someone using the library, not someone working on
+     it: with no NEWS file, this is what a reader consults before
+     upgrading. An entry naming something only a C extension touches says
+     so in its opening words.
+
+     Every entry has to read on its own. Entries are looked at one at a
+     time and move about within a section, so none may lean on a
+     neighbour ("as well", "the producer above") or leave unnamed the
+     method, class or keyword it is about. -->
+
+## 3.0.1
+
+- New: `CArray.jit_for`, `CArray.jit_each` and `CArray.jit_map` name a block
+  that is compiled rather than run. Compiling needs the carray-jit gem;
+  without it they raise `NotImplementedError`. An expression over whole
+  arrays wants `CArray.fuse`, which needs no compiler.
+
+- New: every iterator answers `accumulate` beside `sum`; some of them did not.
+  It is the same fold kept in the source's own data type, where `sum` answers
+  in the type the core promotes to -- a window or tile count over `uint8` cells
+  stays one byte wide.
+
+- New: `CArray::CoreExtensions` adds postfix math on `Complex`, so `a[0].tanh`
+  reads the way `a.tanh` does. It covers the seventeen functions a complex
+  array supports and agrees with the array form exactly, branch cuts and the
+  sign of a zero included. Opt in with `using CArray::CoreExtensions`.
+
+- New: `ca_is_stride_family(ca)` in `carray.h`, for a C extension that folds a
+  view into `root->ptr + base + sum(idx[k] * strides[k])` itself. True for
+  CAStride, CARefer, CABlock, CARepeat, CATranspose, CAFarray and CAField and
+  the mask array of each, and for an externally installed view that shares
+  their operation table.
+
+- New: `divmod` returns `[quotient, remainder]` element-wise with the quotient
+  floored, the pair Ruby's `Integer#divmod` and `Float#divmod` return. The
+  quotient keeps the receiver's data type.
+
+- New: two optional CAObject callbacks take a partial fill as a region instead
+  of one `store_addr` per cell: `fill_block(starts, counts, steps, val)` for a
+  forward per-axis sub-region, `fill_addrs(addrs, val)` otherwise. Defining
+  neither keeps the old behaviour. Filling a 1000x1000 region of a 2000x2000
+  CAObject: 116 ms to 0.6 ms.
+
+- New: `CAFrame#to_table` renders the frame as an aligned text table, and
+  `inspect` / `to_s` sit on it: `p df` summarises the first 8 and last 2 rows,
+  `puts df` prints the whole frame. `rows:` caps the printed rows, `precision:`
+  rounds float cells for display (default 6), masked cells show as `_`.
+
+- New: `CAFrame#to_time` takes a `CATime::Grid`, positionally or as `unit:`, so
+  a netCDF `units` attribute goes in whole. The grid also carries an epoch phase
+  the `unit:` / `epoch:` pair cannot -- that pair reads the epoch on the coarse
+  grid and loses the time of day. The keyword form is unchanged.
+
+- New: `CATime::Grid` packages the `(unit:, origin:)` pair that `#timesteps`,
+  `#snap` and `.from_timesteps` take, so it is built once and passed as one
+  value: `t.snap(g, direction: :floor)`, `t.timesteps(g)`, `g.at(k)`. It parses
+  and prints the udunits `"<unit> since <instant>"` form, holding a phased
+  origin that the keyword pair cannot (`"12 hours since 2017-11-30 09:00"`).
+  `CATime#grid` is the grid an array is stored on. Storage is unchanged.
+
+- New: `CATime#snap(grid, direction:)` rounds to a tick grid, the shape
+  `CArray#snap` has for numbers. `#floor` / `#ceil` / `#round` are its
+  fixed-direction forms; their results and keyword forms are unchanged.
+
+- New: a time element is taken directly as a start or origin literal, so a
+  `floor` / `ceil` / `to_unit` answer feeds back into `CArray.time`,
+  `time_range`, `time_series`, `CArray#time` and an `origin:`; it used to have
+  to go out through `DateTime` and be re-parsed. A `:M` or `:Y` element names
+  the first midnight of its granule. What an origin must satisfy is unchanged.
+
+- New: `CArray.time` parses a year-month (`"2019-09"`) and a bare year
+  (`"2019"`), so the form a `:M` / `:Y` element prints reads back in. A
+  missing finer field names the head of that period.
+
+- Change: `abs`, `abs2` and `arg` on a `cmplx64` array now return `float32`
+  instead of `float64` -- the width that type carries its real values in, the
+  same one `real` and `imag` already returned. `arg` on a `float32` array
+  likewise returns `float32` rather than widening. `cmplx128` and `float64`
+  are unchanged, and `arg` on an integer array still gives `float64`. To keep
+  the old width, add `.to_type(:float64)`.
+
+- Change: `CArray.fuse` takes the expression rather than the arrays it is
+  over -- `CArray.fuse { (a + b) * c }` in place of
+  `CArray.fuse(a, b, c) { |x, y, z| (x + y) * z }`. What comes back is the
+  expression, so `x = CArray.fuse { ... }` now wants `.to_ca` for an array.
+  Where the block's source cannot be read -- an `irb` prompt, inside `eval` --
+  write `a.lazy + b.lazy`. `CArray.lazy(*args) { ... }` is gone.
+
+- Change: a lazy expression (`a.lazy + b`, `CArray.fuse`) builds its mask when
+  something reads it, rather than when the expression is built. A mask set on
+  either operand after the expression was built is now seen; before, only the
+  left one was. `root_array` and `ancestors` now stop at a lazy operation
+  instead of walking into its left operand. Building a long masked expression
+  is also no longer quadratic in the length of the chain.
+
+- Change: the top-level constant `CA_NIL` is now `CArray::UNSPECIFIED`
+  (`CA_UNSPECIFIED` in C). It is an internal sentinel for "the caller gave no
+  argument", not a value to pass in; `unmask`, `shift(fill_value:)` and
+  `window(fill_value:)` behave as before.
+
+- Change: `group_by_category` reductions answer in the data type the core
+  reduction promotes the value to, instead of one chosen per reduction. `sum`
+  on an integer value now answers in float64 (`accumulate` is the spelling
+  that stays in the value's type), and `mean`, `variance` and `median` on an
+  object value stay exact. `sum` on a boolean value and `prod` or `mean` on a
+  complex one, which raised, now work.
+
+- Change: the `:*` unbound repeat is retired. `a[:*, nil]` raises `IndexError`;
+  `CArray#unbound_repeat`, `CAUnboundRepeat` and `insert_axis(repeat: :*)` are
+  gone. Use `:_`, which gives the same shape and now stretches on a store as
+  well as in an operation. `CArray#broadcast_to` and
+  `CArray.meshgrid(sparse: true)` are unaffected.
+
+- Change: a binary operation requires shapes to agree, or to differ only in
+  size-1 axes at equal ndim. `(3,2) + (2,3)` and `(3,2) + (6)` raise
+  `ArgumentError` where they used to answer in one operand's shape; flatten
+  both sides to combine the values in the order they lie. Comparisons, `fma`
+  and the lazy forms follow the same rule. Scalars are unaffected, but a
+  one-element 1-D array such as `CArray.int32(1)` counts as a shape.
+
+- Change: an assignment requires the shapes to match. `t[] = src` with a
+  differently shaped source raises `RuntimeError`; use `src.flatten`. In
+  exchange a smaller source is repeated to fit, so `t[] = row[:_, nil, nil]`
+  and `t[] = col` (shape `(n,1)`) work where they used to raise. A 1-D side on
+  either end still passes, as do shapes differing only in size-1 axes; Ruby
+  Arrays and scalars are unchanged.
+
+- Change: `to_ca` on a view derived from a lazy marker returns a new entity
+  rather than the view itself -- `a.lazy.shift(1, 0).to_ca`, inside a `fuse`
+  block or not. `copy` behaves as before.
+
+- Change: `/` and `%` follow Ruby instead of C. Integer division floors and the
+  remainder carries the sign of the divisor; float `%` floors too, float `/` is
+  unchanged. For the old behaviour use `fmod`, which now takes integers as well
+  as floats.
+
+- Change: `reminder` is removed -- it was IEEE 754 remainder on floats but C `%`
+  on integers. Use `fmod` for the truncated remainder. The IEEE form has no
+  replacement.
+
+- Change: the result-type override of `CArray#conditional` and
+  `CArray.select` is now `data_type:`, spelled the way the rest of the
+  library spells it. There is no alias: `dtype:` raises `unknown keyword`.
+
+- Change: a calendar-grid `origin:` given to the bucket-grid methods of a
+  `CATime` array -- `timesteps`, `snap`, `floor`, `ceil`, `round`,
+  `is_righttime` -- now has to be a month head (the 1st at 00:00); it used to
+  drop the day and time silently. A `:Y` tick likewise has to start in
+  January. `from_timesteps` already refused an off-grid origin.
+
+- Change: the MemoryView producer emits the format vocabulary
+  `ruby/memory_view.h` specifies rather than PEP 3118's, so below 32 bits it
+  writes `c` / `C` / `s` / `S` in place of `b` / `B` / `h` / `H`. From 32 bits
+  up the two already agreed, and `?`, `Zf` / `Zd`, `T{...}` and `Ns` stay PEP
+  3118, which Ruby has no spelling for. The consumer side already accepted
+  both, so views produced by 3.0.0 still import.
+
+- Change: multiplying and dividing a `cmplx64` array (`*`, `/`, `rcp`,
+  `rcp_mul`) is computed in double and rounded once, so both are correctly
+  rounded; the old route could be off by about 1800 units in the last place.
+  A product that overflows a float but not a double no longer comes back NaN.
+  Division is 4.2-5.3x faster and multiplication 1.3x slower. `+`, `-` and
+  every `cmplx128` operation are unchanged.
+
+- Change: element-wise math on a `float32` or `cmplx64` array is computed at
+  that width rather than widened and rounded back, so `sqrt`, `exp`, `log`,
+  the trigonometric and hyperbolic families, `atan2`, `hypot`, `abs` and `arg`
+  are 1.1-3.5x faster there and can move by a bit or two in the last place.
+  Complex `log`, `power`, `exp2` and `exp10` are unchanged, as are the
+  rounding, min / max, comparison and variance families and the wider types.
+
+- Change: a rolling `sum`, `mean`, `prod`, `min`, `max`, `all` or `any` --
+  `a.windows(-1..1).sum` and the like -- over a window up to five cells wide on
+  every axis is 2-5x faster, and 1.3-4x over a masked source; `min_count:` and
+  `fill_value:` come along. `min`, `max` and `prod` answer exactly as before;
+  `sum` and `mean` may differ in the last bits. A wider window, or any other
+  reduction, is unchanged.
+
+- Change: `CATime#to_unit` floors to a coarser grid instead of raising, and
+  crosses the calendar / fixed-length boundary (`:M` <-> `:D`) through
+  civil-date algebra. `:Y` / `:M` -> `:W` still raises.
+
+- Change: `CATimedelta#to_unit` truncates toward zero instead of raising on a
+  coarser target. Crossing the calendar boundary still raises.
+
+- Fix: `nextafter` on a `float32` array returned its own input. The step was
+  taken in double, and the next double above a float rounds back to that same
+  float. It now steps by one float32 ulp.
+
+- Fix: a lazy expression over an object array (`CArray.object`,
+  `CA_OBJECT`) returned wrong values, and crashed when materialised
+  repeatedly. Affects `to_ca` and `copy` on a lazy view, an eager operation
+  with a lazy operand, and a reduction over one. Other data types were never
+  affected.
+
+- Fix: reading a concatenated view (`CArray.concat`, `CAFrame.concat`)
+  backwards along the concatenated axis -- `m.reverse` and any other negative
+  step -- raised IndexError instead of answering.
+
+- Fix: reading a lazy expression (`a.lazy + b`, `CArray.fuse`) with a step
+  other than one -- `expr[[0, 3, 2]]`, `expr.reverse` and the like -- returned
+  values the expression cannot produce, because its operands were read from
+  the wrong cells. Comparisons carried the same fault, `a.lazy > b` and
+  one-operand ones such as `a.lazy.is_nan` alike. Contiguous reads were never
+  affected.
+
+- Fix: `a.value + b` raised `can not create mask array for the value array`
+  when `b` carried a mask. It now propagates `b`'s mask.
+
+- Fix: a rolling window that does not cover the cell it is centred on --
+  `windows(1..2)`, the two cells after this one -- was read as if it started at
+  the array's edge, so every answer came out shifted by the range's start, and
+  `bounds: :truncate` produced anchors whose window did not fit. `windows(1..2)`
+  on `[1..8]` now sums to `[5, 7, 9, 11, 13, 15, 8, 0]`. A window that covers
+  its anchor, which is every centred one, is unaffected.
+
+- Fix: storing a `Complex` into a `cmplx64` or `cmplx128` array kept the sign
+  of a negative zero real part only when the imaginary part was also negative,
+  so `Complex(-0.0, 0.0)` came back as `0.0+0.0i`. The sign of a zero picks the
+  side of a branch cut, so a value stored this way could be carried to the
+  wrong branch. All four sign combinations now round-trip, through element
+  assignment and through `to_type`.
+
+- Fix: `sinh`, `cosh`, `tanh`, `asinh`, `acosh` and `atanh` on a complex array
+  gave the hyperbolic function of the real part alone: `cmplx128` and
+  `cmplx64` arrays came back with `tanh(Re z)` where `ctanh(z)` was meant,
+  wrong in both parts, and `acosh` and `atanh` also returned 0 or infinity
+  where the true value is finite. They now agree with C99 `complex.h`. Real
+  and object arrays were never affected.
+
+- Fix: a C extension reading a view in column-major order -- axes and steps
+  reversed against the view's own -- got wrong values from a view with a
+  length-1 axis, such as `v[nil, :_]`, `v.reshape(n, 1)` or a one-column slice:
+  the first cell repeated, a read out of bounds, or a hang.
+  `carray-linalg-accelerate`'s `solve(a, b)` returned `b[0]` repeated for a
+  single-column right-hand side.
+
+- Fix: an operation between two views of an array that computes its values --
+  a lazy expression such as `(a.lazy + b)`, or a `CAObject` over a file -- no
+  longer reads that source one cell at a time. `+`, `fma` and comparisons on
+  such a pair now run at the speed of copying each operand first, so the
+  `.copy` that worked around it is no longer needed. Single-operand
+  operations, copies, region transfers and reductions were already unaffected.
+
+- Fix: views built inside a `CArray.fuse` block stay part of the expression
+  instead of dropping out of it, so a stencil written the natural way is fused.
+  `[]`, `shift`, `roll`, `flip`/`reverse`, `transpose`/`T`, `reshape`,
+  `flatten`, `window`, `diagonal`, `tile` and `refer` keep the chain;
+  `unbound_repeat` and `[:*, ...]` deliberately do not.
+
+- Fix: a window or shift over a view parent no longer copies that parent in
+  full on every transfer. `a[nil, nil].shift(1, 0)` and friends now read at
+  parity with an entity parent and write several times faster.
+
+- Fix: reductions over a bare `.lazy` marker no longer raise. Per-axis forms
+  and anything over a masked array failed, so `a.lazy.sum(axis: 0)` raised
+  while `a.lazy.sum` worked.
+
+- Fix: `ca_test_flag` / `ca_set_flag` / `ca_unset_flag` in `carray.h`, which
+  only a C extension calls, did not parenthesise their flag argument, so
+  testing two flags at once was true for every array.
+
+- Fix: a Face no longer hands back its storage bytes through the type casts.
+  `as_type`, `fake` and `CArray.wrap_writable` raise; `CArray.wrap_readonly`
+  converts as `to_type` does, which also makes `t.eq(o)` and `o.eq(t)` agree.
+  Reach the storage explicitly with `t.parent.fake(...)`. Numeric Faces are
+  unaffected.
+
+- Fix: `arange` raised `NoMethodError` in every form; it builds the array now.
+  Integer arguments count exactly, so a step dividing the span evenly no longer
+  picks up an extra element. A zero step or a wrong argument count raises
+  `ArgumentError`.
+
+- Fix: `from_timesteps` on a week grid answered Thursdays. The week grid counts
+  from the epoch, which is one, so it cannot hold an ISO Monday head; a week
+  bucket now answers on the day grid and round-trips against `floor` cell for
+  cell. A day-or-finer array keeps the Monday default, a week-stored array its
+  own epoch-anchored ticks.
+
+- Fix: a masked cell decided whether a `CATime` conversion fit. The range
+  guards took their extremes with the mask stripped, so `to_unit` raised
+  `RangeError` over a wide value that was masked out. They now answer UNDEF
+  when there is nothing to bound -- an empty array, or every cell masked.
+
+- Fix: `CATimedelta::Element#/` floored a negative duration, so `-30h / 4`
+  answered `-8h` where the array form answered `-7h`. A duration is a
+  magnitude, so it shrinks toward zero, matching the array form in all four
+  sign combinations.
+
+- Fix: `CArray.time` no longer rolls a field that is out of range over into
+  another date. `"2019-02-31"` parsed to 2019-03-03, and `"201909"` -- a valid
+  YYMMDD to Ruby, 2020-19-09 -- to 2021-07; both now raise.
+
+- Fix: `CATime#to_unit` and `CATimedelta#to_unit` were wrong between two
+  resolutions where neither tick is a whole multiple of the other: converting
+  3 hours to a `"90 minutes"` grid gave 1 unit rather than 2.
+
+- Fix: importing a MemoryView whose mask is published as `C` or `c` no longer
+  fails. The check knew only PEP 3118's `B`, `b` and `?`, so a producer that
+  spells a byte in Ruby's format vocabulary was refused.
+
+## 3.0.0
+
+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/{NEWS.md → CHANGELOG.v1.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 the 2.0.0 release; 2.0.1 went unrecorded.
+
 1.6.0 -> 2.0.0
 --------------
 

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/README.md

@@ -1,56 +1,140 @@
-Ruby/CArray
-===========
+# 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.
 
-Features
---------
+## Status
 
-* 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).
+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.
 
-Requirements
-------------
+## Features
 
-* Ruby 2.4.0 or later
-* C compiler 
-  + IEEE754 floating point number
-  + C99 complex number
+* 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
 
-What is Ruby/CArray 
-------------------
+Each of these is shown, briefly and with a runnable example, in [A tour of the features](docs/FeatureTour.md).
 
-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. 
+## Install
 
-#### Multi-dimensional uniform array ####
+```
+gem install carray
+```
 
-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. 
+Or add it to your `Gemfile`:
 
-#### Collective mathematical operations ####
+```ruby
+gem "carray"
+```
 
-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.
+Requires Ruby 3.0 or later.
 
-#### Referencing data and virtual arrays ####
+On a multi-core machine, parallel `make` cuts install time noticeably:
 
-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.
+```
+MAKEFLAGS="-j$(nproc)" gem install carray                     # Linux
+MAKEFLAGS="-j$(sysctl -n hw.ncpu)" gem install carray         # macOS
+```
 
-#### Built-in element-wise mask handling ####
+## Quick example
 
-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.
+```ruby
+require "carray"
 
-#### User-defined array ####
+# --- create a 2x3 array ---
+a = CArray.float64(2, 3) { |i, j| i * 3 + j }
+#  => [ [ 0, 1, 2 ],
+#       [ 3, 4, 5 ] ]
 
-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.
+# --- 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
 
-License
--------
+# --- 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)
+
+# 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
+```
+
+## Documentation
+
+* [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 3.0 was designed and reviewed by a human developer; the implementation was produced in collaboration with AI coding tools.
+
+## License
 
 MIT (after version 1.5.0)
+
+Copyright (C) 2005-2026 himotoyoshi

data/carray.gemspec

@@ -1,34 +1,36 @@
-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.summary     = "Multi-dimesional array class for Ruby"
+  s.version     = "3.0.1"
+  s.authors      = ["himotoyoshi"]
+  s.email       = ["himotoyoshi@users.noreply.github.com"]
+  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.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("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",
+    "CHANGELOG.md",
+    "CHANGELOG.v1.md",
+    ".yardopts",
+    "carray.gemspec",
+  ].select { |f| File.file?(f) }
+  s.extensions  = ["ext/extconf.rb"]
+  s.require_paths = ["lib", "ext"]
 end
-