Merge pull request rurema#3302 from scivola/improve-Float-methods

Float#<=>, to_r, to_s を改善

Author: znz

manual/api/_builtin/Float.md

@@ -104,16 +104,35 @@ p 0.0 ** 0 # => 1.0
 
 ### def <=>(other) -> -1 | 0 | 1 | nil
 
-`self` と `other` を比較して、`self` が大きい時に正、
-等しい時に `0`、小さい時に負の整数を返します。
+`self` を `other` と比較し、`self` のほうが大きい場合に `1`、
+等しい場合に `0`、小さい場合に `-1` を返します。
 比較できない場合は `nil` を返します
 
-```ruby title="例"
-p 3.05 <=> 3.14   # => -1
-p 1.732 <=> 1.414 # => 1
+返り値を覚えるには、`<=>` を `-` に置き換えてみるとよいでしょう。`x <=> y` と `x - y` は符号が一致します。
+
+```ruby title="比較できる例"
+p 3.05 <=> 3.14     # => -1
+p 1.732 <=> 1.414   # => 1
 p 3.3 - 3.3 <=> 0.0 # => 0
-p 3.14 <=> "hoge" # => nil
+
+# 正負の無限大も比較できる
+p 3.14 <=> Float::INFINITY  # => -1
+p 3.14 <=> -Float::INFINITY # => 1
+p Float::INFINITY <=> -Float::INFINITY # => 1
+
+# Complex オブジェクトでも虚部がゼロなら比較できる
+p 3.14 <=> 3.1+0i # => 1
+```
+
+```ruby title="比較できない例"
+# NaN とは比較できない
 p 3.14 <=> 0.0/0.0  # => nil
+
+# 虚部がゼロでない複素数とは比較できない
+p 3.14 <=> 1i # => nil
+
+# 数値でないものは Float と比較できない
+p 3.14 <=> "3.1" # => nil
 ```
 
 ### def ==(other) -> bool
@@ -486,8 +505,7 @@ p 0.1.negative?  # => false
 
 `self` を人間が読みやすい形の文字列表現にして返します。
 
-固定小数点、浮動小数点の形式か、 `"Infinity"`、`"-Infinity"`、`"NaN"` のいず
-れかを返します。
+10進固定小数点、10進浮動小数点の形式か、`"Infinity"`、`"-Infinity"`、`"NaN"` のいずれかを返します。
 
 - **return** -- 文字列を返します。
 
@@ -500,6 +518,10 @@ p (1.0/0.0).to_s         # => "Infinity"
 p (0.0/0.0).to_s         # => "NaN"
 ```
 
+`0.1.to_s` が文字列 `"0.1"` を返すのは自明ではありません。
+数値リテラル `0.1` によって生成される Float オブジェクトは、数学的には 0.1 からわずかにずれた値であり、厳密な小数表示は循環小数になります。
+それに対し、`Float#to_s` は Float が持つ精度に見合った穏当な文字列表現を返します。
+
 ### def arg   -> 0 | Float
 ### def angle -> 0 | Float
 ### def phase -> 0 | Float
@@ -541,10 +563,24 @@ p 0.5.numerator         # => 1
 
 ### def to_r -> Rational
 
-`self` を [c:Rational] に変換します。
+`self` を [c:Rational] オブジェクトに変換したものを返します。
+
+浮動小数点数は、`Float::INFINITY`, `-Float::INFINITY`, `Float::NAN` を除けば数学的には有理数を表しています。その値を得るメソッドです。
+
+- **raise** `FloatDomainError` -- `self` が `Float::INFINITY`, `-Float::INFINITY`, `Float::NAN` の場合に発生します。
 
 ```ruby title="例"
-p 0.5.to_r    # => (1/2)
+p 0.0.to_r  # => (0/1)
+p 0.75.to_r # => (3/4)
+```
+
+```ruby title="リテラルで得られるFloatの厳密値を知る例"
+p 0.1.to_r # => (3602879701896397/36028797018963968)
+p 0.1r     # => (1/10)
+# 浮動小数点数リテラル `0.1` によって生成される Float オブジェクトは
+# 数学的には 0.1 とはわずかに異なる数を表しており、
+# 有理数リテラル `0.1r` で生成される Rational オブジェクトとは
+# 値が一致しない
 ```
 
 - **SEE** [m:Float#rationalize]