carray 3.0.1 → 3.0.3

data/lib/carray/serialize.rb

@@ -112,21 +112,31 @@ class CArray::Serializer   # :nodoc:
   #   The data region is raw contiguous bytes; attribute Hash and
   #   data_class schema (if any) ride in a YAML trailer at the tail.
   #   @param ca [CArray] array to write.
-  #   @param opt [Hash] `:endian` forces the output byte order
+  #   @param endian [Symbol, Integer, nil] forces the output byte order
   #     (defaults to the host's; a differing value swaps data + header).
   #   @return [CArray] `ca`.
   #   @raise [ArgumentError] when `ca` is a CA_OBJECT array (use
   #     `Marshal.dump(ca)` instead), or carries a data_class the
   #     v1.0 flat-primitive schema cannot express.
-  def save (ca, **opt)
+  #   @raise [TypeError] when `ca` is a Face other than a record (save
+  #     its storage with `.parent`).
+  def save (ca, endian: nil)
     if ca.data_type == :object
       raise ArgumentError,
             "CArray.save cannot serialise a CA_OBJECT array " \
             "(arbitrary Ruby objects have no portable representation); " \
             "use Marshal.dump(ca) for a Ruby-only round-trip"
     end
+    # A Face other than a record is refused, as Marshal refuses it: the file
+    # would carry its storage without what makes it the Face (a unit, the
+    # string buffer, the labels), and load could not put that back.
+    if ca.face? && !ca.is_a?(CARecord)
+      raise TypeError,
+            "CArray.save cannot carry a #{ca.class} yet (its Face would be " \
+            "lost); save its storage with .parent"
+    end
 
-    file_endian = opt[:endian] || CArray.endian
+    file_endian = endian || CArray.endian
     swap        = (file_endian != CArray.endian)
 
     elements     = ca.elements
@@ -170,7 +180,7 @@ class CArray::Serializer   # :nodoc:
 
     @io.write(self.class.pack_header(header, file_endian))
 
-    data_ca = swap ? ca.swap_bytes : ca
+    data_ca = swap ? to_other_byte_order(ca) : ca
     data_ca.dump_binary(@io)
 
     if has_mask
@@ -186,18 +196,19 @@ class CArray::Serializer   # :nodoc:
   #   Reads a _CARRAY3 payload from the wrapped IO and returns the
   #   reconstructed array, re-wrapping it through its recorded
   #   data_class when the trailer carries one.
-  #   @param opt [Hash] `:data_type` overrides the element type for a
+  #   @param data_type [Symbol, Integer, nil] overrides the element type for a
   #     bare `CA_FIXLEN` payload.
   #   @return [CArray]
-  #   @raise [RuntimeError] on a bad magic string, corrupt header, or
+  #   @raise [ArgumentError] on a bad magic string, corrupt header, or
   #     unsupported version.
-  def load (**opt)
+  def load (data_type: nil)
+    fixlen_type = data_type
     buf = @io.read(HEADER_BYTES)
     unless buf && buf.bytesize == HEADER_BYTES
-      raise "not a CArray binary data (truncated header)"
+      raise ArgumentError, "not a CArray binary data (truncated header)"
     end
     if buf[0, 8] != MAGIC
-      raise "not a CArray binary data (bad magic)"
+      raise ArgumentError, "not a CArray binary data (bad magic)"
     end
 
     # The byte order is self-describing via endian_marker at offset 8:
@@ -208,22 +219,23 @@ class CArray::Serializer   # :nodoc:
     when 0x01 then file_endian = CA_BIG_ENDIAN
     when 0x04 then file_endian = CA_LITTLE_ENDIAN
     else
-      raise "corrupt CArray binary data (endian marker mismatch)"
+      raise ArgumentError, "corrupt CArray binary data (endian marker mismatch)"
     end
     h = self.class.unpack_header(buf, file_endian)
 
     if h[:endian_marker] != ENDIAN_MARKER
-      raise "corrupt CArray binary data (endian marker mismatch)"
+      raise ArgumentError, "corrupt CArray binary data (endian marker mismatch)"
     end
     if h[:version_major] != VERSION_MAJOR
-      raise "unsupported CArray binary version #{h[:version_major]}.#{h[:version_minor]}"
+      raise ArgumentError, "unsupported CArray binary version #{h[:version_major]}.#{h[:version_minor]}"
     end
     if h[:header_bytes] != HEADER_BYTES
