Class: Numeric

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

Overview

Raised when attempting to convert special float values (in particular infinite or NaN) to numerical classes which don't support them.

Float::INFINITY.to_r

raises the exception:

FloatDomainError: Infinity

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(aNumeric)[1].

See Numeric#divmod.



428
429
430
431
432
433
434
 
# File 'numeric.c', line 428

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:



327
328
329
330
331
 
# File 'numeric.c', line 327

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

#- ⇒ Numeric

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

Returns:



355
356
357
358
359
360
361
362
363
364
 
# File 'numeric.c', line 355

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 num equals other, nil otherwise.

Returns:

  • (0, nil) 


1033
1034
1035
1036
1037
1038
 
# File 'numeric.c', line 1033

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

Overloads:



547
548
549
550
551
552
553
554
 
# File 'numeric.c', line 547

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.



1970
1971
1972
1973
1974
 
# File 'complex.c', line 1970

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:



1986
1987
1988
1989
1990
1991
1992
 
# File 'complex.c', line 1986

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:



1986
1987
1988
1989
1990
1991
1992
 
# File 'complex.c', line 1986

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 Integer greater than or equal to num. Class 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:



1709
1710
1711
1712
1713
 
# File 'numeric.c', line 1709

static VALUE
num_ceil(VALUE num)
{
    return flo_ceil(rb_Float(num));
}

#coerce(numeric) ⇒ Array

If aNumeric is the same type as num, returns an array containing aNumeric and num. Otherwise, returns an array with both aNumeric 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:



204
205
206
207
208
209
210
211
212
 
# File 'numeric.c', line 204

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) 


2025
2026
2027
2028
2029
 
# File 'complex.c', line 2025

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

#conj ⇒ self #conjugate ⇒ self

Returns self.

Overloads:

  • #conj ⇒ self

    Returns:

    • (self)
  • #conjugate ⇒ self

    Returns:

    • (self) 


2025
2026
2027
2028
2029
 
# File 'complex.c', line 2025

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

#denominator ⇒ Integer

Returns the denominator (always positive).

Returns:



1767
1768
1769
1770
1771
 
# File 'rational.c', line 1767

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(aNumeric)[0].

See Numeric#divmod.

Returns:



408
409
410
411
412
413
 
# File 'numeric.c', line 408

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:



501
502
503
504
505
 
# File 'numeric.c', line 501

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) 


1017
1018
1019
1020
1021
1022
1023
 
# File 'numeric.c', line 1017

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 anInteger to a Float and invoking Float#floor.

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

Returns:



1687
1688
1689
1690
1691
 
# File 'numeric.c', line 1687

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:



341
342
343
344
345
 
# File 'numeric.c', line 341

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) 


1958
1959
1960
1961
1962
 
# File 'complex.c', line 1958

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

#imag ⇒ 0 #imaginary ⇒ 0

Returns zero.

Overloads:

  • #imag ⇒ 0

    Returns:

    • (0)
  • #imaginary ⇒ 0

    Returns:

    • (0) 


1958
1959
1960
1961
1962
 
# File 'complex.c', line 1958

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

#initialize_copy ⇒ Object

:nodoc:



311
312
313
314
315
316
317
318
 
# File 'numeric.c', line 311

static VALUE
num_init_copy(VALUE x, VALUE y)
{
    /* Numerics are immutable values, which should not be copied */
    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).

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


529
530
531
532
533
 
# File 'numeric.c', line 529

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

Overloads:



547
548
549
550
551
552
553
554
 
# File 'numeric.c', line 547

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(aNumeric)[1].

See Numeric#divmod.



428
429
430
431
432
433
434
 
# File 'numeric.c', line 428

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) 


586
587
588
589
590
591
592
593
 
# File 'numeric.c', line 586

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:



1755
1756
1757
1758
1759
 
# File 'rational.c', line 1755

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:



1986
1987
1988
1989
1990
1991
1992
 
# File 'complex.c', line 1986

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:



2012
2013
2014
2015
2016
 
