carray 3.0.3 → 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
@@ -119,7 +120,8 @@ class CArray::Serializer   # :nodoc:
   #     `Marshal.dump(ca)` instead), or carries a data_class the
   #     v1.0 flat-primitive schema cannot express.
   #   @raise [TypeError] when `ca` is a Face other than a record (save
-  #     its storage with `.parent`).
+  #     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,
@@ -131,9 +133,12 @@ class CArray::Serializer   # :nodoc:
     # 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); save its storage with .parent"
+            "lost); " +
+            (storage ? "save its storage, which ##{storage} gives, or " : "") +
+            "keep its values with Marshal.dump(ca.to_type(:object))"
     end
 
     file_endian = endian || CArray.endian
@@ -390,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
@@ -615,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
@@ -627,7 +633,10 @@ class CArray
   #   @param data [Array] Marshal payload.
   #   @return [void]
   def marshal_load (data)
-    initialize_copy(CArray.send(:array_from_marshal_payload, 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.
@@ -635,19 +644,22 @@ class CArray
     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
+      ca.set_attrs(attrs) if attrs && !attrs.empty?
       ca
     when "portable"
       CArray.load(StringIO.new(rest[0]))
     when "record"
-      data_class, storage = rest
-      CARecord.wrap(array_from_marshal_payload(storage), data_class)
+      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
@@ -668,9 +680,11 @@ end
     # @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 storage with .parent"
+              "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
@@ -719,7 +733,7 @@ class CARecord
   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)]
+     CArray.instance_method(:marshal_dump).bind_call(copy.parent), attrs.to_h]
   end
 
 end

data/lib/carray/slab_iterator.rb

@@ -174,6 +174,27 @@ class CASlabIterator < CAIterator
     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
+
   # @overload count(v = <none>)
   #   Per-slab count, delegating to `reference.count(..., axis: slab_axes)`.
   #   No argument counts present (non-masked) cells; `count(UNDEF)` counts
@@ -344,6 +365,35 @@ 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

data/lib/carray/string.rb

@@ -17,20 +17,28 @@ class CArray
   #     CArray.string([a, nil, b])              # nil → masked element
   #     CArray.string(other_ca)                 # from a String Face / object / raw fixlen
   #
-  # `nil` entries become masked cells; "" (empty) is a valid distinct value.
-  # A CArray source is normalised through a String Face ({CArray.string_face_of}):
-  # a String Face converts, CA_OBJECT storage wraps, a raw CA_FIXLEN reads as
-  # NUL-stripped strings; a numeric / boolean array is rejected (stringify with
-  # {#format} / {CArray.format}).
+  # A cell of a CAString is a String.  In the Array and block forms `nil`
+  # becomes a masked cell; "" (empty) is a valid distinct value.  Any other
+  # value (a Symbol, a number, a nested Array) is refused: the values are one
+  # cell each, so a CAString of more than one dimension is built from an
+  # object array (`CArray.string(CA_OBJECT(nested))`).
+  # A CArray source is normalised through a String Face: a String Face
+  # converts, CA_OBJECT storage wraps zero-copy (every cell that is not
+  # masked must be a String, `nil` included: mask it instead), a raw
+  # CA_FIXLEN reads as NUL-stripped strings; a numeric / boolean array is
+  # rejected (stringify with {#format} / {CArray.format}).
   # @overload string(values)
   #   Returns a {CAString} wrapping a CA_OBJECT entity of the given values.
   #   @param values [Array<String, nil>] source values.
   #   @return [CAString]
+  #   @raise [TypeError] if a value is neither a String nor `nil`.
   # @overload string(ca)
   #   Returns a {CAString} of the string-bearing CArray `ca`.
   #   @param ca [CArray] a String Face, CA_OBJECT, or raw CA_FIXLEN array.
   #   @return [CAString]
   #   @raise [CArray::DataTypeError] if `ca` is numeric / boolean.
+  #   @raise [TypeError] if a cell of an object array that is not masked is
+  #     not a String.
   # @overload string(n) { |i| ... }
   #   Returns an `n`-element {CAString} filled by the block, following the
   #   arity-0 broadcast convention.
@@ -55,6 +63,12 @@ class CArray
 
     entity = CArray.object(values.size)
     values.each_with_index do |s, i|
+      if s.is_a?(Array)
+        raise TypeError,
+              "CArray.string: value #{i} is an Array; a CAString cell is a " \
+              "String (for a CAString of another shape, give " \
+              "CArray.string an object array: CArray.string(CA_OBJECT(values)))"
+      end
       entity[i] = s.nil? ? UNDEF : s
     end
     CAString.wrap(entity)
@@ -66,4 +80,90 @@ end
 class CAString
   include CArray::StringOperationMixin
   include CArray::StringOperationMixin::Mutable
