carray 2.0.0 → 3.0.0

data/lib/carray/complex.rb

@@ -0,0 +1,150 @@
+# Complex-component accessors (real / real= / imag / imag= / real? /
+# is_real).  Loaded eagerly BEFORE carray/lazy.rb, because lazy.rb does
+# `alias_method :__real_eager__, :real` (and the imag equivalent) at load
+# time -- these defs must exist by then.
+
+class CArray
+
+  # complex number
+  #
+  # ---------------------------------------------------------------------------
+  # DO NOT RETIRE real / real= / imag / imag= IN FAVOUR OF THE LAZY FRAMEWORK
+  # ---------------------------------------------------------------------------
+  #
+  # A recurring temptation is to consider these methods redundant now that the
+  # lazy substrate provides `c.lazy.real` / `c.lazy.imag` via CAMonOp chains
+  # (cast_<float> for real; imag_i + cast_<float> for imag — see
+  # lib/carray/lazy.rb).  They are NOT redundant.  The two paths are
+  # **complementary** and serve different abstractions:
+  #
+  #   c.real        (here)          -> CAField:  mutable zero-copy view into
+  #                                              the byte slot of complex
+  #                                              storage.  Read AND write.
+  #   c.lazy.real   (lazy.rb)       -> CAMonOp:  read-only lazy chain node
+  #                                              for streaming consumption.
+  #
+  # The CAField path supports in-place mutation idioms that the lazy framework
+  # cannot express:
+  #
+  #   c = CArray.cmplx128(10)
+  #   c.real.seq!(1)        # write 1..10 into real slot, zero-copy
+  #   c.imag.seq!(-1,-1)    # write -1..-10 into imag slot
+  #   c.real = some_array   # bulk write into real slot
+  #
+  # These are used by spec/Features/feature_stat_spec.rb and by user code
+  # patterns CArray's "byte-slot mutable view" capability is designed to
+  # support (= writing to `.real` stores into the real part in place;
+  # CAField makes it a zero-copy abstraction available across all
+  # CAStride-based view algebra).
+  #
+  # Architecturally:
+  #   - lib/carray/lazy.rb's `real`/`imag` overrides dispatch to CAMonOp
+  #     when self is a lazy view, and fall through to the defs here for eager
+  #     parents (via `alias_method :__real_eager__, :real` at load time).
+  #     This file MUST be required before carray/lazy.rb (see carray.rb), and
+  #     removing these defs would break that alias and the lazy.rb load.
+  #
+  #   - ext/ca_obj_stride.c recognises `CAField .real/.imag over complex`
+  #     as a first-class byte-mismatched reinterpret pattern.  Architectural
+  #     commitment is already written into the C layer.
+  #
+  # Outright deletion is a regression on a documented capability (the lazy
+  # framework's read-only chain does not replace the CAField mutable view).
+  # ---------------------------------------------------------------------------
+
+  # @overload real
+  #   Returns the real part of `self` as a zero-copy view. For a
+  #   complex array the view is a mutable {CAField} into the
+  #   real-part slot; for a real numeric array it is a {CARefer}
+  #   over `self`. Writing to the view updates `self` in place.
+  #   @return [CArray]
+  def real
+    if not @__real__
+      if complex?
+        @__real__ = case data_type
+                    when CA_CMPLX64
+                      field(0, CA_FLOAT32)
+                    when CA_CMPLX128
+                      field(0, CA_FLOAT64)
+                    end
+      else
+        @__real__ = self[]
+      end
+    end
+    @__real__
+  end
+
+  # @overload real=(val)
+  #   Sets the real-part slot to `val` via {#real}.
+  #   @param val [CArray, Numeric] value to broadcast.
+  #   @return [Object] `val`.
+  def real= (val)
+    real[] = val
+  end
+
+  # @overload imag
+  #   Returns the imaginary part of `self`. For a complex array the
+  #   result is a mutable {CAField} view of the imaginary slot;
+  #   writing to it updates `self` in place. For a real array the
+  #   result is a fresh independent CArray filled with 0.
+  #   @return [CArray]
+  def imag
+    if not @__imag__
+      if complex?
+        @__imag__ = case data_type
+                    when CA_CMPLX64
+                      field(4, CA_FLOAT32)
+                    when CA_CMPLX128
+                      field(8, CA_FLOAT64)
+                    end
+      else
+        @__imag__ = self.template { 0 }
+      end
+    end
+    return @__imag__
+  end
+
+  # @overload imag=(val)
+  #   Sets the imaginary-part slot to `val` (complex arrays only).
+  #   @param val [CArray, Numeric] value to broadcast.
+  #   @return [Object] `val`.
+  #   @raise [RuntimeError] when `self` is not a complex array.
+  def imag= (val)
+    if complex?
+      imag[] = val
+    else
+      raise "not a complex array"
+    end
+  end
+
+  # @overload real?
+  #   Returns whether every element of `self` is real (imaginary
+  #   part is zero for complex arrays; always `true` for real
+  #   numeric arrays; `nil` for non-numeric arrays).
+  #   @return [Boolean, nil]
+  def real?
+    if complex?
+      imag.eq(0).all
+    elsif numeric?
+      true
+    else
+      nil
+    end
+  end
+
+  # @overload is_real
+  #   Returns an element-wise boolean CArray marking cells whose
+  #   imaginary part is zero (all-true for real numeric arrays,
+  #   `nil` for non-numeric arrays).
+  #   @return [CArray, nil]
+  def is_real
+    if complex?
+      imag.eq(0)
+    elsif numeric?
+      self.true
+    else
+      nil
+    end
+  end
+
+end

