carray 3.0.1 → 3.0.3

data/lib/carray/complex.rb

@@ -52,6 +52,14 @@ class CArray
   # framework's read-only chain does not replace the CAField mutable view).
   # ---------------------------------------------------------------------------
 
+  # Whether a view kept by {#real} / {#imag} was made for this array.
+  # `dup` and `clone` copy instance variables, so a copy arrives holding the
+  # original's view, whose parent is the original; the copy makes its own.
+  def part_of_self? (view)
+    view && view.parent.equal?(self)
+  end
+  private :part_of_self?
+
   # @overload real
   #   Returns the real part of `self` as a zero-copy view. For a
   #   complex array the view is a mutable {CAField} into the
@@ -59,19 +67,16 @@ class CArray
   #   over `self`. Writing to the view updates `self` in place.
   #   @return [CArray]
   def real
-    if not @__real__
-      if complex?
-        @__real__ = case data_type
-                    when CA_CMPLX64
-                      field(0, CA_FLOAT32)
-                    when CA_CMPLX128
-                      field(0, CA_FLOAT64)
-                    end
-      else
-        @__real__ = self[]
-      end
-    end
-    @__real__
+    return @__real__ if part_of_self?(@__real__)
+    view = if complex?
+             case data_type
+             when CA_CMPLX64  then field(0, CA_FLOAT32)
+             when CA_CMPLX128 then field(0, CA_FLOAT64)
+             end
+           else
+             self[]
+           end
+    frozen? ? view : (@__real__ = view)
   end
 
   # @overload real=(val)
@@ -85,35 +90,37 @@ class CArray
   # @overload imag
   #   Returns the imaginary part of `self`. For a complex array the
   #   result is a mutable {CAField} view of the imaginary slot;
-  #   writing to it updates `self` in place. For a real array the
-  #   result is a fresh independent CArray filled with 0.
+  #   writing to it updates `self` in place. For an object array each
+  #   cell's `imaginary`; for a real array a fresh independent CArray
+  #   filled with 0. Masked cells stay masked.
   #   @return [CArray]
   def imag
-    if not @__imag__
-      if complex?
-        @__imag__ = case data_type
-                    when CA_CMPLX64
-                      field(4, CA_FLOAT32)
-                    when CA_CMPLX128
-                      field(8, CA_FLOAT64)
-                    end
-      else
-        @__imag__ = self.template { 0 }
-      end
+    if object?
+      return imag_i
+    end
+    if not complex?
+      zero = template { 0 }
+      zero[is_masked] = UNDEF if has_mask?
+      return zero
     end
-    return @__imag__
+    return @__imag__ if part_of_self?(@__imag__)
+    view = case data_type
+           when CA_CMPLX64  then field(4, CA_FLOAT32)
+           when CA_CMPLX128 then field(8, CA_FLOAT64)
+           end
+    frozen? ? view : (@__imag__ = view)
   end
 
   # @overload imag=(val)
   #   Sets the imaginary-part slot to `val` (complex arrays only).
   #   @param val [CArray, Numeric] value to broadcast.
   #   @return [Object] `val`.
-  #   @raise [RuntimeError] when `self` is not a complex array.
+  #   @raise [CArray::DataTypeError] when `self` is not a complex array.
   def imag= (val)
     if complex?
       imag[] = val
     else
-      raise "not a complex array"
+      raise CArray::DataTypeError, "not a complex array"
     end
   end
 

data/lib/carray/conditional.rb

@@ -6,7 +6,7 @@
 #  same "pick a value per cell based on a boolean condition" contract but
 #  differ in where the condition lives and how the branches are supplied:
 #
-#      cond.then_else(x, y)                  # boolean receiver, 2 values (eager)
+#      cond.then_else(x, y)                  # boolean receiver, 2 values (lazy if an operand is)
 #      self.replace_where(cond, b)           # value receiver, 1 replacement (eager)
 #      self.conditional(cond, f_then, f_else) # value receiver, 2 callables (per-region)
 #
@@ -25,10 +25,20 @@ class CArray
   #   reading as "if `self` then `x` else `y`". The boolean 2-way
   #   case of {#choose} that additionally propagates `self`'s mask
   #   (`UNDEF` in `self` produces `UNDEF` in the result).
