carray 3.0.1 → 3.0.3

data/lib/carray/meld_reduce.rb

@@ -36,7 +36,7 @@ class CAMeld
 
   def sum(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    axis = meld_fast_path_axis(kw)
     if axis.nil?
       parents.map(&:sum).inject(:+)
     elsif meld_axis_normalized?(axis)
@@ -52,7 +52,10 @@ class CAMeld
   # @return [CArray, Numeric]
   def mean(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    # The combine divides in Float; an object array's mean stays exact
+    # (Rational, Integer division) on the core path.
+    return super if object?
+    axis = meld_fast_path_axis(kw)
     # `mean` has no identity: an empty set of contributors has no defined
     # mean (0/0 = NaN).  Punt to super, which returns UNDEF: a reduction
     # with no contributors yields the identity where one exists and UNDEF
@@ -78,12 +81,12 @@ class CAMeld
   # @return [CArray, Numeric]
   def min(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    axis = meld_fast_path_axis(kw)
     # `min` has no identity — empty parent list / all-empty parents punt to
     # super for UNDEF.
     if axis.nil?
       return super if parents.all? { |p| p.elements == 0 }
-      parents.reject { |p| p.elements == 0 }.map(&:min).min
+      meld_combine_flat(:min)
     elsif meld_axis_normalized?(axis)
       return super if parents.all? { |p| p.dim[meld_axis] == 0 }
       nonempty = parents.reject { |p| p.dim[meld_axis] == 0 }
@@ -99,10 +102,10 @@ class CAMeld
   # @return [CArray, Numeric]
   def max(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    axis = meld_fast_path_axis(kw)
     if axis.nil?
       return super if parents.all? { |p| p.elements == 0 }
-      parents.reject { |p| p.elements == 0 }.map(&:max).max
+      meld_combine_flat(:max)
     elsif meld_axis_normalized?(axis)
       return super if parents.all? { |p| p.dim[meld_axis] == 0 }
       nonempty = parents.reject { |p| p.dim[meld_axis] == 0 }
@@ -168,6 +171,9 @@ class CAMeld
   # more elaborate (min_count / fill_value / keep_axis / multi-axis /
   # mask propagation) punts to super.
   def meld_reduce_fast_path_ok?(kw)
+    return false unless CArray.__fast_paths_enabled__
+    # The mask of a meld is a meld built in C, with no parents list.
+    return false unless parents
     return false unless (kw.keys - [:axis]).empty?
     axis = kw[:axis]
     unless axis.nil?
@@ -177,9 +183,30 @@ class CAMeld
     end
     return false if has_mask?
     parents.each { |p| return false if p.has_mask? }
+    # A meld of Face arrays keeps its parents in their Face; the per-parent
+    # calls would reach the Face's own reductions, which answer in the Face's
+    # terms (or refuse), not in storage.
+    parents.each { |p| return false if p.face? }
     true
   end
 
+  # The axis a fast path reduces along.  A 1-D meld has only the meld axis,
+  # and reducing it is reducing the whole array: the answer is a scalar, as
+  # for the flat call.
+  def meld_fast_path_axis(kw)
+    ndim == 1 ? nil : kw[:axis]
+  end
+
+  # The per-parent answers of a whole-array min / max, combined by core's
+  # own min / max so NaN loses the way it loses inside one parent (Ruby's
+  # Array#min would raise on it).
+  def meld_combine_flat(op)
+    vals = parents.reject { |p| p.elements == 0 }.map(&op)
+    part = CArray.new(data_type, [vals.size])
+    vals.each_with_index { |v, i| part[i] = v }
+    part.public_send(op)
+  end
+
   # Non-meld-axis decompose: each parent reduces the same axis independently,
   # then the K per-parent results are concatenated back along the meld axis.
   # Materialised to entity (`.copy`) to match CArray#reduce entity semantics.
@@ -198,7 +225,13 @@ class CAMeld
 
   def variance_family(args, kw, sample:, sqrt:)
     return yield unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    # The merge works in Float; an object array's variance stays exact
+    # (Rational, BigDecimal) on the core path.
+    return yield if object?
+    # The merge squares the difference of means, which for complex values is
+    # not |δ|²; the core path computes the variance of a complex array.
+    return yield if complex?
+    axis = meld_fast_path_axis(kw)
     # 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,

data/lib/carray/methods/align_addr.rb

@@ -85,8 +85,10 @@ class CArray
   #     b_on_grid = b_data.project(ib)
   #
   #   `direction:` (`:round` / `:floor` / `:ceil`) and `tolerance:` are
-  #   forwarded to {#locate_nearest_addr}: out-of-range grid points, and points
-  #   whose nearest value is farther than `tolerance`, come back masked.
+  #   forwarded to {#locate_nearest_addr}: grid points with no match in the
+  #   direction (before an array's first value under `:floor`, after its last
+  #   under `:ceil`), and points whose match is farther than `tolerance`, come
+  #   back masked.
   #
   #   @param arrays [Array<CArray>] one or more arrays (Array / Range coerced
   #     via `to_ca`).
@@ -94,8 +96,10 @@ class CArray
   #     `nil` uses the first array verbatim.
   #   @param direction [:round, :floor, :ceil] rounding rule for the nearest
   #     match.
-  #   @param tolerance [Numeric, nil] maximum accepted distance; farther grid
-  #     points are masked. `nil` disables the check.
+  #   @param tolerance [Numeric, String, CATimedelta::Element, nil] maximum
+  #     accepted distance; farther grid points are masked. For time keys it
+  #     is a duration (`"10 minutes"` or a CATimedelta value), as in
+  #     {#locate_nearest_addr}. `nil` disables the check.
   #   @return [Array<CArray>] `[common, idx_0, idx_1, ...]`.
   #   @raise [ArgumentError] when no array is given (or `direction` is invalid,
   #     raised by {#locate_nearest_addr}).

data/lib/carray/methods/bincount.rb

@@ -38,7 +38,7 @@ class CArray
 
     if elements.zero?
       if weights
-        out = CArray.new(weights.data_type, [length])
+        out = CArray.new(weights.data_type, [length], bytes: weights.bytes)
       else
         out_type = (length > 0xFFFFFFFF) ? CA_UINT64 : CA_UINT32
         out = CArray.new(out_type, [length])
@@ -54,7 +54,7 @@ class CArray
       # Every cell is masked: no labels to count, same result as an empty
       # input (all-zero output of the requested minimum length).
       if weights
-        out = CArray.new(weights.data_type, [length])
+        out = CArray.new(weights.data_type, [length], bytes: weights.bytes)
       else
         out_type = (length > 0xFFFFFFFF) ? CA_UINT64 : CA_UINT32
         out = CArray.new(out_type, [length])

data/lib/carray/methods/bit_string.rb

@@ -58,9 +58,12 @@ class CArray
   #   multiple of 8) are zero-filled. The byte order matches the packed-bit
   #   convention used by Apache Arrow validity bitmaps and PEP 3118 `?` /
   #   `_Bool` at the bit level.
+  #   A masked cell has no bit to pack, so a receiver with masked cells is
+  #   refused; pack the mask separately with {#validity_bits}.
   #   @return [CArray] uint8 CArray of shape `[ceil(n / 8)]`.
-  #   @raise [ArgumentError] when the receiver is not 1-D or its
-  #     `data_type` is not one of `CA_BOOLEAN` / `CA_UINT8` / `CA_INT8`.
+  #   @raise [ArgumentError] when the receiver is not 1-D, its `data_type`
+  #     is not one of `CA_BOOLEAN` / `CA_UINT8` / `CA_INT8`, or it has
+  #     masked cells.
   def pack_bits
     unless data_type == CA_BOOLEAN || data_type == CA_UINT8 || data_type == CA_INT8
       raise ArgumentError,
@@ -71,7 +74,15 @@ class CArray
     n_bytes = (n + 7) / 8
     packed = CArray.uint8(n_bytes) { 0 }
     return packed if n == 0
-    packed.bitarray.reshape(-1)[0..n-1] = self
+    source = self
+    if has_mask?
+      if count_masked > 0
+        raise ArgumentError,
+          "pack_bits: masked cells have no bit to pack; pack the mask with validity_bits"
+      end
+      source = value
+    end
+    packed.bitarray.reshape(-1)[0..n-1] = source
     packed
   end
 

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/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 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
+  #   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/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,14 +15,29 @@ 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}):
   #   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.
+  #
+  #   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
@@ -61,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
 
@@ -75,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
@@ -110,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
 
@@ -126,14 +193,71 @@ class CArray
   # 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)
+      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