class Numeric
Numeric is the class from which all higher-level numeric classes should inherit.
Numeric allows instantiation of heap-allocated objects. Other core numeric classes such as Integer
are implemented as immediates, which means that each Integer
is a single immutable object which is always passed by value.
a = 1 1.object_id == a.object_id #=> true
There can only ever be one instance of the integer 1
, for example. Ruby ensures this by preventing instantiation. If duplication is attempted, the same instance is returned.
Integer.new(1) #=> NoMethodError: undefined method `new' for Integer:Class 1.dup #=> 1 1.object_id == 1.dup.object_id #=> true
For this reason, Numeric should be used when defining other numeric classes.
Classes which inherit from Numeric must implement coerce
, which returns a two-member Array
containing an object that has been coerced into an instance of the new class and self
(see coerce
).
Inheriting classes should also implement arithmetic operator methods (+
, -
, *
and /
) and the <=>
operator (see Comparable
). These methods may rely on coerce
to ensure interoperability with instances of other numeric classes.
class Tally < Numeric def initialize(string) @string = string end def to_s @string end def to_i @string.size end def coerce(other) [self.class.new('|' * other.to_i), self] end def <=>(other) to_i <=> other.to_i end def +(other) self.class.new('|' * (to_i + other.to_i)) end def -(other) self.class.new('|' * (to_i - other.to_i)) end def *(other) self.class.new('|' * (to_i * other.to_i)) end def /(other) self.class.new('|' * (to_i / other.to_i)) end end tally = Tally.new('||') puts tally * 2 #=> "||||" puts tally > 1 #=> true
What’s Here¶ ↑
First, what’s elsewhere. Class Numeric:
-
Inherits from class Object.
-
Includes module Comparable.
Here, class Numeric provides methods for:
Querying¶ ↑
-
finite?
: Returns true unlessself
is infinite or not a number. -
infinite?
: Returns -1,nil
or +1, depending on whetherself
is-Infinity<tt>, finite, or <tt>+Infinity
. -
integer?
: Returns whetherself
is an integer. -
negative?
: Returns whetherself
is negative. -
nonzero?
: Returns whetherself
is not zero. -
positive?
: Returns whetherself
is positive. -
real?
: Returns whetherself
is a real value. -
zero?
: Returns whetherself
is zero.
Comparing¶ ↑
-
#<=>: Returns:
-
-1 if
self
is less than the given value. -
0 if
self
is equal to the given value. -
1 if
self
is greater than the given value. -
nil
ifself
and the given value are not comparable.
-
-
eql?
: Returns whetherself
and the given value have the same value and type.
Converting¶ ↑
-
%
(aliased asmodulo
): Returns the remainder ofself
divided by the given value. -
-@
: Returns the value ofself
, negated. -
abs
(aliased asmagnitude
): Returns the absolute value ofself
. -
abs2
: Returns the square ofself
. -
angle
(aliased asarg
andphase
): Returns 0 ifself
is positive, Math::PI otherwise. -
ceil
: Returns the smallest number greater than or equal toself
, to a given precision. -
coerce
: Returns array[coerced_self, coerced_other]
for the given other value. -
conj
(aliased asconjugate
): Returns the complex conjugate ofself
. -
denominator
: Returns the denominator (always positive) of theRational
representation ofself
. -
div
: Returns the value ofself
divided by the given value and converted to an integer. -
divmod
: Returns array[quotient, modulus]
resulting from dividingself
the given divisor. -
fdiv
: Returns theFloat
result of dividingself
by the given divisor. -
floor
: Returns the largest number less than or equal toself
, to a given precision. -
i
: Returns theComplex
objectComplex(0, self)
. the given value. -
imaginary
(aliased asimag
): Returns the imaginary part of theself
. -
numerator
: Returns the numerator of theRational
representation ofself
; has the same sign asself
. -
polar
: Returns the array[self.abs, self.arg]
. -
quo
: Returns the value ofself
divided by the given value. -
real
: Returns the real part ofself
. -
rect
(aliased asrectangular
): Returns the array[self, 0]
. -
remainder
: Returnsself-arg*(self/arg).truncate
for the givenarg
. -
round
: Returns the value ofself
rounded to the nearest value for the given a precision. -
to_int
: Returns theInteger
representation ofself
, truncating if necessary. -
truncate
: Returnsself
truncated (toward zero) to a given precision.
Other¶ ↑
Public Instance Methods
Returns self
modulo other
as a real number.
Of the Core and Standard Library classes, only Rational
uses this implementation.
For Rational
r
and real number n
, these expressions are equivalent:
r % n r-n*(r/n).floor r.divmod(n)[1]
See Numeric#divmod
.
Examples:
r = Rational(1, 2) # => (1/2) r2 = Rational(2, 3) # => (2/3) r % r2 # => (1/2) r % 2 # => (1/2) r % 2.0 # => 0.5 r = Rational(301,100) # => (301/100) r2 = Rational(7,5) # => (7/5) r % r2 # => (21/100) r % -r2 # => (-119/100) (-r) % r2 # => (119/100) (-r) %-r2 # => (-21/100)
static VALUE num_modulo(VALUE x, VALUE y) { VALUE q = num_funcall1(x, id_div, y); return rb_funcall(x, '-', 1, rb_funcall(y, '*', 1, q)); }
Returns self
.
static VALUE num_uplus(VALUE num) { return num; }
Unary Minus—Returns the receiver, negated.
static VALUE num_uminus(VALUE num) { VALUE zero; zero = INT2FIX(0); do_coerce(&zero, &num, TRUE); return num_funcall1(zero, '-', num); }
Returns zero if self
is the same as other
, nil
otherwise.
No subclass in the Ruby Core or Standard Library uses this implementation.
static VALUE num_cmp(VALUE x, VALUE y) { if (x == y) return INT2FIX(0); return Qnil; }
Returns the absolute value of self
.
12.abs #=> 12 (-34.56).abs #=> 34.56 -34.56.abs #=> 34.56
static VALUE num_abs(VALUE num) { if (rb_num_negative_int_p(num)) { return num_funcall0(num, idUMinus); } return num; }
Returns the square of self
.
static VALUE numeric_abs2(VALUE self) { return f_mul(self, self); }
Returns zero if self
is positive, Math::PI otherwise.
static VALUE numeric_arg(VALUE self) { if (f_positive_p(self)) return INT2FIX(0); return DBL2NUM(M_PI); }
Returns the smallest number that is greater than or equal to self
with a precision of digits
decimal digits.
Numeric implements this by converting self
to a Float
and invoking Float#ceil
.
static VALUE num_ceil(int argc, VALUE *argv, VALUE num) { return flo_ceil(argc, argv, rb_Float(num)); }
Returns self
.
Raises an exception if the value for freeze
is neither true
nor nil
.
Related: Numeric#dup
.
static VALUE num_clone(int argc, VALUE *argv, VALUE x) { return rb_immutable_obj_clone(argc, argv, x); }
Returns a 2-element array containing two numeric elements, formed from the two operands self
and other
, of a common compatible type.
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.
static VALUE num_coerce(VALUE x, VALUE y) { if (CLASS_OF(x) == CLASS_OF(y)) return rb_assoc_new(y, x); x = rb_Float(x); y = rb_Float(y); return rb_assoc_new(y, x); }
Returns self
.
# File ruby_3_3_5/numeric.rb, line 68 def conjugate self end
Returns the denominator (always positive).
static VALUE numeric_denominator(VALUE self) { return f_denominator(f_to_r(self)); }
Returns the quotient self/other
as an integer (via floor
), using method /
in the derived class of self
. (Numeric itself does not define method /
.)
Of the Core and Standard Library classes, Only Float
and Rational
use this implementation.
static VALUE num_div(VALUE x, VALUE y) { if (rb_equal(INT2FIX(0), y)) rb_num_zerodiv(); return rb_funcall(num_funcall1(x, '/', y), rb_intern("floor"), 0); }
Returns a 2-element array [q, r]
, where
q = (self/other).floor # Quotient r = self % other # Remainder
Of the Core and Standard Library classes, only Rational
uses this implementation.
Examples:
Rational(11, 1).divmod(4) # => [2, (3/1)] Rational(11, 1).divmod(-4) # => [-3, (-1/1)] Rational(-11, 1).divmod(4) # => [-3, (1/1)] Rational(-11, 1).divmod(-4) # => [2, (-3/1)] Rational(12, 1).divmod(4) # => [3, (0/1)] Rational(12, 1).divmod(-4) # => [-3, (0/1)] Rational(-12, 1).divmod(4) # => [-3, (0/1)] Rational(-12, 1).divmod(-4) # => [3, (0/1)] Rational(13, 1).divmod(4.0) # => [3, 1.0] Rational(13, 1).divmod(Rational(4, 11)) # => [35, (3/11)]
static VALUE num_divmod(VALUE x, VALUE y) { return rb_assoc_new(num_div(x, y), num_modulo(x, y)); }
Returns true
if self
and other
are the same type and have equal values.
Of the Core and Standard Library classes, only Integer
, Rational
, and Complex
use this implementation.
Examples:
1.eql?(1) # => true 1.eql?(1.0) # => false 1.eql?(Rational(1, 1)) # => false 1.eql?(Complex(1, 0)) # => false
Method eql?
is different from +==+ in that eql?
requires matching types, while +==+ does not.
static VALUE num_eql(VALUE x, VALUE y) { if (TYPE(x) != TYPE(y)) return Qfalse; if (RB_BIGNUM_TYPE_P(x)) { return rb_big_eql(x, y); } return rb_equal(x, y); }
Returns the quotient self/other
as a float, using method /
in the derived class of self
. (Numeric itself does not define method /
.)
Of the Core and Standard Library classes, only BigDecimal uses this implementation.
static VALUE num_fdiv(VALUE x, VALUE y) { return rb_funcall(rb_Float(x), '/', 1, y); }
Returns true
if self
is a finite number, false
otherwise.
# File ruby_3_3_5/numeric.rb, line 38 def finite? true end
Returns the largest number that is less than or equal to self
with a precision of digits
decimal digits.
Numeric implements this by converting self
to a Float
and invoking Float#floor
.
static VALUE num_floor(int argc, VALUE *argv, VALUE num) { return flo_floor(argc, argv, rb_Float(num)); }
Returns Complex(0, self)
:
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.
static VALUE num_imaginary(VALUE num) { return rb_complex_new(INT2FIX(0), num); }
Returns zero.
# File ruby_3_3_5/numeric.rb, line 57 def imaginary 0 end
Returns nil
, -1, or 1 depending on whether self
is finite, -Infinity
, or +Infinity
.
# File ruby_3_3_5/numeric.rb, line 48 def infinite? nil end
Returns true
if self
is an Integer
.
1.0.integer? # => false 1.integer? # => true
# File ruby_3_3_5/numeric.rb, line 29 def integer? false end
Returns the absolute value of self
.
12.abs #=> 12 (-34.56).abs #=> 34.56 -34.56.abs #=> 34.56
Returns self
modulo other
as a real number.
Of the Core and Standard Library classes, only Rational
uses this implementation.
For Rational
r
and real number n
, these expressions are equivalent:
r % n r-n*(r/n).floor r.divmod(n)[1]
See Numeric#divmod
.
Examples:
r = Rational(1, 2) # => (1/2) r2 = Rational(2, 3) # => (2/3) r % r2 # => (1/2) r % 2 # => (1/2) r % 2.0 # => 0.5 r = Rational(301,100) # => (301/100) r2 = Rational(7,5) # => (7/5) r % r2 # => (21/100) r % -r2 # => (-119/100) (-r) % r2 # => (119/100) (-r) %-r2 # => (-21/100)
Returns true
if self
is less than 0, false
otherwise.
static VALUE num_negative_p(VALUE num) { return RBOOL(rb_num_negative_int_p(num)); }
Returns self
if self
is not a zero value, nil
otherwise; uses method zero?
for the evaluation.
The returned self
allows the method to be chained:
a = %w[z Bb bB bb BB a aA Aa AA A] a.sort {|a, b| (a.downcase <=> b.downcase).nonzero? || a <=> b } # => ["A", "a", "AA", "Aa", "aA", "BB", "Bb", "bB", "bb", "z"]
Of the Core and Standard Library classes, Integer
, Float
, Rational
, and Complex
use this implementation.
static VALUE num_nonzero_p(VALUE num) { if (RTEST(num_funcall0(num, rb_intern("zero?")))) { return Qnil; } return num; }
Returns the numerator.
static VALUE numeric_numerator(VALUE self) { return f_numerator(f_to_r(self)); }
Returns array [self.abs, self.arg]
.
static VALUE numeric_polar(VALUE self) { VALUE abs, arg; if (RB_INTEGER_TYPE_P(self)) { abs = rb_int_abs(self); arg = numeric_arg(self); } else if (RB_FLOAT_TYPE_P(self)) { abs = rb_float_abs(self); arg = float_arg(self); } else if (RB_TYPE_P(self, T_RATIONAL)) { abs = rb_rational_abs(self); arg = numeric_arg(self); } else { abs = f_abs(self); arg = f_arg(self); } return rb_assoc_new(abs, arg); }
Returns true
if self
is greater than 0, false
otherwise.
static VALUE num_positive_p(VALUE num) { const ID mid = '>'; if (FIXNUM_P(num)) { if (method_basic_p(rb_cInteger)) return RBOOL((SIGNED_VALUE)num > (SIGNED_VALUE)INT2FIX(0)); } else if (RB_BIGNUM_TYPE_P(num)) { if (method_basic_p(rb_cInteger)) return RBOOL(BIGNUM_POSITIVE_P(num) && !rb_bigzero_p(num)); } return rb_num_compare_with_zero(num, mid); }
Returns the most exact division (rational for integers, float for floats).
VALUE rb_numeric_quo(VALUE x, VALUE y) { if (RB_TYPE_P(x, T_COMPLEX)) { return rb_complex_div(x, y); } if (RB_FLOAT_TYPE_P(y)) { return rb_funcallv(x, idFdiv, 1, &y); } x = rb_convert_type(x, T_RATIONAL, "Rational", "to_r"); return rb_rational_div(x, y); }
Returns self
.
# File ruby_3_3_5/numeric.rb, line 17 def real self end
Returns true
if self
is a real number (i.e. not Complex
).
# File ruby_3_3_5/numeric.rb, line 8 def real? true end
Returns array [self, 0]
.
static VALUE numeric_rect(VALUE self) { return rb_assoc_new(self, INT2FIX(0)); }
Returns the remainder after dividing self
by other
.
Of the Core and Standard Library classes, only Float
and Rational
use this implementation.
Examples:
11.0.remainder(4) # => 3.0 11.0.remainder(-4) # => 3.0 -11.0.remainder(4) # => -3.0 -11.0.remainder(-4) # => -3.0 12.0.remainder(4) # => 0.0 12.0.remainder(-4) # => 0.0 -12.0.remainder(4) # => -0.0 -12.0.remainder(-4) # => -0.0 13.0.remainder(4.0) # => 1.0 13.0.remainder(Rational(4, 1)) # => 1.0 Rational(13, 1).remainder(4) # => (1/1) Rational(13, 1).remainder(-4) # => (1/1) Rational(-13, 1).remainder(4) # => (-1/1) Rational(-13, 1).remainder(-4) # => (-1/1)
static VALUE num_remainder(VALUE x, VALUE y) { if (!rb_obj_is_kind_of(y, rb_cNumeric)) { do_coerce(&x, &y, TRUE); } VALUE z = num_funcall1(x, '%', y); if ((!rb_equal(z, INT2FIX(0))) && ((rb_num_negative_int_p(x) && rb_num_positive_int_p(y)) || (rb_num_positive_int_p(x) && rb_num_negative_int_p(y)))) { if (RB_FLOAT_TYPE_P(y)) { if (isinf(RFLOAT_VALUE(y))) { return x; } } return rb_funcall(z, '-', 1, y); } return z; }
Returns self
rounded to the nearest value with a precision of digits
decimal digits.
Numeric implements this by converting self
to a Float
and invoking Float#round
.
static VALUE num_round(int argc, VALUE* argv, VALUE num) { return flo_round(argc, argv, rb_Float(num)); }
Generates a sequence of numbers; with a block given, traverses the sequence. Of the Core and Standard Library classes, Integer, Float, and Rational use this implementation. A quick example: squares = [] 1.step(by: 2, to: 10) {|i| squares.push(i*i) } squares # => [1, 9, 25, 49, 81] The generated sequence: - Begins with +self+. - Continues at intervals of +by+ (which may not be zero). - Ends with the last number that is within or equal to +to+; that is, less than or equal to +to+ if +by+ is positive, greater than or equal to +to+ if +by+ is negative. If +to+ is +nil+, the sequence is of infinite length. If a block is given, calls the block with each number in the sequence; returns +self+. If no block is given, returns an Enumerator::ArithmeticSequence. <b>Keyword Arguments</b> With keyword arguments +by+ and +to+, their values (or defaults) determine the step and limit: # Both keywords given. squares = [] 4.step(by: 2, to: 10) {|i| squares.push(i*i) } # => 4 squares # => [16, 36, 64, 100] cubes = [] 3.step(by: -1.5, to: -3) {|i| cubes.push(i*i*i) } # => 3 cubes # => [27.0, 3.375, 0.0, -3.375, -27.0] squares = [] 1.2.step(by: 0.2, to: 2.0) {|f| squares.push(f*f) } squares # => [1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0] squares = [] Rational(6/5).step(by: 0.2, to: 2.0) {|r| squares.push(r*r) } squares # => [1.0, 1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0] # Only keyword to given. squares = [] 4.step(to: 10) {|i| squares.push(i*i) } # => 4 squares # => [16, 25, 36, 49, 64, 81, 100] # Only by given. # Only keyword by given squares = [] 4.step(by:2) {|i| squares.push(i*i); break if i > 10 } squares # => [16, 36, 64, 100, 144] # No block given. e = 3.step(by: -1.5, to: -3) # => (3.step(by: -1.5, to: -3)) e.class # => Enumerator::ArithmeticSequence <b>Positional Arguments</b> With optional positional arguments +to+ and +by+, their values (or defaults) determine the step and limit: squares = [] 4.step(10, 2) {|i| squares.push(i*i) } # => 4 squares # => [16, 36, 64, 100] squares = [] 4.step(10) {|i| squares.push(i*i) } squares # => [16, 25, 36, 49, 64, 81, 100] squares = [] 4.step {|i| squares.push(i*i); break if i > 10 } # => nil squares # => [16, 25, 36, 49, 64, 81, 100, 121]
Implementation Notes
If all the arguments are integers, the loop operates using an integer counter. If any of the arguments are floating point numbers, all are converted to floats, and the loop is executed <i>floor(n + n*Float::EPSILON) + 1</i> times, where <i>n = (limit - self)/step</i>.
static VALUE num_step(int argc, VALUE *argv, VALUE from) { VALUE to, step; int desc, inf; if (!rb_block_given_p()) { VALUE by = Qundef; num_step_extract_args(argc, argv, &to, &step, &by); if (!UNDEF_P(by)) { step = by; } if (NIL_P(step)) { step = INT2FIX(1); } else if (rb_equal(step, INT2FIX(0))) { rb_raise(rb_eArgError, "step can't be 0"); } if ((NIL_P(to) || rb_obj_is_kind_of(to, rb_cNumeric)) && rb_obj_is_kind_of(step, rb_cNumeric)) { return rb_arith_seq_new(from, ID2SYM(rb_frame_this_func()), argc, argv, num_step_size, from, to, step, FALSE); } return SIZED_ENUMERATOR_KW(from, 2, ((VALUE [2]){to, step}), num_step_size, FALSE); } desc = num_step_scan_args(argc, argv, &to, &step, TRUE, FALSE); if (rb_equal(step, INT2FIX(0))) { inf = 1; } else if (RB_FLOAT_TYPE_P(to)) { double f = RFLOAT_VALUE(to); inf = isinf(f) && (signbit(f) ? desc : !desc); } else inf = 0; if (FIXNUM_P(from) && (inf || FIXNUM_P(to)) && FIXNUM_P(step)) { long i = FIX2LONG(from); long diff = FIX2LONG(step); if (inf) { for (;; i += diff) rb_yield(LONG2FIX(i)); } else { long end = FIX2LONG(to); if (desc) { for (; i >= end; i += diff) rb_yield(LONG2FIX(i)); } else { for (; i <= end; i += diff) rb_yield(LONG2FIX(i)); } } } else if (!ruby_float_step(from, to, step, FALSE, FALSE)) { VALUE i = from; if (inf) { for (;; i = rb_funcall(i, '+', 1, step)) rb_yield(i); } else { ID cmp = desc ? '<' : '>'; for (; !RTEST(rb_funcall(i, cmp, 1, to)); i = rb_funcall(i, '+', 1, step)) rb_yield(i); } } return from; }
Returns self
as a Complex
object.
static VALUE numeric_to_c(VALUE self) { return rb_complex_new1(self); }
Returns self
as an integer; converts using method to_i
in the derived class.
Of the Core and Standard Library classes, only Rational
and Complex
use this implementation.
Examples:
Rational(1, 2).to_int # => 0 Rational(2, 1).to_int # => 2 Complex(2, 0).to_int # => 2 Complex(2, 1) # Raises RangeError (non-zero imaginary part)
static VALUE num_to_int(VALUE num) { return num_funcall0(num, id_to_i); }
Returns self
truncated (toward zero) to a precision of digits
decimal digits.
Numeric implements this by converting self
to a Float
and invoking Float#truncate
.
static VALUE num_truncate(int argc, VALUE *argv, VALUE num) { return flo_truncate(argc, argv, rb_Float(num)); }