Difference between revisions of "Random Module"

From BaseX Documentation
Jump to navigation Jump to search
 
(28 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This [[Module Library|XQuery Module]] contains non-deterministic functions for returning random values.
+
This [[Module Library|XQuery Module]] contains functions for computing random values. All functions except for {{Function||random:seeded-double}} and {{Function||random:seeded-integer}} are nondeterministic, i. e., they return different values for each call.
  
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the {{Code|http://basex.org/modules/random}} namespace, which is statically bound to the {{Code|random}} prefix.<br/>
+
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/random</nowiki></code> namespace, which is statically bound to the {{Code|random}} prefix.<br/>
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
 
=Functions=
 
=Functions=
  
 
==random:double==
 
==random:double==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
|{{Func|random:double||xs:double()}}<br />
+
| width='120' | '''Signature'''
|-
+
|<pre>random:double() as xs:double</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns a double value between 0.0 (inclusive) and 1.0 (exclusive).<br />
+
|Returns a double value between 0.0 (inclusive) and 1.0 (exclusive).<br/>
|-
 
|
 
|
 
 
|}
 
|}
  
 
==random:integer==
 
==random:integer==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
|{{Func|random:integer|$max as xs:integer?|xs:integer()}}<br />
+
| width='120' | '''Signature'''
|-
+
|<pre>random:integer(
 +
  $max as xs:integer := ()
 +
) as xs:integer</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns an integer value, either in the whole integer range or between 0 (inclusive) and the given maximum (exclusive)<br />
+
|Returns an integer value, either in the whole integer range or between 0 (inclusive) and the given maximum (exclusive)<br/>
|-
+
|- valign="top"
|  
+
| '''Errors'''
|
+
|{{Error|bounds|#Errors}} the maximum value is out of bounds.
 
|}
 
|}
  
 
==random:seeded-double==
 
==random:seeded-double==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
|{{Func|random:seeded-double|$seed as xs:integer, $num as xs:integer|xs:items()*}}<br />
+
| width='120' | '''Signature'''
|-
+
|<pre>random:seeded-double(
 +
  $seed as xs:integer,
 +
  $num   as xs:integer
 +
) as xs:double*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns a sequence with {{Code|$num}} double values between 0.0 (inclusive) and 1.0 (exclusive). The random values are created using the initial seed given in {{Code|$seed}}.<br />
+
|Returns a sequence with {{Code|$num}} double values between 0.0 (inclusive) and 1.0 (exclusive). The random values are created using the initial seed given in {{Code|$seed}}.<br/>
|-
 
|
 
|
 
 
|}
 
|}
  
 
==random:seeded-integer==
 
==random:seeded-integer==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
|{{Func|random:seeded-integer|$seed as xs:integer, $num as xs:integer, $max as xs:integer?|xs:items()*}}<br />
+
| width='120' | '''Signature'''
|-
+
|<pre>random:seeded-integer(
 +
  $seed as xs:integer,
 +
  $num   as xs:integer,
 +
  $max   as xs:integer := ()
 +
) as xs:integer*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns a sequence with {{Code|$num}} integer values, either in the whole integer range or between 0 (inclusive) and the given maximum (exclusive). The random values are created using the initial seed given in {{Code|$seed}}.<br />
+
|Returns a sequence with {{Code|$num}} integer values, either in the whole integer range or between 0 (inclusive) and the given maximum (exclusive). The random values are created using the initial seed given in {{Code|$seed}}.<br/>
|-
+
|- valign="top"
|  
+
| '''Errors'''
|
+
|{{Error|bounds|#Errors}} the maximum value is out of bounds.<br/>{{Error|negative|#Errors}} the number of values to be returned is negative.
 
|}
 
|}
  
 
==random:gaussian==
 
==random:gaussian==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
|{{Func|random:gaussian|$num as xs:integer|xs:items()*}}<br />
+
| width='120' | '''Signature'''
|-
+
|<pre>random:gaussian(
 +
  $num as xs:integer
 +
) as xs:double*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns a sequence with {{Code|$num}} double values. The random values are Gaussian (i.e. normally) distributed with the mean 0.0. and the derivation 1.0.<br />
+
|Returns a sequence with {{Code|$num}} double values. The random values are Gaussian (i.e. normally) distributed with the mean 0.0. and the derivation 1.0.<br/>
|-
+
|}
|  
+
 
