EditRNG (squidlib-util 3.0.6 API)

java.lang.Object
- squidpony.squidmath.AbstractRNG
- - squidpony.squidmath.RNG
  - - squidpony.squidmath.StatefulRNG
    - - squidpony.squidmath.EditRNG

All Implemented Interfaces:

java.io.Serializable, IRNG, IStatefulRNG, RandomnessSource, StatefulRandomness
```
public class EditRNG
extends StatefulRNG
implements java.io.Serializable
```
A subclass of StatefulRNG (and thus RNG) that allows customizing many parts of the random number generation. This is meant to be a more comprehensible version of the functionality present in RandomBias, and also for it to be easier to use with methods that expect an RNG.
You can change the expected average for the values this produces, which uses the RandomBias.EXPONENTIAL distribution, with all the caveats it has: it strongly favors either high or low values when the average gets especially high or low, but it can essentially cover all averages between 0.0 and 1.0 (this class limits it to 0.1 and 0.9, so other techniques can be used effectively).
You can also affect the "centrality" of random numbers, causing more to occur near the expected average (a bell curve effect), or cause more near extreme ends of the random number spectrum. In practice, centrality changes are hard to notice, but may be useful to simulate certain effects. An example of centrality changes in existing games include the Nintendo title Advance Wars 2, where a brutish commander could increase the amount of damage his units dealt but also suffered unpredictability; attacks could deal even more or much less damage than normal without any way to build tactics around it. Square Enix's Final Fantasy XII also notably differentiated certain weapons (axes, hammers, and "hand-cannons") from other similar options by making them deal less predictable damage. In both cases the connotation is that more randomness is fitting for a brute-force approach to combat where pre-planned strategies are less emphasized. It should also be noted that increasing the frequency of extreme results makes small bonuses to defense or offense typically less useful, and small penalties less harmful. The opposite can be true for a carefully tuned game where the most common results are tightly clustered, and most target numbers are just slightly above the ordinary average. In tabletop games, 1d20 and 3d6 have the same average, but 1d20 is uniform, where 3d6 is clustered around 10 and 11, each the result of 1/8 of rolls on their own and 1/4 together. This makes the case where a +1 bonus to succeed changes the outcome on approximately 5% of 1d20 rolls, regardless of the required number to succeed if it is less than 20. However, a +1 bonus matters on a variable portion of 3d6 rolls; if you become able to succeed on a 10 or 11 where that was a failure before, the bonus applies approximately 12.5% of the time. Becoming able to succeed on an 18 where that was a failure before is essentially worthless, affecting less than 0.5% of rolls. This property of centralized results should be considered if game balance and/or the lethality of combat is important. One lengthy stretch of extreme results by enemies that work against the favor of a player character generally result in a dead player character, and RNGs that make extreme results more common may seem particularly cruel to players.
This generator sets a field, rawLatest, every time a random number is produced. This stores a pseudo-random double between 0.0 (inclusive) and 1.0 (exclusive) that is not subject to the bias an expected average introduces, and is close to uniformly distributed. You should expect rawLatest to be higher when higher numbers are returned from a method like nextInt(), and lower when lower numbers are returned. This can be useful for rare effects that should not be drastically more or less likely when slight changes are made to the expected average; if the expected average is 0.65, many more random doubles from nextDouble() will be between 0.95 and 1.0 (probably more than 10% of random numbers), but rawLatest will only be between 0.95 and 1.0 for close to 5% of all generations.
You can get and set the state this uses internally, and this is stored as a 64-bit long.
The choice of RandomnessSource doesn't really matter since this will always use a LightRNG internally. LightRNG is the current best StatefulRandomness implementation, with excellent performance characteristics and few flaws, and though its relatively low period may sometimes be a detriment, all StatefulRandomness implementations will have the same or lower period.
More customizations may be added in the future to the ones available currently.

See Also:

Serialized Form

Nested Class Summary
- Nested classes/interfaces inherited from class squidpony.squidmath.RNG
  RNG.CustomRandom

Field Summary

