carray 3.0.2 → 3.0.4

data/lib/carray/methods/is_in.rb

@@ -5,18 +5,22 @@ class CArray
   #   each cell whose value appears in the set `values`.
   #
   #   `values` is treated as a set, not as an operand to broadcast: it
-  #   may be any shape (or an Array / Range) and is flattened to a
+  #   may be any shape (or an Array) and is flattened to a
   #   single seen-set, so its shape need not match `self`. Only one
   #   argument is accepted; to test a few immediate values pass an
-  #   Array (`a.is_in([0, -1])`).
+  #   Array (`a.is_in([0, -1])`). A single value is a set of one, as
+  #   `[value]` is (`a.is_in(2)` is `a.is_in([2])`).
   #
   #   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
   #   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 data types (e.g. numeric vs fixlen)
-  #   raise.
+  #   cell). Integers of mixed sign are matched by value, as {#eq}
+  #   compares them: `-1` in an int8 array never matches `255` in a uint8
+  #   one, and the set operations answer such a pair in a type that holds
+  #   both (int16 for uint8 with int8, object for uint64 with int64).
+  #   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}):
@@ -27,6 +31,15 @@ class CArray
   #   (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.
   #
+  #   An object array keeps Ruby's own split between its two kinds of
+  #   equality. A lookup through a hash -- `is_in`, the set operations,
+  #   {#locate_addr}, {#unique} and the rest of the discovery family --
+  #   uses `eql?`, as `Array#uniq`, `Array#&` and `Set` do, so `1` and
+  #   `1.0` are different values there. A cell-by-cell comparison --
+  #   {#eq}, {#count}, {#search}, {#bsearch} -- uses `==`, as
+  #   `Array#include?` does, so they are equal there. To match by value
+  #   across Integer and Float, convert the array to a numeric type first.
+  #
   #   Masked cells of `values` do not enter the set. Masked cells of
   #   `self` stay masked in the result (membership is unknown), so
   #   `is_in` propagates `self`'s mask like an element-wise comparison.
@@ -34,8 +47,10 @@ class CArray
   #   For a per-fiber "does this fiber contain any of these values"
   #   reduction, compose with {#any}: `a.is_in(values).any(axis: k)`.
   #
-  #   @param values [CArray, Array, Range] the set to test membership
+  #   @param values [CArray, Array] the set to test membership
   #     against. Promoted with `self` to a common data type.
+  #   @raise [ArgumentError] for a Range, which reads as an interval rather
+  #     than the set of its steps.
   #   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
@@ -43,6 +58,7 @@ class CArray
   #
   #   @return [CArray] boolean CArray of the same shape as `self`.
   def is_in (values)
+    refuse_range_set(values, "is_in")
     a, b = promote_value_set(values)
     a.__send__(:__is_in__, b)
   end
@@ -57,13 +73,15 @@ class CArray
   #   always flat, like {#unique}, because the distinct values of a
   #   fiber vary in number.
   #
-  #   @param other [CArray, Array, Range] promoted with `self`.
+  #   @param other [CArray, Array] promoted with `self` (a Range is refused, as by {#is_in}).
   #   @param sort [Boolean] when true, return the values sorted
   #     ascending instead of in first-appearance order.
   #   @return [CArray] 1-D CArray of the common distinct values.
   def intersection (other, sort: false)
+    refuse_range_set(other, "intersection")
     a, b = promote_value_set(other)
     r = a.__send__(:__intersection__, b)
+    r = r.to_unit(unit) if !a.equal?(self) && respond_to?(:in_common_unit_with)
     sort ? r.sort : r
   end
 
@@ -72,25 +90,31 @@ class CArray
   #   absent from `other`, in `self`'s first-appearance order.
   #   See {#intersection} for the shared semantics and options.
   #
-  #   @param other [CArray, Array, Range] promoted with `self`.
+  #   @param other [CArray, Array] promoted with `self` (a Range is refused, as by {#is_in}).
   #   @param sort [Boolean] when true, return the values sorted ascending.
   #   @return [CArray] 1-D CArray of the self-only distinct values.
   def difference (other, sort: false)
+    refuse_range_set(other, "difference")
     a, b = promote_value_set(other)
     r = a.__send__(:__difference__, b)
