carray 2.0.1 → 3.0.1

data/lib/carray.rb

@@ -1,72 +1,70 @@
-# ----------------------------------------------------------------------------
-#
-#  lib/carray.rb
-#
-#  This file is part of Ruby/CArray extension library.
-#
-#  Copyright (C) 2005-2025 Hiroki Motoyoshi
-#
-# ----------------------------------------------------------------------------
+# main
 
-major = RbConfig::CONFIG['MAJOR'].to_i
-minor = RbConfig::CONFIG['MINOR'].to_i
-teeny = RbConfig::CONFIG['TEENY'].to_i
-ruby_version_code = major * 100 + minor * 10 + teeny
+require 'carray_ext'
 
-if ruby_version_code < 190
-  require 'complex'
+# Top-level CAMath module -- math namespace for CArrays.
+# `CAMath.sin(ca)` works because module functions inherited
+# from Math (via include) accept any object that responds to
+# the corresponding instance method; CArray defines those in
+# C.
+module CAMath
+  include Math
 end
 
-# main 
-
-require 'carray_ext'
-
-require 'carray/inspect'
-require 'carray/basic'
+# carray/inspect is loaded lazily via autoload_carray (#inspect / #source_code
+# stubs). #inspect fires on the first p / pp / irb display or error-message
+# interpolation, so compute programs that never print a CArray skip it.
 require 'carray/construct'
-require 'carray/mask'
-require 'carray/compose'
-require 'carray/transform'
-require 'carray/convert'
-require 'carray/testing'
-require 'carray/ordering'
-require 'carray/broadcast'
+require 'carray/data_type_extension'
+# carray/stack is loaded lazily via autoload_carray (entry-method stubs).
+# CAStack is C-defined so its constant is always present; only the Ruby
+# composition surface (stack/meld/montage/split/append) needs the file.
+require 'carray/runtime'  # load-bearing Ruby support the core depends on
+require 'carray/basics'   # frequently-used convenience methods kept eager
+require 'carray/conditional'  # then_else / replace_where / conditional
+require 'carray/mask_gap_fill'  # unmask/strip_mask method: keyword (hold / linear gap-fill)
+require 'carray/attribute' # per-instance metadata Hash (#attribute / #has_attribute?)
+require 'carray/boolean_reduce' # all/any/none skip_masked: keyword (Kleene fold)
+require 'carray/meld_reduce'    # CAMeld per-parent reduce fast path (sum/mean/min/max along meld_axis)
+# carray/ordering CIFY (2026-06-21): translated to ext/carray_order.c
 
 require 'carray/math'
+# carray/clip_cast CIFY (2026-06-23): translated to ext/carray_cast.c
+require 'carray/complex' # real / imag accessors; MUST precede carray/lazy
+                         # (lazy aliases real/imag at load time)
+require 'carray/lazy'   # the lazy elementwise view layer
+# carray/face.rb was deleted (the Phase 1 skeleton CArray::Face module
+# became dead weight, replaced by C-layer macro deploy +
+# copy_state/storage_to_scalar convention).
+require 'carray/time'  # CATime / CATimedelta
+# carray/methods/* (bincount / broadcast / gather_nd+put_nd) are small
+# single-feature method files, loaded lazily via autoload_carray.
 require 'carray/iterator'
-require 'carray/struct'
-require 'carray/table'
-require 'carray/array'
-require 'carray/string'
-require 'carray/time'
+# carray/struct is loaded lazily via autoload_carray (constant + entry-method
+# stubs). Nothing in the eager core references CAStruct/CAUnion, so programs
+# that only use numeric arrays never pay its load cost.
+require 'carray/string_operation_extension'  # shared StringOperationMixin (must precede the Faces)
+require 'carray/const_string'   # CAConstString construction surface
+require 'carray/string'         # CAString construction surface
+require 'carray/fixlen_string'  # CAFixlenString construction surface
+# CArray.format lives in carray/methods/string_format.rb, autoloaded on first call
 
-# obsolete methods
+# carray/frame is loaded lazily via autoload_carray (CAFrame / GroupedFrame
+# constants). Nothing in the eager core references the frame, so programs that
+# only use arrays never pay its load cost.
 
