Difference between revisions of "Random Module"
Jump to navigation
Jump to search
(29 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | This [[Module Library|XQuery Module]] contains | + | 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 | + | 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/> |
− | |||
=Functions= | =Functions= | ||
− | ==random: | + | ==random:double== |
− | {| | + | |
− | |- | + | {| width='100%' |
− | | width=' | + | |- valign="top" |
− | | | + | | 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: | + | ==random:integer== |
− | {| | + | |
− | |- | + | {| width='100%' |
− | | width=' | + | |- valign="top" |
− | | | + | | 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 | + | ==random:seeded-double== |
− | {| | + | |
− | |- | + | {| width='100%' |
− | | width=' | + | |- valign="top" |
− | | | + | | 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- | + | ==random:seeded-integer== |
− | {| | + | |
− | |- | + | {| width='100%' |
− | | width=' | + | |- valign="top" |
− | | | + | | 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: | + | ==random:gaussian== |
− | {| | + | |
− | |- | + | {| width='100%' |
− | | width=' | + | |- valign="top" |
− | | | + | | 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=' | + | |- valign="top" |
− | | | + | | 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| | + | * {{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= | ||
− | + | ;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. | ||
− | [[ | + | 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 14: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.
Contents
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 |
|
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
- Added:
random:seeded-permutation
- Version 8.0
- Updated:
random:integer
,random:seeded-integer
raise error for invalid input.
The module was introduced with Version 7.5. It includes some functionality which was previously located in the Math Module.