+    r = r.to_unit(unit) if !a.equal?(self) && respond_to?(:in_common_unit_with)
     sort ? r.sort : r
   end
 
   # @overload union(other, sort: false)
   #   Returns a 1-D CArray of the distinct values appearing in either
   #   `self` or `other`, in self-then-other first-appearance order.
-  #   See {#intersection} for the shared semantics and options.
+  #   See {#intersection} for the shared semantics and options.  Two time
+  #   arrays of different units give their union in the finer unit, which
+  #   holds the values of both ({#intersection} and {#difference} answer in
+  #   `self`'s unit, since their values are `self`'s).
   #
-  #   @param other [CArray, Array, Range] promoted with `self`.
+  #   @param other [CArray, Array] promoted with `self` (a Range is refused, as by {#is_in}).
   #   @param sort [Boolean] when true, return the values sorted ascending
   #     (a merged, ordered set — e.g. a common time axis).
   #   @return [CArray] 1-D CArray of the combined distinct values.
   def union (other, sort: false)
+    refuse_range_set(other, "union")
     a, b = promote_value_set(other)
     r = a.__send__(:__union__, b)
     sort ? r.sort : r
@@ -98,6 +122,16 @@ class CArray
 
   private
 
+  # A Range reads as an interval in Ruby, which a set of its steps is not
+  # (2.5 is not in [2, 3, 4]), so the set-valued verbs refuse one rather
+  # than answer for the steps.
+  def refuse_range_set (values, verb)
+    return unless values.is_a?(Range)
+    raise ArgumentError,
+          "#{verb}: a Range is not taken as a set; pass its values as an Array " \
+          "((#{values.inspect}).to_a), or test an interval with is_between(#{values.inspect})"
+  end
+
   # 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 data types are reconciled,
@@ -113,13 +147,69 @@ class CArray
   # operand (Numo, a MemoryView producer, ...) comes in through wrap_readonly,
   # the canonical type-coercion entry, so its format's data type drives the promote.
   def promote_value_set (values)
+    # Two time arrays of different units meet in the finer one.
+    if values.is_a?(CArray) && values.class == self.class &&
+       respond_to?(:in_common_unit_with)
+      return in_common_unit_with(values)
+    end
+    values = values_for_lookup(values) if values.is_a?(CArray)
+    # Two fixed-width string arrays of different widths meet at the wider.
+    if values.is_a?(CArray) && data_type == CA_FIXLEN && values.data_type == CA_FIXLEN
+      return fixlen_widened_with(values)
+    end
+    # A Face that reconciles operands (CATime) reads a bare Array as values
+    # of its own kind -- instants written as Time / String / elements -- and
+    # meets them as a comparison does (comparable_pair).
+    if values.is_a?(Array) && face? && respond_to?(:comparable_pair)
+      return comparable_pair(values)
+    end
+    # A single value (a Time, an element, a bare number) is a set of one,
+    # read the same way; a bare number is refused like any other operand
+    # that is not of its kind.
+    if !values.is_a?(CArray) && !values.is_a?(Range) && face? &&
+       respond_to?(:comparable_pair)
+      return comparable_pair([values])
+    end
+    # ...and so does an array of values that are not of its kind (an object
+    # column of Time values, a string column).
+    if values.is_a?(CArray) && respond_to?(:comparable_pair) &&
+       !values.respond_to?(:comparable_pair)
+      return comparable_pair(values)
+    end
+    # The same from the other side: values of a time array looked for in an
+    # array that is not one.
+    if values.is_a?(CArray) && values.respond_to?(:comparable_pair) &&
+       !respond_to?(:comparable_pair)
+      set, own = values.comparable_pair(self)
+      return [own, set]
+    end
+    # A Face whose storage is not of its surface type.  When its cells are
+    # its values, the set meets it as it would meet an array of the storage
+    # type, and the Face stays while that type does not change.  Any other
+    # Face leaves the set to the lookup, which brings it into the Face's
+    # space or refuses it.
+    if face? && (storage = face_storage).data_type != data_type
+      unless comparable_storage?
+        set = values.is_a?(Range) ? values.to_a : values
+        return [self, set.is_a?(CArray) ? set : CArray.wrap_readonly(set)]
+      end
+      s, set = storage.send(:promote_value_set, values)
+      return [s.equal?(storage) ? self : s, set]
+    end
     case values
     when Array then return promote_elements(values)
     when Range then return promote_elements(values.to_a)
     end
