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

Ruby 3.4.8p72 (2025-12-17 revision 995b59f66677d44767ce9faac6957e5543617ff9)

Macros | Functions
rational.h File Reference

Public APIs related to rb_cRational. More...

`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/internal/arithmetic/long.h"`
Include dependency graph for rational.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros
#define | rb_rational_raw1(x) rb_rational_raw((x), INT2FIX(1))
| Shorthand of `(x/1)r`.
#define | rb_rational_raw2(x, y) rb_rational_raw((x), (y))
| Just another name of rb_rational_raw.
#define | rb_rational_new1(x) rb_rational_new((x), INT2FIX(1))
| Shorthand of `(x/1)r`.
#define | rb_rational_new2(x, y) rb_rational_new((x), (y))
| Just another name of rb_rational_new.
#define | rb_Rational1(x) rb_Rational((x), INT2FIX(1))
| Shorthand of `(x/1)r`.
#define | rb_Rational2(x, y) rb_Rational((x), (y))
| Just another name of rb_Rational.

## Functions
VALUE | rb_rational_raw (VALUE num, VALUE den)
| Identical to rb_rational_new(), except it skips argument validations.
VALUE | rb_rational_new (VALUE num, VALUE den)
| Constructs a Rational, with reduction.
VALUE | rb_Rational (VALUE num, VALUE den)
| Converts various values into a Rational.
VALUE | rb_rational_num (VALUE rat)
| Queries the numerator of the passed Rational.
VALUE | rb_rational_den (VALUE rat)
| Queries the denominator of the passed Rational.
VALUE | rb_flt_rationalize_with_prec (VALUE flt, VALUE prec)
| Simplified approximation of a float.
VALUE | rb_flt_rationalize (VALUE flt)
| Identical to rb_flt_rationalize_with_prec(), except it auto-detects appropriate precision depending on the passed value.

## Detailed Description

Public APIs related to rb_cRational.

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 rational.h.

## Macro Definition Documentation

## ◆ rb_Rational1

#define rb_Rational1 | ( |  | x | ) | rb_Rational((x), INT2FIX(1))

Shorthand of `(x/1)r`.

It practically converts it into a Rational of the identical value.

Parameters

  [in] | x | rb_cInteger, rb_cRational, or something that responds to `#to_r`.

Returns
  An instance of rb_cRational, whose value is `(x/1)r`.

Definition at line 116 of file rational.h.

## ◆ rb_Rational2

#define rb_Rational2 | ( |  | x,
|  |  | y
| ) |  | rb_Rational((x), (y))

Just another name of rb_Rational.

Definition at line 119 of file rational.h.

## ◆ rb_rational_new1

#define rb_rational_new1 | ( |  | x | ) | rb_rational_new((x), INT2FIX(1))

Shorthand of `(x/1)r`.

As `x` is already an Integer, it practically converts it into a Rational of the identical value.

Parameters

  [in] | x | An instance of rb_cInteger.

Returns
  An instance of rb_cRational, whose value is `(x/1)r`.

Definition at line 74 of file rational.h.

## ◆ rb_rational_new2

#define rb_rational_new2 | ( |  | x,
|  |  | y
| ) |  | rb_rational_new((x), (y))

Just another name of rb_rational_new.

Definition at line 77 of file rational.h.

## ◆ rb_rational_raw1

#define rb_rational_raw1 | ( |  | x | ) | rb_rational_raw((x), INT2FIX(1))

Shorthand of `(x/1)r`.

As `x` is already an Integer, it practically converts it into a Rational of the identical value.

Parameters

  [in] | x | An instance of rb_cInteger.

Returns
  An instance of rb_cRational, whose value is `(x/1)r`.

Definition at line 51 of file rational.h.

## ◆ rb_rational_raw2

#define rb_rational_raw2 | ( |  | x,
|  |  | y
| ) |  | rb_rational_raw((x), (y))

Just another name of rb_rational_raw.

Definition at line 54 of file rational.h.

## Function Documentation

## ◆ rb_flt_rationalize()

VALUE rb_flt_rationalize | ( | VALUE | flt | ) |

Identical to rb_flt_rationalize_with_prec(), except it auto-detects appropriate precision depending on the passed value.

Parameters

  [in] | flt | An instance of rb_cFloat to rationalise.