-require 'carray/obsolete'
+# opt-in refinements (loaded on first reference to the constant)
 
-# autoload
+class CArray
+  autoload :CoreExtensions, 'carray/core_extensions'
+end
 
-unless $CARRAY_NO_AUTOLOAD 
-  
-  require 'carray/autoload'
-  require 'carray/autoload/autoload_base'
-  require 'carray/autoload/autoload_io_imagemagick'
-  require 'carray/autoload/autoload_math_histogram'
-  require 'carray/autoload/autoload_math_recurrence'
-  require 'carray/autoload/autoload_object_iterator'
-  require 'carray/autoload/autoload_object_link'
-  require 'carray/autoload/autoload_object_pack'
+# autoload
 
-  require 'carray/autoload/autoload_gem_random'
-  require 'carray/autoload/autoload_gem_gnuplot'
-  require 'carray/autoload/autoload_gem_narray'
-  require 'carray/autoload/autoload_gem_numo_narray'
-#  require 'carray/autoload/autoload_gem_io_csv'
-#  require 'carray/autoload/autoload_gem_io_sqlite3'
-#  require 'carray/autoload/autoload_gem_rmagick'
-#  require 'carray/autoload/autoload_gem_cairo'
-#  require 'carray/autoload/autoload_gem_opencv'
-#  require 'carray/autoload/autoload_gem_ffi'
+require 'carray/autoload_method_extension'
 
-  undef autoload_method
+class CArray
+  extend AutoloadMethodExtension
 end
+
+require 'carray/autoload_carray'

data/yard-stubs/ca_obj_array.rb

