← Back
Editing: rational.h
#ifndef RBIMPL_INTERN_RATIONAL_H /*-*-C++-*-vi:se ft=cpp:*/ #define RBIMPL_INTERN_RATIONAL_H /** * @file * @author Ruby developers <ruby-core@ruby-lang.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. * @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. */ RBIMPL_SYMBOL_EXPORT_BEGIN() /* rational.c */ /** * 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)) /** * 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)) /** * 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); /** * 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() #endif /* RBIMPL_INTERN_RATIONAL_H */
Save File
Cancel