carray 3.0.4 → 3.0.5

data/lib/carray/frame/group.rb

@@ -158,7 +158,7 @@ class CAFrame
     g_of = nb > 0 ? occupied / nb : occupied
     b_of = nb > 0 ? occupied % nb : occupied
     # Each group's by values, from its first row.
-    order = gcat.sort_addr
+    order = gcat.group_addr
     first = order[CArray.segment_offsets(lengths: gcat.category_sizes)[0...ng]]
     columns = {}
     by_names.zip(by_cols).each do |n, col|
@@ -239,10 +239,11 @@ end
 # GroupedFrame — the result of +CAFrame#group_by+ (memo §11.6, §16).
 #
 # Holds the grouping categorical once (grouping is per-key, computed once
-# and shared across every column). Three surfaces:
-#   grp["col"]   -> the CArray group iterator (raw exposure)
-#   aggregate    -> declarative per-column reductions into a new frame
-#   table { |g| }-> cross-column Ruby escape, g is a per-group view-frame
+# and shared across every column). The surfaces:
+#   grp["col"], grp[array] -> the CArray group iterator of a column or array
+#   aggregate(spec)        -> declarative per-column reductions into a new frame
+#   aggregate { |grp| }    -> columns built from iterators, run once
+#   table { |g| }          -> Ruby escape, g is a per-group view-frame
 class GroupedFrame
   include CAFrame::ColumnVerbs
   # +key_names+ are the frame columns the grouping was keyed on. They become
@@ -285,10 +286,40 @@ class GroupedFrame
     @labels.dup
   end
 
-  # Raw exposure: the CArray group iterator for one column (memo §11.6).
-  def [](name)
+  # The CArray group iterator of a column, or of any CArray with one entry
+  # per row of the frame: a value computed from columns, or a column with
+  # some cells masked to leave them out. Its reductions answer one value
+  # per group, and take the arguments a CArray's reductions take.
+  #
+  #   grp["temp"].percentile(90)
+  #   grp[df["temp"] * df["w"]].sum / grp["w"].sum
+  #   grp[df["temp"].mask_where(df["qc"].ne(0))].mean   # without the flagged rows
+  #
+  # The array is matched to the rows by position, as a CArray key of
+  # +group_by+ is. An N-D one is grouped along its first axis; pass
+  # +axis: 0+ to its reductions to keep the trailing shape.
+  #
+  # @param source [String, CArray] a column name, or a CArray whose first
+  #   axis has one entry per row.
+  # @return [CACategoricalIterator]
+  # @raise [KeyError] for a name that is no column.
+  # @raise [ArgumentError] when the CArray's first axis is not the rows.
+  def [](source)
     refuse_changed_rows("[]")
-    @frame[name].group_by_category(@cat)
+    values =
+      case source
+      when CArray
+        rows = source.ndim == 0 ? 0 : source.shape[0]
+        unless source.ndim >= 1 && rows == @cat.elements
+          raise ArgumentError,
+                "[]: the array has #{source.ndim == 0 ? "no axis" : "#{rows} rows"} " \
+                "for the frame's #{@cat.elements}"
+        end
+        source
+      else
+        @frame[@frame.__send__(:column_key, source, "[]")]
+      end
+    values.group_by_category(@cat)
   end
 
   # Declarative aggregation (memo §11.6). Spec maps an output column name to
@@ -304,8 +335,34 @@ class GroupedFrame
   # keyword works for +table+ and the reductions below.
   #
   #   df.group_by("station").aggregate("temp_mean" => ["temp", :mean], keep_rows: true)
