1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- G N A T . R A N D O M _ N U M B E R S --
9 -- Copyright (C) 2007-2015, Free Software Foundation, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
18 -- As a special exception under Section 7 of GPL version 3, you are granted --
19 -- additional permissions described in the GCC Runtime Library Exception, --
20 -- version 3.1, as published by the Free Software Foundation. --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
30 ------------------------------------------------------------------------------
32 -- Extended pseudo-random number generation
34 -- This package provides a type representing pseudo-random number generators,
35 -- and subprograms to extract various distributions of numbers from them. It
36 -- also provides types for representing initialization values and snapshots of
37 -- internal generator state, which permit reproducible pseudo-random streams.
39 -- The generator currently provided by this package has an extremely long
40 -- period (at least 2**19937-1), and passes the Big Crush test suite, with the
41 -- exception of the two linear complexity tests. Therefore, it is suitable for
42 -- simulations, but should not be used as a cryptographic pseudo-random source
43 -- without additional processing.
45 -- The design of this package effects is simplified compared to the design
46 -- of standard Ada.Numerics packages. There is no separate State type; the
47 -- Generator type itself suffices for this purpose. The parameter modes on
48 -- Reset procedures better reflect the effect of these routines.
50 -- Note: this package is marked SPARK_Mode Off, because functions Random work
51 -- by side-effect to change the value of the generator, hence they should not
52 -- be called from SPARK code.
54 with System
.Random_Numbers
;
55 with Interfaces
; use Interfaces
;
57 package GNAT
.Random_Numbers
with
61 type Generator
is limited private;
62 subtype Initialization_Vector
is
63 System
.Random_Numbers
.Initialization_Vector
;
65 function Random
(Gen
: Generator
) return Float;
66 function Random
(Gen
: Generator
) return Long_Float;
67 -- Return pseudo-random numbers uniformly distributed on [0 .. 1)
69 function Random
(Gen
: Generator
) return Interfaces
.Integer_32
;
70 function Random
(Gen
: Generator
) return Interfaces
.Unsigned_32
;
71 function Random
(Gen
: Generator
) return Interfaces
.Integer_64
;
72 function Random
(Gen
: Generator
) return Interfaces
.Unsigned_64
;
73 function Random
(Gen
: Generator
) return Integer;
74 function Random
(Gen
: Generator
) return Long_Integer;
75 -- Return pseudo-random numbers uniformly distributed on T'First .. T'Last
76 -- for various builtin integer types.
79 type Result_Subtype
is (<>);
80 Default_Min
: Result_Subtype
:= Result_Subtype
'Val (0);
81 function Random_Discrete
83 Min
: Result_Subtype
:= Default_Min
;
84 Max
: Result_Subtype
:= Result_Subtype
'Last) return Result_Subtype
;
85 -- Returns pseudo-random numbers uniformly distributed on Min .. Max
88 type Result_Subtype
is delta <>;
89 Default_Min
: Result_Subtype
:= 0.0;
90 function Random_Ordinary_Fixed
92 Min
: Result_Subtype
:= Default_Min
;
93 Max
: Result_Subtype
:= Result_Subtype
'Last) return Result_Subtype
;
94 -- Returns pseudo-random numbers uniformly distributed on Min .. Max
97 type Result_Subtype
is delta <> digits <>;
98 Default_Min
: Result_Subtype
:= 0.0;
99 function Random_Decimal_Fixed
101 Min
: Result_Subtype
:= Default_Min
;
102 Max
: Result_Subtype
:= Result_Subtype
'Last) return Result_Subtype
;
103 -- Returns pseudo-random numbers uniformly distributed on Min .. Max
106 type Result_Subtype
is digits <>;
107 function Random_Float
(Gen
: Generator
) return Result_Subtype
;
108 -- Returns pseudo-random numbers uniformly distributed on [0.0 .. 1.0)
110 function Random_Gaussian
(Gen
: Generator
) return Long_Float;
111 function Random_Gaussian
(Gen
: Generator
) return Float;
112 -- Returns pseudo-random numbers normally distributed value with mean 0
113 -- and standard deviation 1.0.
115 procedure Reset
(Gen
: out Generator
);
116 -- Re-initialize the state of Gen from the time of day
119 (Gen
: out Generator
;
120 Initiator
: Initialization_Vector
);
122 (Gen
: out Generator
;
123 Initiator
: Interfaces
.Integer_32
);
125 (Gen
: out Generator
;
126 Initiator
: Interfaces
.Unsigned_32
);
128 (Gen
: out Generator
;
129 Initiator
: Integer);
130 -- Re-initialize Gen based on the Initiator in various ways. Identical
131 -- values of Initiator cause identical sequences of values.
133 procedure Reset
(Gen
: out Generator
; From_State
: Generator
);
134 -- Causes the state of Gen to be identical to that of From_State; Gen
135 -- and From_State will produce identical sequences of values subsequently.
137 procedure Reset
(Gen
: out Generator
; From_Image
: String);
138 function Image
(Gen
: Generator
) return String;
140 -- Reset (Gen2, Image (Gen1))
141 -- has the same effect as Reset (Gen2, Gen1);
143 Max_Image_Width
: constant :=
144 System
.Random_Numbers
.Max_Image_Width
+ 2 + 20 + 5;
145 -- Maximum possible length of result of Image (...)
149 type Generator
is limited record
150 Rep
: System
.Random_Numbers
.Generator
;
152 Have_Gaussian
: Boolean;
153 -- The algorithm used for Random_Gaussian produces deviates in
154 -- pairs. Have_Gaussian is true iff Random_Gaussian has returned one
155 -- member of the pair and Next_Gaussian contains the other.
157 Next_Gaussian
: Long_Float;
158 -- Next random deviate to be produced by Random_Gaussian, if
162 end GNAT
.Random_Numbers
;