carray 3.0.0 → 3.0.2

data/lib/carray/lazy.rb

@@ -73,11 +73,11 @@ class CArray
     rad_2pi: CAMonOp::OP_RAD_2PI,
     rad_pi:  CAMonOp::OP_RAD_PI,
 
-    # Sign function (preserve dtype).  bool/uint → 0/1, sint → -1/0/1,
+    # Sign function (preserves the data type).  bool/uint → 0/1, sint → -1/0/1,
     # float → -1/0/1 NaN-preserving, complex → unit vector or 0.
     sign:    CAMonOp::OP_SIGN,
 
-    # imag_i: preserve-dtype primitive (0 for numeric, cimag for complex
+    # imag_i: type-preserving primitive (0 for numeric, cimag for complex
     # in the real slot).  Primarily consumed by the `imag` special case
     # below but also directly callable via `a.lazy.imag_i`; entry here
     # so the direct call fuses instead of falling to eager.
@@ -118,24 +118,28 @@ class CArray
   # complex-specific dispatch (= magnitude as float).  Re-express that
   # dispatch via chain composition over existing lazy ops so abs rides
   # the lazy substrate fully:
-  #   numeric parent: CAMonOp(OP_ABS_I)                        (1 node)
-  #   complex parent: CAMonOp(cast_f64) ∘ CAMonOp(OP_ABS_I)    (2 nodes)
-  # The complex chain works because ca_monop_abs_i for cmplx128 stores
-  # |z| in the real slot with imag=0, then cast cmplx128->f64 picks up
-  # the real part — semantically identical to rb_ca_abs (= abs_i + .real
-  # + copy).  No new C kernel, no new op_id required.
+  #   numeric parent: CAMonOp(OP_ABS_I)                            (1 node)
+  #   complex parent: CAMonOp(cast_<float>) ∘ CAMonOp(OP_ABS_I)    (2 nodes)
+  # The complex chain works because ca_monop_abs_i stores |z| in the
+  # real slot with imag=0, then the cast picks up the real part —
+  # semantically identical to the eager abs.  The cast target is the
+  # real component width of the operand (cmplx64 -> f32, cmplx128 ->
+  # f64), matching the eager kernel's `complex: :real_of_source`.
+  # No new C kernel, no new op_id required.
   # ---------------------------------------------------------------------------
 
+  # @private
   alias_method :__abs_eager__, :abs
   __abs_eager_um__ = instance_method(:__abs_eager__)
   define_method(:abs) do
     if __lazy_view__?
       abs_i_node = CAMonOp.__build__(self, CAMonOp::OP_ABS_I)
       if complex?
-        # CA_FLOAT64 is a Symbol; convert via data_type_code so the cast
+        # float_dt is a Symbol; convert via data_type_code so the cast
         # op_id can be computed by Integer arithmetic.
+        float_dt = (data_type == CA_CMPLX64) ? CA_FLOAT32 : CA_FLOAT64
         CAMonOp.__build__(abs_i_node,
-                          CAMonOp::CAST_BASE + CArray.data_type_code(CA_FLOAT64))
+                          CAMonOp::CAST_BASE + CArray.data_type_code(float_dt))
       else
         abs_i_node
       end
@@ -174,6 +178,7 @@ class CArray
   # mutability on the lazy path is not a regression.
   # ---------------------------------------------------------------------------
 
+  # @private
   alias_method :__real_eager__, :real
   __real_eager_um__ = instance_method(:__real_eager__)
   define_method(:real) do
@@ -216,11 +221,11 @@ class CArray
   end
 
   # ---------------------------------------------------------------------------
-  # arg lazy fuse: eager `arg` always returns f64 regardless of input
-  # dtype (data_type-changing monop; see MkKernel.monop :arg output rule).
-  # CAMonOp's cast-before invariant requires input dtype == output dtype
+  # arg lazy fuse: eager `arg` is a data_type-changing monop (see
+  # MkKernel.monop :arg output rule).
+  # CAMonOp's cast-before invariant requires input data type == output data type
   # at each in-place step, so `arg` can't sit directly in the substrate.
