carray 3.0.2 → 3.0.3

data/yard-stubs/carray_order.rb

@@ -30,13 +30,16 @@ class CArray
   # sort / sort_copy stubs live in yard-stubs/carray_sort.rb (same
   # file split as ext/carray_sort.c <-> ext/carray_order.c).
 
-  # @overload partition(kth, axis: 0, masked_position: :last)
+  # @overload partition(kth, axis: nil, masked_position: :last)
   #   Returns a `CARemap` view of `self` permuted along `axis` so that
   #   the element at fiber-local position `kth` is in its final sorted
   #   place, every element before it is `<=` it, and every element
   #   after it is `>=` it. Order within the two regions is unspecified.
   #   Average `O(n)` per fiber via quickselect.
   #
+  #   Without `axis:` (or with `axis: nil`) `self` is flattened and
+  #   treated as one fiber, as {#sort} does; the result is 1-D.
+  #
   #   Negative `kth` counts from the end of the fiber
   #   (`-self.shape[axis] <= kth < self.shape[axis]`).
   #
@@ -52,32 +55,39 @@ class CArray
   #   among unmasked values.
   #
   #   @param kth [Integer] target fiber-local position along `axis`.
-  #   @param axis [Integer]
+  #   @param axis [Integer, nil] `nil` partitions the whole array.
   #   @param masked_position [Symbol] `:last` (default) or `:first`.
   #   @return [CArray] `CARemap` view of `self`.
   #   @raise [ArgumentError] when `kth` is out of range.
-  def partition(kth, axis: 0, masked_position: :last); end
+  def partition(kth, axis: nil, masked_position: :last); end
 
-  # @overload partition_copy(kth, axis: 0, masked_position: :last)
-  #   Returns a fresh entity `CArray` with the same shape as `self`,
-  #   partitioned along `axis` by the same rule as {#partition}.
+  # @overload partition_copy(kth, axis: nil, masked_position: :last)
+  #   Returns a fresh entity `CArray` partitioned along `axis` by the
+  #   same rule as {#partition}: the shape of `self`, or 1-D when `axis`
+  #   is omitted.
   #   Bypasses the `CARemap` scatter layer for cases where an entity
   #   is wanted directly. Same dispatch (numeric / boolean / `CA_FIXLEN` /
   #   `CA_OBJECT`), same `kth` and `masked_position:` semantics.
   #   Masked input delegates to {#partition} + copy.
   #
+  #   A Face partitions in its surface order and comes back as the same
+  #   Face: one whose storage order is its surface order is selected on its
+  #   storage, a fixlen storage by byte order. A Face whose storage order is
+  #   not its surface order (e.g. {CACategorical}) raises.
+  #
   #   Float NaN policy: NaN cells are pre-partitioned to the tail. If
   #   `kth` falls within the finite slice, quickselect runs over the
   #   finite cells; otherwise the kth cell is already NaN.
   #
   #   @param kth [Integer]
-  #   @param axis [Integer]
+  #   @param axis [Integer, nil] `nil` partitions the whole array.
   #   @param masked_position [Symbol] `:last` (default) or `:first`.
   #   @return [CArray] fresh entity.
-  #   @raise [ArgumentError] same conditions as {#partition}.
-  def partition_copy(kth, axis: 0, masked_position: :last); end
+  #   @raise [ArgumentError] same conditions as {#partition}, or a Face that
+  #     is not orderable by its storage.
+  def partition_copy(kth, axis: nil, masked_position: :last); end
 
-  # @overload order(axis: nil, descending: false, method: :ordinal)
+  # @overload order(axis: nil, descending: false, method: :ordinal, kind: :quick)
   #   Returns each cell's rank among the other cells along `axis`
   #   (`0` = smallest). When `axis` is omitted, `self` is flattened
   #   first (global rank). Sugar over `rank_index` (built on the
@@ -105,9 +115,11 @@ class CArray
   #   @param axis [Integer, nil]
   #   @param descending [Boolean]
   #   @param method [Symbol] `:ordinal` (default) or `:dense`.
+  #   @param kind [Symbol] `:quick` (default) or `:stable`, as for
+  #     {#sort_index}; a performance choice only.
   #   @return [CArray] `:int64` ranks, shape == `self.shape`.
   #   @raise [ArgumentError] when `method:` is neither `:ordinal` nor `:dense`.
-  def order(axis: nil, descending: false, method: :ordinal); end
+  def order(axis: nil, descending: false, method: :ordinal, kind: :quick); end
 
   # @!endgroup
 
