carray 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7deb551fcc14866b90ad75e9d74ce716922de103148507bcb8b53c039b9afa48
-  data.tar.gz: d8efa03d7f0852a15223329545c5ad3bb0abfcb0c48191978b1e0e6755d50f6b
+  metadata.gz: 3fd3c3099973bb94e29628f609cf27b65ccd9f318a5a707273fd86586e89e9a2
+  data.tar.gz: c9a01c64bc228fd8c4e92d2ef01043678608fa31f68a2a357f3ace5bf9f8b7af
 SHA512:
-  metadata.gz: d1b4817095544fa7fae956207a3356f3300afab2b3e6b25b2c646e8c52b6db9a3ce9553131bb80ba5899f8d393de9dfd9f8136f1a8224402a372076f74556e89
-  data.tar.gz: 859f3082f6c44a5f340fbf5ddd057e52f2fcacbadf5c5452c117b15faf683c9f915dc1f47ee59ba2fa37fa416fbf050b4747fbb1934971a472e74861c3b32ec4
+  metadata.gz: 84056c479f21558ffac49f051d4efdd6d34f4e7fa18218f097ab7ecabc3a7791782060358605c26265a90928ae2911253e5f6f6ca31acd3b70f3e069b5001bf5
+  data.tar.gz: a20917afb47f7c2ed0e3968678bd834680f41ceacf05d2c3771729d381ba7cb9a93c8e89aeca9f609a5811b9168b33fc446c1bd0cedc28c590c65eb02b070e2d

data/.yardopts

@@ -1,11 +1,12 @@
 --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 CHANGELOG.md,NEWS.md
+--files CHANGELOG.md,CHANGELOG.v1.md
 lib/carray.rb
 lib/carray/**/*.rb
 yard-stubs/**/*.rb

data/CHANGELOG.md

@@ -1,9 +1,331 @@
 # 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).
+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.
 
-## 3.0.0 — 2026-08-25
+<!-- 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,

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 3.0 was designed and reviewed by a human developer; the implementation was
-produced in collaboration with AI coding tools.
+CArray 3.0 was designed and reviewed by a human developer; the implementation was produced in collaboration with AI coding tools.
 
 ## 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.1"
   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) }