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

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

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"`

Go to the source code of this file.

## Macros
#define | rb_rational_raw1(x)
| Shorthand of `(x/1)r`.
#define | rb_rational_raw2(x, y)
| Just another name of rb_rational_raw.
#define | rb_rational_new1(x)
| Shorthand of `(x/1)r`.
#define | rb_rational_new2(x, y)
| Just another name of rb_rational_new.
#define | rb_Rational1(x)
| Shorthand of `(x/1)r`.
#define | rb_Rational2(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 | ) |

Value:
rb_Rational((x), INT2FIX(1))
INT2FIX
#define INT2FIX
Old name of RB_INT2FIX.
Definition long.h:48
rb_Rational
VALUE rb_Rational(VALUE num, VALUE den)
Converts various values into a Rational.
Definition rational.c:1975

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 )

Value:
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 | ) |

Value:
rb_rational_new((x), INT2FIX(1))
rb_rational_new
VALUE rb_rational_new(VALUE num, VALUE den)
Constructs a Rational, with reduction.
Definition rational.c:1969

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.

Referenced by rb_flt_rationalize().

## ◆ rb_rational_new2

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

Value:
rb_rational_new((x), (y))

Just another name of rb_rational_new.

Definition at line 77 of file rational.h.

Referenced by rb_flt_rationalize(), and rb_flt_rationalize_with_prec().

## ◆ rb_rational_raw1

#define rb_rational_raw1 | ( |  | x | ) |

Value:
rb_rational_raw((x), INT2FIX(1))
rb_rational_raw
VALUE rb_rational_raw(VALUE num, VALUE den)
Identical to rb_rational_new(), except it skips argument validations.
Definition rational.c:1955

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 )

Value:
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 2230 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 2214 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 1975 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 1990 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 1969 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 1984 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 1955 of file rational.c.

Referenced by rb_big_pow(), and rb_rational_raw().