diff options
Diffstat (limited to 'include/ruby/internal/intern/rational.h')
| -rw-r--r-- | include/ruby/internal/intern/rational.h | 138 |
1 files changed, 132 insertions, 6 deletions
diff --git a/include/ruby/internal/intern/rational.h b/include/ruby/internal/intern/rational.h index 30a87ff31f..ff4beca297 100644 --- a/include/ruby/internal/intern/rational.h +++ b/include/ruby/internal/intern/rational.h @@ -17,9 +17,10 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Public APIs related to ::rb_cRational. */ +#include "ruby/internal/attr/pure.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" #include "ruby/internal/arithmetic/long.h" /* INT2FIX is here. */ @@ -27,19 +28,144 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* rational.c */ -VALUE rb_rational_raw(VALUE, VALUE); + +/** + * 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. + * + * @param[in] num Numerator, an instance of ::rb_cInteger. + * @param[in] den Denominator, an instance of ::rb_cInteger. + * @exception rb_eTypeError Either argument is not an Integer. + * @return An instance of ::rb_cRational whose value is `(num/den)r`. + */ +VALUE rb_rational_raw(VALUE num, VALUE den); + +/** + * Shorthand of `(x/1)r`. As `x` is already an Integer, it practically + * converts it into a Rational of the identical value. + * + * @param[in] x An instance of ::rb_cInteger. + * @return An instance of ::rb_cRational, whose value is `(x/1)r`. + */ #define rb_rational_raw1(x) rb_rational_raw((x), INT2FIX(1)) + +/** @alias{rb_rational_raw} */ #define rb_rational_raw2(x,y) rb_rational_raw((x), (y)) -VALUE rb_rational_new(VALUE, VALUE); + +/** + * Constructs a Rational, with reduction. This returns for instance `(2/3)r` + * for `rb_rational_new(INT2NUM(-384), INT2NUM(-576))`. + * + * @param[in] num Numerator, an instance of ::rb_cInteger. + * @param[in] den Denominator, an instance of ::rb_cInteger. + * @exception rb_eZeroDivError `den` is zero. + * @return An instance of ::rb_cRational whose value is `(num/den)r`. + */ +VALUE rb_rational_new(VALUE num, VALUE den); + +/** + * Shorthand of `(x/1)r`. As `x` is already an Integer, it practically + * converts it into a Rational of the identical value. + * + * @param[in] x An instance of ::rb_cInteger. + * @return An instance of ::rb_cRational, whose value is `(x/1)r`. + */ #define rb_rational_new1(x) rb_rational_new((x), INT2FIX(1)) + +/** @alias{rb_rational_new} */ #define rb_rational_new2(x,y) rb_rational_new((x), (y)) -VALUE rb_Rational(VALUE, VALUE); + +/** + * 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)`. + * + * @param[in] num Numerator (see above). + * @param[in] den Denominator (see above). + * @exception rb_eTypeError Passed something not described above. + * @exception rb_eFloatDomainError `#to_r` produced Nan/Inf. + * @exception rb_eZeroDivError `#to_r` produced zero for `den`. + * @return An instance of ::rb_cRational whose value is `(num/den)r`. + * + * @internal + * + * This was the implementation of `Kernel#Rational` before, but they diverged. + */ +VALUE rb_Rational(VALUE num, VALUE den); + +/** + * Shorthand of `(x/1)r`. It practically converts it into a Rational of the + * identical value. + * + * @param[in] x ::rb_cInteger, ::rb_cRational, or something that responds to + * `#to_r`. + * @return An instance of ::rb_cRational, whose value is `(x/1)r`. + */ #define rb_Rational1(x) rb_Rational((x), INT2FIX(1)) + +/** @alias{rb_Rational} */ #define rb_Rational2(x,y) rb_Rational((x), (y)) + +RBIMPL_ATTR_PURE() +/** + * Queries the numerator of the passed Rational. + * + * @param[in] rat An instance of ::rb_cRational. + * @return Its numerator part, which is an instance of ::rb_cInteger. + */ VALUE rb_rational_num(VALUE rat); + +RBIMPL_ATTR_PURE() +/** + * Queries the denominator of the passed Rational. + * + * @param[in] rat An instance of ::rb_cRational. + * @return Its denominator part, which is an instance of ::rb_cInteger + * greater than or equal to one.. + */ VALUE rb_rational_den(VALUE rat); -VALUE rb_flt_rationalize_with_prec(VALUE, VALUE); -VALUE rb_flt_rationalize(VALUE); + +/** + * Simplified approximation of a float. It returns a rational `rat` which + * satisfies: + * + * ``` + * flt - |prec| <= rat <= flt + |prec| + * ``` + * + * ```ruby + * 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 + * ``` + * + * @param[in] flt An instance of ::rb_cFloat to rationalise. + * @param[in] prec Another ::rb_cFloat, which is the "precision". + * @return Approximation of `flt`, in ::rb_cRational. + */ +VALUE rb_flt_rationalize_with_prec(VALUE flt, VALUE prec); + +/** + * Identical to rb_flt_rationalize_with_prec(), except it auto-detects + * appropriate precision depending on the passed value. + * + * @param[in] flt An instance of ::rb_cFloat to rationalise. + * @return Approximation of `flt`, in ::rb_cRational. + */ +VALUE rb_flt_rationalize(VALUE flt); RBIMPL_SYMBOL_EXPORT_END() |