carray 3.0.2 → 3.0.3

data/lib/carray/methods/composition.rb

@@ -75,7 +75,8 @@ class CArray
   #   Use `CArray.meld` for the uniform-shape view-default counterpart.
   #
   #   @param list [Array<CArray>] pieces to concatenate.
-  #   @param axis [Integer] axis to concatenate along.
+  #   @param axis [Integer, nil] axis to concatenate along; `nil` is the
+  #     same as `0`.
   #   @param data_type [Symbol, Integer, nil] result `data_type`;
   #     inferred via `result_type` when `nil`.
   #   @return [CArray] fresh CArray with per-piece `axis` sizes summed.
@@ -83,7 +84,8 @@ class CArray
   #     inconsistent.
   def self.concatenate (list, axis: 0, data_type: nil)
     raise ArgumentError, "concatenate: list must not be empty" if list.empty?
-    __ragged_paste(list, [list.size], axis, data_type)
+    axis = 0 if axis.nil?
+    __ragged_paste(list, [list.size], axis, data_type, "concatenate")
   end
 
   # @overload concatenate(*others, axis: 0, data_type: nil)
@@ -128,7 +130,7 @@ class CArray
       raise ArgumentError,
             "mosaic: tdim product (#{expected}) must equal list size (#{list.size})"
     end
-    __ragged_paste(list, tdim, axis, data_type)
+    __ragged_paste(list, tdim, axis, data_type, "mosaic")
   end
 
   # Shared eager paste-loop helper (= ex-`combine` paste implementation,
@@ -136,7 +138,7 @@ class CArray
   # shape obtained by tiling `list` over `tdim` starting at `axis`, with
   # per-piece dim sizes summed along each tile axis (= block-matrix
   # consistency required across rows / columns).
-  def self.__ragged_paste (list, tdim, axis, data_type)
+  def self.__ragged_paste (list, tdim, axis, data_type, name)
     list = CArray.promote_list(list, data_type: data_type)
     # promote_list has already enforced homogeneity (= common data_type, and
     # for Face elements: same Face class + portable + state-compatible).  So,
@@ -144,12 +146,16 @@ class CArray
     # result with face_lift, rather than special-casing data_class / DATA_SIZE
     # here (= which only ever handled CARecord and silently corrupted plain
     # fixlen / numeric Faces by leaving bytes nil).
-    face_parent = list[0].face? ? list[0] : nil
+    # The Face is re-wrapped from the widest piece: a fixlen Face carries
+    # its cell width, and the result is as wide as its widest piece.
+    face_parent = list[0].face? ? list.max_by(&:bytes) : nil
     if face_parent
-      list = list.map { |x| s = x; s = s.parent while s.face?; s }
+      list = list.map { |x| x.__send__(:__face_storage__) }
     end
     data_type = list[0].data_type
-    bytes     = (data_type == :fixlen) ? list[0].bytes : nil
+    # Fixlen pieces of different widths join at the widest, so no cell is
+    # cut; each narrower piece is padded with NUL as it is pasted.
+    bytes     = (data_type == :fixlen) ? list.map(&:bytes).max : nil
     # promote_list guarantees a non-empty list of CArrays, so the reference
     # shape is simply the first element (a CScalar carries shape [1], so a
     # leading scalar is fine; the scalar-expansion pass below broadcasts it).
@@ -157,7 +163,7 @@ class CArray
     dim   = ref.shape
     ndim  = ref.ndim
     tndim = tdim.size
-    axis = CArray.normalize_axis(axis, ndim - tndim + 1, "concatenate/mosaic")
+    axis = CArray.normalize_axis(axis, ndim - tndim + 1, name)
 
     list = list.map do |x|
       if x.scalar?
@@ -190,7 +196,7 @@ class CArray
     block.each_with_index do |item, *tidx|
       unless item.ndim == ndim
         raise ArgumentError,
-              "concatenate/mosaic: piece at tile #{tidx.inspect} has ndim " \
+              "#{name}: piece at tile #{tidx.inspect} has ndim " \
               "#{item.ndim} (expected #{ndim})"
       end
       ndim.times do |d|
@@ -199,7 +205,7 @@ class CArray
         expected = on_tile ? tile_sizes[i][tidx[i]] : dim[d]
         unless item.shape[d] == expected
           raise ArgumentError,
-                "concatenate/mosaic: piece at tile #{tidx.inspect} has " \
+                "#{name}: piece at tile #{tidx.inspect} has " \
                 "#{on_tile ? 'tile' : 'non-tile'} axis #{d} size " \
                 "#{item.shape[d]} (expected #{expected}); pieces must agree " \
                 "on non-tile axes and be block-matrix consistent along tile axes"

