Ruby 3.3.6p108 (2024-11-05 revision 75015d4c1f6965b5e85e96fb309f1f2129f933c0)
rational.h File Reference

Public APIs related to rb_cRational. More...

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
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:
#define INT2FIX
Old name of RB_INT2FIX.
Definition long.h:48
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]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,
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))

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.

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

Definition at line 2237 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]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 2221 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:

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 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]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 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]numNumerator, an instance of rb_cInteger.
[in]denDenominator, 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.

◆ 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 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]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 1955 of file rational.c.

Referenced by rb_big_pow(), and rb_rational_raw().