carray 3.0.1 → 3.0.2

data/yard-stubs/carray_median_percentile.rb

@@ -13,6 +13,11 @@ class CArray
   #   result of Ruby `+` / `/` on the stored objects. Fixlen arrays
   #   raise, since no numeric midpoint is defined.
   #
+  #   An even number of elements has no middle one, only the average of
+  #   two -- so an object array whose elements cannot be averaged (a
+  #   column of Strings) has a median at odd length and raises at even.
+  #   `percentile(50, method: :lower)` names an element either way.
+  #
   #   Masked cells are excluded. Per-axis, each fiber uses only its own
   #   present values; a fully masked fiber reduces to `UNDEF`. If the
   #   count of not-masked cells (per fiber, or over all elements in the
@@ -27,7 +32,8 @@ class CArray
   #     count is below `min_count`.
   #   @param keep_axis [Boolean]
   #   @return [Float, CArray, Object]
-  #   @raise [CArray::DataTypeError] for fixlen data_type.
+  #   @raise [CArray::DataTypeError] for fixlen data_type, or for an even
+  #     number of elements whose objects cannot be averaged.
   #   @raise [ArgumentError] on negative `min_count`.
   def median(*); end
 
@@ -52,6 +58,12 @@ class CArray
   #   - `:nearest` — round-half-to-even to the nearer neighbor.
   #   - `:midpoint` — arithmetic mean of the two neighbors.
   #
+  #   The first three pick an element and the last two compute one, so
+  #   only the first three apply to a `CA_OBJECT` array whose elements
+  #   have no arithmetic: `:linear` and `:midpoint` raise there, and do
+  #   so only when the requested `p` actually falls between two
+  #   elements (`percentile(50)` of five Strings still answers).
+  #
   #   Numeric arrays produce `Float` results; `CA_OBJECT` arrays
   #   apply Ruby `+` / `/` / `*` on the stored objects. Fixlen
   #   arrays raise.
@@ -67,7 +79,9 @@ class CArray
   #     `:nearest`, `:midpoint`.
   #   @param keep_axis [Boolean]
   #   @return [Float, CArray, Object, Array<Float>, Array<CArray>, Array<Object>]
-  #   @raise [CArray::DataTypeError] for fixlen data_type.
+  #   @raise [CArray::DataTypeError] for fixlen data_type, or when an
+  #     interpolating `method` is asked to interpolate between objects
+  #     that have no arithmetic.
   #   @raise [ArgumentError] on empty `p` list, `p` outside `[0, 100]`,
   #     empty axis, unknown `method`, or invalid option combinations.
   def percentile(*); end

data/yard-stubs/carray_order.rb

@@ -170,10 +170,17 @@ class CArray
 
   # @overload search_nearest(val)
   #   Returns the flat address of the element of `self` whose value
-  #   is closest to `val`. For `:object` arrays, uses
-  #   `val.distance(other)` to compare.
+  #   is closest to `val`.
+  #
+  #   In an `:object` array the distance is `val.distance(other)` when
+  #   `val` answers `#distance`, and `(val - other).abs` when it is a
+  #   number. Anything else -- a String, say -- has no distance and
+  #   raises `CArray::DataTypeError`; use {#search} or {#bsearch} for an
+  #   exact match.
   #   @param val [Object]
   #   @return [Integer, nil]
+  #   @raise [CArray::DataTypeError] when `val` is neither a number nor
+  #     answers `#distance`.
   # @overload search_nearest(val, axis:)
   #   Per-fiber nearest-value search along `axis`. Returns
   #   axis-local positions.
@@ -189,73 +196,6 @@ class CArray
   #   @return [CArray]
   def search_nearest_addr(val, axis: nil); end
 