@@ -0,0 +1,385 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for constructor methods defined in ext/ca_obj_array.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Construction
+
+  # @overload initialize(data_type, shape)
+  #   Allocates a CArray of the given `data_type` and `shape`, with
+  #   storage left uninitialized (caller is expected to fill it).
+  #   @param data_type [Symbol, Integer, Class, String] element type.
+  #   @param shape [Array<Integer>] one extent per axis.
+  #   @return [self]
+  # @overload initialize(data_type, shape, bytes:)
+  #   For `data_type == :fixlen`, sets the per-element byte size.
+  #   Ignored for numeric types.
+  #   @param data_type [Symbol]
+  #   @param shape [Array<Integer>]
+  #   @param bytes [Integer]
+  #   @return [self]
+  # @overload initialize(data_type, shape) { value }
+  #   With a 0-arity block, calls the block once and broadcasts its
+  #   return value into every cell of the new array (scalar-fill fast
+  #   path). This is the dominant
+  #   `CArray.<type>(n) { value }` idiom.
+  #   @yieldreturn [Object] value to broadcast.
+  #   @return [self]
+  # @overload initialize(data_type, shape) { |*idx| ... }
+  #   With an n-arity block, calls the block once per cell with the
+  #   multi-dimensional index unpacked (`|i|` for 1-D, `|i, j|` for
+  #   2-D, etc.). The block's return value is stored at that cell.
+  #   @yieldparam idx [Array<Integer>] per-axis indices.
+  #   @yieldreturn [Object]
+  #   @return [self]
+  #
+  #   3.0 breaking: `CArray.new(MyStruct, ...)` no longer accepts a
+  #   user class as `data_type`. Use `CARecord.new(MyStruct, *shape)`
+  #   or define `class MyArr < CARecord; data_class MyStruct; end`.
+  def initialize(*); end
+
+  # @overload initialize_copy(other)
+  #   Implements `dup` / `clone` semantics: copies `other`'s
+  #   `data_type`, shape, mask, and element data into `self`. Result
+  #   is an independent entity.
+  #
+  #   Note that for views, `dup`/`clone` produce a new view sharing
+  #   the parent (Ruby shallow-copy semantics); use {#copy} when an
+  #   independent owned array is required.
+  #   @param other [CArray]
+  #   @return [self]
+  #   @api private
+  def initialize_copy(other); end
+
+  # @!endgroup
+
+  class << self
+    # @!group Construction (typed shorthands)
+    #
+    # `CArray.<type>` (no args) returns the typed class
+    # (`CArray::Float64`, `CArray::Int32`, ...). `CArray.<type>(*shape)`
+    # is a shorthand for `CArray.new(:<type>, shape)`. The shorthands
+    # accept the same optional block as `initialize`.
+
+    # @overload fixlen
+    #   Returns the typed class `CArray::Fixlen`.
+    #   @return [Class]
+    # @overload fixlen(*shape, bytes:) { ... }
+    #   Equivalent to `CArray.new(:fixlen, shape, bytes: bytes) { ... }`.
+    #   The `bytes:` keyword is required for `:fixlen`.
+    #   @param shape [Array<Integer>]
+    #   @param bytes [Integer]
+    #   @return [CArray]
+    def fixlen(*shape, bytes: nil); end
+
+    # @overload boolean
+    #   Returns the typed class `CArray::Boolean`.
+    #   @return [Class]
+    # @overload boolean(*shape) { ... }
+    #   Equivalent to `CArray.new(:boolean, shape) { ... }`.
+    #   @param shape [Array<Integer>]
+    #   @return [CArray]
+    def boolean(*shape); end
+
+    # @overload int8
+    #   Returns the typed class `CArray::Int8`.
+    #   @return [Class]
+    # @overload int8(*shape) { ... }
+    #   Equivalent to `CArray.new(:int8, shape) { ... }`.
+    #   @return [CArray]
+    def int8(*shape); end
+
+    # @overload uint8
+    #   Returns the typed class `CArray::UInt8`.
+    #   @return [Class]
+    # @overload uint8(*shape) { ... }
+    #   Equivalent to `CArray.new(:uint8, shape) { ... }`.
+    #   @return [CArray]
+    def uint8(*shape); end
+
+    # @overload int16
+    #   Returns the typed class `CArray::Int16`.
+    #   @return [Class]
+    # @overload int16(*shape) { ... }
+    #   Equivalent to `CArray.new(:int16, shape) { ... }`.
+    #   @return [CArray]
+    def int16(*shape); end
+
+    # @overload uint16
+    #   Returns the typed class `CArray::UInt16`.
+    #   @return [Class]
+    # @overload uint16(*shape) { ... }
+    #   Equivalent to `CArray.new(:uint16, shape) { ... }`.
+    #   @return [CArray]
+    def uint16(*shape); end
+
+    # @overload int32
+    #   Returns the typed class `CArray::Int32`.
+    #   @return [Class]
+    # @overload int32(*shape) { ... }
+    #   Equivalent to `CArray.new(:int32, shape) { ... }`.
+    #   @return [CArray]
+    def int32(*shape); end
+
+    # @overload uint32
+    #   Returns the typed class `CArray::UInt32`.
+    #   @return [Class]
+    # @overload uint32(*shape) { ... }
+    #   Equivalent to `CArray.new(:uint32, shape) { ... }`.
+    #   @return [CArray]
+    def uint32(*shape); end
+
+    # @overload int64
+    #   Returns the typed class `CArray::Int64`.
+    #   @return [Class]
+    # @overload int64(*shape) { ... }
+    #   Equivalent to `CArray.new(:int64, shape) { ... }`.
+    #   @return [CArray]
+    def int64(*shape); end
+
+    # @overload uint64
+    #   Returns the typed class `CArray::UInt64`.
+    #   @return [Class]
+    # @overload uint64(*shape) { ... }
+    #   Equivalent to `CArray.new(:uint64, shape) { ... }`.
+    #   @return [CArray]
+    def uint64(*shape); end
+
+    # @overload float32
+    #   Returns the typed class `CArray::Float32`.
+    #   @return [Class]
+    # @overload float32(*shape) { ... }
+    #   Equivalent to `CArray.new(:float32, shape) { ... }`.
+    #   @return [CArray]
+    def float32(*shape); end
+
+    # @overload float64
+    #   Returns the typed class `CArray::Float64`.
+    #   @return [Class]
+    # @overload float64(*shape) { ... }
+    #   Equivalent to `CArray.new(:float64, shape) { ... }`.
+    #   @return [CArray]
+    def float64(*shape); end
+
+    # @overload cmplx64
+    #   Returns the typed class `CArray::Cmplx64`.
+    #   @return [Class]
+    # @overload cmplx64(*shape) { ... }
+    #   Equivalent to `CArray.new(:cmplx64, shape) { ... }`.
+    #   @return [CArray]
+    def cmplx64(*shape); end
+
+    # @overload cmplx128
+    #   Returns the typed class `CArray::Cmplx128`.
+    #   @return [Class]
+    # @overload cmplx128(*shape) { ... }
+    #   Equivalent to `CArray.new(:cmplx128, shape) { ... }`.
+    #   @return [CArray]
+    def cmplx128(*shape); end
+
+    # @overload object
+    #   Returns the typed class `CArray::Object`.
+    #   @return [Class]
+    # @overload object(*shape) { ... }
+    #   Equivalent to `CArray.new(:object, shape) { ... }`.
+    #   @return [CArray]
+    def object(*shape); end
+
+    # @!endgroup
+
+    # @!group Construction (legacy-name aliases)
+
+    # @overload byte(*shape)
+    #   Alias of {.uint8}.
+    def byte(*shape); end
+
+    # @overload short(*shape)
+    #   Alias of {.int16}.
+    def short(*shape); end
+
+    # @overload int(*shape)
+    #   Alias of {.int32}.
+    def int(*shape); end
+
+    # @overload float(*shape)
+    #   Alias of {.float32}.
+    def float(*shape); end
+
+    # @overload double(*shape)
+    #   Alias of {.float64}.
+    def double(*shape); end
+
+    # @overload complex(*shape)
+    #   Alias of {.cmplx64}.
+    def complex(*shape); end
+
+    # @overload dcomplex(*shape)
+    #   Alias of {.cmplx128}.
+    def dcomplex(*shape); end
+
+    # @!endgroup
+
+    # @!group External memory wrapping
+
+    # @overload wrap(data_type, shape) { target }
+    #   Wraps an external memory block as a CAWrap. The block must
+    #   return a `target` object that defines `wrap_as_carray(obj)`,
+    #   which receives the freshly allocated CAWrap and is
+    #   responsible for setting its `ptr` field.
+    #
+    #   Use this when bridging to a memory source that does not
+    #   expose the MemoryView protocol (otherwise prefer
+    #   {.wrap_memory_view} / {.from_memory_view}).
+    #   @param data_type [Symbol]
+    #   @param shape [Array<Integer>]
+    #   @yieldreturn [#wrap_as_carray] external buffer holder.
+    #   @return [CAWrap]
+    def wrap(data_type, shape); end
+
+    # @!endgroup
+  end
+end
+
+class CScalar
+  # @!group Construction
+
+  # @overload initialize(data_type)
+  #   Allocates a CScalar (0-D CArray) of the given `data_type`.
+  #   @param data_type [Symbol, Integer, Class, String]
+  #   @return [self]
+  # @overload initialize(data_type, bytes:)
+  #   For `data_type == :fixlen`, sets the per-element byte size.
+  #   @param data_type [Symbol]
+  #   @param bytes [Integer]
+  #   @return [self]
+  # @overload initialize(data_type) { |scalar| ... }
+  #   Yields the freshly allocated scalar; the block's return value
+  #   is stored at the cell unless it is `scalar` itself.
+  #   @yieldparam scalar [CScalar]
+  #   @yieldreturn [Object]
+  #   @return [self]
+  def initialize(*); end
+
+  # @overload initialize_copy(other)
+  #   Copies `other`'s `data_type` and stored value into `self`.
+  #   @param other [CScalar]
+  #   @return [self]
+  #   @api private
+  def initialize_copy(other); end
+
+  # @!endgroup
+
+  class << self
+    # @!group Construction (typed shorthands)
+
+    # @overload fixlen(bytes:) { ... }
+    #   Equivalent to `CScalar.new(:fixlen, bytes: bytes) { ... }`.
+    #   @param bytes [Integer]
+    #   @return [CScalar]
+    def fixlen(bytes:); end
+
+    # @overload boolean { ... }
+    #   Equivalent to `CScalar.new(:boolean) { ... }`.
+    #   @return [CScalar]
+    def boolean; end
+
+    # @overload int8 { ... }
+    #   Equivalent to `CScalar.new(:int8) { ... }`.
+    #   @return [CScalar]
+    def int8; end
+
+    # @overload uint8 { ... }
+    #   Equivalent to `CScalar.new(:uint8) { ... }`.
+    #   @return [CScalar]
+    def uint8; end
+
+    # @overload int16 { ... }
+    #   Equivalent to `CScalar.new(:int16) { ... }`.
+    #   @return [CScalar]
+    def int16; end
+
+    # @overload uint16 { ... }
+    #   Equivalent to `CScalar.new(:uint16) { ... }`.
+    #   @return [CScalar]
+    def uint16; end
+
+    # @overload int32 { ... }
+    #   Equivalent to `CScalar.new(:int32) { ... }`.
+    #   @return [CScalar]
+    def int32; end
+
+    # @overload uint32 { ... }
+    #   Equivalent to `CScalar.new(:uint32) { ... }`.
+    #   @return [CScalar]
+    def uint32; end
+
+    # @overload int64 { ... }
+    #   Equivalent to `CScalar.new(:int64) { ... }`.
+    #   @return [CScalar]
+    def int64; end
+
+    # @overload uint64 { ... }
+    #   Equivalent to `CScalar.new(:uint64) { ... }`.
+    #   @return [CScalar]
+    def uint64; end
+
+    # @overload float32 { ... }
+    #   Equivalent to `CScalar.new(:float32) { ... }`.
+    #   @return [CScalar]
+    def float32; end
+
+    # @overload float64 { ... }
+    #   Equivalent to `CScalar.new(:float64) { ... }`.
+    #   @return [CScalar]
+    def float64; end
+
+    # @overload cmplx64 { ... }
+    #   Equivalent to `CScalar.new(:cmplx64) { ... }`.
+    #   @return [CScalar]
+    def cmplx64; end
+
+    # @overload cmplx128 { ... }
+    #   Equivalent to `CScalar.new(:cmplx128) { ... }`.
+    #   @return [CScalar]
+    def cmplx128; end
+
+    # @overload object { ... }
+    #   Equivalent to `CScalar.new(:object) { ... }`.
+    #   @return [CScalar]
+    def object; end
+
+    # @!endgroup
+
+    # @!group Construction (legacy-name aliases)
+
+    # @overload byte
+    #   Alias of {.uint8}.
+    def byte; end
+
+    # @overload short
+    #   Alias of {.int16}.
+    def short; end
+
+    # @overload int
+    #   Alias of {.int32}.
+    def int; end
+
+    # @overload float
+    #   Alias of {.float32}.
+    def float; end
+
+    # @overload double
+    #   Alias of {.float64}.
+    def double; end
+
+    # @overload complex
+    #   Alias of {.cmplx64}.
+    def complex; end
+
+    # @overload dcomplex
+    #   Alias of {.cmplx128}.
+    def dcomplex; end
+
+    # @!endgroup
+  end
+end

