ruby-changes:67772
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:01:48 +0900 (JST)
Subject: [ruby-changes:67772] 14e6e122e7 (master): include/ruby/internal/intern/numeric.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=14e6e122e7 From 14e6e122e73fc0b5a05a68e277895c6b965092b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= <shyouhei@r...> Date: Fri, 12 Mar 2021 14:16:11 +0900 Subject: include/ruby/internal/intern/numeric.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/internal/intern/numeric.h | 185 +++++++++++++++++++++++++++++++-- 1 file changed, 175 insertions(+), 10 deletions(-) diff --git a/include/ruby/internal/intern/numeric.h b/include/ruby/internal/intern/numeric.h index 7b6578c..30863fb 100644 --- a/include/ruby/internal/intern/numeric.h +++ b/include/ruby/internal/intern/numeric.h @@ -20,22 +20,187 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/numeric.h#L20 * extension libraries. They could be written in C++98. * @brief Public APIs related to ::rb_cNumeric. */ +#include "ruby/internal/attr/cold.h" +#include "ruby/internal/attr/noreturn.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" -#include "ruby/backward/2/attributes.h" + +/** + * @private + * + * @deprecated This macro once was a thing in the old days, but makes no sense + * any longer today. Exists here for backwards compatibility + * only. You can safely forget about it. + */ +#define RB_NUM_COERCE_FUNCS_NEED_OPID 1 RBIMPL_SYMBOL_EXPORT_BEGIN() /* numeric.c */ -NORETURN(void rb_num_zerodiv(void)); -#define RB_NUM_COERCE_FUNCS_NEED_OPID 1 -VALUE rb_num_coerce_bin(VALUE, VALUE, ID); -VALUE rb_num_coerce_cmp(VALUE, VALUE, ID); -VALUE rb_num_coerce_relop(VALUE, VALUE, ID); -VALUE rb_num_coerce_bit(VALUE, VALUE, ID); -VALUE rb_num2fix(VALUE); -VALUE rb_fix2str(VALUE, int); -CONSTFUNC(VALUE rb_dbl_cmp(double, double)); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_COLD() +/** + * Just always raises an exception. + * + * @exception rb_eZeroDivError Division by zero error. + */ +void rb_num_zerodiv(void); + +/** + * @name Coercion operators. + * + * What is a coercion? Well Ruby is basically an OOPL but it also has + * arithmetic operators. They are implemented in OO manners. For instance + * `a+b` is a binary operation `+`, whose receiver is `a`, and whose (sole) + * argument is `b`. + * + * The problem is, you often want `a+b == b+a` to hold. That is easy if both + * `a` and `b` belongs to the same class... Ensuring `1 + 2 == 2 + 1` is kind + * of intuitive. But if you want `1.0 + 2 == 2 + 1.0`, things start getting + * complicated. `1.0+2` is `Float#+`, while `2+1.0` is `Integer#+`. In order + * to achieve the equality Float's and Integer's methods must agree with their + * behaviours. + * + * Now. Floats versus Integers situation is still controllable because they + * are both built-in. But in Ruby you can define your own numeric classes. + * BigDecimal, which is a rubygems gem distributed along with the interpreter, + * is one of such examples. Rational was another such example before. In + * short you cannot create list of all possible combination of the classes that + * could be the operand of `+` operator. Then how do we achieve the + * commutativity? + * + * Here comes the concept of coercion. If a definition of an operator + * encounters an object which is unknown to the author, just assumes that the + * unknown object knows how to handle the situation. So for instance when + * `1+x` has unknown `x`, it lets the `x` handle this. + * + * ```ruby + * class Foo + * def +(x) + * if we_know_what_is_x? then + * ... # handle here + * else + * y, z = x.coerce self + * return y + z + * end + * end + * end + * ``` + * + * The `x.coerce` method returns a 2-element array which are "casted" versions + * of `x` and `self`. + * + * @{ + */ + +/** + * Coerced binary operation. This function first coerces the two objects, then + * applies the operation. + * + * @param[in] lhs LHS operand. + * @param[in] rhs RHS operand. + * @param[in] op Operator method name. + * @exception rb_eTypeError Coercion failed for some reason. + * @return `lhs op rhs`, in a coerced way. + */ +VALUE rb_num_coerce_bin(VALUE lhs, VALUE rhs, ID op); + +/** + * Identical to rb_num_coerce_bin(), except for return values. This function + * best suits for comparison operators e.g. `<=>`. + * + * @param[in] lhs LHS operand. + * @param[in] rhs RHS operand. + * @param[in] op Operator method name. + * @retval RUBY_Qnil Coercion failed for some reason. + * @retval otherwise `lhs op rhs`, in a coerced way. + */ +VALUE rb_num_coerce_cmp(VALUE lhs, VALUE rhs, ID op); + +/** + * Identical to rb_num_coerce_cmp(), except for return values. This function + * best suits for relationship operators e.g. `<=`. + * + * @param[in] lhs LHS operand. + * @param[in] rhs RHS operand. + * @param[in] op Operator method name. + * @exception rb_eArgError Coercion failed for some reason. + * @return `lhs op rhs`, in a coerced way. + */ +VALUE rb_num_coerce_relop(VALUE lhs, VALUE rhs, ID op); + +/** + * This one is optimised for bitwise operations, but the API is identical to + * rb_num_coerce_bin(). + * + * @param[in] lhs LHS operand. + * @param[in] rhs RHS operand. + * @param[in] op Operator method name. + * @exception rb_eArgError Coercion failed for some reason. + * @return `lhs op rhs`, in a coerced way. + */ +VALUE rb_num_coerce_bit(VALUE lhs, VALUE rhs, ID op); + +/** @} */ + +/** + * Converts a numeric value into a Fixnum. This is not a preserving + * conversion; for instance 1.5 would be converted into 1. + * + * @param[in] val A numeric object. + * @exception rb_eTypeError No conversion from `val` to Integer. + * @exception rb_eRangeError `val` out of range. + * @return A fixnum converted from `val`. + * + * @internal + * + * This seems used from nowhere? + */ +VALUE rb_num2fix(VALUE val); + +/** + * Generates a place-value representation of the given Fixnum, with given + * radix. + * + * @param[in] val A fixnum to stringify. + * @param[in] base `2` to `36` inclusive for each radix. + * @exception rb_eArgError `base` is out of range. + * @return An instance of ::rb_cString representing `val`. + * @pre `val` must be a Fixnum (no checks performed). + */ +VALUE rb_fix2str(VALUE val, int base); + +RBIMPL_ATTR_CONST() +/** + * Compares two `double`s. Handy when implementing a spaceship operator. + * + * @param[in] lhs A value. + * @param[in] rhs Another value. + * @retval RB_INT2FIX(-1) `lhs` is "bigger than" `rhs`. + * @retval RB_INT2FIX(1) `rhs` is "bigger than" `lhs`. + * @retval RB_INT2FIX(0) They are equal. + * @retval RUBY_Qnil Not comparable, e.g. NaN. + */ +VALUE rb_dbl_cmp(double lhs, double rhs); + +/** + * Raises the passed `x` to the power of `y`. + * + * @note The return value can be really big. + * @note Also the return value can be really small, in case `x` is a + * negative number. + * @param[in] x A number. + * @param[in] y Another number. + * @retval Inf Cannot express the result. + * @retval 1 Either `y` is 0 or `x` is 1. + * @retval otherwise An instance of ::rb_cInteger whose value is `x ** y`. + * + * @internal + * + * This function returns Infinity when `y` is big enough not to fit into a + * Fixnum. Warning is issued then. + */ RUBY_EXTERN VALUE rb_int_positive_pow(long x, unsigned long y); RBIMPL_SYMBOL_EXPORT_END() -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/