@@ -121,7 +133,7 @@ class CArray
   #   with `UNDEF` at positions where the value is not present.
   #   @param val [Numeric, CArray]
   #   @return [Integer, CArray, nil]
-  #   @raise [RuntimeError] if `self` has any masked element.
+  #   @raise [ArgumentError] if `self` has any masked element.
   # @overload bsearch(val, axis:)
   #   Per-fiber binary search along `axis`. Returns a CArray of
   #   axis-local positions, one per fiber.
@@ -148,6 +160,14 @@ class CArray
   #   to `val`. For float types, `eps` (default machine epsilon)
   #   sets the tolerance. Returns `nil` if no match.
   #
+  #   `val` is compared in the type both share, as `self.eq(val)`
+  #   compares: an integer array searched with a Float is compared in
+  #   float64 (so `3.9` does not match `3`, and `eps` applies), and an
+  #   Integer that does not fit an integer array raises `RangeError`.
+  #   The same holds for {#bsearch} and {#search_nearest}. On an
+  #   `:object` array a cell matches when it is `==` to `val`, as {#eq}
+  #   compares (so `1` matches `1.0`, which {#is_in} does not).
+  #
   #   `self` need not be sorted; this is a linear scan. For sorted
   #   data prefer {#bsearch}.
   #   @param val [Object]
@@ -206,7 +226,8 @@ class CArray
   #   bracketing samples. The integer part of the returned address is
   #   the index of the lower bracket, the fractional part is the
   #   interpolation weight toward the next sample. Out-of-range `val`
-  #   returns NaN.
+  #   returns NaN. A one-point axis has no segment: `val` equal to the
+  #   point is at 0, any other value is out of range.
   #
   #   `self` is coerced to `:float64` if it is not already. When
   #   `axis: nil`, `self` is flattened to 1-D first.

data/yard-stubs/carray_scatter.rb

@@ -19,10 +19,13 @@ class CArray
   #   `CA_SIZE`) or a Ruby Array.
   # - `vals` is a CArray of length matching `addrs` (coerced to
   #   `self.data_type`), or a Numeric scalar broadcast to all
-  #   addresses.
+  #   addresses. A complex `self` also takes a Complex scalar.
   # - Out-of-range `addrs[i]` (`< 0` or `>= self.elements`) raises
-  #   `IndexError`.
-  # - `self.data_type` must be numeric.
+  #   `IndexError`.  The pairs before it stay applied, through a view
+  #   as well.
+  # - `self.data_type` must be numeric. Complex is accepted by
+  #   every variant except {#scatter_min!} and {#scatter_max!},
+  #   since complex values have no order.
   #
   # Mask policy differs between the accumulate family and
   # {#scatter_replace!}: the accumulate variants skip the pair when
@@ -73,6 +76,8 @@ class CArray
   #   @param addrs [CArray, Array<Integer>]
   #   @param vals [CArray, Numeric]
   #   @return [self]
+  #   @raise [CArray::DataTypeError] for a non-numeric or complex
+  #     `data_type`.
   def scatter_min!(addrs, vals); end
 
   # @overload scatter_max!(addrs, vals)
@@ -82,6 +87,8 @@ class CArray
   #   @param addrs [CArray, Array<Integer>]
   #   @param vals [CArray, Numeric]
   #   @return [self]
+  #   @raise [CArray::DataTypeError] for a non-numeric or complex
+  #     `data_type`.
   def scatter_max!(addrs, vals); end
 
   # @overload scatter_replace!(addrs, vals)

data/yard-stubs/carray_segment.rb

