carray 3.0.2 → 3.0.4

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

@@ -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) ----------------------
@@ -277,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

@@ -217,6 +217,14 @@ class CAStruct
       return self::MEMBERS
     end
 
+    # @overload order_by
+    #   Returns the members the records are ordered by (`order_by:` of
+    #   {CArray.struct}), or nil when the struct declares no order.
+    #   @return [Array<String>, nil]
+    def order_by
+      const_defined?(:ORDER_BY) ? self::ORDER_BY : nil
+    end
+
     # @overload fields
     #   Returns the struct's members as {CAStruct::Field} objects
     #   in declaration order. Cached on the class.
@@ -318,64 +326,83 @@ class CAStruct
     end
   end
 
-  protected
-
-  def __data__
-    @data
+  # A copy owns its bytes (dup and clone of the struct object would
+  # otherwise share the one-record array behind it).
+  def initialize_copy (other)
+    super
+    @data = @data.copy
   end
 
-  public
+  # Freezing an element also stops writes to its bytes.
+  # @return [self]
+  def freeze
+    @data.freeze
+    super
+  end
 
-  # Member access (`record[:name]` / `record["name"]` / `record[i]`).
-  # Step 3 (3.0): the per-type `case` was replaced by a class-level
-  # DISPATCH_TABLE built once at struct-definition time.  Each known
-  # member has a frozen `[reader_proc, writer_proc]` pair that closes
-  # over its offset / type / opts, so the per-call work is one Hash
-  # lookup + one Proc#call.  Unknown names fall back to `send(name)`
-  # so subclasses can define computed members via plain Ruby methods.
+  # 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
+  # raises.  These Ruby bodies state the rule; the methods that run are
+  # the C ones installed at the bottom of this file.
   # @overload [](name)
-  #   Returns the value of member `name` (Integer indexes the
-  #   member list). Unknown names fall through to `send(name)`.
-  #   @param name [Symbol, String, Integer]
+  #   Returns the value of member `name`.
+  #   @param name [String, Integer]
   #   @return [Object]
+  #   @raise [TypeError] for a Symbol or another type of name.
+  #   @raise [ArgumentError] when `name` is not a member.
   def [] (name)
-    if name.kind_of?(Integer)
-      name = members[name]
-    end
-    pair = self.class::DISPATCH_TABLE[name.to_s]
-    if pair
-      pair[0].call(@data)
-    else
-      send(name)
-    end
+    pair = self.class::DISPATCH_TABLE[member_name(name)]
+    pair[0].call(@data)
   end
 
   # @overload []=(name, val)
-  #   Sets member `name` to `val`. Unknown names fall through to
-  #   `send("#{name}=", val)`.
-  #   @param name [Symbol, String, Integer]
+  #   Sets member `name` to `val`.
+  #   @param name [String, Integer]
   #   @param val [Object]
   #   @return [Object] `val`.
+  #   @raise [TypeError] for a Symbol or another type of name.
+  #   @raise [ArgumentError] when `name` is not a member.
   def []= (name, val)
-    if name.kind_of?(Integer)
-      name = members[name]
-    end
-    pair = self.class::DISPATCH_TABLE[name.to_s]
-    if pair
-      pair[1].call(@data, val)
+    pair = self.class::DISPATCH_TABLE[member_name(name)]
+    pair[1].call(@data, val)
+  end
+
+  private def member_name (name)
+    case name
+    when Symbol
+      if self.class::MEMBER_TABLE.key?(name.to_s)
+        raise TypeError, "a struct member is named by a String (s[\"#{name}\"]) " \
+                         "or read by its accessor (s.#{name}), not by a Symbol"
+      end
+      raise TypeError, "a struct member is named by a String, not by a Symbol " \
+                       "(#{self.class.inspect} has no member #{name.to_s.inspect} either)"
+    when Integer
+      key = members[name]
+    when String
+      key = name
     else
-      send(name.to_s + "=", val)
+      raise TypeError, "a struct member is named by a String or an Integer " \
+                       "position (got #{name.class})"
     end
+    unless key && self.class::MEMBER_TABLE.key?(key)
+      raise ArgumentError, "#{self.class.inspect} has no member #{name.inspect} " \
+                           "(members: #{members.inspect})"
+    end
+    key
   end
 
   # @overload each { |value| ... }
-  #   Yields each member value in declaration order.
+  #   Yields each member value in declaration order (an Enumerator
+  #   without a block).
   #   @yieldparam value [Object]
   #   @return [self]
   def each
+    return to_enum(:each) { length } unless block_given?
     members.each do |name|
       yield(self[name])
     end
+    self
   end
 
   # @overload each_pair { |name, value| ... }
@@ -385,9 +412,19 @@ class CAStruct
   #   @yieldparam value [Object]
   #   @return [self]
   def each_pair
