aliostad / randomgen

A simple random generation framework for .NET Core and 4.52+

RandomGen

A simple random generation tool. Can create random integer, double, boolean, date, male and femals names, words, surnames and more. Also can create random values based on Normal Distribution. Can pick random items from your list - optionally from a list of items you supplied.

Getting Started

Install the library using Nuget:

PM> Install-Package RandomGen

Use Gen.Random.xxx fluent methods to get a delegate that creates random values every time you call it. RandomGen follows System.Random convention of excluding max value from results, ie. Gen.Random.Numbers.Integers(min: 1, max: 5) will return values { 1, 2, 3, 4 }.

Simple types

// integers
var ints = Gen.Random.Numbers.Integers();
Console.WriteLine(ints()); // between 0 and 100

var ints2 = Gen.Random.Numbers.Integers(10, 15);
Console.WriteLine(ints2()); // between 10 and 15

var uints = Gen.Random.Numbers.UnsignedIntegers();
Console.WriteLine(uints()); // between 0 and 100

// doubles
var doubles = Gen.Random.Numbers.Doubles(10D, 15D);
Console.WriteLine(doubles()); // between 10D and 15D

// booleans
var booleans = Gen.Random.Numbers.Booleans();
Console.WriteLine(booleans()); // true or false

// dates - DateTime and DateTimeOffset
var dates = Gen.Random.Time.Dates(DateTime.Now.AddYears(-1), DateTime.Now);
Console.WriteLine(date());

// Normal Distribution
var normals = Gen.Random.Numbers.Doubles().WithNormalDistribution(mean: 23.4, standardDeviation: 5.9);
Console.WriteLine(normals());

Names and words

// male names
var maleNames = Gen.Random.Names.Male();
Console.WriteLine(maleNames());

// female names
var femaleNames = Gen.Random.Names.Female();
Console.WriteLine(femaleNames());

// random mix of male and female names
var firstNames = Gen.Random.Names.First();
Console.WriteLine(firstNames());

// last names
var surnames = Gen.Random.Names.Surname();
Console.WriteLine(surnames());

// full names: '<first name> <last name>'
var fullnames = Gen.Random.Names.Full();
Console.WriteLine(fullnames());

// words
var words = Gen.Random.Text.Words();
Console.WriteLine(words());

// texts
var texts = Gen.Random.Text.Length(100); // .Short(), .Long(), .VeryLong()
Console.WriteLine(texts());

// naughty strings - useful for security testing
var texts = Gen.Random.Text.Naughty();
Console.WriteLine(texts());

// countries
var countries = Gen.Random.Countries();
Console.WriteLine(countries());

// top level domains
var domains = Gen.Random.Internet.TopLevelDomains();
Console.WriteLine(domains());

// email addresses
var addresses = Gen.Random.Internet.EmailAddresses();
Console.WriteLine(addresses());

// urls
var urls = Gen.Random.Internet.Urls();
Console.WriteLine(urls());

// phone numbers using an input mask
var mobileNumbers = Gen.Random.PhoneNumbers.FromMask("+44 (0) 1xxx xxxxxx");
Console.WriteLine(mobileNumbers());

// phone numbers using a pre-defined format
var customFormats = Gen.Random.PhoneNumbers.WithFormat(NumberFormat.UKMobile);
Console.WriteLine(customFormats());

// phone numbers using a randomly selected pre-defined format
var randomFormats = Gen.Random.PhoneNumbers.WithRandomFormat();
Console.WriteLine(randomFormats());

Your custom objects

// items with equal likelihood
var items = Gen.Random.Items("A", "B", "C");
Console.WriteLine(items()); 

// items with the likelihoods supplied
var items = Gen.Random.Items(new [] {"A", "B", "C"}, new [] {0.5, 6, 1.3});
Console.WriteLine(items()); 

// enums with equal likelihood - enum EnumType { A, B, C }
var items = Gen.Random.Enum<EnumType>();
Console.WriteLine(items()); 

