Class StdRandom


  • public final class StdRandom
    extends Object
    The StdRandom class provides static methods for generating random number from various discrete and continuous distributions, including uniform, Bernoulli, geometric, Gaussian, exponential, Pareto, Poisson, and Cauchy. It also provides method for shuffling an array or subarray and generating random permutations.

    Conventions. By convention, all intervals are half open. For example, uniformDouble(-1.0, 1.0) returns a random number between -1.0 (inclusive) and 1.0 (exclusive). Similarly, shuffle(a, lo, hi) shuffles the hi - lo elements in the array a[], starting at index lo (inclusive) and ending at index hi (exclusive).

    Performance. The methods all take constant expected time, except those that involve arrays. The shuffle method takes time linear in the subarray to be shuffled; the discrete methods take time linear in the length of the argument array.

    Additional information. For additional documentation, see Section 2.2 of Computer Science: An Interdisciplinary Approach by Robert Sedgewick and Kevin Wayne.

    Author:
    Robert Sedgewick, Kevin Wayne
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static boolean bernoulli()
      Returns a random boolean from a Bernoulli distribution with success probability 1/2.
      static boolean bernoulli​(double p)
      Returns a random boolean from a Bernoulli distribution with success probability p.
      static double cauchy()
      Returns a random real number from the Cauchy distribution.
      static int discrete​(double[] probabilities)
      Returns a random integer from the specified discrete distribution.
      static int discrete​(int[] frequencies)
      Returns a random integer from the specified discrete distribution.
      static double exponential​(double lambda)
      Returns a random real number from an exponential distribution with rate λ.
      static double gaussian()
      Returns a random real number from a standard Gaussian distribution.
      static double gaussian​(double mu, double sigma)
      Returns a random real number from a Gaussian distribution with mean μ and standard deviation σ.
      static int geometric​(double p)
      Returns a random integer from a geometric distribution with success probability p.
      static long getSeed()
      Returns the seed of the pseudo-random number generator.
      static void main​(String[] args)
      Unit tests the methods in this class.
      static double pareto()
      Returns a random real number from the standard Pareto distribution.
      static double pareto​(double alpha)
      Returns a random real number from a Pareto distribution with shape parameter α.
      static int[] permutation​(int n)
      Returns a uniformly random permutation of n elements.
      static int[] permutation​(int n, int k)
      Returns a uniformly random permutation of k of n elements.
      static int poisson​(double lambda)
      Returns a random integer from a Poisson distribution with mean λ.
      static void setSeed​(long s)
      Sets the seed of the pseudo-random number generator.
      static void shuffle​(char[] a)
      Rearranges the elements of the specified array in uniformly random order.
      static void shuffle​(double[] a)
      Rearranges the elements of the specified array in uniformly random order.
      static void shuffle​(double[] a, int lo, int hi)
      Rearranges the elements of the specified subarray in uniformly random order.
      static void shuffle​(int[] a)
      Rearranges the elements of the specified array in uniformly random order.
      static void shuffle​(int[] a, int lo, int hi)
      Rearranges the elements of the specified subarray in uniformly random order.
      static void shuffle​(Object[] a)
      Rearranges the elements of the specified array in uniformly random order.
      static void shuffle​(Object[] a, int lo, int hi)
      Rearranges the elements of the specified subarray in uniformly random order.
      static double uniformDouble()
      Returns a random real number uniformly in [0, 1).
      static double uniformDouble​(double a, double b)
      Returns a random real number uniformly in [a, b).
      static int uniformInt​(int n)
      Returns a random integer uniformly in [0, n).
      static int uniformInt​(int a, int b)
      Returns a random integer uniformly in [a, b).
      static long uniformLong​(long n)
      Returns a random long integer uniformly in [0, n).
    • Method Detail

      • setSeed

        public static void setSeed​(long s)
        Sets the seed of the pseudo-random number generator. This method enables you to produce the same sequence of "random" number for each execution of the program. Ordinarily, you should call this method at most once per program.
        Parameters:
        s - the seed
      • getSeed

        public static long getSeed()
        Returns the seed of the pseudo-random number generator.
        Returns:
        the seed
      • uniformDouble

        public static double uniformDouble()
        Returns a random real number uniformly in [0, 1).
        Returns:
        a random real number uniformly in [0, 1)
      • uniformInt

        public static int uniformInt​(int n)
        Returns a random integer uniformly in [0, n).
        Parameters:
        n - number of possible integers
        Returns:
        a random integer uniformly between 0 (inclusive) and n (exclusive)
        Throws:
        IllegalArgumentException - if n <= 0
      • uniformLong

        public static long uniformLong​(long n)
        Returns a random long integer uniformly in [0, n).
        Parameters:
        n - number of possible long integers
        Returns:
        a random long integer uniformly between 0 (inclusive) and n (exclusive)
        Throws:
        IllegalArgumentException - if n <= 0
      • uniformInt

        public static int uniformInt​(int a,
                                     int b)
        Returns a random integer uniformly in [a, b).
        Parameters:
        a - the left endpoint
        b - the right endpoint
        Returns:
        a random integer uniformly in [a, b)
        Throws:
        IllegalArgumentException - if b <= a
        IllegalArgumentException - if b - a >= Integer.MAX_VALUE
      • uniformDouble

        public static double uniformDouble​(double a,
                                           double b)
        Returns a random real number uniformly in [a, b).
        Parameters:
        a - the left endpoint
        b - the right endpoint
        Returns:
        a random real number uniformly in [a, b)
        Throws:
        IllegalArgumentException - unless a < b
      • bernoulli

        public static boolean bernoulli​(double p)
        Returns a random boolean from a Bernoulli distribution with success probability p.
        Parameters:
        p - the probability of returning true
        Returns:
        true with probability p and false with probability 1 - p
        Throws:
        IllegalArgumentException - unless 0p1.0
      • bernoulli

        public static boolean bernoulli()
        Returns a random boolean from a Bernoulli distribution with success probability 1/2.
        Returns:
        true with probability 1/2 and false with probability 1/2
      • gaussian

        public static double gaussian()
        Returns a random real number from a standard Gaussian distribution.
        Returns:
        a random real number from a standard Gaussian distribution (mean 0 and standard deviation 1).
      • gaussian

        public static double gaussian​(double mu,
                                      double sigma)
        Returns a random real number from a Gaussian distribution with mean μ and standard deviation σ.
        Parameters:
        mu - the mean
        sigma - the standard deviation
        Returns:
        a real number distributed according to the Gaussian distribution with mean mu and standard deviation sigma
      • geometric

        public static int geometric​(double p)
        Returns a random integer from a geometric distribution with success probability p. The integer represents the number of independent trials before the first success.
        Parameters:
        p - the parameter of the geometric distribution
        Returns:
        a random integer from a geometric distribution with success probability p; or Integer.MAX_VALUE if p is (nearly) equal to 1.0.
        Throws:
        IllegalArgumentException - unless p >= 0.0 and p <= 1.0
      • poisson

        public static int poisson​(double lambda)
        Returns a random integer from a Poisson distribution with mean λ.
        Parameters:
        lambda - the mean of the Poisson distribution
        Returns:
        a random integer from a Poisson distribution with mean lambda
        Throws:
        IllegalArgumentException - unless lambda > 0.0 and not infinite
      • pareto

        public static double pareto()
        Returns a random real number from the standard Pareto distribution.
        Returns:
        a random real number from the standard Pareto distribution
      • pareto

        public static double pareto​(double alpha)
        Returns a random real number from a Pareto distribution with shape parameter α.
        Parameters:
        alpha - shape parameter
        Returns:
        a random real number from a Pareto distribution with shape parameter alpha
        Throws:
        IllegalArgumentException - unless alpha > 0.0
      • cauchy

        public static double cauchy()
        Returns a random real number from the Cauchy distribution.
        Returns:
        a random real number from the Cauchy distribution.
      • discrete

        public static int discrete​(double[] probabilities)
        Returns a random integer from the specified discrete distribution.
        Parameters:
        probabilities - the probability of occurrence of each integer
        Returns:
        a random integer from a discrete distribution: i with probability probabilities[i]
        Throws:
        IllegalArgumentException - if probabilities is null
        IllegalArgumentException - if sum of array entries is not (very nearly) equal to 1.0
        IllegalArgumentException - unless probabilities[i] >= 0.0 for each index i
      • discrete

        public static int discrete​(int[] frequencies)
        Returns a random integer from the specified discrete distribution.
        Parameters:
        frequencies - the frequency of occurrence of each integer
        Returns:
        a random integer from a discrete distribution: i with probability proportional to frequencies[i]
        Throws:
        IllegalArgumentException - if frequencies is null
        IllegalArgumentException - if all array entries are 0
        IllegalArgumentException - if frequencies[i] is negative for any index i
        IllegalArgumentException - if sum of frequencies exceeds Integer.MAX_VALUE (231 - 1)
      • exponential

        public static double exponential​(double lambda)
        Returns a random real number from an exponential distribution with rate λ.
        Parameters:
        lambda - the rate of the exponential distribution
        Returns:
        a random real number from an exponential distribution with rate lambda
        Throws:
        IllegalArgumentException - unless lambda > 0.0
      • shuffle

        public static void shuffle​(Object[] a)
        Rearranges the elements of the specified array in uniformly random order.
        Parameters:
        a - the array to shuffle
        Throws:
        IllegalArgumentException - if a is null
      • shuffle

        public static void shuffle​(double[] a)
        Rearranges the elements of the specified array in uniformly random order.
        Parameters:
        a - the array to shuffle
        Throws:
        IllegalArgumentException - if a is null
      • shuffle

        public static void shuffle​(int[] a)
        Rearranges the elements of the specified array in uniformly random order.
        Parameters:
        a - the array to shuffle
        Throws:
        IllegalArgumentException - if a is null
      • shuffle

        public static void shuffle​(char[] a)
        Rearranges the elements of the specified array in uniformly random order.
        Parameters:
        a - the array to shuffle
        Throws:
        IllegalArgumentException - if a is null
      • shuffle

        public static void shuffle​(Object[] a,
                                   int lo,
                                   int hi)
        Rearranges the elements of the specified subarray in uniformly random order.
        Parameters:
        a - the array to shuffle
        lo - the left endpoint (inclusive)
        hi - the right endpoint (exclusive)
        Throws:
        IllegalArgumentException - if a is null
        IllegalArgumentException - unless (0 <= lo) && (lo < hi) && (hi <= a.length)
      • shuffle

        public static void shuffle​(double[] a,
                                   int lo,
                                   int hi)
        Rearranges the elements of the specified subarray in uniformly random order.
        Parameters:
        a - the array to shuffle
        lo - the left endpoint (inclusive)
        hi - the right endpoint (exclusive)
        Throws:
        IllegalArgumentException - if a is null
        IllegalArgumentException - unless (0 <= lo) && (lo < hi) && (hi <= a.length)
      • shuffle

        public static void shuffle​(int[] a,
                                   int lo,
                                   int hi)
        Rearranges the elements of the specified subarray in uniformly random order.
        Parameters:
        a - the array to shuffle
        lo - the left endpoint (inclusive)
        hi - the right endpoint (exclusive)
        Throws:
        IllegalArgumentException - if a is null
        IllegalArgumentException - unless (0 <= lo) && (lo < hi) && (hi <= a.length)
      • permutation

        public static int[] permutation​(int n)
        Returns a uniformly random permutation of n elements.
        Parameters:
        n - number of elements
        Returns:
        an array of length n that is a uniformly random permutation of 0, 1, ..., n-1
        Throws:
        IllegalArgumentException - if n is negative
      • permutation

        public static int[] permutation​(int n,
                                        int k)
        Returns a uniformly random permutation of k of n elements.
        Parameters:
        n - number of elements
        k - number of elements to select
        Returns:
        an array of length k that is a uniformly random permutation of k of the elements from 0, 1, ..., n-1
        Throws:
        IllegalArgumentException - if n is negative
        IllegalArgumentException - unless 0 <= k <= n
      • main

        public static void main​(String[] args)
        Unit tests the methods in this class.
        Parameters:
        args - the command-line arguments