From 9eab1e910768c51fd78288263a1432723d4e0b6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= Date: Tue, 26 Jan 2021 11:07:18 +0900 Subject: include/ruby/internal/arithmetic/char.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/internal/arithmetic/char.h | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) (limited to 'include/ruby') diff --git a/include/ruby/internal/arithmetic/char.h b/include/ruby/internal/arithmetic/char.h index 91f06bbf73..920fdc0c9d 100644 --- a/include/ruby/internal/arithmetic/char.h +++ b/include/ruby/internal/arithmetic/char.h @@ -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) { -- cgit v1.2.3