-  # Chain compose via the preserve-dtype `arg_i` primitive:
+  # Chain compose via the type-preserving `arg_i` primitive:
   #
   #   integer / bool parent → cast_f64 ∘ arg_i (result f64)
   #   float parent         → arg_i             (result same float)
@@ -228,14 +233,13 @@ class CArray
   #                          component of complex slot; cast extracts
   #                          the real part, same trick as abs / imag)
   #
-  # Note: eager `arg` always widens to f64.  The lazy path preserves
-  # the operand's float / complex width (f32 → f32, cmplx64 → f32)
-  # rather than always going to f64 — matches the general lazy-substrate
-  # rule "scalar keeps operand's precision" (see ca_lazy_wrap_scalar
-  # header).  A user needing exact eager-parity can wrap with
-  # `.to_type(:float64)` before / after.
+  # Both paths keep the operand's float / complex width (f32 → f32,
+  # cmplx64 → f32), and both send integers to f64 since pi does not fit
+  # an integer slot.  That agrees with the general lazy-substrate rule
+  # "scalar keeps operand's precision" (see ca_lazy_wrap_scalar header).
   # ---------------------------------------------------------------------------
 
+  # @private
   alias_method :__arg_eager__, :arg
   __arg_eager_um__ = instance_method(:__arg_eager__)
   define_method(:arg) do
@@ -307,7 +311,6 @@ class CArray
 
     # IEEE 754 remainder (distinct semantics from `%` / `mod`: float
     # branch uses C99 `remainder`, round-half-to-even).
-    :reminder  => CABinOp::OP_REMINDER,
   }.freeze
 
   LAZY_BINOP_OP_IDS.each do |method_name, op_id|
@@ -533,7 +536,7 @@ class CArray
     if __lazy_view__?
       dt_name = data_type_name
       if CScalar.respond_to?(dt_name)
-        s = CScalar.send(dt_name)
+        s = CScalar.public_send(dt_name)
         s[0] = other
         [s, self]
       else
@@ -801,6 +804,15 @@ end
       end
       copy
     end
+
+    # Where something is registered to compute an expression -- a compiler,
+    # say -- it is asked here, and the walk below is what happens when it
+    # declines, when nothing is registered, or when the array is small
+    # enough that walking is the faster answer.
+    def copy
+      return super unless CArray.expression_evaluator
+      CArray::Fusion.evaluate(self) || super
+    end
   end
 end
 
@@ -825,65 +837,68 @@ end
 #   - A bare lazy return auto-materialises; escaping the lazy view (e.g.
 #     stashing it in an Array) is the user's responsibility.
 # ---------------------------------------------------------------------------
+# CArray.fuse
+#
+# Builds an expression instead of evaluating it, so that it is computed in
+# one pass with no array standing for a step along the way.  The block is
+# read rather than called; see CArray::FuseSource for why, and for what
+# happens where its source cannot be read.
+# ---------------------------------------------------------------------------
 class << CArray
-  # @overload fuse(*args) { |*shadows| ... }
-  #   Runs a transient lazy-fusion scope: wraps each CArray argument
-  #   with `.lazy`, yields the wrappers (and any non-CArray args)
-  #   to the block, then auto-materialises a bare lazy return value
-  #   into an entity. Non-lazy returns pass through as-is.
-  #   @param args [Array<CArray, Object>] operands.
-  #   @yieldparam shadows [Array<CArray, Object>] lazy wrappers
-  #     paired with pass-through non-CArray operands.
-  #   @return [Object]
-  #   @raise [LocalJumpError] when no block is given.
-  def fuse(*args)
-    raise LocalJumpError, "CArray.fuse requires a block" unless block_given?
-    shadows = args.map { |a| a.is_a?(CArray) ? a.lazy : a }
-    result = yield(*shadows)
-    case result
-    when CAMonOp, CABinOp, CAMonCmp, CABinCmp, CALazyMarker
-      result.to_ca
-    else
-      result
+  # The object asked to compute an expression, or nil.  CArray can always
+  # walk one, so nothing has to be registered and nothing changes when
+  # nothing is; what a registered evaluator adds is a second way to arrive
+  # at the same answer, and it may decline.
+  #
+  # It is called as `call(plan, out)` -- see {CArray::Fusion} for what a
+  # plan holds -- and answers by filling `out` and returning something
+  # true, or by returning something false having written nothing.  Raising
+  # is not an answer: one that raises is dropped, with a warning, and
+  # expressions are walked from there on.
+  #
+  # @return [#call, nil]
+  attr_reader :expression_evaluator
+
+  # @param object [#call, nil] see {#expression_evaluator}
+  # @raise [ArgumentError] when it cannot be called.
+  def expression_evaluator= (object)
+    if object && ! object.respond_to?(:call)
+      raise ArgumentError,
+            "an expression evaluator must respond to #call(plan, out)"
     end