-  # @overload locate_addr(ref)
-  #   Returns, for each element of `self`, the flat address into `ref`
-  #   where the value first occurs, or `UNDEF` where it is not present.
-  #   Builds a value-to-first-address map from `ref` in one pass (an
-  #   open-addressing hash, the same substrate as {#unique} /
-  #   {#value_counts}), then probes each element of `self`; no sort,
-  #   peak memory `O(distinct ref values)`.
-  #
-  #   The return is `ref`'s flat address (0 to `ref.elements - 1`),
-  #   so a multi-dimensional `ref` still yields a `self`-shaped
-  #   result of flat addresses; downstream reads (`ref[addr]`,
-  #   `model_var[addr]`, ...) apply it as a flat gather.
-  #
-  #   Works on numeric, `CA_OBJECT`, and `CA_FIXLEN` values, matching
-  #   the value-hash discovery family: numeric follows `==` with all
-  #   NaN collapsed to one value and `-0.0 == +0.0`; object follows
-  #   Ruby `hash` / `eql?` with Float NaN collapsed; fixlen follows
-  #   byte equality. When `ref` holds duplicate values the returned
-  #   address is the earliest (appearance-order) occurrence. Masked
-  #   cells of `ref` do not enter the map but still occupy their flat
-  #   address; masked cells of `self` are `UNDEF` in the result.
-  #
-  #   Typical use is time-axis lookup: compute the address once
-  #   against a reference axis, then reuse it to gather from many
-  #   `ref`-shaped variables without repeating the lookup.
-  #
-  #   Implemented in Ruby (see `lib/carray/methods/locate_addr.rb`)
-  #   over the `__locate_addr__` hash-lane kernel; `self` is coerced
-  #   to `ref`'s data type within the same family (cross-family raises).
-  #   @param ref [CArray] reference values to match against; any
-  #     shape (used as flat).
-  #   @return [CArray] `:int64` flat addresses into `ref`, same shape
-  #     as `self`; unmatched cells are masked.
-  def locate_addr(ref); end
-
-  # @overload locate_nearest_addr(ref, direction: :round, tolerance: nil)
-  #   Returns, for each element of `self`, the flat address into `ref`
-  #   of the nearest reference value. Continuous sibling of
-  #   {#locate_addr}; uses `linear_section` + rounding for non-exact
-  #   matching against a sorted `ref`.
-  #
-  #   Out-of-range cells of `self` (outside `ref`'s span) mask through
-  #   the pipeline: `linear_section` returns NaN, `mask_invalid`
-  #   propagates that as `UNDEF`, rounding and the int64 cast carry
-  #   the mask, and `project` scatters it into the final positions.
-  #   `mask_invalid` runs before rounding because `CArray#round` maps
-  #   NaN to 0 and would otherwise silently match `ref[0]`.
-  #
-  #   `tolerance:` (default `nil`) sets a maximum accepted absolute
-  #   distance between `self[i]` and its matched `ref` value. When
-  #   `|ref[addr] - self[i]| > tolerance`, the result cell is masked.
-  #   Use for accuracy-controlled matching (e.g. "an observation
-  #   snaps to a time step only if within N seconds").
-  #
-  #   Implemented in Ruby (see `lib/carray/methods/locate_addr.rb`).
-  #   @param ref [CArray] 1-D sorted reference grid to match against.
-  #   @param direction [Symbol] `:round`, `:floor`, or `:ceil` —
-  #     rounding applied to the fractional position.
-  #   @param tolerance [Numeric, nil] maximum accepted `|self - ref|`
-  #     distance; cells beyond this are masked. `nil` disables the
-  #     check.
-  #   @return [CArray] `:int64` flat addresses into `ref`, same shape
-  #     as `self`; out-of-range and beyond-tolerance cells are masked.
-  #   @raise [ArgumentError] when `direction` is not one of the
-  #     accepted symbols.
-  def locate_nearest_addr(ref, direction: :round, tolerance: nil); end
-
   # @!endgroup
 
   # @!group Sorting and searching

data/yard-stubs/carray_slab.rb

@@ -10,16 +10,18 @@ class CArray
 
   # @overload each_slab(axis:)
   #   Yields each slab of `self` (a view along the axes NOT in `axis`) to
-  #   the block and returns `self`.  The slab is a live view valid only
-  #   for the duration of the block — capturing it across iterations sees
-  #   the last slab's data.
+  #   the block and returns `self`.  The slab is valid only for the
+  #   duration of the block — capturing it across iterations sees the last
+  #   slab's data — and it is read-only: writing through it raises.  To
+  #   produce values per slab use `map_slab` or `reduce_slab`; to write in
+  #   place, assign through the array itself.
   # @overload each_slab(axis:)
   #   Returns an Enumerator when no block is given.
   #   @param axis [Integer, Array<Integer>, nil] the slab axis or axes
   #     (`nil` = the whole view as a single slab).
   #   @return [self, Enumerator]
-  #   @see file:docs/SlabIterator.md SlabIterator
-  #   @see file:docs/drafts/11_slab_iteration.md Slab iteration
+  #   @see file:docs/topics/SlabIterator.md SlabIterator
+  #   @see file:guides/users/11_slab_iteration.md Slab iteration
   def each_slab(axis:); end
 
   # @overload map_slab(axis:, data_type: nil)
