carray 3.0.1 → 3.0.3

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,6 +326,20 @@ class CAStruct
     end
   end
 
+  # 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
+
+  # Freezing an element also stops writes to its bytes.
+  # @return [self]
+  def freeze
+    @data.freeze
+    super
+  end
+
   protected
 
   def __data__
@@ -326,56 +348,69 @@ class CAStruct
 
   public
 
-  # 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 +420,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,18 +477,60 @@ 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)
+  { :< => ->(c) { c < 0 }, :<= => ->(c) { c <= 0 },
+    :> => ->(c) { c > 0 }, :>= => ->(c) { c >= 0 } }.each do |op, test|
+    define_method(op) 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
   end
 
+  # One member of {#<=>}: NaN after every number, as a numeric array sorts.
+  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
+  end
+
   # Byte-level identity.  Two CAStruct instances are eql? iff they are
   # of exactly the same class and their binary representations match.
   # Lets struct records work as Hash keys / Set members.
@@ -465,6 +552,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 +574,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 +608,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
@@ -641,4 +732,4 @@ if CArray.respond_to?(:__install_castruct_methods__)
   CArray.__install_castruct_methods__(CAStruct)
 end
 
-
+require 'carray/record_order'

data/lib/carray/struct_builder.rb

@@ -234,8 +234,17 @@ class CAStruct::Builder  # :nodoc:
   end
 
   # @!visibility private
+  # A nested member reads as an element of the nested struct over the
+  # parent's own bytes (a field view), so writing to it writes to the
+  # parent, as writing to an array member does.  A frozen parent gives a
+  # frozen nested element.
   def self.build_nested_struct_dispatcher (offset, nested_class)
-    reader = ->(data) { nested_class.decode(data.field(offset, nested_class)) }
+    reader = ->(data) {
+      element = nested_class.allocate
+      element.instance_variable_set(:@data, data.field(offset, nested_class).parent)
+      element.freeze if data.frozen?
+      element
+    }
     writer = ->(data, val) { data.field(offset, nested_class)[0] = val }
     [reader, writer].freeze
   end
@@ -296,7 +305,22 @@ class CAStruct::Builder  # :nodoc:
     CA_CMPLX128 => CA_ALIGN_FLOAT64,
   }
 
+  # Raises ArgumentError when `opt` names a key outside `allowed`.  The
+  # options are read one key at a time, so a misspelt key would otherwise
+  # be ignored and the layout would change without a word.
+  def self.check_keys! (opt, allowed, where)
+    unknown = opt.keys - allowed
+    return if unknown.empty?
+    raise ArgumentError, "#{where}: unknown keyword#{unknown.size > 1 ? "s" : ""}: " +
+                         unknown.map(&:inspect).join(", ")
+  end
+
+  BUILDER_KEYS = [:pack, :size, :order_by].freeze
+  MEMBER_KEYS  = [:offset, :bytes, :endian].freeze
+  NESTED_KEYS  = (BUILDER_KEYS + [:type, :offset]).freeze
+
   def initialize (type, opt = {})
+    CAStruct::Builder.check_keys!(opt, BUILDER_KEYS, type.to_s)
     if not opt[:pack].nil? and not opt[:pack].is_a?(Integer)
       raise CAStruct::DefinitionError,
             "invalid :pack value #{opt[:pack].inspect} (expected nil or Integer)"
@@ -305,10 +329,42 @@ class CAStruct::Builder  # :nodoc:
     @align      = opt[:pack] ### nil for alignment, int for pack(n)
     @members    = []         ### array of CArray::Struct::Builder::Member
     @offset     = 0          ### offset of each member and size of struct
+    @extent     = 0          ### furthest byte any member reaches
     @align_max  = 1          ### maximum of alignment among members
     @size       = opt[:size] ### user defined struct size
     @bit_offset = 0          ### 0..7, sub-byte position for bitfield accumulator