+    @expression_evaluator = object
   end
 
-  # CArray.lazy(*args) { |lazies| ... }  —  dual of fuse
+  # @overload fuse { <expression> }
+  #   Builds the expression rather than evaluating it, so that it is
+  #   computed in one pass with no array standing for a step along the way.
   #
-  # Like `fuse`, wraps each CArray argument with `.lazy` and yields it to
-  # the block, but **does not auto-materialise at block exit** (= returns
-  # the lazy structure as-is). If the block return is non-lazy (= Numeric
-  # / entity CArray / Array etc.) it's pass-through (= same polymorphic
-  # semantics as fuse).
+  #   The block is not called.  Its source is read, every name in it that
+  #   holds a CArray is given `.lazy`, and the result is evaluated back in
+  #   the block's own binding -- so `self`, instance variables, methods and
+  #   constants are what they were where it was written.
   #
-  # Use cases:
-  #   - Passing a chain between functions: build the lazy expression
-  #     inside the function and materialise at the caller
-  #     (= `.to_ca` / `.sum` / `.mean(axis:)` etc.)
-  #   - Reusable expressions: apply the same expr to multiple datasets
-  #   - debug / dump_tree: observe the lazy structure as-is
-  #   - Pick the materialise form later: full materialise or reduction
+  #     out[] = CArray.fuse { (a + b) * (c - a) }
+  #     total = CArray.fuse { a * weight }.sum
   #
-  # Example:
-  #   expr = CArray.lazy(a, b) { |s, o| (s + o) * 2 }
-  #   expr.class           #=> CABinOp (lazy view)
-  #   expr.to_ca           # full materialise
-  #   expr.sum             # reduction (= chain + reduce in 1 pass)
+  #   What comes back is the expression, not an array: it is computed where
+  #   it is used -- stored into an array, reduced, or asked for one with
+  #   `to_ca`.  A block holding anything but an expression over arrays comes
+  #   back as whatever it evaluated to.
   #
-  # Polymorphic semantics (= symmetric with fuse):
-  #   CArray.lazy(25.0, b) { |s, o| s + o }   # s=25.0 Float pass-through
-  #   CArray.lazy(arr, b)  { |s, o| s + o }   # s=arr.lazy
-  # @overload lazy(*args) { |*shadows| ... }
-  #   Like {.fuse} but does not auto-materialise: returns whatever
-  #   the block yields (typically a lazy view) so the expression
-  #   can be materialised later via `.to_ca`, `.sum`, `.mean`, etc.
-  #   @param args [Array<CArray, Object>] operands.
-  #   @yieldparam shadows [Array<CArray, Object>] lazy wrappers.
-  #   @return [Object]
+  #   @return [Object] the expression, as a lazy view
   #   @raise [LocalJumpError] when no block is given.
-  def lazy(*args)
-    raise LocalJumpError, "CArray.lazy requires a block" unless block_given?
-    shadows = args.map { |a| a.is_a?(CArray) ? a.lazy : a }
-    yield(*shadows)
+  #   @raise [ArgumentError] when the block's source cannot be read -- in
+  #     irb, in `eval`, or from a file that is gone.  Write `.lazy` on the
+  #     operands there: `a.lazy + b.lazy`.
+  def fuse (*args, &block)
+    raise LocalJumpError, "CArray.fuse requires a block" unless block
+    unless args.empty?
+      raise ArgumentError,
+            "CArray.fuse takes no arguments: write the expression itself, " \
+            "`CArray.fuse { a + b }`, and the names in it are read from " \
+            "where the block was written"
+    end
+    CArray::FuseSource.evaluate(block)
   end
 end

