org.uncommons.maths.random
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

Author:

Daniel Dyer

See Also:

Serialized Form

Field Summary

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

Probability(double probability)

Method Summary

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

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