data/lib/carray/methods/factorize.rb

@@ -23,8 +23,8 @@ class CArray
   #   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}.
+  #   `CA_FIXLEN`. Complex values compare by value, with NaN and -0.0
+  #   treated the same way in each component.
   #
   #   There is no `sort:` here, unlike {#unique} and {#value_counts}:
   #   the codes index the levels, so reordering the vocabulary would

data/lib/carray/methods/gather_nd.rb

@@ -64,7 +64,8 @@ class CArray
     flat_addr, outer, rest = gather_nd_flat_addr(indices, "gather_nd")
     out_shape = outer + rest
     # flatten + 1-D fancy indexing -> CAMapping view -> materialise via .copy.
-    result = self.flatten[flat_addr].copy
+    # A masked coordinate reads as UNDEF: project carries the address mask.
+    result = flat_addr.has_mask? ? flatten.project(flat_addr) : self.flatten[flat_addr].copy
     out_shape.empty? ? result : result.reshape(*out_shape)
   end
 
@@ -91,7 +92,12 @@ class CArray
   #   @raise [IndexError] when a coordinate is out of range on any axis.
   def put_nd (indices, values)
     flat_addr, _outer, _rest = gather_nd_flat_addr(indices, "put_nd")
-    self.flatten[flat_addr] = values
+    if flat_addr.has_mask?
+      # A masked coordinate writes nothing: scatter_replace! skips it.
+      flatten.scatter_replace!(flat_addr, values)
+    else
+      self.flatten[flat_addr] = values
+    end
     self
   end
 
@@ -150,6 +156,11 @@ class CArray
     flat_idx = (flat_idx_raw + dims) % dims
 
     base     = (flat_idx * strides).sum(axis: 1).int64.reshape(m)  # (M,)
+    # sum skips a masked coordinate, which would leave its row pointing at
+    # the wrong cell: a row with any masked coordinate has no address.
+    if flat_idx_raw.has_mask?
+      base[flat_idx_raw.is_masked.any(axis: 1)] = UNDEF
+    end
 
     flat_addr =
       if rest.empty?

data/lib/carray/methods/insert_block.rb

@@ -11,8 +11,8 @@ class CArray
   #   appends at the end) and a negative value counts from the end;
   #   `bsize[i]` must be non-negative. Inserted cells are filled by
   #   the block's return value, or left at the type's default when
-  #   no block is given. Preserves fixlen bytes and Face identity
-  #   (built on the storage layout, re-wrapped via `face_lift`).
+  #   no block is given. Preserves fixlen bytes and Face identity; the
+  #   block returns a value of the array (a Time for a time array).
   #   The `offset` array is not mutated.
   #
   #   @param offset [Array<Integer>] insertion offset per axis.
@@ -40,21 +40,16 @@ class CArray
       # offset == dim (append) leaves nothing on the upper side to shift.
       grids[i][offset[i]..-1].seq!(offset[i]+bsize[i]) if offset[i] < shape[i]
     end
-    # Build at the storage layout (preserving bytes for fixlen / Face),
-    # then re-wrap as the same Face.
-    face_parent = self.face? ? self : nil
-    src = self
-    src = src.parent while src.face?
-    dt    = src.data_type
-    bytes = (dt == :fixlen) ? src.bytes : nil
-    out = CArray.new(dt, newdim, bytes: bytes)
+    # The original cells are copied as storage, so a read-only Face inserts
+    # too; the block's value is written as a value of the array, which a
+    # read-only Face refuses.
+    out = __blank_like__(newdim)
     if block_given?
-      sel = out.true
-      sel[*grids] = 0
+      sel = CArray.boolean(*newdim) { true }
+      sel[*grids] = false
       out[sel] = block.call
     end
-    out[*grids] = src
-    out = out.face_lift(face_parent) if face_parent
+    out.__send__(:__face_storage__)[*grids] = __face_storage__
     return out
   end
 

data/lib/carray/methods/is_in.rb

@@ -15,8 +15,11 @@ class CArray
   #   {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 +30,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.
@@ -64,6 +76,7 @@ class CArray
   def intersection (other, sort: false)
     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
 
@@ -78,13 +91,17 @@ class CArray
   def difference (other, sort: false)
     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 sort [Boolean] when true, return the values sorted ascending
