/// <summary>
/// Returns a new string instance, with all occurrences of the specified substring outside quotes replaced by a new value.
/// </summary>
/// <param name="str">This string instance.</param>
/// <param name="oldChar">All occurrences of this character are to be replaced.</param>
/// <param name="newChar">The new character to replace occurrences of the <paramref name="oldChar"/>.</param>
/// <param name="startIndex">The zero-based position indicating where the search for <paramref name="oldChar" /> starts.</param>
/// <param name="leftQuotes">Specifies an array of Unicode characters as the left quotes.
/// A left quote of an index of this array corresponds to the right quote of that index of the array specified by <paramref name="rightQuotes" />.</param>
/// <param name="rightQuotes">The right quotes.</param>
/// <returns>
/// A new string instance with characters replaced.
/// </returns>
/// <exception cref="System.FormatException">Occurs when there is a quote mismatch in the string instance.</exception>
public static string ReplaceWithQuotes(this string str, char oldChar, char newChar, int startIndex, char[] leftQuotes, char[] rightQuotes)
{
var strLen = str.Length;
ExceptionHelper.ArgumentRangeRequired("startIndex", startIndex, 0, true, strLen - 1, true);
return(_innerReplaceWithQuotes(str, c => c == oldChar, newChar, startIndex, strLen, leftQuotes, rightQuotes));
}
/// <summary>
/// Reports the zero-based index of the first occurrence of the specified <paramref name="value" /> outside quotes in this string.
/// </summary>
/// <param name="str">This string instance.</param>
/// <param name="value">The substring to seek.</param>
/// <param name="startIndex">The search starting position.</param>
/// <param name="primaryLeftQuote">Specifies the Unicode character as the primary left quote.</param>
/// <param name="primaryRightQuote">Specifies the Unicode character as the primary right quote.</param>
/// <param name="secondaryLeftQuotes">Specifies an array of Unicode characters as the secondary left quotes. A left quote of an index of this array corresponds to the right quote of that index of the array specified by <paramref name="secondaryRightQuotes" />. Secondary quotes are escaped when they are inside a pair of primary quotes.</param>
/// <param name="secondaryRightQuotes">Specifies an array of Unicode characters as the secondary right quotes. A right quote of an index of this array corresponds to the left quote of that index of the array specified by <paramref name="secondaryLeftQuotes" />. Secondary quotes are escaped when they are inside a pair of primary quotes.</param>
/// <param name="comparisonType">One of the enumeration values that specifies the rules for the search of <paramref name="value" />.</param>
/// <returns>
/// The zero-based index position of the first occurrence of <paramref name="value" /> if it is found outside quotes, or -1 if it is not.
/// </returns>
/// <exception cref="System.FormatException">Occurs when there is quote mismatch in the string instance.</exception>
public static int IndexOfWithQuotes(this string str, string value, int startIndex, char primaryLeftQuote, char primaryRightQuote, char[] secondaryLeftQuotes, char[] secondaryRightQuotes, StringComparison comparisonType = StringComparison.Ordinal)
{
var strLen = str.Length;
ExceptionHelper.ArgumentRangeRequired("startIndex", startIndex, 0, true, strLen - 1, true);
return(_innerIndexOfWithQuotes(str, value, startIndex, str.Length, primaryLeftQuote, primaryRightQuote, secondaryLeftQuotes, secondaryRightQuotes, comparisonType));
}
/// <summary>
/// Returns a new string instance, with all Unicode characters, which are outside quotes and satisfy the specified predicate, replaced by a new character.
/// </summary>
/// <param name="str">This string instance.</param>
/// <param name="predicate">A function to test each Unicode character outside quotes of the current string.</param>
/// <param name="newChar">The new character to replace those satisfying the predicate.</param>
/// <param name="startIndex">The zero-based position indicating where the search for characters satisfying <paramref name="predicate" /> starts.</param>
/// <param name="leftQuote">Specifies the Unicode character as the left quote.</param>
/// <param name="rightQuote">Specifies the Unicode character as the right quote.</param>
/// <returns>
/// A new string instance with characters replaced.
/// </returns>
/// <exception cref="System.FormatException">Occurs when there is a quote mismatch in the string instance.</exception>
public static string ReplaceWithQuotes(this string str, Func <char, bool> predicate, char newChar, int startIndex = 0, char leftQuote = '{', char rightQuote = '}')
{
var strLen = str.Length;
ExceptionHelper.ArgumentRangeRequired("startIndex", startIndex, 0, true, strLen - 1, true);
return(_innerReplaceWithQuotes(str, predicate, newChar, startIndex, strLen, leftQuote, rightQuote));
}
/// <summary>
/// Reports the zero-based index of the next character which matches another specified character outside quotes.
/// Those matched characters are usually brackets, such as '(' and ')', '[' and ']', '{' and '}'.
/// </summary>
/// <param name="str">This string instance.</param>
/// <param name="leftChar">The character that matches the character to search, typically a left bracket, such as '(', '[' or '{'.</param>
/// <param name="rightChar">The next character to search, typically a right bracket, such as ')', ']' or '}'.</param>
/// <param name="leftQuotes">
/// Specifies an array of Unicode characters as the left quotes.
/// A left quote of an index of this array corresponds to the right quote of that index of the array specified by <paramref name="rightQuotes" />.
/// Any character that appears between a left quote and its corresponding right quote will not be considered a match.
/// </param>
/// <param name="rightQuotes">
/// Specifies an array of Unicode characters as the right quotes.
/// A right quote of an index of this array corresponds to the left quote of that index of the array specified by <paramref name="leftQuotes" />.
/// Any character that appears between a left quote and its corresponding right quote will not be considered a match.
/// </param>
/// <param name="startIndex">The search starting position. NOTE that this position should be right at the <paramref name="leftChar"/> you want to find a match for. For example, if it is intended to find a match of the first left square bracket at position 0 in string "[abc[de]fgh]", the <paramref name="startIndex" /> should be 0.</param>
/// <returns>
/// The zero-based index position of <paramref name="rightChar" /> if that character is found and it matches <paramref name="leftChar" />, or -1 if it is not.
/// </returns>
/// <exception cref="System.ArgumentOutOfRangeException">Occurs if <paramref name="startIndex" /> or <paramref name="startIndex" /> + <paramref name="length" /> does not indicate a valid position in the string.</exception>
public static int IndexOfNextMatch(this string str, char leftChar, char rightChar, char[] leftQuotes, char[] rightQuotes, int startIndex = 0)
{
var strLen = str.Length;
ExceptionHelper.ArgumentRangeRequired <int>("startIndex", startIndex, 0, true, strLen - 1, true);
_searchRightQuote(str, ref startIndex, strLen, leftChar, rightChar, leftQuotes, rightQuotes);
return(startIndex);
}
/// <summary>
/// Returns a new string instance, with all occurrences of the specified substrings outside quotes replaced by a new value.
/// </summary>
/// <param name="str">This string instance.</param>
/// <param name="oldValues">All occurrences of these substrings are to be replaced.</param>
/// <param name="newValue">The new value to replace occurrences of <paramref name="oldValues" />.</param>
/// <param name="startIndex">The zero-based position indicating where the search for <paramref name="oldValues" /> starts.</param>
/// <param name="leftQuotes">Specifies an array of Unicode characters as the left quotes.
/// A left quote of an index of this array corresponds to the right quote of that index of the array specified by <paramref name="rightQuotes" />.</param>
/// <param name="rightQuotes">Specifies an array of Unicode characters as the right quotes.
/// A right quote of an index of this array corresponds to the left quote of that index of the array specified by <paramref name="leftQuotes" />.</param>
/// <param name="comparisonType">One of the enumeration values that specifies the rules for the search of <paramref name="oldValues" />.</param>
/// <returns>
/// A new string instance with substrings replaced.
/// </returns>
/// <exception cref="System.FormatException">Occurs when there is a quote mismatch in the string instance.</exception>
public static string ReplaceWithQuotes(this string str, string[] oldValues, string newValue, int startIndex,
char[] leftQuotes, char[] rightQuotes, StringComparison comparisonType = StringComparison.Ordinal)
{
var strLen = str.Length;
ExceptionHelper.ArgumentRangeRequired("startIndex", startIndex, 0, true, strLen - 1, true);
return(_innerReplaceWithQuotes(str, oldValues, newValue, startIndex, strLen, leftQuotes, rightQuotes, comparisonType));
}
/// <summary>
/// Gets an enumerator that traverse through k-combinations of elements in the current <see cref="System.Array"/>. A k-combination is a subset of the current array which contains k elements. For example, {1,2,3}, {2,3,4}, etc., are the 3-combinations of integer array {1,2,3,4,5}.
/// </summary>
/// <typeparam name="T">The type of elements in the current array.</typeparam>
/// <param name="array">This array.</param>
/// <param name="k">The number of elements of each combination returned by the enumerator.</param>
/// <returns>
/// An enumerator that traverse through k-combinations of elements in the current array.
/// </returns>
public static IEnumerator <T[]> GetCombinationEnumerator <T>(this T[] array, int k)
{
var endIndex = array.Length;
ExceptionHelper.ArgumentRangeRequired <int>("k", k, 0, true, endIndex, true);
var innerIE = _combNonRecursive <T>(array, 0, endIndex, endIndex, k);
while (innerIE.MoveNext())
{
yield return(innerIE.Current);
}
}
/// <summary>
/// Gets an enumerator that traverse through k-combinations of elements in the current <see cref="System.Array"/>. A k-combination is a subset of the current array which contains k elements. For example, {1,2,3}, {2,3,4}, etc., are the 3-combinations of integer array {1,2,3,4,5}.
/// </summary>
/// <typeparam name="T">The type of elements in the current array.</typeparam>
/// <param name="array">This array.</param>
/// <param name="startIndex">The elements in the returned combinations will be limited to elements starting from this index and ending at <paramref name="startIndex"/> + <paramref name="length"/> - 1.</param>
/// <param name="length">The elements in the returned combinations will be limited to elements starting from <paramref name="startIndex"/> and ending at <paramref name="startIndex"/> + <paramref name="length"/> - 1.</param>
/// <param name="k">The number of elements of each combination returned by the enumerator.</param>
/// <returns>An enumerator that traverse through k-combinations of elements in the current array.</returns>
public static IEnumerator <T[]> GetCombinationEnumerator <T>(this T[] array, int startIndex, int length, int k)
{
var endIndex = ExceptionHelper.ForwardCheckStartIndexAndLength(startIndex, length, array.Length);
ExceptionHelper.ArgumentRangeRequired <int>("k", k, 0, true, length, true);
var innerIE = _combNonRecursive <T>(array, startIndex, endIndex, length, k);
while (innerIE.MoveNext())
{
yield return(innerIE.Current);
}
}
/// <summary>
/// Reports the index of the first character satisfying the specified predicate.
/// The search starts at a specified character position toward the end of this string instance.
/// </summary>
/// <param name="str">This string instance.</param>
/// <param name="startIndex">The search starting position. The search proceeds from <paramref name="startIndex"/> toward the end of this instance.</param>
/// <param name="predicate">A function to test each character of the current string.</param>
/// <returns>The zero-based index position of the first character in this instance satisfying the specified predicate.</returns>
public static int IndexOf(this string str, Func <char, bool> predicate, int startIndex = 0)
{
if (startIndex < 0)
{
startIndex += str.Length;
ExceptionHelper.ArgumentRangeRequired("startIndex", startIndex, -1, true, -str.Length, true);
}
else
{
ExceptionHelper.ArgumentRangeRequired("startIndex", startIndex, 0, true, str.Length - 1, true);
}
return(_innerIndexOf(str, predicate, startIndex, str.Length));
}
/// <summary>
/// Gets an enumerator that traverse through combinations of elements in the current <see cref="System.Array"/>. A combination is a subset of the current array. For example, {1,2,3}, {2,3,4}, etc., are the 3-combinations of integer array {1,2,3,4,5}, while {1,2}, {3,4} are its 2-combinations.
/// </summary>
/// <typeparam name="T">The type of elements in the current array.</typeparam>
/// <param name="array">This array.</param>
/// <param name="startK">The minimum number of elements of each combination returned by the enumerator if <paramref name="startK" /> is no larger than <paramref name="endK" />; otherwise, the maximum number of elements of each combination returned by the enumerator.</param>
/// <param name="endK">The maximum number of elements of each combination returned by the enumerator if <paramref name="startK" /> is no larger than <paramref name="endK" />; otherwise, the minimum number of elements of each combination returned by the enumerator.</param>
/// <param name="returnLimits">Limits the number of combinations the returned enumerator can go through. The first element of this array limits the number of returned <paramref name="startK" />-combinations, the second element limits the number of returned (<paramref name="startK" />+1)-combinations (or (<paramref name="startK" />-1)-combinations if <paramref name="startK" /> is larger than <paramref name="endK" />), and so forth. NOTE that if k-combination has no corresponding return limit, in which case the length of <paramref name="returnLimits" /> is smaller than k - <paramref name="startK" /> + 1, then the number of returned k-combinations will not be limited.
/// <para>For example, if the current array is {1,2,3,4,5}, and <paramref name="startIndex" /> is 0, <paramref name="length" /> 5, <paramref name="startK" /> 2, <paramref name="endK" /> 3, <paramref name="returnLimits" /> {2,3}, then returned enumerator will go through {1,2}, {1,3}, {1,2,3}, {1,2,4}, {1,2,5}. If <paramref name="endK" /> is changed to 4, then all 4-combinations {1,2,3,4},{1,2,3,5},{1,2,4,5},{1,3,4,5},{2,3,4,5} will be returned by the enumerator since there is no limit on 4-combinations.</para>
/// </param>
/// <returns>
/// An enumerator that traverse through combinations of elements in the current array.
/// </returns>
public static IEnumerator <T[]> GetMultiCombinationEnumerator <T>(this T[] array, int startK, int endK, int[] returnLimits)
{
var endIndex = array.Length;
ExceptionHelper.ArgumentRangeRequired <int>("startK", startK, 0, true, endIndex, true);
ExceptionHelper.ArgumentRangeRequired <int>("endK", endK, 0, true, endIndex, true);
var innerIE = _combNonRecursive <T>(array, 0, endIndex, endIndex, 0, startK, endK, returnLimits);
while (innerIE.MoveNext())
{
yield return(innerIE.Current);
}
}
/// <summary>
/// Returns a random bool value.
/// </summary>
/// <param name="rnd">The Random instance to generate the random value.</param>
/// <param name="probabilityOfTrue">The odds of returning true. The value must be set between 0 and 1.</param>
/// <returns>A random bool value.</returns>
/// <exception cref="System.ArgumentOutOfRangeException">Occurs when <paramref name="probabilityOfTrue"/> is smaller than 0 or greater than 1.</exception>
public static bool NextBoolean(this Random rnd, double probabilityOfTrue)
{
ExceptionHelper.ArgumentRangeRequired("probabilityOfTrue", probabilityOfTrue, 0, true, 1, true);
if (probabilityOfTrue == 1)
{
return(true);
}
else if (probabilityOfTrue == 0)
{
return(false);
}
else
{
double val = rnd.NextDouble();
if (val < probabilityOfTrue)
{
return(true);
}
else if (val > probabilityOfTrue)
{
return(false);
}
else
{
int tc = Environment.TickCount;
if (tc % 2 == 0)
{
return(true);
}
else
{
return(false);
}
}
}
}
/// <summary>
/// Reports the zero-based index of the first occurrence in this instance of any character in a specified array of Unicode characters <paramref name="anyOf"/>.
/// The search starts at a specified character position and examines a specified number of character positions.
/// </summary>
/// <param name="str">This string instance.</param>
/// <param name="anyOf">A Unicode character array containing one or more characters to seek.</param>
/// <param name="startIndex">The search starting position.</param>
/// <param name="hitIndex">Returns the index of the encountered character in the specified array of Unicode characters.</param>
/// <returns>The zero-based index position of the first character in this instance satisfying the specified predicate.</returns>
public static int IndexOfAny(this string str, char[] anyOf, int startIndex, out int hitIndex)
{
ExceptionHelper.ArgumentRangeRequired("startIndex", startIndex, 0, true, str.Length - 1, true);
return(_innerIndexOfAny(str, anyOf, startIndex, str.Length, out hitIndex));
}
/// <summary>
/// Reports the zero-based index of the last occurrence of any of the specified <paramref name="values"/> outside quotes in this string. The search starts from <pararef name="startIndex" /> and advances towards the beginning of the current string.
/// </summary>
/// <param name="str">This string instance.</param>
/// <param name="values">The substrings to seek.</param>
/// <param name="startIndex">The search starting position.</param>
/// <param name="primaryLeftQuotes">Specifies an array of Unicode characters as the primary left quotes. A left quote of an index of this array corresponds to the right quote of that index of the array specified by <paramref name="primaryRightQuote" />.</param>
/// <param name="primaryRightQuotes">Specifies an array of Unicode characters as the primary right quotes. A right quote of an index of this array corresponds to the left quote of that index of the array specified by <paramref name="primaryLeftQuote" />.</param>
/// <param name="secondaryLeftQuotes">Specifies an array of Unicode characters as the secondary left quotes. A left quote of an index of this array corresponds to the right quote of that index of the array specified by <paramref name="secondaryRightQuotes" />. Secondary quotes are escaped when they are inside a pair of primary quotes.</param>
/// <param name="secondaryRightQuotes">Specifies an array of Unicode characters as the secondary right quotes. A right quote of an index of this array corresponds to the left quote of that index of the array specified by <paramref name="secondaryLeftQuotes" />. Secondary quotes are escaped when they are inside a pair of primary quotes.</param>
/// <param name="comparisonType">One of the enumeration values that specifies the rules for the search of <paramref name="values" />.</param>
/// <returns>
/// A <see cref="System.StringSearchResult"/> object that stores the zero-based index position of the last occurrence of any of the specified <paramref name="values"/> if one is found outside quotes, or <c>null</c> if none is found.
/// </returns>
/// <exception cref="System.FormatException">Occurs when there is quote mismatch in the string instance.</exception>
public static StringSearchResult LastIndexOfAnyWithQuotes(this string str, string[] values, int startIndex, char[] primaryLeftQuotes, char[] primaryRightQuotes, char[] secondaryLeftQuotes, char[] secondaryRightQuotes, StringComparison comparisonType = StringComparison.Ordinal)
{
ExceptionHelper.ArgumentRangeRequired("startIndex", startIndex, 0, true, str.Length - 1, true);
return(_innerLastIndexOfWithQuotes(str, values, startIndex, -1, primaryLeftQuotes, primaryRightQuotes, secondaryLeftQuotes, secondaryRightQuotes, comparisonType));
}