+    # A single value is a set of one, as [value] is.  wrap_readonly would make
+    # it an object array, which takes self into the object lane, where 2.0 is
+    # not eql? 2.
+    if !values.is_a?(CArray) && !values.respond_to?(:to_ca) &&
+       !CArray.memory_view_available?(values)
+      return promote_elements([values])
+    end
     set = values.is_a?(CArray) ? values : CArray.wrap_readonly(values)
     return [self, set] if set.data_type == data_type   # common fast path
-    t = CArray.result_type(self, set)
+    t = query_match_type(set)
     [coerce_self(t), set.to_type(t)]
   end
 
@@ -136,15 +226,55 @@ class CArray
       # 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.
+      # coerce: a fixlen or object set holds values of self's kind (see above)
       [self, elems.to_ca.to_type(data_type, bytes: bytes)]
     elsif data_type == CA_OBJECT
+      # coerce: an object set holds values of self's kind
       [self, elems.to_ca.to_type(data_type)]
+    elsif elems.any? { |v| v.is_a?(String) || v.is_a?(Symbol) }
+      # A String is a value, which result_type would read as the name of a
+      # data type; a numeric self meets it in the object lane.
+      [to_type(CA_OBJECT), elems.to_ca.to_type(CA_OBJECT)]
     else
       t = CArray.result_type(self, *elems)
       [coerce_self(t), elems.to_ca.to_type(t)]
     end
   end
 
+  # +other+ as a lookup against self reads it.  A string array whose cells
+  # hold ranges into a pool of its own (CAConstString) is read by its
+  # strings, and a categorical by its labels, since their storage is not
+  # their values; anything else, or the same kind of array as self, is
+  # taken as it is.  A record is left to be refused.
+  def values_for_lookup (other)
+    return other if other.send(:orderable_storage?)
+    return other if face? && other.class == self.class
+    if other.respond_to?(:to_string)
+      other.to_string
+    elsif other.is_a?(CACategorical)
+      other.to_type(:object)
+    else
+      other
+    end
+  end
+
+  # [self, other] at one cell width when both are fixed-width string arrays
+  # (CAFixlenString) of different widths: the narrower is padded with NUL to
+  # the wider, as concatenate joins them, so a string matches whatever width
+  # it is held at.  Raw fixlen cells of different widths are values of
+  # different lengths, not padded strings, and are left as they are (the
+  # lookup refuses them, naming the widths).
+  def fixlen_widened_with (other)
+    return [self, other] if bytes == other.bytes
+    return [self, other] unless is_a?(CAFixlenString) && other.is_a?(CAFixlenString)
+    w = [bytes, other.bytes].max
+    [widen_fixlen_string(self, w), widen_fixlen_string(other, w)]
+  end
+
+  def widen_fixlen_string (x, w)
+    x.bytes == w ? x : x.to_fixlen_string(bytes: w)
+  end
+
   def coerce_self (t)
     CArray.result_type(self) == t ? self : to_type(t)
   end

data/lib/carray/methods/join.rb

@@ -46,12 +46,7 @@ class CArray
       return sep.nil? ? to_a.join : to_a.join(sep)
     end
 
-    ax = Integer(axis)
-    ax += ndim if ax < 0
-    if ax < 0 || ax >= ndim
-      raise ArgumentError,
-            "axis #{axis.inspect} out of range for ndim=#{ndim}"
-    end
+    ax = normalize_axis(axis, "join")
 
     sep_str = sep || ""
 
@@ -66,7 +61,7 @@ class CArray
       t = transpose(*order)
     end
     inner = t.shape[-1]
-    outer_n = t.elements / inner  # 1 when ndim == 1
+    outer_n = t.shape[0...-1].inject(1, :*)  # 1 when ndim == 1
     flat = t.reshape(outer_n, inner)
 
     strings = Array.new(outer_n) { |i| flat[i, nil].to_a.join(sep_str) }

