Package org.uncommons.maths.random

Class Probability

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Probability>
    public final class Probability
extends java.lang.Number
implements java.lang.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:
    Serialized Form

    • Field Summary

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

    • Constructor Summary

      Constructors 
      Constructor Description
      Probability​(double probability)  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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​(java.lang.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​(java.util.Random rng)
      Generates an event according the probability value p.
      java.lang.String toString()
      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 Detail

      • 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:
        ONE, EVENS

      • 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:
        ZERO, ONE

      • 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:
        ZERO, EVENS

      • probability

        private final double probability

    • Constructor Detail

      • 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 Detail

      • nextEvent

        public boolean nextEvent​(java.util.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 java.lang.Number
        Returns:
        An integer probability.
        Throws:
        java.lang.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 java.lang.Number
        Returns:
        An integer probability.
        Throws:
        java.lang.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 java.lang.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 java.lang.Number
        Returns:
        A real number between 0 and 1 inclusive.

      • equals

        public boolean equals​(java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.Object
        Returns:
        A string representation of the probability value (a number between 0 and 1 inclusive).