carray 3.0.0 → 3.0.2

data/yard-stubs/carray_scatter.rb

@@ -0,0 +1,106 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_scatter.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Scatter and generation
+  #
+  # The `scatter_*!` family applies an in-place reduction at each
+  # `addrs[i]` position from a paired `vals[i]` (or scalar). The
+  # accumulate variants (`scatter_add!` / `scatter_sub!` /
+  # `scatter_mul!` / `scatter_min!` / `scatter_max!`) apply duplicate
+  # addresses in sequence (unbuffered). {#scatter_replace!} is the
+  # last-write variant, equivalent to `self[addrs] = vals` but
+  # bypasses the CAGrid view chain.
+  #
+  # Shared contract:
+  #
+  # - `addrs` is a CArray of any integer type (coerced to
+  #   `CA_SIZE`) or a Ruby Array.
+  # - `vals` is a CArray of length matching `addrs` (coerced to
+  #   `self.data_type`), or a Numeric scalar broadcast to all
+  #   addresses.
+  # - Out-of-range `addrs[i]` (`< 0` or `>= self.elements`) raises
+  #   `IndexError`.
+  # - `self.data_type` must be numeric.
+  #
+  # Mask policy differs between the accumulate family and
+  # {#scatter_replace!}: the accumulate variants skip the pair when
+  # any of `addrs[i]`, `vals[i]`, or `self[addrs[i]]` is masked (an
+  # unknown source can't accumulate). {#scatter_replace!} instead
+  # overwrites the target (masked `vals[i]` flips the target to
+  # masked, valid `vals[i]` clears the target's mask), matching the
+  # `self[addrs] = vals` indexer.
+
+  # @overload scatter_add!(addrs, vals)
+  #   For each `i`, applies `self[addrs[i]] += vals[i]`
+  #   (or `+= vals` if `vals` is scalar). Mutates `self`.
+  #   @param addrs [CArray, Array<Integer>]
+  #   @param vals [CArray, Numeric]
+  #   @return [self]
+  #   @raise [IndexError] for out-of-range addresses.
+  #   @raise [CArray::DataTypeError] for non-numeric `data_type`.
+  def scatter_add!(addrs, vals); end
+
+  # @overload scatter_sub!(addrs, vals)
+  #   For each `i`, applies `self[addrs[i]] -= vals[i]`. Same
+  #   contract as {#scatter_add!}.
+  #   @param addrs [CArray, Array<Integer>]
+  #   @param vals [CArray, Numeric]
+  #   @return [self]
+  def scatter_sub!(addrs, vals); end
+
+  # @overload scatter_mul!(addrs, vals)
+  #   For each `i`, applies `self[addrs[i]] *= vals[i]`. Duplicate
+  #   addresses multiply.
+  #
+  #   NaN/inf follow standard C arithmetic propagation (no
+  #   `fmin`-style missing-value rule). Integer overflow wraps.
+  #
+  #   Typical uses: Bayesian likelihood patch update, scatter blend,
+  #   log-domain → linear product, weight composition.
+  #   @param addrs [CArray, Array<Integer>]
+  #   @param vals [CArray, Numeric]
+  #   @return [self]
+  def scatter_mul!(addrs, vals); end
+
+  # @overload scatter_min!(addrs, vals)
+  #   For each `i`, applies
+  #   `self[addrs[i]] = min(self[addrs[i]], vals[i])`.
+  #
+  #   For float `data_type`, NaN follows the `fmin` rule (NaN is
+  #   treated as missing: `min(NaN, v) → v`, `min(x, NaN) → x`).
+  #   @param addrs [CArray, Array<Integer>]
+  #   @param vals [CArray, Numeric]
+  #   @return [self]
+  def scatter_min!(addrs, vals); end
+
+  # @overload scatter_max!(addrs, vals)
+  #   For each `i`, applies
+  #   `self[addrs[i]] = max(self[addrs[i]], vals[i])`. For float
+  #   `data_type`, NaN follows the `fmax` rule.
+  #   @param addrs [CArray, Array<Integer>]
+  #   @param vals [CArray, Numeric]
+  #   @return [self]
+  def scatter_max!(addrs, vals); end
+
+  # @overload scatter_replace!(addrs, vals)
+  #   For each `i`, applies `self[addrs[i]] = vals[i]` (or `= vals`
+  #   if scalar). Duplicate addresses resolve to last-write-wins.
+  #
+  #   Semantically equivalent to `self[addrs] = vals` but bypasses
+  #   the CAGrid view chain (which snapshot-copies `addrs` and
+  #   allocates view state); useful in hot loops where a scatter
+  #   result is written back many times.
+  #
+  #   Unlike the arithmetic `scatter_*!` family, `self` may be
+  #   **boolean** (assignment does not widen), and `true` / `false`
+  #   are accepted as scalar `vals` alongside numeric scalars.
+  #
+  #   @param addrs [CArray, Array<Integer>]
+  #   @param vals [CArray, Numeric, true, false]
+  #   @return [self]
+  def scatter_replace!(addrs, vals); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_slab.rb

