carray 3.0.1 → 3.0.2

data/lib/carray/methods/is_in.rb

@@ -22,7 +22,10 @@ class CArray
   #   value-hash discovery family ({#unique} / {#value_counts}):
   #   numeric follows `==` with all NaN collapsed to one value and
   #   -0.0 == +0.0; `CA_OBJECT` follows Ruby `hash` / `eql?` with Float
-  #   NaN collapsed; `CA_FIXLEN` follows byte equality.
+  #   NaN collapsed; `CA_FIXLEN` follows byte equality over the whole
+  #   cell, with a short String in the set padded out to the cell width
+  #   (so a 5-byte array written from `"be"` is `is_in(["be"])`). A
+  #   `CA_FIXLEN` set given as a CArray must already be of that width.
   #
   #   Masked cells of `values` do not enter the set. Masked cells of
   #   `self` stay masked in the result (membership is unknown), so
@@ -126,7 +129,15 @@ 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)

data/lib/carray/methods/locate_addr.rb

@@ -1,8 +1,47 @@
 class CArray
 
-  # User-facing YARD docs for #locate_addr and #locate_nearest_addr live
-  # in yard-stubs/carray_order.rb (grouped with the search family).
+  # @!group Sorting and searching
 
+  # @overload locate_addr(ref)
+  #   Returns, for each element of `self`, the flat address into `ref`
+  #   where the value first occurs, or `UNDEF` where it is not present.
+  #   Builds a value-to-first-address map from `ref` in one pass (an
+  #   open-addressing hash, the same substrate as {#unique} /
+  #   {#value_counts}), then probes each element of `self`; no sort,
+  #   peak memory `O(distinct ref values)`.
+  #
+  #   The return is `ref`'s flat address (0 to `ref.elements - 1`), so a
+  #   multi-dimensional `ref` still yields a `self`-shaped result of flat
+  #   addresses; downstream reads (`ref[addr]`, `model_var[addr]`, ...)
+  #   apply it as a flat gather.
+  #
+  #   Works on numeric, `CA_OBJECT`, and `CA_FIXLEN` values, matching the
+  #   value-hash discovery family: numeric follows `==` with all NaN
+  #   collapsed to one value and `-0.0 == +0.0`; object follows Ruby
+  #   `hash` / `eql?` with Float NaN collapsed; fixlen follows byte
+  #   equality. When `ref` holds duplicate values the returned address is
+  #   the earliest (appearance-order) occurrence. Masked cells of `ref` do
+  #   not enter the map but still occupy their flat address; masked cells
+  #   of `self` are `UNDEF` in the result.
+  #
+  #   `self` and `ref` are compared at their common type, negotiated by
+  #   `CArray.result_type` — a fractional query against an integer `ref`
+  #   is compared at the promoted type rather than truncated, so `1.5` no
+  #   longer matches `1`. Cross-family input (numeric against fixlen)
+  #   raises.
+  #
+  #   Typical use is time-axis lookup: compute the address once against a
+  #   reference axis, then reuse it to gather from many `ref`-shaped
+  #   variables without repeating the lookup.
+  #
+  #   @param ref [CArray, Array, Range] reference values to match against;
+  #     any shape (used as flat). An Array or Range is coerced with `to_ca`
+  #     and so lands in `:object`, where numeric matching follows Ruby
+  #     `eql?` (`2.0` does not match `2`); pass a CArray to match in a
+  #     numeric lane.
+  #   @return [CArray] `:int64` flat addresses into `ref`, same shape as
+  #     `self`; unmatched cells are masked.
+  #   @raise [RuntimeError] when `self` and `ref` have no common data type.
   def locate_addr (ref)
     ref = ref.to_ca unless ref.is_a?(CArray)
     # Put self and ref in a common lane via the single-source promotion rule
@@ -16,6 +55,38 @@ class CArray
     q.send(:__locate_addr__, r)
   end
 
