123456789_123456789_123456789_123456789_123456789_

Class: Numeric

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, ::Comparable
Inherits: Object
Defined in: numeric.c,
complex.c,
rational.c

Overview

Numeric is the class from which all higher-level numeric classes should inherit.

Numeric allows instantiation of heap-allocated objects. Other core numeric classes such as ::Integer are implemented as immediates, which means that each ::Integer is a single immutable object which is always passed by value.

a = 1
1.object_id == a.object_id   #=> true

There can only ever be one instance of the integer 1, for example. Ruby ensures this by preventing instantiation. If duplication is attempted, the same instance is returned.

Integer.new(1)                   #=> NoMethodError: undefined method `new' for Integer:Class
1.dup                            #=> 1
1.object_id == 1.dup.object_id   #=> true

For this reason, Numeric should be used when defining other numeric classes.

Classes which inherit from Numeric must implement #coerce, which returns a two-member ::Array containing an object that has been coerced into an instance of the new class and self (see #coerce).

Inheriting classes should also implement arithmetic operator methods (+, -, * and /) and the #<=> operator (see ::Comparable). These methods may rely on #coerce to ensure interoperability with instances of other numeric classes.

class Tally < Numeric
  def initialize(string)
    @string = string
  end

  def to_s
    @string
  end

  def to_i
    @string.size
  end

  def coerce(other)
    [self.class.new('|' * other.to_i), self]
  end

  def <=>(other)
    to_i <=> other.to_i
  end

  def +(other)
    self.class.new('|' * (to_i + other.to_i))
  end

  def -(other)
    self.class.new('|' * (to_i - other.to_i))
  end

  def *(other)
    self.class.new('|' * (to_i * other.to_i))
  end

  def /(other)
    self.class.new('|' * (to_i / other.to_i))
  end
end

tally = Tally.new('||')
puts tally * 2            #=> "||||"
puts tally > 1            #=> true

Instance Attribute Summary

Instance Method Summary

::Comparable - Included

#<

Compares two objects based on the receiver's #<=> method, returning true if it returns a value less than 0.

#<=

Compares two objects based on the receiver's #<=> method, returning true if it returns a value less than or equal to 0.

#==

Compares two objects based on the receiver's #<=> method, returning true if it returns 0.

#>

Compares two objects based on the receiver's #<=> method, returning true if it returns a value greater than 0.

#>=

Compares two objects based on the receiver's #<=> method, returning true if it returns a value greater than or equal to 0.

#between?

Returns false if obj #<=> min is less than zero or if anObject #<=> max is greater than zero, true otherwise.

#clamp

Returns min if obj #<=> min is less than zero, max if obj #<=> max is greater than zero and obj otherwise.

Instance Attribute Details

#finite?Boolean (readonly)

Returns true if num is a finite number, otherwise returns false.

[ GitHub ]

  
# File 'numeric.c', line 804

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

#infinite?Boolean (readonly)

Returns nil, -1, or 1 depending on whether the value is finite, -Infinity, or <code>Infinity.

[ GitHub ]

  
# File 'numeric.c', line 817

static VALUE
num_infinite_p(VALUE num)
{
    return Qnil;
}

#integer?Boolean (readonly)

Returns true if num is an ::Integer.

1.0.integer?   #=> false
1.integer?     #=> true
[ GitHub ]

  
# File 'numeric.c', line 720

static VALUE
num_int_p(VALUE num)
{
    return Qfalse;
}

#negative?Boolean (readonly)

Returns true if num is less than 0.

[ GitHub ]

  
# File 'numeric.c', line 870

static VALUE
num_negative_p(VALUE num)
{
    return rb_num_negative_int_p(num) ? Qtrue : Qfalse;
}

#nonzero?Boolean (readonly)

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"]
[ GitHub ]

  
# File 'numeric.c', line 789

static VALUE
num_nonzero_p(VALUE num)
{
    if (RTEST(num_funcall0(num, rb_intern("zero?")))) {
	return Qnil;
    }
    return num;
}

#positive?Boolean (readonly)

Returns true if num is greater than 0.

