FluentRandomPicker 3.5.1

dotnet add package FluentRandomPicker --version 3.5.1
NuGet\Install-Package FluentRandomPicker -Version 3.5.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="FluentRandomPicker" Version="3.5.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add FluentRandomPicker --version 3.5.1
#r "nuget: FluentRandomPicker, 3.5.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install FluentRandomPicker as a Cake Addin
#addin nuget:?package=FluentRandomPicker&version=3.5.1

// Install FluentRandomPicker as a Cake Tool
#tool nuget:?package=FluentRandomPicker&version=3.5.1

Fluent Random Picker

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.

License MIT Build status Quality Gate Status Code coverage Nuget version Release notes NuGet downloads

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.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.5.1 2,073 3/16/2024
3.5.0 11,737 11/11/2023
3.4.0 7,332 12/19/2022
3.3.0 764 7/2/2022
3.2.0 483 4/28/2022
3.1.0 4,239 11/27/2021
3.0.2 284 11/13/2021
3.0.1 332 8/7/2021
3.0.0 356 7/28/2021
2.1.0 448 7/10/2021
2.0.1 323 6/28/2021
2.0.0 421 6/26/2021
1.2.0 425 5/22/2021
1.1.1 303 5/15/2021
1.1.0 330 4/24/2021
1.0.4 305 4/17/2021
1.0.3 299 4/16/2021
1.0.2 334 4/15/2021
1.0.1 290 4/15/2021
1.0.0 305 4/15/2021

- v 3.5.1
   - Fixed case when Pick(n) did not work correctly & returned the same element repeatedly. Thanks, https://github.com/SapiensAnatis (#62)
- v 3.5.0
   - Added .Net8 as compatibility to README file.
   - Improved structure of README
   - Fixed exception when calling Pick(n) when there were less than n values. (#48)
- v 3.4.0
   - Added .Net7 as compatibility to README file.
   - Fixed rare cases where weights/percentages did not matter (#15)
   - Fixed rare, but possible OverflowException (#16)
   - Improved performance
- v 3.3.0
   - Added 'PrioritizedElements' (a way to pick from an arbitrary collection via selectors).
- v 3.2.0
   - Cleaned up targets (.Net standard) supports various targets.
   - Improved implementation for when picking multiple distinct values.
- v 3.1.0
   - Implemented class SecureRandomNumberGenerator (secure implementation of IRandomNumberGenerator).
- v 3.0.2
   - Added .Net6 as compatibility to README file.
- v 3.0.1
   - Prevented arithmetic overflows when percentage sums / weights sums are too high.
- v 3.0.0
   - Changed namespace from Fluent_Random_Picker to FluentRandomPicker
   - Allowed omitting percentages and weights. E.g. Out.Of().Value('a').WithWeight(2).AndValue('b').PickOne();
   - Fixed bug: The shuffle algorithm was not working correctly.
   - Improved documentation
   - Renamed multiple interfaces, method parameters, ...
- v 2.1.0
   - Improved package generation process, used SourceLink, fixed version differences of dll, package, ...