|
+
==random:seeded-permutation==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>random:seeded-permutation(
 +
  $seed  as xs:integer,
 +
  $items  as item()*
 +
) as item()*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns a random permutation of the specified {{Code|$items}}. The random order is created using the initial seed given in {{Code|$seed}}.<br/>
 
|}
 
|}
  
 
==random:uuid==
 
==random:uuid==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
|{{Func|random:uuid||xs:string}}
+
| width='120' | '''Signature'''
|-
+
|<pre>random:uuid() as xs:string</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Creates a random universally unique identifier (UUID), represented as 128-bit value.
 
|Creates a random universally unique identifier (UUID), represented as 128-bit value.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* {{Code|math:uuid() eq math:uuid()}} will (most probably) return the boolean value {{Code|false}}.
+
* {{Code|random:uuid() eq random:uuid()}} will (most probably) return the boolean value {{Code|false}}.
 +
|}
 +
 
 +
=Errors=
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="110"|Code
 +
|Description
 +
|- valign="top"
 +
|{{Code|bounds}}
 +
|The specified maximum value is out of bounds.
 +
|- valign="top"
 +
|{{Code|negative}}
 +
|The specified number of values to be returned is negative.
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
  
The module was introduced with Version X. It includes functionality which was previously located in the [[Math_Module|Math Module]].
+
;Version 9.0
 +
 
 +
* Updated: error codes updated; errors now use the module namespace
 +
 
 +
;Version 8.5
 +
 
 +
* Added: {{Function||random:seeded-permutation}}
 +
 
 +
;Version 8.0
 +
 
 +
* Updated: {{Function||random:integer}}, {{Function||random:seeded-integer}} raise error for invalid input.
  
[[Category:XQuery]]
+
The module was introduced with Version 7.5. It includes some functionality which was previously located in the [[Math_Module|Math Module]].

Latest revision as of 13:53, 31 October 2023

This XQuery Module contains functions for computing random values. All functions except for random:seeded-double and random:seeded-integer are nondeterministic, i. e., they return different values for each call.

Conventions[edit]

All functions and errors in this module are assigned to the http://basex.org/modules/random namespace, which is statically bound to the random prefix.

Functions[edit]

random:double[edit]

Signature
random:double() as xs:double
Summary Returns a double value between 0.0 (inclusive) and 1.0 (exclusive).

random:integer[edit]

Signature
random:integer(
  $max  as xs:integer  := ()
) as xs:integer
Summary Returns an integer value, either in the whole integer range or between 0 (inclusive) and the given maximum (exclusive)
Errors bounds: the maximum value is out of bounds.

random:seeded-double[edit]

Signature
random:seeded-double(
  $seed  as xs:integer,
  $num   as xs:integer
) as xs:double*
Summary Returns a sequence with $num double values between 0.0 (inclusive) and 1.0 (exclusive). The random values are created using the initial seed given in $seed.

random:seeded-integer[edit]

Signature
random:seeded-integer(
  $seed  as xs:integer,
  $num   as xs:integer,
  $max   as xs:integer  := ()
) as xs:integer*
Summary Returns a sequence with $num integer values, either in the whole integer range or between 0 (inclusive) and the given maximum (exclusive). The random values are created using the initial seed given in $seed.
Errors bounds: the maximum value is out of bounds.
negative: the number of values to be returned is negative.

random:gaussian[edit]

Signature
random:gaussian(
  $num  as xs:integer
) as xs:double*
Summary Returns a sequence with $num double values. The random values are Gaussian (i.e. normally) distributed with the mean 0.0. and the derivation 1.0.

random:seeded-permutation[edit]

Signature
random:seeded-permutation(
  $seed   as xs:integer,
  $items  as item()*
) as item()*
Summary Returns a random permutation of the specified $items. The random order is created using the initial seed given in $seed.

random:uuid[edit]

Signature
random:uuid() as xs:string
Summary Creates a random universally unique identifier (UUID), represented as 128-bit value.
Examples
  • random:uuid() eq random:uuid() will (most probably) return the boolean value false.

Errors[edit]

Code Description
bounds The specified maximum value is out of bounds.
negative The specified number of values to be returned is negative.

Changelog[edit]

Version 9.0
  • Updated: error codes updated; errors now use the module namespace
Version 8.5
Version 8.0

The module was introduced with Version 7.5. It includes some functionality which was previously located in the Math Module.