carray 3.0.3 → 3.0.5

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,12 +133,23 @@ 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"
-    end
-
-    file_endian = endian || CArray.endian
+            "lost); " +
+            (storage ? "save its storage, which ##{storage} gives, or " : "") +
+            "keep its values with Marshal.dump(ca.to_type(:object))"
+    end
+
+    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
@@ -378,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
 
@@ -390,7 +404,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
@@ -434,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
@@ -615,7 +637,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 +650,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 +661,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 +697,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 +750,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/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

@@ -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.
@@ -49,12 +57,26 @@ 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
 
     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 +88,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

@@ -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?
@@ -278,8 +286,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

@@ -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
     }
@@ -288,6 +290,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 +315,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 +475,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 +485,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 +503,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
     }