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-2020, 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 Interfaces.Integer_128; 73 function Random (Gen : Generator) return Interfaces.Unsigned_128; 74 function Random (Gen : Generator) return Integer; 75 function Random (Gen : Generator) return Long_Integer; 76 -- Return pseudo-random numbers uniformly distributed on T'First .. T'Last 77 -- for various builtin integer types. 78 79 generic 80 type Result_Subtype is (<>); 81 Default_Min : Result_Subtype := Result_Subtype'Val (0); 82 function Random_Discrete 83 (Gen : Generator; 84 Min : Result_Subtype := Default_Min; 85 Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype; 86 -- Returns pseudo-random numbers uniformly distributed on Min .. Max 87 88 generic 89 type Result_Subtype is delta <>; 90 Default_Min : Result_Subtype := 0.0; 91 function Random_Ordinary_Fixed 92 (Gen : Generator; 93 Min : Result_Subtype := Default_Min; 94 Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype; 95 -- Returns pseudo-random numbers uniformly distributed on Min .. Max 96 97 generic 98 type Result_Subtype is delta <> digits <>; 99 Default_Min : Result_Subtype := 0.0; 100 function Random_Decimal_Fixed 101 (Gen : Generator; 102 Min : Result_Subtype := Default_Min; 103 Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype; 104 -- Returns pseudo-random numbers uniformly distributed on Min .. Max 105 106 generic 107 type Result_Subtype is digits <>; 108 function Random_Float (Gen : Generator) return Result_Subtype; 109 -- Returns pseudo-random numbers uniformly distributed on [0.0 .. 1.0) 110 111 function Random_Gaussian (Gen : Generator) return Long_Float; 112 function Random_Gaussian (Gen : Generator) return Float; 113 -- Returns pseudo-random numbers normally distributed value with mean 0 114 -- and standard deviation 1.0. 115 116 procedure Reset (Gen : out Generator); 117 -- Re-initialize the state of Gen from the time of day 118 119 procedure Reset 120 (Gen : out Generator; 121 Initiator : Initialization_Vector); 122 procedure Reset 123 (Gen : out Generator; 124 Initiator : Interfaces.Integer_32); 125 procedure Reset 126 (Gen : out Generator; 127 Initiator : Interfaces.Unsigned_32); 128 procedure Reset 129 (Gen : out Generator; 130 Initiator : Integer); 131 -- Re-initialize Gen based on the Initiator in various ways. Identical 132 -- values of Initiator cause identical sequences of values. 133 134 procedure Reset (Gen : out Generator; From_State : Generator); 135 -- Causes the state of Gen to be identical to that of From_State; Gen 136 -- and From_State will produce identical sequences of values subsequently. 137 138 procedure Reset (Gen : out Generator; From_Image : String); 139 function Image (Gen : Generator) return String; 140 -- The call 141 -- Reset (Gen2, Image (Gen1)) 142 -- has the same effect as Reset (Gen2, Gen1); 143 144 Max_Image_Width : constant := 145 System.Random_Numbers.Max_Image_Width + 2 + 20 + 5; 146 -- Maximum possible length of result of Image (...) 147 148private 149 150 type Generator is limited record 151 Rep : System.Random_Numbers.Generator; 152 153 Have_Gaussian : Boolean; 154 -- The algorithm used for Random_Gaussian produces deviates in 155 -- pairs. Have_Gaussian is true iff Random_Gaussian has returned one 156 -- member of the pair and Next_Gaussian contains the other. 157 158 Next_Gaussian : Long_Float; 159 -- Next random deviate to be produced by Random_Gaussian, if 160 -- Have_Gaussian. 161 end record; 162 163end GNAT.Random_Numbers; 164