Fields
Modifier and Type Field and Description

double rawLatest
The latest generated double, between 0.0 and 1.0, before changes for centrality and expected average.
- Fields inherited from class squidpony.squidmath.RNG
  ran, random

Fields
Modifier and Type	Field and Description
`double`	`rawLatest` The latest generated double, between 0.0 and 1.0, before changes for centrality and expected average.

Constructor Summary

Constructors
Constructor and Description
`EditRNG()` Constructs an EditRNG with a pseudo-random seed from Math.random().
`EditRNG(java.lang.CharSequence seed)` Construct a new EditRNG with the given seed.
`EditRNG(long seed)` Construct a new EditRNG with the given seed.
`EditRNG(long seed, double expected)` Construct a new EditRNG with the given seed.
`EditRNG(long seed, double expected, double centrality)` Construct a new EditRNG with the given seed.
`EditRNG(RandomnessSource rs)` Construct a new EditRNG with the given seed.
`EditRNG(RandomnessSource rs, double expected)` Construct a new EditRNG with the given seed.
`EditRNG(RandomnessSource rs, double expected, double centrality)` Construct a new EditRNG with the given seed.
`EditRNG(java.lang.String seed, double expected)` Construct a new EditRNG with the given seed.
`EditRNG(java.lang.String seed, double expected, double centrality)` Construct a new EditRNG with the given seed.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`EditRNG`	`copy()` Creates a copy of this StatefulRNG; it will generate the same random numbers, given the same calls in order, as this StatefulRNG at the point copy() is called.
`boolean`	`equals(java.lang.Object o)`
`double`	`getCentrality()` Gets the current centrality measure of this EditRNG.
`double`	`getExpected()` Gets the current expected average for this EditRNG.
`RandomnessSource`	`getRandomness()`
`double`	`getRawLatest()` Gets the latest "un-biased" random double used to produce the most recent (potentially) biased random number generated for another method in this class, such as nextDouble(), between(), or getRandomElement().
`int`	`hashCode()`
`int`	`next(int bits)` Get up to 32 bits (inclusive) of random output; the int this produces will not require more than `bits` bits to represent.
`boolean`	`nextBoolean()` Get a random bit of state, interpreted as true or false with approximately equal likelihood.
`double`	`nextDouble()` Generate a random double, altered to try to match the expected average and centrality.
`double`	`nextDouble(double max)` This returns a random double between 0.0 (inclusive) and max (exclusive).
`float`	`nextFloat()` Gets a random float between 0.0f inclusive and 1.0f exclusive.
`int`	`nextInt()` Returns a random integer, which may be positive or negative.
`int`	`nextInt(int bound)` Returns a random integer below the given bound, or 0 if the bound is 0 or negative.
`int`	`nextIntHasty(int bound)` Returns a random non-negative integer below the given bound, or 0 if the bound is 0.
`long`	`nextLong()` Returns a random long, which may be positive or negative.
`long`	`nextLong(long bound)` Returns a random long below the given bound, or 0 if the bound is 0 or negative.
`void`	`setCentrality(double centrality)` Gets the current centrality measure of this EditRNG.
`void`	`setExpected(double expected)` Sets the expected average for random doubles this produces, which must always be between 0.1 and 0.9, and will be set to 0.5 if an invalid value is passed.
`void`	`setRandomness(RandomnessSource random)`
`java.io.Serializable`	`toSerializable()` Returns this EditRNG in a way that can be deserialized even if only `IRNG`'s methods can be called.
`java.lang.String`	`toString()`

Methods inherited from class squidpony.squidmath.StatefulRNG
getState, setState

Methods inherited from class squidpony.squidmath.AbstractRNG
between, between, between, getRandomElement, getRandomElement, nextFloat, nextSignedInt, nextSignedLong, swap

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface squidpony.squidmath.IRNG
between, between, between, getRandomElement, getRandomElement, getRandomElement, nextFloat, nextSignedInt, nextSignedLong, randomOrdering, randomOrdering, randomPortion, shuffle, shuffle, shuffle, shuffle, shuffleInPlace, shuffleInPlace

