Detailed Description

Picks an element from a collection, where the probability of picking each element can be user-defined.

Elements are added to the collection by calling add(). For example, the following code snippet creates a collection of three strings, where "A" has twice the odds of being picked compared to "B" and "C":

RandomFloat r = new RandomFloat();
Choice<String> ep = new Choice<String>(r);
ep.add("A", 0.5).add("B", 0.25).add("C", 0.25);

When adding elements, one must make sure that the sum of probabilities is equal to 1.

Parameters

<T>	The type of the object to pick

Definition at line 44 of file Choice.java.

Inheritance diagram for ca.uqac.lif.synthia.util.Choice< T >:

[legend]

Classes
class	ProbabilityChoice
	Simple data structure asssociating an object with a probability.

Public Member Functions
	Choice (Picker< Float > picker)
	Creates a new element picker. More...

Choice< T >	add (ProbabilityChoice< T > pc)
	Adds an object-probability association. More...

Choice< T >	add (T t, Number p)
	Adds an object-probability association. More...

Choice< T >	add (Picker< T > t, Number p)
	Adds an object-probability association. More...

void	reset ()
	Puts the element picker back into its initial state. More...

T	pick ()
	Picks a random element. More...

Choice< T >	duplicate (boolean with_state)
	Creates a copy of the element picker. More...

int	getChoiceCount ()
	Gets the total number of alternatives available in this picker. More...

Shrinkable< T >	shrink (T o, Picker< Float > decision, float m)
	Shrinks a picker. More...

Shrinkable< T >	shrink (T o)
	Shrinks a picker with default parameters. More...

Protected Attributes
List< ProbabilityChoice< T > >	m_choices
	A list storing each element with its associated probability. More...

Picker< Float >	m_floatPicker
	A picker used to choose the element. More...

Constructor & Destructor Documentation

◆ Choice()

ca.uqac.lif.synthia.util.Choice< T >.Choice ( Picker< Float > picker )

Creates a new element picker.

Parameters

picker A picker used to choose the element

Definition at line 60 of file Choice.java.

Member Function Documentation

◆ add() [1/3]

Choice<T> ca.uqac.lif.synthia.util.Choice< T >.add	(	Picker< T >	t,
		Number	p
	)

Adds an object-probability association.

Parameters

t	The picker for an object
p	The probability, must be between 0 and 1

Returns: This element picker

Definition at line 96 of file Choice.java.

◆ add() [2/3]

Choice<T> ca.uqac.lif.synthia.util.Choice< T >.add ( ProbabilityChoice< T > pc )

Adds an object-probability association.

Parameters

pc	The association

Returns: This element picker

Definition at line 72 of file Choice.java.

◆ add() [3/3]

Choice<T> ca.uqac.lif.synthia.util.Choice< T >.add	(	T	t,
		Number	p
	)

Adds an object-probability association.

Parameters

t	The object
p	The probability, must be between 0 and 1

Returns: This element picker

Definition at line 84 of file Choice.java.

◆ duplicate()

Choice<T> ca.uqac.lif.synthia.util.Choice< T >.duplicate ( boolean with_state )

Creates a copy of the element picker.

Parameters

with_state If set to false, the returned copy is set to the class' initial state (i.e. same thing as calling the picker's constructor). If set to true, the returned copy is put into the same internal state as the object it is copied from.

Returns: The copy of the element picker

Implements ca.uqac.lif.synthia.Picker< T >.

Definition at line 163 of file Choice.java.

◆ getChoiceCount()

int ca.uqac.lif.synthia.util.Choice< T >.getChoiceCount ( )

Gets the total number of alternatives available in this picker.

Returns: The number of choices

Definition at line 255 of file Choice.java.

◆ pick()

T ca.uqac.lif.synthia.util.Choice< T >.pick ( )

Picks a random element.

Typically, this method is expected to return non-null objects; a null return value is used to signal that no more objects will be produced. That is, once this method returns null, it should normally return null on all subsequent calls.

Returns: The random element.

Implements ca.uqac.lif.synthia.Picker< T >.

Definition at line 128 of file Choice.java.

◆ reset()

void ca.uqac.lif.synthia.util.Choice< T >.reset ( )

Puts the element picker back into its initial state.

This means that the sequence of calls to pick() will produce the same values as when the object was instantiated.

Implements ca.uqac.lif.synthia.Picker< T >.

Definition at line 109 of file Choice.java.

◆ shrink() [1/2]

Shrinkable<T> ca.uqac.lif.synthia.util.Choice< T >.shrink ( T o )

Shrinks a picker with default parameters.

For any picker p that implements the Shrinkable interface, a call to p.shrink(o) should be the same as a call to p.shrink(o, RandomFloat.instance, 1).

Parameters

o	The reference object. The picker must guarantee that the returned picker instance only produces objects that are smaller than o, according to an implicit ordering relation that is specific to each object type and each picker.

Returns: The returned picker instance. This object may be of a different class from the object on which the method is called.

See also: #shrink(Object, Picker, float)

Implements ca.uqac.lif.synthia.Shrinkable< T >.

Definition at line 267 of file Choice.java.

◆ shrink() [2/2]

Shrinkable<T> ca.uqac.lif.synthia.util.Choice< T >.shrink	(	T	o,
		Picker< Float >	d,
		float	m
	)

Shrinks a picker.

The method adds two arguments with respect to shrink(Object): a source of randomness and a magnitude parameter. A picker may use the magnitude to determine how "aggressive" is the shrinking process. A value of 1 is expected to produce a picker with the broadest set, and may return all possible objects that are smaller than the reference. Lower values (all the way down to 0) instruct the picker to exclude further objects, and typically to only produce objects that are relatively "much smaller" than the reference.

Parameters

o	The reference object. The picker must guarantee that the returned picker instance only produces objects that are smaller than o, according to an implicit ordering relation that is specific to each object type and each picker.
d	A source of randomness. Some pickers must make choices when producing shrunk objects, and this parameter is used as an external source for these choices.
m	A magnitude parameter, which must be between 0 and 1.

Returns: The returned picker instance. This object may be of a different class from the object on which the method is called.

Implements ca.uqac.lif.synthia.Shrinkable< T >.

Definition at line 261 of file Choice.java.

Member Data Documentation

◆ m_choices

List<ProbabilityChoice<T> > ca.uqac.lif.synthia.util.Choice< T >.m_choices

protected

A list storing each element with its associated probability.

Definition at line 49 of file Choice.java.

◆ m_floatPicker

Picker<Float> ca.uqac.lif.synthia.util.Choice< T >.m_floatPicker

protected

A picker used to choose the element.

Definition at line 54 of file Choice.java.

The documentation for this class was generated from the following file:

Source/Core/src/ca/uqac/lif/synthia/util/Choice.java

Detailed Description

Classes

Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ Choice()

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ duplicate()

◆ getChoiceCount()

◆ pick()

◆ reset()

◆ shrink() [1/2]

◆ shrink() [2/2]

Member Data Documentation

◆ m_choices

◆ m_floatPicker