+  #   The result's data type is the common type of the two branches; a
+  #   branch given as `UNDEF` masks its cells and leaves the type to the
+  #   other branch (`cond.then_else(a, UNDEF)` has `a`'s data type).
+  #   When `self` or a branch is a lazy view, the result is a lazy view
+  #   (read-only) that joins the expression around it; `copy` makes an
+  #   array of it.  An object result is always computed at once.
   #   @param x [CArray, Numeric, Object] true-branch value(s).
   #   @param y [CArray, Numeric, Object] false-branch value(s).
-  #   @return [CArray] new array with the same shape as `self`.
-  #   @raise [ArgumentError] when `self` is not a boolean CArray.
+  #   @return [CArray] new array with the same shape as `self`, or a
+  #     lazy view (CATriOp) when an operand is lazy.
+  #   @raise [ArgumentError] when `self` is not a boolean CArray, or when
+  #     an array branch's shape does not pair with `self`'s as an
+  #     operator's operands would (equal, or size-1 axes of the same ndim;
+  #     an object or fixlen result needs `self`'s shape exactly).
   def then_else (x, y)
     # Guard: self must be boolean.  Integer / float receiver would be
     # silently reinterpreted by the indexer setter (`result[self] = ...`)
@@ -38,10 +48,27 @@ class CArray
       raise ArgumentError,
             "then_else: receiver must be a boolean CArray (data_type == CA_BOOLEAN), got #{self.data_type}"
     end
-    # Promote data_type from both branches via CArray.result_type
-    # (a CScalar contributes its own data_type, so CA_INT32(0) keeps int32
-    # where a bare Ruby Integer would widen to int64).
-    dt = CArray.result_type(x, y)
+    reshaped = [x, y].any? { |v| v.is_a?(CArray) && !v.scalar? && v.shape != shape }
+    face = [x, y].find { |v| v.is_a?(CArray) && !v.scalar? && v.face? }
+    if face
+      refuse_branch_shape(x, y) if reshaped
+      return face_then_else(x, y, face)
+    end
+    # Promote data_type from both branches via CArray.result_type, which
+    # lets a scalar branch take the type of an array branch as an operator
+    # does (cond.then_else(0, int32_array) is int32).  UNDEF is a missing
+    # value, not a value of some type: a branch that is UNDEF leaves the
+    # type to the other.
+    typed = [x, y].reject { |v| v.equal?(UNDEF) }
+    dt = typed.empty? ? CA_OBJECT : CArray.result_type(*typed)
+    return lazy_then_else(x, y, dt) if lazy_then_else?(x, y, dt)
+    # A branch shaped unlike the condition goes through the lazy select,
+    # which pairs the shapes by the operator rule (equal, or size-1 axes
+    # with the same ndim) and refuses the rest.
+    if reshaped
+      refuse_branch_shape(x, y) if scalar? || dt == CA_OBJECT || dt == CA_FIXLEN
+      return lazy_then_else(x, y, dt).copy
+    end
     # A CScalar (scalar? CArray) is treated as a scalar value, not as a
     # self-shaped operand: full CArray -> gather/copy, scalar -> broadcast.
     y_full = y.is_a?(CArray) && !y.scalar?
@@ -60,6 +87,66 @@ class CArray
     result
   end
 
