<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = mthrm.xml                                                          = -->
<!-- = standard math module - reference manual                            = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 1999-2013 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="mth" number="i">
  <title>Standard Math Reference</title>

  <!-- =================================================================== -->
  <!-- = global functions                                                = -->
  <!-- =================================================================== -->

  <functions>
    <func nameset="afnix:mth">
      <name>get-random-integer</name>
      <retn>Integer</retn>
      <args>none|Integer</args>
      <p>
	The <code>get-random-integer</code> function returns a random integer
	number. Without argument, the integer range is machine
	dependent. With one integer argument, the resulting integer number
	is less than the specified maximum bound.
      </p>
    </func>
    
    <func nameset="afnix:mth">
      <name>get-random-real</name>
      <retn>Real</retn>
      <args>none|Boolean</args>
      <p>
	The <code>get-random-real</code> function returns a random real
	number between 0.0 and 1.0. In the first form, without argument,
	the random number is between 0.0 and 1.0 with 1.0 included. In the
	second form, the boolean flag controls whether or not the 1.0 is
	included in the result. If the argument is false, the 1.0 value is
	guaranted to be excluded from the result. If the argument is true,
	the 1.0 is a possible random real value. Calling this function
	with the argument set to true is equivalent to the first form
	without argument.
      </p>
    </func>

    <func nameset="afnix:mth">
      <name>get-random-relatif</name>
      <retn>Relatif</retn>
      <args>Integer|Integer Boolean</args>
      <p>
	The <code>get-random-relatif</code> function returns a n bits random
	positive relatif number. In the first form, the argument is the
	number of bits. In the second form, the first argument is the
	number of bits and the second argument, when true produce an odd
	number, or an even number when false.
      </p>
    </func>

    <func nameset="afnix:mth">
      <name>get-random-prime</name>
      <retn>Relatif</retn>
      <args>Integer</args>
      <p>
	The <code>get-random-prime</code> function returns a n bits random
	positive relatif probable prime number. The argument is the number
	of bits. The prime number is generated by using the Miller-Rabin
	primality test. As such, the returned number is declared probable
	prime. The more bits needed, the longer it takes to generate such
	number.
      </p>
    </func>

    <func nameset="afnix:mth">
      <name>get-random-bitset</name>
      <retn>Bitset</retn>
      <args>Integer</args>
      <p>
	The <code>get-random-bitset</code> function returns a n bits random
	bitset. The argument is the number of bits.
      </p>
    </func>

    <func nameset="afnix:mth">
      <name>fermat-p</name>
      <retn>Boolean</retn>
      <args>Integer|Relatif Integer|Relatif</args>
      <p>
	The <code>fermat-p</code> predicate returns true if the little
	fermat theorem is validated. The first argument is the base number
	and the second argument is the prime number to validate.
      </p>
    </func>

    <func nameset="afnix:mth">
      <name>miller-rabin-p</name>
      <retn>Boolean</retn>
      <args>Integer|Relatif Integer|Relatif</args>
      <p>
	The <code>miller-rabin-p</code> predicate returns true if the
	Miller-Rabin test is validated. The first argument is the base
	number and the second argument is the prime number to validate.
      </p>
    </func>

    <func nameset="afnix:mth">
      <name>prime-probable-p</name>
      <retn>Boolean</retn>
      <args>Integer|Relatif [Integer]</args>
      <p>
	The <code>prime-probable-p</code> predicate returns true if
	the argument is a probable prime. In the first form, only an
	integer or relatif number is required. In the second form, the
	number of iterations is specified as the second argument. By
	default, the number of iterations is specified to 56.
      </p>
    </func>
  </functions>
</appendix>