@@ -0,0 +1,59 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_slab.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+#
+# The slab-iteration family walks `self` in slabs (sub-arrays) taken along
+# a chosen set of axes.  See the @see links for the full walkthrough.
+
+class CArray
+  # @!group Iteration
+
+  # @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 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/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)
+  #   Returns a new CArray built by replacing each slab of `self` with the
+  #   block's result.  The block receives the slab view and must return a
+  #   value of the same shape as the slab (a CArray or scalar); the results
+  #   are written into the output at the same positions.
+  #   @param axis [Integer, Array<Integer>, nil] the slab axis or axes.
+  #   @param data_type [Symbol, Integer, Class, nil] output data type
+  #     (defaults to `self`'s data type).
+  #   @return [CArray]
+  #   @raise [ArgumentError] when the block result's shape does not match
+  #     the slab.
+  #   @see file:docs/topics/SlabIterator.md SlabIterator
+  def map_slab(axis:, data_type: nil); end
+
+  # @overload reduce_slab(axis:, data_type: nil)
+  #   Per-slab form (no `init:`): the block receives each slab view and
+  #   returns a scalar; the scalars fill an output CArray with the slab
+  #   axes collapsed.  Returning a CArray from the block is an error (use
+  #   `slab[0]`, `slab.sum`, etc. to extract a scalar).
+  # @overload reduce_slab(axis:, init:, data_type: nil)
+  #   Per-element form (`init:` given): the block receives `(acc, x)` for
+  #   each element of the slab and returns the new accumulator; the final
+  #   accumulator per slab fills the output.
+  #   @param axis [Integer, Array<Integer>, nil] the slab axis or axes.
+  #   @param init [Object] the initial accumulator (selects the
+  #     per-element form).
+  #   @param data_type [Symbol, Integer, Class, nil] output data type.
+  #   @return [CArray] the reduced array (slab axes collapsed).
+  #   @see file:docs/topics/SlabIterator.md SlabIterator
+  def reduce_slab(axis:, init: nil, data_type: nil); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_sort.rb

