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-2013, 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------------------------------------------------------------------------------ 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 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. 39 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. 45 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. 53 54with Interfaces; 55 56package System.Random_Numbers is 57 58 type Generator is limited private; 59 -- Generator encodes the current state of a random number stream, it is 60 -- provided as input to produce the next random number, and updated so 61 -- that it is ready to produce the next one. 62 63 type State is private; 64 -- A non-limited version of a Generator's internal state 65 66 function Random (Gen : Generator) return Float; 67 function Random (Gen : Generator) return Long_Float; 68 -- Return pseudo-random numbers uniformly distributed on [0.0 .. 1.0) 69 70 function Random (Gen : Generator) return Interfaces.Unsigned_32; 71 function Random (Gen : Generator) return Interfaces.Unsigned_64; 72 -- Return pseudo-random numbers uniformly distributed on T'First .. T'Last 73 -- for builtin integer types. 74 75 generic 76 type Result_Subtype is (<>); 77 Default_Min : Result_Subtype := Result_Subtype'Val (0); 78 function Random_Discrete 79 (Gen : Generator; 80 Min : Result_Subtype := Default_Min; 81 Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype; 82 -- Returns pseudo-random numbers uniformly distributed on Min .. Max 83 84 generic 85 type Result_Subtype is digits <>; 86 function Random_Float (Gen : Generator) return Result_Subtype; 87 -- Returns pseudo-random numbers uniformly distributed on [0 .. 1) 88 89 type Initialization_Vector is 90 array (Integer range <>) of Interfaces.Unsigned_32; 91 -- Provides the most general initialization values for a generator (used 92 -- in Reset). In general, there is little point in providing more than 93 -- a certain number of values (currently 624). 94 95 procedure Reset (Gen : Generator); 96 -- Re-initialize the state of Gen from the time of day 97 98 procedure Reset (Gen : Generator; Initiator : Initialization_Vector); 99 procedure Reset (Gen : Generator; Initiator : Interfaces.Integer_32); 100 procedure Reset (Gen : Generator; Initiator : Interfaces.Unsigned_32); 101 procedure Reset (Gen : Generator; Initiator : Integer); 102 -- Re-initialize Gen based on the Initiator in various ways. Identical 103 -- values of Initiator cause identical sequences of values. 104 105 procedure Reset (Gen : Generator; From_State : Generator); 106 -- Causes the state of Gen to be identical to that of From_State; Gen 107 -- and From_State will produce identical sequences of values subsequently. 108 109 procedure Reset (Gen : Generator; From_State : State); 110 procedure Save (Gen : Generator; To_State : out State); 111 -- The sequence 112 -- Save (Gen2, S); Reset (Gen1, S) 113 -- has the same effect as Reset (Gen2, Gen1). 114 115 procedure Reset (Gen : Generator; From_Image : String); 116 function Image (Gen : Generator) return String; 117 -- The call 118 -- Reset (Gen2, Image (Gen1)) 119 -- has the same effect as Reset (Gen2, Gen1); 120 121 Max_Image_Width : constant := 11 * 624; 122 -- Maximum possible length of result of Image (...) 123 124 function Image (Of_State : State) return String; 125 -- A String representation of Of_State. Identical to the result of 126 -- Image (Gen), if Of_State has been set with Save (Gen, Of_State). 127 128 function Value (Coded_State : String) return State; 129 -- Inverse of Image on States 130 131private 132 133 N : constant := 624; 134 -- The number of 32-bit integers in the shift register 135 136 M : constant := 397; 137 -- Feedback distance from the current position 138 139 subtype State_Val is Interfaces.Unsigned_32; 140 type State is array (0 .. N - 1) of State_Val; 141 142 type Writable_Access (Self : access Generator) is limited null record; 143 -- Auxiliary type to make Generator a self-referential type 144 145 type Generator is limited record 146 Writable : Writable_Access (Generator'Access); 147 -- This self reference allows functions to modify Generator arguments 148 149 S : State := (others => 0); 150 -- The shift register, a circular buffer 151 152 I : Integer := N; 153 -- Current starting position in shift register S (N means uninitialized) 154 -- We should avoid using the identifier I here ??? 155 end record; 156 157end System.Random_Numbers; 158