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
    EVENS
    Convenient constant representing a probability of 0.5 (used to model an event that has a 50/50 chance of occurring).
    static final Probability
    ONE
    Convenient constant representing a probability of one.
    private final double
    probability
     
    static final Probability
    ZERO
    Convenient constant representing a probability of zero.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Probability(double probability)
     

  • Method Summary

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

    Methods inherited from class Number

    byteValue, shortValue

    Methods inherited from class 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).