carray 2.0.1 → 3.0.1

data/yard-stubs/carray_access.rb

@@ -0,0 +1,131 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_access.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+#
+# The indexer surface (`[]` / `[]=`) is large; the per-form detail lives in
+# the user guides (see the @see links) rather than being duplicated here.
+
+class CArray
+  # @!group Indexing and slicing
+
+  # @overload [](*index)
+  #   Returns a view of `self` (or a single element) selected by one
+  #   `index` per axis.  Every array-returning form is a view onto the
+  #   original storage — writing through it reaches the source.
+  #
+  #   Accepted per-axis index forms:
+  #   - Integer — one position (negative counts from the end); an
+  #     all-Integer index returns the single element (masked -> UNDEF).
+  #   - `nil` — the whole axis.
+  #   - Range — a contiguous (or stepped, via a stepped Range) sub-range.
+  #   - boolean CArray — masked selection along that axis.
+  #   - Integer CArray — fancy gather (index array); shape follows the
+  #     index array.
+  #   - `:_` — newaxis: insert a size-1 axis at this position.
+  #   - `:*` / `:%` — repeat / tiling sugar.
+  #   - `:>` — slab axis: wrap the result in a `CASlabIterator`.
+  #   - a member name Symbol — project a struct field (see `CARecord`).
+  #
+  #   A single flat Integer (fewer indices than `ndim`) addresses the
+  #   array in row-major flat order.
+  #   @param index [Array<Integer, Range, nil, CArray, Symbol>] one entry
+  #     per axis (or a single flat address).
+  #   @return [CArray, Object] a view for a slicing form, or the element
+  #     value (or `UNDEF` if masked) for an all-scalar index.
+  #   @raise [IndexError] on an out-of-range index or an unrecognised form.
+  #   @see file:docs/drafts/02_indexing_and_slicing.md Indexing and slicing
+  #   @see file:docs/drafts/16_indexer_reference.md Indexer reference
+  def [](*index); end
+
+  # @overload []=(*index, value)
+  #   Sets the cells of `self` selected by `index` (same per-axis forms as
+  #   {#[]}) to `value`.  `value` may be a scalar (broadcast), an Array, or
+  #   a CArray whose element count matches the selection; assigning `UNDEF`
+  #   masks the selected cells.
+  #
+  #   Assignment through a slab iterator (`:>`) is not supported — use a
+  #   block index (e.g. `ca[range, nil] = val`) or `each_slab`.
+  #   @param index [Array<Integer, Range, nil, CArray, Symbol>] one entry
+  #     per axis (or a single flat address).
+  #   @param value [Object, Array, CArray] the value(s) to store, or
+  #     `UNDEF` to mask.
+  #   @return [Object] `value`.
+  #   @raise [IndexError] on an out-of-range index or an unsupported form.
+  #   @see file:docs/drafts/16_indexer_reference.md Indexer reference
+  def []=(*index, value); end
+
+  # @!endgroup
+
+  # @!group Indexing and slicing
+
+  # @overload fill(value)
+  #   Sets every element of `self` to `value` and clears any mask.
+  #   @param value [Object] the fill value.
+  #   @return [self]
+  def fill(value); end
+
+  # @overload fill_copy(value)
+  #   Returns a copy of `self` with every element set to `value`.
+  #   @param value [Object] the fill value.
+  #   @return [CArray] the filled copy.
+  def fill_copy(value); end
+
+  # @!endgroup
+
+  # @!group Index and address conversion
+
+  # @overload addr2index(addr)
+  #   Unravels a flat row-major address into per-axis indices, sized by
+  #   `self.shape`.  With an Integer `addr` returns N Integers; with a
+  #   CArray of addresses returns N CArrays of the same shape as `addr`
+  #   (mask propagated per cell).  In both cases the return is a Ruby
+  #   Array of length `self.ndim`, so `i, j = ca.addr2index(x)` unpacks
+  #   uniformly for scalar and vector inputs.
+  #   @param addr [Integer, CArray] a flat address in `0...elements`,
+  #     or a CArray of such addresses (arbitrary shape).
+  #   @return [Array<Integer>, Array<CArray>] one entry per axis.
+  #   @raise [ArgumentError] when any `addr` is out of range.
+  def addr2index(addr); end
+
+  # @overload index2addr(*index)
+  #   Folds per-axis indices into flat row-major address(es), using
+  #   `self.shape`.  With all-Integer indices returns a single Integer;
+  #   when any index is a CArray, returns a CArray of addresses whose
+  #   shape follows the first non-scalar input (other non-scalar inputs
+  #   must match that shape).  Mask propagates from the inputs.
+  #   @param index [Array<Integer, CArray>] one entry per axis.
+  #   @return [Integer, CArray] the flat address(es).
+  #   @raise [IndexError] on an out-of-range index.
+  #   @raise [ArgumentError] on shape mismatch between non-scalar inputs.
+  def index2addr(*index); end
+
+  # @overload addr2index(addr, shape:)
+  #   Class-form of {#addr2index} that takes an explicit `shape:` rather
+  #   than reading it from a receiver.  Useful for coordinate arithmetic
+  #   without allocating a template CArray.
+  #   @param addr [Integer, CArray] a flat address or a CArray of them.
+  #   @param shape [Array<Integer>] the row-major shape defining the grid.
+  #   @return [Array<Integer>, Array<CArray>] one entry per axis.
+  #   @raise [ArgumentError] when any `addr` is out of range or `shape:`
+  #     is missing.
+  def self.addr2index(addr, shape:); end
+
+  # @overload index2addr(*index, shape:)
+  #   Class-form of {#index2addr}.
+  #   @param index [Array<Integer, CArray>] one entry per axis.
+  #   @param shape [Array<Integer>] the row-major shape defining the grid.
+  #   @return [Integer, CArray] the flat address(es).
+  #   @raise [ArgumentError] on out-of-range index, shape mismatch, or
+  #     missing `shape:`.
+  def self.index2addr(*index, shape:); end
+
+  # @overload normalize_index(idx)
+  #   Returns a canonical form of the index array `idx` classified against
+  #   `self`'s shape (scalars normalised, `nil` for whole axes, `[start,
+  #   count, step]` for blocks).  Used to inspect how an index resolves.
+  #   @param idx [Array] the raw index spec.
+  #   @return [Array] the normalised per-axis index.
+  def normalize_index(idx); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_attribute.rb