@@ -0,0 +1,72 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_segment.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Index and address conversion
+  #
+  # A flat sequence cut into consecutive segments has three
+  # representations, and these methods convert between them:
+  #
+  #   lengths         [2, 0, 3]         one count per segment
+  #   offsets         [0, 2, 2, 5]      every boundary, both ends included
+  #   segment index   [0, 0, 2, 2, 2]   the segment each element is in
+  #
+  # Segment `c` spans `offsets[c]...offsets[c + 1]`, so there is no
+  # special case for the last segment and none for an empty one.
+  #
+  # Both methods compute in int64 and return int64, so a total beyond
+  # 2**53 stays exact. They accept a CArray of any integer or boolean
+  # data type (views included, read in flatten order) or an Array of
+  # Integers, and refuse masked cells: a masked length is not a count,
+  # and a masked offset is not a position.
+
+  # @overload segment_offsets(lengths:)
+  #   Returns the boundaries of segments with the given lengths: `0`
+  #   first, then the running total. `k` lengths give `k + 1` offsets,
+  #   so no lengths give `[0]`.
+  #
+  #     CArray.segment_offsets(lengths: [2, 0, 3])   # => [0, 2, 2, 5]
+  #
+  #   @param lengths [CArray, Array<Integer>] one count per segment.
+  #   @return [CArray] int64, one element more than `lengths`.
+  #   @raise [ArgumentError] for a negative length, a masked length,
+  #     or a non-Integer in an Array.
+  #   @raise [CArray::DataTypeError] for a non-integer data type.
+  #   @raise [RangeError] when the total overflows int64.
+  def self.segment_offsets(lengths:); end
+
+  # @overload segment_index(lengths:)
+  #   Returns, for each element of the cut sequence, the segment it
+  #   belongs to. A segment of length 0 contributes no elements, so
+  #   its number does not appear.
+  #
+  #     CArray.segment_index(lengths: [2, 0, 3])   # => [0, 0, 2, 2, 2]
+  #
+  #   The same as `CArray.int64(k).seq.repeat(lengths)`, as an owned
+  #   array rather than a view.
+  #   @param lengths [CArray, Array<Integer>] one count per segment.
+  #   @return [CArray] int64, `lengths.sum` elements.
+  #
+  # @overload segment_index(offsets:)
+  #   The same from boundaries. The offsets need not start at 0: the
+  #   offsets of a range cut out of a longer table start where that
+  #   range starts, and the result then covers
+  #   `offsets[0]...offsets[-1]` with the segments numbered from 0.
+  #
+  #     CArray.segment_index(offsets: [0, 2, 2, 5])   # => [0, 0, 2, 2, 2]
+  #     CArray.segment_index(offsets: [4, 6, 6, 9])   # => [0, 0, 2, 2, 2]
+  #
+  #   @param offsets [CArray, Array<Integer>] `k + 1` non-decreasing
+  #     boundaries.
+  #   @return [CArray] int64, `offsets[-1] - offsets[0]` elements.
+  #
+  # @raise [ArgumentError] for a negative length, decreasing or empty
+  #   offsets, a masked cell, a non-Integer in an Array, or unless
+  #   exactly one of `lengths:` and `offsets:` is given.
+  # @raise [CArray::DataTypeError] for a non-integer data type.
+  # @raise [RangeError] when the total length overflows int64.
+  def self.segment_index(lengths: nil, offsets: nil); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_slab.rb

@@ -28,7 +28,8 @@ class CArray
   #   Returns a new CArray built by replacing each slab of `self` with the
   #   block's result.  The block receives the slab view and must return a
   #   value of the same shape as the slab (a CArray or scalar); the results
-  #   are written into the output at the same positions.
+  #   are written into the output at the same positions, and a masked
+  #   cell of the block's result is masked in the output.
   #   @param axis [Integer, Array<Integer>, nil] the slab axis or axes.
   #   @param data_type [Symbol, Integer, Class, nil] output data type
   #     (defaults to `self`'s data type).

data/yard-stubs/carray_sort.rb

@@ -115,6 +115,43 @@ class CArray
   #     `:stable`.
   def sort_addr(axis: nil, kind: :quick, masked_position: :last); end
 
+  # @overload sort_index(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns, for each fiber along `axis`, the positions within the
+  #   fiber that put it in ascending order: `:int64`, shaped like
+  #   `self`. For a 1-D array, `a[a.sort_index]` is `a` sorted.
+  #
+  #   Without `axis:` (or with `axis: nil`) `self` is flattened and
+  #   treated as one fiber, as {#sort} does: the result is 1-D with
+  #   `self.elements` entries, and `a.flatten[a.sort_index]` is
+  #   `a.sort`.
+  #
+  #   The sort is **stable**: cells that compare equal keep their
+  #   input order, whichever `kind:` is chosen, so sorting by one key
+  #   and then stably by another orders by the second key first and
+  #   the first within it. `kind:` is a performance characteristic
+  #   only:
+  #
+  #   - `:quick` (default) — introsort with mergesort escape.
+  #   - `:stable` — bottom-up mergesort.
+  #
+  #   NaN and masked cells cannot be compared with the rest and are
+  #   placed at one end of each fiber: NaN after the numbers, masked
+  #   cells at the end `masked_position:` names (`:last`, default, or
+  #   `:first`). Relative order within the masked cells is unspecified.
+  #
+  #   Takes numeric data types, boolean, `CA_FIXLEN` (byte order),
+  #   `CA_OBJECT` (`<=>` per pair), and an ordered Face such as
+  #   `CATime`. Complex values have no order.
+  #   @param axis [Integer, nil] axis along which fibers run; negative
+  #     counts from the end. `nil` sorts the whole array.
+  #   @param kind [Symbol] `:quick` or `:stable`.
+  #   @param masked_position [Symbol] `:last` (default) or `:first`.
+  #   @return [CArray] `:int64` positions within each fiber.
+  #   @raise [ArgumentError] when `kind:` is neither `:quick` nor
+  #     `:stable`, or `axis` is out of range.
+  #   @raise [CArray::DataTypeError] for a complex `data_type`.
+  def sort_index(axis: nil, kind: :quick, masked_position: :last); end
+
   # @!group Index and address conversion
 
   # @overload axis2addr(indices, axis: 0)