+  # A lazy receiver or branch makes the selection a lazy node (CATriOp
+  # select), so it joins the expression around it rather than computing
+  # it here.  The branches carry the result type: a scalar branch becomes
+  # a CScalar of it, UNDEF a masked one.
+  private def lazy_then_else? (x, y, dt)
+    return false if scalar? || dt == CA_OBJECT || dt == CA_FIXLEN
+    [self, x, y].any? { |v| v.is_a?(CArray) && v.__lazy_view__? }
+  end
+
+  # The types the lazy select cannot carry keep the strict form: a full
+  # branch must have the condition's shape.
+  private def refuse_branch_shape (x, y)
+    bad = [x, y].find { |v| v.is_a?(CArray) && !v.scalar? && v.shape != shape }
+    raise ArgumentError,
+          "then_else: branch shape #{bad.shape.inspect} does not match the condition's #{shape.inspect}"
+  end
+
+  private def lazy_then_else (x, y, dt)
+    branch = lambda do |v|
+      next v if v.is_a?(CArray) && !v.scalar?
+      cell = CScalar.new(dt)
+      cell[0] = v.is_a?(CArray) ? v[0] : v
+      cell
+    end
+    CATriOp.__build__(self, branch.(x), branch.(y), CATriOp::OP_SELECT)
+  end
+
+  private def face_then_else (x, y, face)
+    # A Face branch decides the result: the other branch is written into a
+    # copy of it through the Face's own store, so an instant stays an instant.
+    # Promoting the two branches to a common data type would compare a Face's
+    # surface type with its storage's.  A CAConstString cannot be written, so
+    # it selects among its strings and packs them again.
+    if face.is_a?(CAConstString)
+      sx = x.is_a?(CAConstString) ? x.to_string : x
+      sy = y.is_a?(CAConstString) ? y.to_string : y
+      return CArray.const_string(then_else(sx, sy), encoding: face.encoding)
+    end
+    x_full = x.is_a?(CArray) && !x.scalar?
+    y_full = y.is_a?(CArray) && !y.scalar?
+    base   = y_full ? y : x
+    if base.read_only?
+      # No store to write through (a CACategorical's codes): select among
+      # the values themselves.
+      result = CArray.object(*shape)
+      result[] = y_full ? y.to_type(CA_OBJECT) : y
+      result[self] = x_full ? x.to_type(CA_OBJECT)[self] : x
+      result[self.is_masked] = UNDEF if self.has_mask?
+      return result
+    end
+    result = base.copy
+    if y_full
+      result[self] = x_full ? x[self] : x
+    else
+      result[self.not] = y.is_a?(CArray) ? y[0] : y
+    end
+    result[self.is_masked] = UNDEF if self.has_mask?
+    result
+  end
+
   # @overload replace_where(cond, b)
   #   Returns a copy of `self` with cells where `cond` is true
   #   replaced by `b`. Functional sibling of the destructive

data/lib/carray/const_string.rb

@@ -5,12 +5,15 @@
 #  CAConstString high-level construction + conversion surface.
 #
 #  CAConstString itself (the Face + tail buffer + fetch decode + numeric gate) lives
-#  in ext/ca_obj_const_string.c.  This file provides the ergonomic builders that pack
-#  Ruby Strings into the internal length-prefix buffer + int64 offset entity
-#  and wrap them via the CAConstString.wrap C primitive.
+#  in ext/ca_obj_const_string.c.  This file provides the ergonomic builders that
+#  pack Ruby Strings into the shared buffer + (start,end) pair entity, via the
+#  CAConstString.__build__ C primitive.
 #
-#  Internal buffer format: concatenation of `[int32 length][bytes...]` records
-#  (self-delimiting → one offset per element, permutation-safe view).
+#  Internal buffer format: a pure concatenation of the element bytes, with no
+#  per-record length prefix (= the Arrow values buffer).  Each element carries
+#  its own `(start, end)` byte range in the storage, so it is self-describing
+#  and a gather / sort / select view over the pairs decodes correctly with no
+#  buffer copy.
 #
 # ----------------------------------------------------------------------------
 
@@ -89,21 +92,125 @@ class CAConstString
   # override the L1 generics where present.
   include CArray::StringOperationMixin
 
-  # @overload sort
-  #   Returns a byte-order sorted view built by gathering the
-  #   offsets with `sort_index`. Neither bytes nor offsets are
-  #   copied.
+  # ---- ordering family ---------------------------------------------------
+  #
+  # A storage cell is a `(start, end)` byte range into the shared buffer, so
+  # storage order is the order the strings were packed in, not the order they
+  # compare in.  Without these overrides the family sorted the offsets: the
+  # answers came back well-formed and wrong -- `%w[pear apple].sort_addr` gave
+  # the identity, and `partition_copy` gave NUL bytes.
+  #
+  # Every member therefore reads the bytes.  The flat forms do it natively
+  # (a byte-memcmp scan over the packed buffer, an order of magnitude faster
+  # than decoding a Ruby String per cell), the per-axis forms through
+  # {#to_string}, where a cell is the string and CArray's own kernels apply.
+  # Arguments are forwarded verbatim, so `kind:` / `masked_position:` /
+  # `keep_axis:` mean here what they mean on CArray.
+  #
+  # Anything whose cells are strings comes back a CAConstString, gathered
+  # over the same buffer where it can be (sort / sort_copy) and rebuilt where
+  # it cannot.  Indices, addresses and counts need no conversion.
+
+  # @overload sort(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns a sorted {CAConstString} view, gathered over the same buffer
+  #   and offsets.  With no `axis:` the array is flattened first, as
+  #   `CArray#sort` does.
   #   @return [CAConstString]