+    @order_by   = opt[:order_by] ### member names the records are ordered by
+  end
+
+  # The `order_by:` members, as member names.  Each has to be a member of
+  # this struct that holds one ordered value: not a nested record, an array
+  # member or a complex number.
+  def order_keys (table)
+    keys = Array(@order_by).map(&:to_s)
+    if keys.empty?
+      raise CAStruct::DefinitionError, "order_by: names no member"
+    end
+    keys.each do |key|
+      unless table.key?(key)
+        raise CAStruct::DefinitionError, "order_by: #{key.inspect} is not a member"
+      end
+      type = table[key][1]
+      if type.is_a?(Class) && type <= CAStruct
+        raise CAStruct::DefinitionError,
+              "order_by: #{key.inspect} is a nested record; order by its members instead"
+      end
+      if type.is_a?(CArray)
+        raise CAStruct::DefinitionError,
+              "order_by: #{key.inspect} is an array member, which has no order"
+      end
+      if [:cmplx64, :cmplx128].include?(type)
+        raise CAStruct::DefinitionError,
+              "order_by: #{key.inspect} is complex, which has no order"
+      end
+    end
+    keys.freeze
   end
+  private :order_keys
 
   # Round up the byte cursor if the bitfield accumulator is mid-byte.
   # Called before placing a non-bit member so the byte member starts
@@ -364,6 +420,9 @@ class CAStruct::Builder  # :nodoc:
       klass = Class.new(CAUnion)
     end
     # ---
+    # A member placed by an explicit offset can end before an earlier one
+    # does, so the body runs to the furthest member, not the last one.
+    @offset = @extent if @extent > @offset
     if @align.nil?
       @offset = alignment(@offset, :align_max)
     end
@@ -406,6 +465,7 @@ class CAStruct::Builder  # :nodoc:
     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
     # ---
     # Step 3 dispatch table: precompute a per-member [reader, writer]
     # Proc pair so `record[name]` is one Hash lookup + one Proc call,
@@ -424,14 +484,23 @@ class CAStruct::Builder  # :nodoc:
     klass.const_set(:FAST_PRIMITIVES,
                     self.class.build_fast_primitives(table, @offset).freeze)
     # ---
+    # An accessor for each member, unless the name is already a method of
+    # the element (hash, size, class, initialize, ...): the accessor would
+    # replace it.  Such a member is read as s["name"] only, as a record
+    # array's members always are.
     klass.module_eval {
+      taken = ->(m) { method_defined?(m) || private_method_defined?(m) }
       names.each do |name|
-        define_method(name) {
-          return self[name]
-        }
-        define_method("#{name}=") { |val|
-          return self[name] = val
-        }
+        unless taken.(name)
+          define_method(name) {
+            return self[name]
+          }
+        end
+        unless taken.("#{name}=")
+          define_method("#{name}=") { |val|
+            return self[name] = val
+          }
+        end
       end
     }
     # ---
@@ -471,6 +540,9 @@ class CAStruct::Builder  # :nodoc:
   end
 
   def pack (addr, align, opt={})
+    if addr < 0
+      raise CAStruct::DefinitionError, format("negative member offset: %d", addr)
+    end
     if ( addr % align ) != 0
       raise CAStruct::DefinitionError,
             format("invalid offset for packing: %d not aligned to %d", addr, align)
@@ -491,6 +563,7 @@ class CAStruct::Builder  # :nodoc:
   #   @param opt [Hash] member options (`:offset`, `:bytes`, `:endian`, ...).
   #   @return [Member]
   def member (data_type, id = nil, opt = {})
+    CAStruct::Builder.check_keys!(opt, MEMBER_KEYS, "member")
     opt = opt.clone
     # If a bit member sequence was in flight, round up to a clean byte
     # boundary before placing this byte-typed member.
@@ -504,6 +577,10 @@ class CAStruct::Builder  # :nodoc:
     when :struct                           ### struct
       case @align
       when nil                             ### -- aligned
+        if opt[:offset]
+          raise CAStruct::DefinitionError,
+                "offset: places a member only in a packed struct (pass pack:)"
+        end
         @offset = alignment(@offset, data_type, opt)
         opt[:offset] = @offset
       else                                 ### -- packed
@@ -516,7 +593,12 @@ class CAStruct::Builder  # :nodoc:
       mem = Member.new(id, data_type, opt)
       @members.push(mem)
       @offset += mem.byte_length
+      @extent = @offset if @offset > @extent
     when :union                            ### union
+      if opt[:offset] && opt[:offset] != 0
+        raise CAStruct::DefinitionError,
+              "a union member is always at offset 0 (got offset: #{opt[:offset]})"
+      end
       alignment(0, data_type, opt)
       opt[:offset] = 0
       mem = Member.new(id, data_type, opt)
@@ -537,17 +619,19 @@ class CAStruct::Builder  # :nodoc:
   #     `type:` is provided.
   def struct (*args, &block)
     opt = args.last.is_a?(Hash) ? args.pop : {}