- Field Detail
  - rawLatest
```
public double rawLatest
```
    The latest generated double, between 0.0 and 1.0, before changes for centrality and expected average. Doubles are used to generate all random numbers this class produces, so be aware that calling getRandomElement() will change this just as much as nextDouble(), nextInt(), or between() will. Primarily useful to obtain uniformly-distributed random numbers that are related to the biased random numbers this returns as a main result, such as to find when the last number generated was in the bottom 5% (less than 0.05, which could represent some kind of critical failure or fumble) or top 10% (greater than or equal to 0.9, which could grant a critical success or luck-based reward of some kind).
- Constructor Detail
  - EditRNG
```
public EditRNG()
```
    Constructs an EditRNG with a pseudo-random seed from Math.random().
  - EditRNG
```
public EditRNG(long seed)
```
    Construct a new EditRNG with the given seed.
    
    Parameters:
    
    seed - used to seed the default RandomnessSource.
  - EditRNG
```
public EditRNG(java.lang.CharSequence seed)
```
    Construct a new EditRNG with the given seed.
    
    Parameters:
    
    seed - used to seed the default RandomnessSource.
  - EditRNG
```
public EditRNG(long seed,
               double expected)
```
    Construct a new EditRNG with the given seed.
    
    Parameters:
    
    seed - used to seed the default RandomnessSource.
    
    expected - the expected average for random doubles, which will be capped between 0.1 and 0.9
  - EditRNG
```
public EditRNG(java.lang.String seed,
               double expected)
```
    Construct a new EditRNG with the given seed.
    
    Parameters:
    
    seed - used to seed the default RandomnessSource.
    
    expected - the expected average for random doubles, which will be capped between 0.1 and 0.9
  - EditRNG
```
public EditRNG(long seed,
               double expected,
               double centrality)
```
    Construct a new EditRNG with the given seed.
    
    Parameters:
    
    seed - used to seed the default RandomnessSource.
    
    expected - the expected average for random doubles, which will be capped between 0.1 and 0.9
    
    centrality - if positive, makes results more likely to be near expected; if negative, the opposite. The absolute value of centrality affects how centered results will be, with 0 having no effect
  - EditRNG
```
public EditRNG(java.lang.String seed,
               double expected,
               double centrality)
```
    Construct a new EditRNG with the given seed.
    
    Parameters:
    
    seed - used to seed the default RandomnessSource.
    
    expected - the expected average for random doubles, which will be capped between 0.1 and 0.9
    
    centrality - if positive, makes results more likely to be near expected; if negative, the opposite. The absolute value of centrality affects how centered results will be, with 0 having no effect
  - EditRNG
```
public EditRNG(RandomnessSource rs)
```
    Construct a new EditRNG with the given seed.
    
    Parameters:
    
    rs - the implementation used to generate random bits.
  - EditRNG
```
public EditRNG(RandomnessSource rs,
               double expected)
```
    Construct a new EditRNG with the given seed.
    
    Parameters:
    
    rs - the implementation used to generate random bits.
    
    expected - the expected average for random doubles, which will be capped between 0.1 and 0.9
  - EditRNG
```
public EditRNG(RandomnessSource rs,
               double expected,
               double centrality)
```
    Construct a new EditRNG with the given seed.
    
    Parameters:
    
    rs - the implementation used to generate random bits.
    
    expected - the expected average for random doubles, which will be capped between 0.1 and 0.9
    
    centrality - if positive, makes results more likely to be near expected; if negative, the opposite. The absolute value of centrality affects how centered results will be, with 0 having no effect
- Method Detail
  - nextDouble
```
public double nextDouble()
```
    Generate a random double, altered to try to match the expected average and centrality.
    
    Specified by:
    
    nextDouble in interface IRNG
    
    Overrides:
    
    nextDouble in class RNG
    
    Returns:
    
    a double between 0.0 (inclusive) and 1.0 (exclusive)
  - nextDouble