@@ -0,0 +1,165 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_sort.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Sorting and searching
+
+  # @overload sort_addr(*keys, masked_position: :last)
+  #   Returns a 1-D CArray of `:int64` indices that lex-sort `keys`
+  #   in priority order (`keys[0]` is highest priority,
+  #   `keys[1]` breaks ties, etc.). All `keys` must share the same
+  #   element count.
+  #
+  #   Masked cells are an incomparable sentinel clustered at
+  #   `masked_position:` (`:last`, default, or `:first`), applied
+  #   uniformly across all `keys`. Ties are broken by original index
+  #   (stable).
+  #
+  #   @example
+  #     idx = CArray.sort_addr(a, b, c)  # priority: a > b > c
+  #     a[idx]; b[idx]; c[idx]
+  #
+  #   @param keys [Array<CArray>] one or more CArrays, all of the
+  #     same element count.
+  #   @param masked_position [Symbol] `:last` (default) or `:first`.
+  #   @return [CArray] flat `:int64` indices, shape `[a.elements]`.
+  #   @raise [ArgumentError] when no key is given or element counts
+  #     differ.
+  def self.sort_addr(*keys, masked_position: :last); end
+
+  # @overload sort(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns a `CARemap` view of `self` whose elements are sorted
+  #   along `axis`. When `axis` is omitted, `self` is first
+  #   flattened to 1-D and the entire array is sorted (so the
+  #   result is a 1-D view regardless of `self.ndim`).
+  #
+  #   `kind:` selects the sorting algorithm. Both kinds are stable
+  #   (tie-broken by fiber-local index); the choice is a
+  #   performance characteristic only:
+  #
+  #   - `:quick` (default) — portable textbook introsort with
+  #     mergesort escape. Faster on random data.
+  #   - `:stable` — portable bottom-up mergesort with insertion
+  #     pre-pass. Predictable worst case.
+  #
+  #   Masked cells are an incomparable sentinel (the same role NaN
+  #   plays for float data types): they are excluded from the value
+  #   comparison and clustered at one end of each fiber.
+  #   `masked_position:` picks which end (`:last`, default, or
+  #   `:first`); relative order within the masked cluster is
+  #   unspecified. Masked cells keep their masked-ness at the
+  #   clustered position (the `CARemap` gather carries the mask bit
+  #   through, no separate output-mask step needed).
+  #
+  #   Supports numeric (`i8`..`f64`), `CA_FIXLEN` (via memcmp
+  #   lexicographic order), and `CA_OBJECT` (via `<=>` per pair) --
+  #   all through the same view path, `masked_position:` included.
+  #   @param axis [Integer, nil]
+  #   @param kind [Symbol] `:quick` or `:stable`.
+  #   @param masked_position [Symbol] `:last` (default) or `:first`.
+  #   @return [CArray] sorted view.
+  def sort(axis: nil, kind: :quick, masked_position: :last); end
+
+  # @overload sort_copy(axis: nil, kind: :quick, masked_position: :last)
+  #   Eager-copy counterpart of {#sort}: returns a fresh entity
+  #   CArray with the same shape and `data_type` as `self`, sorted
+  #   along `axis`. Use this when you want an independent array
+  #   rather than a view.
+  #
+  #   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`.
+  #   @return [CArray]
+  def sort_copy(axis: nil, kind: :quick, masked_position: :last); end
+
+  # @overload sort_addr(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns view-flat addresses that index a sort.
+  #
+  #   - With no kwarg (`a.sort_addr`): returns a CArray of `:int64`
+  #     flat addresses shaped like `self` (NOT flattened -- the
+  #     legacy 1-key case of `CArray.sort_addr`'s multi-key lex
+  #     sort). `kind:` has no effect on this form.
+  #   - With `axis:` (e.g. `a.sort_addr(axis: 0)`): returns
+  #     per-fiber view-flat addresses along the given axis, output
+  #     shape == `self.shape`.
+  #
+  #   `kind:` selects the sort algorithm for the `axis:` path:
+  #
+  #   - `:quick` (default) — introsort with mergesort escape.
+  #   - `:stable` — bottom-up mergesort.
+  #
+  #   Both kinds are algorithmically stable (pair sort with index
+  #   tie-break); `kind:` chooses the performance characteristic.
+  #
+  #   `masked_position:` (`:last` default, or `:first`) picks which
+  #   end masked cells cluster to. Effective on both forms: the
+  #   `axis:` path forwards to the `sort`/`sort_index` kernel family;
+  #   the no-`axis:` path forwards to `CArray.sort_addr`'s own
+  #   masked-position-aware comparator.
+  #
+  #   Companion of {#axis2addr} (axis-local indices to view-flat
+  #   addresses) and {#sort} (the view counterpart).
+  #   @param axis [Integer, nil]
+  #   @param kind [Symbol] `:quick` or `:stable`.
+  #   @param masked_position [Symbol] `:last` (default) or `:first`.
+  #   @return [CArray] `:int64` addresses.
+  #   @raise [ArgumentError] when `kind:` is neither `:quick` nor
+  #     `:stable`.
+  def sort_addr(axis: nil, kind: :quick, masked_position: :last); end
+
+  # @!group Index and address conversion
+
+  # @overload axis2addr(indices, axis: 0)
+  #   Converts per-fiber axis-local indices into row-major
+  #   view-flat addresses into `self`. For each cell at coord
+  #   `c = (c_0, ..., c_(n-1))` in `indices`:
+  #
+  #     addr[c] = sum over `j != axis` of c_j * stride_j +
+  #               indices[c] * stride_axis
+  #
+  #   where strides are row-major over `self.shape`.
+  #
+  #   Canonical converter between the two axis-position
+  #   representations the `*_index` / `*_addr` kernel families
+  #   produce:
+  #
+  #   @example
+  #     a.min_index(axis: k)  # axis-local scalar per fiber
+  #     a.min_addr(axis: k)   # view-flat address per fiber
+  #     flat = key.axis2addr(key.min_index(axis: k), axis: k)
+  #     # flat == key.min_addr(axis: k)
+  #
+  #   Sits underneath `#take_along_axis`: the heavy "axis-local
+  #   -> view-flat" arithmetic lives here, and `take_along_axis`
+  #   is a one-liner on top of `flatten[axis2addr(...)]`.
+  #
+  #   Shape rule: `indices.ndim == self.ndim`, and
+  #   `indices.dim[j] == self.dim[j]` for all `j != axis`;
+  #   `indices.dim[axis]` is free.
+  #
+  #   `indices` data_type: any integer kind (zero-copy when
+  #   already `:int64`). Negative indices: Python-style
+  #   (`-1` == last). Out-of-range indices raise `RangeError`.
+  #   Negative `axis:` is Python-style.
+  #
+  #   @param indices [CArray] integer-typed axis-local positions.
+  #   @param axis [Integer] axis along which `indices` are
+  #     interpreted.
+  #   @return [CArray] `:int64` view-flat addresses, same shape as
+  #     `indices`.
+  #   @raise [RangeError] when an index is out of range after
+  #     negative normalization.
+  #   @raise [ArgumentError] for shape / ndim / data_type
+  #     violations.
+  def axis2addr(indices, axis: 0); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_test.rb

