Redpoint.StringEnum 2024.1115.1101

Redpoint.StringEnum

This library provides an API for defining and using string-backed enumeration types. These are useful when used with databases, where storing string values for enumerations improves forward and backward compatibility (unlike storing numeric values).

Defining a string-backed enumeration type

You can create a string-backed enumeration, by defining a class like so:

class Example : StringEnum<Example>
{
    public static readonly StringEnumValue<Example> FirstValue = Create("first-value");

    public static readonly StringEnumValue<Example> SecondValue = Create("second-value");

    public static readonly StringEnumValue<Example> ThirdValue = Create("third-value");

    // ...
}

The string values that represent the enumeration are case-and-byte sensitive (ordinal comparison). You can not create enumeration values from a null string; ArgumentNullException will be thrown if you pass a null value to Create.

Defining additional enumeration values at runtime

There is currently no API for defining additional enumeration values at runtime; the possible enumeration values are lazy-loaded once by looking at the static fields and static properties of the class that inherits from StringEnum<T> (via the T type parameter). Both public and non-public fields/properties are included.

This library is both trim and AOT-compatible, as it uses [DynamicallyAccessedMembers] to ensure the fields and properties of the enumeration type are available at runtime for reflection.

Static usage of values

In most code, you'll simply use the static readonly fields you've defined, such as Example.FirstValue. All instances of the value - even those from parsing - are guaranteed to be reference and value equal.

Parsing known values from strings

To parse a value that is known to be valid from a string, you can use Example.Parse or StringEnumValue<Example>.Parse:

var value = Example.Parse("first-value");
var value2 = StringEnumValue<Example>.Parse("second-value");

If the value is not valid when calling Parse, StringEnumParseException will be thrown. You should use TryParse (see below) if the value is potentially invalid.

If you pass a null value to Parse, ArgumentNullException will be thrown.

Parsing potentially invalid string values

If you're unsure whether a string is a valid enumeration value, you can use Example.TryParse or StringEnumValue<Example>.TryParse:

var isValid = Example.TryParse("...", out var value);
var isValid2 = StringEnumValue<Example>.TryParse("...", out var value2);

If you pass a null value to TryParse, ArgumentNullException will be thrown.

Parsing strings to runtime-based enumeration types

If you don't know the type of the string enumeration you want to parse into at compile time, you can use DynamicStringEnumValue.TryParse to parse any string value into an instance of StringEnumValue<T> by passing the StringEnumValue<T> type as the first parameter, like so:

var type = typeof(StringEnumValue<Example>);
var isValid = DynamicStringEnumValue.TryParse(type, "...", out var value);

You can use DynamicStringEnumValue.IsStringEnumValueType to check if type is a constructed generic type of StringEnumValue<T>. The APIs provided by DynamicStringEnumValue are primarily intended to be used with database serialization and deserialization, where the concrete types of values are not known at the point of deserialization.