"Fossies" - the Fresh Open Source Software Archive

Member "FreeBASIC-1.08.1-source/doc/manual/cache/KeyPgRandomize.wakka" (6 Jul 2021, 5453 Bytes) of package /linux/privat/FreeBASIC-1.08.1-source.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "KeyPgRandomize.wakka": 1.08.0_vs_1.08.1.

    1 {{fbdoc item="title" value="RANDOMIZE"}}----
    2 Seeds the random number generator
    3 
    4 {{fbdoc item="syntax"}}##
    5 	[[KeyPgDeclare|declare]] [[KeyPgSub|sub]] **Randomize** ( [[KeyPgByval|byval]] //seed// [[KeyPgAs|as]] [[KeyPgDouble|double]] = -1.0, [[KeyPgByval|byval]] //algorithm// [[KeyPgAs|as]] [[KeyPgLong|long]] = 0 )
    6 ##
    7 {{fbdoc item="usage"}}##
    8 	**Randomize** [ //seed// ][, //algorithm// ]
    9 ##
   10 {{fbdoc item="param"}}
   11 	##//seed//##
   12 		A ##[[KeyPgDouble|double]]## seed value for the random number generator, but the fractional part is clipped for all algorithms except algorithm #4 (see below). If omitted, a value based on ##[[KeyPgTimer|Timer]]## will be used instead.
   13 	##//algorithm//##
   14 		An integer value to select the algorithm (see below, or from fbc version >= 1.08 the standard header "fbmath.bi" for available algorithms). If omitted, the default algorithm for the current [[CompilerDialects|language dialect]] is used.
   15 
   16 {{fbdoc item="desc"}}
   17 	Sets the random seed that helps ##[[KeyPgRnd|Rnd]]## generate random numbers, and selects the algorithm to use.
   18 	The constants for ##//algorithm//## are defined in ##fbmath.bi## (from fbc version 1.08). In the //[[CompilerOptlang|-lang fb]]// dialect, these constants are part of the ##FB## ##[[KeyPgNamespace|Namespace]]##.
   19 	Valid values for ##//algorithm//## are:
   20 		##FB_RND_AUTO (0)## - Default for current [[CompilerDialects|language dialect]]. This is algorithm ##FB_RND_MTWIST (3)## in the //[[CompilerOptlang|-lang fb]]// dialect, ##FB_RND_QB (4)## in the //[[CompilerOptlang|-lang qb]]// dialect and ##FB_RND_CRT (1)## in the //[[CompilerOptlang|-lang fblite]]// dialect.
   21 		##FB_RND_CRT (1)## - Uses the C runtime library's ##rand()## function. This will give different results depending on the platform.
   22 		##FB_RND_FAST (2)## - Uses a fast implementation. This should be stable across all platforms, and provides 32-bit granularity, reasonable degree of randomness.
   23 		##FB_RND_MTWIST (3)## - Uses the Mersenne Twister. This should be stable across all platforms, provides 32-bit granularity, and gives a high degree of randomness.
   24 		##FB_RND_QB (4)## - Uses a function that is designed to give the same random number sequences as QBASIC. This should be stable across all platforms, and provides 24-bit precision, with a low degree of randomness.
   25 		##FB_RND_REAL (5)## - Available on ""Win32"" and Linux, using system features (""Win32"" Crypto API, Linux /dev/urandom) to provide cryptographically random numbers. If those system APIs are unavailable, algorithm ##FB_RND_MTWIST (3)## will be used instead.
   26 		
   27 		For any given seed, each algorithm will produce a specific, deterministic sequence of numbers for that seed. If you want each call to ##**Randomize**## to produce a different sequence of numbers, a seed that is not quite predictable should be used - for example, the value returned from ##[[KeyPgTimer|Timer]]##. Omitting the ##//seed//## parameter will use a value based on this.
   28 		
   29 		Note: for all algorithms except algorithm #4, because the fractional part of the seed is clipped, the using the ##[[KeyPgTimer|Timer]]## value directly as a parameter will produce the same seed if used more than once in the same second. However, it is generally not worth calling ##**Randomize**## twice with unpredictable seeds anyway, because the second sequence will be no more random than the first, or even possibly worse by inducing sequence overlapping. In most cases, the Mersenne twister should provide a sufficiently random sequence of numbers, without requiring reseeding between ##[[KeyPgRnd|Rnd]]## calls.
   30 		
   31 		When you call ##**Randomize**## with the QB compatible algorithm, part of the old seed is retained. This means that if you call ##**Randomize**## several times with the same seed, you will **not** get the same sequence each time. To get a specific sequence in QB compatible mode, set the seed by calling ##[[KeyPgRnd|Rnd]]## with a negative parameter.
   32 		
   33 		**Note:**
   34 			**""-""** For fbc version >= 1.08, ##**Randomize**## is became thread-safe (by using an internal mutex), but not thread specific. Structures for other random number generators are also now available in the standard header "fbmath.bi".
   35 
   36 {{fbdoc item="ex"}}
   37 	{{fbdoc item="filename" value="examples/manual/math/randomize.bas"}}%%(freebasic)
   38 '' Seed the RNG to the method using C's rand()
   39 randomize , 1
   40 
   41 '' Print a sequence of random numbers
   42 for i as integer = 1 to 10
   43 	print rnd
   44 next
   45 	%%
   46 {{fbdoc item="lang"}}
   47 	The default algorithm used depends on the current dialect in use:
   48 		- With the //[[CompilerOptlang|-lang fb]]// dialect, a 32 bit Mersenne Twister function with a granularity of 32 bits is used.
   49 		- With the //[[CompilerOptlang|-lang qb]]// dialect, a function giving the same output as ##[[KeyPgRnd|Rnd]]## in QB is used. The granularity is 24 bits.
   50 		- With the //[[CompilerOptlang|-lang deprecated]]// and //[[CompilerOptlang|-lang fblite]]// dialects, the function in the C runtime available in the system is used. The function has a granularity of 15 bits in ""Win32"", and 32 bits in Linux and DOS.
   51 
   52 {{fbdoc item="diff"}}
   53 	- The ##//algorithm//## parameter is new to ""FreeBASIC"".
   54 	- QBASIC only had one algorithm (replicated in FB in algorithm number ##**4**##, and set as the default in the //[[CompilerOptlang|-lang qb]]// dialect).
   55 
   56 {{fbdoc item="see"}}
   57 	- ##[[KeyPgRnd|Rnd]]##
   58 	- [[CompilerDialects|Language dialects]]
   59 
   60 {{fbdoc item="back" value="CatPgMath|Mathematical Functions"}}