@@ -147,15 +184,18 @@ class CArray
   #
   #   `indices` data_type: any integer kind (zero-copy when
   #   already `:int64`). Negative indices: Python-style
-  #   (`-1` == last). Out-of-range indices raise `RangeError`.
-  #   Negative `axis:` is Python-style.
+  #   (`-1` == last). Out-of-range indices raise `IndexError`.
+  #   Negative `axis:` is Python-style.  A masked index gives a
+  #   masked address (its stored value is not read), so
+  #   `take_along_axis` answers `UNDEF` there and `put_along_axis`
+  #   writes nothing there.
   #
   #   @param indices [CArray] integer-typed axis-local positions.
   #   @param axis [Integer] axis along which `indices` are
   #     interpreted.
   #   @return [CArray] `:int64` view-flat addresses, same shape as
   #     `indices`.
-  #   @raise [RangeError] when an index is out of range after
+  #   @raise [IndexError] when an index is out of range after
   #     negative normalization.
   #   @raise [ArgumentError] for shape / ndim / data_type
   #     violations.

data/yard-stubs/carray_test.rb

@@ -36,6 +36,13 @@ class CArray
   #   `data_class`, `data_type`, mask state, and elementwise values as
   #   `self`. NaN values compare unequal (IEEE semantics), so two
   #   arrays with NaN at the same position are not `==`.
+  #
+  #   A Face (a time, string or categorical array) equals only a Face of
+  #   its own class, and is compared by its values: two time arrays of
+  #   different units holding the same instants are `==`, as are two
+  #   categoricals with the same labels at each cell whatever the order
+  #   of their vocabularies. A Face is never `==` to an array that is not
+  #   one, even when the bytes match.
   #   @param other [Object]
   #   @return [Boolean]
   def ==(other); end
@@ -46,6 +53,9 @@ class CArray
   #   are compared bitwise (for numeric types) or via `Object#eql?`
   #   (for `:object` arrays). Unlike `==`, `NaN.eql?(NaN)` holds, so
   #   two mask-free arrays with NaN at the same positions are `eql?`.
+  #   Two Faces are `eql?` only when they are of the same class, share
+  #   their state (a time array's unit, a categorical's labels) and hold
+  #   the same storage.
   #
   #   Guarantees `a.eql?(b)` ⇒ `a.hash == b.hash`.
   #   @param other [Object]

data/yard-stubs/carray_utils.rb

@@ -67,31 +67,5 @@ class CArray
     def guess_type_and_bytes(type_spec, bytes = nil); end
 
     # @!endgroup
-
-    # @!group String scanning (internal)
-
-    # @overload _scan_float(str, fill_value = nil)
-    #   Parses `str` as a single double-precision float. Returns
-    #   `fill_value` (or `NaN` if `fill_value` is nil) when `str` is
-    #   `nil` or unparseable. Internal helper used by text-format I/O
-    #   readers; end users should prefer Ruby's `Float()` /
-    #   `String#to_f`.
-    #   @param str [String, nil]
-    #   @param fill_value [Float, nil]
-    #   @return [Float]
-    #   @api private
-    def _scan_float(str, fill_value = nil); end
-
-    # @overload _scan_int(str, fill_value = nil)
-    #   Parses `str` as a single integer. Returns `fill_value`
-    #   (or `0` if `fill_value` is nil) when `str` is `nil` or
-    #   unparseable. Internal helper used by text-format I/O readers.
-    #   @param str [String, nil]
-    #   @param fill_value [Integer, nil]
-    #   @return [Integer]
-    #   @api private
-    def _scan_int(str, fill_value = nil); end
-
-    # @!endgroup
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carray
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.0.3
 platform: ruby
 authors:
 - himotoyoshi
