[前][次][番号順一覧][スレッド一覧]

ruby-changes:67790

From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:02:01 +0900 (JST)
Subject: [ruby-changes:67790] f9a00f9ef2 (master): include/ruby/internal/intern/bignum.h: add doxygen

https://git.ruby-lang.org/ruby.git/commit/?id=f9a00f9ef2

From f9a00f9ef2dedaad4fe09c327603d63d580fa32e 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: Wed, 19 May 2021 10:54:58 +0900
Subject: include/ruby/internal/intern/bignum.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/intern/bignum.h | 813 ++++++++++++++++++++++++++++++++--
 1 file changed, 777 insertions(+), 36 deletions(-)

diff --git a/include/ruby/internal/intern/bignum.h b/include/ruby/internal/intern/bignum.h
index 124d065..43d6801 100644
--- a/include/ruby/internal/intern/bignum.h
+++ b/include/ruby/internal/intern/bignum.h
@@ -26,6 +26,7 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/bignum.h#L26
 # include <stddef.h>
 #endif
 
+#include "ruby/internal/attr/nonnull.h"
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/value.h"
 #include "ruby/backward/2/long_long.h"
@@ -33,71 +34,811 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/bignum.h#L34
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
 /* bignum.c */
-VALUE rb_big_new(size_t, int);
+
+/**
+ * Allocates a bignum object.
+ *
+ * @param[in]  len   Length of the bignum's backend storage, in words.
+ * @param[in]  sign  Sign of the bignum.
+ * @return     An allocated new bignum instance.
+ * @note       This only allocates an object, doesn't fill its value in.
+ *
+ * @internal
+ *
+ * @shyouhei  finds it  hard to  use from  extension libraries.   `len` is  per
+ * `BDIGIT` but its definition is hidden.
+ */
+VALUE rb_big_new(size_t len, int sign);
+
+/**
+ * Queries if  the passed bignum  instance is a  "bigzro".  What is  a bigzero?
+ * Well, bignums  are for very big  integers, but can also  represent tiny ones
+ * like -1,  0, 1.   Bigzero are  instances of bignums  whose values  are zero.
+ * Knowing if a bignum is bigzero can  be handy on occasions, like for instance
+ * detecting division by zero situation.
+ *
+ * @param[in]  x  A bignum.
+ * @retval     1  It is a bigzero.
+ * @retval     0  Otherwise.
+ */
 int rb_bigzero_p(VALUE x);
-VALUE rb_big_clone(VALUE);
-void rb_big_2comp(VALUE);
-VALUE rb_big_norm(VALUE);
+
+/**
+ * Duplicates the given bignum.
+ *
+ * @param[in]  num  A bignum.
+ * @return     An allocated bignum, who is equivalent to `num`.
+ */
+VALUE rb_big_clone(VALUE num);
+
+/**
+ * Destructively modify the passed bignum into 2's complement representation.
+ *
+ * @note  By default bignums are in signed magnitude system.
+ *
+ * @param[out]  num  A bignum to modify.
+ */
+void rb_big_2comp(VALUE num);
+
+/**
+ * Normalises the passed bignum.  It for  instance returns a fixnum of the same
+ * value if fixnum can represent that number.
+ *
+ * @param[out]  x  Target bignum (can be destructively modified).
+ * @return      An integer of the identical value (can be `x` itself).
+ */
+VALUE rb_big_norm(VALUE x);
+
+/**
+ * Destructively resizes the backend storage of the passed bignum.
+ *
+ * @param[out]  big  A bignum.
+ * @param[in]   len  New length of `big`'s backend, in words.
+ */
 void rb_big_resize(VALUE big, size_t len);
