Merge pull request #5 from rurema/update-generated-documents

Update generated documents

Author: github-actions[bot]

db/db-3.0/class/-numeric

@@ -203,3 +203,116 @@ class Numeric
   end
 end
 //}
+
+
+===[a:division] 除法と商・剰余
+
+Numeric には除法（除算；割り算；division）に関わるメソッドがいくつもありますが、
+除法にはいくつか種類があるため、全貌が把握しづらくなっています。
+
+この節では除法の種類を説明し、各メソッドがどの除法に基づいているのかが分かるようにします。
+
+まず用語ですが、割られる数を被除数（dividend）、割る数を除数（divisor）、
+割った結果を商（quotient）と言います。
+
+除法は大きく分けて二つあります。
+
+そのうちの一つを、ここでは「普通の除法」と呼ぶことにします。
+
+普通の除法は、被除数を x、除数を y、商を q としたとき、x == q×y となるよう定義された除法です。
+7 割る 2 を 3.5 とする除法は普通の除法です。
+
+普通の除法における商をここでは「普通の商」と呼ぶことにしましょう。
+
+もう一つの除法は、商が必ず整数になるよう定義されるもので、これを「整除法」と言います。
+7 割る 2 を 3 余り 1 とする除法は整除法です。
+
+整除法における商をとくに「整商」と言います。
+
+整除法では、被除数を x、除数を y、商を q としたとき、x と q×y が一致する（つまり割り切れる）とは限りません。
+
+その差 x − q×y を剰余（余り；remainder）と言います。
+整除法は商と剰余がセットで決まる除法なので「剰余付き除法」とも呼ばれます。
+
+しばしば「整除法は整数の世界でしか成り立たない」と誤解されていますが、
+2.5 m の紐から 0.75 m の紐が何本取れて何 m の半端が出るか、という問題を
+考えれば、被除数・除数が整数でなくてもよいことが分かります。
+
+//emlist[例: Float の世界の整商と剰余][ruby]{
+p 2.5.divmod(0.75) # => [3, 0.25]
+# 2.5 m の紐から 0.75 m の紐が 3 本取れて 0.25 m 余る
+//}
+
+ただし、複素数の世界では整商・剰余は考えないので、Complex に divmod など
+のメソッドは定義されていません。
+
+以下では、まず普通の除法に基づくメソッドについて述べます。
+
+普通の商を得るメソッドは [[m:Numeric#quo]] です。
+quo の返り値のクラスは、被除数・除数のクラスによって異なります。
+例えば、被除数・除数の一方が Integer、他方が Float なら返り値は Float です。
+
+普通の商を得るメソッドには、[[m:Numeric#fdiv]] もあります。
+これは商を Float で返します（被除数・除数の一方が Complex のときは
+Complex を返します）。
+
+整数同士の除法の場合、quo は厳密値を Rational で返しますが、
+fdiv では丸め誤差が生じうることに注意してください。
+
+次に整除法に基づくメソッドについて述べます。
+
+重要なことは、整除法の定義（言い換えれば整商・剰余の定義）がいくつもある、ということです。
+
+しかし、どの定義にも共通していることが二つあります。
+
+それは、被除数を x、除数を y としたときの整商を q、剰余を r とすると、第一に
+
+x == y * q + r （ただし q は整数）
+
+が成り立つということです。
+第二に、剰余 r は「半端」ですから、r の絶対値は y の絶対値より小さくなくては
+ならないということです。
+
+この二つを満たす整商・剰余の定義は何通りもありますが、
+Ruby では、剰余に関して二通りの定義を採用し、
+[[m:Numeric#modulo]] メソッドと [[m:Numeric#remainder]] メソッドとして
+実装されています。
+
+modulo は、
+
+  * y > 0 のとき 0 <= r <  y
+  * y < 0 のとき y <  r <= 0
+
+となるように定められた剰余です。
+定義からすぐ分かるとおり、剰余 r の符号は除数 y の符号と一致します。
+
+modulo の別名は % で、普通はメソッド呼び出しの形ではなく二項演算子の
+形で用います。
+
+modulo に対応する整商は [[m:Numeric#div]] です。
+これは、普通の商を [[m:Numeric#floor]] で整数化したものと
+一致します。
+
+さきほどの例で出てきた [[m:Numeric#divmod]] は、
+div と modulo の値を一度に配列で返すメソッドです。
+
+一方、remainder は
+
+  * x > 0 のとき  0   <= r <  |y|
+  * x < 0 のとき -|y| <  r <= 0
+
+となるように定められた剰余です。
+定義からすぐ分かるとおり、剰余 r の符号は被除数 x の符号と一致します。
+
+これに対応する整商を得るメソッドはありませんが、
+x.quo(y).truncate で得ることができます。
+
+x と y がともに正のときと、ともに負のとき、modulo と remainder は
+一致します。
+
+商を得るメソッドには [[m:Numeric#/]] もあります。
+普通はメソッド呼び出しの形ではなく、二項演算子として用います。
+
+これは被除数・除数のクラスによって挙動が異なります。例えば Integer 同士なら div と同じ、Integer や Rational と Float なら quo と同じ、といった具合です。
+
+被除数のクラスの / メソッドの説明をご覧ください。

db/db-3.0/class/-string-i-o

@@ -1,6 +1,6 @@
 type=class
-superclass=Data
-included=
+superclass=Object
+included=Enumerable
 extended=
 dynamically_included=
 dynamically_extended=

db/db-3.0/method/-numeric/i.=25._builtin

@@ -1,7 +1,7 @@
 names=%,modulo
 visibility=public
 kind=defined
-source_location=refm/api/src/_builtin/Numeric:644
+source_location=refm/api/src/_builtin/Numeric:771
 
 --- modulo(other)    -> Numeric
 --- %(other)         -> Numeric

db/db-3.0/method/-numeric/i.=2b=40._builtin

@@ -1,7 +1,7 @@
 names=+@
 visibility=public
 kind=defined
-source_location=refm/api/src/_builtin/Numeric:362
+source_location=refm/api/src/_builtin/Numeric:489
 
 --- +@    -> self
 

db/db-3.0/method/-numeric/i.=2d=40._builtin

@@ -1,7 +1,7 @@
 names=-@
 visibility=public
 kind=defined
-source_location=refm/api/src/_builtin/Numeric:375
+source_location=refm/api/src/_builtin/Numeric:502
 
 --- -@    -> Numeric
 

db/db-3.0/method/-numeric/i.=3c=3d=3e._builtin

@@ -1,7 +1,7 @@
 names=<=>
 visibility=public
 kind=defined
-source_location=refm/api/src/_builtin/Numeric:891
+source_location=refm/api/src/_builtin/Numeric:1018
 
 --- <=>(other) -> -1 | 0 | 1 | nil
 

db/db-3.0/method/-numeric/i.abs._builtin

@@ -1,7 +1,7 @@
 names=abs,magnitude
 visibility=public
 kind=defined
-source_location=refm/api/src/_builtin/Numeric:386
+source_location=refm/api/src/_builtin/Numeric:513
 
 --- abs        -> Numeric
 --- magnitude  -> Numeric

db/db-3.0/method/-numeric/i.abs2._builtin

@@ -1,7 +1,7 @@
 names=abs2
 visibility=public
 kind=defined
-source_location=refm/api/src/_builtin/Numeric:925
+source_location=refm/api/src/_builtin/Numeric:1052
 
 --- abs2 -> Numeric
 

db/db-3.0/method/-numeric/i.angle._builtin

@@ -1,7 +1,7 @@
 names=angle,arg,phase
 visibility=public
 kind=defined
-source_location=refm/api/src/_builtin/Numeric:939
+source_location=refm/api/src/_builtin/Numeric:1066
 
 --- arg   -> 0 | Math::PI
 --- angle -> 0 | Math::PI

db/db-3.0/method/-numeric/i.ceil._builtin

@@ -1,7 +1,7 @@
 names=ceil
 visibility=public
 kind=defined
-source_location=refm/api/src/_builtin/Numeric:397
+source_location=refm/api/src/_builtin/Numeric:524
 
 --- ceil   -> Integer