-  def sort
-    self[sort_index]
+  def sort (*args, **kw)
+    addr = sort_addr(*args, **kw)
+    kw[:axis].nil? ? self[addr.flatten] : self[addr]
+  end
+
+  # @overload sort_copy(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns an owned sorted {CAConstString}; the materialised counterpart
+  #   to {#sort}.
+  #   @return [CAConstString]
+  def sort_copy (*args, **kw)
+    sort(*args, **kw).copy
+  end
+
+  # @overload sort_addr(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns the view-flat addresses that index a sort by string order.
+  #   @return [CArray] `:int64` addresses.
+  def sort_addr (*args, **kw)
+    # The native scan has no notion of an incomparable sentinel, so a masked
+    # column goes the same way a per-axis one does.
+    return __sort_addr_bytes__ if args.empty? && kw.empty? && ! has_mask?
+    to_string.sort_addr(*args, **kw)
+  end
+
+  # @overload sort_index(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns the per-fiber indices that index a sort by string order.
+  #   @return [CArray] `:int64` indices.
+  def sort_index (*args, **kw)
+    to_string.sort_index(*args, **kw)
+  end
+
+  # @overload rank_index(axis: nil)
+  #   @return [CArray] each cell's rank in string order.
+  def rank_index (*args, **kw)
+    to_string.rank_index(*args, **kw)
+  end
+
+  # @overload order(*args)
+  #   @return [CArray] the ordering of the cells by string order.
+  def order (*args, **kw)
+    to_string.order(*args, **kw)
+  end
+
+  # @overload min(axis: nil, keep_axis: false)
+  #   Returns the byte-smallest string, skipping masked cells; UNDEF when
+  #   every cell is masked or the array is empty.
+  #   @return [String, CAConstString]
+  def min (*args, **kw)
+    return __min_bytes__ || UNDEF if args.empty? && kw.empty?
+    const_string_lift(to_string.min(*args, **kw))
+  end
+
+  # @overload max(axis: nil, keep_axis: false)
+  #   Byte-largest counterpart of {#min}.
+  #   @return [String, CAConstString]
+  def max (*args, **kw)
+    return __max_bytes__ || UNDEF if args.empty? && kw.empty?
+    const_string_lift(to_string.max(*args, **kw))
+  end
+
+  # @overload minmax(axis: nil, keep_axis: false)
+  #   @return [Array] `[min, max]`.
+  def minmax (*args, **kw)
+    return [min, max] if args.empty? && kw.empty?
+    to_string.minmax(*args, **kw).map { |r| const_string_lift(r) }
   end
 
-  # @overload sort_copy
-  #   Returns an owned sorted {CAConstString}; the materialised
-  #   counterpart to {#sort}.
+  # @overload clip(min, max = nil, fill_value = nil, lfill: nil, ufill: nil)
+  #   Clips the strings in byte order (see {CArray#clip}).
   #   @return [CAConstString]
-  def sort_copy
-    self[sort_index].copy
+  def clip (*args, **kw)
+    const_string_lift(to_string.clip(*args, **kw))
+  end
+
+  # @overload min_index(axis: nil)
+  #   @return [Integer, CArray] where the byte-smallest string sits.
+  def min_index (*args, **kw)
+    to_string.min_index(*args, **kw)
+  end
+
+  # @overload max_index(axis: nil)
+  #   @return [Integer, CArray] where the byte-largest string sits.
+  def max_index (*args, **kw)
+    to_string.max_index(*args, **kw)
+  end
+
+  # @overload partition_copy(kth, axis: nil)
+  #   @return [CAConstString] partitioned about the `kth` string in order.
+  def partition_copy (*args, **kw)
+    const_string_lift(to_string.partition_copy(*args, **kw))
+  end
+
+  # @overload partition_index(kth, axis: nil)
+  #   @return [CArray] the indices that partition about the `kth` string.
+  def partition_index (*args, **kw)
+    to_string.partition_index(*args, **kw)
   end
 
   # CAConstString is the one Face with three separate entities -- storage