@@ -0,0 +1,85 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_test.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Index and address conversion
+
+  # @overload valid_index?(*idx)
+  #   Returns `true` if the given index tuple is in range for `self`.
+  #   The number of indices must equal `ndim`.
+  #   @param idx [Array<Integer>] one index per axis.
+  #   @return [Boolean]
+  #   @raise [ArgumentError] if the number of indices does not match
+  #     `ndim`.
+  def valid_index?(*idx); end
+
+  # @overload valid_addr?(addr)
+  #   Returns `true` if `addr` is in range `0...elements` for `self`.
+  #   @param addr [Integer] flat address into the contiguous element
+  #     sequence.
+  #   @return [Boolean]
+  def valid_addr?(addr); end
+
+  # @overload same_shape?(other)
+  #   Returns `true` if `other` has the same shape as `self`.
+  #   @param other [CArray]
+  #   @return [Boolean]
+  def same_shape?(other); end
+
+  # @!endgroup
+
+  # @!group Equality and hashing
+
+  # @overload ==(other)
+  #   Returns `true` if `other` is a CArray with the same shape,
+  #   `data_class`, `data_type`, mask state, and elementwise values as
+  #   `self`. NaN values compare unequal (IEEE semantics), so two
+  #   arrays with NaN at the same position are not `==`.
+  #   @param other [Object]
+  #   @return [Boolean]
+  def ==(other); end
+
+  # @overload eql?(other)
+  #   Returns `true` under Hash-invariant semantics: `data_class`,
+  #   `data_type`, shape, and mask state must all match, and elements
+  #   are compared bitwise (for numeric types) or via `Object#eql?`
+  #   (for `:object` arrays). Unlike `==`, `NaN.eql?(NaN)` holds, so
+  #   two mask-free arrays with NaN at the same positions are `eql?`.
+  #
+  #   Guarantees `a.eql?(b)` ⇒ `a.hash == b.hash`.
+  #   @param other [Object]
+  #   @return [Boolean]
+  def eql?(other); end
+
+  # @overload hash
+  #   Returns the Hash key value for `self`. Mixes `data_type`,
+  #   `ndim`, `bytes`, `elements`, shape, scalar-ness, and mask
+  #   presence; for unmasked arrays, samples the leading 64 bytes of
+  #   data. Masked arrays skip the data sample.
+  #   @return [Integer]
+  def hash; end
+
+  # @!endgroup
+
+  # @!group Equality and hashing
+
+  # @overload freeze
+  #   Freezes `self` and marks it read-only. Subsequent mutations
+  #   raise `FrozenError`.
+  #   @return [self]
+  def freeze; end
+
+  # @overload set_read_only_flag
+  #   Marks `self` read-only (sets `CA_FLAG_READ_ONLY`) without
+  #   freezing the Ruby object, so subsequent mutations raise
+  #   `RuntimeError` while `frozen?` stays false and views / Faces
+  #   derived from `self` can still memoise. One-way: there is no
+  #   method to clear the flag. Use `#copy` for a writable copy (a
+  #   copy does not inherit the flag). Contrast `#freeze`, which also
+  #   freezes the Ruby object.
+  #   @return [self]
+  def set_read_only_flag; end
+
+  # @!endgroup
+end

