Point out API usage of RandomCollection

Dieser Commit ist enthalten in:
Hannes Greule 2020-08-15 18:05:26 +02:00
Ursprung 6fb202443b
Commit da9d85e427
3 geänderte Dateien mit 28 neuen und 0 gelöschten Zeilen

Datei anzeigen

@ -17,11 +17,15 @@ public class FastRandomCollection<T> extends RandomCollection<T> {
/** /**
* Create a new FastRandomCollection if the given values and weights match the criteria. * Create a new FastRandomCollection if the given values and weights match the criteria.
* The criteria may change at any point, so this method isn't guaranteed to return a
* non-empty Optional in any case.
*
* @param weights the weight of the values. * @param weights the weight of the values.
* @param random the random generator to use for this collection. * @param random the random generator to use for this collection.
* @param <T> the value type. * @param <T> the value type.
* @return an {@link Optional} containing the new collection if it could * @return an {@link Optional} containing the new collection if it could
* be created, {@link Optional#empty()} otherwise. * be created, {@link Optional#empty()} otherwise.
* @see RandomCollection for API usage.
*/ */
public static <T> Optional<RandomCollection<T>> create(Map<T, Double> weights, SimpleRandom random) { public static <T> Optional<RandomCollection<T>> create(Map<T, Double> weights, SimpleRandom random) {
int max = 0; int max = 0;

Datei anzeigen

@ -6,6 +6,13 @@ import java.util.Map;
import static com.google.common.base.Preconditions.checkNotNull; import static com.google.common.base.Preconditions.checkNotNull;
/**
* A RandomCollection holds multiple values that can be accessed by using
* {@link RandomCollection#next(int, int, int)}. The returned value is
* determined by a given {@link SimpleRandom} implementation.
*
* @param <T> the type of values the collection holds.
*/
public abstract class RandomCollection<T> { public abstract class RandomCollection<T> {
private SimpleRandom random; private SimpleRandom random;
@ -13,6 +20,15 @@ public abstract class RandomCollection<T> {
this.random = random; this.random = random;
} }
/**
* Return a new RandomCollection. The implementation may differ depending on the
* given arguments but there is no need to differ.
*
* @param weights the weighted map.
* @param random the random number generator.
* @param <T> the type the collection holds.
* @return a RandomCollection using the given weights and the RNG.
*/
public static <T> RandomCollection<T> of(Map<T, Double> weights, SimpleRandom random) { public static <T> RandomCollection<T> of(Map<T, Double> weights, SimpleRandom random) {
checkNotNull(random); checkNotNull(random);
return FastRandomCollection.create(weights, random) return FastRandomCollection.create(weights, random)

Datei anzeigen

@ -11,6 +11,14 @@ public class SimpleRandomCollection<E> extends RandomCollection<E> {
private final NavigableMap<Double, E> map = new TreeMap<>(); private final NavigableMap<Double, E> map = new TreeMap<>();
private double total = 0; private double total = 0;
/**
* Create a {@link RandomCollection} from a weighted map and a RNG.
* It is recommended to use {@link RandomCollection#of(Map, SimpleRandom)}
* instead of this constructor.
*
* @param weights the weighted map.
* @param random the random number generator.
*/
public SimpleRandomCollection(Map<E, Double> weights, SimpleRandom random) { public SimpleRandomCollection(Map<E, Double> weights, SimpleRandom random) {
super(random); super(random);
for (Map.Entry<E, Double> entry : weights.entrySet()) { for (Map.Entry<E, Double> entry : weights.entrySet()) {