summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBurdette Lamar <BurdetteLamar@Yahoo.com>2021-10-18 18:35:06 -0500
committerGitHub <noreply@github.com>2021-10-18 18:35:06 -0500
commit012cafa5c7274ef50e6306cf5c3e09c2fb64f44d (patch)
tree6863df12d4e105d424301c5ac5c6e8ef97c7b340
parent8bc24438038e7beb92b5bd07e104b4077f32bb64 (diff)
Enhanced RDoc for numerics (#4982)
Treats: Numeric#coerce Numeric#clone Numeric#dup Numeric#@+ (unary plus) Numeric#i Float#coerce
Notes
Notes: Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
-rw-r--r--numeric.c90
1 files changed, 63 insertions, 27 deletions
diff --git a/numeric.c b/numeric.c
index 7f6a5f036c1..db2b2eb2793 100644
--- a/numeric.c
+++ b/numeric.c
@@ -387,19 +387,37 @@ num_funcall1(VALUE x, ID func, VALUE y)
/*
* call-seq:
- * num.coerce(numeric) -> array
+ * coerce(other) -> array
*
- * If +numeric+ is the same type as +num+, returns an array
- * <code>[numeric, num]</code>. Otherwise, returns an array with both
- * +numeric+ and +num+ represented as Float objects.
+ * Returns a 2-element array containing two numeric elements,
+ * formed from the two operands +self+ and +other+,
+ * of a common compatible type.
*
- * This coercion mechanism is used by Ruby to handle mixed-type numeric
- * operations: it is intended to find a compatible common type between the two
- * operands of the operator.
+ * Of the Core and Standard Library classes,
+ * Integer, Rational, and Complex use this implementation.
+ *
+ * Examples:
+ *
+ * i = 2 # => 2
+ * i.coerce(3) # => [3, 2]
+ * i.coerce(3.0) # => [3.0, 2.0]
+ * i.coerce(Rational(1, 2)) # => [0.5, 2.0]
+ * i.coerce(Complex(3, 4)) # Raises RangeError.
+ *
+ * r = Rational(5, 2) # => (5/2)
+ * r.coerce(2) # => [(2/1), (5/2)]
+ * r.coerce(2.0) # => [2.0, 2.5]
+ * r.coerce(Rational(2, 3)) # => [(2/3), (5/2)]
+ * r.coerce(Complex(3, 4)) # => [(3+4i), ((5/2)+0i)]
+ *
+ * c = Complex(2, 3) # => (2+3i)
+ * c.coerce(2) # => [(2+0i), (2+3i)]
+ * c.coerce(2.0) # => [(2.0+0i), (2+3i)]
+ * c.coerce(Rational(1, 2)) # => [((1/2)+0i), (2+3i)]
+ * c.coerce(Complex(3, 4)) # => [(3+4i), (2+3i)]
+ *
+ * Raises an exception if any type conversion fails.
*
- * 1.coerce(2.5) #=> [2.5, 1.0]
- * 1.2.coerce(3) #=> [3.0, 1.2]
- * 1.coerce(2) #=> [2, 1]
*/
static VALUE
@@ -509,9 +527,14 @@ num_sadded(VALUE x, VALUE name)
#if 0
/*
* call-seq:
- * num.clone(freeze: true) -> num
+ * clone(freeze: true) -> self
+ *
+ * Returns +self+.
+ *
+ * Raises an exception if the value for +freeze+ is neither +true+ nor +nil+.
+ *
+ * Related: Numeric#dup.
*
- * Returns the receiver. +freeze+ cannot be +false+.
*/
static VALUE
num_clone(int argc, VALUE *argv, VALUE x)
@@ -525,9 +548,12 @@ num_clone(int argc, VALUE *argv, VALUE x)
#if 0
/*
* call-seq:
- * num.dup -> num
+ * dup -> self
+ *
+ * Returns +self+.
+ *
+ * Related: Numeric#clone.
*
- * Returns the receiver.
*/
static VALUE
num_dup(VALUE x)
@@ -540,9 +566,10 @@ num_dup(VALUE x)
/*
* call-seq:
- * +num -> num
+ * +num -> self
+ *
+ * Returns +self+.
*
- * Unary Plus---Returns the receiver.
*/
static VALUE
@@ -553,13 +580,16 @@ num_uplus(VALUE num)
/*
* call-seq:
- * num.i -> Complex(0, num)
+ * i -> complex
+ *
+ * Returns <tt>Complex(0, self)</tt>:
*
- * Returns the corresponding imaginary number.
- * Not available for complex numbers.
+ * 2.i # => (0+2i)
+ * -2.i # => (0-2i)
+ * 2.0.i # => (0+2.0i)
+ * Rational(1, 2).i # => (0+(1/2)*i)
+ * Complex(3, 4).i # Raises NoMethodError.
*
- * -42.i #=> (0-42i)
- * 2.0.i #=> (0+2.0i)
*/
static VALUE
@@ -985,15 +1015,21 @@ flo_to_s(VALUE flt)
/*
* call-seq:
- * float.coerce(numeric) -> array
+ * coerce(other) -> array
+ *
+ * Returns a 2-element array containing +other+ converted to a \Float
+ * and +self+:
+ *
+ * f = 3.14 # => 3.14
+ * f.coerce(2) # => [2.0, 3.14]
+ * f.coerce(2.0) # => [2.0, 3.14]
+ * f.coerce(Rational(1, 2)) # => [0.5, 3.14]
+ * f.coerce(Complex(3, 4)) # Raises RangeError.
*
- * Returns an array with both +numeric+ and +float+ represented as Float
- * objects.
+ * Related: Numeric#coerce (for other numeric types).
*
- * This is achieved by converting +numeric+ to a Float.
+ * Raises an exception if a type conversion fails.
*
- * 1.2.coerce(3) #=> [3.0, 1.2]
- * 2.5.coerce(1.1) #=> [1.1, 2.5]
*/
static VALUE