-  def aggregate(spec = nil, keep_rows: false, **named)
+  #
+  # Given a block instead of a spec, aggregate yields the grouped frame once
+  # and the block returns a Hash of output name => a CArray with one entry
+  # per group. The block computes the columns with the grouped frame's
+  # reductions, +grp[...]+ iterators and CArray arithmetic, so nothing runs
+  # per group in Ruby:
+  #
+  #   df.group_by("station").aggregate do |g|
+  #     {
+  #       "temp"  => g["temp"].mean,
+  #       "range" => g["temp"].max - g["temp"].min,
+  #       "wmean" => g[df["temp"] * df["w"]].sum / g["w"].sum,
+  #       "n"     => g["temp"].group_sizes,
+  #     }
+  #   end
+  #
+  # +keep_rows: true+ lays each column over the rows as for a spec.
+  #
+  # @raise [ArgumentError] when both a spec and a block are given, or the
+  #   block returns something other than a Hash of per-group CArrays.
+  def aggregate(spec = nil, keep_rows: false, **named, &block)
     refuse_changed_rows("aggregate")
+    if block
+      unless spec.nil? && named.empty?
+        raise ArgumentError, "aggregate: give a spec or a block, not both"
+      end
+      return result_frame(block_columns(yield(self)), keep_rows)
+    end
     spec = (spec || {}).merge(named)
     cols = {}
     spec.each do |out_name, (in_name, reduction, *args)|
@@ -364,7 +421,9 @@ class GroupedFrame
   # its trailing shape: a (N, L) column gives (groups, L). Each
   # takes +min_count:+ and +fill_value:+ as a core reduction does: a group
   # with fewer than min_count present values is UNDEF, and fill_value fills
-  # the UNDEF cells. +keep_rows: true+ gives each row its group's value
+  # the UNDEF cells. One fill_value goes to every column and has to suit each
+  # (a number into a string column raises); a Hash of column name => value
+  # fills those columns only. +keep_rows: true+ gives each row its group's value
   # instead of one row per group, as for +aggregate+.
   #
   # Given column names, they reduce those columns only and return them as
@@ -644,8 +703,18 @@ class GroupedFrame
   # +keep_rows+.
   private def reduce_columns(reduction, names, keep_rows, **keywords)
     keywords = keywords.compact
-    out = over_named_columns(reduction, names, @key_names) do |col|
-      col = group_reduce(col, reduction, **keywords)
+    fills = keywords.delete(:fill_value)
+    if fills.is_a?(Hash)
+      unknown = fills.keys - @frame.column_names
+      unless unknown.empty?
+        raise ArgumentError,
+              "#{reduction}: fill_value names no column #{unknown.map(&:inspect).join(', ')}"
+      end
+    end
+    out = over_named_columns(reduction, names, @key_names) do |col, name|
+      fill = fills.is_a?(Hash) ? fills[name] : fills
+      kw = fill.nil? ? keywords : keywords.merge(fill_value: fill)
+      col = group_reduce(col, reduction, **kw)
       keep_rows && !names.empty? ? spread_to_rows(col) : col
     end
     return out unless names.empty?
@@ -690,6 +759,24 @@ class GroupedFrame
     end
   end
 
+  # The columns an aggregate block returned: a Hash of names to CArrays
+  # with one entry per group along their first axis.
+  private def block_columns(out)
+    unless out.is_a?(Hash)
+      raise ArgumentError, "aggregate block must return a Hash (got #{out.class})"
+    end
+    out.each_with_object({}) do |(name, col), cols|
+      name = @frame.__send__(:column_name_arg, name, "aggregate")
+      unless col.is_a?(CArray) && col.ndim >= 1 && col.shape[0] == ngroup
+        got = col.is_a?(CArray) ? "shape #{col.shape.inspect}" : col.class.to_s
+        raise ArgumentError,
+              "aggregate: #{name.inspect} must be a CArray with one value per group " \
+              "(#{ngroup}), got #{got}"
+      end
+      cols[name] = col
+    end
+  end
+
   private def per_group_column(in_name, proc)
     results = []
     each_group_slice(in_name) { |slice| results << proc.call(slice) }
@@ -751,7 +838,7 @@ class GroupedFrame
   end
 
   private def group_perm
