random関連のドキュメントの更新 (#298)

* mt_rand() はPHP 8.0以降ValueError をスローする (php/doc-en#4660)

* `getrandmax`が小さいのはPHP 7.1までであることを明示 (php/doc-en#4664)

* 誤字訂正

* Mt19937 の重複についての訳を改善

* 「重複したシードが存在します」→「シードが重複します」

Author: takaram

language-snippets.ent

@@ -35,16 +35,16 @@ xmlns="http://docbook.org/ns/docbook"><simpara>この関数は PHP 5.3.0 で
  </para>
  <para>
   暗黙、または明示的にランダムなシードに依存する場合、
-  重複がそれ(4,294,967,296 個)よりも早く発生します。
-  誕生日のパラドックスによると、80,000 個以下のランダムな値を生成した場合でも、
-  シードの重複が 50&#37; の確率で発生します。
-  重複したシードの 10&#37; が、ざっと 30,000 個のランダムな値を生成したあとに発生します。
+  重複がそれ(4,294,967,296 個)よりもかなり早く発生します。
+  誕生日のパラドックスによると、80,000 個以下のランダムなシードを生成した場合でも、
+  50&#37; の確率でシードが重複します。
+  ざっと 30,000 個のランダムなシードを生成すると、10&#37; の確率でシードが重複します。
  </para>
  <para>
   このため、無視できる確率以上に重複したシーケンスが発生してはいけないアプリケーションでは、Mt19937 は適していません。
   再現可能なシードが必須の場合、
   <classname>Random\Engine\Xoshiro256StarStar</classname> と <classname>Random\Engine\PcgOneseq128XslRr64</classname>
-  が、ランダムな値が衝突しにくく、より大きなシードをサポートしています。
+  が、ずっと大きなシードをサポートしているため、衝突の可能性が低いです。
   再現可能なシードが必須でない場合、
   <classname>Random\Engine\Secure</classname>
   が、暗号学的にセキュアなランダム性を提供します。
@@ -354,7 +354,7 @@ xmlns="http://docbook.org/ns/docbook"><simpara>この機能は PHP 8.4.0 で
 xmlns="http://docbook.org/ns/docbook"><simpara>この関数は PHP 8.4.0 で
 <emphasis>非推奨</emphasis>になります。この関数に頼らないことを強く推奨します。</simpara></warning>'>
 
-<!ENTITY removed.php.future 'この非推奨の機能は、<emphasis xmlns="http://docbook.org/ns/docbook">きっと</emphasis> 
+<!ENTITY removed.php.future 'この非推奨の機能は、<emphasis xmlns="http://docbook.org/ns/docbook">きっと</emphasis>
 将来 <emphasis xmlns="http://docbook.org/ns/docbook">削除</emphasis> されるでしょう。'>
 
 <!ENTITY warn.deprecated.function.removed-5-3-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>
@@ -678,7 +678,7 @@ xmlns="http://docbook.org/ns/docbook"><simpara>この関数は PHP 8.1.0 で
      </listitem>
      <listitem>
       <simpara>
-       <constant>SORT_NATURAL</constant> - 要素の比較を文字列として行い、 
+       <constant>SORT_NATURAL</constant> - 要素の比較を文字列として行い、
        <function>natsort</function> と同様の「自然順」で比較します。
       </simpara>
      </listitem>
@@ -1318,7 +1318,7 @@ $font = 'SomeFont';
 <function>mb_regex_encoding</function> で指定した文字エンコーディングを、
 この関数の文字エンコーディングとして使用します。</para></note>'>
 
-<!ENTITY mbstring.encoding.parameter '<para xmlns="http://docbook.org/ns/docbook"><parameter>encoding</parameter> 
+<!ENTITY mbstring.encoding.parameter '<para xmlns="http://docbook.org/ns/docbook"><parameter>encoding</parameter>
 パラメータには文字エンコーディングを指定します。省略した場合、もしくは &null; の場合は、
 内部文字エンコーディングを使用します。</para>'>
 
@@ -1588,7 +1588,7 @@ object</parameter></term><listitem><para>手続き型のみ: <function>date_crea
 が返す <classname>DateTime</classname> オブジェクト</para></listitem></varlistentry>'>
 
 <!ENTITY date.datetime.description.modified '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>object</parameter></term>
-<listitem><para>手続き型のみ: 
+<listitem><para>手続き型のみ:
 <function>date_create</function> が返す <classname>DateTime</classname> オブジェクト。
 この関数は、このオブジェクトを変更します。</para></listitem></varlistentry>'>
 
@@ -1651,7 +1651,7 @@ object</parameter></term><listitem><para>手続き型のみ: <function>date_crea
   この関数は、HTML4 のパーサを使って入力をパースします。モダンなWebブラウザが採用している HTML5 のパースルールとは異なります。入力によっては、このことが原因で異なるDOM構造になるかもしれません。よって、この関数はHTMLを無害化する目的で安全に使えません。
  </simpara>
  <simpara>
-  HTML をパースする挙動は、利用している 
+  HTML をパースする挙動は、利用している
   <literal>libxml</literal> のバージョンに依存します。
   特にエッジケースやエラーハンドリングについてそれが当てはまります。
   HTML5 に準拠したパースを行うには、PHP 8.4 で追加される
@@ -2170,7 +2170,7 @@ PECL 拡張モジュールのインストール</link> という章にありま
 といった関連する情報については、次の場所にあります。'>
 
 <!ENTITY pecl.info.dead 'この拡張モジュールは、メンテナンスされておらず開発が止まっています。
-しかし、ソースコードは <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> 
+しかし、ソースコードは <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym>
 <acronym xmlns="http://docbook.org/ns/docbook">SVN</acronym> から取得できます。'>
 
 <!ENTITY pecl.info.dead.git 'この拡張モジュールは、メンテナンスされておらず開発が止まっています。
@@ -2620,7 +2620,7 @@ Apache 設定ファイルにパスの値を追加する際、例えば
 <!ENTITY imagick.method.available.0x657 'このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。'>
 <!ENTITY imagick.method.not.available.0x700 'このメソッドは、ImageMagick バージョン 7.0.0 以降で Imagick をコンパイルした場合には利用できません。'>
 
-<!ENTITY imagick.constant.available 'この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 
+<!ENTITY imagick.constant.available 'この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で
 行った場合に使用可能です。'>
 
 <!ENTITY imagick.deprecated.function-3-4-4 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>この関数は Imagick 3.4.4 以降では <emphasis>非推奨</emphasis> になりました。この関数に依存したコードを書くのはやめましょう。</simpara></warning>'>
@@ -4473,7 +4473,7 @@ local: {
     数値の後にドル記号 <literal>$</literal> を続けます。
    </para>
   </formalpara>
-  
+
   <para>
    <table>
     <title>フラグ一覧</title>
@@ -5268,7 +5268,7 @@ xmlns="http://docbook.org/ns/docbook"><simpara>この関数は、PECL uopz 5.0.0
     たいていの場合は、正しい SSL 証明書を持つサーバーと通信するならこれを変更する必要はありません。
     OpenSSL が、よく知られた CA バンドルを使うように設定されているからです。
    </para>
-   
+
    <para xmlns="http://docbook.org/ns/docbook">
     デフォルトの CA バンドルを上書きすることもできます。
     openssl.cafile あるいは openssl.capath を設定すればグローバルに変更でき、コンテキストオプション

reference/random/functions/mt-rand.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 0b6c76516a299395a3703e6df44f8ea4cb4549a8 Maintainer: hirokawa Status: ready -->
+<!-- EN-Revision: 0a5e7b12546b62a611a0cbc7105e617ab96fbcbd Maintainer: hirokawa Status: ready -->
 <!-- CREDITS: takagi,mumumu -->
 <refentry xml:id="function.mt-rand" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -65,10 +65,19 @@
    <parameter>min</parameter> (あるいは 0)
    から <parameter>max</parameter> (あるいは <function>mt_getrandmax</function>、それぞれ端点を含む)
    までの間のランダムな整数値を返します。
-   <parameter>max</parameter> が <parameter>min</parameter> より小さい場合は
-   &false; を返します。
   </para>
  </refsect1>
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     <parameter>max</parameter> が <parameter>min</parameter> より小さい場合
+     <classname>ValueError</classname> がスローされます。
+    </simpara>
+   </listitem>
+  </itemizedlist>
+ </refsect1>
  <refsect1 role="changelog">
   &reftitle.changelog;
   <para>
@@ -81,6 +90,14 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>8.0.0</entry>
+       <entry>
+        <parameter>max</parameter> が <parameter>min</parameter> より小さい場合は
+        <classname>ValueError</classname> がスローされます。
+        以前は <constant>E_WARNING</constant> が発生し、関数は &false; を返していました。
+       </entry>
+      </row>
       <row>
        <entry>7.2.0</entry>
        <entry>
@@ -92,7 +109,7 @@
       <row>
        <entry>7.1.0</entry>
        <entry>
-        <function>rand</function> は、<function>mt_rand</function> の 
+        <function>rand</function> は、<function>mt_rand</function> の
         <link linkend="migration71.incompatible.rand-srand-aliases">エイリアスになりました。</link>
        </entry>
       </row>

reference/random/functions/rand.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 826073522514072830b63bee2b6135dc675ea45d Maintainer: hirokawa Status: ready -->
+<!-- EN-Revision: bf672f5f2402ee78264a130c52defeed37fe44bf Maintainer: hirokawa Status: ready -->
 <!-- CREDITS: takagi,mumumu -->
 <refentry xml:id="function.rand" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -22,15 +22,15 @@
    オプションの引数
    <parameter>min</parameter>,<parameter>max</parameter>
    を省略してコールした場合、<function>rand</function> は 0 と
-   <function>getrandmax</function> の間の擬似乱数(整数)を返します。 
+   <function>getrandmax</function> の間の擬似乱数(整数)を返します。
    例えば、5 から 15 まで（両端を含む）の乱数を得たい場合、
    <literal>rand(5, 15)</literal> とします。
   </simpara>
   &caution.cryptographically-insecure;
   <note>
    <simpara>
-    （Windows のような）いくつかのプラットフォームでは、<function>getrandmax</function>
-    は 32767 と小さな値となっています。
+    PHP 7.1.0 より前のバージョンでは、（Windows のような）いくつかのプラットフォームにおいて
+    <function>getrandmax</function> は 32767 と小さな値となっていました。
     32767 より広い範囲にしたい場合、
     <parameter>min</parameter> および <parameter>max</parameter> を指定することで、
     これより大きな範囲の乱数を生成することができます。
@@ -102,7 +102,7 @@
       <row>
        <entry>7.1.0</entry>
        <entry>
-        <function>rand</function> は、<function>mt_rand</function> の 
+        <function>rand</function> は、<function>mt_rand</function> の
         <link linkend="migration71.incompatible.rand-srand-aliases">エイリアスになりました。</link>
        </entry>
       </row>
@@ -143,9 +143,9 @@ echo rand(5, 15), "\n";
   <warning>
    <para>
     <parameter>min</parameter> から <parameter>max</parameter>
-    までの幅を <function>mt_getrandmax</function> の範囲内におさめる必要があります。
+    までの幅を <function>getrandmax</function> の範囲内におさめる必要があります。
     つまり、(<parameter>max</parameter> -
-    <parameter>min</parameter>) &lt;= <function>mt_getrandmax</function>
+    <parameter>min</parameter>) &lt;= <function>getrandmax</function>
     でなければいけないということです。この範囲をこえてしまうと、
     <function>rand</function> が返す値のランダム性が、
     低品質になってしまいます。