Ruby: include/ruby/internal/intern/numeric.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Macros | Functions
numeric.h File Reference

Public APIs related to rb_cNumeric. More...

`#include "ruby/internal/attr/cold.h"`
`#include "ruby/internal/attr/noreturn.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Macros
#define | RB_NUM_COERCE_FUNCS_NEED_OPID 1

## Functions
void | rb_num_zerodiv (void)
| Just always raises an exception.
VALUE | rb_num2fix (VALUE val)
| Converts a numeric value into a Fixnum.
VALUE | rb_fix2str (VALUE val, int base)
| Generates a place-value representation of the given Fixnum, with given radix.
VALUE | rb_dbl_cmp (double lhs, double rhs)
| Compares two `double`s.
VALUE | rb_int_positive_pow (long x, unsigned long y)
| Raises the passed `x` to the power of `y`.
Coercion operators.
What is a coercion? Well Ruby is basically an OOPL but it also has arithmetic operators. They are implemented in OO manners. For instance `a+b` is a binary operation `+`, whose receiver is `a`, and whose (sole) argument is `b`. The problem is, you often want `a+b == b+a` to hold. That is easy if both `a` and `b` belongs to the same class... Ensuring `1 + 2 == 2 + 1` is kind of intuitive. But if you want `1.0 + 2 == 2 + 1.0`, things start getting complicated. `1.0+2` is `Float#+`, while `2+1.0` is `Integer#+`. In order to achieve the equality Float's and Integer's methods must agree with their behaviours. Now. Floats versus Integers situation is still controllable because they are both built-in. But in Ruby you can define your own numeric classes. BigDecimal, which is a rubygems gem distributed along with the interpreter, is one of such examples. Rational was another such example before. In short you cannot create list of all possible combination of the classes that could be the operand of `+` operator. Then how do we achieve the commutativity? Here comes the concept of coercion. If a definition of an operator encounters an object which is unknown to the author, just assumes that the unknown object knows how to handle the situation. So for instance when `1+x` has unknown `x`, it lets the `x` handle this. class Foo def +(x) if we_know_what_is_x? then ... # handle here else y, z = x.coerce self return y + z end end end The `x.coerce` method returns a 2-element array which are "casted" versions of `x` and `self`.
VALUE | rb_num_coerce_bin (VALUE lhs, VALUE rhs, ID op)
| Coerced binary operation.
VALUE | rb_num_coerce_cmp (VALUE lhs, VALUE rhs, ID op)
| Identical to rb_num_coerce_bin(), except for return values.
VALUE | rb_num_coerce_relop (VALUE lhs, VALUE rhs, ID op)
| Identical to rb_num_coerce_cmp(), except for return values.
VALUE | rb_num_coerce_bit (VALUE lhs, VALUE rhs, ID op)
| This one is optimised for bitwise operations, but the API is identical to rb_num_coerce_bin().

## Detailed Description

Public APIs related to rb_cNumeric.

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either `RBIMPL` or `rbimpl` are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance `__VA_ARGS__` is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file numeric.h.

## Macro Definition Documentation

## ◆ RB_NUM_COERCE_FUNCS_NEED_OPID

#define RB_NUM_COERCE_FUNCS_NEED_OPID 1

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 35 of file numeric.h.

## Function Documentation

## ◆ rb_dbl_cmp()

VALUE rb_dbl_cmp | ( | double | lhs,
|  | double | rhs )

Compares two `double`s.

Handy when implementing a spaceship operator.

Parameters

  [in] | lhs | A value.
  [in] | rhs | Another value.

Return values

  RB_INT2FIX(-1) | `lhs` is "bigger than" `rhs`.
  RB_INT2FIX(1) | `rhs` is "bigger than" `lhs`.
  RB_INT2FIX(0) | They are equal.
  RUBY_Qnil | Not comparable, e.g. NaN.

Definition at line 1661 of file numeric.c.

Referenced by rb_dbl_cmp().

## ◆ rb_fix2str()

VALUE rb_fix2str | ( | VALUE | val,
|  | int | base )

Generates a place-value representation of the given Fixnum, with given radix.

Parameters

  [in] | val | A fixnum to stringify.
  [in] | base | `2` to `36` inclusive for each radix.

Exceptions

  rb_eArgError | `base` is out of range.