+    CAStruct::Builder.check_keys!(opt, NESTED_KEYS, "struct")
     if block
-      opt = {:pack => @align}.update(opt)
-      st = self.class.new(:struct, opt).define(&block)
+      inner = {:pack => @align}.update(opt.slice(*BUILDER_KEYS))
+      st = self.class.new(:struct, inner).define(&block)
     elsif opt[:type] and opt[:type] <= CAStruct
       st = opt[:type]
     else
       raise CAStruct::DefinitionError,
             "no type given for nested struct member (pass a block or :type)"
     end
+    place = opt.key?(:offset) ? {:offset => opt[:offset]} : {}
     args.each do |arg|
-      member(st, arg)
+      member(st, arg, place)
     end
     return st
   end
@@ -562,17 +646,19 @@ class CAStruct::Builder  # :nodoc:
   #     `type:` is provided.
   def union (*args, &block)
     opt = args.last.is_a?(Hash) ? args.pop : {}
+    CAStruct::Builder.check_keys!(opt, NESTED_KEYS, "union")
     if block
-      opt = {:pack => @align}.update(opt)
-      st = self.class.new(:union, opt).define(&block)
+      inner = {:pack => @align}.update(opt.slice(*BUILDER_KEYS))
+      st = self.class.new(:union, inner).define(&block)
     elsif opt[:type] and opt[:type] <= CAStruct
       st = opt[:type]
     else
       raise CAStruct::DefinitionError,
             "no type given for nested union member (pass a block or :type)"
     end
+    place = opt.key?(:offset) ? {:offset => opt[:offset]} : {}
     args.each do |arg|
-      member(st, arg)
+      member(st, arg, place)
     end
     return st
   end
@@ -585,12 +671,14 @@ class CAStruct::Builder  # :nodoc:
   #     CArray template.
   def array (*args)
     opt = args.last.is_a?(Hash) ? args.pop : {}
+    CAStruct::Builder.check_keys!(opt, [:type, :offset], "array")
     if not opt[:type] or not opt[:type].kind_of?(CArray)
       raise CAStruct::DefinitionError,
             "no :type given for array member (expected a CArray template)"
     end
+    place = opt.key?(:offset) ? {:offset => opt[:offset]} : {}
     args.each do |arg|
-      member(opt[:type], arg)
+      member(opt[:type], arg, place)
     end
   end
 
@@ -618,6 +706,13 @@ class CAStruct::Builder  # :nodoc:
             "bit member requires bits: as an Integer in 1..64 (got #{bits.inspect})"
     end
     total_bit_offset = @offset * 8 + @bit_offset
+    # A bit member is read from one word of up to 8 bytes starting at the
+    # byte it begins in, so it may not reach past the 64th bit of that word.
+    if (total_bit_offset % 8) + bits > 64
+      raise CAStruct::DefinitionError,
+            "bit member #{name.to_s.inspect} (bits: #{bits}) starts at bit " \
+            "#{total_bit_offset % 8} of a byte and would span more than 8 bytes"
+    end
     mem = Member.new(name.to_s, :bitfield,
                      {:bits       => bits,
                       :bit_offset => total_bit_offset,
@@ -676,6 +771,7 @@ class CAStruct::Builder  # :nodoc:
                 "#{typename} requires at least one member name " \
                 "(use nil for anonymous padding)"
         end
+        CAStruct::Builder.check_keys!(opt, MEMBER_KEYS, "#{typename}")
         CAStruct::Builder.validate_endian!(opt, "#{typename}", #{allow_endian})
         args.each do |arg|
           member(:#{typename}, arg, opt)

data/lib/carray/table.rb

@@ -16,7 +16,7 @@ class CArray
     #   are silently ignored.
     #   @param list [Array<Symbol, String>, nil] column names.
     #   @return [Array<Symbol, String>, nil] the assigned list.
-    #   @raise [RuntimeError] when `list.size != dim1`.
+    #   @raise [ArgumentError] when `list.size != dim1`.
     def column_names= (list)
       if self.empty?
         return
@@ -25,7 +25,7 @@ class CArray
       elsif list.empty? 
         return
       elsif list and list.size != dim1
-        raise "column_names list size is invalid (#{list.size} <=> #{dim1} )"
+        raise ArgumentError, "column_names list size is invalid (#{list.size} <=> #{dim1} )"
       else
         @column_names = list
       end