data/yard-stubs/carray_undef.rb

@@ -0,0 +1,64 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for the UNDEF sentinel and UndefClass defined in
+# ext/carray_undef.c. See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Singleton class of the {UNDEF} sentinel value.  Not instantiable
+# (`UndefClass.new` is undef'd after the single instance is created
+# in `Init_carray_undef`).
+#
+# The class is private API in practice: read and write the sentinel
+# through the top-level `UNDEF` constant rather than touching the
+# class directly.
+class UndefClass
+  # @overload inspect
+  #   Returns the literal string `"UNDEF"`.
+  #   @return [String]
+  def inspect; end
+
+  # @overload to_s
+  #   Returns the literal string `"UNDEF"`.  Display works (so
+  #   `puts UNDEF` shows `"UNDEF"`); numeric coercion via {#to_f}
+  #   / {#to_i} raises.
+  #   @return [String]
+  def to_s; end
+
+  # @overload to_f
+  #   Raises `TypeError`.  Numeric coercion of UNDEF is rejected so
+  #   that accidental arithmetic on a masked sentinel surfaces as an
+  #   error rather than silently producing `0.0` / `NaN`.
+  #   @raise [TypeError]
+  def to_f; end
+
+  # @overload to_i
+  #   Raises `TypeError`.  Same rationale as {#to_f}.
+  #   @raise [TypeError]
+  def to_i; end
+
+  # @overload to_int
+  #   Alias of {#to_i}.  Raises `TypeError`.
+  #   @raise [TypeError]
+  def to_int; end
+
+  # @overload ==(other)
+  #   Returns `true` only when `other` is the same UNDEF singleton
+  #   (identity comparison).  No coercion or value equality.
+  #   @param other [Object]
+  #   @return [Boolean]
+  def ==(other); end
+end
+
+# Top-level sentinel used by mask-bearing CArray APIs to mean
+# "masked / no value here" without choosing a numeric sentinel
+# (NaN, `-1`, etc.) that might collide with valid data.
+#
+# Identity semantics: every reference to `UNDEF` is the same Ruby
+# object, pinned against the compacting GC so the C extension can
+# safely use raw pointer comparison to detect it.
+#
+# @example mask a cell during construction
+#   a = CArray.int32(3) { |i| (i == 1) ? UNDEF : i * 10 }
+#   a.to_a  # => [0, nil, 20]    # UNDEF surfaces as nil after to_a
+#
+# @example check whether an element is masked
+#   a[1] == UNDEF  # => true
+UNDEF = UndefClass.new

data/yard-stubs/carray_utils.rb

