Difference between revisions of "Random Module"
Jump to navigation
Jump to search
(21 intermediate revisions by 2 users not shown)  
Line 1:  Line 1:  
−  This [[Module LibraryXQuery Module]] contains nondeterministic  +  This [[Module LibraryXQuery Module]] contains functions for computing random values. All functions except for [[#random:seededdoublerandom:seededdouble]] and [[#random:seededintegerrandom:seededinteger]] 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 {{Coderandom}} prefix.<br/> 
−  
=Functions=  =Functions=  
==random:double==  ==random:double==  
−  {  +  
+  { width='100%'  
    
−   width='  +   width='120'  '''Signatures''' 
−  {{Funcrandom:doublexs:double  +  {{Funcrandom:doublexs:double}}<br /> 
    
 '''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='  +   width='120'  '''Signatures''' 
−  {{Funcrandom:integer$max as xs:integer  +  {{Funcrandom:integerxs:integer}}<br />{{Funcrandom:integer$max as xs:integerxs:integer}}<br /> 
    
 '''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 />  
    
−    +   '''Errors''' 
−    +  {{Errorbounds#Errors}} the maximum value is out of bounds. 
}  }  
==random:seededdouble==  ==random:seededdouble==  
−  {  +  
+  { width='100%'  
    
−   width='  +   width='120'  '''Signatures''' 
−  {{Funcrandom:seededdouble$seed as xs:integer, $num as xs:integerxs:  +  {{Funcrandom:seededdouble$seed as xs:integer, $num as xs:integerxs:double*}}<br /> 
    
 '''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:seededinteger==  ==random:seededinteger==  
−  {  +  
+  { width='100%'  
    
−   width='  +   width='120'  '''Signatures''' 
−  {{Funcrandom:seededinteger$seed as xs:integer, $num as xs:integer, $max as xs:integer  +  {{Funcrandom:seededinteger$seed as xs:integer, $num as xs:integerxs:integer*}}<br />{{Funcrandom:seededinteger$seed as xs:integer, $num as xs:integer, $max as xs:integerxs:integer*}} 
    
 '''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 />  
    
−    +   '''Errors''' 
−    +  {{Errorbounds#Errors}} the maximum value is out of bounds.<br/>{{Errornegative#Errors}} the number of values to be returned is negative. 
}  }  
==random:gaussian==  ==random:gaussian==  
−  {  +  
+  { width='100%'  
    
−   width='  +   width='120'  '''Signatures''' 
−  {{Funcrandom:gaussian$num as xs:integerxs:  +  {{Funcrandom:gaussian$num as xs:integerxs:double*}}<br /> 
    
 '''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:seededpermutation==  
+  
+  { width='100%'  
+    
+   width='120'  '''Signatures'''  
+  {{Funcrandom:seededpermutation$seed as xs:integer, $items as item()*item()*}}  
    
−    +   '''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='  +   width='120'  '''Signatures''' 
{{Funcrandom:uuidxs:string}}  {{Funcrandom:uuidxs:string}}  
    
Line 84:  Line 91:  
 '''Examples'''   '''Examples'''  
    
−  * {{Code  +  * {{Coderandom:uuid() eq random:uuid()}} will (most probably) return the boolean value {{Codefalse}}. 
+  }  
+  
+  =Errors=  
+  
+  { class="wikitable" width="100%"  
+  ! width="110"Code  
+  Description  
+    
+  {{Codebounds}}  
+  The specified maximum value is out of bounds.  
+    
+  {{Codenegative}}  
+  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: [[#random:seededpermutationrandom:seededpermutation]]  
+  
+  ;Version 8.0  
+  
+  * Updated: [[#random:integerrandom:integer]], [[#random:seededintegerrandom:seededinteger]] raise error for invalid input.  
−  [[  +  The module was introduced with Version 7.5. It includes some functionality which was previously located in the [[Math_ModuleMath Module]]. 
Latest revision as of 13:23, 24 May 2018
This XQuery Module contains functions for computing random values. All functions except for random:seededdouble and random:seededinteger 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]
Signatures  random:double() as xs:double 
Summary  Returns a double value between 0.0 (inclusive) and 1.0 (exclusive). 
random:integer[edit]
Signatures  random:integer() as xs:integer 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:seededdouble[edit]
Signatures  random:seededdouble($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:seededinteger[edit]
Signatures  random:seededinteger($seed as xs:integer, $num as xs:integer) as xs:integer* random:seededinteger($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]
Signatures  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:seededpermutation[edit]
Signatures  random:seededpermutation($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]
Signatures  random:uuid() as xs:string

Summary  Creates a random universally unique identifier (UUID), represented as 128bit 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:seededpermutation
 Version 8.0
 Updated: random:integer, random:seededinteger 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.