ruby-changes:67811
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:02:15 +0900 (JST)
Subject: [ruby-changes:67811] 5e1caeb15c (master): include/ruby/internal/arithmetic/int.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=5e1caeb15c From 5e1caeb15ce7590621facf93d87207e73dd8a3a9 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: Mon, 25 Jan 2021 10:37:46 +0900 Subject: include/ruby/internal/arithmetic/int.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/internal/arithmetic/int.h | 127 +++++++++++++++++++++++++++++---- 1 file changed, 114 insertions(+), 13 deletions(-) diff --git a/include/ruby/internal/arithmetic/int.h b/include/ruby/internal/arithmetic/int.h index 7ae89ae..6bd8ec2 100644 --- a/include/ruby/internal/arithmetic/int.h +++ b/include/ruby/internal/arithmetic/int.h @@ -34,16 +34,16 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/int.h#L34 #include "ruby/internal/warning_push.h" #include "ruby/assert.h" -#define RB_INT2NUM rb_int2num_inline -#define RB_NUM2INT rb_num2int_inline -#define RB_UINT2NUM rb_uint2num_inline +#define RB_INT2NUM rb_int2num_inline /**< @alias{rb_int2num_inline} */ +#define RB_NUM2INT rb_num2int_inline /**< @alias{rb_num2int_inline} */ +#define RB_UINT2NUM rb_uint2num_inline /**< @alias{rb_uint2num_inline} */ -#define FIX2INT RB_FIX2INT -#define FIX2UINT RB_FIX2UINT -#define INT2NUM RB_INT2NUM -#define NUM2INT RB_NUM2INT -#define NUM2UINT RB_NUM2UINT -#define UINT2NUM RB_UINT2NUM +#define FIX2INT RB_FIX2INT /**< @old{RB_FIX2INT} */ +#define FIX2UINT RB_FIX2UINT /**< @old{RB_FIX2UINT} */ +#define INT2NUM RB_INT2NUM /**< @old{RB_INT2NUM} */ +#define NUM2INT RB_NUM2INT /**< @old{RB_NUM2INT} */ +#define NUM2UINT RB_NUM2UINT /**< @old{RB_NUM2UINT} */ +#define UINT2NUM RB_UINT2NUM /**< @old{RB_UINT2NUM} */ /** @cond INTERNAL_MACRO */ #define RB_FIX2INT RB_FIX2INT @@ -52,13 +52,79 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/int.h#L52 /** @endcond */ RBIMPL_SYMBOL_EXPORT_BEGIN() -long rb_num2int(VALUE); -long rb_fix2int(VALUE); -unsigned long rb_num2uint(VALUE); -unsigned long rb_fix2uint(VALUE); + +/** + * Converts an instance of ::rb_cNumeric into C's `long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `int`. + * @return The passed value converted into C's `long`. + * + * @internal + * + * Yes, the API is really strange. It returns `long`, but raises when the + * value is out of `int`. This seems to be due to the fact that Matz favoured + * K&R before, and his machine at that moment was an ILP32 architecture. + */ +long rb_num2int(VALUE num); + +/** + * Identical to rb_num2int(). + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `int`. + * @return The passed value converted into C's `long`. + * + * @internal + * + * This function seems to be a complete waste of disk space. @shyouhei has no + * idea why this is a different thing from rb_num2short(). + */ +long rb_fix2int(VALUE num); + +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned int`. + * @return The passed value converted into C's `unsigned long`. + * + * @internal + * + * Yes, the API is really strange. It returns `unsigned long`, but raises when + * the value is out of `unsigned int`. This seems to be due to the fact that + * Matz favoured K&R before, and his machine at that moment was an ILP32 + * architecture. + */ +unsigned long rb_num2uint(VALUE num); + +/** + * Identical to rb_num2uint(). + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned int`. + * @return The passed value converted into C's `unsigned long`. + * + * @internal + * + * This function seems to be a complete waste of disk space. @shyouhei has no + * idea why this is a different thing from rb_num2short(). + */ +unsigned long rb_fix2uint(VALUE num); RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_ARTIFICIAL() +/** + * Converts a Fixnum into C's `int`. + * + * @param[in] x Some Fixnum. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `int`. + */ static inline int RB_FIX2INT(VALUE x) { @@ -80,6 +146,14 @@ RB_FIX2INT(VALUE x) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/int.h#L146 return RBIMPL_CAST((int)ret); } +/** + * Converts an instance of ::rb_cNumeric into C's `int`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `int`. + * @return The passed value converted into C's `int`. + */ static inline int rb_num2int_inline(VALUE x) { @@ -98,6 +172,14 @@ rb_num2int_inline(VALUE x) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/int.h#L172 return RBIMPL_CAST((int)ret); } +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned int`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `unsigned int`. + * @return The passed value converted into C's `unsigned int`. + */ RBIMPL_ATTR_ARTIFICIAL() static inline unsigned int RB_NUM2UINT(VALUE x) @@ -115,6 +197,13 @@ RB_NUM2UINT(VALUE x) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/int.h#L197 } RBIMPL_ATTR_ARTIFICIAL() +/** + * Converts a Fixnum into C's `int`. + * + * @param[in] x Some Fixnum. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `int`. + */ static inline unsigned int RB_FIX2UINT(VALUE x) { @@ -140,6 +229,12 @@ RBIMPL_WARNING_IGNORED(-Wtype-limits) /* We can ignore them here. */ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/int.h#L229 RBIMPL_WARNING_IGNORED(-Wtautological-constant-out-of-range-compare) #endif +/** + * Converts a C's `int` into an instance of ::rb_cInteger. + * + * @param[in] v Arbitrary `int` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE rb_int2num_inline(int v) { @@ -149,6 +244,12 @@ rb_int2num_inline(int v) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/arithmetic/int.h#L244 return rb_int2big(v); } +/** + * Converts a C's `unsigned int` into an instance of ::rb_cInteger. + * + * @param[in] v Arbitrary `unsigned int` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE rb_uint2num_inline(unsigned int v) { -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/