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-2010, 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 type State is private; 60 -- A non-limited version of a Generator's internal state 61 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) 65 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. 70 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 79 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) 84 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). 90 91 procedure Reset (Gen : Generator); 92 -- Re-initialize the state of Gen from the time of day 93 94 procedure Reset (Gen : Generator; Initiator : Initialization_Vector); 95 procedure Reset (Gen : Generator; Initiator : Interfaces.Integer_32); 96 procedure Reset (Gen : Generator; Initiator : Interfaces.Unsigned_32); 97 procedure Reset (Gen : Generator; Initiator : Integer); 98 -- Re-initialize Gen based on the Initiator in various ways. Identical 99 -- values of Initiator cause identical sequences of values. 100 101 procedure Reset (Gen : 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. 104 105 procedure Reset (Gen : 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). 110 111 procedure Reset (Gen : 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); 116 117 Max_Image_Width : constant := 11 * 624; 118 -- Maximum possible length of result of Image (...) 119 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). 123 124 function Value (Coded_State : String) return State; 125 -- Inverse of Image on States 126 127private 128 129 N : constant := 624; 130 -- The number of 32-bit integers in the shift register 131 132 M : constant := 397; 133 -- Feedback distance from the current position 134 135 subtype State_Val is Interfaces.Unsigned_32; 136 type State is array (0 .. N - 1) of State_Val; 137 138 type Writable_Access (Self : access Generator) is limited null record; 139 -- Auxiliary type to make Generator a self-referential type 140 141 type Generator is limited record 142 Writable : Writable_Access (Generator'Access); 143 -- This self reference allows functions to modify Generator arguments 144 145 S : State := (others => 0); 146 -- The shift register, a circular buffer 147 148 I : Integer := N; 149 -- Current starting position in shift register S (N means uninitialized) 150 -- We should avoid using the identifier I here ??? 151 end record; 152 153end System.Random_Numbers; 154