source/modules/juce_core/maths/juce_Random.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    The code included in this file is provided under the terms of the ISC license
  11    http://www.isc.org/downloads/software-support-policy/isc-license. Permission
  12    To use, copy, modify, and/or distribute this software for any purpose with or
  13    without fee is hereby granted provided that the above copyright notice and
  14    this permission notice appear in all copies.
  15
  16    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  17    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  18    DISCLAIMED.
  19
  20   ==============================================================================
  21 */
  22
  23 namespace juce
  24 {
  25
  26 //==============================================================================
  27 /**
  28     A random number generator.
  29
  30     You can create a Random object and use it to generate a sequence of random numbers.
  31
  32     @tags{Core}
  33 */
  34 class JUCE_API  Random  final
  35 {
  36 public:
  37     //==============================================================================
  38     /** Creates a Random object based on a seed value.
  39
  40         For a given seed value, the subsequent numbers generated by this object
  41         will be predictable, so a good idea is to set this value based
  42         on the time, e.g.
  43
  44         new Random (Time::currentTimeMillis())
  45     */
  46     explicit Random (int64 seedValue) noexcept;
  47
  48     /** Creates a Random object using a random seed value.
  49         Internally, this calls setSeedRandomly() to randomise the seed.
  50     */
  51     Random();
  52
  53     /** Returns the next random 32 bit integer.
  54         @returns a random integer from the full range 0x80000000 to 0x7fffffff
  55     */
  56     int nextInt() noexcept;
  57
  58     /** Returns the next random number, limited to a given range.
  59         The maxValue parameter may not be negative, or zero.
  60         @returns a random integer between 0 (inclusive) and maxValue (exclusive).
  61     */
  62     int nextInt (int maxValue) noexcept;
  63
  64     /** Returns the next random number, limited to a given range.
  65         @returns a random integer between the range start (inclusive) and its end (exclusive).
  66     */
  67     int nextInt (Range<int> range) noexcept;
  68
  69     /** Returns the next 64-bit random number.
  70         @returns a random integer from the full range 0x8000000000000000 to 0x7fffffffffffffff
  71     */
  72     int64 nextInt64() noexcept;
  73
  74     /** Returns the next random floating-point number.
  75         @returns a random value in the range 0 (inclusive) to 1.0 (exclusive)
  76     */
  77     float nextFloat() noexcept;
  78
  79     /** Returns the next random floating-point number.
  80         @returns a random value in the range 0 (inclusive) to 1.0 (exclusive)
  81     */
  82     double nextDouble() noexcept;
  83
  84     /** Returns the next random boolean value. */
  85     bool nextBool() noexcept;
  86
  87     /** Returns a BigInteger containing a random number.
  88         @returns a random value in the range 0 to (maximumValue - 1).
  89     */
  90     BigInteger nextLargeNumber (const BigInteger& maximumValue);
  91
  92     /** Fills a block of memory with random values. */
  93     void fillBitsRandomly (void* bufferToFill, size_t sizeInBytes);
  94
  95     /** Sets a range of bits in a BigInteger to random values. */
  96     void fillBitsRandomly (BigInteger& arrayToChange, int startBit, int numBits);
  97
  98     //==============================================================================
  99     /** Resets this Random object to a given seed value. */
 100     void setSeed (int64 newSeed) noexcept;
 101
 102     /** Returns the RNG's current seed. */
 103     int64 getSeed() const noexcept                      { return seed; }
 104
 105     /** Merges this object's seed with another value.
 106         This sets the seed to be a value created by combining the current seed and this
 107         new value.
 108     */
 109     void combineSeed (int64 seedValue) noexcept;
 110
 111     /** Reseeds this generator using a value generated from various semi-random system
 112         properties like the current time, etc.
 113
 114         Because this function convolves the time with the last seed value, calling
 115         it repeatedly will increase the randomness of the final result.
 116     */
 117     void setSeedRandomly();
 118
 119     /** The overhead of creating a new Random object is fairly small, but if you want to avoid
 120         it, you can call this method to get a global shared Random object.
 121
 122         It's not thread-safe though, so threads should use their own Random object, otherwise
 123         you run the risk of your random numbers becoming.. erm.. randomly corrupted..
 124     */
 125     static Random& getSystemRandom() noexcept;
 126
 127 private:
 128     //==============================================================================
 129     int64 seed;
 130
 131     JUCE_LEAK_DETECTOR (Random)
 132 };
 133
 134 } // namespace juce