+
+  # The String operators and the picks by order run on the object storage,
+  # cell by cell, as on any object array.  A String's +, * and % give a
+  # String (or raise), and a pick gives one of the operands, so the result
+  # is text and comes back as a CAString, as the bang forms (add!, mul!)
+  # keep it.  A lazy operand is computed here.
+
+  # Per-cell `String#+`.
+  # @return [CAString] shape and mask carried.
+  def + (other) ; as_text(super) ; end
+  # Per-cell `String#+` (the word form of {#+}).
+  # @return [CAString]
+  def add (other) ; as_text(super) ; end
+  # Per-cell `String#*`.
+  # @return [CAString] shape and mask carried.
+  def * (other) ; as_text(super) ; end
+  # Per-cell `String#*` (the word form of {#*}).
+  # @return [CAString]
+  def mul (other) ; as_text(super) ; end
+  # Per-cell `String#%` (format).
+  # @return [CAString] shape and mask carried.
+  def % (other) ; as_text(super) ; end
+  # Per-cell `String#%` (the word form of {#%}).
+  # @return [CAString]
+  def mod (other) ; as_text(super) ; end
+  # The later String of each cell and `other`, cell by cell.
+  # @return [CAString]
+  def pmax (other) ; as_text(super) ; end
+  # The earlier String of each cell and `other`, cell by cell.
+  # @return [CAString]
+  def pmin (other) ; as_text(super) ; end
+  # Another name of {#pmax} (a String has no NaN to let win).
+  # @return [CAString]
+  def maximum (other) ; as_text(super) ; end
+  # Another name of {#pmin}.
+  # @return [CAString]
+  def minimum (other) ; as_text(super) ; end
+  # Another name of {#pmax}.
+  # @return [CAString]
+  def fmax (other) ; as_text(super) ; end
+  # Another name of {#pmin}.
+  # @return [CAString]
+  def fmin (other) ; as_text(super) ; end
+
+  # The String a blank cell holds: the cell a fresh {#template} gives and
+  # the one {#shift} fills by default.  Frozen, because every blank cell
+  # shares it.
+  BLANK = "".freeze
+
+  # A same-shape CAString.  With no block every cell is {BLANK}; a block
+  # fills the cells as for any array, and its values must be Strings or
+  # UNDEF.  Given a data type, the result is a plain array of that type.
+  # @overload template(type = nil, **opts)
+  #   @return [CAString, CArray]
+  def template (*args, **opts, &block)
+    return super if block || ! args.empty? || ! opts.empty?
+    out = super
+    out[] = BLANK
+    out
+  end
+
+  # Shifts the cells as {CArray#shift} does.  The cells shifted in hold
+  # {BLANK} unless `fill_value:` names a String or UNDEF.
+  # @return [CAString] a view over the shifted cells.
+  def shift (*shifts, fill_value: BLANK, **opts)
+    super(*shifts, fill_value: fill_value, **opts)
+  end
+
+  # A window as {CArray#window} gives.  The cells outside the array hold
+  # {BLANK} unless `fill_value:` names a String or UNDEF.
+  # @return [CAString] a view over the window.
+  def window (*ranges, fill_value: BLANK, **opts)
+    super(*ranges, fill_value: fill_value, **opts)
+  end
+
+  # A resized copy as {CArray#resize} gives.  The new cells hold {BLANK}
+  # unless `fill_value:` names a String or UNDEF.
+  # @return [CAString]
+  def resize (*newdim, fill_value: BLANK)
+    super(*newdim, fill_value: fill_value)
+  end
+
+  private def as_text (result)
+    result = result.copy if result.lazy_view?
+    CAString.wrap(result)
+  end
 end

data/lib/carray/string_operation_extension.rb

@@ -278,8 +278,15 @@ class CArray
   # boolean array has no string reading and is rejected -- stringify explicitly
   # with #format / CArray.format.  (This mirrors the numeric gate that rejects
   # numeric reductions on a String Face.)
-  def self.string_face_of (ca)
+  def self.string_face_of (ca, verb = "CArray.string")
     return ca if ca.is_a?(CArray::StringOperationMixin)
+    # Another Face's storage is not its text: a CATime's fixlen surface
+    # holds ticks, a categorical's codes.
+    if ca.face?
+      raise TypeError,
+            "#{verb}: a #{ca.class} is not text " \
+            "(convert its values to Strings first)"
+    end
     case ca.data_type
     when :object then CAString.wrap(ca)
     when :fixlen then CAFixlenString.wrap(ca)

data/lib/carray/struct.rb

@@ -340,14 +340,6 @@ class CAStruct
     super
   end
 
-  protected
-
-  def __data__
-    @data
-  end
-
-  public
-
   # Member access.  A member is named by a String (`s["lat"]`) or its
   # Integer position (`s[0]`); its accessor (`s.lat`) reads it too.  A
   # Symbol is not a member name here, and a name that is not a member
@@ -509,26 +501,22 @@ class CAStruct
   # @!method <=(other)
   # @!method >(other)
   # @!method >=(other)
