diff options
Diffstat (limited to 'include/ruby/internal/arithmetic/char.h')
| -rw-r--r-- | include/ruby/internal/arithmetic/char.h | 31 |
1 files changed, 27 insertions, 4 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) { |