data/yard-stubs/ca_obj_bitarray.rb

@@ -0,0 +1,38 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CABitarray and CArray#bitarray defined in ext/ca_obj_bitarray.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Per-bit expansion view of the parent.  Every parent cell is fanned
+# out into `parent.bytes * 8` boolean cells along a trailing bit
+# axis appended after the parent's own axes, so the view's shape is
+# `[*parent.shape, parent.bytes * 8]` and its `data_type` is
+# `:boolean`.
+#
+# On big-endian hosts the bit axis of a non-fixlen parent reflects
+# network byte order (parent bytes are walked in reverse within each
+# element); single-byte parents are linear on either endian.
+class CABitarray < CAView
+end
+
+class CArray
+  # @!group Views
+
+  # Returns a {CABitarray} view of `self`, exposing every bit of
+  # every parent cell as an individual boolean cell.  See
+  # {CABitarray} for the axis layout and endian handling.
+  #
+  # Aliased as `bits`.
+  #
+  # @overload bitarray
+  #   @return [CABitarray]
+  #   @raise [CADataTypeError] when `self.data_type` is a complex or
+  #     object type (bit-level access is not defined for those).
+  def bitarray; end
+
+  # Alias for {#bitarray}.
+  #
+  # @return [CABitarray]
+  def bits; end
+
+  # @!endgroup
+end

