normal	2018-12-23 07:39:31 +0900 (Sun, 23 Dec 2018)

  New Revision: 66498

  https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=66498

  Log:
    {complex,object,rational}.c: document exception: false
    
    From: Victor Shepelev <zverok.offline@g...>
    
    [ruby-core:90673] [Bug #15452]

  Modified files:
    trunk/complex.c
    trunk/object.c
    trunk/rational.c
Index: complex.c
===================================================================
--- complex.c	(revision 66497)
+++ complex.c	(revision 66498)
@@ -394,7 +394,7 @@ static VALUE nucomp_s_convert(int argc, https://github.com/ruby/ruby/blob/trunk/complex.c#L394
 
 /*
  * call-seq:
- *    Complex(x[, y])  ->  numeric
+ *    Complex(x[, y], exception: false)  ->  numeric
  *
  * Returns x+i*y;
  *
@@ -403,6 +403,9 @@ static VALUE nucomp_s_convert(int argc, https://github.com/ruby/ruby/blob/trunk/complex.c#L403
  *    Complex(nil)     #=> TypeError
  *    Complex(1, nil)  #=> TypeError
  *
+ *    Complex(1, nil, exception: false) # => nil
+ *    Complex('1+2', exception: false) # => nil
+ *
  * Syntax of string form:
  *
  *   string form = extra spaces , complex , extra spaces ;
Index: object.c
===================================================================
--- object.c	(revision 66497)
+++ object.c	(revision 66498)
@@ -3221,7 +3221,7 @@ opts_exception_p(VALUE opts) https://github.com/ruby/ruby/blob/trunk/object.c#L3221
 
 /*
  *  call-seq:
- *     Integer(arg, base=0)    -> integer
+ *     Integer(arg, base=0, exception: true)    -> integer
  *
  *  Converts <i>arg</i> to an <code>Integer</code>.
  *  Numeric types are converted directly (with floating point numbers
@@ -3232,15 +3232,23 @@ opts_exception_p(VALUE opts) https://github.com/ruby/ruby/blob/trunk/object.c#L3232
  *  In any case, strings should be strictly conformed to numeric
  *  representation. This behavior is different from that of
  *  <code>String#to_i</code>.  Non string values will be converted by first
- *  trying <code>to_int</code>, then <code>to_i</code>. Passing <code>nil</code>
- *  raises a TypeError.
+ *  trying <code>to_int</code>, then <code>to_i</code>.
+ *
+ *  Passing <code>nil</code> raises a TypeError, while passing String that
+ *  does not conform with numeric representation raises an ArgumentError.
+ *  This behavior can be altered by passing <code>exception: false</code>,
+ *  in this case not convertible value will return <code>nil</code>.
  *
  *     Integer(123.999)    #=> 123
  *     Integer("0x1a")     #=> 26
  *     Integer(Time.new)   #=> 1204973019
  *     Integer("0930", 10) #=> 930
  *     Integer("111", 2)   #=> 7
- *     Integer(nil)        #=> TypeError
+ *     Integer(nil)        #=> TypeError: can't convert nil into Integer
+ *     Integer("x")        #=> ArgumentError: invalid value for Integer(): "x"
+ *
+ *     Integer("x", exception: false)        #=> nil
+ *
  */
 
 static VALUE
@@ -3575,17 +3583,19 @@ rb_Float(VALUE val) https://github.com/ruby/ruby/blob/trunk/object.c#L3583
 
 /*
  *  call-seq:
- *     Float(arg)    -> float
+ *     Float(arg, exception: true)    -> float
  *
  *  Returns <i>arg</i> converted to a float. Numeric types are converted
  *  directly, and with exception to string and nil the rest are converted using <i>arg</i>.to_f.
  *  Converting a <code>string</code> with invalid characters will result in a <code>ArgumentError</code>.
  *  Converting <code>nil</code> generates a <code>TypeError</code>.
+ *  Exceptions could be suppressed by passing <code>exception: false</code>.
  *
  *     Float(1)                 #=> 1.0
  *     Float("123.456")         #=> 123.456
  *     Float("123.0_badstring") #=> ArgumentError: invalid value for Float(): "123.0_badstring"
  *     Float(nil)               #=> TypeError: can't convert nil into Float
+ *     Float("123.0_badstring", exception: false)  #=> nil
  */
 
 static VALUE
Index: rational.c
===================================================================
--- rational.c	(revision 66497)
+++ rational.c	(revision 66498)
@@ -529,8 +529,8 @@ static VALUE nurat_s_convert(int argc, V https://github.com/ruby/ruby/blob/trunk/rational.c#L529
 
 /*
  * call-seq:
- *    Rational(x, y)  ->  rational
- *    Rational(arg)   ->  rational
+ *    Rational(x, y, exception: true)  ->  rational
+ *    Rational(arg, exception: true)   ->  rational
  *
  * Returns +x/y+ or +arg+ as a Rational.
  *
@@ -546,6 +546,8 @@ static VALUE nurat_s_convert(int argc, V https://github.com/ruby/ruby/blob/trunk/rational.c#L546
  *    Rational(nil)         #=> TypeError
  *    Rational(1, nil)      #=> TypeError
  *
+ *    Rational("10 cents", exception: false)  #=> nil
+ *
  * Syntax of the string form:
  *
  *   string form = extra spaces , rational , extra spaces ;

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