# Class: Numeric

Inherits:
Object
show all
Includes:
Comparable
Defined in:
numeric.c

## Overview

The top-level number class.

## Instance Method Summary collapse

• x.modulo(y) means x-y*(x/y).floor.

• Unary Plus—Returns the receiver's value.

• Unary Minus—Returns the receiver's value, negated.

• Returns zero if `number` equals `other`, otherwise `nil` is returned if the two values are incomparable.

• Returns the absolute value of `num`.

• Returns square of self.

• Returns 0 if the value is positive, pi otherwise.

• Returns 0 if the value is positive, pi otherwise.

• Returns the smallest possible Integer that is greater than or equal to `num`.

• If a +numeric is the same type as `num`, returns an array containing `numeric` and `num`.

• Returns self.

• Returns self.

• Returns the denominator (always positive).

• Uses `/` to perform division, then converts the result to an integer.

• Returns an array containing the quotient and modulus obtained by dividing `num` by `numeric`.

• Returns `true` if `num` and `numeric` are the same type and have equal values.

• Returns float division.

• Returns the largest integer less than or equal to `num`.

• Returns the corresponding imaginary number.

• Returns zero.

• Returns zero.

• Numerics are immutable values, which should not be copied.

• Returns `true` if `num` is an Integer (including Fixnum and Bignum).

• Returns the absolute value of `num`.

• x.modulo(y) means x-y*(x/y).floor.

• Returns `self` if `num` is not zero, `nil` otherwise.

• Returns the numerator.

• Returns 0 if the value is positive, pi otherwise.

• Returns an array; [num.abs, num.arg].

• Returns most exact division (rational for integers, float for floats).

• Returns self.

• Returns `true` if `num` is a Real number.

• Returns an array; [num, 0].

• Returns an array; [num, 0].

• x.remainder(y) means x-y*(x/y).truncate.

• Rounds `num` to a given precision in decimal digits (default 0 digits).

• Trap attempts to add methods to Numeric objects.

• Invokes the given block with the sequence of numbers starting at `num`, incremented by `step` (defaulted to `1`) on each call.

• Returns the value as a complex.

• Invokes the child class's `to_i` method to convert `num` to an integer.

• Returns `num` truncated to an Integer.

• Returns `true` if `num` has a zero value.

## Instance Method Details

### #modulo(numeric) ⇒ Object

x.modulo(y) means x-y*(x/y).floor

Equivalent to `num.divmod(numeric)[1]`.

See Numeric#divmod.

 ``` 425 426 427 428 429 430 431``` ```# File 'numeric.c', line 425 static VALUE num_modulo(VALUE x, VALUE y) { return rb_funcall(x, '-', 1, rb_funcall(y, '*', 1, rb_funcall(x, rb_intern("div"), 1, y))); }```

### #+ ⇒ Numeric

Returns:

 ``` 341 342 343 344 345``` ```# File 'numeric.c', line 341 static VALUE num_uplus(VALUE num) { return num; }```

### #- ⇒ Numeric

Unary Minus—Returns the receiver's value, negated.

Returns:

 ``` 369 370 371 372 373 374 375 376 377 378``` ```# File 'numeric.c', line 369 static VALUE num_uminus(VALUE num) { VALUE zero; zero = INT2FIX(0); do_coerce(&zero, &num, TRUE); return rb_funcall(zero, '-', 1, num); }```

### #<=>(other) ⇒ 0?

Returns zero if `number` equals `other`, otherwise `nil` is returned if the two values are incomparable.

Returns:

• (0, nil)
 ``` 1045 1046 1047 1048 1049 1050``` ```# File 'numeric.c', line 1045 static VALUE num_cmp(VALUE x, VALUE y) { if (x == y) return INT2FIX(0); return Qnil; }```

### #abs ⇒ Numeric #magnitude ⇒ Numeric

Returns the absolute value of `num`.

``````12.abs         #=> 12
(-34.56).abs   #=> 34.56
-34.56.abs     #=> 34.56
``````

Numeric#magnitude is an alias of Numeric#abs.

 ``` 548 549 550 551 552 553 554 555``` ```# File 'numeric.c', line 548 static VALUE num_abs(VALUE num) { if (negative_int_p(num)) { return rb_funcall(num, rb_intern("[email protected]"), 0); } return num; }```

### #abs2 ⇒ Object

Returns square of self.

 ``` 1972 1973 1974 1975 1976``` ```# File 'complex.c', line 1972 static VALUE numeric_abs2(VALUE self) { return f_mul(self, self); }```

### #arg ⇒ 0, Float #angle ⇒ 0, Float #phase ⇒ 0, Float

Returns 0 if the value is positive, pi otherwise.

 ``` 1988 1989 1990 1991 1992 1993 1994``` ```# File 'complex.c', line 1988 static VALUE numeric_arg(VALUE self) { if (f_positive_p(self)) return INT2FIX(0); return rb_const_get(rb_mMath, id_PI); }```