data/lib/carray/mask_gap_fill.rb

@@ -172,7 +172,9 @@ class CArray
       return vec[present].linear_fetch(addr)
     end
     vval = vec.value.float64[present]         # valid values
-    vval.linear_fetch(addr).to_type(vec.data_type).mask_invalid
+    # Mark the out-of-range NaN before casting back: for an integer data_type
+    # the cast turns NaN into 0, and mask_invalid then has nothing left to find.
+    vval.linear_fetch(addr).mask_invalid.to_type(vec.data_type)
   end
 
   # Yield an index key (Array with `nil` at `axis`, integers elsewhere)

data/lib/carray/meld_reduce.rb

@@ -190,7 +190,7 @@ class CAMeld
   # is unchanged.  (Reduced axis == meld_axis is handled by the callers'
   # meld_axis branch and never reaches here.)
   def non_meld_axis_decompose(op, axis)
-    parts = parents.map { |p| p.send(op, axis: axis) }
+    parts = parents.map { |p| p.public_send(op, axis: axis) }
     axis_norm = axis < 0 ? axis + ndim : axis
     new_meld_axis = axis_norm < meld_axis ? meld_axis - 1 : meld_axis
     CArray.meld(parts, axis: new_meld_axis).copy
@@ -202,7 +202,7 @@ class CAMeld
     # Empty-parent / short-parent handling — Welford needs n >= 2 per parent
     # to recover m2 from p.variance for sample, n >= 1 for variancep (n=1
     # gives m2=0, fine).  Any parent below its threshold punts to super,
-    # which handles UNDEF / 0-count per CLAUDE.md contract.
+    # which handles the UNDEF / zero-count cases.
     min_n = sample ? 2 : 1
     if axis.nil?
       return yield if parents.any? { |p| p.elements < min_n }

data/lib/carray/methods/align_addr.rb

@@ -33,7 +33,7 @@ class CArray
   #
   #   Value equality follows the value-hash discovery family (numeric `==` with
   #   NaN collapsed and `-0.0 == +0.0`; object `hash` / `eql?`; fixlen byte
-  #   equality). Arrays are coerced to the first array's dtype within the same
+  #   equality). Arrays are coerced to the first array's data type within the same
   #   family (cross-family raises). Masked cells do not enter `common`.
   #
   #   @param arrays [Array<CArray>] two or more arrays (Array / Range coerced

data/lib/carray/methods/composition.rb

@@ -12,7 +12,7 @@
 # (`stack` / `meld` / `montage`, plus `CArray#stack` and `CAStack#append`)
 # lives in carray/stack.rb.  The cheat sheet below covers the whole family.
 #
-#                       | view (same dtype)      | eager (auto-cast)
+#                       | view (same data type)      | eager (auto-cast)
 #   -------------------+------------------------+-----------------------
 #   concat existing    | meld  (CAMeld view)    | concatenate (materialised)
 #   axis (ndim same)   |                        |

data/lib/carray/methods/discovery_along.rb