```
public double nextDouble(double max)
```
    This returns a random double between 0.0 (inclusive) and max (exclusive).
    
    Specified by:
    
    nextDouble in interface IRNG
    
    Overrides:
    
    nextDouble in class AbstractRNG
    
    Parameters:
    
    max - the outer exclusive bound as a double; can be negative or positive
    
    Returns:
    
    a value between 0 (inclusive) and max (exclusive)
  - nextInt
```
public int nextInt(int bound)
```
    Returns a random integer below the given bound, or 0 if the bound is 0 or negative.
    
    Specified by:
    
    nextInt in interface IRNG
    
    Overrides:
    
    nextInt in class AbstractRNG
    
    Parameters:
    
    bound - the upper bound (exclusive)
    
    Returns:
    
    the found number
  - nextInt
```
public int nextInt()
```
    Returns a random integer, which may be positive or negative.
    
    Specified by:
    
    nextInt in interface IRNG
    
    Overrides:
    
    nextInt in class RNG
    
    Returns:
    
    A random int
  - nextLong
```
public long nextLong()
```
    Returns a random long, which may be positive or negative.
    
    Specified by:
    
    nextLong in interface IRNG
    
    Specified by:
    
    nextLong in interface RandomnessSource
    
    Overrides:
    
    nextLong in class RNG
    
    Returns:
    
    A random long
  - nextLong
```
public long nextLong(long bound)
```
    Returns a random long below the given bound, or 0 if the bound is 0 or negative.
    
    Specified by:
    
    nextLong in interface IRNG
    
    Overrides:
    
    nextLong in class AbstractRNG
    
    Parameters:
    
    bound - the upper bound (exclusive)
    
    Returns:
    
    the found number
  - getExpected
```
public double getExpected()
```
    Gets the current expected average for this EditRNG.
    
    Returns:
    
    the current expected average.
  - setExpected
```
public void setExpected(double expected)
```
    Sets the expected average for random doubles this produces, which must always be between 0.1 and 0.9, and will be set to 0.5 if an invalid value is passed.
    
    Parameters:
    
    expected - the expected average to use, which should be 0.1 <= fairness < 0.9
  - getCentrality
```
public double getCentrality()
```
    Gets the current centrality measure of this EditRNG. Centrality has several possible effects: When positive, makes the generator more likely to generate values close to the average (bell curve). When zero (the default), makes no changes to the centering of values. When negative, makes the generator swing more toward extremes rather than gravitate toward the average.
    Values are typically between -100 and 100, but can have extreme weight and overshadow other parts of the RNG if they go much higher than 200.
    
    Returns:
    
    the current centrality
  - setCentrality
```
public void setCentrality(double centrality)
```
    Gets the current centrality measure of this EditRNG. Centrality has several possible effects: When positive, makes the generator more likely to generate values close to the average (bell curve). When zero (the default), makes no changes to the centering of values. When negative, makes the generator swing more toward extremes rather than gravitate toward the average.
    Values are typically between -100 and 100, but can have extreme weight and overshadow other parts of the RNG if they go much higher than 200.
    
    Parameters:
    
    centrality - the new centrality measure to use
  - next
```
public int next(int bits)
```
    Description copied from class: RNG
    
    Get up to 32 bits (inclusive) of random output; the int this produces will not require more than bits bits to represent.
    
    Specified by:
    
    next in interface IRNG
    
    Specified by:
    
    next in interface RandomnessSource
    
    Overrides:
    
    next in class RNG
    
    Parameters:
    
    bits - the number of bits to be returned
    
    Returns:
    
    a random int of the number of bits specified.
  - nextFloat
```
public float nextFloat()
```
    Description copied from class: RNG
    
    Gets a random float between 0.0f inclusive and 1.0f exclusive. This returns a maximum of 0.99999994 because that is the largest float value that is less than 1.0f .
    
    Specified by:
    
    nextFloat in interface IRNG
    
    Overrides:
    
    nextFloat in class RNG
    
    Returns:
    
    a float between 0f (inclusive) and 0.99999994f (inclusive)
  - nextBoolean
