eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Random':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: Random


Inheritance:

   Object
   |
   +--Stream
      |
      +--Random
         |
         +--RandomGNUSmalltalk
         |
         +--RandomGenerator

Package:
stx:libbasic2
Category:
Magnitude-Numbers-Random
Version:
rev: 1.72 date: 2018/04/30 19:38:45
user: cg
file: Random.st directory: libbasic2
module: stx stc-classLibrary: libbasic2
Author:
Claus Gittinger

Description:


A facade to the actual RandomGenerator.
In previous versions, Random was a very bad fallback random generator,
with an included warning, to not use it.

Now this old generator was renamed to RandomGNUSmalltalk,
and the default generator used is the one provided by the much
better RandomGenerator class.

    Random new next:10   


Related information:

    http://www0.cs.ucl.ac.uk/staff/d.jones/GoodPracticeRNG.pdf
    RandomTT800
    -
    a
    new
    random
    generator
    RandomParkMiller
    -
    another
    new
    random
    generator

Class protocol:

instance creation
o  new
return a new random generator.
Here, this instance creation message is forwarded to the standardGenerator
usage example(s):
     Random new

o  random
return a new random generator.
Defined here for compatibility with StreamCipher

o  seed: seedValue
return a new random generator with initial seed.
Here, this instance creation message is forwarded to the standardGenerator

o  sharedGenerator
return a shared random generator.

o  standard
return the 'standard' generator

o  standardGeneratorClass
return the class used for the 'standard' generator

random numbers
o  next
return the next random number in the range 0..1
This method behaves like the corresponding instance method,
but allows generation of random numbers without
a need for an instance of Random to be kept around.
This uses a common, shared generator.
usage example(s):
     Transcript showCR:(Random next).
     Transcript showCR:(Random next).
     Transcript showCR:(Random next).
     Transcript showCR:(Random next).

o  nextBetween: start and: stop
return a random number between start and stop.
This method behaves like the corresponding instance method,
but allows generation of random numbers without
a need for an instance of Random to be kept around.
This uses a common, shared generator.
usage example(s):
     Transcript showCR:(Random nextBetween:1 and:100).
     Transcript showCR:(Random nextBetween:1 and:100).
     Transcript showCR:(Random nextBetween:1 and:100).
     Transcript showCR:(Random nextBetween:1 and:100).

o  nextBoolean
return a boolean random.
This method behaves like the corresponding instance method,
but allows generation of random numbers without
a need for an instance of Random to be kept around.
This uses a common, shared generator.
usage example(s):
     Transcript showCR:(Random nextBoolean).
     Transcript showCR:(Random nextBoolean).
     Transcript showCR:(Random nextBoolean).
     Transcript showCR:(Random nextBoolean).

o  nextInteger
return an integral random number.
This method behaves like the corresponding instance method,
but allows generation of random numbers without
a need for an instance of Random to be kept around.
This uses a common, shared generator.
usage example(s):
     Transcript showCR:(Random nextInteger).
     Transcript showCR:(Random nextInteger).
     Transcript showCR:(Random nextInteger).
     Transcript showCR:(Random nextInteger).

o  nextIntegerBetween: start and: stop
return an integral random number between start and stop.
This method behaves like the corresponding instance method,
but allows generation of random numbers without
a need for an instance of Random to be kept around.
This uses a common, shared generator.
usage example(s):
     Transcript showCR:(Random nextIntegerBetween:1 and:10).
     Transcript showCR:(Random nextIntegerBetween:1 and:10).
     Transcript showCR:(Random nextIntegerBetween:1 and:10).
     Transcript showCR:(Random nextIntegerBetween:1 and:10).

o  nextLettersOrDigits: count
get the next count printable letters or digits [0-9A-Za-z].
usage example(s):
     Transcript showCR:(Random nextLettersOrDigits:10).
     Transcript showCR:(Random nextLettersOrDigits:10).
     Transcript showCR:(Random nextLettersOrDigits:10).
     Transcript showCR:(Random nextLettersOrDigits:10).

seeding
o  randomSeed
return a number useful for seeding.
This takes the current processor's time, plus the processor's process id,
plus some value depending on the memory allocation state,
plus a random salt, and shuffles those bits around.
The entropy returned should be reasonable enough for a good seed of a good rnd
generator. However, keep in mind, that it only has a limited number of entropy bits
(in the order of 32).
But it should be much better than what is commonly used in older
programs (current time) or even a constant.
usage example(s):
     10 timesRepeat:[Transcript showCR:self randomSeed].
     10 timesRepeat:[Transcript showCR:(self randomSeed bitAnd:16rFFFF)].
     self randomSeed bitAnd:16rFFFFFFFF