-  { :< => ->(c) { c < 0 }, :<= => ->(c) { c <= 0 },
-    :> => ->(c) { c > 0 }, :>= => ->(c) { c >= 0 } }.each do |op, test|
-    define_method(op) do |other|
+  [:<, :<=, :>, :>=].each do |op|
+    define_method(op, &Ractor.make_shareable(proc do |other|
       c = (self <=> other)
       if c.nil?
         raise ArgumentError,
               "comparison of #{self.class.inspect} with #{other.class.inspect} failed" +
               (self.class.order_by ? "" : " (the struct declares no order_by:)")
       end
-      test.call(c)
-    end
+      c.public_send(op, 0)
+    end))
   end
 
-  # One member of {#<=>}: NaN after every number, as a numeric array sorts.
+  # One member of {#<=>}: the order a sort puts the member's values in
+  # (NaN after every number).
   def self.compare_key (a, b)
-    a_nan = a.is_a?(Float) && a.nan?
-    b_nan = b.is_a?(Float) && b.nan?
-    return (a_nan ? 0 : -1) if b_nan
-    return 1 if a_nan
-    a <=> b
+    CArray.send(:object_order_cmp, a, b)
   end
 
   # Byte-level identity.  Two CAStruct instances are eql? iff they are
@@ -728,8 +716,8 @@ end
 # in Builder sets them up before any instance is created).  Subclasses
 # created by Builder later don't need re-installation -- they inherit the
 # C methods from CAStruct.
-if CArray.respond_to?(:__install_castruct_methods__)
-  CArray.__install_castruct_methods__(CAStruct)
+if CArray.respond_to?(:install_struct_methods, true)
+  CArray.send(:install_struct_methods, CAStruct)
 end
 
 require 'carray/record_order'

data/lib/carray/struct_builder.rb

@@ -288,6 +288,15 @@ class CAStruct::Builder  # :nodoc:
   end
 
   # @!visibility private
+  # Shared with every Ractor when it can be.  A member whose type is an
+  # array template holds a CArray, which cannot be shared, and its struct
+  # is then used in the main Ractor only.
+  def self.shareable (object)
+    Ractor.make_shareable(object)
+  rescue Ractor::Error
+    object.freeze
+  end
+
   ALIGN_TABLE = {
     CA_FIXLEN   => CA_ALIGN_FIXLEN,
     CA_BOOLEAN  => CA_ALIGN_INT8,
@@ -304,6 +313,7 @@ class CAStruct::Builder  # :nodoc:
     CA_CMPLX64  => CA_ALIGN_FLOAT32,
     CA_CMPLX128 => CA_ALIGN_FLOAT64,
   }
+  Ractor.make_shareable(ALIGN_TABLE)
 
   # Raises ArgumentError when `opt` names a key outside `allowed`.  The
   # options are read one key at a time, so a misspelt key would otherwise
@@ -463,9 +473,9 @@ class CAStruct::Builder  # :nodoc:
     end
     table.freeze
     names.freeze
-    klass.const_set(:MEMBER_TABLE, table)   ### required element as data class
-    klass.const_set(:MEMBERS, names)
-    klass.const_set(:ORDER_BY, order_keys(table)) if @order_by
+    klass.const_set(:MEMBER_TABLE, self.class.shareable(table))   ### required element as data class
+    klass.const_set(:MEMBERS, self.class.shareable(names))
+    klass.const_set(:ORDER_BY, self.class.shareable(order_keys(table))) if @order_by
     # ---
     # Step 3 dispatch table: precompute a per-member [reader, writer]
     # Proc pair so `record[name]` is one Hash lookup + one Proc call,
@@ -473,7 +483,7 @@ class CAStruct::Builder  # :nodoc:
     # checks and view-shape decisions happen here, once, at class
     # definition time.
     klass.const_set(:DISPATCH_TABLE,
-                    self.class.build_dispatch_table(table, @offset).freeze)
+                    self.class.shareable(self.class.build_dispatch_table(table, @offset)))
     # Also precompute FAST_PRIMITIVES, the subset of members that the
     # C-side `[]` / `[]=` can handle without
     # allocating a CAField view.  Entries are `[offset, type_code]`;
@@ -491,15 +501,16 @@ class CAStruct::Builder  # :nodoc:
     klass.module_eval {
       taken = ->(m) { method_defined?(m) || private_method_defined?(m) }
       names.each do |name|
+        Ractor.make_shareable(name)   # the accessors below capture it
         unless taken.(name)
-          define_method(name) {
+          define_method(name, &Ractor.make_shareable(proc {
             return self[name]
-          }
+          }))
         end
         unless taken.("#{name}=")
-          define_method("#{name}=") { |val|
+          define_method("#{name}=", &Ractor.make_shareable(proc { |val|
             return self[name] = val
-          }
+          }))
         end
       end
     }