carray 3.0.4 → 3.0.5

data/yard-stubs/carray_math.rb

@@ -11,6 +11,11 @@
 # builds a node in the expression tree instead of evaluating, and the
 # eager and lazy paths are required to agree element for element.
 #
+# The transcendental functions call the platform's C math library, so
+# their last bits, and the complex functions' answers at special values
+# (signed zeros, infinities, NaN), follow that library and can differ
+# between operating systems.
+#
 # See yard-stubs/README.md and yard-stubs/STYLE.md.
 
 class CArray
@@ -598,6 +603,8 @@ class CArray
   #   Returns each element of `self` with the magnitude it already has
   #   and the sign of the matching element of `other`. The sign of a
   #   zero is respected, so `copysign` distinguishes `-0.0` from `0.0`.
+  #   The sign of a NaN that a computation produced (`sqrt(-1)`,
+  #   `Inf * 0`) depends on the CPU: x86 sets it, ARM does not.
   #   Accepts float and `:object` arrays only, as {#atan2}.
   #   @param other [CArray, Numeric] sign source, broadcast to
   #     `self.shape`.
@@ -683,8 +690,8 @@ class CArray
   # @overload pmax(other)
   #   Returns the element-wise larger of `self` and `other`, ignoring
   #   `NaN`: where one element is `NaN` the other is returned, and only
-  #   two `NaN`s give `NaN`. This is C's `fmax`. For the form that lets
-  #   a `NaN` win see {#maximum}.
+  #   two `NaN`s give `NaN`. Of `-0.0` and `0.0` the result is `0.0`,
+  #   in either order. For the form that lets a `NaN` win see {#maximum}.
   #   @param other [CArray, Numeric] the other operand, broadcast to
   #     `self.shape`.
   #   @return [CArray] result of the promoted `data_type` of the two
@@ -697,7 +704,8 @@ class CArray
 
   # @overload pmin(other)
   #   Returns the element-wise smaller of `self` and `other`, ignoring
-  #   `NaN`. The counterpart of {#pmax}.
+  #   `NaN`. Of `-0.0` and `0.0` the result is `-0.0`, in either order.
+  #   The counterpart of {#pmax}.
   #   @param other [CArray, Numeric] the other operand.
   #   @return [CArray]
   #   @raise [CArray::DataTypeError] for a complex array.
@@ -929,7 +937,9 @@ class CArray
   # @overload signbit
   #   Returns a boolean array that is true where an element carries a
   #   negative sign bit. A negative zero is true, which distinguishes
-  #   `-0.0` from `0.0` where a `< 0` comparison cannot.
+  #   `-0.0` from `0.0` where a `< 0` comparison cannot. On a NaN that a
+  #   computation produced (`sqrt(-1)`, `Inf * 0`) the answer depends on
+  #   the CPU: x86 sets the sign bit, ARM does not.
   #   @return [CArray] `:boolean`.
   #   @raise [CArray::DataTypeError] for a complex array.
   #   @example

data/yard-stubs/carray_order.rb

@@ -128,7 +128,8 @@ class CArray
 
   # @overload bsearch(val)
   #   Returns the flat address of `val` in `self` via binary search.
-  #   `self` must be sorted along its single (flat) axis. Returns
+  #   `self` must be sorted along its single (flat) axis. Of several
+  #   equal cells, the first one's address is returned. Returns
   #   `nil` if `val` is not present. When `val` is a CArray, returns
   #   a CArray of `:int64` addresses (one per element of `val`),
   #   with `UNDEF` at positions where the value is not present.
@@ -159,7 +160,8 @@ class CArray
   # @overload search(val, eps = nil)
   #   Returns the flat address of the first element of `self` equal
   #   to `val`. For float types, `eps` (default machine epsilon)
-  #   sets the tolerance. Returns `nil` if no match.
+  #   sets the tolerance; a negative or NaN `eps` raises
+  #   `ArgumentError`. 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
@@ -201,7 +203,10 @@ class CArray
 
   # @overload search_nearest(val)
   #   Returns the flat address of the element of `self` whose value
-  #   is closest to `val`.
+  #   is closest to `val`. Of several equally close elements, the one
+  #   at the lowest address wins, as {#search} answers the first match
+  #   (`[0, 2, 4].search_nearest(1)` is 0). {#locate_nearest_addr}
+  #   rounds a position instead, and answers the larger value on a tie.
   #
   #   In an `:object` array the distance is `val.distance(other)` when
   #   `val` answers `#distance`, and `(val - other).abs` when it is a
@@ -268,7 +273,9 @@ class CArray
   #   `self` is coerced to `:float64` if it is not already. When
   #   `axis: nil`, `self` is flattened to 1-D first.
   #
-  #   Out-of-range `addr` returns NaN.
+  #   A position with no answer -- out of range, or between samples one
+  #   of which is NaN -- gives `nil` for a scalar `addr` and NaN in the
+  #   cell of an array result.
   #
   #   Because this half of the pair returns a *value* rather than a
   #   position, a Face axis gets its Face back: `CATime#linear_fetch` /
@@ -280,5 +287,94 @@ class CArray
   #   @see file:docs/topics/LinearInterpolation.md
   def linear_fetch(addr, axis: nil); end
 
