carray 3.0.2 → 3.0.4

data/lib/carray/serialize.rb

@@ -63,6 +63,7 @@ class CArray::Serializer   # :nodoc:
 
   # @!visibility private
   MAGIC         = "_CARRAY3"
+  Ractor.make_shareable(MAGIC)
   # @!visibility private
   HEADER_BYTES  = 256
   # @!visibility private
@@ -112,21 +113,35 @@ 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 through the Face's own accessor, such as `#ticks` or
+  #     `#codes`, or its values with `Marshal.dump(ca.to_type(:object))`).
+  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)
+      storage = ca.__send__(:face_storage_method)
+      raise TypeError,
+            "CArray.save cannot carry a #{ca.class} yet (its Face would be " \
+            "lost); " +
+            (storage ? "save its storage, which ##{storage} gives, or " : "") +
+            "keep its values with Marshal.dump(ca.to_type(:object))"
+    end
 
-    file_endian = opt[:endian] || CArray.endian
+    file_endian = endian || CArray.endian
     swap        = (file_endian != CArray.endian)
 
     elements     = ca.elements
@@ -170,7 +185,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 +201,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 +224,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 +248,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 +360,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 +369,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 = {
@@ -310,7 +395,7 @@ class CArray::Serializer   # :nodoc:
     if trailer.key?("attrs")
       attrs = trailer["attrs"]
       if attrs.is_a?(Hash) and not attrs.empty?
-        ca.instance_variable_set(:@attr, attrs)
+        ca.set_attrs(attrs)
       end
     end
     ca
@@ -320,6 +405,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 +443,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
@@ -521,7 +620,8 @@ class CArray
       ["object",
        target.shape,
        target.value.to_a,
-       (target.has_mask? ? target.mask.to_a : nil)]
+       (target.has_mask? ? target.mask.to_a : nil),
+       target.attrs.to_h]
     else
       ["portable", CArray.dump(target)]
     end
@@ -533,23 +633,107 @@ class CArray
   #   @param data [Array] Marshal payload.
   #   @return [void]
   def marshal_load (data)
+    source = CArray.send(:array_from_marshal_payload, data)
+    initialize_copy(source)
+    attrs = source.attrs
+    set_attrs(attrs) unless attrs.empty?
+  end
+
+  # The array a {#marshal_dump} payload describes.
+  def self.array_from_marshal_payload (data)
     tag, *rest = data
     case tag
     when "object"
-      shape, values, mask = rest
+      shape, values, mask, attrs = rest
       ca = CArray.object(*shape)
       ca[] = values
       if mask
         ca.mask = 0
         ca.mask[] = mask
       end
-      initialize_copy(ca)
+      ca.set_attrs(attrs) if attrs && !attrs.empty?
+      ca
     when "portable"
-      ca = CArray.load(StringIO.new(rest[0]))
-      initialize_copy(ca)
+      CArray.load(StringIO.new(rest[0]))
+    when "record"
+      data_class, storage, attrs = rest
+      ca = CARecord.wrap(array_from_marshal_payload(storage), data_class)
+      ca.set_attrs(attrs) if attrs && !attrs.empty?
+      ca
     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?
+        storage = face_storage_method
+        raise TypeError,
+              "Marshal cannot carry a #{self.class} yet (its Face would be lost); " \
+              "dump its values with to_type(:object)" +
+              (storage ? ", or its storage, which ##{storage} gives" : "")
+      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), attrs.to_h]
+  end
 
 end

data/lib/carray/slab_iterator.rb

@@ -152,12 +152,45 @@ class CASlabIterator < CAIterator
   # @!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,
+  #
+  # 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
+
+  # @!method first
+  #   Per-slab first present value, in row-major order over the slab axes;
+  #   UNDEF for a slab with none.
+  #   @return [CArray] one value per slab
+  # @!method last
+  #   Per-slab last present value; UNDEF for a slab with none.
+  #   @return [CArray] one value per slab
+  # @!method nunique
+  #   Per-slab number of distinct present values (int64); 0 for a slab with
+  #   none.
+  #   @return [CArray] one count per slab
+  #
+  # These take no `min_count:` or `fill_value:`, as the core ones do not.
+  [:first, :last, :nunique].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
@@ -167,25 +200,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
@@ -206,30 +242,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
@@ -279,18 +316,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 ---------------------
@@ -328,10 +365,47 @@ class CASlabIterator < CAIterator
     RUBY
   end
 
+  # @overload lag(n = 1)
+  #   Per-slab value `n` steps earlier along the slab axis (UNDEF where the
+  #   slab has none), as `reference.lag(n, axis: slab_axis)`: a view of the
+  #   reference. A multi-axis slab has no single direction to step in, so it
+  #   raises, as the scans do.
+  #   @return [CArray] reference-shaped
+  def lag (n = 1)
+    @reference.lag(n, axis: single_scan_axis(:lag))
+  end
+
+  # @overload strip_mask(method:)
+  #   Per-slab fill of the masked cells along the slab axis, as
+  #   `reference.strip_mask(method:, axis: slab_axis)`: `:forward` / `:ffill`
+  #   or `:backward` / `:bfill`. A multi-axis slab raises, as the scans do.
+  #   @return [CArray] reference-shaped
+  def strip_mask (method:)
+    CAIterator.hold_backward?(method)
+    @reference.strip_mask(method: method, axis: single_scan_axis(:strip_mask))
+  end
+
+  # @overload order(descending: false, method: :ordinal, kind: :quick)
+  #   Per-slab rank of each cell along the slab axis (int64), as
+  #   `reference.order(axis: slab_axis, ...)`. A multi-axis slab has no
+  #   single sort axis, so it raises, as sort_addr does.
+  #   @return [CArray] reference-shaped
+  def order (**kw)
+    @reference.order(axis: single_sort_axis(:order), **CAIterator.reduce_keywords(:order, kw))
+  end
+
   private
 
   # 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