# 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:
  - Serialized Form

## 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.
`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:
  - `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 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).