Merge pull request #42 from xin9le/feature/v2-readme

README for v2

README.md

@@ -6,8 +6,7 @@ FastEnum is **extremely fast** enum utilities for C#/.NET. It's much faster than
 
 
 # Performance
-
-![Benchmark](https://github.com/user-attachments/assets/134afde8-93d0-4c10-8a80-a999ff31b7da)
+![Benchmark](https://github.com/user-attachments/assets/81755afc-30ad-4e20-9737-fa3031ef52aa)
 
 
 ``` ini
@@ -18,9 +17,6 @@ BenchmarkDotNet v0.14.0, Windows 11 (10.0.22621.4037/22H2/2022Update/SunValley2)
   Job-CYQAVK : .NET 8.0.8 (8.0.824.36612), X64 RyuJIT AVX2
 ```
 
-> [!NOTE]
-> At present, FastEnum doesn't generate source code at compile time. We understand that leveraging Roslyn's Source Generator functionality could further accelerate performance, and thus our current implementation is not theoretically the "fastest" possible. We are positively considering the introduction of Source Generator in the future. However, as we aim to maintain a library that is both user-friendly and easily comprehensible, we may need to wait for future enhancements in C#'s expressiveness. We appreciate your understanding in this matter.
-
 
 
 # Support Platform
@@ -35,7 +31,6 @@ BenchmarkDotNet v0.14.0, Windows 11 (10.0.22621.4037/22H2/2022Update/SunValley2)
 
 
 # How to use
-
 This library super easy to use like `System.Enum` that is standard of .NET. Look below:
 
 ```cs
@@ -64,13 +59,27 @@ As you can see, the replacement from `System.Enum` is very easy. You never confu
 
 
 
-# More features
+# Source code generation
+FastEnum is fundamentally implemented based on caching enum metadata upon its initial invocation. This approach alone achieves speeds that significantly surpass those of standard .NET, making it the optimal choice for the majority of users. Nevertheless, we acknowledge the existence of mission-critical scenarios where the ultimate pursuit of speed is paramount. To address such cases, we have introduced an API in v2 that leverages source code generation to achieve even higher performance.
 
+```cs
+[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);
+```
+
+
+
+# More features
 There are some functions that are often used for enum, and you can be used more conveniently by including them together.
 
 
 ## 1. Gets pairwised member information
-
 Sometimes you want name / value pair of enum. `Member<TEnum>` can be used under such cases. Of course supports [deconstruction](https://docs.microsoft.com/en-us/dotnet/csharp/deconstruct) feature. `FieldInfo` is also included, so please use it for reflection code.
 
 
@@ -89,7 +98,6 @@ var (name, value) = member;  // Supports deconstruction
 
 
 ## 2. Gets `EnumMemberAttribute.Value`
-
 I often see the developer using `EnumMemberAttribute` as an alias for field name. So FastEnum provides an API that the value can be quickly obtained from the `EnumMemberAttribute.Value` property.
 
 
@@ -104,9 +112,7 @@ var value = Company.Apple.GetEnumMemberValue();  // Apple, Inc.
 ```
 
 
-
 ## 3. Adds multiple label annotations to a field
-
 Multiple attributes can’t be attached to the same field, since `EnumMemberAttribute` is specified `AllowMultiple = false`. It’s inconvenient and I don’t like it personally, so I often use my own `LabelAttribute` as an alternative. You can use it conveniently as follows, because FastEnum provides this feature.
 
 
@@ -123,13 +129,12 @@ var x2 = Company.Apple.GetLabel(1);  // AAPL
 ```
 
 
-# Limitation
 
+# Limitation
 ## 1. Provides only generics API
 FastEnum provides only generics version method because of performance reason. `System.Enum` provides `System.Type` argument overload, but that’s too slow because of boxing occuration. If you need to use the method that passes `System.Type` type, please use `System.Enum` version.
 
 
-
 ## 2. Can’t parse comma-separated string
 `System.Enum.Parse` can parse like following string. I think that it isn’t well known because it is a specification that exists quietly.
 
@@ -150,19 +155,16 @@ var value = Enum.Parse<Fruits>("Apple, Melon");
 Console.WriteLine((int)value);  // 5
 ```
 
-It seems to be a useful function when performing flag processing, but if tries to add such a comma-separated analysis, the overhead will come out, so cutting this feature off makes speed up. I think that in most cases there is no problem, because this feature is rarely used (at least I have NEVER used for 12 years).
+It seems to be a useful function when performing flag processing, but if tries to add such a comma-separated analysis, the overhead will come out, so cutting this feature off makes speed up. I think that in most cases there is no problem, because this feature is rarely used (at least I have NEVER used for 16 years).
 
 
 
 # Why fast ?
-
-As you might expect, it’s because cached internally. It takes the approach of **Static Type Caching**, so the reading cost is **almost zero**. Based on this, I use techniques for avoiding allocation, and create specialized dictionary for specific key internally.
-
+As you might expect, it’s because cached internally. It takes the approach of Static Type Caching, so the reading cost is almost zero. Based on this, I use techniques for avoiding allocation, and create specialized dictionary for specific key internally. Furthermore, the overwhelming speed is achieved by combining the latest language features of C# with optimized code output through source code generation.
 
 
 
 # Installation
-
 Getting started from downloading [NuGet](https://www.nuget.org/packages/FastEnum) package.
 
 ```
@@ -172,10 +174,8 @@ dotnet add package FastEnum
 
 
 # License
-
 This library is provided under [MIT License](http://opensource.org/licenses/MIT).
 
 
 # Author
-
 Takaaki Suzuki (a.k.a [@xin9le](https://twitter.com/xin9le)) is software developer in Japan who awarded Microsoft MVP for Developer Technologies (C#) since July 2012.