data/lib/carray/methods/lag.rb

@@ -0,0 +1,49 @@
+class CArray
+
+  # @overload lag(n = 1, axis: nil)
+  #   Returns the value `n` steps earlier along `axis`, cell by cell: cell
+  #   `i` of the result is cell `i - n` of `self`. A cell with no value `n`
+  #   steps back is UNDEF, so a difference against it is UNDEF rather than
+  #   a difference against a stand-in value:
+  #
+  #   ```
+  #   x = CA_FLOAT64([1.0, 4.0, 9.0])
+  #   x.lag           # => [UNDEF, 1.0, 4.0]
+  #   x - x.lag       # => [UNDEF, 3.0, 5.0]
+  #   x.lag(-1)       # => [4.0, 9.0, UNDEF]   (the value one step later)
+  #   ```
+  #
+  #   The cell `n` steps back is taken by position: when it is masked, the
+  #   result is UNDEF there too. It is `shift` with `UNDEF` as the fill
+  #   value, and returns the same kind of view: it shares storage with
+  #   `self`. Use `copy` for an independent array.
+  #
+  #   The steps run along one axis. A 1-D array has only one, so `axis:`
+  #   may be left out; an array of more dimensions must name it, since
+  #   stepping back through the cells in flatten order would carry a value
+  #   across from the end of one row to the start of the next.
+  #
+  #   @param n [Integer] steps back; a negative `n` looks ahead.
+  #   @param axis [Integer, nil] the axis the steps run along.
+  #   @return [CArray] a view, shaped like `self`.
+  #   @raise [TypeError] when `n` or `axis` is not an Integer.
+  #   @raise [ArgumentError] when `axis` is out of range, or left out for an
+  #     array of more than one dimension.
+  def lag (n = 1, axis: nil)
+    unless n.is_a?(Integer)
+      raise TypeError, "lag: n must be an Integer (got #{n.class})"
+    end
+    if axis.nil?
+      unless ndim == 1
+        raise ArgumentError,
+              "lag: name the axis to step along (axis:) for an array of " \
+              "#{ndim} dimensions"
+      end
+      axis = 0
+    end
+    steps = Array.new(ndim, 0)
+    steps[normalize_axis(axis, "lag")] = n
+    shift(*steps, fill_value: UNDEF)
+  end
+
+end

data/lib/carray/methods/locate_addr.rb

@@ -1,3 +1,6 @@
+require "carray/methods/is_in"   # fixlen_widened_with, values_for_lookup
+require "carray/distance_limit"
+
 class CArray
 
   # @!group Sorting and searching
@@ -27,29 +30,63 @@ class CArray
   #   `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.
+  #   longer matches `1`, and integers of mixed sign are matched by value
+  #   (`-1` never matches `255`). Cross-family input (numeric against
+  #   fixlen) raises.
+  #
+  #   A time key (`CATime`) reads values that are not time arrays -- Time,
+  #   Date or String objects, in an Array, an `:object` array or a string
+  #   array -- as instants, on either side of the lookup, as {#is_in} does.
   #
   #   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.
+  #     any shape (used as flat). An Array or Range is the list of its
+  #     values, met at a common type with `self` as {#is_in} meets one, so
+  #     `2` finds `2.0`.
   #   @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.
+  #   @raise [CArray::DataTypeError] when `self` and `ref` have no common data type.
   def locate_addr (ref)
+    # A time key (any Face that reconciles operands) against values that do
+    # not -- Time, Date or String objects, a string column -- reads them as
+    # values of its kind, whichever side they are on.
+    if ref.is_a?(CArray) && ref.class == self.class &&
+       respond_to?(:in_common_unit_with) && ref.unit != unit
+      a, b = in_common_unit_with(ref)
+      return a.locate_addr(b)
+    end
+    # They meet as a comparison does (comparable_pair).
+    if respond_to?(:comparable_pair) && !ref.respond_to?(:comparable_pair)
+      key, r = comparable_pair(ref)
+      return key.locate_addr(r)
+    elsif ref.respond_to?(:comparable_pair) && !respond_to?(:comparable_pair)
+      r, key = ref.comparable_pair(self)
+      return key.locate_addr(r)
+    end
+    unless ref.is_a?(CArray) || ref.respond_to?(:to_ca)
+      raise TypeError, "locate_addr: the reference is an array of values (got #{ref.class})"
+    end
+    # An Array or Range of values meets self as is_in's does: the common type
+    # comes from self and the elements, so 2 finds 2.0 in a float array.  The
+    # conversion keeps the order, so the addresses stay positions in ref.
+    if ref.is_a?(Array) || ref.is_a?(Range)
+      q, r = promote_elements(ref.is_a?(Range) ? ref.to_a : ref)
+      return q.send(:__locate_addr__, r)
+    end
     ref = ref.to_ca unless ref.is_a?(CArray)
