random: Add examples for the engine constructors (#2197)

Author: TimWolla

reference/random/random/engine/mt19937/construct.xml

@@ -79,18 +79,13 @@
    <programlisting role="php">
 <![CDATA[
 <?php
+// Uses a random 32 Bit seed.
+$e = new \Random\Engine\Mt19937();
 
-/* ... */
-
+$r = new \Random\Randomizer($e);
 ?>
 ]]>
    </programlisting>
-   &example.outputs.similar;
-   <screen>
-<![CDATA[
-...
-]]>
-   </screen>
   </example>
  </refsect1>
 

reference/random/random/engine/pcgoneseq128xslrr64/construct.xml

@@ -97,16 +97,36 @@
    <programlisting role="php">
 <![CDATA[
 <?php
+// Uses a random 128 Bit seed.
+$e = new \Random\Engine\PcgOneseq128XslRr64();
 
-/* ... */
+$r = new \Random\Randomizer($e);
+?>
+]]>
+   </programlisting>
+  </example>
+  <example>
+   <title>Deriving a seed from a &string;</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$string = "My string seed";
+
+// Hash the string with truncated SHA-256 using binary output
+// to turn the $string into a 128 Bit seed. Using the same
+// string will result in the same sequence of randomness.
+$e = new \Random\Engine\PcgOneseq128XslRr64(
+    substr( hash( 'sha256', $string, binary: true ), 0, 16 )
+);
 
+echo bin2hex( $e->generate() ), "\n";
 ?>
 ]]>
    </programlisting>
-   &example.outputs.similar;
+   &example.outputs;
    <screen>
 <![CDATA[
-...
+8333ef59315b16d8
 ]]>
    </screen>
   </example>

reference/random/random/engine/xoshiro256starstar/construct.xml

@@ -103,16 +103,36 @@
    <programlisting role="php">
 <![CDATA[
 <?php
+// Uses a random 256 Bit seed.
+$e = new \Random\Engine\Xoshiro256StarStar();
 
-/* ... */
+$r = new \Random\Randomizer($e);
+?>
+]]>
+   </programlisting>
+  </example>
+  <example>
+   <title>Deriving a seed from a &string;</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$string = "My string seed";
+
+// Hash the string with SHA-256 using binary output to turn the
+// $string into a 256 Bit seed. Using the same string will result
+// in the same sequence of randomness.
+$e = new \Random\Engine\Xoshiro256StarStar(
+    hash( 'sha256', $string, binary: true )
+);
 
+echo bin2hex( $e->generate() ), "\n";
 ?>
 ]]>
    </programlisting>
-   &example.outputs.similar;
+   &example.outputs;
    <screen>
 <![CDATA[
-...
+6e013453678388c2
 ]]>
    </screen>
   </example>