@@ -0,0 +1,246 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_attribute.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Attributes
+
+  # @overload obj_type
+  #   Returns the object-type integer of `self` (e.g. `CA_OBJ_ARRAY`,
+  #   `CA_OBJ_BLOCK`).
+  #
+  #   Rarely needed in user code; the same information is available
+  #   from `self.class`.
+  #   @return [Integer]
+  def obj_type; end
+
+  # @!group Type inquiry
+
+  # @overload data_type
+  #   Returns the data type of each element as a Symbol (e.g. `:int32`,
+  #   `:float64`).
+  #   @return [Symbol]
+  def data_type; end
+
+  # @overload data_type_name
+  #   Returns the String name of `data_type` (e.g. `"int32"`,
+  #   `"fixlen"`).
+  #   @return [String]
+  def data_type_name; end
+
+  # @!group Attributes
+
+  # @overload ndim
+  #   Returns the number of dimensions of `self`.
+  #   @return [Integer]
+  def ndim; end
+
+  # @overload rank
+  #   @deprecated Use {#ndim}.
+  #   @return [Integer]
+  def rank; end
+
+  # @overload bytes
+  #   Returns the byte size of one element. Equals
+  #   `CArray.sizeof(data_type)` for numeric types; for fixed-length
+  #   types this method is the only way to obtain the size.
+  #   @return [Integer]
+  def bytes; end
+
+  # @overload flags
+  #   Returns the raw internal flag bitset (`ca->flags`) as an Integer.
+  #   The bits record structural facts about the array (scalar, Face,
+  #   view, read-only, …). This is a low-level provenance value with no
+  #   stable public meaning; it is exposed mainly so the `_CARRAY3`
+  #   serializer can snapshot it into a saved file's header.
+  #   @return [Integer]
+  def flags; end
+
+  # @overload elements
+  #   Returns the total number of elements (product of `shape`).
+  #   @return [Integer]
+  def elements; end
+
+  # @overload size
+  #   Alias of {#elements}.
+  #   @return [Integer]
+  def size; end
+
+  # @overload length
+  #   @deprecated Use {#elements} or {#size}.
+  #   @return [Integer]
+  def length; end
+
+  # @overload shape
+  #   Returns a freshly allocated Array containing the dimensional
+  #   shape of `self` (e.g. `[2, 3]` for a 2×3 array).
+  #
+  #   This is the recommended accessor. {#dim} is a legacy alias.
+  #   @return [Array<Integer>]
+  #   @example
+  #     CArray.float64(2, 3).shape  # => [2, 3]
+  def shape; end
+
+  # @overload dim
+  #   @deprecated Use {#shape}.
+  #   @return [Array<Integer>]
+  def dim; end
+
+  # @overload dim0
+  #   Returns `shape[0]`.
+  #   @return [Integer]
+  def dim0; end
+
+  # @overload dim1
+  #   Returns `shape[1]`, or `nil` if `ndim < 2`.
+  #   @return [Integer, nil]
+  def dim1; end
+
+  # @overload dim2
+  #   Returns `shape[2]`, or `nil` if `ndim < 3`.
+  #   @return [Integer, nil]
+  def dim2; end
+
+  # @overload dim3
+  #   Returns `shape[3]`, or `nil` if `ndim < 4`.
+  #   @return [Integer, nil]
+  def dim3; end
+
+  # @overload parent
+  #   Returns the parent CArray of `self`, or `nil` if `self` has no
+  #   parent (i.e. is an entity).
+  #   @return [CArray, nil]
+  def parent; end
+
+  # @overload root_array
+  #   Returns the array at the root of the view chain (the entity).
+  #   Returns `self` if `self` is already an entity.
+  #   @return [CArray]
+  def root_array; end
+
+  # @overload ancestors
+  #   Returns the list of arrays in the view chain, ordered from root
+  #   to `self`.
+  #   @return [Array<CArray>]
+  def ancestors; end
+
+  # @!group Type inquiry
+
+  # @overload data_class
+  #   Returns the `data_class` of `self` if it is a Face that carries
+  #   one (e.g. `CARecord`). Returns `nil` for non-Face arrays.
+  #   @return [Class, nil]
+  def data_class; end
+
+  # @overload data_class=(klass)
+  #   Always raises. `data_class` now lives on the Face tail
+  #   (`CARecord`); use `CARecord.new(klass, *shape)` or
+  #   `CARecord.wrap(entity, klass)` instead.
+  #   @param klass [Class] unused.
+  #   @return [void]
+  #   @raise [ArgumentError] always.
+  def data_class=(klass); end
+
+  # @!endgroup
+
+  # @!group State inquiry
+
+  # @overload scalar?
+  #   Returns `true` if `self` is a {CScalar}.
+  #   @return [Boolean]
+  def scalar?; end
+
+  # @overload entity?
+  #   Returns `true` if `self` is an entity array (not a virtual
+  #   view).
+  #   @return [Boolean]
+  def entity?; end
+
+  # @overload virtual?
+  #   Returns `true` if `self` is a virtual array (a view, not an
+  #   entity).
+  #   @return [Boolean]
+  def virtual?; end
+
+  # @overload attached?
+  #   Returns `true` if `self` is currently attached
+  #   (`ptr != NULL`).
+  #   @return [Boolean]
+  def attached?; end
+
+  # @overload empty?
+  #   Returns `true` if `self` has zero elements.
+  #   @return [Boolean]
+  def empty?; end
+
+  # @overload read_only?
+  #   Returns `true` if `self` is read-only.
+  #   @return [Boolean]
+  def read_only?; end
+
+  # @overload mask_array?
+  #   Returns `true` if `self` is itself a mask array. (Not the same
+  #   as "a masked array"; for that see {#has_mask?}.)
+  #   @return [Boolean]
+  def mask_array?; end
+
+  # @overload value_array?
+  #   Returns `true` if `self` is a value array (the `.value` view of
+  #   a masked array).
+  #   @return [Boolean]
+  def value_array?; end
+
+  # @!group Type inquiry
+
+  # @overload face?
+  #   Returns `true` if `self` is a Face view (`CA_FLAG_IS_FACE`
+  #   set).
+  #   @return [Boolean]
+  def face?; end
+
+  # @overload has_data_class?
+  #   Returns `true` if `self` carries a `data_class` (i.e. is a Face
+  #   such as `CARecord`).
+  #   @return [Boolean]
+  def has_data_class?; end
+
+  # @overload fixlen?
+  #   Returns `true` if `self` is a fixed-length type array.
+  #   @return [Boolean]
+  def fixlen?; end
+
+  # @overload boolean?
+  #   Returns `true` if `self` is a boolean type array.
+  #   @return [Boolean]
+  def boolean?; end
+
+  # @overload numeric?
+  #   Returns `true` if `self` is a numeric type array (any integer,
+  #   float, or complex type).
+  #   @return [Boolean]
+  def numeric?; end
+
+  # @overload integer?
+  #   Returns `true` if `self` is an integer type array (signed or
+  #   unsigned, any width).
+  #   @return [Boolean]
+  def integer?; end
+
+  # @overload float?
+  #   Returns `true` if `self` is a floating-point type array.
+  #   @return [Boolean]
+  def float?; end
+
+  # @overload complex?
+  #   Returns `true` if `self` is a complex type array.
+  #   @return [Boolean]
+  def complex?; end
+
+  # @overload object?
+  #   Returns `true` if `self` is an object type array
+  #   (`data_type == :object`).
+  #   @return [Boolean]
+  def object?; end
+
+  # @!endgroup
+end

