mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
172 lines
6.3 KiB
C++
172 lines
6.3 KiB
C++
#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 */
|