@@ -144,14 +251,14 @@ class CAConstString
   # @overload unique(sort: false)
   #   @return [CAConstString] the distinct strings.
   def unique (sort: false)
-    to_string.unique(sort: sort).to_const_string
+    const_string_lift(to_string.unique(sort: sort))
   end
 
   # @overload value_counts(sort: false)
   #   @return [Array(CAConstString, CArray)] `[values, counts]`.
   def value_counts (sort: false)
     values, counts = to_string.value_counts(sort: sort)
-    [values.to_const_string, counts]
+    [const_string_lift(values), counts]
   end
 
   # @overload nunique(axis: nil, keep_axis: false)
@@ -164,11 +271,7 @@ class CAConstString
   #   @return [CAConstString, Array] the most frequent string(s).
   def mode (axis: nil)
     r = to_string.mode(axis: axis)
-    case r
-    when CArray then r.to_const_string
-    when Array  then r.map { |c| c.is_a?(CArray) ? c.to_const_string : c }
-    else r
-    end
+    r.is_a?(Array) ? r.map { |c| const_string_lift(c) } : const_string_lift(r)
   end
 
   # @overload is_mode(axis: nil)
@@ -180,7 +283,7 @@ class CAConstString
   # @overload mask_duplicates(axis: nil)
   #   @return [CAConstString] a copy with every repeat occurrence masked.
   def mask_duplicates (axis: nil)
-    to_string.mask_duplicates(axis: axis).to_const_string
+    const_string_lift(to_string.mask_duplicates(axis: axis))
   end
 
   # @overload is_in(values)
@@ -192,19 +295,19 @@ class CAConstString
   # @overload intersection(other, sort: false)
   #   @return [CAConstString] the distinct strings present in both.
   def intersection (other, sort: false)
-    to_string.intersection(string_operand(other), sort: sort).to_const_string
+    const_string_lift(to_string.intersection(string_operand(other), sort: sort))
   end
 
   # @overload difference(other, sort: false)
   #   @return [CAConstString] the distinct strings only `self` has.
   def difference (other, sort: false)
-    to_string.difference(string_operand(other), sort: sort).to_const_string
+    const_string_lift(to_string.difference(string_operand(other), sort: sort))
   end
 
   # @overload union(other, sort: false)
   #   @return [CAConstString] the distinct strings of either side.
   def union (other, sort: false)
-    to_string.union(string_operand(other), sort: sort).to_const_string
+    const_string_lift(to_string.union(string_operand(other), sort: sort))
   end
 
   # @overload locate_addr(ref)
@@ -219,10 +322,57 @@ class CAConstString
     to_string.categorize(labels: labels, sort_labels: sort_labels)
   end
 
+  # ---- comparison operators ---------------------------------------------
+  #
+  # The core operators compare storage, and a storage cell is a byte range:
+  # `x < "dd"` compared where each string sits in the buffer and answered
+  # true everywhere.  They read the strings here instead.  `eq` has a native
+  # byte scan and stays; `<=>` composes from `>` and `<`, so it follows.
+
+  # @!method ne(other)
+  #   @return [CArray] boolean, true where the strings differ.
+  # @!method lt(other)
+  #   @return [CArray] boolean, true where self sorts before `other`.
+  # @!method le(other)
+  #   @return [CArray] boolean, true where self sorts before or equals `other`.
+  # @!method gt(other)
+  #   @return [CArray] boolean, true where self sorts after `other`.
+  # @!method ge(other)
+  #   @return [CArray] boolean, true where self sorts after or equals `other`.
+  [:ne, :lt, :le, :gt, :ge].each do |op|
+    define_method(op) { |other| to_string.public_send(op, string_operand(other)) }
+  end
+
+  alias <  lt
+  alias <= le
+  alias >  gt
+  alias >= ge
+
   # A CAConstString operand has to be decoded too; anything else (a CAString,
   # an object array, an Array) already compares as strings.
   private def string_operand (other)
     other.is_a?(CAConstString) ? other.to_string : other
   end
 