+    return to_enum(:each_pair) { length } unless block_given?
     members.each do |name|
       yield(name.intern, self[name])
     end
+    self
+  end
+
+  # @overload to_h
+  #   Returns the members as a Hash of member name (Symbol) to value, in
+  #   declaration order.
+  #   @return [Hash{Symbol => Object}]
+  def to_h
+    each_pair.to_h
   end
 
   # @overload length
@@ -432,16 +469,54 @@ class CAStruct
     return ["<", self.class.inspect, " ", table.inspect[1..-2], ">"].join
   end
 
-  # Value comparison against another record of the same class.  Unlike
-  # `eql?`, which compares the raw bytes, this compares the decoded members.
+  alias to_s inspect
+
+  # Equality with another record of the same class, by the record's bytes
+  # (the same as {#eql?}): a struct is its bytes, so a NaN member equals
+  # itself, 0.0 and -0.0 differ, and so do records whose padding bytes
+  # differ.  A record array's `eq` compares records the same way.
   # @return [Boolean]
   def == (other)
-    case other
-    when self.class
-      return @data == other.__data__
-    else
-      return false
+    other.is_a?(self.class) && encode == other.encode
+  end
+
+  # Order against a record of the same class, by the members the struct
+  # was declared with in `order_by:`, compared in that order.  NaN sorts
+  # after every number.  nil when the other is not a record of this class,
+  # or when the struct declares no order.
+  # @return [Integer, nil]
+  def <=> (other)
+    keys = self.class.order_by
+    return nil unless keys && other.class.equal?(self.class)
+    keys.each do |key|
+      c = CAStruct.compare_key(self[key], other[key])
+      return c unless c == 0
     end
+    0
+  end
+
+  # @!method <(other)
+  #   @raise [ArgumentError] when the struct declares no `order_by:`, or
+  #     `other` is not a record of the same class.
+  # @!method <=(other)
+  # @!method >(other)
+  # @!method >=(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
+      c.public_send(op, 0)
+    end))
+  end
+
+  # One member of {#<=>}: the order a sort puts the member's values in
+  # (NaN after every number).
+  def self.compare_key (a, b)
+    CArray.send(:object_order_cmp, a, b)
   end
 
   # Byte-level identity.  Two CAStruct instances are eql? iff they are
@@ -465,6 +540,7 @@ class CAStruct
   #   @return [self]
   #   @raise [CAStruct::DecodeError] on an unsupported input.
   def decode (data)
+    raise FrozenError.new("can't modify frozen #{self.class}", receiver: self) if frozen?
     case data
     when String
       @data.load_binary(data)
@@ -486,25 +562,18 @@ class CAStruct
   end
 
   # @overload swap_bytes!
-  #   Byte-swaps `self` in place (endian flip).
+  #   Byte-swaps each member of `self` in place (endian flip).
   #   @return [self]
   def swap_bytes!
-    @data[] = @data.swap_bytes
-    return self
+    decode(swap_bytes.encode)
   end
 
   # @overload swap_bytes
-  #   Returns a fresh byte-swapped copy of `self`.
+  #   Returns a fresh copy of `self` with each member byte-swapped, as
+  #   a record array's swap_bytes swaps its records.
   #   @return [CAStruct]
   def swap_bytes
-    return self.class.decode(@data.swap_bytes.dump_binary)
-  end
-
-  # @overload to_ptr
-  #   Returns a `Fiddle::Pointer` to the backing storage.
-  #   @return [Fiddle::Pointer]
-  def to_ptr
-    return @data.to_ptr
+    return CARecord.wrap(@data, self.class).swap_bytes[0]
   end
 
 end
@@ -527,9 +596,19 @@ class CArray
   #   Returns a new {CAStruct} subclass defined by the block via
   #   {CAStruct::Builder}. Options control alignment, packing, and
   #   endianness.
-  #   @param opt [Hash]
+  #
+  #   `order_by:` names the members records are ordered by, compared in
+  #   that order (`order_by: [:lat, :id]` sorts by `lat`, then `id` among
+  #   equal `lat`).  It gives the records `<=>` and the comparison
+  #   operators, and gives a {CARecord} of them `sort`, `min`, `max`,
+  #   `partition_copy` and their index forms.  A struct without it has no
+  #   order, and those raise.  NaN sorts after every number, as in a
+  #   numeric array.
+  #   @param opt [Hash] `pack:`, `size:`, `order_by:`.
   #   @yield DSL calls in {CAStruct::Builder}.
   #   @return [Class] anonymous {CAStruct} subclass.
+  #   @raise [CAStruct::DefinitionError] when `order_by:` names something
+  #     that is not a member, or a nested record.
   def self.struct (opt={}, &block)
     return CAStruct::Builder.new(:struct, opt).define(&block)
   end
@@ -637,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'