/// <summary>
/// 检索指定枚举类型中常数描述和值的集合。如果不存在描述，则使用其名称。
/// </summary>
/// <param name="enumType">枚举类型。</param>
/// <returns>一个 <see cref="TextValuePairCollection"/> 实例，其中包含
/// <paramref name="enumType"/> 中实例的描述和值。该集合的元素按枚举的二进制值排序。</returns>
/// <exception cref="ArgumentNullException"><paramref name="enumType"/> 为 <c>null</c>。</exception>
/// <exception cref="ArgumentException"><paramref name="enumType"/> 不是 <see cref="Enum"/>。</exception>
/// <overloads>
/// <summary>
/// 检索指定枚举类型中常数描述和值的集合。
/// </summary>
/// </overloads>
public static TextValuePairCollection GetDescValues(Type enumType)
{
CommonExceptions.CheckArgumentNull(enumType, "enumType");
Contract.Ensures(Contract.Result <TextValuePairCollection>() != null);
CommonExceptions.CheckEnumType(enumType, "enumType");
return(GetTextValues(enumType, true));
}
/// <summary>
/// 检索指定枚举类型中常数名称和值的集合。
/// </summary>
/// <param name="enumType">枚举类型。</param>
/// <returns>一个 <see cref="TextValuePairCollection"/> 实例，其中包含
/// <paramref name="enumType"/> 中实例的名称和值。该集合的元素按枚举的二进制值排序。</returns>
/// <exception cref="ArgumentNullException"><paramref name="enumType"/> 为 <c>null</c>。</exception>
/// <exception cref="ArgumentException"><paramref name="enumType"/> 不是 <see cref="Enum"/>。</exception>
/// <overloads>
/// <summary>
/// 检索指定枚举类型中常数名称和值的集合。
/// </summary>
/// </overloads>
public static TextValuePairCollection GetNameValues(Type enumType)
{
CommonExceptions.CheckArgumentNull(enumType, nameof(enumType));
Contract.Ensures(Contract.Result <TextValuePairCollection>() != null);
CommonExceptions.CheckEnumType(enumType, nameof(enumType));
return(GetTextValues(enumType, false));
}
/// <summary>
/// 在指定枚举中检索具有指定值的常数的描述。如果不存在描述，则使用其名称。
/// </summary>
/// <param name="enumType">枚举类型。</param>
/// <param name="value">特定枚举常数的值（与 <paramref name="enumType"/> 兼容）。 </param>
/// <returns>一个字符串，其中包含 <paramref name="enumType"/> 中值为 <paramref name="value"/>
/// 的枚举常数的描述；如果没有找到这样的常数，则为 <c>null</c>。</returns>
/// <exception cref="ArgumentNullException"><paramref name="enumType"/> 为 <c>null</c>。</exception>
/// <exception cref="ArgumentException"><paramref name="enumType"/> 不是 <see cref="Enum"/>。</exception>
/// <exception cref="ArgumentNullException"><paramref name="value"/> 为 <c>null</c>。</exception>
/// <exception cref="InvalidCastException"><paramref name="value"/> 不能转换为 <paramref name="enumType"/>。</exception>
/// <remarks>如果多个枚举成员具有相同的基础值，则 <see cref="GetName{TValue}"/>
/// 方法可保证它将返回其中一个枚举成员的描述。但是，它并不保证它将始终返回相同枚举成员的描述。
/// 因此，如果多个枚举成员具有相同的值，应用程序代码决不应依赖于返回特定成员描述的方法。</remarks>
/// <overloads>
/// <summary>
/// 在指定枚举中检索具有指定值的常数的描述。如果不存在描述，则使用其名称。
/// </summary>
/// </overloads>
public static string GetDescription(Type enumType, object value)
{
CommonExceptions.CheckArgumentNull(enumType, "enumType");
CommonExceptions.CheckArgumentNull(value, "value");
Contract.EndContractBlock();
CommonExceptions.CheckEnumType(enumType, "enumType");
ulong ulValue = ToUInt64(value);
EnumCache cache = GetEnumCache(enumType);
int idx = Array.BinarySearch(cache.Values, ulValue);
return(idx >= 0 ? cache.Descriptions[idx] : null);
}
/// <summary>
/// 在指定枚举中检索具有指定值的常数的名称。
/// </summary>
/// <typeparam name="TValue">常数的类型。</typeparam>
/// <param name="enumType">枚举类型。</param>
/// <param name="value">特定枚举常数的值（与 <paramref name="enumType"/> 兼容）。</param>
/// <returns>一个字符串，其中包含 <paramref name="enumType"/> 中值为 <paramref name="value"/>
/// 的枚举常数的名称；如果没有找到这样的常数，则为 <c>null</c>。</returns>
/// <exception cref="ArgumentNullException"><paramref name="enumType"/> 为 <c>null</c>。</exception>
/// <exception cref="ArgumentException"><paramref name="enumType"/> 不是 <see cref="Enum"/>。</exception>
/// <exception cref="ArgumentNullException"><paramref name="value"/> 为 <c>null</c>。</exception>
/// <exception cref="InvalidCastException"><paramref name="value"/> 不能转换为 <paramref name="enumType"/>。</exception>
/// <remarks>如果多个枚举成员具有相同的基础值，则 <see cref="GetName{TValue}"/>
/// 方法可保证它将返回其中一个枚举成员的名称。但是，它并不保证它将始终返回相同枚举成员的名称。
/// 因此，如果多个枚举成员具有相同的值，应用程序代码决不应依赖于返回特定成员名称的方法。</remarks>
public static string GetName <TValue>(Type enumType, TValue value)
{
CommonExceptions.CheckArgumentNull(enumType, nameof(enumType));
CommonExceptions.CheckArgumentNull(value, nameof(value));
Contract.EndContractBlock();
CommonExceptions.CheckEnumType(enumType, nameof(enumType));
var ulValue = ToUInt64(value);
var cache = GetEnumCache(enumType);
var idx = Array.BinarySearch(cache.Values, ulValue);
return(idx >= 0 ? cache.Names[idx] : default(string));
}
/// <summary>
/// 将一个或多个枚举常数的名称、描述或数字值的字符串表示转换成等效的枚举对象。
/// 一个参数指定该操作是否区分大小写。
/// </summary>
/// <typeparam name="TEnum">要获取枚举对象的枚举类型。</typeparam>
/// <param name="value">包含要转换的值或名称的字符串。</param>
/// <param name="ignoreCase"><c>true</c> 为忽略大小写；<c>false</c> 为考虑大小写。</param>
/// <returns><typeparamref name="TEnum"/> 类型的对象，其值由 <paramref name="value"/> 表示。</returns>
/// <exception cref="ArgumentNullException"><paramref name="value"/> 为 <c>null</c>。</exception>
/// <exception cref="ArgumentException"><typeparamref name="TEnum"/> 不是 <see cref="Enum"/>。</exception>
/// <exception cref="ArgumentException"><paramref name="value"/> 是空字符串 ("") 或只包含空白。</exception>
/// <exception cref="ArgumentException"><paramref name="value"/> 是一个名称或描述，但不是为该枚举定义的命名常量之一。
/// </exception>
/// <exception cref="OverflowException"><paramref name="value"/> 超出 <typeparamref name="TEnum"/>
/// 基础类型的范围。</exception>
public static TEnum ParseEx <TEnum>(string value, bool ignoreCase)
{
CommonExceptions.CheckArgumentNull(value, "value");
Contract.EndContractBlock();
CommonExceptions.CheckEnumType(typeof(TEnum));
ulong ulValue = ParseToULong(typeof(TEnum), value, ignoreCase);
if (typeof(TEnum).IsUnsigned())
{
return(Convert.ChangeType <ulong, TEnum>(ulValue));
}
return(Convert.ChangeType <long, TEnum>((long)ulValue));
}
/// <summary>
/// 将一个或多个枚举常数的名称、描述或数字值的字符串表示转换成等效的枚举对象。
/// 一个参数指定该操作是否区分大小写。
/// </summary>
/// <param name="enumType">枚举类型。</param>
/// <param name="value">包含要转换的值或名称的字符串。</param>
/// <param name="ignoreCase"><c>true</c> 为忽略大小写；<c>false</c> 为考虑大小写。</param>
/// <returns><paramref name="enumType"/> 类型的对象，其值由 <paramref name="value"/> 表示。</returns>
/// <exception cref="ArgumentNullException"><paramref name="enumType"/> 为 <c>null</c>。</exception>
/// <exception cref="ArgumentException"><paramref name="enumType"/> 不是 <see cref="Enum"/>。</exception>
/// <exception cref="ArgumentNullException"><paramref name="value"/> 为 <c>null</c>。</exception>
/// <exception cref="ArgumentException"><paramref name="value"/> 是空字符串 ("") 或只包含空白。</exception>
/// <exception cref="ArgumentException"><paramref name="value"/> 是一个名称或描述，但不是为该枚举定义的命名常量之一。
/// </exception>
/// <exception cref="OverflowException"><paramref name="value"/> 超出 <paramref name="enumType"/>
/// 基础类型的范围。</exception>
public static object ParseEx(Type enumType, string value, bool ignoreCase)
{
CommonExceptions.CheckArgumentNull(enumType, "enumType");
CommonExceptions.CheckArgumentNull(value, "value");
Contract.EndContractBlock();
CommonExceptions.CheckEnumType(enumType, "enumType");
ulong ulValue = ParseToULong(enumType, value, ignoreCase);
if (enumType.IsUnsigned())
{
return(Convert.ChangeType(ulValue, enumType));
}
return(Convert.ChangeType((long)ulValue, enumType));
}
/// <summary>
/// 将一个或多个枚举常数的名称、描述或数字值的字符串表示转换成等效的枚举对象。
/// </summary>
/// <param name="enumType">枚举类型。</param>
/// <param name="value">包含要转换的值或名称的字符串。</param>
/// <returns><paramref name="enumType"/> 类型的对象，其值由 <paramref name="value"/> 表示。</returns>
/// <exception cref="ArgumentNullException"><paramref name="enumType"/> 为 <c>null</c>。</exception>
/// <exception cref="ArgumentException"><paramref name="enumType"/> 不是 <see cref="Enum"/>。</exception>
/// <exception cref="ArgumentNullException"><paramref name="value"/> 为 <c>null</c>。</exception>
/// <exception cref="ArgumentException"><paramref name="value"/> 是空字符串 ("") 或只包含空白。</exception>
/// <exception cref="ArgumentException"><paramref name="value"/> 是一个名称或描述，但不是为该枚举定义的命名常量之一。
/// </exception>
/// <exception cref="OverflowException"><paramref name="value"/> 超出 <paramref name="enumType"/>
/// 基础类型的范围。</exception>
/// <overloads>
/// <summary>
/// 将一个或多个枚举常数的名称、描述或数字值的字符串表示转换成等效的枚举对象。
/// </summary>
/// </overloads>
public static object ParseEx(Type enumType, string value)
{
CommonExceptions.CheckArgumentNull(enumType, nameof(enumType));
CommonExceptions.CheckArgumentNull(value, nameof(value));
Contract.EndContractBlock();
CommonExceptions.CheckEnumType(enumType, nameof(enumType));
var ulValue = ParseToULong(enumType, value, false);
if (enumType.IsUnsigned())
{
return(Convert.ChangeType(ulValue, enumType));
}
return(Convert.ChangeType((long)ulValue, enumType));
}
/// <summary>
/// 检索指定枚举类型中常数描述和值的集合。如果不存在描述，则使用其名称。
/// </summary>
/// <typeparam name="TEnum">枚举类型。</typeparam>
/// <returns>一个 <see cref="TextValuePairCollection"/> 实例，其中包含
/// <typeparamref name="TEnum"/> 中实例的名称和值。该集合的元素按枚举的二进制值排序。</returns>
/// <exception cref="ArgumentException"><typeparamref name="TEnum"/> 不是 <see cref="Enum"/>。</exception>
public static TextValuePairCollection <TEnum> GetDescValues <TEnum>()
{
Contract.Ensures(Contract.Result <TextValuePairCollection <TEnum> >() != null);
CommonExceptions.CheckEnumType(typeof(TEnum));
return(GetTextValues <TEnum>(true));
}