+  # @overload nlargest(n, axis: nil)
+  #   Returns the `n` largest values, largest first. Without `axis:` the
+  #   array is read flat; with it, each fiber along `axis` gives its own
+  #   `n` and the axis keeps length `n`. A NaN and a masked cell lose to
+  #   every value; when fewer cells remain than `n`, the result is
+  #   shorter (or, per fiber, ends in UNDEF).
+  #   @param n [Integer] how many values, 0 or more.
+  #   @param axis [Integer, nil]
+  #   @return [CArray]
+  #   @raise [ArgumentError] when `n` is negative.
+  def nlargest(n, axis: nil); end
+
+  # @overload nsmallest(n, axis: nil)
+  #   Returns the `n` smallest values, smallest first. As {#nlargest}
+  #   otherwise.
+  #   @param n [Integer]
+  #   @param axis [Integer, nil]
+  #   @return [CArray]
+  #   @raise [ArgumentError] when `n` is negative.
+  def nsmallest(n, axis: nil); end
+
+  # @overload nlargest_index(n, axis:)
+  #   Returns, along `axis`, the axis-local positions of each fiber's `n`
+  #   largest values, largest first (`take_along_axis` reads the values
+  #   back). `axis:` is required.
+  #   @param n [Integer]
+  #   @param axis [Integer]
+  #   @return [CArray] `:int64` positions.
+  #   @raise [ArgumentError] when `axis:` is missing or `n` is negative.
+  def nlargest_index(n, axis:); end
+
+  # @overload nsmallest_index(n, axis:)
+  #   As {#nlargest_index}, for the `n` smallest values.
+  #   @param n [Integer]
+  #   @param axis [Integer]
+  #   @return [CArray] `:int64` positions.
+  #   @raise [ArgumentError] when `axis:` is missing or `n` is negative.
+  def nsmallest_index(n, axis:); end
+
+  # @overload sort_by_key(key, axis: 0)
+  #   Returns `self` reordered along `axis` by the order of `key` (an
+  #   array of `self`'s shape): `self[key.sort_addr(axis:)]`.
+  #   @param key [CArray] the values to order by.
+  #   @param axis [Integer]
+  #   @return [CArray]
+  #   @raise [ArgumentError] when `key`'s shape differs from `self`'s.
+  def sort_by_key(key, axis: 0); end
+
+  # @overload max_by_key(key, axis: nil)
+  #   Returns the value of `self` where `key` is largest: one value, or
+  #   one per fiber along `axis`. UNDEF where there is no cell to compare.
+  #   @param key [CArray] the values to compare, of `self`'s shape.
+  #   @param axis [Integer, nil]
+  #   @return [Object, CArray]
+  #   @raise [ArgumentError] when `key`'s shape differs from `self`'s.
+  def max_by_key(key, axis: nil); end
+
+  # @overload min_by_key(key, axis: nil)
+  #   As {#max_by_key}, where `key` is smallest.
+  #   @param key [CArray]
+  #   @param axis [Integer, nil]
+  #   @return [Object, CArray]
+  #   @raise [ArgumentError] when `key`'s shape differs from `self`'s.
+  def min_by_key(key, axis: nil); end
+
+  # @overload take_along_axis(indices, axis: 0)
+  #   Returns the values of `self` at axis-local `indices` along `axis`
+  #   (`indices` has `self`'s shape except along `axis`), as the
+  #   `*_index(axis:)` methods answer them. A masked index reads UNDEF.
+  #   @param indices [CArray] integer positions along `axis`.
+  #   @param axis [Integer]
+  #   @return [CArray]
+  def take_along_axis(indices, axis: 0); end
+
+  # @overload put_along_axis(indices, values, axis: 0)
+  #   Writes `values` into `self` at axis-local `indices` along `axis`,
+  #   the inverse of {#take_along_axis}. A masked index writes nothing.
+  #   @param indices [CArray] integer positions along `axis`.
+  #   @param values [CArray, Object]
+  #   @param axis [Integer]
+  #   @return [self]
+  def put_along_axis(indices, values, axis: 0); end
+
+  # @overload range
+  #   Returns `min..max` of `self` from one pass (`UNDEF..UNDEF` when no
+  #   cell takes part).
+  #   @return [Range]
+  def range; end
+
   # @!endgroup
 end

data/yard-stubs/carray_scatter.rb

@@ -104,13 +104,15 @@ class CArray
   #   allocates view state); useful in hot loops where a scatter
   #   result is written back many times.
   #
-  #   Unlike the arithmetic `scatter_*!` family, `self` may be
-  #   **boolean** (assignment does not widen); `true` / `false` (or
-  #   `1` / `0`) are its scalar values. A scalar `UNDEF` masks every
-  #   addressed cell.
+  #   Unlike the arithmetic `scatter_*!` family, `self` may be of any
+  #   type (assignment does not widen): **boolean**, with `true` /
+  #   `false` (or `1` / `0`) as its scalar values, and **object** or
+  #   **fixlen**, written as `self.flatten[addrs] = vals` writes them
+  #   (as `put_nd` and `put_along_axis` take them). A scalar `UNDEF`
+  #   masks every addressed cell.
   #
   #   @param addrs [CArray, Array<Integer>]
-  #   @param vals [CArray, Numeric, true, false, UNDEF]
+  #   @param vals [CArray, Object, UNDEF]
   #   @return [self]
   def scatter_replace!(addrs, vals); end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carray
 version: !ruby/object:Gem::Version
-  version: 3.0.4
+  version: 3.0.5
 platform: ruby
 authors:
 - himotoyoshi