-      raise "unsupported CArray binary header size #{h[:header_bytes]}"
+      raise ArgumentError, "unsupported CArray binary header size #{h[:header_bytes]}"
     end
     if h[:data_bytes] != h[:elements] * h[:element_bytes]
-      raise "corrupt CArray binary data (data_bytes cross-check failed)"
+      raise ArgumentError, "corrupt CArray binary data (data_bytes cross-check failed)"
     end
+    check_header(h)
 
     swap      = (file_endian != CArray.endian)
     data_type = h[:data_type_code]
@@ -231,30 +243,94 @@ class CArray::Serializer   # :nodoc:
     dim       = h[:shape][0, ndim]
     bytes     = h[:element_bytes]
 
-    if opt[:data_type] and data_type == CArray.data_type_code(CA_FIXLEN)
-      data_type = opt[:data_type]
+    if fixlen_type and data_type == CArray.data_type_code(CA_FIXLEN)
+      data_type = fixlen_type
     end
 
     ca = CArray.new(data_type, dim, :bytes => bytes)
     ca.load_binary(@io)
-    ca[] = ca.swap_bytes if swap
 
+    mask = nil
     if h[:has_mask] != 0
-      ca.mask = 0
-      ca.mask.load_binary(@io)
+      mask = CArray.boolean(*dim)
+      mask.load_binary(@io)
     end
 
     if h[:trailer_bytes] > 0
       trailer_raw = @io.read(h[:trailer_bytes])
+      unless trailer_raw && trailer_raw.bytesize == h[:trailer_bytes]
+        raise ArgumentError, "corrupt CArray binary data (truncated trailer)"
+      end
       trailer = decode_trailer(trailer_raw)
+      unless trailer.is_a?(Hash)
+        raise ArgumentError, "corrupt CArray binary data (trailer is not a mapping)"
+      end
       ca = apply_trailer(ca, trailer)
     end
 
+    # Swap once the trailer is applied and before the mask is: a record is
+    # swapped member by member, as the writer swapped it, and only its
+    # data_class says where the members are.  Swapping the bare fixlen
+    # first reversed the whole record.
+    ca[] = to_other_byte_order(ca) if swap
+
+    if mask
+      ca.mask = 0
+      ca.mask[] = mask
+    end
+
     return ca
   end
 
   private
 
+  # `ca` in the other byte order.  A member declared with `endian:` holds its
+  # bytes in that order on every machine and in every file, so it is left as
+  # it is; only the members in machine order are swapped.
+  def to_other_byte_order (ca)
+    swapped = ca.swap_bytes
+    declared = ca.respond_to?(:data_class) && ca.data_class &&
+               ca.data_class.fields.select(&:endian)
+    return swapped if !declared || declared.empty?
+    swapped = swapped.copy
+    declared.each { |f| swapped[f.name][] = ca[f.name].value }
+    swapped
+  end
+
+  # The header fields that describe the same array have to agree, and a
+  # source whose size is known has to hold what the header declares --
+  # checked before the array is allocated, so a short file cannot make
+  # the reader allocate what it declares.
+  def check_header (h)
+    ndim = h[:ndim]
+    unless ndim >= 1 && ndim <= CA_RANK_MAX
+      raise ArgumentError, "corrupt CArray binary data (ndim #{ndim} out of 1..#{CA_RANK_MAX})"
+    end
+    dim = h[:shape][0, ndim]
+    if dim.any?(&:negative?) || dim.inject(:*) != h[:elements]
+      raise ArgumentError, "corrupt CArray binary data (shape #{dim.inspect} does not " \
+            "hold #{h[:elements]} elements)"
+    end
+    fixlen = CArray.data_type_code(CA_FIXLEN)
+    if h[:data_type_code] != fixlen &&
+       h[:data_type_code] <= CArray.data_type_code(CA_OBJECT) &&
+       h[:element_bytes] != CArray.sizeof(h[:data_type_code])
+      raise ArgumentError, "corrupt CArray binary data (element_bytes #{h[:element_bytes]} " \
+            "for data type #{CArray.data_type_name(h[:data_type_code]) rescue h[:data_type_code]})"
+    end
+    mask_bytes = (h[:has_mask] != 0) ? h[:elements] : 0
+    if h[:mask_bytes] != mask_bytes
+      raise ArgumentError, "corrupt CArray binary data (mask_bytes cross-check failed)"
+    end
+    if @io.respond_to?(:size) && @io.respond_to?(:pos)
+      declared = h[:data_bytes] + mask_bytes + h[:trailer_bytes]
+      if @io.size - @io.pos < declared
+        raise ArgumentError, "corrupt CArray binary data (declares #{declared} bytes after " \
+              "the header, the source holds #{@io.size - @io.pos})"
+      end
+    end
+  end
+
   # Build the trailer mapping (String-keyed) from the array's
   # attributes and data_class.  Returns {} when there is nothing to
   # serialise.