@@ -0,0 +1,74 @@
+class CArray
+
+  #  The value-hash discovery family (`unique`, `nunique`,
+  #  `mask_duplicates`, ...) interns one **cell** at a time.  `along:`
+  #  widens the unit to a whole sub-array: the sub-arrays enumerated
+  #  along one axis, each compared as a single value.
+  #
+  #  Nothing new has to hash.  `fz_hash`'s third key lane already interns
+  #  a fixed-width block of bytes (FNV-1a, with a memcmp re-check), which
+  #  is what a sub-array is once it sits contiguously; this method is the
+  #  bridge to it, and the three things the bridge has to get right:
+  #
+  #    - the sub-arrays have to be contiguous before their bytes mean
+  #      anything, which a transpose or a strided view does not give;
+  #    - byte equality is not the family's contract for floats, where
+  #      every NaN is one value and -0.0 is +0.0;
+  #    - masks fold for free -- a CARefer that covers several parent
+  #      cells with one view cell OR-reduces their mask bits, so a
+  #      sub-array holding a masked cell is a masked sub-array and the
+  #      kernels skip it.
+  #
+  #  Returns a 1-D fixlen array, one cell per sub-array, for the caller
+  #  to run an ordinary cell-level discovery method over.
+  private def fibers_as_cells (along, caller_name)
+    if ndim < 2
+      raise ArgumentError,
+            "#{caller_name}: along: compares sub-arrays, and a #{ndim}-D array " \
+            "has none -- drop along: for the whole-array form"
+    end
+
+    if data_type == CA_OBJECT
+      raise ArgumentError,
+            "#{caller_name}: along: is not available for an object array -- " \
+            "its cells hold Ruby references, which would compare by identity " \
+            "rather than by value"
+    end
+
+    axis = normalize_axis(along, caller_name)
+
+    #  Bring the named axis to the front so each sub-array is one
+    #  unbroken run of bytes, and take a copy: `refer` reinterprets a
+    #  byte buffer, and a view whose element stride is not its element
+    #  width is not one.  The copy is also what makes the normalisation
+    #  below safe to write.
+    order = [axis] + (0...ndim).to_a.reject { |i| i == axis }
+    block = (axis.zero? ? self : transpose(*order)).copy
+
+    #  Two values the family calls equal are not equal byte for byte.
+    #  Normalise them so the bytes say what the values mean.
+    if block.float?
+      block[:is_nan] = Float::NAN     #  every NaN is one value
+      block[:eq, 0.0] = 0.0           #  -0.0 is +0.0
+    elsif block.complex?
+      [block.real, block.imag].each do |part|
+        part[:is_nan] = Float::NAN
+        part[:eq, 0.0] = 0.0
+      end
+    end
+
+    count = shape[axis]
+    block.refer(:fixlen, [count], bytes: elements / count * bytes)
+  end
+
+  #  `axis:` and `along:` ask different questions of the same array, so
+  #  answering both at once has no meaning.
+  private def reject_axis_with_along (axis, along, caller_name)
+    return unless axis and along
+    raise ArgumentError,
+          "#{caller_name}: axis: and along: cannot be given together -- " \
+          "axis: is about the values inside each sub-array, along: is about " \
+          "the sub-arrays themselves"
+  end
+
+end

data/lib/carray/methods/factorize.rb

@@ -0,0 +1,50 @@
+class CArray
+
+  # @overload factorize
+  #   Returns `[codes, levels]` in one pass: `levels` is a 1-D CArray of
+  #   the distinct values of `self` in first-appearance order — what
+  #   {#unique} answers — and `codes` is an integer CArray of `self`'s
+  #   shape where `levels[codes[i]]` is `self[i]`.
+  #
+  #   This is the member of the value-hash discovery family ({#unique},
+  #   {#value_counts}, {#mask_duplicates}, {#nunique}) that hands back
+  #   the codes as storage. {#unique} answers with the vocabulary alone
+  #   and {#categorize} wraps both in a {CACategorical} Face; a caller
+  #   who wants the codes themselves — a position to scatter into, a key
+  #   to group by, a dense renumbering of sparse keys — would otherwise
+  #   pay a second pass or take the Face and its Ruby label list.
+  #
+  #   `codes` takes the narrowest unsigned data type the vocabulary
+  #   fits, reserving that type's top value as the exclusion sentinel.
+  #   A cell that joins no category — a masked cell — is both masked and
+  #   holds the sentinel, exactly as {CACategorical}'s storage is, so a
+  #   consumer may read either.
+  #
+  #   Distinctness is the family's hash-key judgement (see {#unique}):
+  #   `==` for numeric with all NaN collapsed to one value and
+  #   -0.0 / +0.0 the same value; `eql?` / `hash` for `CA_OBJECT` and
+  #   `CA_FIXLEN`. Complex is not a lane the factorizer takes and raises
+  #   {CArray::DataTypeError}.
+  #
+  #   There is no `sort:` here, unlike {#unique} and {#value_counts}:
+  #   the codes index the levels, so reordering the vocabulary would
+  #   desync them. Take {#unique}`(sort: true)` where the codes are not
+  #   wanted, or sort afterwards and carry the codes through the same
+  #   permutation.
+  #
+  #   @return [Array(CArray, CArray)] `[codes, levels]`.
+  def factorize
+    # One linear pass through the shared value hash (C
+    # __factorize_appearance__). It writes the sentinel into the
+    # excluded cells but leaves the codes unmasked; masking them is what
+    # CACategorical.from_codes does on its way to the Face, and this
+    # surface owes the same, since it hands the storage out bare.
+    codes, levels = __factorize_appearance__
+    excluded = codes.eq(CACategorical::SENTINEL[codes.data_type])
+    if excluded.count(true) > 0
+      codes.mask = codes.has_mask? ? (codes.mask | excluded) : excluded
+    end
+    [codes, levels]
+  end
+
+end