+  # Pack a string-bearing result back into a column of this one's encoding.
+  # The encoding has to be carried: the builder checks each element against
+  # the column's, so a Shift_JIS column rebuilt as the UTF-8 default raised
+  # rather than coming back.
+  private def const_string_lift (x)
+    x.is_a?(CArray) ? CArray.const_string(x, encoding: encoding) : x
+  end
+
+end
+
+class CAConstString
+  # The decimal readers of CAFrame#infer_types / #cast, read from the buffer
+  # without a String per cell.
+  def __infer_number_type_of_text__
+    CArray.__const_string_infer_number_type_of_text__(self)
+  end
+
+  def __read_text_as_number__(type, report = nil)
+    out = CArray.__const_string_read_text_as_number__(self, type, report)
+    out && ndim > 1 ? out.reshape(*shape) : out
+  end
 end

data/lib/carray/construct.rb

@@ -256,6 +256,46 @@ class CArray
   TypeSymbol = nil
   # @!visibility private
   DataType   = nil
+
+  # @overload empty(data_type, dim, bytes: nil)
+  #   Returns a new CArray of `data_type` with the shape `dim`, whose
+  #   contents are **undefined**. This is {CArray.new} without the fill:
+  #   the arguments are read the same way, and the cost of zeroing the
+  #   buffer is not paid. Use it when every cell is written before it is
+  #   read; otherwise use `CArray.new`, which zero-fills.
+  #
+  #   `CA_OBJECT` is the exception: its cells are zero-initialised
+  #   anyway, because the garbage collector walks them.
+  #
+  #   @param data_type [Symbol, String, Integer] element type.
+  #   @param dim [Array<Integer>] shape of the new CArray.
+  #   @param bytes [Integer, nil] element width, for `:fixlen` only.
+  #   @return [CArray]
+  #   @raise [ArgumentError] if a block is given -- filling an array is
+  #     what `CArray.new` is for.
+  # @overload empty(*shape)
+  #   (Numo / NumPy compatibility) Returns an uninitialised CArray of
+  #   the given shape. The element type comes from the receiver, so
+  #   `CArray` itself gives `CA_FLOAT64`; see
+  #   {DataTypeExtension#empty}.
+  #   @param shape [Array<Integer>, Array<Array<Integer>>] shape.
+  #   @return [CArray]
+  def self.empty (*args, **options, &block)
+    if block
+      raise ArgumentError,
+            "CArray.empty does not take a block " \
+            "(its contents are left undefined); use CArray.new to fill."
+    end
+    if args.size == 2 and args[1].is_a?(Array)
+      return __empty__(*args, **options)
+    end
+    unless options.empty?
+      raise ArgumentError,
+            "CArray.empty(*shape) takes no options; bytes: belongs to " \
+            "CArray.empty(data_type, dim)"
+    end
+    super(*args)
+  end
 end
 
 class CArray

data/lib/carray/data_type_extension.rb

@@ -237,6 +237,9 @@ class CArray
     #   **uninitialised**. The caller must overwrite the array
     #   before reading from it. `CA_OBJECT` silently falls back to
     #   a zero-VALUE init required for GC safety.
+    #
+    #   carray's own spelling is `CArray.empty(data_type, dim)`, which
+    #   names the element type instead of taking it from the receiver.
     #   @param shape [Array<Integer>, Array<Array<Integer>>]
     #   @return [CArray]
     def empty (*args)

data/lib/carray/data_type_limits.rb