-    @group_perm ||= @cat.sort_addr
+    @group_perm ||= @cat.group_addr
   end
 
   private def group_bounds

data/lib/carray/frame/io.rb

@@ -66,7 +66,9 @@ class CAFrame
   #   attrs:    attribute keys for the lines right below the header, one
   #             key per line: field j of a line becomes that attribute of
   #             column j (an empty field gives none). The data then starts
-  #             below them. What to_csv(attrs:) writes, it reads back
+  #             below them. What to_csv(attrs:) writes, it reads back. The
+  #             fields are read as the data fields are, so strip: trims them
+  #             too
   #
   #   CAFrame.from_csv("obs.csv", header: 2)            # a title above
   #   CAFrame.from_csv("obs.csv", header: 0, data: 3)   # units on lines 1-2

data/lib/carray/fuse_source.rb

@@ -160,9 +160,9 @@ class CArray
 
     def self.extract (block)
       sequence = RubyVM::InstructionSequence.of(block) rescue nil
-      location = sequence && sequence.to_a[4][:code_location]
       path     = sequence && (sequence.absolute_path || sequence.path)
-      unless location && path && File.readable?(path)
+      location = path && File.readable?(path) && code_location(sequence, path)
+      unless location
         raise ArgumentError,
               "CArray.fuse cannot read this block's source (defined in irb, " \
               "eval, or a file that is no longer there).  Write `.lazy` on " \
@@ -181,6 +181,35 @@ class CArray
       end
     end
 
+    # [first_line, first_column, last_line, last_column] of the block.  The
+    # block that starts on the sequence's first line is found in the file's
+    # syntax tree.  Only when two start on that line is the sequence itself
+    # dumped: InstructionSequence#to_a reads the instructions while another
+    # Ractor may be running them, and that can crash the process.
+    def self.code_location (sequence, path)
+      line = sequence.first_lineno
+      found = []
+      pending = [Prism.parse_file(path).value]
+      until pending.empty?
+        node = pending.pop
+        next unless node
+        # A lambda's code starts after the arrow, at its parameters or brace.
+        start = case node
+                when Prism::BlockNode  then node.location
+                when Prism::LambdaNode then (node.parameters || node).location
+                end
+        start = node.opening_loc if start && node.is_a?(Prism::LambdaNode) && !node.parameters
+        found << [start, node.location] if start && start.start_line == line
+        pending.concat(node.compact_child_nodes)
+      end
+      if found.size == 1
+        start, whole = found.first
+        [start.start_line, start.start_column, whole.end_line, whole.end_column]
+      else
+        sequence.to_a[4][:code_location]
+      end
+    end
+
     # -- the rewrite -------------------------------------------------------
 
     # The leaves are the names being read.  Everything else keeps its shape:

data/lib/carray/lazy.rb

@@ -330,9 +330,28 @@ class CArray
     # branch uses C99 `remainder`, round-half-to-even).
   }.freeze
 
+  # A Face answers an operator by its own values (a label, an instant, a
+  # String) and refuses what it can't answer; the lazy kernels read the
+  # storage and see neither.  With a Face among the operands the operator is
+  # the eager one, on the lazy operands computed.
+  module LazyDispatch
+    private
+
+    def face_among_operands? (*operands)
+      operands.any? { |o| o.is_a?(CArray) && o.face? }
+    end
+
+    def computed_operand (operand)
+      ( operand.is_a?(CArray) && operand.lazy_view? ) ? operand.copy : operand
+    end
+  end
+
   CArray.send(:define_named_methods, LazyDispatch, LAZY_BINOP_OP_IDS, template: <<~'RUBY')
     def __NAME__(other)
       if lazy_view? || (other.is_a?(CArray) && other.lazy_view?)
+        if face_among_operands?(self, other)
+          return computed_operand(self).__send__(__method__, computed_operand(other))
+        end
         CABinOp.__build__(self, other, __VALUE__)
       else
         super(other)