-VALUE rb_cstr_to_inum(const char*, int, int);
-VALUE rb_str_to_inum(VALUE, int, int);
-VALUE rb_cstr2inum(const char*, int);
-VALUE rb_str2inum(VALUE, int);
-VALUE rb_big2str(VALUE, int);
-long rb_big2long(VALUE);
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Parses C's string to convert into a Ruby's integer.  It understands prefixes
+ * (e.g. `0x`) and underscores.
+ *
+ * @param[in]  str           Stringised representation of the return value.
+ * @param[in]  base          Base of conversion.   Must be `-36..36` inclusive,
+ *                           except `1`.  `2..36` means  the conversion is done
+ *                           according to it,  with unmatched prefix understood
+ *                           as  a part  of  the result.   `-36..-2` means  the
+ *                           conversion  honours prefix  when  present, or  use
+ *                           `-base` when  absent. `0` is equivalent  to `-10`.
+ *                           `-1` mandates a prefix. `1` is an error.
+ * @param[in]  badcheck      Whether  to raise  ::rb_eArgError on  failure.  If
+ *                           `0`  is  passed  here  this  function  can  return
+ *                           `INT2FIX(0)` for parse errors.
+ * @exception  rb_eArgError  Failed to parse (and `badcheck` is truthy).
+ * @return     An instance of ::rb_cInteger,  which is a numeric interpretation
+ *             of what is written in `str`.
+ *
+ * @internal
+ *
+ * Not sure if it intentionally accepts `base  == -1` or is just buggy.  Nobody
+ * practically uses negative bases these days.
+ */
+VALUE rb_cstr_to_inum(const char *str, int base, int badcheck);
+
+/**
+ * Identical to rb_cstr2inum(), except it takes Ruby's strings instead of C's.
+ *
+ * @param[in]  str                 Stringised  representation   of  the  return
+ *                                 value.
+ * @param[in]  base                Base  of  conversion.    Must  be  `-36..36`
+ *                                 inclusive,  except `1`.   `2..36` means  the
+ *                                 conversion  is done  according  to it,  with
+ *                                 unmatched prefix understood as a part of the
+ *                                 result.   `-36..-2`   means  the  conversion
+ *                                 honours prefix when  present, or use `-base`
+ *                                 when  absent. `0`  is  equivalent to  `-10`.
+ *                                 `-1` mandates a prefix. `1` is an error.
+ * @param[in]  badcheck            Whether to raise  ::rb_eArgError on failure.
+ *                                 If  `0` is  passed  here  this function  can
+ *                                 return `INT2FIX(0)` for parse errors.
+ * @exception  rb_eArgError        Failed to parse (and `badcheck` is truthy).
+ * @exception  rb_eTypeError       `str` is not a string.
+ * @exception  rb_eEncCompatError  `str` is not ASCII compatible.
+ * @return     An instance of ::rb_cInteger,  which is a numeric interpretation
+ *             of what is written in `str`.
+ */
+VALUE rb_str_to_inum(VALUE str, int base, int badcheck);
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Identical to rb_cstr_to_inum(), except the second argument controls the base
+ * and badcheck at  once.  It basically doesn't raise for  parse errors, unless
+ * the base is zero.
+ *
+ * This is an older API.  New codes might prefer rb_cstr_to_inum().
+ *
+ * @param[in]  str           Stringised representation of the return value.
+ * @param[in]  base          Base of conversion.   Must be `-36..36` inclusive,
+ *                           except `1`.  `2..36` means  the conversion is done
+ *                           according to it,  with unmatched prefix understood
+ *                           as  a part  of  the result.   `-36..-2` means  the
+ *                           conversion  honours prefix  when  present, or  use
+ *                           `-base` when  absent. `0` is equivalent  to `-10`.
+ *                           `-1` mandates a prefix. `1` is an error.
+ * @exception  rb_eArgError  Failed to parse (and `base` is zero).
+ * @return     An instance of ::rb_cInteger,  which is a numeric interpretation
+ *             of what is written in `str`.
+ */
+VALUE rb_cstr2inum(const char *str, int base);
+
+/**
+ * Identical to rb_str_to_inum(), except the  second argument controls the base
+ * and  badcheck at  once.  It  can  also be  seen  as a  routine identical  to
+ * rb_cstr2inum(), except it takes Ruby's strings instead of C's.
+ *
+ * This is an older API.  New codes might prefer rb_cstr_to_inum().
+ *
+ * @param[in]  str                 Stringised  representation   of  the  return
+ *                                 value.
+ * @param[in]  base                Base  of  conversion.    Must  be  `-36..36`
+ *                                 inclusive,  except `1`.   `2..36` means  the
+ *                                 conversion  is done  according  to it,  with
+ *                                 unmatched prefix understood as a part of the
+ *                                 result.   `-36..-2`   means  the  conversion
+ *                                 honours prefix when  present, or use `-base`
+ *                                 when  absent. `0`  is  equivalent to  `-10`.
+ *                                 `-1` mandates a prefix. `1` is an error.
+ * @exception  rb_eArgError        Failed to parse (and `base` is zero).
+ * @exception  rb_eTypeError       `str` is not a string.
+ * @exception  rb_eEncCompatError  `str` is not ASCII compatible.
+ * @return     An instance of ::rb_cInteger,  which is a numeric interpretation
+ *             of what is written in `str`.
+ */
+VALUE rb_str2inum(VALUE str, int base);
+
+/**
+ * Generates a place-value representation of the passed integer.
+ *
+ * @param[in]  x               An integer to stringify.
+ * @param[in]  base            `2` to `36` inclusive for each radix.
+ * @exception  rb_eArgError    `base` is out of range.
+ * @exception  rb_eRangeError  `x` is too big, cannot represent in string.
+ * @return     An instance of ::rb_cString which represents `x`.
+ */
+VALUE rb_big2str(VALUE x, int base);
+
+/**
+ * Converts a bignum into C's `long`.
+ *
+ * @param[in]  x               A bignum.
+ * @exception  rb_eRangeError  `x` is out of range of `long`.
+ * @return     The passed value converted into C's `long`.
+ */
+long rb_big2long(VALUE x);
+
+/** @alias{rb_big2long} */
 #define rb_big2int(x) rb_big2long(x)
-unsigned long rb_big2ulong(VALUE);
+
+/**
+ * Converts a bignum into C's `unsigned long`.
+ *
+ * @param[in]  x               A bignum.
+ * @exception  rb_eRangeError  `x` is out of range of `unsigned long`.
+ * @return     The passed value converted into C's `unsigned long`.
+ *
+ * @internal
+ *
+ * This function  can generate  a very  large positiv (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]