Uncommons Maths API
(Version 1.2.3)

## 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 Probabilityextends Numberimplements 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
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).

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

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

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

Uncommons Maths API
(Version 1.2.3)