// enums with the likelihoods supplied
var items = Gen.Random.Enum<EnumType>(new [] {0.5, 6, 1.3});
Console.WriteLine(items()); 

Change dates or numbers

Use Gen.Change.xxx fluent methods to get a new random value based on a value provided. Useful when you need to randomize data set but want to keep the same order of magnitude.

// dates
var date = DateTime.Now;
var newDate = Gen.Change(date).By(10).Days(); //.Minutes(), .Hours(), .Months()
Console.WriteLine(newDate); 

var date = DateTimeOffset.Now;
var newDate = Gen.Change(date).By(TimeSpan.FromSeconds(10));
Console.WriteLine(newDate); 

// numbers: ints, longs, doubles, decimals
var amount = 42;
var newAmount = Gen.Change(amount).By(10).Percent(); //.Amount()
Console.WriteLine(newAmount); 

Providing seed value

You can provide own seed value for random generator by calling WithSeed(int seed) method. This can be useful when you need to randomize data set in a predictable way, for example during testing.

var seed = 12345;
var number1 = Gen.WithSeed(seed).Random.Numbers.Integers()();
var number2 = Gen.WithSeed(seed).Random.Numbers.Integers()();
Console.WriteLine("{0} = {1}", number1, number2); 

randomgen's Issues

Invalid e-mail addresses being generated

Hi

I get domain names with arabic or hindu characters or something.

I use these email addresses to create fake users with a third party system, which appaently checks email addresses for vailidity.

Could you add some sanity checking to e-mails? I'm not talking about checking that domain names exist or anything like that, but at least generate valid characters.

Every number generator throws exception for equal arguments

Each of the following examples throws the exception:
Specified argument was out of the range of valid values.
Parameter name: min >= max

var @int = RandomGen.Gen.Random.Numbers.Integers(1, 1)(); var @decimal = RandomGen.Gen.Random.Numbers.Decimals(1, 1)(); var @double = RandomGen.Gen.Random.Numbers.Doubles(1, 1)(); var @long = RandomGen.Gen.Random.Numbers.Longs(1, 1)(); var @uint = RandomGen.Gen.Random.Numbers.UnsignedIntegers(1, 1)();

Adding support for System.Numerics.BigInteger

The System.Numerics.BigInteger class is used to generate arbitrarily large integers.

Extending the text generator to just generate numbers but return a string would add this quite easily. Using BigInteger.Parse(string)

Build is failing

The build on appveyor is failing
https://ci.appveyor.com/project

Remove offensive name

We use this library to generate random names in the demo environment of our product. A customer was recently offended by the name "Rivka Shyrock", because of Rivka being a Jewish first name, and Shyrock being very close to Shylock, which is a character in Shakespeare that is offensive to Jews.
I suggest replacing "Shyrock" with some other last name.
I understand it's hard to foresee possible combinations of names that could be considered offensive in various cultures. We have worked around this in our code, but want to make you aware of the potential issue.

Use the public key to sign the assembly of this project

Sign the assembly before posting to NuGet, please.
With * .snk.

Fluent API

I'm considering implementing a fluent API,

Right now we have a collection of RandomXXX() methods and they are not grouped in any way. As more features are added it may be difficult to find a certain generator. Also, since all those methods begin with Random they don't play nice with intellisense.

I would like to suggest we group related methods using fluent API (examples):

Gen.Random().Dates()
Gen.Random().Doubles()
Gen.Random().Text(length: 50)
Gen.Random().Text().Short()
Gen.Random().Text().Long()
Gen.Random().Text().ReallyLong()
Gen.Random().Names().Female()
Gen.Random().Names().Male()
Gen.Random().Names().Surnames()
Gen.Random().Names().FullNames()

The methods above will return current Func<> generators.

I'm thinking about adding another set of methods for 'updating' single values:

Gen.Change().Double(74.5).By(10).Percent()
Gen.Change().Double(74.5).By(10).Absolute()

The former methods would return a random double in range [67.05-81.95], the latter [64.5-84.5].

That can be applied to dates as well:

