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-2019, 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 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 54with System.Random_Numbers; 55with Interfaces; use Interfaces; 56 57package GNAT.Random_Numbers with 58 SPARK_Mode => Off 59is 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 146private 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 161end GNAT.Random_Numbers; 162