From 86d4fe686c52920c2bb638fd1da731e811c4261a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= Date: Thu, 21 Jan 2021 11:57:07 +0900 Subject: [PATCH] include/ruby/internal/arithmetic/st_data_t.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/internal/arithmetic/st_data_t.h | 22 +++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/include/ruby/internal/arithmetic/st_data_t.h b/include/ruby/internal/arithmetic/st_data_t.h index 867c382744..3bff4ffc0b 100644 --- a/include/ruby/internal/arithmetic/st_data_t.h +++ b/include/ruby/internal/arithmetic/st_data_t.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 */