Gen.Change().Date(xxx).By(21).Days()
Gen.Change().Date(xxx).By(5).Weeks()
Gen.Change().Date(xxx).By(2).Months()

Extending Adding my own

Hi great framework 👍 how can I extend this to other values,

There is a lack of tools like this.

It would be nice to reflect of a DB table (or EF entity) and populate the records based on the column types/names

Culture is not supported for Countries()() on kubernetes

Hi!

I get errors when I call the Gen.Random.Countries()() method in the Swarm container.

$ locale
LANG=C.UTF-8
LANGUAGE=en_US:en
LC_CTYPE="en_US.UTF-8"
LC_NUMERIC="en_US.UTF-8"
LC_TIME="en_US.UTF-8"
LC_COLLATE="en_US.UTF-8"
LC_MONETARY="en_US.UTF-8"
LC_MESSAGES="en_US.UTF-8"
LC_PAPER="en_US.UTF-8"
LC_NAME="en_US.UTF-8"
LC_ADDRESS="en_US.UTF-8"
LC_TELEPHONE="en_US.UTF-8"
LC_MEASUREMENT="en_US.UTF-8"
LC_IDENTIFICATION="en_US.UTF-8"
LC_ALL=en_US.UTF-8

Error Message:
System.Globalization.CultureNotFoundException : Culture is not supported. (Parameter 'culture') 4096 (0x1000) is an invalid culture identifier.
Stack Trace:
at System.Globalization.CultureData.GetCultureData(Int32 culture, Boolean bUseUserOverride)
at System.Globalization.RegionInfo..ctor(Int32 culture)
at RandomGen.RandomLink.<>c.<Countries>b__22_0(CultureInfo culture)
at System.Linq.Enumerable.SelectArrayIterator`2.MoveNext()
at System.Collections.Generic.HashSet`1.UnionWith(IEnumerable`1 other)
at System.Collections.Generic.HashSet`1..ctor(IEnumerable`1 collection, IEqualityComparer`1 comparer)
at System.Linq.Enumerable.DistinctIterator`1.ToList()
at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
at RandomGen.RandomLink.Items[T](IEnumerable`1 items, IEnumerable`1 weights)
at RandomGen.RandomLink.Countries()

Provide a seed value for Random generator

Hi Ali!

Is there a way to set the seed value for the underlying Random?

This is particularly helpful for consistent results when replaying from an event log :)

cheers,

Harry

Remove dependency on Json.NET

Let's replace Json.NET with System.Text.Json, one less dependency to worry about.

Also, I'm running into versioning clash in one of my test project that uses RandomGen (that depends on Json.NET 11) and CosmosDB (that depends on Json.NET 10) - having to maintain binding redirections.

I don't believe we need a config option to specify the json serializer used as it's only needed to load resource files.

I'm happy to implement the change.

Every number generator throws exception for equal arguments

Each of the following examples throws the exception:
Specified argument was out of the range of valid values.
Parameter name: min >= max

var _int = RandomGen.Gen.Random.Numbers.Integers(1, 1)();
var _decimal = RandomGen.Gen.Random.Numbers.Decimals(1, 1)();
var _double = RandomGen.Gen.Random.Numbers.Doubles(1, 1)();
var _long = RandomGen.Gen.Random.Numbers.Longs(1, 1)();
var _uint = RandomGen.Gen.Random.Numbers.UnsignedIntegers(1, 1)();

Adding random timespans

If @jkonecki are OK, I will add this one too.

Support for single item generation

Curently RandomGen supports creation of generators (Func<T>) that can be used to obtain a series of random items.

I found that in most cases I require a single random item at a time.

The solution is to either store the generators (Func<T>) and reuse them between calls or to evaluate the function instantly (Gen.Random.Numbers.Integers()()) which doesn't look nice in code ()().

What I would like to be able to do is write just:

var number = Gen.Random.Numbers.Integers();.

I would like to propose that we create an additional set of methods that would compliment the existing ones and allow for single items to be generated:

Func<int> Gen.Random.Numbers.Integers()
int Gen.Random.Number.Integer()