testing
o  bucketTest: randy
A quick-and-dirty bucket test. Prints nbuckets values on the Transcript.
Each should be 'near' the value of ntries. Any run with any value 'far' from ntries
indicates something is very wrong. Each run generates different values.
For a slightly better test, try values of nbuckets of 200-1000 or more;
go get coffee.
This is a poor test; see Knuth.
Some 'OK' runs:
1000 1023 998 969 997 1018 1030 1019 1054 985 1003
1011 987 982 980 982 974 968 1044 976
1029 1011 1025 1016 997 1019 991 954 968 999 991
978 1035 995 988 1038 1009 988 993 976

usage example(s):
Execute this:  
         self bucketTest: self new
         self bucketTest: RandomGenerator new

o  chiSquareTest
Chi-Squared Test - from R.Sedgewick's 1st ed. of 'Algorithms',
o N = number of samples
o r = range of random numners is [0,r) -- condition: N >= 10r.
o Random number generator 'passes' if chisquare value is very close to r
o Repeat test several times, since it may be *wrong* 1 out of 10 trials.
usage example(s):
     self chiSquareTest 
     RandomGenerator chiSquareTest


Instance protocol:

Compatibility-Squeak
o  nextInt: upperBound
Answer a random integer in the interval [1, anInteger].
usage example(s):
     Random new nextInt:10

o  nextIntFrom: lowerBound to: upperBound
return a random integer in the given range
usage example(s):
     Random new nextIntFrom:5 to:10

o  seed: anInteger

accessing-reading
o  next
return the next random number in the range ]0..1[

** This method raises an error - it must be redefined in concrete classes **

o  next: count
return the next count random numbers in the range ]0..1[
usage example(s):
     (RandomGenerator new) next:10

o  next: count integerBetween: min and: max
return the next count random integers in min..max
usage example(s):
     (RandomGenerator new) next:100 integerBetween:0 and:100

o  nextBetween: start and: stop
return a random number in the range ]start..stop[.
claus: the original GNU version has a bug in returning values
from the interval [start .. stop+1]

o  nextBoolean
return true or false by random

o  nextByte
return the next integral random number byte in the range 0 .. 16rFF

o  nextBytes: count
return count random bytes (0..16rFF each)
usage example(s):
     Transcript showCR:(RandomGenerator new nextBytes:20).  

o  nextBytesNonZero: count
return count random bytes, none of which is zero (i.e. 1..16rFF each)
usage example(s):
     Transcript showCR:(Random new nextBytesNonZero:20).

o  nextCharacters: count
get the next cnt printable characters.
We answer printable characters in the ascii range (codepoints 32 - 126)
usage example(s):
      RandomGenerator new nextCharacters:8 

o  nextInteger
return the next integral random number,
in the range 0 .. self maxInteger

** This method raises an error - it must be redefined in concrete classes **

o  nextIntegerBetween: start and: stop
return an integral random number in [start..stop] (inclusive)
usage example(s):
shows pair-combination counts

     |r v prev this counts|

     v := TextView new .
     v extent:500@250.
     v list:#('xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
              'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
              'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
              'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
              'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
              'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
              'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
              'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
              'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
              'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx').
     v openAndWait.
     counts := (1 to:10) collect:[:row | Array new:10 withAll:0].

     r := self new.
     prev := r nextIntegerBetween:1 and:10.
     10000 timesRepeat:[
         100 timesRepeat:[
            this := r nextIntegerBetween:1 and:10.
            (counts at:this) at:prev put:((counts at:this) at:prev)+1.
         ].
         v list:(counts collect:[:row |
                    '%4d %4d %4d %4d %4d %4d %4d %4d %4d %4d'printf:row ]).
         prev := this.
     ].

o  nextLettersOrDigits: count
get a random string consisting of count printable letters or digits [0-9A-Za-z].
usage example(s):
      Random new nextLettersOrDigits:40 

blocked methods
o  contents
blocked from use - contents makes no sense for random generators

o  nextPut: value
blocked from use - it makes no sense for randoms

initialization
o  initialize

private
o  addEntropy: entropyBytes
add some entropy - ignored here

o  seed

o  setSeed
set the initial seed value based on the current time and processId.
These numbers implement a maximum period generator which passes
the spectral test for randomness for dimensions 2 3 4 5 6 and
the product does not overflow 2 raisedTo:29.

Use both time and processId for seed, to make different processes
return different Random numbers

o  setSeed: seedValue
set the initial seed and intialize the PRNG parameters.

** This method raises an error - it must be redefined in concrete classes **

o  step
compute the next random integer

** This method raises an error - it must be redefined in concrete classes **

testing
o  atEnd
instances of Random can always give more numbers

o  isReadable

o  isWritable
return true, if writing is supported by the receiver.
Random Generators never are

o  maxInteger
the max value returned by self nextInteger

** This method raises an error - it must be redefined in concrete classes **


Examples:


    |rnd|

    rnd := Random new.
    10 timesRepeat:[
        Transcript showCR:(rnd next)
    ]
rolling a dice:
    |rnd|

    rnd := Random new.
    10 timesRepeat:[
        Transcript showCR:(rnd nextIntegerBetween:1 and:6)
    ]


ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Sat, 17 Nov 2018 08:41:15 GMT