carray 3.0.2 → 3.0.4

data/lib/carray/complex.rb

@@ -1,7 +1,7 @@
 # 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.
+# is_real).  Loaded eagerly BEFORE carray/lazy.rb, because lazy.rb takes
+# `instance_method(:real)` (and the imag equivalent) at load time -- these
+# defs must exist by then.
 
 class CArray
 
@@ -40,9 +40,9 @@ class CArray
   # 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).
+  #     parents (via `instance_method(:real)` taken 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.
+  #     removing these defs would break the lazy.rb load.
   #
   #   - ext/ca_obj_stride.c recognises `CAField .real/.imag over complex`
   #     as a first-class byte-mismatched reinterpret pattern.  Architectural
@@ -52,6 +52,14 @@ class CArray
   # framework's read-only chain does not replace the CAField mutable view).
   # ---------------------------------------------------------------------------
 
+  # Whether a view kept by {#real} / {#imag} was made for this array.
+  # `dup` and `clone` copy instance variables, so a copy arrives holding the
+  # original's view, whose parent is the original; the copy makes its own.
+  def part_of_self? (view)
+    view && view.parent.equal?(self)
+  end
+  private :part_of_self?
+
   # @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
@@ -59,19 +67,16 @@ class CArray
   #   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__
+    return @__real__ if part_of_self?(@__real__)
+    view = if complex?
+             case data_type
+             when CA_CMPLX64  then field(0, CA_FLOAT32)
+             when CA_CMPLX128 then field(0, CA_FLOAT64)
+             end
+           else
+             self[]
+           end
+    frozen? ? view : (@__real__ = view)
   end
 
   # @overload real=(val)
@@ -85,35 +90,37 @@ class CArray
   # @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.
+  #   writing to it updates `self` in place. For an object array each
+  #   cell's `imaginary`; for a real array a fresh independent CArray
+  #   filled with 0. Masked cells stay masked.
   #   @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
+    if object?
+      return imag_i
+    end
+    if not complex?
+      zero = template { 0 }
+      zero[is_masked] = UNDEF if has_mask?
+      return zero
     end
-    return @__imag__
+    return @__imag__ if part_of_self?(@__imag__)
+    view = case data_type
+           when CA_CMPLX64  then field(4, CA_FLOAT32)
+           when CA_CMPLX128 then field(8, CA_FLOAT64)
+           end
+    frozen? ? view : (@__imag__ = view)
   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.
+  #   @raise [CArray::DataTypeError] when `self` is not a complex array.
   def imag= (val)
     if complex?
       imag[] = val
     else
-      raise "not a complex array"
+      raise CArray::DataTypeError, "not a complex array"
     end
   end
 

data/lib/carray/conditional.rb

@@ -6,7 +6,7 @@
 #  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)
+#      cond.then_else(x, y)                  # boolean receiver, 2 values (lazy if an operand is)
 #      self.replace_where(cond, b)           # value receiver, 1 replacement (eager)
 #      self.conditional(cond, f_then, f_else) # value receiver, 2 callables (per-region)
 #
@@ -25,10 +25,25 @@ class 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).
+  #   The result's data type is the common type of the two branches; a
+  #   branch given as `UNDEF` masks its cells and leaves the type to the
+  #   other branch (`cond.then_else(a, UNDEF)` has `a`'s data type).
+  #   String branches make the result a {CAString}
+  #   (`cond.then_else("yes", "no")`, also with `UNDEF` for one of them).
+  #   A Symbol branch, or a String beside a value of another kind, makes
+  #   the result an object array.
+  #   When `self` or a branch is a lazy view, the result is a lazy view
+  #   (read-only) that joins the expression around it; `copy` makes an
+  #   array of it.  An object result is always computed at once.
   #   @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.
+  #   @return [CArray] new array with the same shape as `self` (a
+  #     {CAString} for String branches), or a lazy view (CATriOp) when an
+  #     operand is lazy.
+  #   @raise [ArgumentError] when `self` is not a boolean CArray, or when
+  #     an array branch's shape does not pair with `self`'s as an
+  #     operator's operands would (equal, or size-1 axes of the same ndim;
+  #     an object or fixlen result needs `self`'s shape exactly).
   def then_else (x, y)
     # Guard: self must be boolean.  Integer / float receiver would be
     # silently reinterpreted by the indexer setter (`result[self] = ...`)
