fixing pr42337
[official-gcc.git] / gcc / ada / s-rannum.ads
blob28dcdc692159027cd6c598d64cfb7dafd1888fa7
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT RUN-TIME COMPONENTS --
4 -- --
5 -- S Y S T E M . R A N D O M _ N U M B E R S --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2007,2009 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 -- 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. --
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 ------------------------------------------------------------------------------
32 -- Extended pseudo-random number generation
34 -- This package provides a type representing pseudo-random number generators,
35 -- and subprograms to extract various uniform distributions of numbers
36 -- from them. It also provides types for representing initialization values
37 -- and snapshots of internal generator state, which permit reproducible
38 -- pseudo-random streams.
40 -- The generator currently provided by this package has an extremely long
41 -- period (at least 2**19937-1), and passes the Big Crush test suite, with the
42 -- exception of the two linear complexity tests. Therefore, it is suitable
43 -- for simulations, but should not be used as a cryptographic pseudo-random
44 -- source without additional processing.
46 -- Note: this package is in the System hierarchy so that it can be directly
47 -- used by other predefined packages. User access to this package is via
48 -- the package GNAT.Random_Numbers (file g-rannum.ads), which also extends
49 -- its capabilities. The interfaces are different so as to include in
50 -- System.Random_Numbers only the definitions necessary to implement the
51 -- standard random-number packages Ada.Numerics.Float_Random and
52 -- Ada.Numerics.Discrete_Random.
54 with Interfaces;
56 package System.Random_Numbers is
58 type Generator is limited private;
59 type State is private;
60 -- A non-limited version of a Generator's internal state
62 function Random (Gen : Generator) return Float;
63 function Random (Gen : Generator) return Long_Float;
64 -- Return pseudo-random numbers uniformly distributed on [0 .. 1)
66 function Random (Gen : Generator) return Interfaces.Unsigned_32;
67 function Random (Gen : Generator) return Interfaces.Unsigned_64;
68 -- Return pseudo-random numbers uniformly distributed on T'First .. T'Last
69 -- for builtin integer types.
71 generic
72 type Result_Subtype is (<>);
73 Default_Min : Result_Subtype := Result_Subtype'Val (0);
74 function Random_Discrete
75 (Gen : Generator;
76 Min : Result_Subtype := Default_Min;
77 Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype;
78 -- Returns pseudo-random numbers uniformly distributed on Min .. Max
80 generic
81 type Result_Subtype is digits <>;
82 function Random_Float (Gen : Generator) return Result_Subtype;
83 -- Returns pseudo-random numbers uniformly distributed on [0 .. 1)
85 type Initialization_Vector is
86 array (Integer range <>) of Interfaces.Unsigned_32;
87 -- Provides the most general initialization values for a generator (used
88 -- in Reset). In general, there is little point in providing more than
89 -- a certain number of values (currently 624).
91 procedure Reset (Gen : out Generator);
92 -- Re-initialize the state of Gen from the time of day
94 procedure Reset (Gen : out Generator; Initiator : Initialization_Vector);
95 procedure Reset (Gen : out Generator; Initiator : Interfaces.Integer_32);
96 procedure Reset (Gen : out Generator; Initiator : Interfaces.Unsigned_32);
97 procedure Reset (Gen : out Generator; Initiator : Integer);
98 -- Re-initialize Gen based on the Initiator in various ways. Identical
99 -- values of Initiator cause identical sequences of values.
101 procedure Reset (Gen : out Generator; From_State : Generator);
102 -- Causes the state of Gen to be identical to that of From_State; Gen
103 -- and From_State will produce identical sequences of values subsequently.
105 procedure Reset (Gen : out Generator; From_State : State);
106 procedure Save (Gen : Generator; To_State : out State);
107 -- The sequence
108 -- Save (Gen2, S); Reset (Gen1, S)
109 -- has the same effect as Reset (Gen2, Gen1).
111 procedure Reset (Gen : out Generator; From_Image : String);
112 function Image (Gen : Generator) return String;
113 -- The call
114 -- Reset (Gen2, Image (Gen1))
115 -- has the same effect as Reset (Gen2, Gen1);
117 Max_Image_Width : constant := 11 * 624;
118 -- Maximum possible length of result of Image (...)
120 function Image (Of_State : State) return String;
121 -- A String representation of Of_State. Identical to the result of
122 -- Image (Gen), if Of_State has been set with Save (Gen, Of_State).
124 function Value (Coded_State : String) return State;
125 -- Inverse of Image on States
127 private
129 N : constant := 624;
130 -- The number of 32-bit integers in the shift register
132 M : constant := 397;
133 -- Feedback distance from the current position
135 subtype State_Val is Interfaces.Unsigned_32;
136 type State is array (0 .. N - 1) of State_Val;
138 type Generator is limited record
139 S : State := (others => 0);
140 -- The shift register, a circular buffer
142 I : Integer := N;
143 -- Current starting position in shift register S
144 end record;
146 end System.Random_Numbers;