@@ -33,7 +35,7 @@ class CArray
   #   @return [CArray]
   #   @raise [ArgumentError] when the block result's shape does not match
   #     the slab.
-  #   @see file:docs/SlabIterator.md SlabIterator
+  #   @see file:docs/topics/SlabIterator.md SlabIterator
   def map_slab(axis:, data_type: nil); end
 
   # @overload reduce_slab(axis:, data_type: nil)
@@ -50,7 +52,7 @@ class CArray
   #     per-element form).
   #   @param data_type [Symbol, Integer, Class, nil] output data type.
   #   @return [CArray] the reduced array (slab axes collapsed).
-  #   @see file:docs/SlabIterator.md SlabIterator
+  #   @see file:docs/topics/SlabIterator.md SlabIterator
   def reduce_slab(axis:, init: nil, data_type: nil); end
 
   # @!endgroup

data/yard-stubs/carray_sort.rb

@@ -67,11 +67,13 @@ class CArray
   #   along `axis`. Use this when you want an independent array
   #   rather than a view.
   #
-  #   Unmasked numeric paths use a per-fiber gather + sort +
-  #   scatter, bypassing the `CARemap` scatter layer that `sort`
-  #   uses. `CA_FIXLEN` and masked input both materialize the
-  #   `sort` view instead (same shape, ordering, and
-  #   `masked_position:` semantics as {#sort}).
+  #   It takes whatever {#sort} takes: numeric (`i8`..`f64`),
+  #   `CA_BOOLEAN`, `CA_FIXLEN` and `CA_OBJECT`, masked or not.
+  #
+  #   Unmasked `i8`..`f64` uses a per-fiber gather + sort + scatter,
+  #   bypassing the `CARemap` scatter layer that `sort` uses.
+  #   Everything else materializes the `sort` view instead (same
+  #   shape, ordering, and `masked_position:` semantics as {#sort}).
   #   @param axis [Integer, nil]
   #   @param kind [Symbol] `:quick` or `:stable`.
   #   @param masked_position [Symbol] `:last` (default) or `:first`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carray
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.0.2
 platform: ruby
 authors:
 - himotoyoshi
@@ -96,6 +96,8 @@ files:
 - ext/ca_op_cmplx64.h
 - ext/ca_op_ipower.c
 - ext/ca_op_powi.h
+- ext/ca_rng_normal.h
+- ext/ca_rng_xoshiro256pp.h
 - ext/ca_sort_kernels.h
 - ext/ca_sweep_engine.c
 - ext/ca_sweep_engine.h
@@ -104,6 +106,7 @@ files:
 - ext/ca_triop_dispatch.h
 - ext/carray.h
 - ext/carray_access.c
+- ext/carray_address_basis.c
 - ext/carray_attribute.c
 - ext/carray_bincount.c
 - ext/carray_broadcast.c
@@ -186,6 +189,7 @@ files:
 - lib/carray/construct.rb
 - lib/carray/core_extensions.rb
 - lib/carray/data_type_extension.rb
+- lib/carray/data_type_limits.rb
 - lib/carray/fixlen_string.rb
 - lib/carray/frame.rb
 - lib/carray/frame/concat.rb
@@ -214,6 +218,8 @@ files:
 - lib/carray/methods/broadcast.rb
 - lib/carray/methods/choose.rb
 - lib/carray/methods/composition.rb
+- lib/carray/methods/discovery_along.rb
+- lib/carray/methods/factorize.rb
 - lib/carray/methods/gather_nd.rb
 - lib/carray/methods/index.rb
 - lib/carray/methods/insert_block.rb
@@ -224,12 +230,14 @@ files:
 - lib/carray/methods/meshgrid.rb
 - lib/carray/methods/mode.rb
 - lib/carray/methods/nunique.rb
+- lib/carray/methods/repeat.rb
 - lib/carray/methods/resize.rb
 - lib/carray/methods/snap.rb
 - lib/carray/methods/string_format.rb
 - lib/carray/methods/unique.rb
 - lib/carray/methods/value_counts.rb
 - lib/carray/mkmf.rb
+- lib/carray/rng.rb
 - lib/carray/runtime.rb
 - lib/carray/serialize.rb
 - lib/carray/slab_iterator.rb