Returns
  An instance of rb_cString representing `val`.

Precondition
  `val` must be a Fixnum (no checks performed).

Definition at line 3853 of file numeric.c.

Referenced by rb_fix2str().

## ◆ rb_int_positive_pow()

VALUE rb_int_positive_pow | ( | long | x,
|  | unsigned long | y )
| extern

Raises the passed `x` to the power of `y`.

Note
  The return value can be really big.
  Also the return value can be really small, in case `x` is a negative number.

Parameters

  [in] | x | A number.
  [in] | y | Another number.

Return values

  Inf | Cannot express the result.
  1 | Either `y` is 0 or `x` is 1.
  otherwise | An instance of rb_cInteger whose value is `x ** y`.

Definition at line 4492 of file numeric.c.

Referenced by rb_flt_rationalize(), rb_int_positive_pow(), and rb_str_format().

## ◆ rb_num2fix()

VALUE rb_num2fix | ( | VALUE | val | ) |

Converts a numeric value into a Fixnum.

This is not a preserving conversion; for instance 1.5 would be converted into 1.

Parameters

  [in] | val | A numeric object.

Exceptions

  rb_eTypeError | No conversion from `val` to Integer.
  rb_eRangeError | `val` out of range.

Returns
  A fixnum converted from `val`.

Definition at line 3382 of file numeric.c.

Referenced by rb_num2fix().

## ◆ rb_num_coerce_bin()

VALUE rb_num_coerce_bin | ( | VALUE | lhs,
|  | VALUE | rhs,
|  | ID | op )

Coerced binary operation.

This function first coerces the two objects, then applies the operation.

Parameters

  [in] | lhs | LHS operand.
  [in] | rhs | RHS operand.
  [in] | op | Operator method name.

Exceptions

  rb_eTypeError | Coercion failed for some reason.

Returns
  `lhs op rhs`, in a coerced way.

Definition at line 471 of file numeric.c.

Referenced by rb_big_divmod(), rb_big_minus(), rb_big_modulo(), rb_big_mul(), rb_big_plus(), rb_big_pow(), rb_complex_minus(), rb_complex_mul(), rb_complex_plus(), and rb_complex_pow().

## ◆ rb_num_coerce_bit()

VALUE rb_num_coerce_bit | ( | VALUE | lhs,
|  | VALUE | rhs,
|  | ID | op )

This one is optimised for bitwise operations, but the API is identical to rb_num_coerce_bin().

Parameters

  [in] | lhs | LHS operand.
  [in] | rhs | RHS operand.
  [in] | op | Operator method name.

Exceptions

  rb_eArgError | Coercion failed for some reason.

Returns
  `lhs op rhs`, in a coerced way.

Definition at line 4923 of file numeric.c.

Referenced by rb_big_and(), rb_big_or(), rb_big_xor(), and rb_num_coerce_bit().

## ◆ rb_num_coerce_cmp()

VALUE rb_num_coerce_cmp | ( | VALUE | lhs,
|  | VALUE | rhs,
|  | ID | op )

Identical to rb_num_coerce_bin(), except for return values.

This function best suits for comparison operators e.g. `<=>`.

Parameters

  [in] | lhs | LHS operand.
  [in] | rhs | RHS operand.
  [in] | op | Operator method name.

Return values

  RUBY_Qnil | Coercion failed for some reason.
  otherwise | `lhs op rhs`, in a coerced way.

Definition at line 478 of file numeric.c.

Referenced by rb_big_cmp().

## ◆ rb_num_coerce_relop()

VALUE rb_num_coerce_relop | ( | VALUE | lhs,
|  | VALUE | rhs,
|  | ID | op )

Identical to rb_num_coerce_cmp(), except for return values.

This function best suits for relationship operators e.g. `<=`.

Parameters

  [in] | lhs | LHS operand.
  [in] | rhs | RHS operand.
  [in] | op | Operator method name.

Exceptions

  rb_eArgError | Coercion failed for some reason.

Returns
  `lhs op rhs`, in a coerced way.

Definition at line 493 of file numeric.c.

## ◆ rb_num_zerodiv()

void rb_num_zerodiv | ( | void |  | ) |

Just always raises an exception.

Exceptions

  rb_eZeroDivError | Division by zero error.

Definition at line 200 of file numeric.c.