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.



451
452
453
454
455
456
457
 
# File 'numeric.c', line 451

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:



367
368
369
370
371
 
# File 'numeric.c', line 367

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

#- ⇒ Numeric

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

Returns:



395
396
397
398
399
400
401
402
403
404
 
# File 'numeric.c', line 395

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) 


1076
1077
1078
1079
1080
1081
 
# File 'numeric.c', line 1076

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:



574
575
576
577
578
579
580
581
 
# File 'numeric.c', line 574

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.



1941
1942
1943
1944
1945
 
# File 'complex.c', line 1941

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:



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

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:



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

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:



1852
1853
1854
1855
1856
 
# File 'numeric.c', line 1852

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:



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

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) 


1997
1998
1999
2000
2001
 
# File 'complex.c', line 1997

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

#conj ⇒ self #conjugate ⇒ self

Returns self.

Overloads:

  • #conj ⇒ self

    Returns:

    • (self)
  • #conjugate ⇒ self

    Returns:

    • (self) 


1997
1998
1999
2000
2001
 
# File 'complex.c', line 1997

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

#denominator ⇒ Integer

Returns the denominator (always positive).

Returns:



1819
1820
1821
1822
1823
 
# File 'rational.c', line 1819

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:



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

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:



525
526
527
528
529
 
# File 'numeric.c', line 525

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) 


1060
1061
1062
1063
1064
1065
1066
 
# File 'numeric.c', line 1060

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:



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

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:



1829
1830
1831
1832
1833
 
# File 'numeric.c', line 1829

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:



381
382
383
384
385
 
# File 'numeric.c', line 381

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) 


1929
1930
1931
1932
1933
 
# File 'complex.c', line 1929

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

#imag ⇒ 0 #imaginary ⇒ 0

Returns zero.

Overloads:

  • #imag ⇒ 0

    Returns:

    • (0)
  • #imaginary ⇒ 0

    Returns:

    • (0) 


1929
1930
1931
1932
1933
 
# File 'complex.c', line 1929

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

#initialize_copy(y) ⇒ Object

Numerics are immutable values, which should not be copied.

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



352
353
354
355
356
357
358
 
# File 'numeric.c', line 352

static VALUE
num_init_copy(VALUE x, VALUE y)
{
    rb_raise(rb_eTypeError, "can't copy %"PRIsVALUE, rb_obj_class(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) 


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

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:



574
575
576
577
578
579
580
581
 
# File 'numeric.c', line 574

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.



451
452
453
454
455
456
457
 
# File 'numeric.c', line 451

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) 


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

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:



1807
1808
1809
1810
1811
 
# File 'rational.c', line 1807

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:



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

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:



1984
1985
1986
1987
1988
 
# File 'complex.c', line 1984

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



1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
 
# File 'rational.c', line 1834

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) 


1916
1917
1918
1919
1920
 
# File 'complex.c', line 1916

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) 


538
539
540
541
542
 
# File 'numeric.c', line 538

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

#rect ⇒ Array #rectangular ⇒ Array

Returns an array; [num, 0].

Overloads:



1972
1973
1974
1975
1976
 
# File 'complex.c', line 1972

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

#rect ⇒ Array #rectangular ⇒ Array

Returns an array; [num, 0].

Overloads:



1972
1973
1974
1975
1976
 
# File 'complex.c', line 1972

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.



468
469
470
471
472
473
474
475
476
477
478
479
480
481
 
# File 'numeric.c', line 468

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:



1871
1872
1873
1874
1875
 
# File 'numeric.c', line 1871

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

#singleton_method_added(name) ⇒ 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.



333
334
335
336
337
338
339
340
341
342
343
344
345
 
# File 'numeric.c', line 333

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 \"%"PRIsVALUE"\" for %"PRIsVALUE,
	     rb_id2str(mid),
	     rb_obj_class(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, 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) 


2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
 
# File 'numeric.c', line 2104

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.



1489
1490
1491
1492
1493
 
# File 'complex.c', line 1489

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:



634
635
636
637
638
 
# File 'numeric.c', line 634

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:



1887
1888
1889
1890
1891
 
# File 'numeric.c', line 1887

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) 


591
592
593
594
595
596
597
598
 
# File 'numeric.c', line 591

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