@@ -403,6 +422,10 @@ class CArray
                       (op2.is_a?(CArray) && op2.lazy_view?) ||
                       (op3.is_a?(CArray) && op3.lazy_view?)
       if lazy_receiver
+        if face_among_operands?(self, op2, op3)
+          return computed_operand(self).__send__(__method__, computed_operand(op2),
+                                                 computed_operand(op3))
+        end
         CATriOp.__build__(self, op2, op3, __VALUE__)
       else
         super(op2, op3)
@@ -435,6 +458,10 @@ class CArray
   # is already fast.  The lazy-substrate gap was Float/Complex only.
   module LazyDispatch
     def **(other)
+      if ( lazy_view? || (other.is_a?(CArray) && other.lazy_view?) ) &&
+         face_among_operands?(self, other)
+        return computed_operand(self) ** computed_operand(other)
+      end
       if other.is_a?(Integer) && (float? || complex?) &&
          (lazy_view? || (other.is_a?(CArray) && other.lazy_view?))
         CABinOp.__build__(self, CScalar.int64.tap { |s| s[0] = other },
@@ -492,6 +519,9 @@ class CArray
   CArray.send(:define_named_methods, LazyDispatch, LAZY_BINCMP_OP_IDS, template: <<~'RUBY')
     def __NAME__(other)
       if lazy_view? || (other.is_a?(CArray) && other.lazy_view?)
+        if face_among_operands?(self, other)
+          return computed_operand(self).__send__(__method__, computed_operand(other))
+        end
         CABinCmp.__build__(self, other, __VALUE__)
       else
         super(other)
@@ -511,6 +541,9 @@ class CArray
   CArray.send(:define_named_methods, LazyDispatch, LAZY_BINCMP_TOL_OP_IDS, template: <<~'RUBY')
     def __NAME__(other, tol)
       if lazy_view? || (other.is_a?(CArray) && other.lazy_view?)
+        if face_among_operands?(self, other)
+          return computed_operand(self).__send__(__method__, computed_operand(other), tol)
+        end
         CABinCmp.__build__(self, other, __VALUE__, tol.to_f.abs)
       else
         super(other, tol)
@@ -598,6 +631,8 @@ class CAMonOp
     op_id = __op_id__
     if op_id >= CAMonOp::CAST_BASE
       "cast_#{CArray.data_type_name(op_id - CAMonOp::CAST_BASE)}"
+    elsif op_id == CAMonOp::OP_BYTE_SWAP
+      "swap_bytes"       # a view of its own, not a lazy operation by name
     else
       (OP_NAMES[op_id] || "op_#{op_id}").to_s
     end

data/lib/carray/methods/is_in.rb

@@ -226,8 +226,15 @@ class CArray
       # set for not matching self.  Same rule the scalar operand of a
       # comparison follows: a String standing in for a cell is padded to the
       # cell's width.
+      # A String longer than the cell keeps its length: self is read at its
+      # width instead (NUL-padded), so "abX" is in no two-byte cell.
+      w = elems.map { |v| v.is_a?(String) ? v.bytesize : 0 }.max.to_i
+      me = self
+      if w > bytes
+        me = is_a?(CAFixlenString) ? to_fixlen_string(bytes: w) : to_type(CA_FIXLEN, bytes: w)
+      end
       # coerce: a fixlen or object set holds values of self's kind (see above)
-      [self, elems.to_ca.to_type(data_type, bytes: bytes)]
+      [me, elems.to_ca.to_type(data_type, bytes: me.bytes)]
     elsif data_type == CA_OBJECT
       # coerce: an object set holds values of self's kind
       [self, elems.to_ca.to_type(data_type)]

data/lib/carray/segment_iterator.rb

@@ -252,12 +252,20 @@ class CASegmentIterator < CAIterator
     return axis_by_masked_copy(axis, :variance) if axis
     m = moments
     return per_segment(core_reduce_kind(:variance)) { |s| s.variance } unless m
+    centred_variance(m, 1)
+  end
+
+  # The kernel divides the centred sum of squares by count - ddof once, as
+  # the core reduction does; scaling the sample variance by (n-1)/n instead
+  # rounds twice and lands an ulp away.
+  def centred_variance (m, ddof)
     cnt   = m[:count]
-    means = m[:sum] / cnt.float64    # per-segment mean (garbage where count 0/1,
-    out   = CArray.float64(@k)       #   ignored by the kernel's n<2 guards)
-    grouped.send(:__reduceat_variance__, @offsets, means, cnt, out)
+    means = m[:sum] / cnt.float64    # per-segment mean (garbage where the count
+    out   = CArray.float64(@k)       #   is too small; the kernel masks those)
+    grouped.send(:__reduceat_variance__, @offsets, means, cnt, out, ddof)
     out
   end
+  private :centred_variance
 
   # @overload stddev
   #   Returns per-segment SAMPLE standard deviation (ddof=1) as float64.
@@ -375,11 +383,7 @@ class CASegmentIterator < CAIterator
     return axis_by_masked_copy(axis, :variancep) if axis
     m = moments
     return per_segment(core_reduce_kind(:variancep)) { |s| s.variancep } unless m
-    cnt = m[:count]
-    vp  = variance * (cnt - 1).float64 / cnt.float64
-    one = cnt.eq(1)                       # one value: defined, unlike variance --
-    vp[one] = (m[:sum] - m[:sum])[one]    # 0.0, or NaN for a NaN or an infinity
-    vp
+    centred_variance(m, 0)               # one value: 0.0, or NaN for a NaN or an infinity
   end
 
   # @overload stddevp

data/lib/carray/serialize.rb

@@ -141,7 +141,15 @@ class CArray::Serializer   # :nodoc:
             "keep its values with Marshal.dump(ca.to_type(:object))"
     end
 
-    file_endian = endian || CArray.endian
+    file_endian = case endian
+                  when nil, :native        then CArray.endian
+                  when :big, CA_BIG_ENDIAN then CA_BIG_ENDIAN
+                  when :little, CA_LITTLE_ENDIAN then CA_LITTLE_ENDIAN
+                  else
+                    raise ArgumentError,
+                          "endian: must be :big, :little, :native, " \
+                          "CA_BIG_ENDIAN or CA_LITTLE_ENDIAN (got #{endian.inspect})"
+                  end
     swap        = (file_endian != CArray.endian)
 
     elements     = ca.elements
@@ -383,6 +391,7 @@ class CArray::Serializer   # :nodoc:
       "members"      => members,
     }
     schema["name"] = klass.name if klass.name
