http://www.zorba-xquery.com/modules/random

import module namespace r = "http://www.zorba-xquery.com/modules/random";

This module provides several functions for generating (pseudo-)random numbers and strings.

Matthias Brantner, Sorin Nasoi

xquery version "3.0" encoding "utf-8";

• the XQuery module can be found here.

	random ( ) as xs:integer This function generates one random number.
	random ( $num as xs:integer ) as xs:integer* external This function generates an arbitrary number of random numbers.
	random-between ( $lower as xs:integer, $upper as xs:integer ) as xs:integer This function generates one random number within a given range.
	random-between ( $lower as xs:integer, $upper as xs:integer, $num as xs:integer ) as xs:integer* This function generates an arbitrary number of random numbers within a given range.
	seeded-random ( $seed as xs:integer, $num as xs:integer ) as xs:integer* external This function generates an arbitrary number of pseudo-random numbers.
	seeded-random-between ( $seed as xs:integer, $lower as xs:integer, $upper as xs:integer, $num as xs:integer ) as xs:integer* This function generates an arbitrary number of pseudo-random numbers within a given range.
	uuid ( ) as xs:string external This function returns a uuid.

random

declare %ann:nondeterministic function r:random (
 ) as xs:integer

This function generates one random number. The function is nondeterministic.

The function is based on r:random#1. Specifically, it returns the value of invoking r:random(1).

• a random integer

random

declare %ann:nondeterministic function r:random (
            $num as xs:integer 
 ) as xs:integer* external

This function generates an arbitrary number of random numbers. The function is nondeterministic because the sequence is not repeatable.

However, the function is based on posix function srand() and rand(). Specifically, it invokes srand() with some random number based on the current time and then returns the values returned by invoking rand() $num-times.

• $num the length of the sequence returned

• $num random integers, or the empty sequence if $num is negative.

random-between

declare %ann:nondeterministic function r:random-between (
            $lower as xs:integer, 
            $upper as xs:integer 
 ) as xs:integer

This function generates one random number within a given range. The function is nondeterministic.

The function is based on r:random-between#3. Specifically, it returns the value of invoking r:random-betwen($lower, $upper, 1).

• $lower the lower bound for the random number
• $upper the upper bound for the random number

• a random integer within the given range

random-between

declare %ann:nondeterministic function r:random-between (
            $lower as xs:integer, 
            $upper as xs:integer, 
            $num as xs:integer 
 ) as xs:integer*

This function generates an arbitrary number of random numbers within a given range. The function is nondeterministic because the sequence is not repeatable.

• $lower the lower bound for every value within the sequence
• $upper the upper bound for every value within the sequence
• $num the length of the sequence returned

• $num pseudo-random integers within (and including) the range specified by $lower and $upper. It returns $num-times $lower if $lower is equal to $upper and the empty sequence if $num is negative.

• r:invalid-arg if $lower is greater than $upper

seeded-random

declare function r:seeded-random (
            $seed as xs:integer, 
            $num as xs:integer 
 ) as xs:integer* external

This function generates an arbitrary number of pseudo-random numbers. The sequence is repeatable by calling the function with the same seed.

The function is based on posix function srand() and rand(). Specifically, it invokes srand($seed) and then returns the values returned by invoking rand() $num-times.

Sequences returned by this function are not thread-safe (i.e. if multiple XQuery programs invoking this function are executed concurrently in several threads). This is because the function is based on srand() and rand().

• $seed the initial seed value for the sequence
• $num the length of the sequence returned

• $num pseudo-random integers, or the empty sequence if $num is negative.

• zerr:ZQXD0004 if the given seed is negative or great than the max value of unsigned int on the given platform.

seeded-random-between

declare function r:seeded-random-between (
            $seed as xs:integer, 
            $lower as xs:integer, 
            $upper as xs:integer, 
            $num as xs:integer 
 ) as xs:integer*

This function generates an arbitrary number of pseudo-random numbers within a given range. The sequence is repeatable by calling the function with the same seed and boundaries.

The function is based on the function r:seeded-random#2. Specifically, it's result is repeatable if called with the same arguments.

• $seed the initial seed value for the sequence
• $lower the lower bound for every value within the sequence
• $upper the upper bound for every value within the sequence
• $num the length of the sequence returned

• $num pseudo-random integers within (and including) the range specified by $lower and $upper. It returns $num-times $lower if $lower is equal to $upper and the empty sequence if $num is negative.

• zerr:ZQXD0004 if the given seed is negative or great than the max value of unsigned int on the given platform.
• r:invalid-arg if $lower is greater than $upper

uuid

declare %ann:nondeterministic function r:uuid (
 ) as xs:string external

This function returns a uuid. Note, that the function is not stable, that is, it returns a different UUID everytime the function is invoked.

• the generated UUID as xs:string