+  # @overload locate_nearest_addr(ref, direction: :round, tolerance: nil)
+  #   Returns, for each element of `self`, the flat address into `ref` of
+  #   the nearest reference value. Continuous sibling of {#locate_addr};
+  #   uses `linear_section` + rounding for non-exact matching against a
+  #   sorted `ref`.
+  #
+  #   Out-of-range cells of `self` (outside `ref`'s span) mask through the
+  #   pipeline: `linear_section` returns NaN, `mask_invalid` propagates
+  #   that as `UNDEF`, rounding and the int64 cast carry the mask, and
+  #   `project` scatters it into the final positions. `mask_invalid` runs
+  #   before rounding because `CArray#round` maps NaN to 0 and would
+  #   otherwise silently match `ref[0]`.
+  #
+  #   `tolerance:` (default `nil`) sets a maximum accepted absolute
+  #   distance between `self[i]` and its matched `ref` value. When
+  #   `|ref[addr] - self[i]| > tolerance`, the result cell is masked. Use
+  #   for accuracy-controlled matching (e.g. "an observation snaps to a
+  #   time step only if within N seconds").
+  #
+  #   `ref` need not be given in ascending order: it is sorted internally
+  #   and the returned addresses are mapped back to positions in `ref` as
+  #   passed.
+  #
+  #   @param ref [CArray] 1-D reference grid to match against.
+  #   @param direction [Symbol] `:round`, `:floor`, or `:ceil` — rounding
+  #     applied to the fractional position.
+  #   @param tolerance [Numeric, nil] maximum accepted `|self - ref|`
+  #     distance; cells beyond this are masked. `nil` disables the check.
+  #   @return [CArray] `:int64` flat addresses into `ref`, same shape as
+  #     `self`; out-of-range and beyond-tolerance cells are masked.
+  #   @raise [ArgumentError] when `direction` is not one of the accepted
+  #     symbols.
   def locate_nearest_addr (ref, direction: :round, tolerance: nil)
     unless [:round, :floor, :ceil].include?(direction)
       raise ArgumentError,
@@ -49,4 +120,6 @@ class CArray
     idx
   end
 
+  # @!endgroup
+
 end

data/lib/carray/methods/mask_duplicates.rb

@@ -1,3 +1,5 @@
+require "carray/methods/discovery_along"
+
 class CArray
 
   # @overload mask_duplicates(axis: nil)
@@ -23,7 +25,39 @@ class CArray
   #     `nil` uses flatten order.
   #   @return [CArray] shape-preserving copy of `self` with
   #     duplicates masked.
-  def mask_duplicates (axis: nil)
+  # @overload mask_duplicates(along: k)
+  #   Returns a shape-preserving copy of `self` with every cell of a
+  #   duplicated **sub-array** masked, comparing whole sub-arrays rather
+  #   than cells: `along: k` names the axis whose index enumerates them,
+  #   so `z.mask_duplicates(along: 0)` masks each repeated row of a 2-D
+  #   array and keeps the first occurrence.
+  #
+  #   Note the contrast with `axis:`, which names the axis a *fiber runs
+  #   along* and marks repeated values inside each fiber. The two cannot
+  #   be given together.
+  #
+  #   A sub-array holding a masked cell does not participate: it is
+  #   neither judged a duplicate nor able to make a later one, and its
+  #   cells keep the mask they came with. `object` arrays are refused,
+  #   because their cells hold Ruby references.
+  #
+  #   @param along [Integer] axis whose index enumerates the sub-arrays.
+  #   @return [CArray] shape-preserving copy of `self` with duplicated
+  #     sub-arrays masked.
+  def mask_duplicates (axis: nil, along: nil)
+    reject_axis_with_along(axis, along, "mask_duplicates")
+    if along
+      keys = fibers_as_cells(along, "mask_duplicates")
+      #  A sub-array that did not participate (it held a masked cell) is
+      #  masked in `keys` already; only the ones that did and repeated
+      #  are duplicates here.
+      repeated = keys.mask_duplicates.is_masked & keys.is_not_masked
+      args = [:_] * ndim
+      args[normalize_axis(along, "mask_duplicates")] = nil
+      spread = CArray.boolean(*shape)
+      spread[] = repeated[*args]
+      return mask_where(spread)
+    end
     dup =
       if axis.nil?
         # One seen-set over the flattened array, then restore shape.

