diff options
Diffstat (limited to 'include/ruby/internal/arithmetic')
| -rw-r--r-- | include/ruby/internal/arithmetic/char.h | 31 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/double.h | 49 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/fixnum.h | 32 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/gid_t.h | 5 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/int.h | 129 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/intptr_t.h | 38 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/long.h | 160 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/long_long.h | 85 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/mode_t.h | 5 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/off_t.h | 5 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/pid_t.h | 5 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/short.h | 85 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/size_t.h | 24 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/st_data_t.h | 24 | ||||
| -rw-r--r-- | include/ruby/internal/arithmetic/uid_t.h | 5 |
15 files changed, 579 insertions, 103 deletions
diff --git a/include/ruby/internal/arithmetic/char.h b/include/ruby/internal/arithmetic/char.h index 3033639a43..920fdc0c9d 100644 --- a/include/ruby/internal/arithmetic/char.h +++ b/include/ruby/internal/arithmetic/char.h @@ -17,7 +17,7 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `char` and Ruby's. */ #include "ruby/internal/arithmetic/int.h" /* NUM2INT is here, but */ @@ -29,9 +29,9 @@ #include "ruby/internal/core/rstring.h" #include "ruby/internal/value_type.h" -#define RB_NUM2CHR rb_num2char_inline -#define NUM2CHR RB_NUM2CHR -#define CHR2FIX RB_CHR2FIX +#define RB_NUM2CHR rb_num2char_inline /**< @alias{rb_num2char_inline} */ +#define NUM2CHR RB_NUM2CHR /**< @old{RB_NUM2CHR} */ +#define CHR2FIX RB_CHR2FIX /**< @old{RB_CHR2FIX} */ /** @cond INTERNAL_MACRO */ #define RB_CHR2FIX RB_CHR2FIX @@ -40,12 +40,35 @@ RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) RBIMPL_ATTR_ARTIFICIAL() +/** + * Converts a C's `unsigned char` into an instance of ::rb_cInteger. + * + * @param[in] c Arbitrary `unsigned char` value. + * @return An instance of ::rb_cInteger. + * + * @internal + * + * Nobody explicitly states this but in Ruby, a char means an unsigned integer + * value of range 0..255. This is a general principle. AFAIK there is no + * single line of code where char is signed. + */ static inline VALUE RB_CHR2FIX(unsigned char c) { return RB_INT2FIX(c); } +/** + * Converts an instance of ::rb_cNumeric into C's `char`. At the same time it + * accepts a String of more than one character, and returns its first byte. In + * the early days there was a Ruby level "character" literal `?c`, which + * roughly worked this way. + * + * @param[in] x Either a string or a 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 `char`. + */ static inline char rb_num2char_inline(VALUE x) { diff --git a/include/ruby/internal/arithmetic/double.h b/include/ruby/internal/arithmetic/double.h index 69d8630dbb..229de47aef 100644 --- a/include/ruby/internal/arithmetic/double.h +++ b/include/ruby/internal/arithmetic/double.h @@ -17,23 +17,56 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `double` and Ruby's. */ #include "ruby/internal/attr/pure.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" -#define NUM2DBL rb_num2dbl -#define RFLOAT_VALUE rb_float_value -#define DBL2NUM rb_float_new +#define NUM2DBL rb_num2dbl /**< @old{rb_num2dbl} */ +#define RFLOAT_VALUE rb_float_value /**< @old{rb_float_value} */ +#define DBL2NUM rb_float_new /**< @old{rb_float_new} */ RBIMPL_SYMBOL_EXPORT_BEGIN() -double rb_num2dbl(VALUE); +/** + * Converts an instance of ::rb_cNumeric into C's `double`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @return The passed value converted into C's `double`. + */ +double rb_num2dbl(VALUE num); + RBIMPL_ATTR_PURE() -double rb_float_value(VALUE); -VALUE rb_float_new(double); -VALUE rb_float_new_in_heap(double); +/** + * Extracts its double value from an instance of ::rb_cFloat. + * + * @param[in] num An instance of ::rb_cFloat. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `double`. + */ +double rb_float_value(VALUE num); + +/** + * Converts a C's `double` into an instance of ::rb_cFloat. + * + * @param[in] d Arbitrary `double` value. + * @return An instance of ::rb_cFloat. + */ +VALUE rb_float_new(double d); + +/** + * Identical to rb_float_new(), except it does not generate Flonums. + * + * @param[in] d Arbitrary `double` value. + * @return An instance of ::rb_cFloat. + * + * @internal + * + * @shyouhei has no idea why it is here. + */ +VALUE rb_float_new_in_heap(double d); RBIMPL_SYMBOL_EXPORT_END() #endif /* RBIMPL_ARITHMETIC_DOUBLE_H */ diff --git a/include/ruby/internal/arithmetic/fixnum.h b/include/ruby/internal/arithmetic/fixnum.h index 68544b760b..c8927ac824 100644 --- a/include/ruby/internal/arithmetic/fixnum.h +++ b/include/ruby/internal/arithmetic/fixnum.h @@ -17,28 +17,44 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Handling of integers formerly known as Fixnums. */ #include "ruby/backward/2/limits.h" -#define FIXABLE RB_FIXABLE -#define FIXNUM_MAX RUBY_FIXNUM_MAX -#define FIXNUM_MIN RUBY_FIXNUM_MIN -#define NEGFIXABLE RB_NEGFIXABLE -#define POSFIXABLE RB_POSFIXABLE +#define FIXABLE RB_FIXABLE /**< @old{RB_FIXABLE} */ +#define FIXNUM_MAX RUBY_FIXNUM_MAX /**< @old{RUBY_FIXNUM_MAX} */ +#define FIXNUM_MIN RUBY_FIXNUM_MIN /**< @old{RUBY_FIXNUM_MIN} */ +#define NEGFIXABLE RB_NEGFIXABLE /**< @old{RB_NEGFIXABLE} */ +#define POSFIXABLE RB_POSFIXABLE /**< @old{RB_POSFIXABLE} */ -/* +/** + * Checks if the passed value is in range of fixnum, assuming it is a positive + * number. Can sometimes be useful for C's unsigned integer types. + * + * @internal + * * FIXABLE can be applied to anything, from double to intmax_t. The problem is * double. On a 64bit system RUBY_FIXNUM_MAX is 4,611,686,018,427,387,903, * which is not representable by a double. The nearest value that a double can * represent is 4,611,686,018,427,387,904, which is not fixable. The - * seemingly-stragne "< FIXNUM_MAX + 1" expression below is due to this. + * seemingly-strange "< FIXNUM_MAX + 1" expression below is due to this. */ #define RB_POSFIXABLE(_) ((_) < RUBY_FIXNUM_MAX + 1) + +/** + * Checks if the passed value is in range of fixnum, assuming it is a negative + * number. This is an implementation of #RB_FIXABLE. Rarely used stand alone. + */ #define RB_NEGFIXABLE(_) ((_) >= RUBY_FIXNUM_MIN) + +/** Checks if the passed value is in range of fixnum */ #define RB_FIXABLE(_) (RB_POSFIXABLE(_) && RB_NEGFIXABLE(_)) + +/** Maximum possible value that a fixnum can represent. */ #define RUBY_FIXNUM_MAX (LONG_MAX / 2) + +/** Minimum possible value that a fixnum can represent. */ #define RUBY_FIXNUM_MIN (LONG_MIN / 2) #endif /* RBIMPL_ARITHMETIC_FIXNUM_H */ diff --git a/include/ruby/internal/arithmetic/gid_t.h b/include/ruby/internal/arithmetic/gid_t.h index 094fc63092..361220bfab 100644 --- a/include/ruby/internal/arithmetic/gid_t.h +++ b/include/ruby/internal/arithmetic/gid_t.h @@ -17,20 +17,23 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `gid_t` and Ruby's. */ #include "ruby/internal/config.h" #include "ruby/internal/arithmetic/long.h" +/** Converts a C's `gid_t` into an instance of ::rb_cInteger. */ #ifndef GIDT2NUM # define GIDT2NUM RB_LONG2NUM #endif +/** Converts an instance of ::rb_cNumeric into C's `gid_t`. */ #ifndef NUM2GIDT # define NUM2GIDT RB_NUM2LONG #endif +/** A rb_sprintf() format prefix to be used for a `gid_t` parameter. */ #ifndef PRI_GIDT_PREFIX # define PRI_GIDT_PREFIX PRI_LONG_PREFIX #endif diff --git a/include/ruby/internal/arithmetic/int.h b/include/ruby/internal/arithmetic/int.h index 346fa9258b..6bd8ec2184 100644 --- a/include/ruby/internal/arithmetic/int.h +++ b/include/ruby/internal/arithmetic/int.h @@ -17,7 +17,7 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `int` and Ruby's. */ #include "ruby/internal/config.h" @@ -34,16 +34,16 @@ #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 @@ /** @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) 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) 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) } 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. */ 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) 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) { diff --git a/include/ruby/internal/arithmetic/intptr_t.h b/include/ruby/internal/arithmetic/intptr_t.h index 442c87144c..a354f4469c 100644 --- a/include/ruby/internal/arithmetic/intptr_t.h +++ b/include/ruby/internal/arithmetic/intptr_t.h @@ -17,7 +17,7 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `intptr_t` and Ruby's. */ #include "ruby/internal/config.h" @@ -29,13 +29,45 @@ #include "ruby/internal/value.h" #include "ruby/internal/dllexport.h" -#define rb_int_new rb_int2inum -#define rb_uint_new rb_uint2inum +#define rb_int_new rb_int2inum /**< @alias{rb_int2inum} */ +#define rb_uint_new rb_uint2inum /**< @alias{rb_uint2inum} */ RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** + * Converts a C's `intptr_t` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `intptr_t` value. + * @return An instance of ::rb_cInteger. + * @note This function always allocates Bignums, even if the given number + * is small enough to fit into a Fixnum. + */ VALUE rb_int2big(intptr_t i); + +/** + * Converts a C's `intptr_t` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `intptr_t` value. + * @return An instance of ::rb_cInteger. + */ VALUE rb_int2inum(intptr_t i); + +/** + * Converts a C's `intptr_t` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `intptr_t` value. + * @return An instance of ::rb_cInteger. + * @note This function always allocates Bignums, even if the given number + * is small enough to fit into a Fixnum. + */ VALUE rb_uint2big(uintptr_t i); + +/** + * Converts a C's `uintptr_t` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `uintptr_t` value. + * @return An instance of ::rb_cInteger. + */ VALUE rb_uint2inum(uintptr_t i); RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/internal/arithmetic/long.h b/include/ruby/internal/arithmetic/long.h index aff7d68478..6b8fd8ffc3 100644 --- a/include/ruby/internal/arithmetic/long.h +++ b/include/ruby/internal/arithmetic/long.h @@ -17,7 +17,7 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `long` and Ruby's. * * ### Q&A ### @@ -43,23 +43,23 @@ #include "ruby/internal/value.h" #include "ruby/assert.h" -#define FIX2LONG RB_FIX2LONG -#define FIX2ULONG RB_FIX2ULONG -#define INT2FIX RB_INT2FIX -#define LONG2FIX RB_INT2FIX -#define LONG2NUM RB_LONG2NUM -#define NUM2LONG RB_NUM2LONG -#define NUM2ULONG RB_NUM2ULONG -#define RB_FIX2LONG rb_fix2long -#define RB_FIX2ULONG rb_fix2ulong -#define RB_LONG2FIX RB_INT2FIX -#define RB_LONG2NUM rb_long2num_inline -#define RB_NUM2LONG rb_num2long_inline -#define RB_NUM2ULONG rb_num2ulong_inline -#define RB_ULONG2NUM rb_ulong2num_inline -#define ULONG2NUM RB_ULONG2NUM -#define rb_fix_new RB_INT2FIX -#define rb_long2int rb_long2int_inline +#define FIX2LONG RB_FIX2LONG /**< @old{RB_FIX2LONG} */ +#define FIX2ULONG RB_FIX2ULONG /**< @old{RB_FIX2ULONG} */ +#define INT2FIX RB_INT2FIX /**< @old{RB_INT2FIX} */ +#define LONG2FIX RB_INT2FIX /**< @old{RB_INT2FIX} */ +#define LONG2NUM RB_LONG2NUM /**< @old{RB_LONG2NUM} */ +#define NUM2LONG RB_NUM2LONG /**< @old{RB_NUM2LONG} */ +#define NUM2ULONG RB_NUM2ULONG /**< @old{RB_NUM2ULONG} */ +#define RB_FIX2LONG rb_fix2long /**< @alias{rb_fix2long} */ +#define RB_FIX2ULONG rb_fix2ulong /**< @alias{rb_fix2ulong} */ +#define RB_LONG2FIX RB_INT2FIX /**< @alias{RB_INT2FIX} */ +#define RB_LONG2NUM rb_long2num_inline /**< @alias{rb_long2num_inline} */ +#define RB_NUM2LONG rb_num2long_inline /**< @alias{rb_num2long_inline} */ +#define RB_NUM2ULONG rb_num2ulong_inline /**< @alias{rb_num2ulong_inline} */ +#define RB_ULONG2NUM rb_ulong2num_inline /**< @alias{rb_ulong2num_inline} */ +#define ULONG2NUM RB_ULONG2NUM /**< @old{RB_ULONG2NUM} */ +#define rb_fix_new RB_INT2FIX /**< @alias{RB_INT2FIX} */ +#define rb_long2int rb_long2int_inline /**< @alias{rb_long2int_inline} */ /** @cond INTERNAL_MACRO */ #define RB_INT2FIX RB_INT2FIX @@ -69,15 +69,44 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() RBIMPL_ATTR_NORETURN() RBIMPL_ATTR_COLD() +/** + * This is an utility function to raise an ::rb_eRangeError. + * + * @param[in] num A signed value about to overflow. + * @exception rb_eRangeError `num` is out of range of `int`. + */ void rb_out_of_int(SIGNED_VALUE num); +/** + * 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 `long`. + * @return The passed value converted into C's `long`. + */ long rb_num2long(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 long`. + * @return The passed value converted into C's `unsigned long`. + */ unsigned long rb_num2ulong(VALUE num); RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) RBIMPL_ATTR_ARTIFICIAL() +/** + * Converts a C's `long` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `long` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE RB_INT2FIX(long i) { @@ -86,7 +115,7 @@ RB_INT2FIX(long i) /* :NOTE: VALUE can be wider than long. As j being unsigned, 2j+1 is fully * defined. Also it can be compiled into a single LEA instruction. */ const unsigned long j = i; - const unsigned long k = 2 * j + RUBY_FIXNUM_FLAG; + const unsigned long k = (j << 1) + RUBY_FIXNUM_FLAG; const long l = k; const SIGNED_VALUE m = l; /* Sign extend */ const VALUE n = m; @@ -95,6 +124,13 @@ RB_INT2FIX(long i) return n; } +/** + * Checks if `int` can hold the given integer. + * + * @param[in] n Arbitrary `long` value. + * @exception rb_eRangeError `n` is out of range of `int`. + * @return Identical value of type `int` + */ static inline int rb_long2int_inline(long n) { @@ -112,6 +148,16 @@ rb_long2int_inline(long n) RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) +/** + * @private + * + * This is an implementation detail of rb_fix2long(). People don't use it + * directly. + * + * @param[in] x A Fixnum. + * @return Identical value of type `long` + * @pre Must not pass anything other than a Fixnum. + */ static inline long rbimpl_fix2long_by_idiv(VALUE x) { @@ -130,6 +176,16 @@ rbimpl_fix2long_by_idiv(VALUE x) RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) +/** + * @private + * + * This is an implementation detail of rb_fix2long(). People don't use it + * directly. + * + * @param[in] x A Fixnum. + * @return Identical value of type `long` + * @pre Must not pass anything other than a Fixnum. + */ static inline long rbimpl_fix2long_by_shift(VALUE x) { @@ -147,6 +203,15 @@ rbimpl_fix2long_by_shift(VALUE x) RBIMPL_ATTR_CONST() RBIMPL_ATTR_CONSTEXPR(CXX11) +/** + * @private + * + * This is an implementation detail of rb_fix2long(). People don't use it + * directly. + * + * @retval true This C compiler's right shift operator is arithmetic. + * @retval false This C compiler's right shift operator is logical. + */ static inline bool rbimpl_right_shift_is_arithmetic_p(void) { @@ -155,6 +220,13 @@ rbimpl_right_shift_is_arithmetic_p(void) RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) +/** + * Converts a Fixnum into C's `long`. + * + * @param[in] x Some Fixnum. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `long`. + */ static inline long rb_fix2long(VALUE x) { @@ -168,6 +240,14 @@ rb_fix2long(VALUE x) RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) +/** + * Converts a Fixnum into C's `unsigned long`. + * + * @param[in] x Some Fixnum. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `unsigned long`. + * @note Negative fixnums will be converted into large unsigned longs. + */ static inline unsigned long rb_fix2ulong(VALUE x) { @@ -175,6 +255,14 @@ rb_fix2ulong(VALUE x) return rb_fix2long(x); } +/** + * Converts an instance of ::rb_cNumeric into C's `long`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `long`. + * @return The passed value converted into C's `long`. + */ static inline long rb_num2long_inline(VALUE x) { @@ -184,20 +272,38 @@ rb_num2long_inline(VALUE x) return rb_num2long(x); } +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned long`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `unsigned long`. + * @return The passed value converted into C's `unsigned long`. + * + * @internal + * + * This (negative fixnum would become a large unsigned long while negative + * bignum is an exception) has been THE behaviour of NUM2ULONG since the + * beginning. It is strange, but we can no longer change how it works at this + * moment. We have to get by with it. + * + * @see https://bugs.ruby-lang.org/issues/9089 + */ static inline unsigned long rb_num2ulong_inline(VALUE x) { - /* This (negative fixnum would become a large unsigned long while negative - * bignum is an exception) has been THE behaviour of NUM2ULONG since the - * beginning. It is strange, but we can no longer change how it works at - * this moment. We have to get by with it. See also: - * https://bugs.ruby-lang.org/issues/9089 */ if (RB_FIXNUM_P(x)) return RB_FIX2ULONG(x); else return rb_num2ulong(x); } +/** + * Converts a C's `long` into an instance of ::rb_cInteger. + * + * @param[in] v Arbitrary `long` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE rb_long2num_inline(long v) { @@ -207,6 +313,12 @@ rb_long2num_inline(long v) return rb_int2big(v); } +/** + * Converts a C's `unsigned long` into an instance of ::rb_cInteger. + * + * @param[in] v Arbitrary `unsigned long` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE rb_ulong2num_inline(unsigned long v) { diff --git a/include/ruby/internal/arithmetic/long_long.h b/include/ruby/internal/arithmetic/long_long.h index a4a5d0aa09..65dec8729d 100644 --- a/include/ruby/internal/arithmetic/long_long.h +++ b/include/ruby/internal/arithmetic/long_long.h @@ -17,7 +17,7 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `long long` and Ruby's. */ #include "ruby/internal/value.h" @@ -25,22 +25,59 @@ #include "ruby/internal/special_consts.h" #include "ruby/backward/2/long_long.h" -#define RB_LL2NUM rb_ll2num_inline -#define RB_ULL2NUM rb_ull2num_inline -#define LL2NUM RB_LL2NUM -#define ULL2NUM RB_ULL2NUM -#define RB_NUM2LL rb_num2ll_inline -#define RB_NUM2ULL rb_num2ull_inline -#define NUM2LL RB_NUM2LL -#define NUM2ULL RB_NUM2ULL +#define RB_LL2NUM rb_ll2num_inline /**< @alias{rb_ll2num_inline} */ +#define RB_ULL2NUM rb_ull2num_inline /**< @alias{rb_ull2num_inline} */ +#define LL2NUM RB_LL2NUM /**< @old{RB_LL2NUM} */ +#define ULL2NUM RB_ULL2NUM /**< @old{RB_ULL2NUM} */ +#define RB_NUM2LL rb_num2ll_inline /**< @alias{rb_num2ll_inline} */ +#define RB_NUM2ULL rb_num2ull_inline /**< @alias{rb_num2ull_inline} */ +#define NUM2LL RB_NUM2LL /**< @old{RB_NUM2LL} */ +#define NUM2ULL RB_NUM2ULL /**< @old{RB_NUM2ULL} */ RBIMPL_SYMBOL_EXPORT_BEGIN() -VALUE rb_ll2inum(LONG_LONG); -VALUE rb_ull2inum(unsigned LONG_LONG); -LONG_LONG rb_num2ll(VALUE); -unsigned LONG_LONG rb_num2ull(VALUE); +/** + * Converts a C's `long long` into an instance of ::rb_cInteger. + * + * @param[in] num Arbitrary `long long` value. + * @return An instance of ::rb_cInteger. + */ +VALUE rb_ll2inum(LONG_LONG num); + +/** + * Converts a C's `unsigned long long` into an instance of ::rb_cInteger. + * + * @param[in] num Arbitrary `unsigned long long` value. + * @return An instance of ::rb_cInteger. + */ +VALUE rb_ull2inum(unsigned LONG_LONG num); + +/** + * Converts an instance of ::rb_cNumeric into C's `long long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `long long`. + * @return The passed value converted into C's `long long`. + */ +LONG_LONG rb_num2ll(VALUE num); + +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned long long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned long long`. + * @return The passed value converted into C's `unsigned long long`. + */ +unsigned LONG_LONG rb_num2ull(VALUE num); RBIMPL_SYMBOL_EXPORT_END() +/** + * Converts a C's `long long` into an instance of ::rb_cInteger. + * + * @param[in] n Arbitrary `long long` value. + * @return An instance of ::rb_cInteger + */ static inline VALUE rb_ll2num_inline(LONG_LONG n) { @@ -48,6 +85,12 @@ rb_ll2num_inline(LONG_LONG n) return rb_ll2inum(n); } +/** + * Converts a C's `unsigned long long` into an instance of ::rb_cInteger. + * + * @param[in] n Arbitrary `unsigned long long` value. + * @return An instance of ::rb_cInteger + */ static inline VALUE rb_ull2num_inline(unsigned LONG_LONG n) { @@ -55,6 +98,14 @@ rb_ull2num_inline(unsigned LONG_LONG n) return rb_ull2inum(n); } +/** + * Converts an instance of ::rb_cNumeric into C's `long long`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `long long`. + * @return The passed value converted into C's `long long`. + */ static inline LONG_LONG rb_num2ll_inline(VALUE x) { @@ -64,6 +115,14 @@ rb_num2ll_inline(VALUE x) return rb_num2ll(x); } +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned long long`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `unsigned long long`. + * @return The passed value converted into C's `unsigned long long`. + */ static inline unsigned LONG_LONG rb_num2ull_inline(VALUE x) { diff --git a/include/ruby/internal/arithmetic/mode_t.h b/include/ruby/internal/arithmetic/mode_t.h index 46e41f7ef9..5b7ad35fbc 100644 --- a/include/ruby/internal/arithmetic/mode_t.h +++ b/include/ruby/internal/arithmetic/mode_t.h @@ -17,20 +17,23 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `mode_t` and Ruby's. */ #include "ruby/internal/config.h" #include "ruby/internal/arithmetic/int.h" +/** Converts a C's `mode_t` into an instance of ::rb_cInteger. */ #ifndef NUM2MODET # define NUM2MODET RB_NUM2INT #endif +/** Converts an instance of ::rb_cNumeric into C's `mode_t`. */ #ifndef MODET2NUM # define MODET2NUM RB_INT2NUM #endif +/** A rb_sprintf() format prefix to be used for a `mode_t` parameter. */ #ifndef PRI_MODET_PREFIX # define PRI_MODET_PREFIX PRI_INT_PREFIX #endif diff --git a/include/ruby/internal/arithmetic/off_t.h b/include/ruby/internal/arithmetic/off_t.h index c1959c61a1..0ec9362cc9 100644 --- a/include/ruby/internal/arithmetic/off_t.h +++ b/include/ruby/internal/arithmetic/off_t.h @@ -17,7 +17,7 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `off_t` and Ruby's. */ #include "ruby/internal/config.h" @@ -26,6 +26,7 @@ #include "ruby/internal/arithmetic/long_long.h" #include "ruby/backward/2/long_long.h" +/** Converts a C's `off_t` into an instance of ::rb_cInteger. */ #ifdef OFFT2NUM # /* take that. */ #elif SIZEOF_OFF_T == SIZEOF_LONG_LONG @@ -36,6 +37,7 @@ # define OFFT2NUM RB_INT2NUM #endif +/** Converts an instance of ::rb_cNumeric into C's `off_t`. */ #ifdef NUM2OFFT # /* take that. */ #elif SIZEOF_OFF_T == SIZEOF_LONG_LONG @@ -46,6 +48,7 @@ # define NUM2OFFT RB_NUM2INT #endif +/** A rb_sprintf() format prefix to be used for an `off_t` parameter. */ #ifdef PRI_OFFT_PREFIX # /* take that. */ #elif SIZEOF_OFF_T == SIZEOF_LONG_LONG diff --git a/include/ruby/internal/arithmetic/pid_t.h b/include/ruby/internal/arithmetic/pid_t.h index 86373ebfde..df9704e8f5 100644 --- a/include/ruby/internal/arithmetic/pid_t.h +++ b/include/ruby/internal/arithmetic/pid_t.h @@ -17,20 +17,23 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `pid_t` and Ruby's. */ #include "ruby/internal/config.h" #include "ruby/internal/arithmetic/long.h" +/** Converts a C's `pid_t` into an instance of ::rb_cInteger. */ #ifndef PIDT2NUM # define PIDT2NUM RB_LONG2NUM #endif +/** Converts an instance of ::rb_cNumeric into C's `pid_t`. */ #ifndef NUM2PIDT # define NUM2PIDT RB_NUM2LONG #endif +/** A rb_sprintf() format prefix to be used for a `pid_t` parameter. */ #ifndef PRI_PIDT_PREFIX # define PRI_PIDT_PREFIX PRI_LONG_PREFIX #endif diff --git a/include/ruby/internal/arithmetic/short.h b/include/ruby/internal/arithmetic/short.h index ef213a8d3e..7a324d945b 100644 --- a/include/ruby/internal/arithmetic/short.h +++ b/include/ruby/internal/arithmetic/short.h @@ -17,7 +17,7 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `short` and Ruby's. * * Shyouhei wonders: why there is no SHORT2NUM, given there are both @@ -27,21 +27,80 @@ #include "ruby/internal/dllexport.h" #include "ruby/internal/special_consts.h" -#define RB_NUM2SHORT rb_num2short_inline -#define RB_NUM2USHORT rb_num2ushort -#define NUM2SHORT RB_NUM2SHORT -#define NUM2USHORT RB_NUM2USHORT -#define USHORT2NUM RB_INT2FIX -#define RB_FIX2SHORT rb_fix2short -#define FIX2SHORT RB_FIX2SHORT +#define RB_NUM2SHORT rb_num2short_inline /**< @alias{rb_num2short_inline} */ +#define RB_NUM2USHORT rb_num2ushort /**< @alias{rb_num2ushort} */ +#define NUM2SHORT RB_NUM2SHORT /**< @old{RB_NUM2SHORT} */ +#define NUM2USHORT RB_NUM2USHORT /**< @old{RB_NUM2USHORT} */ +#define USHORT2NUM RB_INT2FIX /**< @old{RB_INT2FIX} */ +#define RB_FIX2SHORT rb_fix2short /**< @alias{rb_fix2ushort} */ +#define FIX2SHORT RB_FIX2SHORT /**< @old{RB_FIX2SHORT} */ RBIMPL_SYMBOL_EXPORT_BEGIN() -short rb_num2short(VALUE); -unsigned short rb_num2ushort(VALUE); -short rb_fix2short(VALUE); -unsigned short rb_fix2ushort(VALUE); + +/** + * Converts an instance of ::rb_cNumeric into C's `short`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `short`. + * @return The passed value converted into C's `short`. + */ +short rb_num2short(VALUE num); + +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned short`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned short`. + * @return The passed value converted into C's `unsigned short`. + */ +unsigned short rb_num2ushort(VALUE num); + +/** + * Identical to rb_num2short(). + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `short`. + * @return The passed value converted into C's `short`. + * + * @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(). + */ +short rb_fix2short(VALUE num); + +/** + * Identical to rb_num2ushort(). + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned short`. + * @return The passed value converted into C's `unsigned short`. + * + * @internal + * + * This function seems to be a complete waste of disk space. @shyouhei has no + * idea why this is a different thing from rb_num2ushort(). + */ +unsigned short rb_fix2ushort(VALUE num); RBIMPL_SYMBOL_EXPORT_END() +/** + * Identical to rb_num2short(). + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `short`. + * @return The passed value converted into C's `short`. + * + * @internal + * + * This function seems to be a complete waste of time. @shyouhei has no idea + * why this is a different thing from rb_num2short(). + */ static inline short rb_num2short_inline(VALUE x) { @@ -51,4 +110,4 @@ rb_num2short_inline(VALUE x) return rb_num2short(x); } -#endif /* RBIMPL_ARITHMETIC_SOHRT_H */ +#endif /* RBIMPL_ARITHMETIC_SHORT_H */ diff --git a/include/ruby/internal/arithmetic/size_t.h b/include/ruby/internal/arithmetic/size_t.h index 0458f1f5f3..1082160b8e 100644 --- a/include/ruby/internal/arithmetic/size_t.h +++ b/include/ruby/internal/arithmetic/size_t.h @@ -17,7 +17,7 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `size_t` and Ruby's. */ #include "ruby/internal/config.h" @@ -26,7 +26,12 @@ #include "ruby/internal/arithmetic/long_long.h" #include "ruby/backward/2/long_long.h" -#if SIZEOF_SIZE_T == SIZEOF_LONG_LONG +#if defined(__DOXYGEN__) +# /** Converts a C's `size_t` into an instance of ::rb_cInteger. */ +# define RB_SIZE2NUM RB_ULONG2NUM +# /** Converts a C's `ssize_t` into an instance of ::rb_cInteger. */ +# define RB_SSIZE2NUM RB_LONG2NUM +#elif SIZEOF_SIZE_T == SIZEOF_LONG_LONG # define RB_SIZE2NUM RB_ULL2NUM # define RB_SSIZE2NUM RB_LL2NUM #elif SIZEOF_SIZE_T == SIZEOF_LONG @@ -37,7 +42,12 @@ # define RB_SSIZE2NUM RB_INT2NUM #endif -#if SIZEOF_SIZE_T == SIZEOF_LONG_LONG +#if defined(__DOXYGEN__) +# /** Converts an instance of ::rb_cInteger into C's `size_t`. */ +# define RB_NUM2SIZE RB_NUM2ULONG +# /** Converts an instance of ::rb_cInteger into C's `ssize_t`. */ +# define RB_NUM2SSIZE RB_NUM2LONG +#elif SIZEOF_SIZE_T == SIZEOF_LONG_LONG # define RB_NUM2SIZE RB_NUM2ULL # define RB_NUM2SSIZE RB_NUM2LL #elif SIZEOF_SIZE_T == SIZEOF_LONG @@ -48,9 +58,9 @@ # define RB_NUM2SSIZE RB_NUM2INT #endif -#define NUM2SIZET RB_NUM2SIZE -#define SIZET2NUM RB_SIZE2NUM -#define NUM2SSIZET RB_NUM2SSIZE -#define SSIZET2NUM RB_SSIZE2NUM +#define NUM2SIZET RB_NUM2SIZE /**< @old{RB_NUM2SIZE} */ +#define SIZET2NUM RB_SIZE2NUM /**< @old{RB_SIZE2NUM} */ +#define NUM2SSIZET RB_NUM2SSIZE /**< @old{RB_NUM2SSIZE} */ +#define SSIZET2NUM RB_SSIZE2NUM /**< @old{RB_SSIZE2NUM} */ #endif /* RBIMPL_ARITHMETIC_SIZE_T_H */ diff --git a/include/ruby/internal/arithmetic/st_data_t.h b/include/ruby/internal/arithmetic/st_data_t.h index 93a5ccb7a1..3bff4ffc0b 100644 --- a/include/ruby/internal/arithmetic/st_data_t.h +++ b/include/ruby/internal/arithmetic/st_data_t.h @@ -17,7 +17,7 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `st_data_t` and Ruby's. */ #include "ruby/internal/arithmetic/fixnum.h" @@ -30,7 +30,7 @@ #include "ruby/assert.h" #include "ruby/st.h" -#define ST2FIX RB_ST2FIX +#define ST2FIX RB_ST2FIX /**< @old{RB_ST2FIX} */ /** @cond INTERNAL_MACRO */ #define RB_ST2FIX RB_ST2FIX /** @endcond */ @@ -38,7 +38,23 @@ RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) RBIMPL_ATTR_ARTIFICIAL() -/* See also [ruby-core:84395] [Bug #14218] [ruby-core:82687] [Bug #13877] */ +/** + * Converts a C's `st_data_t` into an instance of ::rb_cInteger. + * + * @param[in] i The data in question. + * @return A converted result + * @warning THIS CONVERSION LOSES DATA! Be warned. + * @see https://bugs.ruby-lang.org/issues/13877 + * @see https://bugs.ruby-lang.org/issues/14218 + * + * @internal + * + * This is needed because of hash functions. Hash functions return + * `st_data_t`, which could theoretically be bigger than Fixnums. However + * allocating Bignums for them every time we calculate hash values is just too + * heavy. To avoid penalty we need to ignore some upper bit(s) and stick to + * Fixnums. This function is used for that purpose. + */ static inline VALUE RB_ST2FIX(st_data_t i) { @@ -56,4 +72,4 @@ RB_ST2FIX(st_data_t i) return RB_LONG2FIX(y); } -#endif /* RBIMPL_ARITHMERIC_ST_DATA_T_H */ +#endif /* RBIMPL_ARITHMETIC_ST_DATA_T_H */ diff --git a/include/ruby/internal/arithmetic/uid_t.h b/include/ruby/internal/arithmetic/uid_t.h index a990b2f480..12cde2a9c8 100644 --- a/include/ruby/internal/arithmetic/uid_t.h +++ b/include/ruby/internal/arithmetic/uid_t.h @@ -17,20 +17,23 @@ * 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. + * extension libraries. They could be written in C++98. * @brief Arithmetic conversion between C's `uid_t` and Ruby's. */ #include "ruby/internal/config.h" #include "ruby/internal/arithmetic/long.h" +/** Converts a C's `uid_t` into an instance of ::rb_cInteger. */ #ifndef UIDT2NUM # define UIDT2NUM RB_LONG2NUM #endif +/** Converts an instance of ::rb_cNumeric into C's `uid_t`. */ #ifndef NUM2UIDT # define NUM2UIDT RB_NUM2LONG #endif +/** A rb_sprintf() format prefix to be used for a `uid_t` parameter. */ #ifndef PRI_UIDT_PREFIX # define PRI_UIDT_PREFIX PRI_LONG_PREFIX #endif |