### #arg ⇒ 0, Float #angle ⇒ 0, Float #phase ⇒ 0, Float

Returns 0 if the value is positive, pi otherwise.

 ``` 1988 1989 1990 1991 1992 1993 1994``` ```# File 'complex.c', line 1988 static VALUE numeric_arg(VALUE self) { if (f_positive_p(self)) return INT2FIX(0); return rb_const_get(rb_mMath, id_PI); }```

### #ceil ⇒ Integer

Returns the smallest possible Integer that is greater than or equal to `num`.

Numeric achieves this by converting itself to a Float then invoking Float#ceil.

``````1.ceil        #=> 1
1.2.ceil      #=> 2
(-1.2).ceil   #=> -1
(-1.0).ceil   #=> -1
``````

Returns:

 ``` 1706 1707 1708 1709 1710``` ```# File 'numeric.c', line 1706 static VALUE num_ceil(VALUE num) { return flo_ceil(rb_Float(num)); }```

### #coerce(numeric) ⇒ Array

If a +numeric is the same type as `num`, returns an array containing `numeric` and `num`. Otherwise, returns an array with both a `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]
``````

Returns:

 ``` 215 216 217 218 219 220 221 222 223``` ```# File 'numeric.c', line 215 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); }```

### #conj ⇒ self #conjugate ⇒ self

Returns self.

• #conjself

Returns:

• (self)
• #conjugateself

Returns:

• (self)
 ``` 2028 2029 2030 2031 2032``` ```# File 'complex.c', line 2028 static VALUE numeric_conj(VALUE self) { return self; }```

### #conj ⇒ self #conjugate ⇒ self

Returns self.

• #conjself

Returns:

• (self)
• #conjugateself

Returns:

• (self)
 ``` 2028 2029 2030 2031 2032``` ```# File 'complex.c', line 2028 static VALUE numeric_conj(VALUE self) { return self; }```

### #denominator ⇒ Integer

Returns the denominator (always positive).

Returns:

 ``` 1836 1837 1838 1839 1840``` ```# File 'rational.c', line 1836 static VALUE numeric_denominator(VALUE self) { return f_denominator(f_to_r(self)); }```

### #div(numeric) ⇒ Integer

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.

Returns:

 ``` 406 407 408 409 410 411``` ```# File 'numeric.c', line 406 static VALUE num_div(VALUE x, VALUE y) { if (rb_equal(INT2FIX(0), y)) rb_num_zerodiv(); return rb_funcall(rb_funcall(x, '/', 1, y), rb_intern("floor"), 0); }```

### #divmod(numeric) ⇒ Array

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 -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]
``````

Returns:

 ``` 499 500 501 502 503``` ```# File 'numeric.c', line 499 static VALUE num_divmod(VALUE x, VALUE y) { return rb_assoc_new(num_div(x, y), num_modulo(x, y)); }```

### #eql?(numeric) ⇒ Boolean

Returns `true` if `num` and `numeric` are the same type and have equal values.

``````1 == 1.0          #=> true
1.eql?(1.0)       #=> false
(1.0).eql?(1.0)   #=> true
``````

Returns:

• (Boolean)

Returns:

• (Boolean)
 ``` 1029 1030 1031 1032 1033 1034 1035``` ```# File 'numeric.c', line 1029 static VALUE num_eql(VALUE x, VALUE y) { if (TYPE(x) != TYPE(y)) return Qfalse; return rb_equal(x, y); }```

### #fdiv(numeric) ⇒ Float

Returns float division.

Returns:

 ``` 387 388 389 390 391``` ```# File 'numeric.c', line 387 static VALUE num_fdiv(VALUE x, VALUE y) { return rb_funcall(rb_Float(x), '/', 1, y); }```

### #floor ⇒ Integer

Returns the largest integer less than or equal to `num`.

Numeric implements this by converting an Integer to a Float and invoking Float#floor.

``````1.floor      #=> 1
(-1).floor   #=> -1
``````

Returns:

 ``` 1683 1684 1685 1686 1687``` ```# File 'numeric.c', line 1683 static VALUE num_floor(VALUE num) { return flo_floor(rb_Float(num)); }```

### #i ⇒ Complex(0]

Returns the corresponding imaginary number. Not available for complex numbers.

Returns Complex(0].

Returns:

 ``` 355 356 357 358 359``` ```# File 'numeric.c', line 355 static VALUE num_imaginary(VALUE num) { return rb_complex_new(INT2FIX(0), num); }```

### #imag ⇒ 0 #imaginary ⇒ 0

Returns zero.

• #imag0

Returns:

• (0)
• #imaginary0

Returns:

• (0)
 ``` 1960 1961 1962 1963 1964``` ```# File 'complex.c', line 1960 static VALUE numeric_imag(VALUE self) { return INT2FIX(0); }```

### #imag ⇒ 0 #imaginary ⇒ 0

Returns zero.

• #imag0

Returns:

• (0)
• #imaginary0

Returns:

• (0)
 ``` 1960 1961 1962 1963 1964``` ```# File 'complex.c', line 1960 static VALUE numeric_imag(VALUE self) { return INT2FIX(0); }```

### #initialize_copy ⇒ Object

Numerics are immutable values, which should not be copied.

Any attempt to use this method on a Numeric will raise a TypeError.

 ``` 326 327 328 329 330 331 332``` ```# File 'numeric.c', line 326 static VALUE num_init_copy(VALUE x, VALUE y) { rb_raise(rb_eTypeError, "can't copy %s", rb_obj_classname(x)); UNREACHABLE; }```

### #integer? ⇒ Boolean

Returns `true` if `num` is an Integer (including Fixnum and Bignum).

``````(1.0).integer? #=> false
(1).integer?   #=> true
``````

Returns:

• (Boolean)

Returns:

• (Boolean)
 ``` 528 529 530 531 532``` ```# File 'numeric.c', line 528 static VALUE num_int_p(VALUE num) { return Qfalse; }```

### #abs ⇒ Numeric #magnitude ⇒ Numeric

Returns the absolute value of `num`.

``````12.abs         #=> 12
(-34.56).abs   #=> 34.56
-34.56.abs     #=> 34.56
``````

Numeric#magnitude is an alias of Numeric#abs.

 ``` 548 549 550 551 552 553 554 555``` ```# File 'numeric.c', line 548 static VALUE num_abs(VALUE num) { if (negative_int_p(num)) { return rb_funcall(num, rb_intern("[email protected]"), 0); } return num; }```

### #modulo(numeric) ⇒ Object

x.modulo(y) means x-y*(x/y).floor

Equivalent to `num.divmod(numeric)[1]`.

See Numeric#divmod.

 ``` 425 426 427 428 429 430 431``` ```# File 'numeric.c', line 425 static VALUE num_modulo(VALUE x, VALUE y) { return rb_funcall(x, '-', 1, rb_funcall(y, '*', 1, rb_funcall(x, rb_intern("div"), 1, y))); }```

### #nonzero? ⇒ self?

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"]
``````

Returns:

• (self, nil)

Returns:

• (Boolean)
 ``` 588 589 590 591 592 593 594 595``` ```# File 'numeric.c', line 588 static VALUE num_nonzero_p(VALUE num) { if (RTEST(rb_funcall(num, rb_intern("zero?"), 0, 0))) { return Qnil; } return num; }```

### #numerator ⇒ Integer

Returns the numerator.

Returns:

 ``` 1824 1825 1826 1827 1828``` ```# File 'rational.c', line 1824 static VALUE numeric_numerator(VALUE self) { return f_numerator(f_to_r(self)); }```

### #arg ⇒ 0, Float #angle ⇒ 0, Float #phase ⇒ 0, Float

Returns 0 if the value is positive, pi otherwise.

 ``` 1988 1989 1990 1991 1992 1993 1994``` ```# File 'complex.c', line 1988 static VALUE numeric_arg(VALUE self) { if (f_positive_p(self)) return INT2FIX(0); return rb_const_get(rb_mMath, id_PI); }```

### #polar ⇒ Array

Returns an array; [num.abs, num.arg].

Returns:

 ``` 2015 2016 2017 2018 2019``` ```# File 'complex.c', line 2015 static VALUE numeric_polar(VALUE self) { return rb_assoc_new(f_abs(self), f_arg(self)); }```

### #quo(int_or_rat) ⇒ Object #quo(flo) ⇒ Object

Returns most exact division (rational for integers, float for floats).

 ``` 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868``` ```# File 'rational.c', line 1851 static VALUE numeric_quo(VALUE x, VALUE y) { if (RB_TYPE_P(y, T_FLOAT)) { return f_fdiv(x, y); } #ifdef CANON if (canonicalization) { x = rb_rational_raw1(x); } else #endif { x = rb_convert_type(x, T_RATIONAL, "Rational", "to_r"); } return rb_funcall(x, '/', 1, y); }```

### #real ⇒ self

Returns self.

Returns:

• (self)
 ``` 1947 1948 1949 1950 1951``` ```# File 'complex.c', line 1947 static VALUE numeric_real(VALUE self) { return self; }```

### #real? ⇒ Boolean

Returns `true` if `num` is a Real number. (i.e. not Complex).

Returns:

• (Boolean)

Returns:

• (Boolean)
 ``` 512 513 514 515 516``` ```# File 'numeric.c', line 512 static VALUE num_real_p(VALUE num) { return Qtrue; }```