data/lib/carray/methods/nunique.rb

@@ -1,3 +1,5 @@
+require "carray/methods/discovery_along"
+
 class CArray
 
   # @overload nunique(axis: nil, keep_axis: false)
@@ -29,7 +31,26 @@ class CArray
   #     axis as a length-1 axis instead of dropping it.
   #   @return [Integer, CArray] Integer for `axis: nil`, otherwise a
   #     reduced `CA_INT64` CArray.
-  def nunique (axis: nil, keep_axis: false)
+  # @overload nunique(along: k)
+  #   Returns how many distinct **sub-arrays** `self` holds, comparing
+  #   whole sub-arrays rather than cells: `along: k` names the axis
+  #   whose index enumerates them, so `z.nunique(along: 0)` counts the
+  #   distinct rows of a 2-D array. This is `len(np.unique(z, axis=k))`.
+  #
+  #   Note the contrast with `axis:`, which names the axis a *fiber runs
+  #   along* and counts the distinct values inside each fiber -- one
+  #   count per fiber, not one count for the array. The two cannot be
+  #   given together.
+  #
+  #   Sub-arrays holding a masked cell do not participate and are not
+  #   counted. `object` arrays are refused, because their cells hold
+  #   Ruby references.
+  #
+  #   @param along [Integer] axis whose index enumerates the sub-arrays.
+  #   @return [Integer] the number of distinct sub-arrays.
+  def nunique (axis: nil, keep_axis: false, along: nil)
+    reject_axis_with_along(axis, along, "nunique")
+    return fibers_as_cells(along, "nunique").nunique if along
     # Per-fiber single-pass seen-set hash (C __nunique__), one lane per data type
     # family (numeric widen / NaN collapse, object rb_hash + rb_eql, fixlen
     # byte-hash + memcmp). Masked cells are skipped; the accumulator is a no-op

data/lib/carray/methods/repeat.rb

