Fluent Random Picker

Fluent Random Picker is a user-friendly, but also performant .NET library that simplifies random value selection / picking. It allows you to specify probabilities and weights for each value, making it easy to handle complex randomization tasks.

Fluent Random Picker

Compatibility

Fluent Random Picker targets .Net Standard 2.0 and is therefore compatible with the following target frameworks:

✔️ .Net 5, 6, 7, 8
✔️ .Net Core 2.X, 3.X
✔️ .Net Standard 2.0, 2.1
✔️ .Net Framework 4.7.2, 4.8

Getting started

Install the nuget package (https://www.nuget.org/packages/FluentRandomPicker/)

Add the using directive:

using FluentRandomPicker;

To get started, use the Out.Of() syntax as shown in the examples below:

Examples

The easiest example

var randomNumber = Out.Of().Value(5).AndValue(6).PickOne();
// randomNumber is 5 or 6 with equal probability.

Specifying percentages

var randomChar = Out.Of()
                  .Value('a').WithPercentage(70)
                  .AndValue('b').WithPercentage(30)
                  .PickOne();
// randomChar is 'a' with a probability of 70 % and 'b' with a probability of 30 %.

Specifying weights

var randomString = Out.Of()
                  .Value("hello").WithWeight(2)
                  .AndValue("world").WithWeight(3)
                  .PickOne();
// randomString is "hello" or "world", but the probability for "world" is 1.5 times as high.

Specifying multiple values

var randomChar = Out.Of().Values(new List<char> { 'a', 'b' })
                  .WithPercentages(new List<int> { 70, 30 })
                  .PickOne();
// randomChar is 'a' with a probability of 70 % and 'b' with a probability of 30 %.

var randomChar = Out.Of().Values(new HashSet<string> { "hello", "world" })
                  .WithWeights(new List<int> { 2, 3 })
                  .PickOne();
// randomString is "hello" or "world", but the probability for "world" is 1.5 times as high.

Picking multiple values

var randomInts = Out.Of()
                  .Value(1).WithPercentage(70)
                  .AndValue(10).WithPercentage(15)
                  .AndValue(100).WithPercentage(10)
                  .AndValue(1000).WithPercentage(5)
                  .Pick(5);
// randomInts can be [1, 1, 1, 1, 1] with a higher probability or [1, 1, 100, 10, 1]
// or even [1000, 1000, 1000, 1000, 1000] with a very small probability.

Picking distinct values

var randomInts = Out.Of()
                  .Values(new List<int> { 1, 10, 100, 1000 })
                  .WithPercentages(70, 15, 10, 5)
                  .PickDistinct(2);
// randomInts can be [1, 10], [1, 100], ..., [1000, 100], but not [1, 1], [10, 10], ...

Using external types with weight/percentage information

class Item {
    public int Rarity { get; set; }
    public string Name { get; set; }
}

var items = new Item[]
{
    new Item { Name = "Stone", Rarity = 5 }, // common
    new Item { Name = "Silver helmet", Rarity = 2 }, // uncommon
    new Item { Name = "Gold sword", Rarity = 1 }, // rare
};

var itemName = Out.Of()
                  .PrioritizedElements(items)
                  .WithValueSelector(x => x.Name)
                  .AndWeightSelector(x => x.Rarity)
                  .PickOne();

// itemName is "Stone" in 5/8 of the cases, "Silver helmet" in 2/8 of the cases and "Gold sword" in 1/8 of the cases.
// If no value selector is specified, the whole item object will be returned instead of only its name.

Omitting percentages or weights

var randomChar = Out.Of()
                  .Value('a').WithPercentage(80)
                  .AndValue('b') // no percentage
                  .AndValue('c') // no percentage
                  .PickOne();
// The missing percentages to reach 100% are equally distributed on the values without specified percentages.
// Attention! The missing percentages to reach 100% must be divisible without remainder through the number of values without percentages.
// randomChar is 'a' with a probability of 80% or 'b' or 'c' with a probability of each 10%.

var randomString = Out.Of()
                  .Value("hello").WithWeight(4)
                  .AndValue("world") // no weight
                  .PickOne();
// The default weight is 1.
// randomString is "hello" with a probability of 80% (4 of 5) and "world" with a probability of 20% (1 of 5).

Specifying the returned type explicitly

var operation = Out.Of<Func<long, long>>()
                .Value(i => i + 2)
                .AndValue(i => i * 2)
                .AndValue(i => (long)Math.Pow(i, 2))
                .AndValue(i => (long)Math.Pow(i, i))
                .PickOne();

var result = operation(10);
// result equals 10 + 2 or 10 * 2 or 10^2 or 10^10.

Advanced

Please see README-Advanced.md for more advanced topics like:

Migration to version 3

The namespace was changed to match coding conventions. Please replace:

using Fluent_Random_Picker;

with

using FluentRandomPicker;

Some method parameter identifiers do also have changed to match the coding conventions of Microsoft.

ndsvw/Fluent-Random-Picker