```
public boolean nextBoolean()
```
    Description copied from class: RNG
    
    Get a random bit of state, interpreted as true or false with approximately equal likelihood. This may have better behavior than rng.next(1), depending on the RandomnessSource implementation; the default DiverRNG will behave fine, as will LightRNG and ThrustAltRNG (these all use similar algorithms), but the normally-high-quality XoRoRNG will produce very predictable output with rng.next(1) and very good output with rng.nextBoolean(). This is a known and considered flaw of Xoroshiro128+, the algorithm used by XoRoRNG, and a large number of generators have lower quality on the least-significant bit than the most- significant bit, where this method only checks the most-significant bit.
    
    Specified by:
    
    nextBoolean in interface IRNG
    
    Overrides:
    
    nextBoolean in class RNG
    
    Returns:
    
    a random boolean.
  - getRandomness
```
public RandomnessSource getRandomness()
```
    Overrides:
    
    getRandomness in class RNG
  - setRandomness
```
public void setRandomness(RandomnessSource random)
```
    Overrides:
    
    setRandomness in class StatefulRNG
  - getRawLatest
```
public double getRawLatest()
```
    Gets the latest "un-biased" random double used to produce the most recent (potentially) biased random number generated for another method in this class, such as nextDouble(), between(), or getRandomElement(). This is a double between 0.0 (inclusive) and 1.0 (exclusive).
    
    Returns:
    
    the latest uniformly-distributed double before bias is added; between 0.0 and 1.0 (exclusive upper)
  - copy
```
public EditRNG copy()
```
    Creates a copy of this StatefulRNG; it will generate the same random numbers, given the same calls in order, as this StatefulRNG at the point copy() is called. The copy will not share references with this StatefulRNG.
    
    Specified by:
    
    copy in interface RandomnessSource
    
    Specified by:
    
    copy in interface StatefulRandomness
    
    Overrides:
    
    copy in class StatefulRNG
    
    Returns:
    
    a copy of this StatefulRNG
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class StatefulRNG
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class RNG
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class RNG
  - nextIntHasty
```
public int nextIntHasty(int bound)
```
    Returns a random non-negative integer below the given bound, or 0 if the bound is 0. Uses a slightly optimized technique. This method is considered "hasty" since it should be faster than nextInt() doesn't check for "less-valid" bounds values. It also has undefined behavior if bound is negative, though it will probably produce a negative number (just how negative is an open question).
    
    Overrides:
    
    nextIntHasty in class RNG
    
    Parameters:
    
    bound - the upper bound (exclusive); behavior is undefined if bound is negative
    
    Returns:
    
    the found number
  - toSerializable
```
public java.io.Serializable toSerializable()
```
    Returns this EditRNG in a way that can be deserialized even if only IRNG's methods can be called.
    
    Specified by:
    
    toSerializable in interface IRNG
    
    Overrides:
    
    toSerializable in class StatefulRNG
    
    Returns:
    
    a Serializable view of this EditRNG; always this

Class EditRNG

Nested Class Summary

Nested classes/interfaces inherited from class squidpony.squidmath.RNG

Field Summary

Fields inherited from class squidpony.squidmath.RNG

Constructor Summary

Method Summary

Methods inherited from class squidpony.squidmath.StatefulRNG

Methods inherited from class squidpony.squidmath.RNG

Methods inherited from class squidpony.squidmath.AbstractRNG

Methods inherited from class java.lang.Object

Methods inherited from interface squidpony.squidmath.IRNG

Field Detail

rawLatest

Constructor Detail

EditRNG

EditRNG

EditRNG

EditRNG

EditRNG

EditRNG

EditRNG

EditRNG

EditRNG

EditRNG

Method Detail

nextDouble

nextDouble

nextInt

nextInt

nextLong

nextLong

getExpected

setExpected

getCentrality

setCentrality

next

nextFloat

nextBoolean

getRandomness

setRandomness

getRawLatest

copy

toString

equals

hashCode

nextIntHasty

toSerializable