-    # Put self and ref in a common lane via the single-source promotion rule
-    # (CArray.result_type), so a fractional query against an int ref is compared
-    # at the promoted type instead of truncating (1.5 no longer matches 1).
-    # to_type is elementwise and order-preserving, so the addresses stay valid
-    # indices into ref. result_type raises for cross-family input.
-    t = CArray.result_type(self, ref)
+    ref = values_for_lookup(ref)
+    if data_type == CA_FIXLEN && ref.data_type == CA_FIXLEN && bytes != ref.bytes
+      a, b = fixlen_widened_with(ref)
+      return a.locate_addr(b) unless a.equal?(self) && b.equal?(ref)
+    end
+    # Put self and ref in the type they match in (query_match_type), so a
+    # fractional query against an int ref is compared as a float (1.5 does
+    # not match 1) and a pair of mixed sign by value.  to_type is elementwise
+    # and order-preserving, so the addresses stay valid indices into ref.
+    t = ref.send(:query_match_type, self)
     q = (data_type     == t) ? self : to_type(t)
     r = (ref.data_type == t) ? ref  : ref.to_type(t)
     q.send(:__locate_addr__, r)
@@ -57,16 +94,18 @@ class CArray
 
   # @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`.
+  #   the nearest reference value. Continuous sibling of {#locate_addr}:
+  #   each cell is placed among the sorted reference values by comparing
+  #   it with them, so an integer key is exact at any size and an infinite
+  #   one keeps its place.  `:round` takes the nearer neighbour, the upper
+  #   one on a tie.
   #
-  #   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]`.
+  #   Outside `ref`'s span the direction still decides: `:floor` matches
+  #   a cell after the last value to that last value, `:ceil` matches a
+  #   cell before the first value to that first value, and `:round`
+  #   matches either to the nearer end.  The other side has no match
+  #   (`:floor` before the first value, `:ceil` after the last) and is
+  #   masked.  Use `tolerance:` to refuse matches that are too far away.
   #
   #   `tolerance:` (default `nil`) sets a maximum accepted absolute
   #   distance between `self[i]` and its matched `ref` value. When
@@ -76,50 +115,148 @@ class CArray
   #
   #   `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.
+  #   passed.  A masked or NaN `ref` value matches nothing.  Two time keys
+  #   of different units are compared in the finer of the two.
+  #   With one value present in `ref`, that value is the match for
+  #   every cell the direction allows (`:floor` at or after it, `:ceil`
+  #   at or before it, `:round` all).  With none, every cell is masked;
+  #   an empty `self` gives an empty result.  A masked or NaN cell of
+  #   `self` is always masked.
   #
   #   @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.
+  #   @param tolerance [Numeric, String, CATimedelta::Element, nil] maximum
+  #     accepted `|self - ref|` distance; cells beyond this are masked.
+  #     For a time key it is a duration: a String such as `"10 minutes"` or
+  #     a CATimedelta value (a bare number is refused, since its length
+  #     would depend on the key's unit). `nil` disables the check.
   #   @return [CArray] `:int64` flat addresses into `ref`, same shape as
-  #     `self`; out-of-range and beyond-tolerance cells are masked.
+  #     `self`; cells with no match in the direction and beyond-tolerance
+  #     cells are masked.
   #   @raise [ArgumentError] when `direction` is not one of the accepted
