/// <summary>
/// Provides a random item from the collection where return chance is based
/// on their weights.
/// </summary>
/// <typeparam name="T">The type of items which are stored in the collection.
/// </typeparam>
/// <param name="collection">The collection where this item will be retrieved from.
/// </param>
/// <returns>A random item from the collection.</returns>
/// <exception cref="ArgumentNullException">If the given collection does not exist.
/// </exception>
public static T GetElement <T>(this IWeightedCollection <T> collection)
{
if (collection == null)
{
throw new ArgumentNullException(nameof(collection));
}
return(collection.GetElement(new Random()));
}
/// <summary>
/// Provides a new item to the collection with a weight of 1.
/// </summary>
/// <typeparam name="T">The type of items which are stored in the collection.
/// </typeparam>
/// <param name="collection">The collection where this item will be inserted in.
/// </param>
/// <param name="item">The collection item which can be retrieved with
/// the specified weight.</param>
/// <exception cref="ArgumentNullException">If the given collection does not exist.
/// </exception>
public static void Add <T>(this IWeightedCollection <T> collection, T item)
{
if (collection == null)
{
throw new ArgumentNullException(nameof(collection));
}
collection.Add(item, 1);
}
/// <summary>
/// Provides a new item to the collection with the specified weight.
/// </summary>
/// <typeparam name="T">The type of items which are stored in the collection.
/// </typeparam>
/// <param name="collection">The collection where this item will be inserted in.
/// </param>
/// <param name="item">The collection item which can be retrieved with
/// the specified weight.</param>
/// <param name="weight">The weight for which this item will be retrieved
/// from the collection.</param>
/// <exception cref="ArgumentNullException">If the given collection does not exist.
/// </exception>
/// <exception cref="ArgumentException">If the value of the weight is below 0.
/// Weights may only have positive values.</exception>
public static void Add <T>(this IWeightedCollection <T> collection, T item, double weight)
{
if (collection == null)
{
throw new ArgumentNullException(nameof(collection));
}
if (weight < 0)
{
throw new ArgumentException(
string.Format(Settings.Culture,
Resources.EX_ExpPosValue,
nameof(weight)
),
nameof(weight)
);
}
collection.Add(item, (uint)weight);
}