@@ -45,7 +45,6 @@ files:
 - ext/ca_composite_dispatch.c
 - ext/ca_composite_dispatch.h
 - ext/ca_for_buffer.h
-- ext/ca_for_each_element.h
 - ext/ca_group_iter.c
 - ext/ca_iter_substrate.h
 - ext/ca_kernel_iterator.c
@@ -96,6 +95,7 @@ files:
 - ext/ca_op_cmplx64.h
 - ext/ca_op_ipower.c
 - ext/ca_op_powi.h
+- ext/ca_pow5_table.h
 - ext/ca_rng_normal.h
 - ext/ca_rng_xoshiro256pp.h
 - ext/ca_sort_kernels.h
@@ -104,19 +104,18 @@ files:
 - ext/ca_transform_common.c
 - ext/ca_triop_dispatch.c
 - ext/ca_triop_dispatch.h
+- ext/caframe_csv_reader.c
 - ext/carray.h
 - ext/carray_access.c
 - ext/carray_address_basis.c
 - ext/carray_attribute.c
 - ext/carray_bincount.c
 - ext/carray_broadcast.c
-- ext/carray_build_flags.h
 - ext/carray_call_cfunc.c
 - ext/carray_call_cfunc.h
 - ext/carray_cast.c
 - ext/carray_cast_func.rb
 - ext/carray_class.c
-- ext/carray_config.h
 - ext/carray_conversion.c
 - ext/carray_copy.c
 - ext/carray_core.c
@@ -130,21 +129,6 @@ files:
 - ext/carray_index_classifier.c
 - ext/carray_index_classifier.h
 - ext/carray_internal.h
-- ext/carray_kernels_bincmp.c
-- ext/carray_kernels_binop.c
-- ext/carray_kernels_init.c
-- ext/carray_kernels_map.c
-- ext/carray_kernels_moncmp.c
-- ext/carray_kernels_monop.c
-- ext/carray_kernels_reduce_aggregate.c
-- ext/carray_kernels_reduce_boolean.c
-- ext/carray_kernels_reduce_cumulative.c
-- ext/carray_kernels_reduce_extreme.c
-- ext/carray_kernels_reduce_variance.c
-- ext/carray_kernels_scan.c
-- ext/carray_kernels_search.c
-- ext/carray_kernels_sort.c
-- ext/carray_kernels_triop.c
 - ext/carray_lazy.c
 - ext/carray_loop.c
 - ext/carray_mask.c
@@ -157,16 +141,19 @@ files:
 - ext/carray_partition.c
 - ext/carray_random.c
 - ext/carray_scatter.c
+- ext/carray_segment.c
 - ext/carray_slab.c
 - ext/carray_slab.h
 - ext/carray_sort.c
 - ext/carray_sort_kernel.c
 - ext/carray_struct.c
 - ext/carray_test.c
+- ext/carray_time_text.c
 - ext/carray_undef.c
 - ext/carray_utils.c
 - ext/extconf.rb
 - ext/mk_call_cfunc.rb
+- ext/mk_pow5_table.rb
 - ext/mkkernel.rb
 - ext/ruby_carray.c
 - ext/version.h
@@ -195,11 +182,13 @@ files:
 - lib/carray/frame/concat.rb
 - lib/carray/frame/convert.rb
 - lib/carray/frame/csv_parser.rb
+- lib/carray/frame/describe.rb
 - lib/carray/frame/frame.rb
 - lib/carray/frame/group.rb
 - lib/carray/frame/io.rb
 - lib/carray/frame/join.rb
 - lib/carray/frame/records.rb
+- lib/carray/frame/reshape.rb
 - lib/carray/frame/sort.rb
 - lib/carray/frame/verbs.rb
 - lib/carray/fuse_source.rb
@@ -237,8 +226,10 @@ files:
 - lib/carray/methods/unique.rb
 - lib/carray/methods/value_counts.rb
 - lib/carray/mkmf.rb
+- lib/carray/record_order.rb
 - lib/carray/rng.rb
 - lib/carray/runtime.rb
+- lib/carray/segment_iterator.rb
 - lib/carray/serialize.rb
 - lib/carray/slab_iterator.rb
 - lib/carray/stack.rb
@@ -286,6 +277,7 @@ files:
 - yard-stubs/carray_order.rb
 - yard-stubs/carray_random.rb
 - yard-stubs/carray_scatter.rb
+- yard-stubs/carray_segment.rb
 - yard-stubs/carray_slab.rb
 - yard-stubs/carray_sort.rb
 - yard-stubs/carray_test.rb