File : g-rannum.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT RUN-TIME COMPONENTS --
4 -- --
5 -- G N A T . R A N D O M _ N U M B E R S --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2007-2015, Free Software Foundation, Inc. --
10 -- --
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. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
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/>. --
26 -- --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
29 -- --
30 ------------------------------------------------------------------------------
31
32 -- Extended pseudo-random number generation
33
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.
38
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.
44
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.
49
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.
53
54 with System.Random_Numbers;
55 with Interfaces; use Interfaces;
56
57 package GNAT.Random_Numbers with
58 SPARK_Mode => Off
59 is
60 type Generator is limited private;
61 subtype Initialization_Vector is
62 System.Random_Numbers.Initialization_Vector;
63
64 function Random (Gen : Generator) return Float;
65 function Random (Gen : Generator) return Long_Float;
66 -- Return pseudo-random numbers uniformly distributed on [0 .. 1)
67
68 function Random (Gen : Generator) return Interfaces.Integer_32;
69 function Random (Gen : Generator) return Interfaces.Unsigned_32;
70 function Random (Gen : Generator) return Interfaces.Integer_64;
71 function Random (Gen : Generator) return Interfaces.Unsigned_64;
72 function Random (Gen : Generator) return Integer;
73 function Random (Gen : Generator) return Long_Integer;
74 -- Return pseudo-random numbers uniformly distributed on T'First .. T'Last
75 -- for various builtin integer types.
76
77 generic
78 type Result_Subtype is (<>);
79 Default_Min : Result_Subtype := Result_Subtype'Val (0);
80 function Random_Discrete
81 (Gen : Generator;
82 Min : Result_Subtype := Default_Min;
83 Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype;
84 -- Returns pseudo-random numbers uniformly distributed on Min .. Max
85
86 generic
87 type Result_Subtype is delta <>;
88 Default_Min : Result_Subtype := 0.0;
89 function Random_Ordinary_Fixed
90 (Gen : Generator;
91 Min : Result_Subtype := Default_Min;
92 Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype;
93 -- Returns pseudo-random numbers uniformly distributed on Min .. Max
94
95 generic
96 type Result_Subtype is delta <> digits <>;
97 Default_Min : Result_Subtype := 0.0;
98 function Random_Decimal_Fixed
99 (Gen : Generator;
100 Min : Result_Subtype := Default_Min;
101 Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype;
102 -- Returns pseudo-random numbers uniformly distributed on Min .. Max
103
104 generic
105 type Result_Subtype is digits <>;
106 function Random_Float (Gen : Generator) return Result_Subtype;
107 -- Returns pseudo-random numbers uniformly distributed on [0.0 .. 1.0)
108
109 function Random_Gaussian (Gen : Generator) return Long_Float;
110 function Random_Gaussian (Gen : Generator) return Float;
111 -- Returns pseudo-random numbers normally distributed value with mean 0
112 -- and standard deviation 1.0.
113
114 procedure Reset (Gen : out Generator);
115 -- Re-initialize the state of Gen from the time of day
116
117 procedure Reset
118 (Gen : out Generator;
119 Initiator : Initialization_Vector);
120 procedure Reset
121 (Gen : out Generator;
122 Initiator : Interfaces.Integer_32);
123 procedure Reset
124 (Gen : out Generator;
125 Initiator : Interfaces.Unsigned_32);
126 procedure Reset
127 (Gen : out Generator;
128 Initiator : Integer);
129 -- Re-initialize Gen based on the Initiator in various ways. Identical
130 -- values of Initiator cause identical sequences of values.
131
132 procedure Reset (Gen : out Generator; From_State : Generator);
133 -- Causes the state of Gen to be identical to that of From_State; Gen
134 -- and From_State will produce identical sequences of values subsequently.
135
136 procedure Reset (Gen : out Generator; From_Image : String);
137 function Image (Gen : Generator) return String;
138 -- The call
139 -- Reset (Gen2, Image (Gen1))
140 -- has the same effect as Reset (Gen2, Gen1);
141
142 Max_Image_Width : constant :=
143 System.Random_Numbers.Max_Image_Width + 2 + 20 + 5;
144 -- Maximum possible length of result of Image (...)
145
146 private
147
148 type Generator is limited record
149 Rep : System.Random_Numbers.Generator;
150
151 Have_Gaussian : Boolean;
152 -- The algorithm used for Random_Gaussian produces deviates in
153 -- pairs. Have_Gaussian is true iff Random_Gaussian has returned one
154 -- member of the pair and Next_Gaussian contains the other.
155
156 Next_Gaussian : Long_Float;
157 -- Next random deviate to be produced by Random_Gaussian, if
158 -- Have_Gaussian.
159 end record;
160
161 end GNAT.Random_Numbers;