[ GitHub ]

  
# File 'numeric.c', line 847

static VALUE
num_positive_p(VALUE num)
{
    const ID mid = '>';

    if (FIXNUM_P(num)) {
	if (method_basic_p(rb_cInteger))
	    return (SIGNED_VALUE)num > (SIGNED_VALUE)INT2FIX(0) ? Qtrue : Qfalse;
    }
    else if (RB_TYPE_P(num, T_BIGNUM)) {
	if (method_basic_p(rb_cInteger))
	    return BIGNUM_POSITIVE_P(num) && !rb_bigzero_p(num) ? Qtrue : Qfalse;
    }
    return rb_num_compare_with_zero(num, mid);
}

#realself (readonly)

Returns self.

[ GitHub ]

  
# File 'complex.c', line 2094

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

#real?Boolean (readonly)

Returns true if num is a real number (i.e. not ::Complex).

[ GitHub ]

  
# File 'numeric.c', line 704

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

#zero?Boolean (readonly)

Returns true if num has a zero value.

[ GitHub ]

  
# File 'numeric.c', line 756

static VALUE
num_zero_p(VALUE num)
{
    if (FIXNUM_P(num)) {
	if (FIXNUM_ZERO_P(num)) {
	    return Qtrue;
	}
    }
    else if (RB_TYPE_P(num, T_BIGNUM)) {
	if (rb_bigzero_p(num)) {
	    /* this should not happen usually */
	    return Qtrue;
	}
    }
    else if (rb_equal(num, INT2FIX(0))) {
	return Qtrue;
    }
    return Qfalse;
}

Instance Method Details

#modulo(numeric) ⇒ Numeric Also known as: #modulo

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

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

See #divmod.

[ GitHub ]

  
# File 'numeric.c', line 616

static VALUE
num_modulo(VALUE x, VALUE y)
{
    VALUE q = num_funcall1(x, id_div, y);
    return rb_funcall(x, '-', 1,
		      rb_funcall(y, '*', 1, q));
}

#+Numeric

Unary Plus—Returns the receiver.

[ GitHub ]

  
# File 'numeric.c', line 532

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

#-Numeric

Unary Minus—Returns the receiver, negated.

[ GitHub ]

  
# File 'numeric.c', line 562

static VALUE
num_uminus(VALUE num)
{
    VALUE zero;

    zero = INT2FIX(0);
    do_coerce(&zero, &num, TRUE);

    return num_funcall1(zero, '-', num);
}

#<=>(other) ⇒ 0?

Returns zero if number equals other, otherwise returns nil.

[ GitHub ]

  
# File 'numeric.c', line 1350

static VALUE
num_cmp(VALUE x, VALUE y)
{
    if (x == y) return INT2FIX(0);
    return Qnil;
}

#absNumeric #magnitudeNumeric
Also known as: #magnitude

Returns the absolute value of num.

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

#magnitude is an alias for abs.

[ GitHub ]

  
# File 'numeric.c', line 740

static VALUE
num_abs(VALUE num)
{
    if (rb_num_negative_int_p(num)) {
	return num_funcall0(num, idUMinus);
    }
    return num;
}

#abs2Numeric

Returns square of self.

[ GitHub ]

  
# File 'complex.c', line 2119

static VALUE
numeric_abs2(VALUE self)
{
    return f_mul(self, self);
}

#arg0, Float #angle0, Float #phase0, Float

Alias for #arg.

#arg0, Float #angle0, Float #phase0, Float
Also known as: #angle, #phase

Returns 0 if the value is positive, pi otherwise.

[ GitHub ]

  
# File 'complex.c', line 2133

static VALUE
numeric_arg(VALUE self)
{
    if (f_positive_p(self))
        return INT2FIX(0);
    return DBL2NUM(M_PI);
}

#ceil([ndigits]) ⇒ Integer, Float

Returns the smallest number greater than or equal to num with a precision of ndigits decimal digits (default: 0).

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

[ GitHub ]

  
# File 'numeric.c', line 2444

static VALUE
num_ceil(int argc, VALUE *argv, VALUE num)
{
    return flo_ceil(argc, argv, rb_Float(num));
}