### #rect ⇒ Array #rectangular ⇒ Array

Returns an array; [num, 0].

 ``` 2003 2004 2005 2006 2007``` ```# File 'complex.c', line 2003 static VALUE numeric_rect(VALUE self) { return rb_assoc_new(self, INT2FIX(0)); }```

### #rect ⇒ Array #rectangular ⇒ Array

Returns an array; [num, 0].

 ``` 2003 2004 2005 2006 2007``` ```# File 'complex.c', line 2003 static VALUE numeric_rect(VALUE self) { return rb_assoc_new(self, INT2FIX(0)); }```

### #remainder(numeric) ⇒ Object

x.remainder(y) means x-y*(x/y).truncate

See Numeric#divmod.

 ``` 442 443 444 445 446 447 448 449 450 451 452 453 454 455``` ```# File 'numeric.c', line 442 static VALUE num_remainder(VALUE x, VALUE y) { VALUE z = rb_funcall(x, '%', 1, y); if ((!rb_equal(z, INT2FIX(0))) && ((negative_int_p(x) && positive_int_p(y)) || (positive_int_p(x) && negative_int_p(y)))) { return rb_funcall(z, '-', 1, y); } return z; }```

### #round([ndigits]) ⇒ Integer, Float

Rounds `num` to a given precision in decimal digits (default 0 digits).

Precision may be negative. Returns a floating point number when `ndigits` is more than zero.

Numeric implements this by converting itself to a Float and invoking Float#round.

Returns:

 ``` 1725 1726 1727 1728 1729``` ```# File 'numeric.c', line 1725 static VALUE num_round(int argc, VALUE* argv, VALUE num) { return flo_round(argc, argv, rb_Float(num)); }```

Trap attempts to add methods to Numeric objects. Always raises a TypeError.

Numerics should be values; singleton_methods should not be added to them.

 ``` 307 308 309 310 311 312 313 314 315 316 317 318 319``` ```# File 'numeric.c', line 307 static VALUE num_sadded(VALUE x, VALUE name) { ID mid = rb_to_id(name); /* ruby_frame = ruby_frame->prev; */ /* pop frame for "singleton_method_added" */ rb_remove_method_id(rb_singleton_class(x), mid); rb_raise(rb_eTypeError, "can't define singleton method \"%s\" for %s", rb_id2name(mid), rb_obj_classname(x)); UNREACHABLE; }```

### #step(by:step, to:limit]) {|i| ... } ⇒ self #step(by:step, to:limit]) ⇒ Object #step(limit = nil, step = 1) {|i| ... } ⇒ self #step(limit = nil, step = 1) ⇒ Object

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, integer 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 the following expression:

floor(n + n*epsilon)+ 1

Where the `n` is the following:

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.71828182845905 2.91828182845905 3.11828182845905
``````

• #step(by:step, to:limit]) {|i| ... } ⇒ self

Yields:

• (i)

Returns:

• (self)
• #step(limit = nil, step = 1) {|i| ... } ⇒ self

Yields:

• (i)

Returns:

• (self)
 ``` 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976``` ```# File 'numeric.c', line 1928 static VALUE num_step(int argc, VALUE *argv, VALUE from) { VALUE to, step, hash; int desc, inf; RETURN_SIZED_ENUMERATOR(from, argc, argv, num_step_size); NUM_STEP_SCAN_ARGS(argc, argv, to, step, hash, desc); NUM_STEP_GET_INF(to, desc, inf); 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; }```

### #to_c ⇒ Object

Returns the value as a complex.

 ``` 1524 1525 1526 1527 1528``` ```# File 'complex.c', line 1524 static VALUE numeric_to_c(VALUE self) { return rb_complex_new1(self); }```

### #to_int ⇒ Integer

Invokes the child class's `to_i` method to convert `num` to an integer.

``````1.0.class => Float
1.0.to_int.class => Fixnum
1.0.to_i.class => Fixnum
``````

Returns:

 ``` 608 609 610 611 612``` ```# File 'numeric.c', line 608 static VALUE num_to_int(VALUE num) { return rb_funcall(num, id_to_i, 0, 0); }```

### #truncate ⇒ Integer

Returns `num` truncated to an Integer.

Numeric implements this by converting its value to a Float and invoking Float#truncate.

Returns:

 ``` 1741 1742 1743 1744 1745``` ```# File 'numeric.c', line 1741 static VALUE num_truncate(VALUE num) { return flo_truncate(rb_Float(num)); }```

### #zero? ⇒ Boolean

Returns `true` if `num` has a zero value.

Returns:

• (Boolean)

Returns:

• (Boolean)
 ``` 565 566 567 568 569 570 571 572``` ```# File 'numeric.c', line 565 static VALUE num_zero_p(VALUE num) { if (rb_equal(num, INT2FIX(0))) { return Qtrue; } return Qfalse; }```