@@ -0,0 +1,110 @@
+class CArray
+
+  # @overload repeat(count, axis: nil)
+  #   @overload repeat(counts, axis: nil)
+  #   Returns each element (or each sub-array) of `self` laid down
+  #   `count` times in place, one after another.
+  #
+  #   With an Integer, every element is repeated the same number of
+  #   times. With an array of counts -- one per element, or one per
+  #   sub-array when `axis:` is given -- each is repeated its own number
+  #   of times, and a count of 0 drops that one:
+  #
+  #     v = CA_INT([10, 20, 30])
+  #     v.repeat(2)              #  => [ 10, 10, 20, 20, 30, 30 ]
+  #     v.repeat([3, 1, 2])      #  => [ 10, 10, 10, 20, 30, 30 ]
+  #     v.repeat([2, 0, 1])      #  => [ 10, 10, 30 ]
+  #
+  #   This is `np.repeat`, and it is not {#tile}: `repeat` puts the
+  #   copies of one element next to each other, `tile` lays the whole
+  #   array down again -- `v.tile(2)` is `[10, 20, 30, 10, 20, 30]`.
+  #
+  #   `axis: k` repeats the sub-arrays enumerated by axis `k` rather
+  #   than the cells, so a 2-D array repeats whole rows and the result
+  #   keeps its shape apart from that axis:
+  #
+  #     t = CA_INT([[0, 1], [2, 3], [4, 5]])
+  #     t.repeat([2, 1, 1], axis: 0)
+  #     #  => [ [ 0, 1 ],
+  #     #       [ 0, 1 ],
+  #     #       [ 2, 3 ],
+  #     #       [ 4, 5 ] ]
+  #
+  #   Without `axis:` a multi-dimensional receiver is taken in flatten
+  #   (row-major) order and the result is 1-D, as `np.repeat` does.
+  #
+  #   The result is a **view** of `self` -- the same element named as
+  #   many times as it was repeated -- so nothing is copied and writing
+  #   through it reaches `self`, at every position that names the cell
+  #   written. Take a `copy` when that is not wanted.
+  #
+  #   Counts must be non-negative, and there must be exactly as many as
+  #   there are elements (or sub-arrays along `axis:`). A masked count
+  #   is refused: it names no number of repetitions.
+  #
+  #   @param count [Integer, CArray, Array] how many times to repeat --
+  #     one number for all, or one per element / sub-array.
+  #   @param axis [Integer, nil] axis whose index enumerates the
+  #     sub-arrays to repeat; `nil` repeats cells in flatten order.
+  #   @return [CArray] the repeated elements, as a view of `self`.
+  def repeat (count, axis: nil)
+    along = axis.nil? ? nil : normalize_axis(axis, "repeat")
+    width = along ? shape[along] : elements
+
+    counts =
+      case count
+      when Integer
+        if count < 0
+          raise ArgumentError, "repeat: count must not be negative (got #{count})"
+        end
+        CArray.int64(width).fill(count)
+      else
+        given = count.to_ca.int64
+        unless given.elements == width
+          raise ArgumentError,
+                "repeat: #{given.elements} counts for #{width} " \
+                "#{along ? "sub-arrays along axis #{along}" : 'elements'}"
+        end
+        if given.has_mask? and given.count_masked > 0
+          raise ArgumentError,
+                "repeat: a masked count names no number of repetitions"
+        end
+        if given.lt(0).any
+          raise ArgumentError, "repeat: counts must not be negative"
+        end
+        given.flatten
+      end
+
+    source = along ? self : (ndim > 1 ? flatten : self)
+    source[*gather_args(repeat_index(counts), along)]
+  end
+
+  #  The source index of every position in the result: element i appears
+  #  at the `counts[i]` positions starting at the exclusive prefix sum.
+  #
+  #  Marking those starts with +1 and running a cumulative sum turns the
+  #  marks back into indices, and does the right thing with a zero
+  #  count for free -- two elements then share a start, that position
+  #  carries 2, and the sum steps over the one that was asked for zero
+  #  times.
+  private def repeat_index (counts)
+    total = counts.sum.to_i
+    return CArray.int64(0) if total.zero?
+    starts = counts.cumsum.int64 - counts
+    marks  = CArray.int64(total)
+    #  A trailing zero count starts one past the end; it marks nothing,
+    #  which is what a zero count means.
+    marks.scatter_add!(starts[starts.lt(total)], 1)
+    marks.cumsum.int64 - 1
+  end
+
+  #  One index argument per axis: the gathered index on the axis being
+  #  repeated, whole axes everywhere else.
+  private def gather_args (index, along)
+    return [index] unless along
+    args = [nil] * ndim
+    args[along] = index
+    args
+  end
+
+end

data/lib/carray/methods/unique.rb

@@ -1,3 +1,5 @@
+require "carray/methods/discovery_along"
+
 class CArray
 
   # @overload unique(sort: false)
@@ -34,7 +36,45 @@ class CArray
   #
   #   @return [CArray] 1-D CArray of the distinct values, same data type
   #     as `self`.