data/lib/carray/methods/is_in.rb

@@ -10,19 +10,22 @@ class CArray
   #   argument is accepted; to test a few immediate values pass an
   #   Array (`a.is_in([0, -1])`).
   #
-  #   When `self` and `values` have different numeric dtypes they are
+  #   When `self` and `values` have different numeric data types they are
   #   promoted to a common type first (the same promotion binops use,
   #   {CArray.result_type}), so membership is value-correct across
-  #   dtypes (e.g. an int cell equals a float set element of the same
+  #   data types (e.g. an int cell equals a float set element of the same
   #   value, and a fractional set element never truncates onto an int
-  #   cell). Genuinely incompatible dtypes (e.g. numeric vs fixlen)
+  #   cell). Genuinely incompatible data types (e.g. numeric vs fixlen)
   #   raise.
   #
   #   Membership is value-based and shares the distinctness of the
   #   value-hash discovery family ({#unique} / {#value_counts}):
   #   numeric follows `==` with all NaN collapsed to one value and
   #   -0.0 == +0.0; `CA_OBJECT` follows Ruby `hash` / `eql?` with Float
-  #   NaN collapsed; `CA_FIXLEN` follows byte equality.
+  #   NaN collapsed; `CA_FIXLEN` follows byte equality over the whole
+  #   cell, with a short String in the set padded out to the cell width
+  #   (so a 5-byte array written from `"be"` is `is_in(["be"])`). A
+  #   `CA_FIXLEN` set given as a CArray must already be of that width.
   #
   #   Masked cells of `values` do not enter the set. Masked cells of
   #   `self` stay masked in the result (membership is unknown), so
@@ -32,7 +35,7 @@ class CArray
   #   reduction, compose with {#any}: `a.is_in(values).any(axis: k)`.
   #
   #   @param values [CArray, Array, Range] the set to test membership
-  #     against. Promoted with `self` to a common dtype.
+  #     against. Promoted with `self` to a common data type.
   #   Between two time arrays the question is about instants, not ticks:
   #   `values` is reconciled into `self`'s unit first, so a `:D` array and an
   #   `:h` array match on the instants they share.  The same holds for the set
@@ -49,7 +52,7 @@ class CArray
   #   `self` and `other`, in `self`'s first-appearance order.
   #
   #   Value-based, sharing the distinctness of the discovery family
-  #   (see {#is_in}); `self` and `other` are promoted to a common dtype.
+  #   (see {#is_in}); `self` and `other` are promoted to a common data type.
   #   Masked cells of either array do not participate. The result is
   #   always flat, like {#unique}, because the distinct values of a
   #   fiber vary in number.
@@ -97,18 +100,18 @@ class CArray
 
   # Reconcile a set-valued argument with self to a common data_type via
   # CArray.result_type (the single-source promotion rule the eager binop and
-  # lazy CABinOp share), returning [self', set']. Only dtypes are reconciled,
+  # lazy CABinOp share), returning [self', set']. Only data types are reconciled,
   # never shapes: unlike the binop coercion (cast_self_or_other) the set's
   # shape never broadcasts against self's, so a size-1 self keeps its shape.
-  # result_type raises for genuinely incompatible dtypes (numeric vs fixlen).
+  # result_type raises for genuinely incompatible data types (numeric vs fixlen).
   #
-  # A bare Array / Range has no intrinsic dtype, so the common type is inferred
+  # A bare Array / Range has no intrinsic data type, so the common type is inferred
   # from self and the individual elements (result_type classifies each scalar).
   # This keeps a fractional literal from truncating onto an int self, and an
   # int literal from boxing a float self into the object lane (where Float 2.0
