Skip to content

Home

Jump to bottom
bfren edited this page Apr 13, 2024 · 13 revisions

Rnd: Random value generators

Although primarily of use in unit tests, the random string generators in particular have a much wider use, for example generating secure passphrases or encryption key.

Usage of Rnd is mainly through the base class Rnd, e.g.:

using RndF;

// 'flip a coin' - random true/false
Console.WriteLine("bool: " + Rnd.Flip);

// cryptographically-secure random Guid (better than Guid.NewGuid())
Console.WriteLine("Guid: " + Rnd.Guid);

// 8-word passphrase, using EFF's short word list, with capital letters and a number
Console.WriteLine("string: " + Rnd.Pass);

// 6-letter string of lower- and upper-case letters
Console.WriteLine("string: " + Rnd.Str);

// between the years 1 and 9999
Console.WriteLine("DateOnly: " + Rnd.Date);

// between 00:00 and 23:59, and the years 1 and 9999
Console.WriteLine("DateTime: " + Rnd.DateTime);

// between 00:00 and 23:59
Console.WriteLine("TimeOnly: " + Rnd.Time);

// numbers are between 0 and 10,000 inclusive
Console.WriteLine("double: " + Rnd.Dbl);
Console.WriteLine("float: " + Rnd.Flt);
Console.WriteLine("int: " + Rnd.Int);
Console.WriteLine("long: " + Rnd.Lng);
Console.WriteLine("uint: " + Rnd.UInt);
Console.WriteLine("ulong: " + Rnd.ULng);

/**
bool: False
Guid: aca15809-ef7f-0b75-a2c9-e9fd0a252362
string: Mammal3-Jaywalker-Couch-Fox-Automobile-Outhouse-Wipeout-Oiliness
string: dlAsdG
DateOnly: 14/06/9837
DateTime: 05/05/0558 21:52:19
TimeOnly: 02:54
double: 425.6777661938279
float: 1349.789
int: 1483
long: 2699
uint: 6767
ulong: 1500
*/

Bytes

The heart of the generator functions is Rnd.ByteF.Get(int length). This uses RandomNumberGenerator to fill a byte array with random bytes (see here).

Utility Functions

Each kind of generators is grouped together in static classes, e.g. NumberF:

using RndF;

// short version
var v0 = Rnd.Lng;

// long version - called by short version
var v1 = Rnd.NumberF.GetInt64(max: 10000L);

This gives you greater flexibility over what is returned, for example specifying the minimum or maximum number, or the length of the random string.

Strings

Utility functions for random strings are contained within Rnd.StringF. By default, Rnd.StringF.Get(int length) will return a mix of lowercase and uppercase numbers. However, say you want a 25-character string with lowercase letters and special characters only, you could do this:

using RndF;

Console.WriteLine(Rnd.StringF.Get(
    length: 3,
    classes: Chars.Lower | Chars.Special
));

// ~cy^k@i~@`n:q^+zfngp¬`;*l

If you do something that doesn't make sense, like try to generate a string without character classes, or ask for a string that's shorter than the number of classes you've requested, you'll get an error:

using RndF;

Console.WriteLine(Rnd.StringF.Get(
    length: 3,
    classes: Chars.All
));

// InvalidCharsException:
// "Using requested character groups results in a string longer than the one requested."

Console.WriteLine(Get(
    length: 10,
    classes: Chars.None
));

// InvalidCharsException:
// "You must include at least one character class."

Passphrases

The EFF publishes lists of words for generating passphrases. Both the short (with unique three-letter prefixes) and long word lists are included here (modified with British spellings).

Rnd.Pass - which calls Rnd.StringF.Passphrase() - uses the EFF's short word list to generate a (recommended) 8-word passphrase, where each word is capitalised and one of them contains a random number before or after it. Each word is separated by Rnd.StringF.DefaultSeparator ('-'), and no word can be repeated.

The other passphrase functions use the long word list, which is more secure for fewer numbers of words. By default Rnd.StringF.Passphrase(int numberOfWords) will both capitalise each word and add a number, but if you don't want that, or you want a custom separator character, you can do this:

using RndF;

var pass = Rnd.StringF.Passphrase(
    numberOfWords: 5,
    separator: '|',
    upperFirst: false,
    includeNumber: false
);
Console.WriteLine(pass);

// (e.g.) pelt|banked|subzero|huff|subscribe

If you so desire you can even use your own word list to generate a passphrase:

using RndF;

var pass = Rnd.StringF.Passphrase(
    wordList: new[] { "one", "two", "three", "four", "five" },
    numberOfWords: 3,
    separator: '/',
    upperFirst: true,
    includeNumber: false
);
Console.WriteLine(pass);

// (e.g.) Three/One/Two

Clone this wiki locally