ruby-changes:67826
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:02:26 +0900 (JST)
Subject: [ruby-changes:67826] eb39497ecf (master): include/ruby/util.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=eb39497ecf From eb39497ecf2599edfb5ab5bbb2c1ed16102819cc 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: Tue, 8 Jun 2021 14:51:47 +0900 Subject: include/ruby/util.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/util.h | 191 +++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 183 insertions(+), 8 deletions(-) diff --git a/include/ruby/util.h b/include/ruby/util.h index 660f91d..dfe215e 100644 --- a/include/ruby/util.h +++ b/include/ruby/util.h @@ -9,25 +9,119 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/util.h#L9 * Permission is hereby granted, to either redistribute and/or * modify this file, provided that the conditions mentioned in the * file COPYING are met. Consult the file for details. + * @warning DO NOT ADD RANDOM GARBAGES IN THIS FILE! Contents of this file + * reside here for historical reasons. Find a right place for your + * API! */ #include "ruby/internal/config.h" + +#ifdef STDC_HEADERS +# include <stddef.h> /* size_t */ +#endif + +#if HAVE_SYS_TYPES_H +# include <sys/types.h> /* ssize_t */ +#endif + +#include "ruby/internal/attr/nodiscard.h" +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/attr/pure.h" +#include "ruby/internal/attr/restrict.h" +#include "ruby/internal/attr/returns_nonnull.h" +#include "ruby/internal/config.h" #include "ruby/internal/dllexport.h" #include "ruby/defines.h" RBIMPL_SYMBOL_EXPORT_BEGIN() +/** an approximation of ceil(n * log10(2)), up to 65536 at least */ #define DECIMAL_SIZE_OF_BITS(n) (((n) * 3010 + 9998) / 9999) -/* an approximation of ceil(n * log10(2)), up to 65536 at least */ +/** + * Character to number mapping like `'a'` -> `10`, `'b'` -> `11` etc. For + * punctuation etc., the value is -1. "36" terminology comes from the fact + * that this is the table behind `str.to_i(36)`. + */ RUBY_EXTERN const signed char ruby_digit36_to_number_table[]; + +/** + * Characters that Ruby accepts as hexadecimal digits. This is `/\h/` expanded + * into an array. + */ RUBY_EXTERN const char ruby_hexdigits[]; +/** + * Scans the passed string, assuming the string is a textual representation of + * an integer. Stops when encountering something non-digit for the passed + * base. + * + * @note This does not understand minus sign. + * @note This does not understand e.g. `0x` prefix. + * @note It is a failure to pass `0` to `base`, unlike ruby_strtoul(). + * @param[in] str Target string of digits to interpret. + * @param[in] len Number of bytes of `str`, or -1 to detect `NUL`. + * @param[in] base Base, `2` to `36` inclusive. + * @param[out] retlen Return value buffer. + * @param[out] overflow Return value buffer. + * @return Interpreted numeric representation of `str`. + * @post `retlen` is the number of bytes scanned so far. + * @post `overflow` is set to true if the string represents something + * bigger than `ULONG_MAX`. Something meaningful still returns; + * which is the designed belabour of C's unsigned arithmetic. + */ unsigned long ruby_scan_digits(const char *str, ssize_t len, int base, size_t *retlen, int *overflow); + +/** @old{ruby_scan_oct} */ #define scan_oct(s,l,e) ((int)ruby_scan_oct((s),(l),(e))) -unsigned long ruby_scan_oct(const char *, size_t, size_t *); + +RBIMPL_ATTR_PURE() +RBIMPL_ATTR_NONNULL(()) +/** + * Interprets the passed string as an octal unsigned integer. Stops when + * encounters something not understood. + * + * @param[in] str C string to scan. + * @param[in] len Length of `str`. + * @param[out] consumed Return value buffer. + * @return Parsed integer. + * @post `ret` is the number of characters read. + * + * @internal + * + * No consideration is made for integer overflows. As the return value is + * unsigned this function has fully defined behaviour, but you cannot know if + * there was an integer wrap-around or not. + */ +unsigned long ruby_scan_oct(const char *str, size_t len, size_t *consumed); + +/** @old{ruby_scan_hex} */ #define scan_hex(s,l,e) ((int)ruby_scan_hex((s),(l),(e))) -unsigned long ruby_scan_hex(const char *, size_t, size_t *); +RBIMPL_ATTR_PURE() +RBIMPL_ATTR_NONNULL(()) +/** + * Interprets the passed string a hexadecimal unsigned integer. Stops when + * encounters something not understood. + * + * @param[in] str C string to scan. + * @param[in] len Length of `str`. + * @param[out] ret Return value buffer. + * @return Parsed integer. + * @post `ret` is the number of characters read. + * + * @internal + * + * No consideration is made for integer overflows. As the return value is + * unsigned this function has fully defined behaviour, but you cannot know if + * there was an integer wrap-around or not. + */ +unsigned long ruby_scan_hex(const char *str, size_t len, size_t *ret); + +/** + * Reentrant implementation of quick sort. If your system provides something + * (like C11 qsort_s), this is a thin wrapper of that routine. Otherwise + * resorts to our own version. + */ #ifdef HAVE_GNU_QSORT_R # define ruby_qsort qsort_r #else @@ -35,20 +129,101 @@ void ruby_qsort(void *, const size_t, const size_t, https://github.com/ruby/ruby/blob/trunk/include/ruby/util.h#L129 int (*)(const void *, const void *, void *), void *); #endif -void ruby_setenv(const char *, const char *); -void ruby_unsetenv(const char *); +RBIMPL_ATTR_NONNULL((1)) +/** + * Sets an environment variable. In case of POSIX this is a wrapper of + * `setenv(3)`. But there are systems which lack one. We try hard emulating. + * + * @param[in] key An environment variable. + * @param[in] val A value to be associated with `key`, or 0. + * @exception rb_eSystemCallError `setenv(3)` failed for some reason. + * @post Environment variable `key` is created if necessary. Its value + * is updated to be `val`. + */ +void ruby_setenv(const char *key, const char *val); + +RBIMPL_ATTR_NONNULL(()) +/** + * Deletes the passed environment variable, if any. + * + * @param[in] key An environment variable. + * @exception rb_eSystemCallError `unsetenv(3)` failed for some reason. + * @post Environment variable `key` does not exist. + */ +void ruby_unsetenv(const char *key); + +RBIMPL_ATTR_NODISCARD() +RBIMPL_ATTR_RESTRICT() +RBIMPL_ATTR_RETURNS_NONNULL() +RBIMPL_ATTR_NONNULL(()) +/** + * This is our own version of `strdup(3)` that uses ruby_xmalloc() instead of + * system malloc (benefits our GC). + * + * @param[in] str Target C string to duplicate. + * @return An allocated C string holding the identical contents. + * @note Return value must be discarded using ruby_xfree(). + */ +char *ruby_strdup(const char *str); -char *ruby_strdup(const char *); #undef strdup +/** + * @alias{ruby_strdup} + * + * @internal + * + * @shyouhei doesn't think it is a wise idea. ruby_strdup()'s return value + * must be passed to ruby_xfree(), but this macro makes it almost impossible. + */ #define strdup(s) ruby_strdup(s) +RBIMPL_ATTR_NODISCARD() +RBIMPL_ATTR_RESTRICT() +RBIMPL_ATTR_RETURNS_NONNULL() +/** + * This is our own version of `getcwd(3)` that uses ruby_xmalloc() instead of + * system malloc (benefits our GC). + * + * @return An allocated C string holding the process working directory. + * @note Return value must be discarded using ruby_xfree(). + */ char *ruby_getcwd(void); -double ruby_strtod(const char *, char **); +RBIMPL_ATTR_NONNULL((1)) +/** + * Our own locale-insensitive version of `strtod(3)`. The conversion is done + * as if the current locale is set to the "C" locale, no matter actual runtime + * locale settings. + * + * @param[in] str Decimal or hexadecimal representation of a floating + * point number. + * @param[out] endptr NULL, or an arbitrary pointer (overwritten on return). + * @return Converted number. + * @post If `endptr` is not NULL, it is updated to point the first such + * byte where conversion failed. + * @note This function sets `errno` on failure. + * - `ERANGE`: Converted integer is out of range of `double`. + * @see William D. Clinger, "How to Read Floating Point Numbers + * Accurately" in Proc. ACM SIGPLAN '90, pp. 92-101. + * https://doi.org/10.1145/93542.93557 + */ +double ruby_strtod(const char *str, char **endptr); + #undef strtod +/** @alias{ruby_strtod} */ #define strtod(s,e) ruby_strtod((s),(e)) -void ruby_each_words(const char *, void (*)(const char*, int, void*), void *); +RBIMPL_ATTR_NONNULL((2)) +/** + * Scans the passed string, with calling the callback function every time it + * encounters a "word". A word here is a series of characters separated by + * either a space (of IEEE 1003.1 section 7.3.1.1), or a `','`. + * + * @param[in] str Target string to split into each words. + * @param[in] func Callback function. + * @param[in,out] argv Passed as-is to `func`. + */ +void ruby_each_words(const char *str, void (*func)(const char *word, int len, void *argv), void *argv); RBIMPL_SYMBOL_EXPORT_END() -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/