+    schema["order_by"] = klass.order_by.map(&:to_s) if klass.order_by
     schema
   end
 
@@ -439,7 +448,15 @@ class CArray::Serializer   # :nodoc:
     members      = schema["members"]
     record_bytes = schema["record_bytes"]
     builder      = (schema["kind"] == "union") ? CArray.method(:union) : CArray.method(:struct)
-    builder.call(:pack => 1, :size => record_bytes) do
+    order_by     = schema["order_by"]
+    names        = members.map { |m| m["name"].to_s }
+    if order_by && !(order_by.is_a?(Array) && order_by.all? { |n| names.include?(n.to_s) })
+      raise ArgumentError, "corrupt CArray binary data (order_by #{order_by.inspect} " \
+            "names a member the data_class does not have)"
+    end
+    opts = { :pack => 1, :size => record_bytes }
+    opts[:order_by] = order_by.map(&:to_sym) if order_by
+    builder.call(**opts) do
       members.each do |m|
         sym = PEP_TO_SYMBOL[m["type"]]
         unless sym

data/lib/carray/stack.rb

@@ -69,27 +69,28 @@ class CArray
   # No data is copied; reads gather from parents on demand and writes flow
   # back to them (chain composability preserved).
   #
-  # Pieces must agree on `ndim`, `data_type`, byte width, and every axis
-  # length except `axis` (the "meld axis").  Mismatched `data_type` raises:
-  # cast the pieces yourself (`.to_type(:float64)`) or use
-  # {CArray.concatenate} (eager, auto-casts).
+  # Pieces must agree on `ndim` and every axis length except `axis` (the
+  # "meld axis").  Pieces of different data types are brought to a common
+  # one as {CArray.stack} brings them (`promote_list`), through read-only
+  # views of the pieces that need it.
   #
   # "meld" = melt + weld — pieces dissolve their boundaries along the named
   # axis and are regarded as one.
   #