@@ -0,0 +1,91 @@
+#  What each numeric data type can hold, as constants on the typed
+#  classes.
+#
+#      CArray::Int32::MAX        #  =>  2147483647
+#      CArray::Float32::EPSILON  #  =>  1.1920928955078125e-07
+#
+#  The names follow NumPy's iinfo / finfo rather than Ruby's Float, so
+#  that MIN and MAX bracket the range for every numeric type alike:
+#
+#      CArray::Float64::MIN      #  => -1.7976931348623157e+308
+#      Float::MIN                #  =>  2.2250738585072014e-308
+#
+#  Those are not the same number and not the same question.  Ruby's
+#  Float::MIN is the smallest positive normal, which is TINY here; MIN
+#  is the bottom of the range, which for an integer type is the only
+#  thing MIN could mean.  Code that has to bracket a type without
+#  knowing whether it is integer or float reads MIN and MAX and is
+#  right either way, and that is the reason for the choice.
+#
+#  Not every data type has limits.  boolean, fixlen and object have no
+#  numeric range, so they carry none of these constants -- asking gives
+#  a NameError rather than an answer that would have to be invented.
+
+class CArray
+
+  #  The integer widths come from the extension rather than from a table
+  #  written here, so a platform where a type is not the usual width is
+  #  described correctly instead of confidently mis-described.
+
+  {
+    Int8   => true,  Int16  => true,  Int32  => true,  Int64  => true,
+    UInt8  => false, UInt16 => false, UInt32 => false, UInt64 => false,
+  }.each do |klass, signed|
+    bits = 8 * CArray.sizeof(klass::TypeSymbol)
+    if signed
+      klass.const_set(:MIN, -(2 ** (bits - 1)))
+      klass.const_set(:MAX, 2 ** (bits - 1) - 1)
+    else
+      klass.const_set(:MIN, 0)
+      klass.const_set(:MAX, 2 ** bits - 1)
+    end
+  end
+
+  #  float32 and float64 are IEEE-754 binary32 and binary64, and the four
+  #  values below follow from the format: with `p` significand bits (the
+  #  implicit one included) and `emax` the exponent of the largest finite
+  #  value,
+  #
+  #      EPSILON = 2 ** (1 - p)          the step from 1.0 to the next float
+  #      MAX     = (2 - EPSILON) * 2 ** emax
+  #      MIN     = -MAX                  every format here is symmetric
+  #      TINY    = 2 ** (1 - emax)       the smallest positive normal
+  #
+  #  All four are exactly representable as a Ruby Float, binary32
+  #  included, so nothing is rounded on the way in.  The width is
+  #  checked rather than assumed: on a platform where C float or double
+  #  is not one of these formats the arithmetic below would be wrong,
+  #  and a wrong limit is worse than a missing one.
+
+  {
+    Float32 => [4, 24, 127],
+    Float64 => [8, 53, 1023],
+  }.each do |klass, (bytes, precision, max_exponent)|
+    actual = CArray.sizeof(klass::TypeSymbol)
+    unless actual == bytes
+      raise "#{klass} is #{actual} bytes wide, not the #{bytes * 8}-bit IEEE-754 " \
+            "format its limits are derived from"
+    end
+    epsilon = 2.0 ** (1 - precision)
+    max     = (2.0 - epsilon) * 2.0 ** max_exponent
+    klass.const_set(:EPSILON, epsilon)
+    klass.const_set(:MAX,     max)
+    klass.const_set(:MIN,     -max)
+    klass.const_set(:TINY,    2.0 ** (1 - max_exponent))
+  end
+
+  #  A complex type is a pair of floats, so its limits are its
+  #  component's -- MIN and MAX bound the real and the imaginary part
+  #  separately, not any magnitude of the pair.  This is what
+  #  np.finfo(np.complex64) answers too.
+
+  {
+    Complex64  => Float32,
+    Complex128 => Float64,
+  }.each do |klass, component|
+    [:MIN, :MAX, :TINY, :EPSILON].each do |name|
+      klass.const_set(name, component.const_get(name))
+    end
+  end
+
+end

data/lib/carray/fixlen_string.rb

@@ -3,7 +3,7 @@
 #  CAFixlenString high-level construction surface.
 #
 #  CAFixlenString itself (the string interpretation of CA_FIXLEN storage) lives
-#  in ext/ca_obj_string.c.  This file provides the ergonomic builder that packs
+#  in ext/ca_obj_fixlen_string.c.  This file provides the ergonomic builder that packs
 #  Ruby Strings into a fixed-width CA_FIXLEN entity and wraps it via
 #  CAFixlenString.wrap.
 #