@@ -113,13 +130,60 @@ 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.
+    if values.is_a?(Array) && face? && respond_to?(:to_comparable)
+      return [self, to_comparable(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?(:to_comparable)
+      return [self, to_comparable([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?(:to_comparable) &&
+       !values.respond_to?(:to_comparable)
+      return [self, values_in_face(self, values) || to_comparable([])]
+    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?(:to_comparable) &&
+       !respond_to?(:to_comparable)
+      return [values_in_face(values, self) || values.to_comparable([]), values]
+    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
     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 = value_match_type(CArray.result_type(self, set), set.data_type)
     [coerce_self(t), set.to_type(t)]
   end
 
@@ -141,10 +205,59 @@ class CArray
       [self, elems.to_ca.to_type(data_type)]
     else
       t = CArray.result_type(self, *elems)
+      t = value_match_type(t, CA_INT64) if elems.any? { |v| v.is_a?(Integer) && v < 0 }
       [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
+
+  # The values of +other+, which has no to_comparable, read as values of +face+'s
+  # kind (instants written as Time / Date / String for a time key), in an
+  # array of +other+'s shape; a masked cell stays masked.  nil when every
+  # cell is masked: there is nothing to read.
+  private def values_in_face(face, other)
+    return face.to_comparable(other) if other.is_a?(Array)
+    vals = other.flatten.to_a
+    filler = vals.find { |v| !UNDEF.equal?(v) }
+    return nil if filler.equal?(nil) && vals.all? { |v| UNDEF.equal?(v) }
+    out = face.to_comparable(vals.map { |v| UNDEF.equal?(v) ? filler : v })
+    out[other.is_masked.flatten] = UNDEF if other.has_mask?
+    out.reshape(*other.shape)
+  end
+
   def coerce_self (t)
     CArray.result_type(self) == t ? self : to_type(t)
   end

data/lib/carray/methods/join.rb

@@ -66,7 +66,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/locate_addr.rb

@@ -1,3 +1,5 @@
+require "carray/methods/is_in"   # fixlen_widened_with, values_in_face, values_for_lookup
+
 class CArray
 
   # @!group Sorting and searching
@@ -27,8 +29,13 @@ 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
@@ -41,15 +48,40 @@ class CArray
   #     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.
+  #   @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
+    if respond_to?(:to_comparable) && !ref.respond_to?(:to_comparable)
+      ref = values_in_face(self, ref)
+      return CArray.int64(*shape).fill(UNDEF) unless ref
+    elsif ref.respond_to?(:to_comparable) && !respond_to?(:to_comparable)
+      q = values_in_face(ref, self)
+      return CArray.int64(*shape).fill(UNDEF) unless q
+      return q.locate_addr(ref)
+    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
     ref = ref.to_ca unless ref.is_a?(CArray)
+    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 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)
+    # indices into ref. result_type raises for cross-family input; an integer
+    # pair of mixed sign is matched by value (see value_match_type).
+    t = value_match_type(CArray.result_type(self, ref), ref.data_type)
     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 +89,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 +110,157 @@ 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
+    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
+    if ri.elements == 0
+      out = CArray.int64(*shape)
+      out[] = UNDEF
+      return out
     end
-    masked = sec.mask_invalid
+    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
       dist = (ref.project(idx) - self).abs
-      idx[dist > tolerance] = UNDEF
+      idx[dist > nearest_tolerance(tolerance, dist)] = UNDEF
     end
     idx
   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 = value_match_type(CArray.result_type(q, rs), rs.data_type)
+    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
+
+  # The tolerance in the units of the distance. A time key measures its
+  # distance as a CATimedelta, so its tolerance is a duration: a String in
+  # the spelling CArray.time takes for a unit ("10 minutes"), or a
+  # CATimedelta value. A bare number would mean a different length in each
+  # unit, so it is refused there; any other key takes a number.
+  private def nearest_tolerance(tolerance, dist)
+    unless dist.is_a?(CATimedelta)
+      if tolerance.is_a?(String)
+        raise ArgumentError,
+              "tolerance: #{tolerance.inspect} is a duration, but the key is " \
+              "#{data_type_name}; give a number"
+      end
+      return tolerance
+    end
+    case tolerance
+    when String
+      res = CATime::Resolution.parse(tolerance)
+      CATimedelta::Element.new(res.count, res.base)
+    when CATimedelta::Element
+      tolerance
+    else
+      raise ArgumentError,
+            "tolerance: a time key needs a duration such as \"10 minutes\" " \
+            "or a CATimedelta value (got #{tolerance.inspect})"
+    end
+  end
+
   # @!endgroup
 
 end