data/yard-stubs/ca_obj_bitfield.rb

@@ -0,0 +1,43 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CABitfield and CArray#bitfield defined in ext/ca_obj_bitfield.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Bit-field extraction view: each cell of `self` carries a contiguous
+# bit field of the parent, exposed as an unsigned-integer (or boolean
+# when the field is 1 bit wide) CArray of the same shape.  Writes
+# through the view are read-modify-write against the parent — bits
+# outside the field are preserved.
+class CABitfield < CAView
+end
+
+class CArray
+  # @!group Views
+
+  # Returns a {CABitfield} view of `self`.  Each parent cell is
+  # treated as a bag of bits; `range` selects a contiguous slice of
+  # those bits, and the resulting view exposes that slice as a cell
+  # of the returned array.
+  #
+  # `range` may be an integer (a single bit — the resulting view has
+  # `data_type :boolean`) or a `Range` covering the bit positions.
+  # The `data_type` of the view is chosen from the bit width:
+  # 1 bit → `:boolean`, 2..8 → `:uint8`, 9..16 → `:uint16`,
+  # 17..32 → `:uint32`, 33..64 → `:uint64`.
+  #
+  # `type` is accepted but currently ignored (the width-derived type
+  # is always used).
+  #
+  # @overload bitfield(range, type = nil)
+  #   @param range [Integer, Range] bit position (single bit) or bit
+  #     range within one parent cell.
+  #   @param type [Symbol, nil] reserved, currently ignored.
+  #   @return [CABitfield]
+  #   @raise [IndexError] when `range` extends past the parent's bit
+  #     width, when the range has a step != 1, or when the bit length
+  #     is outside `1..64`.
+  #   @raise [ArgumentError] when the derived bit length exceeds the
+  #     resolved data type.
+  def bitfield(range, type = nil); end
+
+  # @!endgroup
+end

