/// <summary>
/// Generates a random string using only decimal digits and letters from the English alphabet, with the restriction that the first character cannot be a decimal digit.
/// </summary>
/// <param name="random">The pseudo-random engine that will be used to generate bits from which the return value is derived.</param>
/// <param name="length">The length of the string to be generated.</param>
/// <param name="casing">The letter casing used for English letters.</param>
/// <returns>A random string which conforms to typical rules of valid identifier names in many programming languages.</returns>
/// <seealso cref="Identifier(IRandom, int)"/>
/// <seealso cref="Identifier(IRandom, int, float)"/>
/// <seealso cref="Identifier(IRandom, int, Casing, float)"/>
public static string Identifier(this IRandom random, int length, Casing casing)
{
if (length <= 0)
{
return("");
}
char[] buffer = new char[length];
buffer[0] = GetAlphabeticCharacters(casing).RandomElement(random);
random.Characters(buffer, 1, length - 1, GetAlphaNumericCharacters(casing));
return(new string(buffer));
}
/// <summary>
/// Generates a random string using only decimal digits and letters from the English alphabet, plus the underscore character which can occur randomly with a specified probability, with the restriction that the first character cannot be a decimal digit.
/// </summary>
/// <param name="random">The pseudo-random engine that will be used to generate bits from which the return value is derived.</param>
/// <param name="length">The length of the string to be generated.</param>
/// <param name="casing">The letter casing used for English letters.</param>
/// <param name="underscoreProbability">The probability of any specific index in the string being a underscore character. Must be in the range [0, 1].</param>
/// <returns>A random string which conforms to typical rules of valid identifier names in many programming languages.</returns>
/// <remarks><para>It is guaranteed that except at the very beginning of the string, two underscore characters will never be generated
/// one immediately after the other, regardless of the underscore probability.</para>
/// <para>An underscore probability of 0 will guarantee that there are no underscore at all, while a probability of 1 will guarantee
/// that every second character is a underscore character. Probabilities less than 1 but greater that 0.5 will be biased toward the
/// same every-other character outcome, but will have a chance of generating longer sequences of non-underscore characters, rather than
/// being strictly limited to one non-underscore character at a time.</para></remarks>
/// <seealso cref="Identifier(IRandom, int)"/>
/// <seealso cref="Identifier(IRandom, int, float)"/>
/// <seealso cref="Identifier(IRandom, int, Casing)"/>
public static string Identifier(this IRandom random, int length, Casing casing, float underscoreProbability)
{
if (length <= 0)
{
return("");
}
char[] buffer = new char[length];
if (random.Probability(underscoreProbability))
{
buffer[0] = '_';
}
else
{
buffer[0] = GetAlphabeticCharacters(casing).RandomElement(random);
}
random.Characters(buffer, 1, length - 1, GetAlphaNumericCharacters(casing), '_', underscoreProbability, true, true, false);
return(new string(buffer));
}
/// <summary>
/// Generates a random string using the provided character set, plus a separator character which can occur randomly with a specified probability.
/// </summary>
/// <param name="random">The pseudo-random engine that will be used to generate bits from which the return value is derived.</param>
/// <param name="length">The length of the string to be generated.</param>
/// <param name="characters">The allowable characters to select from when generating the string.</param>
/// <param name="separator">The separator character to be randomly inserted into the string according to the probability specified.</param>
/// <param name="separatorProbability">The probability of any specific index in the string being a separator character. Must be in the range [0, 1].</param>
/// <param name="allowSeparatorAtEnd">Whether or not the last character to be generated is allowed to be a separator character.</param>
/// <param name="allowSeparatorAtBegin">Whether or not the first character to be generated is allowed to be a separator character.</param>
/// <param name="forceSeparatorAtBegin">Whether or not the first character to be generated must be a separator character. Ignored if <paramref name="allowSeparatorAtBegin"/> is false.</param>
/// <returns>A random string, with each character being a uniformly random selection from the provided character set.</returns>
/// <remarks><para>It is guaranteed that two separator characters will never be generated one immediately after the other, regardless of the separator probability.</para>
/// <para>A separator probability of 0 will guarantee that there are no separators at all, while a probability of 1 will guarantee
/// that every second character is a separtor character. Probabilities less than 1 but greater that 0.5 will be biased toward the
/// same every-other character outcome, but will have a chance of generating longer sequences of non-separator characters, rather than
/// being strictly limited to one non-separator character at a time.</para></remarks>
/// <seealso cref="String(IRandom, int, char[])"/>
/// <seealso cref="Characters(IRandom, char[], int, int, char[], char, float, bool, bool, bool)"/>
public static string String(this IRandom random, int length, char[] characters, char separator, float separatorProbability, bool allowSeparatorAtEnd = false, bool allowSeparatorAtBegin = false, bool forceSeparatorAtBegin = false)
{
char[] buffer = new char[length];
random.Characters(buffer, 0, length, characters, separator, separatorProbability);
return(new string(buffer));
}
/// <summary>
/// Generates a random string using the provided character set.
/// </summary>
/// <param name="random">The pseudo-random engine that will be used to generate bits from which the return value is derived.</param>
/// <param name="length">The length of the string to be generated.</param>
/// <param name="characters">The allowable characters to select from when generating the string.</param>
/// <returns>A random string, with each character being a uniformly random selection from the provided character set.</returns>
/// <seealso cref="String(IRandom, int, char[], char, float, bool, bool, bool)"/>
/// <seealso cref="Characters(IRandom, char[], int, int, char[])"/>
public static string String(this IRandom random, int length, char[] characters)
{
char[] buffer = new char[length];
random.Characters(buffer, 0, length, characters);
return(new string(buffer));
}