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.


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

Unary Plus—Returns the receiver's value.

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.

Overloads:


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.

Overloads:


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.

Overloads:


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.

Overloads:

  • #conj ⇒ self

    Returns:

    • (self)
  • #conjugate ⇒ self

    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.

Overloads:

  • #conj ⇒ self

    Returns:

    • (self)
  • #conjugate ⇒ self

    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.

Overloads:

  • #imag ⇒ 0

    Returns:

    • (0)
  • #imaginary ⇒ 0

    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.

Overloads:

  • #imag ⇒ 0

    Returns:

    • (0)
  • #imaginary ⇒ 0

    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.

Overloads:


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.

Overloads:


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

Overloads:


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

Overloads:


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

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


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

Overloads:

  • #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;
}