-  def unique (sort: false)
+  #
+  # @overload unique(along: k)
+  #   Returns the distinct **sub-arrays** of `self`, comparing whole
+  #   sub-arrays rather than cells: `along: k` names the axis whose
+  #   index enumerates them, so `z.unique(along: 0)` gives the distinct
+  #   rows of a 2-D array, in first-appearance order. This is
+  #   `np.unique(z, axis=k)`.
+  #
+  #   Note the contrast with `axis:` on {#nunique} and
+  #   {#mask_duplicates}, which names the axis a *fiber runs along* and
+  #   asks about the values inside each fiber. The two cannot be given
+  #   together.
+  #
+  #   Distinctness is the family's, widened from a cell to a sub-array:
+  #   two sub-arrays are the same when every cell is, with all NaN one
+  #   value and -0.0 == +0.0. A sub-array holding a masked cell does not
+  #   participate and never appears in the result.
+  #
+  #   The result is a **view** of `self` -- the surviving sub-arrays,
+  #   not copies of them -- so writing through it reaches `self`. Take a
+  #   `copy` when that is not wanted. `sort:` is not available here:
+  #   sub-arrays have no order to sort by. `object` arrays are refused,
+  #   because their cells hold Ruby references.
+  #
+  #   @param along [Integer] axis whose index enumerates the sub-arrays.
+  #   @return [CArray] the distinct sub-arrays, same shape as `self`
+  #     except along `along`.
+  def unique (sort: false, along: nil)
+    if along
+      if sort
+        raise ArgumentError,
+              "unique: sort: is not available with along: -- sub-arrays have " \
+              "no order to sort by; the result is in first-appearance order"
+      end
+      keys = fibers_as_cells(along, "unique")
+      args = [nil] * ndim
+      args[normalize_axis(along, "unique")] = keys.mask_duplicates.is_not_masked
+      return self[*args]
+    end
     # Single-pass seen-set hash (C __unique_flat__), one lane per data type family:
     # integer widens to a 64-bit key; float uses the bitwise key with all-NaN
     # collapsed and -0.0 / +0.0 normalized; object keys on rb_hash + rb_eql and

data/lib/carray/rng.rb

@@ -0,0 +1,86 @@
+class CArray
+
+  # A random number generator with its own state.
+  #
+  # `Rng` rather than `Random`: a `CArray::Random` would shadow `::Random`
+  # for every bare `Random` written inside `class CArray`, and the two mean
+  # different generators -- `random!(rng: Random.new(4))` draws through
+  # Ruby's MT19937 and `random!(rng: CArray::Rng.new(seed: 4))` through the
+  # one below.  Two names that different should not look alike.
+  #
+  # The class itself is defined in ext/carray_random.c, which is where the
+  # state is advanced.  What is added here is the generator's source text,
+  # so that another gem can run the same code rather than a second
+  # implementation of it.
+  class Rng
+
+    # The generators this carray knows, and how many int64 cells each one
+    # keeps its state in.
+    STATE_CELLS = {
+      :xoshiro256pp => 4,
+    }.freeze
+
+    GENERATORS = STATE_CELLS.keys.freeze
+
+    # Where a generator's C lives.  Shipped: the gemspec takes ext/*.h,
+    # and `ext` is a require path, so this resolves in a checkout and in
+    # an installed gem alike -- lib/ and ext/ are siblings in both.
+    SOURCE_FILES = {
+      :xoshiro256pp => File.expand_path("../../ext/ca_rng_xoshiro256pp.h",
+                                        __dir__),
+    }.freeze
+
+    # The C each generator is, as text.
+    #
+    #   CArray::Rng::SOURCE[:xoshiro256pp]   #=> "/* ---- ... */\n..."
+    #
+    # This is the same text the extension compiled -- the file below is
+    # `#include`d by ext/carray_random.c -- which is the point of handing
+    # it out.  A caller that pastes it into a translation unit of its own
+    # gets a generator that continues a sequence this one started, because
+    # it is running the code this one ran and not a copy of it.
+    #
+    # carray-jit is the caller this exists for: a kernel's `random(rng:)`
+    # pastes the text beside the helpers its own compiler emits, so a
+    # kernel draws from the CArray::Rng it was handed.  The text needs
+    # nothing but <stdint.h> and defines only `static inline` functions
+    # under a `ca_` prefix.
+    #
+    # It is read once, when this file is first required.
+    SOURCE = SOURCE_FILES.transform_values { |path|
+      File.read(path, :encoding => "UTF-8")
+    }.freeze
+
+    # What every generator's text needs beside it, and what none of them
+    # owns: turning uniforms into a normal is the same arithmetic whichever
+    # generator the uniforms came from.
+    #
+    # Handed out apart from SOURCE because whoever pastes it pastes it once,
+    # however many generators are drawing.  Folded into each generator's own
+    # text instead, two generators in one translation unit would define it
+    # twice.
+    COMMON_SOURCE = File.read(
+      File.expand_path("../../ext/ca_rng_normal.h", __dir__), :encoding => "UTF-8"
+    ).freeze
+
+    # The functions in SOURCE a caller may reach, by generator and by what
+    # the draw answers: `:random` a double in [0.0, 1.0), `:randomn` a
+    # standard normal, `:bits` the raw word a draw came from.  Each takes the
+    # state and advances it -- `:randomn` by two draws, the other two by one.
+    #
+    # Named here rather than worked out by whoever pastes the text: which
+    # symbols are the entry points is a fact about the generator, and the
+    # generator is CArray's.  These are the three `#random`, `#randomn`
+    # and `#bits` call, so a caller pasting the text draws the sequence
+    # this one draws.
+    DRAW_FUNCTIONS = {
+      :xoshiro256pp => {
+        :random  => "ca_xoshiro256pp_next_real",
+        :randomn => "ca_xoshiro256pp_next_normal",
+        :bits    => "ca_xoshiro256pp_next",
+      }.freeze,
+    }.freeze
+
+  end
+
+end