data/yard-stubs/ca_obj_block.rb

@@ -0,0 +1,73 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CABlock accessors and address helpers defined in
+# ext/ca_obj_block.c.  The CABlock class shell lives in
+# yard-stubs/ruby_carray.rb.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CABlock
+  # @!group Block geometry
+
+  # @overload size0
+  #   Returns the parent dimension sizes that the block is carved
+  #   from (one Integer per axis).  Distinct from `shape`, which is
+  #   the block's own shape (= `count` after step / stride logic).
+  #   @return [Array<Integer>]
+  def size0; end
+
+  # @overload start
+  #   Returns the starting index of the block within the parent, per
+  #   axis.
+  #   @return [Array<Integer>]
+  def start; end
+
+  # @overload step
+  #   Returns the per-axis step (stride in parent index units) the
+  #   block walks the parent with.
+  #   @return [Array<Integer>]
+  def step; end
+
+  # @overload count
+  #   Returns the per-axis number of elements the block exposes.
+  #   Same as `shape`.
+  #   @return [Array<Integer>]
+  def count; end
+
+  # @overload offset
+  #   Returns the block's base flat offset into the parent (in
+  #   element units), set at construction and adjusted as start[]
+  #   moves.
+  #   @return [Integer]
+  def offset; end
+
+  # @!endgroup
+
+  # @!group Address mapping
+
+  # @overload idx2addr0(*idx)
+  #   Maps a per-axis view index tuple to the corresponding flat
+  #   address into the parent (= "addr0").  Useful for projecting a
+  #   view-local coordinate back onto the parent's buffer.
+  #   @param idx [Array<Integer>] one Integer per axis;
+  #     `idx.length == self.ndim` is required.
+  #   @return [Integer]
+  #   @raise [ArgumentError] when the number of args does not equal
+  #     `self.ndim`.
+  #   @raise [IndexError] when any `idx[k]` is out of range for the
+  #     block's `shape[k]`.
+  def idx2addr0(*idx); end
+
+  # @overload index2addr0(*idx)
+  #   Alias of {#idx2addr0}.
+  def index2addr0(*idx); end
+
+  # @overload addr2addr0(addr)
+  #   Flat-address variant of {#idx2addr0}.  Unravels the block-local
+  #   flat `addr` into a multi-dim index, then maps that to the
+  #   parent's flat address.
+  #   @param addr [Integer] block-local flat address
+  #     (`0...self.elements`).
+  #   @return [Integer]
+  def addr2addr0(addr); end
+
+  # @!endgroup
+end