@@ -0,0 +1,97 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_utils.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Index and address conversion
+
+  # @overload normalize_axis(axis, name = nil)
+  #   Returns the canonical non-negative integer axis index in
+  #   `[0, ndim)` for `self`. Accepts Python-style negative indices
+  #   (`-1` ⇒ `ndim-1`).
+  #   @param axis [Integer] axis index, possibly negative.
+  #   @param name [String, nil] argument name to embed in error
+  #     messages (e.g. `"axis"`, `"at"`).
+  #   @return [Integer]
+  #   @raise [ArgumentError] if `axis` is outside `[-ndim, ndim)`.
+  def normalize_axis(axis, name = nil); end
+
+  # @overload normalize_axes(axes, name = nil)
+  #   Returns an Array of canonical non-negative axis indices in
+  #   input order. Accepts:
+  #
+  #   - `nil` ⇒ all axes `[0, 1, ..., ndim-1]`
+  #   - `Integer` ⇒ `[normalize_axis(axis)]`
+  #   - `Array<Integer>` ⇒ each normalized, preserving input order
+  #
+  #   @param axes [Integer, Array<Integer>, nil]
+  #   @param name [String, nil] argument name for error messages.
+  #   @return [Array<Integer>]
+  #   @raise [ArgumentError] on out-of-range or duplicate axes.
+  def normalize_axes(axes, name = nil); end
+
+  # @!endgroup
+
+  class << self
+    # @!group Index and address conversion
+
+    # @overload normalize_axis(axis, ndim, name = nil)
+    #   Class-method form of {CArray#normalize_axis} that operates on
+    #   an explicit `ndim` rather than a CArray instance. Range is
+    #   `[0, ndim)`.
+    #
+    #   For an insertion position (valid range `[0, old_ndim]`
+    #   inclusive), pass `old_ndim + 1` as `ndim`. Used by class-level
+    #   callers such as `CArray.stack(list, axis:)` that must
+    #   normalize before any instance is available, and by
+    #   composition helpers in `lib/carray/compose.rb`.
+    #   @param axis [Integer]
+    #   @param ndim [Integer]
+    #   @param name [String, nil]
+    #   @return [Integer]
+    def normalize_axis(axis, ndim, name = nil); end
+
+    # @!endgroup
+
+    # @!group Type guessing
+
+    # @overload guess_type_and_bytes(type_spec, bytes = nil)
+    #   Resolves a user-supplied type spec into the pair
+    #   `[data_type_code, bytes]`. `data_type_code` is the internal
+    #   `int8_t` numeric code (see {CArray.data_type_code}); `bytes`
+    #   is the per-element byte size (`0` for non-`:fixlen`).
+    #   @param type_spec [Symbol, Integer, Class, String]
+    #   @param bytes [Integer, nil] element byte size, used only for
+    #     `:fixlen`.
+    #   @return [Array(Integer, Integer)]
+    def guess_type_and_bytes(type_spec, bytes = nil); end
+
+    # @!endgroup
+
+    # @!group String scanning (internal)
+
+    # @overload _scan_float(str, fill_value = nil)
+    #   Parses `str` as a single double-precision float. Returns
+    #   `fill_value` (or `NaN` if `fill_value` is nil) when `str` is
+    #   `nil` or unparseable. Internal helper used by text-format I/O
+    #   readers; end users should prefer Ruby's `Float()` /
+    #   `String#to_f`.
+    #   @param str [String, nil]
+    #   @param fill_value [Float, nil]
+    #   @return [Float]
+    #   @api private
+    def _scan_float(str, fill_value = nil); end
+
+    # @overload _scan_int(str, fill_value = nil)
+    #   Parses `str` as a single integer. Returns `fill_value`
+    #   (or `0` if `fill_value` is nil) when `str` is `nil` or
+    #   unparseable. Internal helper used by text-format I/O readers.
+    #   @param str [String, nil]
+    #   @param fill_value [Integer, nil]
+    #   @return [Integer]
+    #   @api private
+    def _scan_int(str, fill_value = nil); end
+
+    # @!endgroup
+  end
+end