@@ -38,10 +53,22 @@ class CArray
       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)
+    reshaped = [x, y].any? { |v| v.is_a?(CArray) && !v.scalar? && v.shape != shape }
+    face = [x, y].find { |v| v.is_a?(CArray) && !v.scalar? && v.face? }
+    if face
+      refuse_branch_shape(x, y) if reshaped
+      refuse_branch_mix(x, y, face)
+      return face_then_else(x, y, face)
+    end
+    dt = CArray.send(:selection_type, [x, y])
+    return lazy_then_else(x, y, dt) if lazy_then_else?(x, y, dt)
+    # A branch shaped unlike the condition goes through the lazy select,
+    # which pairs the shapes by the operator rule (equal, or size-1 axes
+    # with the same ndim) and refuses the rest.
+    if reshaped
+      refuse_branch_shape(x, y) if scalar? || dt == CA_OBJECT || dt == CA_FIXLEN
+      return lazy_then_else(x, y, dt).copy
+    end
     # 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?
@@ -57,6 +84,82 @@ class CArray
     if self.has_mask?
       result[self.is_masked] = UNDEF
     end
+    CArray.send(:selection_text?, [x, y]) ? CAString.wrap(result) : result
+  end
+
+  # A lazy receiver or branch makes the selection a lazy node (CATriOp
+  # select), so it joins the expression around it rather than computing
+  # it here.  The branches carry the result type: a scalar branch becomes
+  # a CScalar of it, UNDEF a masked one.
+  private def lazy_then_else? (x, y, dt)
+    return false if scalar? || dt == CA_OBJECT || dt == CA_FIXLEN
+    [self, x, y].any? { |v| v.is_a?(CArray) && v.lazy_view? }
+  end
+
+  # The types the lazy select cannot carry keep the strict form: a full
+  # branch must have the condition's shape.
+  private def refuse_branch_shape (x, y)
+    bad = [x, y].find { |v| v.is_a?(CArray) && !v.scalar? && v.shape != shape }
+    raise ArgumentError,
+          "then_else: branch shape #{bad.shape.inspect} does not match the condition's #{shape.inspect}"
+  end
+
+  # An array branch beside a Face branch must be a Face of the same kind
+  # (the same obj_type, so a CARecord subclass and a CARecord of one data
+  # class pair, as their store takes): the Face decides what a cell means,
+  # so a plain array would be read as its storage (an integer as a time's
+  # ticks) and the result would take the class of whichever branch came
+  # second.  A scalar branch is a value and goes through the Face's store.
+  private def refuse_branch_mix (x, y, face)
+    arrays = [x, y].select { |v| v.is_a?(CArray) && !v.scalar? }
+    return if arrays.all? { |v| v.face? && v.obj_type == face.obj_type }
+    hint = face.is_a?(CAString) ?
+      " (CArray.string(a) makes a CAString of an object array of Strings)" : ""
+    raise ArgumentError,
+          "then_else: cannot mix Face and non-Face arrays, or arrays of " \
+          "different Face classes; convert them first to one Face class or to no Face" + hint
+  end
+
+  private def lazy_then_else (x, y, dt)
+    branch = lambda do |v|
+      next v if v.is_a?(CArray) && !v.scalar?
+      cell = CScalar.new(dt)
+      cell[0] = v.is_a?(CArray) ? v[0] : v
+      cell
+    end
+    CATriOp.__build__(self, branch.(x), branch.(y), CATriOp::OP_SELECT)
+  end
+
+  private def face_then_else (x, y, face)
+    # A Face branch decides the result: the other branch is written into a
+    # copy of it through the Face's own store, so an instant stays an instant.
+    # Promoting the two branches to a common data type would compare a Face's
+    # surface type with its storage's.  A CAConstString cannot be written, so
+    # it selects among its strings and packs them again.
+    if face.is_a?(CAConstString)
+      sx = x.is_a?(CAConstString) ? x.to_string : x
+      sy = y.is_a?(CAConstString) ? y.to_string : y
+      return CArray.const_string(then_else(sx, sy), encoding: face.encoding)
+    end
+    x_full = x.is_a?(CArray) && !x.scalar?
+    y_full = y.is_a?(CArray) && !y.scalar?
+    base   = y_full ? y : x
+    if base.read_only?
+      # No store to write through (a CACategorical's codes): select among
+      # the values themselves.
+      result = CArray.object(*shape)
+      result[] = y_full ? y.to_type(CA_OBJECT) : y
+      result[self] = x_full ? x.to_type(CA_OBJECT)[self] : x
+      result[self.is_masked] = UNDEF if self.has_mask?
+      return result
+    end
+    result = base.copy
+    if y_full
+      result[self] = x_full ? x[self] : x
+    else
+      result[self.not] = y.is_a?(CArray) ? y[0] : y
+    end
+    result[self.is_masked] = UNDEF if self.has_mask?
     result
   end
 