data/lib/carray/conditional.rb

@@ -0,0 +1,216 @@
+# ----------------------------------------------------------------------------
+#
+#  carray/conditional.rb
+#
+#  Element-wise conditional selection primitives.  Three flavours share the
+#  same "pick a value per cell based on a boolean condition" contract but
+#  differ in where the condition lives and how the branches are supplied:
+#
+#      cond.then_else(x, y)                  # boolean receiver, 2 values (eager)
+#      self.replace_where(cond, b)           # value receiver, 1 replacement (eager)
+#      self.conditional(cond, f_then, f_else) # value receiver, 2 callables (per-region)
+#
+#  `then_else` and `replace_where` evaluate both branches over the full array
+#  and pick per cell — fast but requires every branch to be domain-safe over
+#  the whole receiver.  `conditional` extracts the two subsets first and
+#  applies each callable only to its own region, which is domain-safe by
+#  construction (e.g. `x.log` is never evaluated on negative cells).
+#
+# ----------------------------------------------------------------------------
+
+class CArray
+
+  # @overload then_else(x, y)
+  #   Returns a ternary selection on `self` (a boolean CArray),
+  #   reading as "if `self` then `x` else `y`". The boolean 2-way
+  #   case of {#choose} that additionally propagates `self`'s mask
+  #   (`UNDEF` in `self` produces `UNDEF` in the result).
+  #   @param x [CArray, Numeric, Object] true-branch value(s).
+  #   @param y [CArray, Numeric, Object] false-branch value(s).
+  #   @return [CArray] new array with the same shape as `self`.
+  #   @raise [ArgumentError] when `self` is not a boolean CArray.
+  def then_else (x, y)
+    # Guard: self must be boolean.  Integer / float receiver would be
+    # silently reinterpreted by the indexer setter (`result[self] = ...`)
+    # as an index array, producing surprising scatter rather than the
+    # intended ternary select.  Fail fast.
+    unless self.boolean?
+      raise ArgumentError,
+            "then_else: receiver must be a boolean CArray (data_type == CA_BOOLEAN), got #{self.data_type}"
+    end
+    # Promote data_type from both branches via CArray.result_type
+    # (a CScalar contributes its own data_type, so CA_INT32(0) keeps int32
+    # where a bare Ruby Integer would widen to int64).
+    dt = CArray.result_type(x, y)
+    # A CScalar (scalar? CArray) is treated as a scalar value, not as a
+    # self-shaped operand: full CArray -> gather/copy, scalar -> broadcast.
+    y_full = y.is_a?(CArray) && !y.scalar?
+    result =
+      if y_full
+        y.data_type == dt ? y.copy : y.to_type(dt)
+      else
+        CArray.new(dt, self.shape).fill(y.is_a?(CArray) ? y[0] : y)
+      end
+    x_full = x.is_a?(CArray) && !x.scalar?
+    result[self] = x_full ? x[self] : x
+    # Propagate cond's mask: UNDEF in self -> UNDEF in result.
+    if self.has_mask?
+      result[self.is_masked] = UNDEF
+    end
+    result
+  end
+
+  # @overload replace_where(cond, b)
+  #   Returns a copy of `self` with cells where `cond` is true
+  #   replaced by `b`. Functional sibling of the destructive
+  #   indexer `a[cond] = b`; mask handling matches the indexer.
+  #   Preserves `self`'s `data_type` (unlike {#then_else}, which
+  #   promotes via `CArray.result_type`).
+  #   @param cond [CArray] boolean selector; same shape as `self`
+  #     or broadcastable.
+  #   @param b [CArray, Numeric, Object] replacement value(s).
+  #   @return [CArray] new array.
+  #   @raise [ArgumentError] when `cond` is not a boolean CArray.
+  def replace_where (cond, b)
+    unless cond.is_a?(CArray) && cond.boolean?
+      raise ArgumentError,
+            "replace_where: cond must be a boolean CArray (data_type == CA_BOOLEAN)"
+    end
+    result = self.copy
+    result[cond] = b.is_a?(CArray) ? b[cond] : b
+    result
+  end
+
+  # @overload conditional(cond, then_fn, else_fn, dtype: nil)
+  #   Returns per-cell `then_fn.call(self[cond])` where `cond` is
+  #   true and `else_fn.call(self[cond.not])` where it is false.
+  #   The two callables are applied only to their own subset of
+  #   `self`, so a branch that would fail on the other region
+  #   (e.g. `->(v) { v.log }` on negative cells) stays safe.
+  #
+  #   Scalar returns from a callable (e.g. `->(v) { 0 }`) broadcast
+  #   to the subset shape. The result `data_type` is the promotion
+  #   of the two subset results via `CArray.result_type`, or
+  #   `dtype` when given. Masked cells in `cond` propagate to
+  #   `UNDEF` in the result.
+  #
+  #   @param cond [CArray] boolean selector; same shape as `self`.
+  #   @param then_fn [#call] callable applied to `self[cond]`.
+  #   @param else_fn [#call] callable applied to `self[cond.not]`.
+  #   @param dtype [Symbol, Integer, nil] override for the result
+  #     `data_type`.
+  #   @return [CArray] new array with the same shape as `self`.
+  #   @raise [ArgumentError] when `cond` is not a same-shape
+  #     boolean CArray.
+  #   @example
+  #     x = CArray.float64(6).span(-2.0..3.0)
+  #     x.conditional(x > 0,
+  #                   ->(v) { v.log },        # domain-safe: only positive cells
+  #                   ->(v) { -v })
+  #     # => [2.0, 1.0, -0.0, 0.0, 0.6931..., 1.0986...]
+  def conditional (cond, then_fn, else_fn, dtype: nil)
+    unless cond.is_a?(CArray) && cond.boolean? && cond.shape == self.shape
+      raise ArgumentError,
+            "conditional: cond must be a boolean CArray with same shape as self"
+    end
+
+    x_then = self[cond]
+    x_else = self[cond.not]
+    y_then = then_fn.call(x_then)
+    y_else = else_fn.call(x_else)
+
+    # A callable that returns a scalar (e.g. `->(v) { 0 }`) broadcasts
+    # to the subset shape; wrap it here so the scatter step below sees a
+    # same-length CArray.
+    unless y_then.is_a?(CArray)
+      y_then = CArray.new(dtype || CArray.result_type(y_then), x_then.shape).fill(y_then)
+    end
+    unless y_else.is_a?(CArray)
+      y_else = CArray.new(dtype || CArray.result_type(y_else), x_else.shape).fill(y_else)
+    end
+
+    dt  = dtype || CArray.result_type(y_then, y_else)
+    out = CArray.new(dt, self.shape)
+    out[cond]     = y_then
+    out[cond.not] = y_else
+    # Propagate cond's mask (mirrors then_else's rule): UNDEF in cond ->
+    # UNDEF in out.  Kleene `cond.not` also carries UNDEF at the same
+    # positions, so both scatters leave the cell untouched — an explicit
+    # fix-up is required.
+    out[cond.is_masked] = UNDEF if cond.has_mask?
+    out
+  end
+
+  # @overload select(condlist, choicelist, default: 0, dtype: nil)
+  #   Multi-way ternary select: for each cell, picks the value from
+  #   the first `choicelist[k]` whose matching `condlist[k]` is true,
+  #   falling back to `default` when no condition holds. When several
+  #   conditions overlap, the earliest one in `condlist` wins.
+  #
+  #   All entries in `condlist` must be same-shape boolean CArrays.
+  #   Each `choicelist[k]` is either a same-shape CArray or a scalar
+  #   broadcast to every cell. The result `data_type` is the promotion
+  #   of every choice plus `default` via `CArray.result_type`, or
+  #   `dtype` when given.
+  #
+  #   @param condlist [Array<CArray>] boolean selectors.
+  #   @param choicelist [Array<CArray, Numeric, Object>] values, one
+  #     per condition (same length as `condlist`).
+  #   @param default [CArray, Numeric, Object] value written where no
+  #     condition holds.
+  #   @param dtype [Symbol, Integer, nil] override for the result
+  #     `data_type`.
+  #   @return [CArray] new array with the shape of `condlist[0]`.
+  #   @raise [ArgumentError] on size mismatch, empty `condlist`, or a
+  #     non-boolean / wrong-shape entry in `condlist`.
+  #   @example
+  #     x = CArray.float64(6).span(-5.0..5.0)
+  #     CArray.select([x < 0, x < 2],
+  #                   [-x,    x * 10],
+  #                   default: 999)
+  #     # => [5.0, 3.0, -10.0, 0.0, 10.0, 999.0]
+  def self.select (condlist, choicelist, default: 0, dtype: nil)
+    unless condlist.is_a?(Array) && choicelist.is_a?(Array)
+      raise ArgumentError, "select: condlist and choicelist must be Arrays"
+    end
+    if condlist.size != choicelist.size
+      raise ArgumentError,
+            "select: condlist (#{condlist.size}) and choicelist (#{choicelist.size}) size mismatch"
+    end
+    if condlist.empty?
+      raise ArgumentError, "select: at least one condition required"
+    end
+
+    first = condlist.first
+    unless first.is_a?(CArray) && first.boolean?
+      raise ArgumentError, "select: condlist[0] must be a boolean CArray"
+    end
+    shape = first.shape
+
+    dt = dtype || CArray.result_type(*choicelist, default)
+    # `default` can be either a same-shape CArray (per-cell fallback) or a
+    # scalar (broadcast to every cell).
+    default_full = default.is_a?(CArray) && !default.scalar?
+    out =
+      if default_full
+        default.data_type == dt ? default.copy : default.to_type(dt)
+      else
+        CArray.new(dt, shape).fill(default.is_a?(CArray) ? default[0] : default)
+      end
+
+    # Iterate from lowest priority to highest (reverse) so the earliest
+    # entry in `condlist` ends up on top — matches `np.select`'s
+    # first-match semantics.
+    (condlist.size - 1).downto(0) do |k|
+      c = condlist[k]
+      unless c.is_a?(CArray) && c.boolean? && c.shape == shape
+        raise ArgumentError,
+              "select: condlist[#{k}] must be a same-shape boolean CArray"
+      end
+      v = choicelist[k]
+      out[c] = v.is_a?(CArray) ? v[c] : v
+    end
+    out
+  end
+
+end