# File 'complex.c', line 2012

static VALUE
numeric_polar(VALUE self)
{
    return rb_assoc_new(f_abs(self), f_arg(self));
}

#quo(numeric) ⇒ Object

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



373
374
375
376
377
 
# File 'numeric.c', line 373

static VALUE
num_quo(VALUE x, VALUE y)
{
    return rb_funcall(rb_rational_raw1(x), '/', 1, y);
}

#real ⇒ self

Returns self.

Returns:

  • (self) 


1945
1946
1947
1948
1949
 
# File 'complex.c', line 1945

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

#real? ⇒ Boolean

Returns true if num is a Real (i.e. non Complex).

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


515
516
517
518
519
 
# File 'numeric.c', line 515

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

#rect ⇒ Array

Returns an array; [num, 0].

Returns:



2000
2001
2002
2003
2004
 
# File 'complex.c', line 2000

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

#rect ⇒ Array

Returns an array; [num, 0].

Returns:



2000
2001
2002
2003
2004
 
# File 'complex.c', line 2000

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.



445
446
447
448
449
450
451
452
453
454
455
456
457
458
 
# File 'numeric.c', line 445

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));
}

#singleton_method_added ⇒ Object

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



295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'numeric.c', line 295

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" */
    /* Numerics should be values; singleton_methods should not be added to them */
    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(limit[, step]) {|i| ... } ⇒ self #step(limit[, step]) ⇒ Object

Invokes block with the sequence of numbers starting at num, incremented by step (default 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). 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*epsilon)+ 1 times, where n = (limit - num)/step. Otherwise, the loop starts at num, uses either the < or > operator to compare the counter against limit, and increments itself using the + operator.

If no block is given, an enumerator is returned instead.

1.step(10, 2) { |i| print i, " " }
Math::E.step(Math::PI, 0.2) { |f| print f, " " }

produces:

1 3 5 7 9
2.71828182845905 2.91828182845905 3.11828182845905

Overloads:

  • #step(limit[, step]) {|i| ... } ⇒ self

    Yields:

    • (i)

    Returns:

    • (self) 


1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
 
# File 'numeric.c', line 1866

static VALUE
num_step(int argc, VALUE *argv, VALUE from)
{
    VALUE to, step;

    RETURN_SIZED_ENUMERATOR(from, argc, argv, num_step_size);
    if (argc == 1) {
	to = argv[0];
	step = INT2FIX(1);
    }
    else {
	rb_check_arity(argc, 1, 2);
	to = argv[0];
	step = argv[1];
	if (rb_equal(step, INT2FIX(0))) {
	    rb_raise(rb_eArgError, "step can't be 0");
	}
    }

    if (FIXNUM_P(from) && FIXNUM_P(to) && FIXNUM_P(step)) {
	long i, end, diff;

	i = FIX2LONG(from);
	end = FIX2LONG(to);
	diff = FIX2LONG(step);

	if (diff > 0) {
	    while (i <= end) {
		rb_yield(LONG2FIX(i));
		i += diff;
	    }
	}
	else {
	    while (i >= end) {
		rb_yield(LONG2FIX(i));
		i += diff;
	    }
	}
    }
    else if (!ruby_float_step(from, to, step, FALSE)) {
	VALUE i = from;
	ID cmp;

	if (positive_int_p(step)) {
	    cmp = '>';
	}
	else {
	    cmp = '<';
	}
	for (;;) {
	    if (RTEST(rb_funcall(i, cmp, 1, to))) break;
	    rb_yield(i);
	    i = rb_funcall(i, '+', 1, step);
	}
    }
    return from;
}

#to_c ⇒ Object

Returns the value as a complex.



1509
1510
1511
1512
1513
 
# File 'complex.c', line 1509

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.

Returns:



603
604
605
606
607
 
# File 'numeric.c', line 603

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:



1740
1741
1742
1743
1744
 
# File 'numeric.c', line 1740

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) 


564
565
566
567
568
569
570
571
 
# File 'numeric.c', line 564

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