-  # @overload meld(*arrays, axis: 0)
-  # @overload meld(list, axis: 0)
+  # @overload meld(*arrays, axis: 0, data_type: nil)
+  # @overload meld(list, axis: 0, data_type: nil)
   #   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, nil] existing axis to extend (normalises
   #     negative values against the reference ndim); `nil` is the same
   #     as `0`.
+  #   @param data_type [Symbol, Integer, nil] result `data_type`;
+  #     inferred when `nil`.
   #   @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
-  #     (surfaced by CAMeld.new).
-  def self.meld (*arrays, axis: 0)
+  #     or non-axis dim mismatch across pieces (surfaced by CAMeld.new).
+  def self.meld (*arrays, axis: 0, data_type: nil)
     if arrays.length == 1 && arrays[0].is_a?(Array)
       arrays = arrays[0]
     end
@@ -100,6 +101,7 @@ class CArray
       raise ArgumentError, "meld: entries must be CArray (got #{first.class})"
     end
     axis_norm = CArray.normalize_axis(axis, first.ndim, "meld")
+    arrays = CArray.promote_list(arrays, data_type: data_type)
     # Flatten nested CAMeld inputs that share our meld axis: they already
     # describe a segment sequence, so absorbing their parents keeps chain
     # depth at 1 (avoids 2-level xfer_all / reduce chains through the
@@ -119,14 +121,15 @@ class CArray
   # Instance form of {CArray.meld}; non-destructive, see the class method
   # for full semantics.
   #
-  # @overload meld(*others, axis: 0)
+  # @overload meld(*others, axis: 0, data_type: nil)
   #   @param others [Array<CArray>] additional pieces.
   #   @param axis [Integer] existing axis to extend.
+  #   @param data_type [Symbol, Integer, nil] result `data_type`.
   #   @return [CAMeld]
   #   @raise [ArgumentError] when no `others` are given.
-  def meld (*others, axis: 0)
+  def meld (*others, axis: 0, data_type: nil)
     raise ArgumentError, "meld: at least one other array required" if others.empty?
-    CArray.meld(self, *others, axis: axis)
+    CArray.meld(self, *others, axis: axis, data_type: data_type)
   end
 
   # Arrange `list` of uniform-shape pieces in a `tdim`-shape grid that

data/lib/carray/string.rb

@@ -57,6 +57,14 @@ class CArray
       else
         values = Array.new(n) { |i| block.call(i) }
       end
+    elsif arg.is_a?(Integer)
+      raise ArgumentError,
+            "CArray.string: a count is given with a block that makes each " \
+            "String (CArray.string(n) { |i| ... })"
+    elsif arg.is_a?(String) || ! arg.respond_to?(:to_a)
+      raise TypeError,
+            "CArray.string: expected an Array of Strings, an object array or " \
+            "a String array (got #{arg.class})"
     else
       values = arg.to_a
     end

data/lib/carray/string_operation_extension.rb

@@ -31,11 +31,14 @@ class CArray
     # (integer / boolean results).  Shape and mask are carried.
     def string_map (data_type = nil) # :nodoc:
       out = data_type ? template(data_type) : CArray.object(*shape)
