| ------------------------------------------------------------------------------ |
| -- -- |
| -- GNAT RUN-TIME COMPONENTS -- |
| -- -- |
| -- G N A T . R A N D O M _ N U M B E R S -- |
| -- -- |
| -- S p e c -- |
| -- -- |
| -- Copyright (C) 2007-2022, Free Software Foundation, Inc. -- |
| -- -- |
| -- GNAT is free software; you can redistribute it and/or modify it under -- |
| -- terms of the GNU General Public License as published by the Free Soft- -- |
| -- ware Foundation; either version 3, or (at your option) any later ver- -- |
| -- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- |
| -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- |
| -- or FITNESS FOR A PARTICULAR PURPOSE. -- |
| -- -- |
| -- As a special exception under Section 7 of GPL version 3, you are granted -- |
| -- additional permissions described in the GCC Runtime Library Exception, -- |
| -- version 3.1, as published by the Free Software Foundation. -- |
| -- -- |
| -- You should have received a copy of the GNU General Public License and -- |
| -- a copy of the GCC Runtime Library Exception along with this program; -- |
| -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- |
| -- <http://www.gnu.org/licenses/>. -- |
| -- -- |
| -- GNAT was originally developed by the GNAT team at New York University. -- |
| -- Extensive contributions were provided by Ada Core Technologies Inc. -- |
| -- -- |
| ------------------------------------------------------------------------------ |
| |
| -- Extended pseudo-random number generation |
| |
| -- This package provides a type representing pseudo-random number generators, |
| -- and subprograms to extract various distributions of numbers from them. It |
| -- also provides types for representing initialization values and snapshots of |
| -- internal generator state, which permit reproducible pseudo-random streams. |
| |
| -- The generator currently provided by this package has an extremely long |
| -- period (at least 2**19937-1), and passes the Big Crush test suite, with the |
| -- exception of the two linear complexity tests. Therefore, it is suitable for |
| -- simulations, but should not be used as a cryptographic pseudo-random source |
| -- without additional processing. |
| |
| -- The design of this package effects is simplified compared to the design |
| -- of standard Ada.Numerics packages. There is no separate State type; the |
| -- Generator type itself suffices for this purpose. The parameter modes on |
| -- Reset procedures better reflect the effect of these routines. |
| |
| -- Note: this package is marked SPARK_Mode Off, because functions Random work |
| -- by side-effect to change the value of the generator, hence they should not |
| -- be called from SPARK code. |
| |
| with System.Random_Numbers; |
| with Interfaces; use Interfaces; |
| |
| package GNAT.Random_Numbers with |
| SPARK_Mode => Off |
| is |
| type Generator is limited private; |
| subtype Initialization_Vector is |
| System.Random_Numbers.Initialization_Vector; |
| |
| function Random (Gen : Generator) return Float; |
| function Random (Gen : Generator) return Long_Float; |
| -- Return pseudo-random numbers uniformly distributed on [0 .. 1) |
| |
| function Random (Gen : Generator) return Interfaces.Integer_32; |
| function Random (Gen : Generator) return Interfaces.Unsigned_32; |
| function Random (Gen : Generator) return Interfaces.Integer_64; |
| function Random (Gen : Generator) return Interfaces.Unsigned_64; |
| function Random (Gen : Generator) return Interfaces.Integer_128; |
| function Random (Gen : Generator) return Interfaces.Unsigned_128; |
| function Random (Gen : Generator) return Integer; |
| function Random (Gen : Generator) return Long_Integer; |
| -- Return pseudo-random numbers uniformly distributed on T'First .. T'Last |
| -- for various builtin integer types. |
| |
| generic |
| type Result_Subtype is (<>); |
| Default_Min : Result_Subtype := Result_Subtype'Val (0); |
| function Random_Discrete |
| (Gen : Generator; |
| Min : Result_Subtype := Default_Min; |
| Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype; |
| -- Returns pseudo-random numbers uniformly distributed on Min .. Max |
| |
| generic |
| type Result_Subtype is delta <>; |
| Default_Min : Result_Subtype := 0.0; |
| function Random_Ordinary_Fixed |
| (Gen : Generator; |
| Min : Result_Subtype := Default_Min; |
| Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype; |
| -- Returns pseudo-random numbers uniformly distributed on Min .. Max |
| |
| generic |
| type Result_Subtype is delta <> digits <>; |
| Default_Min : Result_Subtype := 0.0; |
| function Random_Decimal_Fixed |
| (Gen : Generator; |
| Min : Result_Subtype := Default_Min; |
| Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype; |
| -- Returns pseudo-random numbers uniformly distributed on Min .. Max |
| |
| generic |
| type Result_Subtype is digits <>; |
| function Random_Float (Gen : Generator) return Result_Subtype; |
| -- Returns pseudo-random numbers uniformly distributed on [0.0 .. 1.0) |
| |
| function Random_Gaussian (Gen : Generator) return Long_Float; |
| function Random_Gaussian (Gen : Generator) return Float; |
| -- Returns pseudo-random numbers normally distributed value with mean 0 |
| -- and standard deviation 1.0. |
| |
| procedure Reset (Gen : out Generator); |
| -- Re-initialize the state of Gen from the time of day |
| |
| procedure Reset |
| (Gen : out Generator; |
| Initiator : Initialization_Vector); |
| procedure Reset |
| (Gen : out Generator; |
| Initiator : Interfaces.Integer_32); |
| procedure Reset |
| (Gen : out Generator; |
| Initiator : Interfaces.Unsigned_32); |
| procedure Reset |
| (Gen : out Generator; |
| Initiator : Integer); |
| -- Re-initialize Gen based on the Initiator in various ways. Identical |
| -- values of Initiator cause identical sequences of values. |
| |
| procedure Reset (Gen : out Generator; From_State : Generator); |
| -- Causes the state of Gen to be identical to that of From_State; Gen |
| -- and From_State will produce identical sequences of values subsequently. |
| |
| procedure Reset (Gen : out Generator; From_Image : String); |
| function Image (Gen : Generator) return String; |
| -- The call |
| -- Reset (Gen2, Image (Gen1)) |
| -- has the same effect as Reset (Gen2, Gen1); |
| |
| Max_Image_Width : constant := |
| System.Random_Numbers.Max_Image_Width + 2 + 20 + 5; |
| -- Maximum possible length of result of Image (...) |
| |
| private |
| |
| type Generator is limited record |
| Rep : System.Random_Numbers.Generator; |
| |
| Have_Gaussian : Boolean; |
| -- The algorithm used for Random_Gaussian produces deviates in |
| -- pairs. Have_Gaussian is true iff Random_Gaussian has returned one |
| -- member of the pair and Next_Gaussian contains the other. |
| |
| Next_Gaussian : Long_Float; |
| -- Next random deviate to be produced by Random_Gaussian, if |
| -- Have_Gaussian. |
| end record; |
| |
| end GNAT.Random_Numbers; |