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
x.modulo(y)
means x-y*(x/y).floor
.
Equivalent to num.divmod(numeric)[1]
.
See Numeric#divmod
.
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)); }
Unary Plus—Returns the receiver.
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 number
equals other
, otherwise returns nil
.
static VALUE num_cmp(VALUE x, VALUE y) { if (x == y) return INT2FIX(0); return Qnil; }
Returns the absolute value of num
.
12.abs #=> 12 (-34.56).abs #=> 34.56 -34.56.abs #=> 34.56
Numeric#magnitude
is an alias for Numeric#abs
.
static VALUE num_abs(VALUE num) { if (rb_num_negative_int_p(num)) { return num_funcall0(num, idUMinus); } return num; }
Returns square of self.
static VALUE numeric_abs2(VALUE self) { return f_mul(self, self); }
Returns 0 if the value is positive, pi otherwise.
static VALUE numeric_arg(VALUE self) { if (f_positive_p(self)) return INT2FIX(0); return DBL2NUM(M_PI); }
Returns 0 if the value is positive, pi otherwise.
static VALUE numeric_arg(VALUE self) { if (f_positive_p(self)) return INT2FIX(0); return DBL2NUM(M_PI); }
Returns the smallest number greater than or equal to num
with a precision of ndigits
decimal digits (default: 0).
Numeric
implements this by converting its value 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 the receiver. freeze
cannot be false
.
static VALUE num_clone(int argc, VALUE *argv, VALUE x) { return rb_immutable_obj_clone(argc, argv, x); }
If numeric
is the same type as num
, returns an array [numeric, num]
. Otherwise, returns an array with both numeric
and num
represented as Float
objects.
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.
1.coerce(2.5) #=> [2.5, 1.0] 1.2.coerce(3) #=> [3.0, 1.2] 1.coerce(2) #=> [2, 1]
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.
static VALUE numeric_conj(VALUE self) { return self; }
Returns self.
static VALUE numeric_conj(VALUE self) { return self; }
Returns the denominator (always positive).
static VALUE numeric_denominator(VALUE self) { return f_denominator(f_to_r(self)); }
Uses /
to perform division, then converts the result to an integer. Numeric
does not define the /
operator; this is left to subclasses.
Equivalent to num.divmod(numeric)[0]
.
See Numeric#divmod
.
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 an array containing the quotient and modulus obtained by dividing num
by numeric
.
If q, r = x.divmod(y)
, then
q = floor(x/y) x = q*y + r
The quotient is rounded toward negative infinity, as shown in the following table:
a | b | a.divmod(b) | a/b | a.modulo(b) | a.remainder(b) ------+-----+---------------+---------+-------------+--------------- 13 | 4 | 3, 1 | 3 | 1 | 1 ------+-----+---------------+---------+-------------+--------------- 13 | -4 | -4, -3 | -4 | -3 | 1 ------+-----+---------------+---------+-------------+--------------- -13 | 4 | -4, 3 | -4 | 3 | -1 ------+-----+---------------+---------+-------------+--------------- -13 | -4 | 3, -1 | 3 | -1 | -1 ------+-----+---------------+---------+-------------+--------------- 11.5 | 4 | 2, 3.5 | 2.875 | 3.5 | 3.5 ------+-----+---------------+---------+-------------+--------------- 11.5 | -4 | -3, -0.5 | -2.875 | -0.5 | 3.5 ------+-----+---------------+---------+-------------+--------------- -11.5 | 4 | -3, 0.5 | -2.875 | 0.5 | -3.5 ------+-----+---------------+---------+-------------+--------------- -11.5 | -4 | 2, -3.5 | 2.875 | -3.5 | -3.5
Examples
11.divmod(3) #=> [3, 2] 11.divmod(-3) #=> [-4, -1] 11.divmod(3.5) #=> [3, 0.5] (-11).divmod(3.5) #=> [-4, 3.0] 11.5.divmod(3.5) #=> [3, 1.0]
static VALUE num_divmod(VALUE x, VALUE y) { return rb_assoc_new(num_div(x, y), num_modulo(x, y)); }
Returns true
if num
and numeric
are the same type and have equal values. Contrast this with Numeric#==, which performs type conversions.
1 == 1.0 #=> true 1.eql?(1.0) #=> false 1.0.eql?(1.0) #=> true
static VALUE num_eql(VALUE x, VALUE y) { if (TYPE(x) != TYPE(y)) return Qfalse; if (RB_TYPE_P(x, T_BIGNUM)) { return rb_big_eql(x, y); } return rb_equal(x, y); }
Returns float division.
static VALUE num_fdiv(VALUE x, VALUE y) { return rb_funcall(rb_Float(x), '/', 1, y); }
Returns true
if num
is a finite number, otherwise returns false
.
static VALUE num_finite_p(VALUE num) { return Qtrue; }
Returns the largest number less than or equal to num
with a precision of ndigits
decimal digits (default: 0).
Numeric
implements this by converting its value 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 the corresponding imaginary number. Not available for complex numbers.
-42.i #=> (0-42i) 2.0.i #=> (0+2.0i)
static VALUE num_imaginary(VALUE num) { return rb_complex_new(INT2FIX(0), num); }
Returns zero.
static VALUE numeric_imag(VALUE self) { return INT2FIX(0); }
Returns zero.
static VALUE numeric_imag(VALUE self) { return INT2FIX(0); }
Returns nil
, -1, or 1 depending on whether the value is finite, -Infinity
, or +Infinity
.
static VALUE num_infinite_p(VALUE num) { return Qnil; }
Returns true
if num
is an Integer
.
1.0.integer? #=> false 1.integer? #=> true
static VALUE num_int_p(VALUE num) { return Qfalse; }
Returns the absolute value of num
.
12.abs #=> 12 (-34.56).abs #=> 34.56 -34.56.abs #=> 34.56
Numeric#magnitude
is an alias for Numeric#abs
.
static VALUE num_abs(VALUE num) { if (rb_num_negative_int_p(num)) { return num_funcall0(num, idUMinus); } return num; }
x.modulo(y)
means x-y*(x/y).floor
.
Equivalent to num.divmod(numeric)[1]
.
See Numeric#divmod
.
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 true
if num
is less than 0.
static VALUE num_negative_p(VALUE num) { return rb_num_negative_int_p(num) ? Qtrue : Qfalse; }
Returns self
if num
is not zero, nil
otherwise.
This behavior is useful when chaining comparisons:
a = %w( z Bb bB bb BB a aA Aa AA A ) b = a.sort {|a,b| (a.downcase <=> b.downcase).nonzero? || a <=> b } b #=> ["A", "a", "AA", "Aa", "aA", "BB", "Bb", "bB", "bb", "z"]
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 0 if the value is positive, pi otherwise.
static VALUE numeric_arg(VALUE self) { if (f_positive_p(self)) return INT2FIX(0); return DBL2NUM(M_PI); }
Returns an array; [num.abs, num.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 num
is greater than 0.
static VALUE num_positive_p(VALUE num) { const ID mid = '>'; if (FIXNUM_P(num)) { if (method_basic_p(rb_cInteger)) return (SIGNED_VALUE)num > (SIGNED_VALUE)INT2FIX(0) ? Qtrue : Qfalse; } else if (RB_TYPE_P(num, T_BIGNUM)) { if (method_basic_p(rb_cInteger)) return BIGNUM_POSITIVE_P(num) && !rb_bigzero_p(num) ? Qtrue : Qfalse; } 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_FLOAT_TYPE_P(y)) { return rb_funcall(x, rb_intern("fdiv"), 1, y); } if (canonicalization) { x = rb_rational_raw1(x); } else { x = rb_convert_type(x, T_RATIONAL, "Rational", "to_r"); } return nurat_div(x, y); }
Returns self.
static VALUE numeric_real(VALUE self) { return self; }
Returns true
if num
is a real number (i.e. not Complex
).
static VALUE num_real_p(VALUE num) { return Qtrue; }
Returns an array; [num, 0].
static VALUE numeric_rect(VALUE self) { return rb_assoc_new(self, INT2FIX(0)); }
Returns an array; [num, 0].
static VALUE numeric_rect(VALUE self) { return rb_assoc_new(self, INT2FIX(0)); }
x.remainder(y)
means x-y*(x/y).truncate
.
See Numeric#divmod
.
static VALUE num_remainder(VALUE x, VALUE y) { 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)))) { return rb_funcall(z, '-', 1, y); } return z; }
Returns num
rounded to the nearest value with a precision of ndigits
decimal digits (default: 0).
Numeric
implements this by converting its value 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)); }
Invokes the given block with the sequence of numbers starting at num
, incremented by step
(defaulted to 1
) on each call.
The loop finishes when the value to be passed to the block is greater than limit
(if step
is positive) or less than limit
(if step
is negative), where limit
is defaulted to infinity.
In the recommended keyword argument style, either or both of step
and limit
(default infinity) can be omitted. In the fixed position argument style, zero as a step (i.e. num.step(limit, 0)
) is not allowed for historical compatibility reasons.
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 floor(n + n*Float::EPSILON) + 1 times, where n = (limit - num)/step.
Otherwise, the loop starts at num
, uses either the less-than (<
) or greater-than (>
) operator to compare the counter against limit
, and increments itself using the +
operator.
If no block is given, an Enumerator
is returned instead.
For example:
p 1.step.take(4) p 10.step(by: -1).take(4) 3.step(to: 5) {|i| print i, " " } 1.step(10, 2) {|i| print i, " " } Math::E.step(to: Math::PI, by: 0.2) {|f| print f, " " }
Will produce:
[1, 2, 3, 4] [10, 9, 8, 7] 3 4 5 1 3 5 7 9 2.718281828459045 2.9182818284590453 3.118281828459045
static VALUE num_step(int argc, VALUE *argv, VALUE from) { VALUE to, step; int desc, inf; RETURN_SIZED_ENUMERATOR(from, argc, argv, num_step_size); desc = num_step_scan_args(argc, argv, &to, &step); if (rb_equal(step, INT2FIX(0))) { inf = 1; } else if (RB_TYPE_P(to, T_FLOAT)) { 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)) { 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 the value as a complex.
static VALUE numeric_to_c(VALUE self) { return rb_complex_new1(self); }
Invokes the child class's to_i
method to convert num
to an integer.
1.0.class #=> Float 1.0.to_int.class #=> Integer 1.0.to_i.class #=> Integer
static VALUE num_to_int(VALUE num) { return num_funcall0(num, id_to_i); }
Returns num
truncated (toward zero) to a precision of ndigits
decimal digits (default: 0).
Numeric
implements this by converting its value 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)); }
Returns true
if num
has a zero value.
static VALUE num_zero_p(VALUE num) { if (FIXNUM_P(num)) { if (FIXNUM_ZERO_P(num)) { return Qtrue; } } else if (RB_TYPE_P(num, T_BIGNUM)) { if (rb_bigzero_p(num)) { /* this should not happen usually */ return Qtrue; } } else if (rb_equal(num, INT2FIX(0))) { return Qtrue; } return Qfalse; }