-  # is not eql? Integer 2). A CArray argument uses its own dtype; any other
+  # is not eql? Integer 2). A CArray argument uses its own data type; any other
   # operand (Numo, a MemoryView producer, ...) comes in through wrap_readonly,
-  # the canonical type-coercion entry, so its format's dtype drives the promote.
+  # the canonical type-coercion entry, so its format's data type drives the promote.
   def promote_value_set (values)
     case values
     when Array then return promote_elements(values)
@@ -123,10 +126,18 @@ class CArray
   # Bare Array / Range against numeric self: infer the common numeric type
   # from self and the elements (each classified by result_type), so a
   # fractional literal promotes self to float instead of truncating. Against
-  # object / fixlen self the elements are values, not dtype specifiers (a
-  # String is a value, not a type name), so build the set in self's dtype.
+  # object / fixlen self the elements are values, not data type specifiers (a
+  # String is a value, not a type name), so build the set in self's data type.
   def promote_elements (elems)
-    if data_type == CA_OBJECT || data_type == CA_FIXLEN
+    if data_type == CA_FIXLEN
+      # A fixlen value is a cell-width blob, so the set has to be built at
+      # this array's width -- to_type(:fixlen) with no bytes: builds it at
+      # width 0, where every element is "" and the C guard then refuses the
+      # set for not matching self.  Same rule the scalar operand of a
+      # comparison follows: a String standing in for a cell is padded to the
+      # cell's width.
+      [self, elems.to_ca.to_type(data_type, bytes: bytes)]
+    elsif data_type == CA_OBJECT
       [self, elems.to_ca.to_type(data_type)]
     else
       t = CArray.result_type(self, *elems)

data/lib/carray/methods/locate_addr.rb

@@ -1,8 +1,47 @@
 class CArray
 
-  # User-facing YARD docs for #locate_addr and #locate_nearest_addr live
-  # in yard-stubs/carray_order.rb (grouped with the search family).
+  # @!group Sorting and searching
 
+  # @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.
+  #
+  #   `self` and `ref` are compared at their common type, negotiated by
+  #   `CArray.result_type` — a fractional query against an integer `ref`
+  #   is compared at the promoted type rather than truncated, so `1.5` no
+  #   longer matches `1`. Cross-family input (numeric against fixlen)
+  #   raises.
+  #
+  #   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.
+  #
+  #   @param ref [CArray, Array, Range] reference values to match against;
+  #     any shape (used as flat). An Array or Range is coerced with `to_ca`
+  #     and so lands in `:object`, where numeric matching follows Ruby
+  #     `eql?` (`2.0` does not match `2`); pass a CArray to match in a
+  #     numeric lane.
+  #   @return [CArray] `:int64` flat addresses into `ref`, same shape as
+  #     `self`; unmatched cells are masked.
+  #   @raise [RuntimeError] when `self` and `ref` have no common data type.
   def locate_addr (ref)
     ref = ref.to_ca unless ref.is_a?(CArray)
     # Put self and ref in a common lane via the single-source promotion rule
@@ -16,6 +55,38 @@ class CArray
     q.send(:__locate_addr__, r)
   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").
+  #
+  #   `ref` need not be given in ascending order: it is sorted internally
+  #   and the returned addresses are mapped back to positions in `ref` as
+  #   passed.
+  #
+  #   @param ref [CArray] 1-D 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)
     unless [:round, :floor, :ceil].include?(direction)
       raise ArgumentError,
@@ -35,7 +106,12 @@ class CArray
       fill[] = sec.nil? ? UNDEF : sec
       sec = fill
     end
-    si = sec.mask_invalid.send(direction).int64
+    masked = sec.mask_invalid
+    si = case direction
+         when :round then masked.round
+         when :floor then masked.floor
+         when :ceil  then masked.ceil
+         end.int64
     idx = ri.project(si)
     if tolerance
       dist = (ref.project(idx) - self).abs
@@ -44,4 +120,6 @@ class CArray
     idx
   end
 
+  # @!endgroup
+
 end