@@ -91,7 +194,9 @@ class CArray
   #   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
-  #   `data_type` when given. Masked cells in `cond` propagate to
+  #   `data_type` when given. A String result is a value (not the name
+  #   of a data type); when both callables give Strings or {CAString}s
+  #   the result is a {CAString}. Masked cells in `cond` propagate to
   #   `UNDEF` in the result.
   #
   #   @param cond [CArray] boolean selector; same shape as `self`.
@@ -118,18 +223,19 @@ class CArray
     x_else = self[cond.not]
     y_then = then_fn.call(x_then)
     y_else = else_fn.call(x_else)
+    text = !data_type && CArray.send(:selection_text?, [y_then, y_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(data_type || CArray.result_type(y_then), x_then.shape).fill(y_then)
+      y_then = CArray.new(data_type || CArray.send(:selection_type, [y_then]), x_then.shape).fill(y_then)
     end
     unless y_else.is_a?(CArray)
-      y_else = CArray.new(data_type || CArray.result_type(y_else), x_else.shape).fill(y_else)
+      y_else = CArray.new(data_type || CArray.send(:selection_type, [y_else]), x_else.shape).fill(y_else)
     end
 
-    dt  = data_type || CArray.result_type(y_then, y_else)
+    dt  = data_type || CArray.send(:selection_type, [y_then, y_else])
     out = CArray.new(dt, self.shape)
     out[cond]     = y_then
     out[cond.not] = y_else
@@ -138,7 +244,7 @@ class CArray
     # positions, so both scatters leave the cell untouched — an explicit
     # fix-up is required.
     out[cond.is_masked] = UNDEF if cond.has_mask?
-    out
+    text ? CAString.wrap(out) : out
   end
 
   # @overload select(condlist, choicelist, default: 0, data_type: nil)
@@ -151,7 +257,9 @@ class CArray
   #   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
-  #   `data_type` when given.
+  #   `data_type` when given. A String choice is a value (not the name of
+  #   a data type); when every choice and `default` is a String or a
+  #   {CAString}, the result is a {CAString}.
   #
   #   @param condlist [Array<CArray>] boolean selectors.
   #   @param choicelist [Array<CArray, Numeric, Object>] values, one
@@ -187,7 +295,7 @@ class CArray
     end
     shape = first.shape
 
-    dt = data_type || CArray.result_type(*choicelist, default)
+    dt = data_type || selection_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?
@@ -210,7 +318,35 @@ class CArray
       v = choicelist[k]
       out[c] = v.is_a?(CArray) ? v[c] : v
     end
+    if !data_type && selection_text?(choicelist + [default])
+      out = CAString.wrap(out)
+    end
     out
   end
 
+  # The data type a selection among `values` writes into: their common type,
+  # by the rule an operator promotes its operands by (a scalar takes the
+  # type of an array beside it).  UNDEF is a missing value, not a value of
+  # some type, so it leaves the type to the others.  A String or Symbol is a
+  # value, which CArray.result_type would read as the name of a data type
+  # ("int32"), so it makes the result object.
+  def self.selection_type (values)
+    typed = values.reject { |v| v.equal?(UNDEF) }
+    if typed.empty? || typed.any? { |v| v.is_a?(String) || v.is_a?(Symbol) }
+      CA_OBJECT
+    else
+      CArray.result_type(*typed)
+    end
+  end
+  private_class_method :selection_type
+
+  # Whether a selection among `values` gives text: every value that is not
+  # UNDEF is a String or a CAString, and there is at least one.  The result
+  # is then a CAString rather than an object array of Strings.
+  def self.selection_text? (values)
+    present = values.reject { |v| v.equal?(UNDEF) }
+    !present.empty? && present.all? { |v| v.is_a?(String) || v.is_a?(CAString) }
+  end
+  private_class_method :selection_text?
+
 end

data/lib/carray/const_string.rb

@@ -55,7 +55,7 @@ class CArray
   #   @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)
+      return string_face_of(arg, "CArray.const_string").to_const_string(encoding: encoding)
     end
     if block
       n = Integer(arg)
@@ -135,7 +135,7 @@ class CAConstString
   def sort_addr (*args, **kw)
     # The native scan has no notion of an incomparable sentinel, so a masked
     # column goes the same way a per-axis one does.
-    return __sort_addr_bytes__ if args.empty? && kw.empty? && ! has_mask?
+    return sort_addr_by_bytes if args.empty? && kw.empty? && ! has_mask?
     to_string.sort_addr(*args, **kw)
   end
 
@@ -143,6 +143,12 @@ class CAConstString
   #   Returns the per-fiber indices that index a sort by string order.
   #   @return [CArray] `:int64` indices.
   def sort_index (*args, **kw)
+    if args.empty? && kw.empty? && ! has_mask?
+      # With no axis the indices are those of the flattened array, which are
+      # its addresses.
+      addr = sort_addr_by_bytes
+      return ndim == 1 ? addr : addr.flatten.copy
+    end
     to_string.sort_index(*args, **kw)
   end
 
@@ -163,7 +169,7 @@ class CAConstString
   #   every cell is masked or the array is empty.
   #   @return [String, CAConstString]
   def min (*args, **kw)
-    return __min_bytes__ || UNDEF if args.empty? && kw.empty?
+    return min_string_by_bytes || UNDEF if args.empty? && kw.empty?
     const_string_lift(to_string.min(*args, **kw))
   end
 
@@ -171,7 +177,7 @@ class CAConstString
   #   Byte-largest counterpart of {#min}.
   #   @return [String, CAConstString]
   def max (*args, **kw)
-    return __max_bytes__ || UNDEF if args.empty? && kw.empty?
+    return max_string_by_bytes || UNDEF if args.empty? && kw.empty?
     const_string_lift(to_string.max(*args, **kw))
   end
 
@@ -182,6 +188,13 @@ class CAConstString
     to_string.minmax(*args, **kw).map { |r| const_string_lift(r) }
   end
 
+  # @overload clip(min, max = nil, fill_value = nil, lfill: nil, ufill: nil)
+  #   Clips the strings in byte order (see {CArray#clip}).
+  #   @return [CAConstString]
+  def clip (*args, **kw)
+    const_string_lift(to_string.clip(*args, **kw))
+  end
+
   # @overload min_index(axis: nil)
   #   @return [Integer, CArray] where the byte-smallest string sits.
   def min_index (*args, **kw)
@@ -312,9 +325,38 @@ class CAConstString
   # @overload categorize(labels: nil, sort_labels: false)
   #   @return [CACategorical] categories keyed on the strings.
   def categorize (labels: nil, sort_labels: false)
+    # Discovery reads the bytes (a String per distinct value only); a given
+    # vocabulary is matched through the strings.
+    return super if labels.nil?
     to_string.categorize(labels: labels, sort_labels: sort_labels)
   end
 
+  # ---- comparison operators ---------------------------------------------
+  #
+  # The core operators compare storage, and a storage cell is a byte range:
+  # `x < "dd"` compared where each string sits in the buffer and answered
+  # true everywhere.  They read the strings here instead.  `eq` has a native
+  # byte scan and stays; `<=>` composes from `>` and `<`, so it follows.
+
+  # @!method ne(other)
+  #   @return [CArray] boolean, true where the strings differ.
+  # @!method lt(other)
+  #   @return [CArray] boolean, true where self sorts before `other`.
+  # @!method le(other)
+  #   @return [CArray] boolean, true where self sorts before or equals `other`.
+  # @!method gt(other)
+  #   @return [CArray] boolean, true where self sorts after `other`.
+  # @!method ge(other)
+  #   @return [CArray] boolean, true where self sorts after or equals `other`.
+  [:ne, :lt, :le, :gt, :ge].each do |op|
+    define_method(op, &Ractor.make_shareable(proc { |other| to_string.public_send(op, string_operand(other)) }))
+  end
+
+  alias <  lt
+  alias <= le
+  alias >  gt
+  alias >= ge
+
   # 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)
@@ -330,3 +372,16 @@ class CAConstString
   end
 
 end
+
+class CAConstString
+  # The decimal readers of CAFrame#infer_types / #cast, read from the buffer
+  # without a String per cell.
+  def __infer_number_type_of_text__
+    CArray.__const_string_infer_number_type_of_text__(self)
+  end
+
+  def __read_text_as_number__(type, report = nil)
+    out = CArray.__const_string_read_text_as_number__(self, type, report)
+    out && ndim > 1 ? out.reshape(*shape) : out
+  end
+end

data/lib/carray/construct.rb

@@ -287,7 +287,7 @@ class CArray
             "(its contents are left undefined); use CArray.new to fill."
     end
     if args.size == 2 and args[1].is_a?(Array)
-      return __empty__(*args, **options)
+      return empty_of_data_type(*args, **options)
     end
     unless options.empty?
       raise ArgumentError,
@@ -314,32 +314,36 @@ class CArray
       CArray.new(self::DataType, shape)
     end
 
-    # @overload from_memory_view(obj)
+    # @overload from_memory_view(obj, mask: nil)
     #   Returns a fresh CArray interpreted as this typed subclass's
     #   `data_type`, imported by copy from a MemoryView producer.
     #   Forwards to
-    #   `CArray.from_memory_view(obj, data_type: self::DataType)`; the
-    #   result is always 1-D (chain `.reshape` for higher rank).
+    #   `CArray.from_memory_view(obj, data_type: self::DataType)`.  A
+    #   typed producer keeps its shape and must agree with the type; a
+    #   typeless one is read as 1-D (chain `.reshape` for higher rank).
     #   @param obj [Object] MemoryView producer.
+    #   @param mask [Object, nil] MemoryView producer of the mask.
     #   @return [CArray]
-    def from_memory_view (obj)
-      CArray.from_memory_view(obj, data_type: self::DataType)
+    def from_memory_view (obj, mask: nil)
+      CArray.from_memory_view(obj, data_type: self::DataType, mask: mask)
     end
 
-    # @overload wrap_memory_view(obj)
+    # @overload wrap_memory_view(obj, mask: nil)
     #   Returns a zero-copy CAWrap over `obj`'s MemoryView interpreted
     #   as this typed subclass's `data_type`. Forwards to
-    #   `CArray.wrap_memory_view(obj, data_type: self::DataType)`; the
-    #   result is always 1-D (chain `.reshape` for higher rank).
+    #   `CArray.wrap_memory_view(obj, data_type: self::DataType)`.  A
+    #   typed producer keeps its shape and must agree with the type; a
+    #   typeless one is read as 1-D (chain `.reshape` for higher rank).
     #
     #   Here the receiver names the element type, not the class of the
     #   result: the call forwards with `CArray` as the receiver, so a
     #   `CAWrap` comes back. Choosing the class is the other reading of
     #   the receiver, and it lives on `CArray.wrap_memory_view` itself.
     #   @param obj [Object] MemoryView producer.
+    #   @param mask [Object, nil] MemoryView producer of the mask.
     #   @return [CAWrap]
-    def wrap_memory_view (obj)
-      CArray.wrap_memory_view(obj, data_type: self::DataType)
+    def wrap_memory_view (obj, mask: nil)
+      CArray.wrap_memory_view(obj, data_type: self::DataType, mask: mask)
     end
 
   end

data/lib/carray/data_type_extension.rb

@@ -164,6 +164,7 @@ class CArray
       #  midpoints go the same way as numpy's integer linspace).
       float_out = CArray.new(CA_FLOAT64, [n]).span(x1.to_f..x2.to_f)
       return float_out if data_type == CA_FLOAT64
+      # coerce: the type the caller asked for
       float_out.floor.to_type(data_type)
     end
 

data/lib/carray/distance_limit.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class CArray
+
+  # The length a match by distance is limited by -- the +tolerance:+ of
+  # locate_nearest_addr (and of align_nearest_addr and CAFrame#join_asof
+  # through it), the +before:+, +after:+ and +interval:+ of a key window --
+  # read the same way wherever it is given: a length of the key's kind,
+  # not below 0.
+  #
+  # - For a number key it is a real number; NaN, which no distance is
+  #   within or beyond, and a negative length are refused, as is a String.
+  # - For a time or duration key it is a duration: a String such as
+  #   "10 minutes" (and "0 minutes") or a CATimedelta value, not negative.
+  #   A bare number is refused, since its length would depend on the key's
+  #   unit.
+  #
+  # Every refusal is ArgumentError naming +label+, the keyword as the
+  # caller says it ("tolerance:", "windows: before:").
+  module DistanceLimit
+
+    ZERO_DURATION = /\A\s*0+\s+([A-Za-z]+)\s*\z/
+
+    # +width+ as a Numeric (number key) or a CATimedelta::Element (time or
+    # duration key); +nil+ passes through.
+    def self.read (width, key, label)
+      return nil if width.nil?
+      if key.is_a?(CATime) || key.is_a?(CATimedelta)
+        duration(width, label)
+      else
+        number(width, key, label)
+      end
+    end
+
+    def self.number (width, key, label)
+      if width.is_a?(String) || width.is_a?(CATimedelta::Element)
+        raise ArgumentError,
+              "#{label} #{width.inspect} is a duration, but the key is " \
+              "#{CArray::Inspector.type_label(key)}; give a number"
+      end
+      unless width.is_a?(Numeric) && width.real? && !(width.is_a?(Float) && width.nan?) && width >= 0
+        raise ArgumentError, "#{label} is a number not below 0 (got #{width.inspect})"
+      end
+      width
+    end
+
+    def self.duration (width, label)
+      element =
+        case width
+        when CATimedelta::Element
+          width
+        when String
+          if (zero = width.match(ZERO_DURATION))
+            CATimedelta::Element.new(0, CATime::Resolution.parse(zero[1]).base)
+          else
+            res = begin
+                    CATime::Resolution.parse(width)
+                  rescue ArgumentError
+                    raise ArgumentError,
+                          "#{label} #{width.inspect} is not a duration " \
+                          "(use e.g. \"10 minutes\" / \"1 hour\")"
+                  end
+            CATimedelta::Element.new(res.count, res.base)
+          end
+        end
+      unless element
+        raise ArgumentError,
+              "#{label} a time key needs a duration such as \"10 minutes\" " \
+              "or a CATimedelta value (got #{width.inspect})"
+      end
+      if element.value < 0
+        raise ArgumentError, "#{label} is a duration not below 0 (got #{width.inspect})"
+      end
+      element
+    end
+  end
+end

data/lib/carray/fixlen_string.rb

@@ -46,7 +46,7 @@ class CArray
   #   @return [CAFixlenString]
   def self.fixlen_string (arg, bytes: nil, truncate: :error, &block)
     if arg.is_a?(CArray)
-      return string_face_of(arg).to_fixlen_string(bytes: bytes, truncate: truncate)
+      return string_face_of(arg, "CArray.fixlen_string").to_fixlen_string(bytes: bytes, truncate: truncate)
     end
     unless [:error, :silent].include?(truncate)
       raise ArgumentError, "truncate: must be :error or :silent (got #{truncate.inspect})"
@@ -90,6 +90,12 @@ end
 # Mutable fixed-width String Face: L1 ops + in-place variants.  In-place
 # transforms re-store through the native fixlen path (silent truncate).
 class CAFixlenString
+  # inspect's name for the array: the class and the cell width, which is the
+  # longest string a cell holds.
+  private def inspect_label
+    "#{self.class}[#{bytes}]"
+  end
+
   include CArray::StringOperationMixin
   include CArray::StringOperationMixin::Mutable
 end