[DOC] non-positive `base` in `Kernel#Integer` and `String#to_i`

2 files changed, 41 insertions, 8 deletions

diff --git a/object.c b/object.c
index eb54d84967..2328b20757 100644
--- a/object.c
+++ b/object.c
@@ -3175,6 +3175,11 @@ rb_opts_exception_p(VALUE opts, int default_value)
  *  using +to_int+ first and +to_i+ second;
  *  see below for exceptions.
  *
+ *  With a non-zero +base+, +object+ must be a string or convertible
+ *  to a string.
+ *
+ *  ==== numeric objects
+ *
  *  With integer argument +object+ given, returns +object+:
  *
  *    Integer(1)                # => 1
@@ -3186,6 +3191,8 @@ rb_opts_exception_p(VALUE opts, int default_value)
  *    Integer(1.9)              # => 1  # Rounds toward zero.
  *    Integer(-1.9)             # => -1 # Rounds toward zero.
  *
+ *  ==== string objects
+ *
  *  With string argument +object+ and zero +base+ given,
  *  returns +object+ converted to an integer in base 10:
  *
@@ -3193,32 +3200,48 @@ rb_opts_exception_p(VALUE opts, int default_value)
  *    Integer('-100')   # => -100
  *
  *  With +base+ zero, string +object+ may contain leading characters
- *  to specify the actual base:
+ *  to specify the actual base (radix indicator):
  *
  *    Integer('0100')  # => 64  # Leading '0' specifies base 8.
  *    Integer('0b100') # => 4   # Leading '0b', specifies base 2.
  *    Integer('0x100') # => 256 # Leading '0x' specifies base 16.
  *
- *  With a non-zero +base+ (in range 2..36) given
- *  (in which case +object+ must be a string),
- *  returns +object+ converted to an integer in the given base:
+ *  With a positive +base+ (in range 2..36) given, returns +object+
+ *  converted to an integer in the given base:
  *
  *    Integer('100', 2)   # => 4
  *    Integer('100', 8)   # => 64
  *    Integer('-100', 16) # => -256
  *
+ *  With a negative +base+ (in range -36..-2) given, returns +object+
+ *  converted to an integer in the radix indicator if exists or
+ *  +-base+:
+ *
+ *    Integer('0x100', -2)   # => 256
+ *    Integer('100', -2)     # => 4
+ *    Integer('0b100', -8)   # => 4
+ *    Integer('100', -8)     # => 64
+ *    Integer('0o100', -10)  # => 64
+ *    Integer('100', -10)    # => 100
+ *
+ *  +base+ -1 is equal the -10 case.
+ *
  *  When converting strings, surrounding whitespace and embedded underscores
  *  are allowed and ignored:
  *
  *    Integer(' 100 ')      # => 100
  *    Integer('-1_0_0', 16) # => -256
  *
+ *  ==== other classes
+ *
  *  Examples with +object+ of various other classes:
  *
  *    Integer(Rational(9, 10)) # => 0  # Rounds toward zero.
  *    Integer(Complex(2, 0))   # => 2  # Imaginary part must be zero.
  *    Integer(Time.now)        # => 1650974042
  *
+ *  ==== keywords
+ *
  *  With optional keyword argument +exception+ given as +true+ (the default):
  *
  *  - Raises TypeError if +object+ does not respond to +to_int+ or +to_i+.
diff --git a/string.c b/string.c
index 951aeca6dd..a2bc7410fa 100644
--- a/string.c
+++ b/string.c
@@ -6513,11 +6513,21 @@ rb_str_include(VALUE str, VALUE arg)
  *    to_i(base = 10) -> integer
  *
  *  Returns the result of interpreting leading characters in +self+
- *  as an integer in the given +base+ (which must be in (2..36)):
+ *  as an integer in the given +base+ (which must be in (0, 2..36)):
  *
  *    '123456'.to_i     # => 123456
  *    '123def'.to_i(16) # => 1195503
  *
+ *  With +base+ zero, string +object+ may contain leading characters
+ *  to specify the actual base:
+ *
+ *    '123def'.to_i(0)   # => 123
+ *    '0123def'.to_i(0)  # => 83
+ *    '0b123def'.to_i(0) # => 1
+ *    '0o123def'.to_i(0) # => 83
+ *    '0d123def'.to_i(0) # => 123
+ *    '0x123def'.to_i(0) # => 1195503
+ *
  *  Characters past a leading valid number (in the given +base+) are ignored:
  *
  *    '12.345'.to_i   # => 12
@@ -10083,9 +10093,9 @@ rb_str_hex(VALUE str)
  *  returns zero if there is no such leading substring:
  *
  *    '123'.oct             # => 83
-      '-377'.oct            # => -255
-      '0377non-numeric'.oct # => 255
-      'non-numeric'.oct     # => 0
+ *    '-377'.oct            # => -255
+ *    '0377non-numeric'.oct # => 255
+ *    'non-numeric'.oct     # => 0
  *
  *  If +self+ starts with <tt>0</tt>, radix indicators are honored;
  *  see Kernel#Integer.