1#@!#!123s

: / opt / alt / ruby31 / include / ruby / internal / intern /
Filename : rational.h
back
#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 */