data/lib/carray/const_string.rb

@@ -0,0 +1,228 @@
+# ----------------------------------------------------------------------------
+#
+#  carray/const_string.rb
+#
+#  CAConstString high-level construction + conversion surface.
+#
+#  CAConstString itself (the Face + tail buffer + fetch decode + numeric gate) lives
+#  in ext/ca_obj_const_string.c.  This file provides the ergonomic builders that pack
+#  Ruby Strings into the internal length-prefix buffer + int64 offset entity
+#  and wrap them via the CAConstString.wrap C primitive.
+#
+#  Internal buffer format: concatenation of `[int32 length][bytes...]` records
+#  (self-delimiting → one offset per element, permutation-safe view).
+#
+# ----------------------------------------------------------------------------
+
+class CArray
+
+  # Build a CAConstString (read-only variable-length string column) from Ruby data.
+  #
+  #     CArray.const_string(["alpha", "", "gamma"])       # 1-D from Array
+  #     CArray.const_string(3) { |i| "item#{i}" }         # block form
+  #     CArray.const_string([a, nil, b])                   # nil → masked element
+  #
+  # B1: "" (length 0) is a valid empty string, distinct from a masked element
+  #     (nil → masked).  B2: element encoding must match :encoding (strict),
+  #     pure-ASCII strings pass regardless (ASCII-compatible relaxation).
+  #
+  # Storage is one `(start, end)` byte-range pair per element over a
+  # pure-concatenation buffer (Arrow string layout).  For a high-duplication
+  # column (categorical labels), use {CACategorical} (= Arrow DictionaryArray)
+  # instead — CAConstString stores every element's bytes, without dedup.
+  # @overload const_string(values, encoding: Encoding::UTF_8)
+  #   Returns a read-only {CAConstString} column packing each String's
+  #   bytes into a shared buffer. `values` may be any Array (or
+  #   Array-like) of Strings; `nil` entries are masked.
+  #   @param values [Array<String, nil>] source values.
+  #   @param encoding [Encoding] column encoding.
+  #   @return [CAConstString]
+  # @overload const_string(ca, encoding: Encoding::UTF_8)
+  #   Builds from a string-bearing CArray (String Face / CA_OBJECT / raw
+  #   CA_FIXLEN, the last read as NUL-stripped strings); always materialises.
+  #   @param ca [CArray] source array.
+  #   @return [CAConstString]
+  #   @raise [CArray::DataTypeError] if `ca` is numeric / boolean.
+  # @overload const_string(n, encoding: Encoding::UTF_8) { |i| ... }
+  #   Returns an `n`-element {CAConstString} column filled by the
+  #   block, following the arity-0 broadcast convention.
+  #   @param n [Integer] element count.
+  #   @yieldparam i [Integer] cell index.
+  #   @yieldreturn [String, nil] value for cell `i`.
+  #   @return [CAConstString]
+  def self.const_string (arg, encoding: Encoding::UTF_8, &block)
+    if arg.is_a?(CArray)
+      return string_face_of(arg).to_const_string(encoding: encoding)
+    end
+    if block
+      n = Integer(arg)
+      # B5: follow CArray.<type>(n){ ... } arity-0 broadcast quirk for
+      #     consistency — arity-0 block is evaluated once and broadcast.
+      if block.arity == 0
+        v = block.call
+        values = Array.new(n) { v }
+      else
+        values = Array.new(n) { |i| block.call(i) }
+      end
+    else
+      values = arg.to_a
+    end
+
+    # Arrow-style layout, built in one C pass: pure-concatenation buffer +
+    # one (start,end) int64 pair per element, mask for nil.
+    CAConstString.__build__(values, encoding)
+  end
+
+end
+
+# Read-only column of variable-length Strings: every element's bytes are
+# packed into one shared buffer, with a `(start, end)` byte-range pair per
+# element (the Arrow string layout).
+#
+# Built through `CArray.const_string`.  For a column with heavy duplication
+# (categorical labels) prefer {CACategorical}, which stores each distinct
+# value once.
+class CAConstString
+
+  # Read-only String Face: L1 string operations only (no in-place Mutable).
+  # Its C-native byte predicates / search / comparison (ext/ca_obj_const_string.c)
+  # override the L1 generics where present.
+  include CArray::StringOperationMixin
+
+  # @overload sort
+  #   Returns a byte-order sorted view built by gathering the
+  #   offsets with `sort_index`. Neither bytes nor offsets are
+  #   copied.
+  #   @return [CAConstString]
+  def sort
+    self[sort_index]
+  end
+
+  # @overload sort_copy
+  #   Returns an owned sorted {CAConstString}; the materialised
+  #   counterpart to {#sort}.
+  #   @return [CAConstString]
+  def sort_copy
+    self[sort_index].copy
+  end
+
+  # CAConstString is the one Face with three separate entities -- storage
+  # (int64 offset), surface (fixlen), and the length-prefixed buffer -- so it
+  # has no byte-compatible blank form (other Faces have surface == storage or
+  # a struct tail, which the core template lift handles).  A same-class
+  # template would be an unusable shell, so override it: with an explicit type
+  # defer to the generic (plain) path; with no type return a plain same-shape
+  # `object` array (a fillable string container), honouring a block.
+  # @overload template(type = nil, **opts)
+  #   @return [CArray]
+  def template (*args, &block)
+    return super unless args.empty?    # a type was given: generic plain path
+    out = CArray.object(*shape)
+    if block
+      if block.arity == 0
+        out[] = block.call
+      else
+        out.map_with_index! { |_, *idx| block.call(*idx) }
+      end
+    end
+    out
+  end
+
+  # ---- value-hash discovery family --------------------------------------
+  #
+  # A storage cell is a `(start, end)` byte range into the shared buffer, so
+  # storage equality is NOT string equality: "ab" appearing twice occupies two
+  # distinct ranges.  The family's Face gate only descends a Face whose storage
+  # equality *is* its surface equality (docs/authoring/FaceOrderingSearch.md
+  # §5.0), and CAConstString is the Face it deliberately excludes -- without
+  # these overrides `%w[ab cd ab ef].nunique` answered 4.
+  #
+  # So the family runs on {#to_string}, where a cell *is* the string, and value
+  # outputs come back as a CAConstString.  Counts, booleans and addresses need
+  # no conversion.
+
+  # @overload unique(sort: false)
+  #   @return [CAConstString] the distinct strings.
+  def unique (sort: false)
+    to_string.unique(sort: sort).to_const_string
+  end
+
+  # @overload value_counts(sort: false)
+  #   @return [Array(CAConstString, CArray)] `[values, counts]`.
+  def value_counts (sort: false)
+    values, counts = to_string.value_counts(sort: sort)
+    [values.to_const_string, counts]
+  end
+
+  # @overload nunique(axis: nil, keep_axis: false)
+  #   @return [Integer, CArray] the number of distinct strings.
+  def nunique (axis: nil, keep_axis: false)
+    to_string.nunique(axis: axis, keep_axis: keep_axis)
+  end
+
+  # @overload mode(axis: nil)
+  #   @return [CAConstString, Array] the most frequent string(s).
+  def mode (axis: nil)
+    r = to_string.mode(axis: axis)
+    case r
+    when CArray then r.to_const_string
+    when Array  then r.map { |c| c.is_a?(CArray) ? c.to_const_string : c }
+    else r
+    end
+  end
+
+  # @overload is_mode(axis: nil)
+  #   @return [CArray] boolean, true where the cell holds a modal string.
+  def is_mode (axis: nil)
+    to_string.is_mode(axis: axis)
+  end
+
+  # @overload mask_duplicates(axis: nil)
+  #   @return [CAConstString] a copy with every repeat occurrence masked.
+  def mask_duplicates (axis: nil)
+    to_string.mask_duplicates(axis: axis).to_const_string
+  end
+
+  # @overload is_in(values)
+  #   @return [CArray] boolean, true where the cell's string is in `values`.
+  def is_in (values)
+    to_string.is_in(string_operand(values))
+  end
+
+  # @overload intersection(other, sort: false)
+  #   @return [CAConstString] the distinct strings present in both.
+  def intersection (other, sort: false)
+    to_string.intersection(string_operand(other), sort: sort).to_const_string
+  end
+
+  # @overload difference(other, sort: false)
+  #   @return [CAConstString] the distinct strings only `self` has.
+  def difference (other, sort: false)
+    to_string.difference(string_operand(other), sort: sort).to_const_string
+  end
+
+  # @overload union(other, sort: false)
+  #   @return [CAConstString] the distinct strings of either side.
+  def union (other, sort: false)
+    to_string.union(string_operand(other), sort: sort).to_const_string
+  end
+
+  # @overload locate_addr(ref)
+  #   @return [CArray] for each cell, its address in `ref` (UNDEF when absent).
+  def locate_addr (ref)
+    to_string.locate_addr(string_operand(ref))
+  end
+
+  # @overload categorize(labels: nil, sort_labels: false)
+  #   @return [CACategorical] categories keyed on the strings.
+  def categorize (labels: nil, sort_labels: false)
+    to_string.categorize(labels: labels, sort_labels: sort_labels)
+  end
+
+  # A CAConstString operand has to be decoded too; anything else (a CAString,
+  # an object array, an Array) already compares as strings.
+  private def string_operand (other)
+    other.is_a?(CAConstString) ? other.to_string : other
+  end
+
+end