/// <summary>Gets the value of a specific pool with respect to a specific [optional] property name.
/// </summary>
/// <typeparam name="T">The type of the value.</typeparam>
/// <param name="dataQuery">The data query, i.e. property name/value pairs.</param>
/// <param name="propertyName">The name of the property to search.</param>
/// <param name="tryGetPoolElement">A method to pick a specific object.</param>
/// <param name="value">On input this is a standard value of the property; on exit this argument will be changed if and only if a property with
/// name <paramref name="propertyName"/> exists and contains valid data.</param>
/// <param name="dataAdvice">Data advice, i.e. a list of possible outcome to improve the useability, perhaps <c>null</c>.</param>
/// <returns>A value indicating whether <paramref name="value"/> contains valid data.</returns>
/// <exception cref="ArgumentException">Thrown, if the user input is invalid, i.e. the name of the pool item is not given in its <see cref="System.String"/> representation.</exception>
/// <exception cref="ArgumentNullException">Thrown, if <paramref name="dataQuery"/> is <c>null</c>.</exception>
public static bool TryGetOptionalPropertyPoolValue <T>(this IExcelDataQuery dataQuery, string propertyName, ExcelDataQuery.tTryGetPoolElement <T> tryGetPoolElement, ref T value, IExcelDataAdvice dataAdvice = null)
{
if (dataQuery == null)
{
throw new ArgumentNullException("dataQuery");
}
string objectName;
ExcelPropertyValueState state = dataQuery.TryGetPropertyValue <String>(propertyName, out objectName, dataAdvice);
if (state == ExcelPropertyValueState.ProperProperty)
{
T tempValue;
if (tryGetPoolElement(objectName, out tempValue) == true)
{
value = tempValue;
return(true);
}
throw new ArgumentException("No valid input for property '" + propertyName + "' found; '" + objectName + "' is invalid input" + GetFormatedDataQueryName(dataQuery) + ".");
}
else if ((state == ExcelPropertyValueState.NoPropertyFound) || (state == ExcelPropertyValueState.ValueIsEmptyExcelCell))
{
return(false);
}
throw new ArgumentException("No valid input for property '" + propertyName + "' found" + GetFormatedDataQueryName(dataQuery) + ".");
}
/// <summary>Gets the value of a specific required property.
/// </summary>
/// <typeparam name="T">The type of the value.</typeparam>
/// <param name="dataQuery">The data query, i.e. property name/value pairs.</param>
/// <param name="propertyName">The name of the property to search.</param>
/// <param name="tryGetPoolElement">A method to pick a specific object.</param>
/// <param name="dataAdvice">Data advice, i.e. a list of possible outcome to improve the useability, perhaps <c>null</c>.</param>
/// <returns>The value of the property.</returns>
/// <exception cref="ArgumentException">Thrown, if no property or valid value is given by the user.</exception>
/// <exception cref="ArgumentNullException">Thrown, if <paramref name="dataQuery"/> is <c>null</c>.</exception>
public static T GetRequiredPropertyPoolValue <T>(this IExcelDataQuery dataQuery, string propertyName, ExcelDataQuery.tTryGetPoolElement <T> tryGetPoolElement, IExcelDataAdvice dataAdvice = null)
{
if (dataQuery == null)
{
throw new ArgumentNullException("dataQuery");
}
string objectName;
ExcelPropertyValueState state = dataQuery.TryGetPropertyValue <String>(propertyName, out objectName, dataAdvice);
if (state == ExcelPropertyValueState.NoPropertyFound)
{
throw new ArgumentException("No property with name '" + propertyName + " ' found" + GetFormatedDataQueryName(dataQuery) + ".");
}
else if (state == ExcelPropertyValueState.NoValidValue)
{
throw new ArgumentException("No valid input for property '" + propertyName + "' found" + GetFormatedDataQueryName(dataQuery) + ".");
}
else if (state == ExcelPropertyValueState.ValueIsEmptyExcelCell)
{
throw new ArgumentException("Input required for property '" + propertyName + "'" + GetFormatedDataQueryName(dataQuery) + ".");
}
T value;
if (tryGetPoolElement(objectName, out value) == true)
{
return(value);
}
throw new ArgumentException("No valid input for property '" + propertyName + "' found" + GetFormatedDataQueryName(dataQuery) + ".");
}
/// <summary>Gets the value of a specific [optional] property.
/// </summary>
/// <typeparam name="T">The type of the value.</typeparam>
/// <param name="dataQuery">The <see cref="IExcelDataQuery"/> object.</param>
/// <param name="propertyName">The name of the property to search.</param>
/// <param name="value">On input this is a standard value of the property; on exit this argument will be changed if and only if a property with
/// name <paramref name="propertyName"/> exists and contains valid data.</param>
/// <param name="dataAdvice">A data advice for a the property value, i.e. possible outcome to improve the useability.</param>
/// <param name="propertyValueColumnIndex">The null-based index of the column which contains the value.</param>
/// <returns>A value indicating whether <paramref name="value"/> has been changed with user input.</returns>
/// <exception cref="ArgumentException">Thrown, if <typeparamref name="T"/> represents the type of a specific enumeration or no <b>valid</b> user input is given, i.e.
/// a property of name <paramref name="propertyName"/> exists but the value is non-empty and can not convert to <typeparamref name="T"/>.</exception>
/// <exception cref="ArgumentNullException">Thrown, if <paramref name="dataQuery"/> is <c>null</c>.</exception>
/// <remarks>Use this method if some standard values are available and the user has the option to change the standard setting.</remarks>
public static bool TryGetOptionalPropertyValue <T>(this IExcelDataQuery dataQuery, string propertyName, ref T value, IExcelDataAdvice dataAdvice = null, int propertyValueColumnIndex = 1)
{
T tempValue;
ExcelPropertyValueState state = TryGetPropertyValue <T>(dataQuery, propertyName, out tempValue, dataAdvice, propertyValueColumnIndex);
if (state == ExcelPropertyValueState.NoValidValue)
{
throw new ArgumentException("No valid input for property '" + propertyName + "' found" + GetFormatedDataQueryName(dataQuery) + ".");
}
else if (state == ExcelPropertyValueState.ProperProperty)
{
value = tempValue;
return(true);
}
return(false);
}
/// <summary>Gets the value of a specific [optional] property.
/// </summary>
/// <typeparam name="TEnum">The type of the value which is assumed to be a enumeration.</typeparam>
/// <param name="dataQuery">The <see cref="IExcelDataQuery"/> object.</param>
/// <param name="propertyName">The name of the property to search.</param>
/// <param name="value">On input this is a standard value of the property; on exit this argument will be changed if and only if a property with
/// name <paramref name="propertyName"/> exists and contains valid data.</param>
/// <param name="enumStringRepresentationUsage">The method how to compute the <see cref="System.String"/> representation of the enumeration <typeparamref name="TEnum"/>.</param>
/// <param name="propertyValueColumnIndex">The null-based index of the column which contains the value, the second column is standard.</param>
/// <returns>A value indicating whether <paramref name="value"/> has been changed with user input.</returns>
/// <exception cref="ArgumentException">Thrown, if <typeparamref name="TEnum"/> does not represents a specific enumeration or no <b>valid</b> user input is given, i.e.
/// a property of name <paramref name="propertyName"/> exists but the value is non-empty and can not convert to <typeparamref name="TEnum"/>.</exception>
/// <exception cref="ArgumentNullException">Thrown, if <paramref name="dataQuery"/> is <c>null</c>.</exception>
/// <remarks>Use this method if some standard values are available and the user has the option to change the standard setting.</remarks>
public static bool TryGetOptionalPropertyValue <TEnum>(this IExcelDataQuery dataQuery, string propertyName, ref TEnum value, EnumStringRepresentationUsage enumStringRepresentationUsage, int propertyValueColumnIndex = 1)
where TEnum : struct, IComparable, IConvertible, IFormattable
{
TEnum tempValue;
ExcelPropertyValueState state = TryGetPropertyValue <TEnum>(dataQuery, propertyName, out tempValue, enumStringRepresentationUsage, propertyValueColumnIndex);
if (state == ExcelPropertyValueState.NoValidValue)
{
throw new ArgumentException("No valid input for property '" + propertyName + "' found" + GetFormatedDataQueryName(dataQuery) + ".");
}
else if (state == ExcelPropertyValueState.ProperProperty)
{
value = tempValue;
return(true);
}
return(false);
}
/// <summary>Sets an optional property value, i.e. if a specific property value is available the value will be used
/// to change the state of a specific object, otherwise the standard value will be use.
/// </summary>
/// <typeparam name="T">The type of the value.</typeparam>
/// <param name="dataQuery">The property stream.</param>
/// <param name="propertyName">The name of the property.</param>
/// <param name="trySetPropertyValue">A delegate which is used to set the value of the property for a specific object, if the property value is available.</param>
/// <param name="dataAdvice">A data advice for a the property value, i.e. possible outcome to improve the useability.</param>
/// <param name="propertyValueColumnIndex">The null-based index of the column which contains the value.</param>
/// <exception cref="ArgumentNullException">Thrown, if <paramref name="dataQuery"/> is <c>null</c>.</exception>
/// <remarks>Use this method for properties which have some standard value if the user does not
/// enter a specific value, for example the standard tolerance used for a optimizer algorithm is 1e-7 if the
/// user does not enter a different value.</remarks>
public static void SetOptionalPropertyValue <T>(this IExcelDataQuery dataQuery, string propertyName, Func <T, bool> trySetPropertyValue, IExcelDataAdvice dataAdvice = null, int propertyValueColumnIndex = 1)
{
if (dataQuery == null)
{
throw new ArgumentNullException("dataQuery");
}
T propertyValue;
ExcelPropertyValueState state = dataQuery.TryGetPropertyValue <T>(propertyName, out propertyValue, dataAdvice, propertyValueColumnIndex);
if (state == ExcelPropertyValueState.ProperProperty)
{
if (trySetPropertyValue(propertyValue) == false)
{
throw new ArgumentException("Invalid data for property '" + propertyName + "'" + GetFormatedDataQueryName(dataQuery) + ".");
}
}
else if (state == ExcelPropertyValueState.NoValidValue)
{
throw new ArgumentException("Invalid data for property '" + propertyName + "'" + GetFormatedDataQueryName(dataQuery) + ".");
}
}
/// <summary>Sets an optional property value, i.e. if a specific property value is available the value will be used
/// to change the state of a specific object, otherwise the standard value will be use.
/// </summary>
/// <typeparam name="TEnum">The type of the value which is assumed to be a enumeration.</typeparam>
/// <param name="dataQuery">The <see cref="IExcelDataQuery"/> object.</param>
/// <param name="propertyName">The name of the property.</param>
/// <param name="trySetPropertyValue">A delegate which is used to set the value of the property with respect to a specific object, if the property value is available.</param>
/// <param name="enumStringRepresentationUsage">The method how to compute the <see cref="System.String"/> representation of the enumeration <typeparamref name="TEnum"/>.</param>
/// <exception cref="ArgumentNullException">Thrown, if <paramref name="dataQuery"/> is <c>null</c>.</exception>
/// <remarks>Use this method for properties which have some standard value if the user does not
/// enter a specific value, for example the standard exit condition of an optimizer algorithm
/// is the maximal number of iterations.</remarks>
public static void SetOptionalPropertyValue <TEnum>(this IExcelDataQuery dataQuery, string propertyName, Func <TEnum, bool> trySetPropertyValue, EnumStringRepresentationUsage enumStringRepresentationUsage)
where TEnum : struct, IComparable, IConvertible, IFormattable
{
if (dataQuery == null)
{
throw new ArgumentNullException("dataQuery");
}
TEnum propertyValue;
ExcelPropertyValueState state = dataQuery.TryGetPropertyValue <TEnum>(propertyName, out propertyValue, enumStringRepresentationUsage);
if (state == ExcelPropertyValueState.ProperProperty)
{
if (trySetPropertyValue(propertyValue) == false)
{
throw new ArgumentException("Invalid data for property '" + propertyName + "'" + GetFormatedDataQueryName(dataQuery) + ".");
}
}
else if (state == ExcelPropertyValueState.NoValidValue)
{
throw new ArgumentException("Invalid data for property '" + propertyName + "'" + GetFormatedDataQueryName(dataQuery) + ".");
}
}
