org.uncommons.maths.random

Class Probability

java.lang.Object

java.lang.Number

org.uncommons.maths.random.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 and 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.
static Probability	ZERO Convenient constant representing a probability of zero.

Constructor Summary

Constructors

Constructor and Description
Probability(double probability)

Method Summary

Modifier and Type	Method and 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

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

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).