feat(parser): add fast-path rules for user agent parsing

- Introduce HttpUserAgentFastRules for efficient token matching
- Update HttpUserAgentParser to utilize fast-path rules
- Enhance documentation with examples for public methods
- Add unit tests for new functionality and existing behavior

Author: BenjaminAbt

src/HttpUserAgentParser.AspNetCore/DependencyInjection/HttpUserAgentParserDependencyInjectionOptionsExtensions.cs

@@ -15,6 +15,12 @@ public static class HttpUserAgentParserDependencyInjectionOptionsExtensions
     /// Registers <see cref="HttpUserAgentParserAccessor"/> as <see cref="IHttpUserAgentParserAccessor"/>.
     ///  Requires a registered <see cref="IHttpUserAgentParserProvider"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// IServiceCollection services = new ServiceCollection();
+    /// services.AddHttpUserAgentParser().AddHttpUserAgentParserAccessor();
+    /// </code>
+    /// </example>
     public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentParserAccessor(
         this HttpUserAgentParserDependencyInjectionOptions options)
     {

src/HttpUserAgentParser.AspNetCore/HttpContextExtensions.cs

@@ -13,6 +13,11 @@ public static class HttpContextExtensions
     /// <summary>
     /// Returns the User-Agent header value
     /// </summary>
+    /// <example>
+    /// <code>
+    /// string? userAgent = httpContext.GetUserAgentString();
+    /// </code>
+    /// </example>
     public static string? GetUserAgentString(this HttpContext httpContext)
     {
         if (httpContext.Request.Headers.TryGetValue("User-Agent", out StringValues value))

src/HttpUserAgentParser.AspNetCore/HttpUserAgentParserAccessor.cs

@@ -19,12 +19,22 @@ public class HttpUserAgentParserAccessor(IHttpUserAgentParserProvider httpUserAg
     /// <summary>
     /// User agent of current <see cref="IHttpContextAccessor"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// string? userAgent = accessor.GetHttpContextUserAgent(httpContext);
+    /// </code>
+    /// </example>
     public string? GetHttpContextUserAgent(HttpContext httpContext)
         => httpContext.GetUserAgentString();
 
     /// <summary>
     /// Returns current <see cref="HttpUserAgentInformation"/> of current <see cref="IHttpContextAccessor"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// HttpUserAgentInformation? info = accessor.Get(httpContext);
+    /// </code>
+    /// </example>
     public HttpUserAgentInformation? Get(HttpContext httpContext)
     {
         string? httpUserAgent = GetHttpContextUserAgent(httpContext);

src/HttpUserAgentParser.MemoryCache/DependencyInjection/HttpUserAgentParserMemoryCacheServiceCollectionExtensions.cs

@@ -14,6 +14,16 @@ public static class HttpUserAgentParserMemoryCacheServiceCollectionExtensions
     /// <summary>
     /// Registers <see cref="HttpUserAgentParserCachedProvider"/> as singleton to <see cref="IHttpUserAgentParserProvider"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// IServiceCollection services = new ServiceCollection();
+    /// services.AddHttpUserAgentMemoryCachedParser(options =>
+    /// {
+    ///     options.CacheOptions.SizeLimit = 512;
+    ///     options.CacheEntryOptions.SlidingExpiration = TimeSpan.FromHours(6);
+    /// });
+    /// </code>
+    /// </example>
     public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentMemoryCachedParser(
         this IServiceCollection services, Action<HttpUserAgentParserMemoryCachedProviderOptions>? options = null)
     {

src/HttpUserAgentParser.MemoryCache/HttpUserAgentParserMemoryCachedProviderOptions.cs

@@ -26,18 +26,36 @@ public class HttpUserAgentParserMemoryCachedProviderOptions
     /// <summary>
     /// Creates a new instance of <see cref="HttpUserAgentParserMemoryCachedProviderOptions"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// var options = new HttpUserAgentParserMemoryCachedProviderOptions(new MemoryCacheOptions { SizeLimit = 512 });
+    /// </code>
+    /// </example>
     public HttpUserAgentParserMemoryCachedProviderOptions(MemoryCacheOptions cacheOptions)
         : this(cacheOptions, null) { }
 
     /// <summary>
     /// Creates a new instance of <see cref="HttpUserAgentParserMemoryCachedProviderOptions"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// var options = new HttpUserAgentParserMemoryCachedProviderOptions(
+    ///     new MemoryCacheEntryOptions { SlidingExpiration = TimeSpan.FromHours(6) });
+    /// </code>
+    /// </example>
     public HttpUserAgentParserMemoryCachedProviderOptions(MemoryCacheEntryOptions cacheEntryOptions)
         : this(null, cacheEntryOptions) { }
 
     /// <summary>
     /// Creates a new instance of <see cref="HttpUserAgentParserMemoryCachedProviderOptions"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// var options = new HttpUserAgentParserMemoryCachedProviderOptions(
+    ///     new MemoryCacheOptions { SizeLimit = 512 },
+    ///     new MemoryCacheEntryOptions { SlidingExpiration = TimeSpan.FromHours(6) });
+    /// </code>
+    /// </example>
     public HttpUserAgentParserMemoryCachedProviderOptions(
         MemoryCacheOptions? cacheOptions = null, MemoryCacheEntryOptions? cacheEntryOptions = null)
     {

src/HttpUserAgentParser/DependencyInjection/HttpUserAgentParserServiceCollectionExtensions.cs

@@ -13,6 +13,12 @@ public static class HttpUserAgentParserServiceCollectionExtensions
     /// <summary>
     /// Registers <see cref="HttpUserAgentParserDefaultProvider"/> as singleton to <see cref="IHttpUserAgentParserProvider"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// IServiceCollection services = new ServiceCollection();
+    /// services.AddHttpUserAgentParser();
+    /// </code>
+    /// </example>
     public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentParser(
         this IServiceCollection services)
     {
@@ -22,6 +28,12 @@ public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentPars
     /// <summary>
     /// Registers <see cref="HttpUserAgentParserCachedProvider"/> as singleton to <see cref="IHttpUserAgentParserProvider"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// IServiceCollection services = new ServiceCollection();
+    /// services.AddHttpUserAgentCachedParser();
+    /// </code>
+    /// </example>
     public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentCachedParser(
         this IServiceCollection services)
     {
@@ -31,6 +43,12 @@ public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentCach
     /// <summary>
     /// Registers <typeparam name="TProvider"/> as singleton to <see cref="IHttpUserAgentParserProvider"/>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// IServiceCollection services = new ServiceCollection();
+    /// services.AddHttpUserAgentParser&lt;HttpUserAgentParserDefaultProvider&gt;();
+    /// </code>
+    /// </example>
     public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentParser<TProvider>(
         this IServiceCollection services) where TProvider : class, IHttpUserAgentParserProvider
     {