+      # A typed result has no nil: a cell the String method answers nil for
+      # (index finds nothing) is UNDEF.
+      cell = data_type ? ->(s) { v = yield(s); v.nil? ? UNDEF : v } : ->(s) { yield(s) }
       if has_mask?
         m = is_masked
-        elements.times { |i| out[i] = (m[i] ? UNDEF : yield(self[i])) }
+        elements.times { |i| out[i] = (m[i] ? UNDEF : cell.(self[i])) }
       else
-        elements.times { |i| out[i] = yield(self[i]) }
+        elements.times { |i| out[i] = cell.(self[i]) }
       end
       data_type ? out : CAString.wrap(out)
     end
@@ -124,10 +127,12 @@ class CArray
     # @return [CArray] `:int`, shape and mask of `self` preserved.
     def bytesize ()    ; string_map(:int) { |s| s.bytesize } ; end
     # Per-cell `String#index`.
-    # @return [CArray] `:int`, shape and mask of `self` preserved.
+    # @return [CArray] `:int`, shape and mask of `self` preserved; UNDEF
+    #   where the cell does not hold the substring.
     def str_index (*a) ; string_map(:int) { |s| s.index(*a) } ; end
     # Per-cell `String#rindex`.
-    # @return [CArray] `:int`, shape and mask of `self` preserved.
+    # @return [CArray] `:int`, shape and mask of `self` preserved; UNDEF
+    #   where the cell does not hold the substring.
     def rindex (*a)    ; string_map(:int) { |s| s.rindex(*a) } ; end
 
     # ---- numeric parse (Integer / Float result) --------------------------
@@ -191,6 +196,9 @@ class CArray
       unless [:error, :silent].include?(truncate)
         raise ArgumentError, "truncate: must be :error or :silent (got #{truncate.inspect})"
       end
+      unless bytes.nil? || (bytes.is_a?(Integer) && bytes >= 1)
+        raise ArgumentError, "to_fixlen_string: invalid bytes: #{bytes.inspect} (a cell needs bytes: of 1 or more)"
+      end
       return self if is_a?(CAFixlenString) && (bytes.nil? || bytes == self.bytes)
 
       if has_mask?
@@ -200,7 +208,7 @@ class CArray
         values = Array.new(elements) { |i| self[i].to_s }
       end
       width = bytes || values.compact.map(&:bytesize).max || 1
-      width = 1 if width < 1
+      width = 1 if width < 1   # every string empty: the narrowest cell
       if truncate == :error
         values.each_with_index do |s, i|
           next if s.nil?

data/lib/carray/struct_builder.rb

@@ -224,11 +224,13 @@ class CAStruct::Builder  # :nodoc:
     end
     vtype = {1 => :uint8, 2 => :uint16, 4 => :uint32, 8 => :uint64}[view_bytes]
     range = bit_in_byte..(bit_in_byte + bits - 1)
+    # The word is read little-endian on every host: bits are numbered
+    # byte by byte from the record's start, as the layout places them.
     reader = ->(data) {
-      data.field(start_byte, vtype).bitfield(range)[0]
+      data.field(start_byte, vtype).endian(:little).bitfield(range)[0]
     }
     writer = ->(data, val) {
-      data.field(start_byte, vtype).bitfield(range)[0] = val
+      data.field(start_byte, vtype).endian(:little).bitfield(range)[0] = val
     }
     [reader, writer].freeze
   end
@@ -241,7 +243,7 @@ class CAStruct::Builder  # :nodoc:
   def self.build_nested_struct_dispatcher (offset, nested_class)
     reader = ->(data) {
       element = nested_class.allocate
-      element.instance_variable_set(:@data, data.field(offset, nested_class).parent)
+      element.instance_variable_set(:@data, data.field(offset, nested_class).send(:face_storage))
       element.freeze if data.frozen?
       element
     }