-  #     symbols.
+  #     symbols, or `tolerance` is not a duration for a time key.
   def locate_nearest_addr (ref, direction: :round, tolerance: nil)
     unless [:round, :floor, :ceil].include?(direction)
       raise ArgumentError,
             "locate_nearest_addr: direction must be :round / :floor / " \
             ":ceil (got #{direction.inspect})"
     end
+    [self, ref].each { |key| nearest_refuse_bytes(key) }
+    limit = tolerance && DistanceLimit.read(tolerance, self, "tolerance:")
+    return CArray.int64(*shape) if elements == 0
+    # A masked reference value matches nothing, as in locate_addr: sorting
+    # puts the masked ones last, and only the others are searched.  A NaN
+    # one has no place among the others either; it sorts after them.
     ri = ref.sort_addr
-    rs = ref[ri]
-    sec = rs.linear_section(self)
-    unless sec.is_a?(CArray)
-      # A single-element (scalar-like) self makes linear_section collapse to
-      # its scalar-query path, which returns a bare Float (or nil when out of
-      # range) instead of a CArray.  Rebuild a self-shaped float64 CArray so
-      # the mask_invalid -> direction -> project pipeline stays array-valued
-      # and the returned addr array matches self's shape.
-      fill = CArray.float64(*shape)
-      fill[] = sec.nil? ? UNDEF : sec
-      sec = fill
+    ri = ri[0...ref.count_not_masked] if ref.has_mask?
+    if ref.float? && ri.elements > 0
+      ri = ri[0...(ri.elements - ref[ri].is_nan.count(true))]
     end
-    masked = sec.mask_invalid
+    if ri.elements == 0
+      out = CArray.int64(*shape)
+      out[] = UNDEF
+      return out
+    end
+    rs = ref[ri]
+    n = rs.elements
+    rk, qk = nearest_keys(rs, self)
+    # The position of each cell among the sorted references is counted, not
+    # interpolated: :floor takes the last reference at or below it, :ceil the
+    # first at or above it.
+    # Counting keeps an integer key exact past 2**53 and an infinite one in
+    # its place, where an interpolated position would not.
     si = case direction
-         when :round then masked.round
-         when :floor then masked.floor
-         when :ceil  then masked.ceil
-         end.int64
+         when :floor then nearest_count_below(rk, qk, true) - 1
+         when :ceil  then nearest_count_below(rk, qk, false)
+         when :round then nearest_round(rk, qk, nearest_count_below(rk, qk, false))
+         end
+    si[si.lt(0) | si.ge(n)] = UNDEF
+    si[qk.is_nan.strip_mask(false)] = UNDEF if qk.float?
+    si = si.reshape(*shape)
+    si[is_masked] = UNDEF if has_mask?
     idx = ri.project(si)
-    if tolerance
+    if limit
       dist = (ref.project(idx) - self).abs
-      idx[dist > tolerance] = UNDEF
+      idx[dist > limit] = UNDEF
     end
     idx
   end
 