Returns
  Approximation of `flt`, in rb_cRational.

Definition at line 2242 of file rational.c.

Referenced by rb_flt_rationalize().

## ◆ rb_flt_rationalize_with_prec()

VALUE rb_flt_rationalize_with_prec | ( | VALUE | flt,
|  | VALUE | prec
| ) |  |

Simplified approximation of a float.

It returns a rational `rat` which satisfies:

flt - |prec| <= rat <= flt + |prec|
3.141592.rationalize(0.001) # => (201/64)r
3.141592.rationalize(0.01)' # => (22/7)r
3.141592.rationalize(0.1)' # => (16/5)r
3.141592.rationalize(1)' # => (3/1)r

Parameters

  [in] | flt | An instance of rb_cFloat to rationalise.
  [in] | prec | Another rb_cFloat, which is the "precision".

Returns
  Approximation of `flt`, in rb_cRational.

Definition at line 2226 of file rational.c.

Referenced by rb_flt_rationalize_with_prec().

## ◆ rb_Rational()

VALUE rb_Rational | ( | VALUE | num,
|  | VALUE | den
| ) |  |

Converts various values into a Rational.

This function accepts:

- Instances of rb_cInteger (taken as-is),
- Instances of rb_cRational (taken as-is),
- Instances of rb_cFloat (applies `#to_r`),
- Instances of rb_cComplex (applies `#to_r`),
- Instances of rb_cString (applies `#to_r`),
- Other objects that respond to `#to_r`.

It (possibly recursively) applies `#to_r` until both sides become either Integer or Rational, then divides them.

As a special case, passing RUBY_Qundef to `den` is the same as passing `RB_INT2NUM(1)`.

Parameters

  [in] | num | Numerator (see above).
  [in] | den | Denominator (see above).

Exceptions

  rb_eTypeError | Passed something not described above.
  rb_eFloatDomainError | `#to_r` produced Nan/Inf.
  rb_eZeroDivError | `#to_r` produced zero for `den`.

Returns
  An instance of rb_cRational whose value is `(num/den)r`.

Definition at line 1980 of file rational.c.

Referenced by rb_Rational().

## ◆ rb_rational_den()

VALUE rb_rational_den | ( | VALUE | rat | ) |

Queries the denominator of the passed Rational.

Parameters

  [in] | rat | An instance of rb_cRational.

Returns
  Its denominator part, which is an instance of rb_cInteger greater than or equal to one..

Definition at line 1995 of file rational.c.

Referenced by rb_rational_den(), and rb_str_format().

## ◆ rb_rational_new()

VALUE rb_rational_new | ( | VALUE | num,
|  | VALUE | den
| ) |  |

Constructs a Rational, with reduction.

This returns for instance `(2/3)r` for `rb_rational_new(INT2NUM(-384), INT2NUM(-576))`.

Parameters

  [in] | num | Numerator, an instance of rb_cInteger.
  [in] | den | Denominator, an instance of rb_cInteger.

Exceptions

  rb_eZeroDivError | `den` is zero.

Returns
  An instance of rb_cRational whose value is `(num/den)r`.

Definition at line 1974 of file rational.c.

Referenced by rb_rational_new().

## ◆ rb_rational_num()

VALUE rb_rational_num | ( | VALUE | rat | ) |

Queries the numerator of the passed Rational.

Parameters

  [in] | rat | An instance of rb_cRational.

Returns
  Its numerator part, which is an instance of rb_cInteger.

Definition at line 1989 of file rational.c.

Referenced by rb_rational_num(), and rb_str_format().

## ◆ rb_rational_raw()

VALUE rb_rational_raw | ( | VALUE | num,
|  | VALUE | den
| ) |  |

Identical to rb_rational_new(), except it skips argument validations.

It is thus dangerous for extension libraries. For instance `1/0r` could be constructed using this.

Parameters

  [in] | num | Numerator, an instance of rb_cInteger.
  [in] | den | Denominator, an instance of rb_cInteger.

Exceptions

  rb_eTypeError | Either argument is not an Integer.

Returns
  An instance of rb_cRational whose value is `(num/den)r`.

Definition at line 1960 of file rational.c.

Referenced by rb_big_pow(), and rb_rational_raw().