#clone(freeze:true) ⇒ Numeric

Returns the receiver. freeze cannot be false.

[ GitHub ]

  
# File 'numeric.c', line 500

static VALUE
num_clone(int argc, VALUE *argv, VALUE x)
{
    return rb_immutable_obj_clone(argc, argv, x);
}

#coerce(numeric) ⇒ Array

If numeric is the same type as num, returns an array [numeric, num]. Otherwise, returns an array with both 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]
[ GitHub ]

  
# File 'numeric.c', line 397

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

#conjself #conjugateself
Also known as: #conjugate

Returns self.

[ GitHub ]

  
# File 'complex.c', line 2193

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

#conjself #conjugateself

Alias for #conj.

#denominatorInteger

Returns the denominator (always positive).

[ GitHub ]

  
# File 'rational.c', line 1982

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

[ GitHub ]

  
# File 'numeric.c', line 598

static VALUE
num_div(VALUE x, VALUE y)
{
    if (rb_equal(INT2FIX(0), y)) rb_num_zerodiv();
    return rb_funcall(num_funcall1(x, '/', 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 negative 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]
[ GitHub ]

  
# File 'numeric.c', line 691

static VALUE
num_divmod(VALUE x, VALUE y)
{
    return rb_assoc_new(num_div(x, y), num_modulo(x, y));
}

#dupNumeric

Returns the receiver.

[ GitHub ]

  
# File 'numeric.c', line 516

static VALUE
num_dup(VALUE x)
{
    return x;
}

#eql?(numeric) ⇒ Boolean

Returns true if num and numeric are the same type and have equal values. Contrast this with Numeric#==, which performs type conversions.

1 == 1.0        #=> true
1.eql?(1.0)     #=> false
1.0.eql?(1.0)   #=> true
[ GitHub ]

  
# File 'numeric.c', line 1331

static VALUE
num_eql(VALUE x, VALUE y)
{
    if (TYPE(x) != TYPE(y)) return Qfalse;

    if (RB_TYPE_P(x, T_BIGNUM)) {
	return rb_big_eql(x, y);
    }

    return rb_equal(x, y);
}

#fdiv(numeric) ⇒ Float

Returns float division.

[ GitHub ]

  
# File 'numeric.c', line 580

static VALUE
num_fdiv(VALUE x, VALUE y)
{
    return rb_funcall(rb_Float(x), '/', 1, y);
}

#floor([ndigits]) ⇒ Integer, Float

Returns the largest number less than or equal to num with a precision of ndigits decimal digits (default: 0).

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

[ GitHub ]

  
# File 'numeric.c', line 2427

static VALUE
num_floor(int argc, VALUE *argv, VALUE num)
{
    return flo_floor(argc, argv, rb_Float(num));
}

#iComplex(0, num)

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

-42.i  #=> (0-42i)
2.0.i  #=> (0+2.0i)
[ GitHub ]

  
# File 'numeric.c', line 549

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

#imag0 #imaginary0
Also known as: #imaginary

Returns zero.

[ GitHub ]

  
# File 'complex.c', line 2107

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

#imag0 #imaginary0

Alias for #imag.

#absNumeric #magnitudeNumeric

Alias for #abs.

#modulo(numeric) ⇒ Numeric #modulo(numeric) ⇒ Numeric

Alias for #%.

#numeratorInteger

Returns the numerator.

[ GitHub ]

  
# File 'rational.c', line 1970

static VALUE
numeric_numerator(VALUE self)
{
    return f_numerator(f_to_r(self));
}

#arg0, Float #angle0, Float #phase0, Float

Alias for #arg.

#polarArray

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

[ GitHub ]

  
# File 'complex.c', line 2162

static VALUE
numeric_polar(VALUE self)
{
    VALUE abs, arg;

    if (RB_INTEGER_TYPE_P(self)) {
        abs = rb_int_abs(self);
        arg = numeric_arg(self);
    }
    else if (RB_FLOAT_TYPE_P(self)) {
        abs = rb_float_abs(self);
        arg = float_arg(self);
    }
    else if (RB_TYPE_P(self, T_RATIONAL)) {
        abs = rb_rational_abs(self);
        arg = numeric_arg(self);
    }
    else {
        abs = f_abs(self);
        arg = f_arg(self);
    }
    return rb_assoc_new(abs, arg);
}

#quo(int_or_rat) ⇒ rat #quo(flo) ⇒ flo

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

[ GitHub ]

  
# File 'rational.c', line 1997

VALUE
rb_numeric_quo(VALUE x, VALUE y)
{
    if (RB_FLOAT_TYPE_P(y)) {
        return rb_funcall(x, rb_intern("fdiv"), 1, y);
    }

    if (canonicalization) {
        x = rb_rational_raw1(x);
    }
    else {
        x = rb_convert_type(x, T_RATIONAL, "Rational", "to_r");
    }
    return nurat_div(x, y);
}

#rectArray #rectangularArray
Also known as: #rectangular

Returns an array; [num, 0].

[ GitHub ]

  
# File 'complex.c', line 2148

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

#rectArray #rectangularArray

Alias for #rect.

#remainder(numeric) ⇒ Numeric

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

See #divmod.

[ GitHub ]

  
# File 'numeric.c', line 633

static VALUE
num_remainder(VALUE x, VALUE y)
{
    VALUE z = num_funcall1(x, '%', y);

    if ((!rb_equal(z, INT2FIX(0))) &&
	((rb_num_negative_int_p(x) &&
	  rb_num_positive_int_p(y)) ||
	 (rb_num_positive_int_p(x) &&
	  rb_num_negative_int_p(y)))) {
	return rb_funcall(z, '-', 1, y);
    }
    return z;
}

#round([ndigits]) ⇒ Integer, Float

Returns num rounded to the nearest value with a precision of ndigits decimal digits (default: 0).

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

[ GitHub ]

  
# File 'numeric.c', line 2461

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

#singleton_method_added(name)

This method is for internal use only.

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

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

[ GitHub ]

  
# File 'numeric.c', line 479

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_RETURN(Qnil);
}

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

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 floor(n + n*Float::EPSILON) + 1 times, where 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. Especially, the enumerator is an ::Enumerator::ArithmeticSequence if both limit and step are kind of Numeric or nil.

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.718281828459045 2.9182818284590453 3.118281828459045
[ GitHub ]

  
# File 'numeric.c', line 2740

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

    if (!rb_block_given_p()) {
        VALUE by = Qundef;

        num_step_extract_args(argc, argv, &to, &step, &by);
        if (by != Qundef) {
            step = by;
        }
        if (NIL_P(step)) {
            step = INT2FIX(1);
        }
        if ((NIL_P(to) || rb_obj_is_kind_of(to, rb_cNumeric)) &&
            rb_obj_is_kind_of(step, rb_cNumeric)) {
            return rb_arith_seq_new(from, ID2SYM(rb_frame_this_func()), argc, argv,
                                    num_step_size, from, to, step, FALSE);
        }

        RETURN_SIZED_ENUMERATOR(from, argc, argv, num_step_size);
    }

    desc = num_step_scan_args(argc, argv, &to, &step, TRUE, FALSE);
    if (rb_equal(step, INT2FIX(0))) {
	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, 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_cComplex

Returns the value as a complex.

[ GitHub ]

  
# File 'complex.c', line 1639

static VALUE
numeric_to_c(VALUE self)
{
    return rb_complex_new1(self);
}

#to_intInteger

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

1.0.class          #=> Float
1.0.to_int.class   #=> Integer
1.0.to_i.class     #=> Integer
[ GitHub ]

  
# File 'numeric.c', line 834

static VALUE
num_to_int(VALUE num)
{
    return num_funcall0(num, id_to_i);
}

#truncate([ndigits]) ⇒ Integer, Float

Returns num truncated (toward zero) to a precision of ndigits decimal digits (default: 0).

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

[ GitHub ]

  
# File 'numeric.c', line 2478

static VALUE
num_truncate(int argc, VALUE *argv, VALUE num)
{
    return flo_truncate(argc, argv, rb_Float(num));
}