+  # A key held as fixed-length bytes (raw fixlen, or a fixlen string) has
+  # no nearest: the search counts keys as numbers.  A Face whose storage is
+  # a number (a time) is searched by that number.
+  # +subject+ and +remedy+ let a caller (CAFrame#join_asof) say it in its
+  # own words.
+  private def nearest_refuse_bytes(key, subject = nil, remedy = "match exact values with locate_addr")
+    # A Face whose cells encode the value (a const string, a categorical)
+    # is refused later by its own reconcile, which says why.
+    return unless key.is_a?(CArray) && key.__send__(:orderable_storage?)
+    storage = key.face? ? key.__send__(:face_storage) : key
+    return unless storage.data_type == CA_FIXLEN
+    subject ||= "locate_nearest_addr: a #{CArray::Inspector.type_label(key)} key"
+    raise CArray::DataTypeError,
+          "#{subject} is held as fixed-length bytes, which have no nearest; #{remedy}"
+  end
+
+  # The keys locate_nearest_addr orders by: the storage of the sorted
+  # reference and of the query, in one numeric type.  A Face key is first
+  # brought into the reference's space (two time keys of different units
+  # into the finer of the two, which holds both exactly); plain keys meet at
+  # the type CArray.result_type gives, an integer pair of mixed sign at one
+  # that holds both.
+  private def nearest_keys(rs, q)
+    if rs.face? || q.face?
+      if rs.respond_to?(:to_unit) && q.class == rs.class && q.unit != rs.unit
+        u  = CATimeUnitAlgebra.finer(rs.unit, q.unit)
+        rs = rs.to_unit(u)
+        q  = q.to_unit(u)
+      end
+      q  = rs.__send__(:reconcile_operand, q, "locate_nearest_addr")
+      rs = rs.__send__(:face_storage)
+    end
+    t = rs.send(:query_match_type, q)
+    rk = (rs.data_type == t) ? rs : rs.to_type(t)
+    qk = (q.data_type  == t) ? q  : q.to_type(t)
+    [rk, qk.flatten]
+  end
+
+  # For each query key, how many of the sorted reference keys are below it
+  # (inclusive: at or below).  A numeric key is binary-searched in C; an
+  # object key is sorted together with the references, a tie putting the
+  # reference first when it counts, and counted against the references met
+  # before it.
+  private def nearest_count_below(rk, qk, inclusive)
+    return rk.send(:__count_below__, qk, inclusive) unless rk.data_type == CA_OBJECT
+    n, m = rk.elements, qk.elements
+    keys = CArray.concatenate([rk, qk])
+    tag  = CArray.int8(n + m)
+    tag[0...n]   = inclusive ? 0 : 1
+    tag[n...n+m] = inclusive ? 1 : 0
+    perm  = CArray.sort_addr(keys, tag)
+    seen  = perm.lt(n).cumsum.int64
+    query = perm.ge(n)
+    count = CArray.int64(m)
+    count[perm[query] - n] = seen[query]
+    count
+  end
+
+  # :round -- an exact match takes its first reference; otherwise the
+  # nearer of the two neighbours, the upper one on a tie.  +lt+ counts the
+  # references below each key, so the upper neighbour is at lt and an exact
+  # match is the reference there.
+  private def nearest_round(rk, qk, lt)
+    lo = rk.project(lt - 1)
+    hi = rk.project(lt)
+    upper = (hi - qk).le(qk - lo).strip_mask(false)
+    upper[lo.is_masked] = true if lo.has_mask?
+    upper[hi.is_masked] = false if hi.has_mask?
+    upper[hi.eq(qk).strip_mask(false)] = true
+    si = lt - 1
+    si[upper] = lt[upper]
+    si
+  end
+
   # @!endgroup
 
 end

data/lib/carray/methods/mode.rb

@@ -65,12 +65,25 @@ class CArray
   #   Only meaningful for discrete / binned data: raw float is almost all
   #   unique, so every value is modal and the per-axis Array grows to the
   #   fiber length. Bin first. Same NaN / mask semantics as {#is_mode}.
+  #   A complex array raises {CArray::DataTypeError}, since the modes
+  #   are listed in ascending order; {#is_mode} marks its modal cells.
   #
   #   @param axis [Integer, nil] axis to take the mode along; `nil` uses
   #     the whole array.
   #   @return [CArray, Array<CArray>] 1-D CArray (flat) or an Array of
   #     reduced CArrays, one per mode rank (per-axis).
   def mode (axis: nil)
+    # An error from the methods mode is made of (sort, ...) names mode.
+    CArray.__name_errors_after_method__(:mode) { mode_answered(axis) }
+  end
+
+  private def mode_answered (axis)
+    if complex?
+      raise CArray::DataTypeError,
+            "mode: the modes are listed in ascending order, and a " \
+            "#{data_type_name} value has no order (complex numbers are not " \
+            "ordered); is_mode marks the cells that hold a mode"
+    end
     return __mode_flat if axis.nil?
     k = normalize_axis(axis, "mode")
 
@@ -120,7 +133,11 @@ class CArray
   def __mode_flat
     values, counts = value_counts
     return values if values.elements == 0
-    values[counts.eq(counts.max)].sort
+    modes = values[counts.eq(counts.max)]
+    # Records are sorted only by the members their struct declares in
+    # order_by:; without one the modes stay in first-appearance order.
+    return modes if is_a?(CARecord) && data_class.order_by.nil?
+    modes.sort
   end
 
 end