Class Probability

java.lang.Object
java.lang.Number
org.uncommons.maths.random.Probability
All Implemented Interfaces:
Serializable, Comparable<Probability>

public final class Probability extends Number implements Comparable<Probability>
Immutable value type for probabilities. Forces numeric probabilities to be within the range 0..1 inclusive and provides useful utility methods for working with probabilities (such as generating an event with a given probability).
Since:
1.2
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Probability
    Convenient constant representing a probability of 0.5 (used to model an event that has a 50/50 chance of occurring).
    static final Probability
    Convenient constant representing a probability of one.
    private final double
     
    static final Probability
    Convenient constant representing a probability of zero.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Probability(double probability)
     
  • Method Summary

    Modifier and Type
    Method
    Description
    int
    Compares this value with the specified object for order.
    double
    Returns the probability value as a double.
    boolean
    equals(Object other)
    Determines whether this probability value is equal to some other object.
    float
    Returns the probability value as a float.
    The complement of a probability p is 1 - p.
    int
    Over-ridden to be consistent with equals(Object).
    int
    Converting a fractional probability into an integer is not meaningful since all useful information is discarded.
    long
    Converting a fractional probability into an integer is not meaningful since all useful information is discarded.
    boolean
    Generates an event according the probability value p.
    Formats the probability as a String.

    Methods inherited from class java.lang.Number

    byteValue, shortValue

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • ZERO

      public static final Probability ZERO
      Convenient constant representing a probability of zero. If an event has a probability of zero it will never happen (it is an impossibility).
      See Also:
    • EVENS

      public static final Probability EVENS
      Convenient constant representing a probability of 0.5 (used to model an event that has a 50/50 chance of occurring).
      See Also:
    • ONE

      public static final Probability ONE
      Convenient constant representing a probability of one. An event with a probability of one is a certainty.
      See Also:
    • probability

      private final double probability
  • Constructor Details

    • Probability

      public Probability(double probability)
      Parameters:
      probability - The probability value (a number in the range 0..1 inclusive). A value of zero means that an event is guaranteed not to happen. A value of 1 means it is guaranteed to occur.
  • Method Details

    • nextEvent

      public boolean nextEvent(Random rng)
      Generates an event according the probability value p.
      Parameters:
      rng - A source of randomness for generating events.
      Returns:
      True with a probability of p, false with a probability of 1 - p.
    • getComplement

      public Probability getComplement()
      The complement of a probability p is 1 - p. If p = 0.75, then the complement is 0.25.
      Returns:
      The complement of this probability.
    • intValue

      public int intValue()
      Converting a fractional probability into an integer is not meaningful since all useful information is discarded. For this reason, this method is over-ridden to thrown an ArithmeticException, except when the probability is exactly zero or one.
      Specified by:
      intValue in class Number
      Returns:
      An integer probability.
      Throws:
      ArithmeticException - Unless the probability is exactly zero or one.
    • longValue

      public long longValue()
      Converting a fractional probability into an integer is not meaningful since all useful information is discarded. For this reason, this method is over-ridden to thrown an ArithmeticException, except when the probability is exactly zero or one.
      Specified by:
      longValue in class Number
      Returns:
      An integer probability.
      Throws:
      ArithmeticException - Unless the probability is exactly zero or one.
    • floatValue

      public float floatValue()
      Returns the probability value as a float.
      Specified by:
      floatValue in class Number
      Returns:
      A real number between 0 and 1 inclusive.
    • doubleValue

      public double doubleValue()
      Returns the probability value as a double.
      Specified by:
      doubleValue in class Number
      Returns:
      A real number between 0 and 1 inclusive.
    • equals

      public boolean equals(Object other)
      Determines whether this probability value is equal to some other object. To be considered equal the other object must also be a Probability object with an indentical probability value.
      Overrides:
      equals in class Object
      Parameters:
      other - The object to compare against.
      Returns:
      True if the objects are equal, false otherwise.
    • hashCode

      public int hashCode()
      Over-ridden to be consistent with equals(Object).
      Overrides:
      hashCode in class Object
      Returns:
      The hash code value.
    • compareTo

      public int compareTo(Probability other)
      Compares this value with the specified object for order. Returns a negative integer, zero, or a positive integer as this value is less than, equal to, or greater than the specified value.
      Specified by:
      compareTo in interface Comparable<Probability>
      Parameters:
      other - Another Probability value.
      Returns:
      A negative integer, zero, or a positive integer as this value is less than, equal to, or greater than the specified value.
    • toString

      public String toString()
      Formats the probability as a String. This is simply the string representation of the double value encapsulated by this probability object.
      Overrides:
      toString in class Object
      Returns:
      A string representation of the probability value (a number between 0 and 1 inclusive).