@@ -279,7 +355,8 @@ class CArray::Serializer   # :nodoc:
         raise ArgumentError,
               "CArray.save cannot serialise data_class #{klass.inspect}: " \
               "member #{f.name.inspect} is a bitfield (the v1.0 Layer 1 " \
-              "schema is flat-primitive only); use Marshal.dump(ca)"
+              "schema is flat-primitive only); Marshal.dump(ca) carries it " \
+              "when the struct is named (assigned to a constant)"
       end
       pep = SYMBOL_TO_PEP[f.type]
       unless pep
@@ -287,9 +364,12 @@ class CArray::Serializer   # :nodoc:
               "CArray.save cannot serialise data_class #{klass.inspect}: " \
               "member #{f.name.inspect} has non-primitive type #{f.type.inspect} " \
               "(nested struct / template / fixlen are not expressible in the " \
-              "v1.0 Layer 1 schema); use Marshal.dump(ca)"
+              "v1.0 Layer 1 schema); Marshal.dump(ca) carries it " \
+              "when the struct is named (assigned to a constant)"
       end
-      { "name" => f.name, "type" => pep, "offset" => f.offset, "bytes" => f.bytes }
+      m = { "name" => f.name, "type" => pep, "offset" => f.offset, "bytes" => f.bytes }
+      m["endian"] = f.endian.to_s if f.endian
+      m
     end
 
     schema = {
@@ -320,6 +400,12 @@ class CArray::Serializer   # :nodoc:
   # synthesise an anonymous struct from the Layer 1 members[], else
   # leave the raw CA_FIXLEN array untouched.
   def wrap_data_class (ca, schema)
+    members = schema.is_a?(Hash) ? schema["members"] : nil
+    unless schema.is_a?(Hash) &&
+           (members.nil? || members.is_a?(Array) && members.all?(Hash))
+      raise ArgumentError, "corrupt CArray binary data (data_class schema is not a " \
+            "mapping with a list of member mappings)"
+    end
     name = schema["name"]
     if name
       begin
@@ -352,9 +438,17 @@ class CArray::Serializer   # :nodoc:
       members.each do |m|
         sym = PEP_TO_SYMBOL[m["type"]]
         unless sym
-          raise "unknown data_class member type #{m["type"].inspect} in CArray binary data"
+          raise ArgumentError, "unknown data_class member type #{m["type"].inspect} in CArray binary data"
         end
-        member sym, m["name"], :offset => m["offset"]
+        opt = { :offset => m["offset"] }
+        if m.key?("endian")
+          endian = %w[big little native preserve].find { |e| e == m["endian"] }
+          unless endian
+            raise ArgumentError, "unknown data_class member endian #{m["endian"].inspect} in CArray binary data"
+          end
+          opt[:endian] = endian.to_sym
+        end
+        member sym, m["name"], opt
       end
     end
   end
@@ -533,6 +627,11 @@ class CArray
   #   @param data [Array] Marshal payload.
   #   @return [void]
   def marshal_load (data)
+    initialize_copy(CArray.send(:array_from_marshal_payload, data))
+  end
+
+  # The array a {#marshal_dump} payload describes.
+  def self.array_from_marshal_payload (data)
     tag, *rest = data
     case tag
     when "object"
@@ -543,13 +642,84 @@ class CArray
         ca.mask = 0
         ca.mask[] = mask
       end
-      initialize_copy(ca)
+      ca
     when "portable"
-      ca = CArray.load(StringIO.new(rest[0]))
-      initialize_copy(ca)
+      CArray.load(StringIO.new(rest[0]))
+    when "record"
+      data_class, storage = rest
+      CARecord.wrap(array_from_marshal_payload(storage), data_class)
     else
       raise TypeError, "unrecognised CArray Marshal payload"
     end
   end
+  private_class_method :array_from_marshal_payload
+
+end
+
+# Marshal of a view and a scalar: the {CArray#marshal_dump} payload, loaded
+# back by the class method rather than into an empty instance.  A view comes
+# back as a plain array (a copy owns its memory, as #copy gives); a scalar
+# comes back a scalar.  A wrap is refused below.
+[CAView, CAWrap, CScalar].each do |klass|
+  klass.class_eval do
+    # A Face other than a record is refused: the payload would carry its
+    # storage without what makes it the Face (a unit, labels), and load
+    # could not put that back.
+    # @return [String]
+    def _dump (_level)
+      if face?
+        raise TypeError,
+              "Marshal cannot carry a #{self.class} yet (its Face would be lost); " \
+              "dump its storage with .parent"
+      end
+      Marshal.dump(CArray.instance_method(:marshal_dump).bind_call(self))
+    end
+  end
+end
+
+class CAView
+  # @return [CArray] the plain array a {#_dump} string describes.
+  def self._load (str)
+    CArray.send(:array_from_marshal_payload, Marshal.load(str))
+  end
+end
+
+class CAWrap
+  # A wrap borrows memory, which Marshal cannot carry to another process;
+  # Ruby would also try to write the objects that keep the borrowed memory
+  # alive.  Its copy owns its memory and marshals.
+  def _dump (_level)
+    raise TypeError,
+          "Marshal cannot carry a #{self.class}: it borrows its memory; " \
+          "dump .copy instead"
+  end
+
+  def self._load (str)
+    CArray.send(:array_from_marshal_payload, Marshal.load(str))
+  end
+end
+
+class CScalar
+  # @return [CScalar] the scalar a {#_dump} string describes.
+  def self._load (str)
+    a = CArray.send(:array_from_marshal_payload, Marshal.load(str))
+    s = CScalar.new(a.data_type, bytes: a.bytes)
+    s[0] = a[0]
+    s
+  end
+end
+
+class CARecord
+
+  # A record array keeps marshal_dump: it round-trips with its class.  A
+  # named struct is written by name with the record bytes, so every kind of
+  # member (nested, fixlen, bit, array) travels.  An anonymous struct has no
+  # name to write: it goes through the binary format, whose schema
+  # describes flat numeric members only.
+  def marshal_dump
+    return CArray.instance_method(:marshal_dump).bind_call(self) unless data_class.name
+    ["record", data_class,
+     CArray.instance_method(:marshal_dump).bind_call(copy.parent)]
+  end
 
 end

data/lib/carray/slab_iterator.rb

@@ -95,24 +95,81 @@ 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).
-  [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,
+  # @!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
+  #
+  # Each takes `min_count:` and `fill_value:` and passes them to the core
+  # reduction, as the other iterators do; `all` and `any` take neither, as
+  # the core ones do not.
+  [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev,
    :variancep, :stddevp, :minmax, :min_index, :max_index,
    :min_addr, :max_addr].each do |op|
     class_eval <<~RUBY, __FILE__, __LINE__ + 1
-      def #{op}
-        @reference.#{op}(axis: @slab_axes)
+      def #{op} (min_count: nil, fill_value: nil)
+        @reference.#{op}(axis: @slab_axes, **reduce_options(min_count, fill_value))
+      end
+    RUBY
+  end
+
+  [:all, :any].each do |op|
+    class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def #{op} (**kw)
+        @reference.#{op}(axis: @slab_axes, **CAIterator.reduce_keywords(:#{op}, kw))
       end
     RUBY
   end
@@ -122,25 +179,28 @@ class CASlabIterator < CAIterator
   #   No argument counts present (non-masked) cells; `count(UNDEF)` counts
   #   masked cells; `count(v)` counts cells equal to `v`.
   #   @return [CArray] one count per slab
-  def count (*args)
-    return count_not_masked if args.empty?
+  def count (*args, **kw)
+    return count_not_masked(**kw) if args.empty?
     # CABlock / CAWindow shadow #count with a geometry accessor, and @reference
     # may be such a view, so dispatch CArray#count explicitly for count(v).
-    CArray.instance_method(:count).bind_call(@reference, *args, axis: @slab_axes)
+    CArray.instance_method(:count).bind_call(@reference, *args, axis: @slab_axes,
+                                             **CAIterator.reduce_keywords(:count, kw))
   end
 
   # @overload count_not_masked
   #   Per-slab count of present (non-masked) cells.
   #   @return [CArray]
-  def count_not_masked
-    @reference.count_not_masked(axis: @slab_axes)
+  def count_not_masked (**kw)
+    @reference.count_not_masked(axis: @slab_axes,
+                                **CAIterator.reduce_keywords(:count_not_masked, kw))
   end
 
   # @overload count_masked
   #   Per-slab count of masked cells.
   #   @return [CArray]
-  def count_masked
-    @reference.count_masked(axis: @slab_axes)
+  def count_masked (**kw)
+    @reference.count_masked(axis: @slab_axes,
+                            **CAIterator.reduce_keywords(:count_masked, kw))
   end
 
   # @overload elements
@@ -161,30 +221,31 @@ class CASlabIterator < CAIterator
   #
   # Core order statistics take a single integer axis, so a single slab axis is
   # delegated directly (fast C path) and a multi-axis slab is folded per slab
-  # with reduce_slab (each slab flattened). As with `CArray#median(axis:)`, a
-  # masked source raises (the known per-axis masked limitation); strip the mask
-  # with `ca.value` first if needed.
+  # with reduce_slab (each slab flattened). Masked cells are left out, as in
+  # `CArray#median(axis:)`.
 
-  # @overload median
+  # @overload median(min_count: nil, fill_value: nil)
   #   Per-slab median.
   #   @return [CArray]
-  def median
+  def median (min_count: nil, fill_value: nil)
+    opts = reduce_options(min_count, fill_value)
     if @slab_axes.size == 1
-      @reference.median(axis: @slab_axes[0])
+      @reference.median(axis: @slab_axes[0], **opts)
     else
-      @reference.reduce_slab(axis: @slab_axes) { |s| s.median }
+      @reference.reduce_slab(axis: @slab_axes) { |s| s.median(**opts) }
     end
   end
 
-  # @overload percentile(*pers)
+  # @overload percentile(*pers, min_count: nil, fill_value: nil)
   #   Per-slab percentile(s). One argument returns one CArray; several return an
   #   array of CArrays (as `CArray#percentile`).
   #   @return [CArray, Array<CArray>]
-  def percentile (*pers)
+  def percentile (*pers, min_count: nil, fill_value: nil)
+    opts = reduce_options(min_count, fill_value)
     if @slab_axes.size == 1
-      @reference.percentile(*pers, axis: @slab_axes[0])
+      @reference.percentile(*pers, axis: @slab_axes[0], **opts)
     else
-      rs = pers.map { |p| @reference.reduce_slab(axis: @slab_axes) { |s| s.percentile(p) } }
+      rs = pers.map { |p| @reference.reduce_slab(axis: @slab_axes) { |s| s.percentile(p, **opts) } }
       pers.size == 1 ? rs[0] : rs
     end
   end
@@ -234,18 +295,18 @@ class CASlabIterator < CAIterator
   # the same shape as the reference (one weight per cell). Core wsum / wmean
   # accept multi-axis, so this covers multi-axis slabs directly.
 
-  # @overload wsum(weights)
+  # @overload wsum(weights, min_count: nil, fill_value: nil)
   #   Per-slab weighted sum, `weights` shaped like the reference.
   #   @return [CArray]
-  def wsum (weights)
-    @reference.wsum(weights, axis: @slab_axes)
+  def wsum (weights, min_count: nil, fill_value: nil)
+    @reference.wsum(weights, axis: @slab_axes, **reduce_options(min_count, fill_value))
   end
 
-  # @overload wmean(weights)
+  # @overload wmean(weights, min_count: nil, fill_value: nil)
   #   Per-slab weighted mean, `weights` shaped like the reference.
   #   @return [CArray]
-  def wmean (weights)
-    @reference.wmean(weights, axis: @slab_axes)
+  def wmean (weights, min_count: nil, fill_value: nil)
+    @reference.wmean(weights, axis: @slab_axes, **reduce_options(min_count, fill_value))
   end
 
   # ---- segment scan: within-slab running statistics ---------------------
@@ -260,19 +321,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|
@@ -287,6 +348,14 @@ class CASlabIterator < CAIterator
 
   # The single slab axis for the order surface (core sort takes one integer
   # axis). A multi-axis slab has no single sort axis, so raise.
+  # The reduction keywords that were given, for the core call.
+  def reduce_options (min_count, fill_value)
+    opts = {}
+    opts[:min_count]  = min_count  unless min_count.nil?
+    opts[:fill_value] = fill_value unless fill_value.nil?
+    opts
+  end
+
   def single_sort_axis (op)
     return @slab_axes[0] if @slab_axes.size == 1
     raise ArgumentError,

data/lib/carray/stack.rb

@@ -51,13 +51,15 @@ class CArray
   #   `data_type` and re-wraps homogeneous Face inputs via
   #   `face_lift`. Output `ndim` is one greater than each piece.
   #   @param list [Array<CArray>] pieces to stack; must not be empty.
-  #   @param axis [Integer] position of the new K axis.
+  #   @param axis [Integer, nil] position of the new K axis; `nil` is
+  #     the same as `0`.
   #   @param data_type [Symbol, Integer, nil] result `data_type`;
   #     inferred when `nil`.
   #   @return [CArray] CAStack view.
   #   @raise [ArgumentError] when `list` is empty.
   def self.stack (list, axis: 0, data_type: nil)
     raise ArgumentError, "stack: list must not be empty" if list.empty?
+    axis = 0 if axis.nil?
     list = CArray.promote_list(list, data_type: data_type)
     axis = CArray.normalize_axis(axis, list[0].ndim + 1, "stack")
     CAStack.new(list, axis: axis)                # CAStack.new does Face lift internally
@@ -80,8 +82,9 @@ class CArray
   #   Convenience form: a single Array argument is treated as the list.
   #   @param arrays [Array<CArray>] pieces to weld.  A single Array
   #     argument is accepted for compatibility with older callers.
-  #   @param axis [Integer] existing axis to extend (normalises negative
-  #     values against the reference ndim).
+  #   @param axis [Integer, nil] existing axis to extend (normalises
+  #     negative values against the reference ndim); `nil` is the same
+  #     as `0`.
   #   @return [CAMeld] view over the welded pieces.
   #   @raise [ArgumentError] when the list is empty, ndim mismatch,
   #     data_type mismatch, or non-axis dim mismatch across pieces
@@ -91,6 +94,7 @@ class CArray
       arrays = arrays[0]
     end
     raise ArgumentError, "meld: list must not be empty" if arrays.empty?
+    axis = 0 if axis.nil?
     first = arrays[0]
     unless first.is_a?(CArray)
       raise ArgumentError, "meld: entries must be CArray (got #{first.class})"
@@ -247,8 +251,10 @@ class CArray
   #   entities.
   #   @param axis [Integer] axis to split along.
   #   @return [Array<CArray>] one slice per index along `axis`.
-  #   @raise [ArgumentError] when `axis` is not a single Integer.
+  #   @raise [ArgumentError] when `axis` is not a single Integer
+  #     (including `nil`).
   def split (axis:)
+    raise ArgumentError, "split: axis: is required" if axis.nil?
     if axis.is_a?(Array)
       raise ArgumentError, "split: axis must be a single Integer"
     end

data/lib/carray/string_operation_extension.rb

@@ -153,13 +153,14 @@ class CArray
 
     # @overload extract(regexp, replace = '\0')
     #   Returns a CArray whose cells are each cell's first match of `regexp`
-    #   transformed by `String#sub(regexp, replace)`; non-matching cells
-    #   become `""`.
+    #   transformed by `String#sub(regexp, replace)`. A cell that does not
+    #   match is masked (`UNDEF`), so it stays apart from a match of the empty
+    #   string, and a later `cast` to a number does not read it as 0.
     #   @param regexp [Regexp]
     #   @param replace [String]
     #   @return [CAString]
     def extract (regexp, replace = '\0')
-      string_map { |s| regexp.match(s) { |m| m[0].sub(regexp, replace) } || "" }
+      string_map { |s| regexp.match(s) { |m| m[0].sub(regexp, replace) } || UNDEF }
     end
 
     # --- inter-Face conversions (String Faces only) ----------------------
@@ -229,7 +230,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 /