data/lib/carray/slab_iterator.rb

@@ -95,18 +95,63 @@ class CASlabIterator < CAIterator
   # the map / reduce block surface, these are mask-aware: they route through the
   # core reduction, which handles masked sources.)
 
-  # @overload sum
-  #   Per-slab sum, delegating to `reference.sum(axis: slab_axes)`.
-  #   @return [CArray] one value per slab (shape = self.dim minus the slab axes)
-  # @overload accumulate
+  # Each reduction below delegates to `reference.<op>(axis: slab_axes)`, so it
+  # inherits the core data type, mask, empty / all-masked and epsilon-close
+  # contracts unchanged.  See {CAIterator} for what each one computes.
+  #
+  # @!method sum
+  #   Per-slab sum.
+  #   @return [CArray] one value per slab (shape = {#shape}).
+  # @!method accumulate
   #   Per-slab sum kept in the source's own data type, wrapping at its width,
   #   as the core `accumulate` does -- `sum` answers in the type the core
   #   promotes to (float64 for integers).
   #   @return [CArray] one value per slab
-  # The rest are analogous: prod / mean / min / max, sample and population
-  # variance / stddev, all / any, fused minmax ([min, max] pair), the axis-local
-  # position min_index / max_index (index within the slab axes), and the flat
-  # source address min_addr / max_addr (which source cell holds the extremum).
+  # @!method prod
+  #   Per-slab product.
+  #   @return [CArray] one value per slab
+  # @!method mean
+  #   Per-slab arithmetic mean.
+  #   @return [CArray] one value per slab
+  # @!method min
+  #   Per-slab minimum.
+  #   @return [CArray] one value per slab
+  # @!method max
+  #   Per-slab maximum.
+  #   @return [CArray] one value per slab
+  # @!method variance
+  #   Per-slab sample variance (divisor `n - 1`).
+  #   @return [CArray] one value per slab
+  # @!method stddev
+  #   Per-slab sample standard deviation (divisor `n - 1`).
+  #   @return [CArray] one value per slab
+  # @!method variancep
+  #   Per-slab population variance (divisor `n`).
+  #   @return [CArray] one value per slab
+  # @!method stddevp
+  #   Per-slab population standard deviation (divisor `n`).
+  #   @return [CArray] one value per slab
+  # @!method all
+  #   Whether every cell of each slab is true.
+  #   @return [CArray] `:boolean`, one value per slab
+  # @!method any
+  #   Whether any cell of each slab is true.
+  #   @return [CArray] `:boolean`, one value per slab
+  # @!method minmax
+  #   Per-slab minimum and maximum, found in one pass.
+  #   @return [Array<CArray>] the pair `[min, max]`
+  # @!method min_index
+  #   Per-slab position of the minimum, local to the slab axes.
+  #   @return [CArray] one index per slab
+  # @!method max_index
+  #   Per-slab position of the maximum, local to the slab axes.
+  #   @return [CArray] one index per slab
+  # @!method min_addr
+  #   Per-slab flat source address of the minimum -- which source cell holds it.
+  #   @return [CArray] one flat address per slab
+  # @!method max_addr
+  #   Per-slab flat source address of the maximum.
+  #   @return [CArray] one flat address per slab
   [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,
    :variancep, :stddevp, :minmax, :min_index, :max_index,
    :min_addr, :max_addr].each do |op|
