DOCSEARCHbyAlgolia
Submit Docs

FastEnum Documentation

repository·main·Indexed 19 days ago

https://github.com/xin9le/fastenum

A zero-allocation, high-performance enum utility library for C#/.NET designed as a replacement for System.Enum. FastEnum utilizes internal caching and optional source code generation to provide fast implementations of GetValues, GetNames, Parse, and ToString. It supports .NET 8.0+ (v2.0.8+) and legacy platforms via v1.8.0. Key features include the ToMember() extension, EnumMemberAttribute value retrieval, and custom label support.

Tokens
1.4K
Snippets
6
Records
8
Agent score
18%

What's inside FastEnum

  1. Optimize performance with Source Code Generation

    main

    For mission-critical scenarios where maximum speed is required, FastEnum v2 offers a source code generation API. This avoids the overhead of internal caching by generating specialized code at compile time.

    To use it:

    1. Annotate your target enum type with [FastEnum<TEnum>].
    2. Define a partial class to act as the placeholder for the generated code.
    3. Pass the placeholder class as a generic argument to the FastEnum methods.

    Supported methods with source generation:

    • FastEnum.ToString<TEnum, TBooster>(TEnum value)
    • FastEnum.IsDefined<TEnum, TBooster>(TEnum value)
    • FastEnum.Parse<TEnum, TBooster>(string value)
    • FastEnum.TryParse<TEnum, TBooster>(string value, out TEnum result)
    [FastEnum<HttpStatusCode>]  // Annotate target enum type
partial class HttpStatusCodeBooster  // Placeholder for source code generation
{ }

var x1 = FastEnum.ToString<HttpStatusCode, HttpStatusCodeBooster>(HttpStatusCode.OK);
var x2 = FastEnum.IsDefined<HttpStatusCode, HttpStatusCodeBooster>(HttpStatusCode.OK);
var x3 = FastEnum.Parse<HttpStatusCode, HttpStatusCodeBooster>("OK");
var x4 = FastEnum.TryParse<HttpStatusCode, HttpStatusCodeBooster>("OK", out var value);

  2. Limitations of FastEnum

    main

    When using FastEnum, be aware of the following constraints:

    1. Generics Only: FastEnum provides only generic API versions (e.g., Parse<T>) to avoid the performance overhead of boxing caused by System.Type arguments. If you must pass a System.Type object, use System.Enum instead.
    2. No Comma-Separated Parsing: Unlike System.Enum.Parse, FastEnum does not support parsing comma-separated strings (e.g., "Apple, Melon" for [Flags] enums). This limitation is intentional to maintain maximum parsing speed.

  3. Use FastEnum as a drop-in replacement for System.Enum

    main

    FastEnum provides a generics-based API that is designed to be used similarly to System.Enum. It achieves zero allocation and significantly higher performance by caching enum metadata internally.

    Common replacement methods include:

    • FastEnum.GetValues<TEnum>()
    • FastEnum.GetNames<TEnum>()
    • FastEnum.GetName(TEnum value)
    • TEnum.FastToString()
    • FastEnum.IsDefined(TEnum value)
    • FastEnum.Parse<TEnum>(string value)
    • FastEnum.TryParse<TEnum>(string value, out TEnum result)
    //--- FastEnum
var values = FastEnum.GetValues<Fruits>();
var names = FastEnum.GetNames<Fruits>();
var name = FastEnum.GetName(Fruits.Apple);
var toString = Fruits.Apple.FastToString();
var defined = FastEnum.IsDefined(Fruits.Apple);
var parse = FastEnum.Parse<Fruits>("Apple");
var tryParse = FastEnum.TryParse<Fruits>("Apple", out var value);

  5. Retrieve EnumMemberAttribute.Value using GetEnumMemberValue()

    main

    FastEnum provides a convenient way to quickly access the Value property of the [EnumMember] attribute, which is often used as an alias for enum field names.

    enum Company
{
    [EnumMember(Value = "Apple, Inc.")]
    Apple = 0,
}

var value = Company.Apple.GetEnumMemberValue(); // Returns "Apple, Inc."
    enum Company
{
    [EnumMember(Value = "Apple, Inc.")]
    Apple = 0,
}

var value = Company.Apple.GetEnumMemberValue();  // Apple, Inc.

  6. Get pairwised member information with ToMember()

    main

    If you need both the name and the value of an enum member simultaneously, use the ToMember() extension method. It returns a Member<TEnum> object which supports C# deconstruction and provides access to the FieldInfo for reflection purposes.

    var member = Fruits.Apple.ToMember()!;
var (name, value) = member; // Deconstruction
    var member = Fruits.Apple.ToMember()!;
var (name, value) = member;  // Supports deconstruction

  7. Retrieve custom label annotations using GetLabel()

    main

    Since EnumMemberAttribute does not allow multiple instances on a single field, you can use custom attributes (e.g., [Label]) to attach multiple labels. FastEnum provides GetLabel() to retrieve these.

    enum Company
{
    [Label("Apple, Inc.")]
    [Label("AAPL", 1)]
    Apple = 0,
}

var x1 = Company.Apple.GetLabel();   // "Apple, Inc."
var x2 = Company.Apple.GetLabel(1);  // "AAPL"
    enum Company
{
    [Label("Apple, Inc.")]
    [Label("AAPL", 1)]
    Apple = 0,
}

var x1 = Company.Apple.GetLabel();   // Apple, Inc.
var x2 = Company.Apple.GetLabel(1);  // AAPL

  8. Platform Support and Compatibility

    main
    • Current Version (v2.0.8+): Requires .NET 8.0+.
    • Legacy Versions (v1.8.0): If you need to support older platforms, use version 1.8.0, which supports:
      • .NET Framework 4.6.1+
      • .NET Standard 2.0+
      • .NET 5+