Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
Macros | Functions
rational.h File Reference

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

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

Functions

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

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
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]xrb_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,
 
)    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]xAn 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,
 
)    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]xAn 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,
 
)    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]fltAn instance of rb_cFloat to rationalise.
Returns
Approximation of flt, in rb_cRational.

Definition at line 2243 of file rational.c.

◆ 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]fltAn instance of rb_cFloat to rationalise.
[in]precAnother rb_cFloat, which is the "precision".
Returns
Approximation of flt, in rb_cRational.

Definition at line 2227 of file rational.c.

◆ rb_Rational()

VALUE rb_Rational ( VALUE  num,
VALUE  den 
)

Converts various values into a Rational.

This function accepts:

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]numNumerator (see above).
[in]denDenominator (see above).
Exceptions
rb_eTypeErrorPassed 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 1981 of file rational.c.

◆ rb_rational_den()

VALUE rb_rational_den ( VALUE  rat)

Queries the denominator of the passed Rational.

Parameters
[in]ratAn instance of rb_cRational.
Returns
Its denominator part, which is an instance of rb_cInteger greater than or equal to one..

Definition at line 1996 of file rational.c.

Referenced by 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]numNumerator, an instance of rb_cInteger.
[in]denDenominator, an instance of rb_cInteger.
Exceptions
rb_eZeroDivErrorden is zero.
Returns
An instance of rb_cRational whose value is (num/den)r.

Definition at line 1975 of file rational.c.

◆ rb_rational_num()

VALUE rb_rational_num ( VALUE  rat)

Queries the numerator of the passed Rational.

Parameters
[in]ratAn instance of rb_cRational.
Returns
Its numerator part, which is an instance of rb_cInteger.

Definition at line 1990 of file rational.c.

Referenced by 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]numNumerator, an instance of rb_cInteger.
[in]denDenominator, an instance of rb_cInteger.
Exceptions
rb_eTypeErrorEither argument is not an Integer.
Returns
An instance of rb_cRational whose value is (num/den)r.

Definition at line 1961 of file rational.c.

Referenced by rb_big_pow().