@@ -260,19 +305,19 @@ class CASlabIterator < CAIterator
   # multi-axis running accumulation is ambiguous), so a multi-axis slab raises --
   # scan one axis at a time, like the order surface.
 
-  # @overload cumsum
+  # @!method cumsum
   #   Per-slab inclusive running sum (float64), reference-shaped.
   #   @return [CArray]
-  # @overload cumprod
+  # @!method cumprod
   #   Per-slab inclusive running product (float64), reference-shaped.
   #   @return [CArray]
-  # @overload cummax
+  # @!method cummax
   #   Per-slab inclusive running maximum (reference data type), reference-shaped.
   #   @return [CArray]
-  # @overload cummin
+  # @!method cummin
   #   Per-slab inclusive running minimum (reference data type), reference-shaped.
   #   @return [CArray]
-  # @overload cumcount
+  # @!method cumcount
   #   Per-slab running count of present cells (int64), reference-shaped.
   #   @return [CArray]
   [:cumsum, :cumprod, :cummax, :cummin, :cumcount].each do |op|

data/lib/carray/string_operation_extension.rb

@@ -229,7 +229,11 @@ class CArray
       else
         values = Array.new(elements) { |i| self[i] }
       end
-      CArray.const_string(values, encoding: encoding)
+      out = CArray.const_string(values, encoding: encoding)
+      # The builder takes a flat list, so give the shape back -- as
+      # to_fixlen_string above already does.  Without this an N-D column
+      # came back 1-D.
+      ndim > 1 ? out.reshape(*shape) : out
     end
 
     # In-place transforms, mixed into the mutable Faces only (CAString /

data/lib/carray/time.rb

@@ -55,6 +55,21 @@ module CATimeCivil
     doe = yoe * 365 + yoe / 4 - yoe / 100 + doy
     era * 146097 + doe - 719468
   end
+
+  # Same algebra for one date, on plain Integers.  A literal is parsed one
+  # at a time, and routing each one through the vectorized form costs a
+  # one-cell CArray and a kernel call per literal -- which is where nearly
+  # all the time in a bulk column parse used to go (170k rows: 3.5 s, of
+  # which 3.1 s was this).  Ruby's Integer `/` floors, as CArray's does,
+  # so the two forms read alike and agree everywhere.
+  def days_from_civil_1 (y, m, d)
+    y  -= 1 if m <= 2
+    era = y / 400
+    yoe = y - era * 400
+    doy = (153 * (m + (m > 2 ? -3 : 9)) + 2) / 5 + (d - 1)
+    doe = yoe * 365 + yoe / 4 - yoe / 100 + doy
+    era * 146097 + doe - 719468
+  end
 end
 
 # Unit algebra for the time surface: how two units relate (same group, which
@@ -110,6 +125,8 @@ module CATimeUnitAlgebra
     g  = rgcd(a.tick_ratio, b.tick_ratio)
     CATime::Resolution.new(Integer(g / base_ratio(fb)), fb)
   end
+  # Alias of {#common}, used where the caller reads the result as "the finer
+  # of the two grids" rather than "the grid they share".
   alias_method :finer, :common
   module_function :finer
 
@@ -1654,8 +1671,7 @@ module CATimeLiteral
       end
     when String
       h = parse_date_fields(spec, format)
-      days = CATimeCivil.days_from_civil(CA_INT64([h[:year]]), CA_INT64([h[:mon] || 1]),
-                               CA_INT64([h[:mday] || 1]))[0]
+      days = CATimeCivil.days_from_civil_1(h[:year], h[:mon] || 1, h[:mday] || 1)
       sec  = Rational(days * 86400 + (h[:hour] || 0) * 3600 +
                       (h[:min] || 0) * 60 + (h[:sec] || 0))
       sec += h[:sec_fraction] if h[:sec_fraction]