Class: Numeric

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

Overview

The top-level number class.

Direct Known Subclasses

Complex, Float, Integer, Rational

Instance Method Summary collapse

Methods included from Comparable

#<, #<=, #==, #>, #>=, #between?

Instance Method Details

#modulo(numeric) ⇒ Object

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

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

See Numeric#divmod.



431
432
433
434
435
436
437
 
# File 'numeric.c', line 431

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

Unary Plus—Returns the receiver’s value.

Returns:



347
348
349
350
351
 
# File 'numeric.c', line 347

static VALUE
num_uplus(VALUE num)
{
    return num;
}

#- ⇒ Numeric

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

Returns:



375
376
377
378
379
380
381
382
383
384
 
# File 'numeric.c', line 375

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) 


1051
1052
1053
1054
1055
1056
 
# File 'numeric.c', line 1051

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.

Overloads:



554
555
556
557
558
559
560
561
 
# File 'numeric.c', line 554

static VALUE
num_abs(VALUE num)
{
    if (negative_int_p(num)) {
	return rb_funcall(num, rb_intern("-@"), 0);
    }
    return num;
}

#abs2 ⇒ Object

Returns square of self.



1937
1938
1939
1940
1941
 
# File 'complex.c', line 1937

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.

Overloads:



1953
1954
1955
1956
1957
1958
1959
 
# File 'complex.c', line 1953

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.

Overloads:



1953
1954
1955
1956
1957
1958
1959
 
# File 'complex.c', line 1953

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:



1712
1713
1714
1715
1716
 
# File 'numeric.c', line 1712

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:



219
220
221
222
223
224
225
226
227
 
# File 'numeric.c', line 219

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.

Overloads:

  • #conj ⇒ self

    Returns:

    • (self)
  • #conjugate ⇒ self

    Returns:

    • (self) 


1993
1994
1995
1996
1997
 
# File 'complex.c', line 1993

static VALUE
numeric_conj(VALUE self)
{
    return self;
}

#conj ⇒ self #conjugate ⇒ self

Returns self.

Overloads:

  • #conj ⇒ self

    Returns:

    • (self)
  • #conjugate ⇒ self

    Returns:

    • (self) 


1993
1994
1995
1996
1997
 
# File 'complex.c', line 1993

static VALUE
numeric_conj(VALUE self)
{
    return self;
}

#denominator ⇒ Integer

Returns the denominator (always positive).

Returns:



1805
1806
1807
1808
1809
 
# File 'rational.c', line 1805

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:



412
413
414
415
416
417
 
# File 'numeric.c', line 412

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:



505
506
507
508
509
 
# File 'numeric.c', line 505

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) 


1035
1036
1037
1038
1039
1040
1041
 
# File 'numeric.c', line 1035

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:



393
394
395
396
397
 
# File 'numeric.c', line 393

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:



1689
1690
1691
1692
1693
 
# File 'numeric.c', line 1689

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:



361
362
363
364
365
 
# File 'numeric.c', line 361

static VALUE
num_imaginary(VALUE num)
{
    return rb_complex_new(INT2FIX(0), num);
}

#imag ⇒ 0 #imaginary ⇒ 0

Returns zero.

Overloads:

  • #imag ⇒ 0

    Returns:

    • (0)
  • #imaginary ⇒ 0

    Returns:

    • (0) 


1925
1926
1927
1928
1929
 
# File 'complex.c', line 1925

static VALUE
numeric_imag(VALUE self)
{
    return INT2FIX(0);
}

#imag ⇒ 0 #imaginary ⇒ 0

Returns zero.

Overloads:

  • #imag ⇒ 0

    Returns:

    • (0)
  • #imaginary ⇒ 0

    Returns:

    • (0) 


1925
1926
1927
1928
1929
 
# File 'complex.c', line 1925

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.



332
333
334
335
336
337
338
 
# File 'numeric.c', line 332

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) 


534
535
536
537
538
 
# File 'numeric.c', line 534

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.

Overloads:



554
555
556
557
558
559
560
561
 
# File 'numeric.c', line 554

static VALUE
num_abs(VALUE num)
{
    if (negative_int_p(num)) {
	return rb_funcall(num, rb_intern("-@"), 0);
    }
    return num;
}

#modulo(numeric) ⇒ Object

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

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

See Numeric#divmod.



431
432
433
434
435
436
437
 
# File 'numeric.c', line 431

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) 


594
595
596
597
598
599
600
601
 
# File 'numeric.c', line 594

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:



1793
1794
1795
1796
1797
 
# File 'rational.c', line 1793

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.

Overloads:



1953
1954
1955
1956
1957
1958
1959
 
# File 'complex.c', line 1953

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:



1980
1981
1982
1983
1984
 
# File 'complex.c', line 1980

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).



1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
 
# File 'rational.c', line 1820

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) 


1912
1913
1914
1915
1916
 
# File 'complex.c', line 1912

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) 


518
519
520
521
522
 
# File 'numeric.c', line 518

static VALUE
num_real_p(VALUE num)
{
    return Qtrue;
}

#rect ⇒ Array #rectangular ⇒ Array

Returns an array; [num, 0].

Overloads:



1968
1969
1970
1971
1972
 
# File 'complex.c', line 1968

static VALUE
numeric_rect(VALUE self)
{
    return rb_assoc_new(self, INT2FIX(0));
}

#rect ⇒ Array #rectangular ⇒ Array

Returns an array; [num, 0].

Overloads:



1968
1969
1970
1971
1972
 
# File 'complex.c', line 1968

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.



448
449
450
451
452
453
454
455
456
457
458
459
460
461
 
# File 'numeric.c', line 448

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:



1731
1732
1733
1734
1735
 
# File 'numeric.c', line 1731

static VALUE
num_round(int argc, VALUE* argv, VALUE num)
{
    return flo_round(argc, argv, rb_Float(num));
}

#singleton_method_added ⇒ Object

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

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



313
314
315
316
317
318
319
320
321
322
323
324
325
 
# File 'numeric.c', line 313

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

Overloads:

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

    Yields:

    • (i)

    Returns:

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

    Yields:

    • (i)

    Returns:

    • (self) 


1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
 
# File 'numeric.c', line 1964

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 (RTEST(rb_num_coerce_cmp(step, INT2FIX(0), id_eq))) {
	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;
}

#to_c ⇒ Object

Returns the value as a complex.



1482
1483
1484
1485
1486
 
# File 'complex.c', line 1482

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:



614
615
616
617
618
 
# File 'numeric.c', line 614

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:



1747
1748
1749
1750
1751
 
# File 'numeric.c', line 1747

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) 


571
572
573
574
575
576
577
578
 
# File 'numeric.c', line 571

static VALUE
num_zero_p(VALUE num)
{
    if (rb_equal(num, INT2FIX(0))) {
	return Qtrue;
    }
    return Qfalse;
}