data/yard-stubs/carray_broadcast.rb

@@ -0,0 +1,37 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_broadcast.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Views
+
+  # @overload broadcast_to(*shape)
+  #   Returns a read-only `CARepeat` view of `self` whose shape is
+  #   `shape`. Axes are paired right-to-left:
+  #
+  #   - matching extents reuse the source stride
+  #   - target extent `> 1` against source extent `1` repeats with
+  #     stride `0`
+  #   - extra leading target axes require the corresponding source
+  #     axis to be `1` (otherwise raises)
+  #
+  #   `CScalar` sources broadcast to any target shape with all
+  #   strides `0`.
+  #
+  #   The result is read-only because writes against a stride-0
+  #   axis would be ambiguous.
+  #   @param shape [Array<Integer>] target shape, with
+  #     `length >= self.ndim`.
+  #   @return [CArray]
+  #   @raise [RuntimeError] if a source axis cannot be paired with a
+  #     target axis (cross-ndim expansion is intentionally strict —
+  #     see {CArray.broadcast} for the explicit-`:_` / `:*` axis
+  #     declaration form).
+  #   @example
+  #     a = CArray.float64(3) { [1.0, 2.0, 3.0] }
+  #     a.broadcast_to(2, 3).to_a
+  #     # => [[1.0, 2.0, 3.0], [1.0, 2.0, 3.0]]
+  def broadcast_to(*shape); end
+
+  # @!endgroup
+end