HumanNumbers.AspNetCore 2.0.2

HumanNumbers

Human-readable numbers for .NET — a governed, high-performance, API-safe formatting engine.

⚡ Quick Start

using HumanNumbers;

1500.ToHuman();        // "1.50K"
1500000.ToHuman();     // "1.50M"

🎯 Why HumanNumbers?

Formatting numbers correctly at scale is deceptively complex. Naive implementations often:

• Break at rounding boundaries: (e.g., 999,499 rounding to 1,000K instead of 1.00M).
• Allocate excessively: Creating intermediate strings in hot telemetry or logging paths.
• Lack consistency: Different services formatting the same data in conflicting ways.

HumanNumbers provides a governed, high-performance platform for number presentation that prioritizes:

• Correctness: Smart suffix promotion logic that handles rounding boundaries gracefully.

  999499m.ToHuman();                                      // "1.00M" (Readable)
  999499m.ToHuman(HumanNumberFormatOptions.StrictPreset); // "999.50K" (Accurate)
  

• Performance: Optimized Span<char>-based paths and zero-allocation parsing.
• Safety: Non-intrusive ASP.NET Core integration that preserves API contracts by default.
• Governance: A central Policy system to ensure consistent formatting across distributed services.

🚀 Comparison: Three Ways to Format

🔢 Core Formatting Engine

Readable vs. Strict Promotion

By default, we prioritize readability. If a number rounds up to the next threshold (e.g., 999,499 to 1.00M), we promote the suffix. For audit-heavy scenarios, use Strict Mode:

999499m.ToHuman();                                      // "1.00M" (Readable Default)
999499m.ToHuman(HumanNumberFormatOptions.StrictPreset); // "999.50K" (Strict Accuracy)

Specialized Units

• Financial: 1234.56m.ToHumanWords(); // "One Thousand Two Hundred..."
• Bytes: 1024L.ToHumanBytes(); // "1.00 KiB" (Supports Binary/Decimal)
• Fractions: 1.5m.ToHumanFraction(32); // "1 16/32"
• Roman: 2024.ToRoman(); // "MMXXIV"

🌍 Internationalization & Global Support

HumanNumbers is built on top of the native .NET CultureInfo system, meaning it automatically respects global numbering rules, separators, and currency symbols out of the box.

Verified Global Outputs (Examples)

Custom Words (Financial I18n)

For non-English support in financial word-formatting (Check Writing), implement the IWordsProvider interface:

public class SpanishWordsProvider : IWordsProvider
{
    public string NegativeWord => "Negativo";
    public string ConjunctionWord => "con";
    public string ToWords(decimal value) => "Mil Doscientos"; 
}

// Usage
1200m.ToHumanWords(provider: new SpanishWordsProvider()); // "Mil Doscientos"

🚀 Modernization & New Features (v2.0.2)

We have significantly hardened and optimized the codebase with robust enterprise-grade features:

• Pluggable Currency Dependency Injection (ICurrencyMappingProvider): Map custom regional or business keys (like "EastAfrica", "AsiaPacific") to ISO currency codes by registering a custom provider to the DI container:

  builder.Services.AddSingleton<ICurrencyMappingProvider, MyCustomMappingProvider>();
  

• O(1) Pre-Cached Currency Lookups: High-latency culture scanning is gone! Currency symbols are fully pre-cached, turning regional scans into O(1) dictionary lookups.
• O(log N) Suffix Lookups: Support for large custom suffix arrays with O(log N) binary search threshold selection, retaining fast linear scanning for standard <= 8 suffix arrays.
• Thread-Safe Option Mutations: Shared options registration utilizes record with-expressions, preventing thread cross-contamination during concurrent executions.
• Circular Reference Protection: Dynamic serialization filter protects APIs from recursion crashes by tracing visited nodes via identity-based reference sets.

🧩 Policy-Driven Formatting (Enterprise Ready)

Define formatting rules once and enforce them across your entire infrastructure. Ensure that APIs, dashboards, and reports share the same magnitude logic and rounding rules.

// Setup central governance
builder.Services.AddHumanNumbersDefaults(options =>
{
    options.AddPolicy("Finance", new HumanNumberFormatOptions
    {
        DecimalPlaces = 2,
        PromotionThreshold = 1.0m // strict mode: 999,499 -> "999.50K"
    });
});

// Apply consistently across services
HumanNumber.Format(value).UsingPolicy("Finance").ToHuman();

🌍 Multi-Culture & Custom Magnitude Examples

The policy system handles unique numbering systems (like 10,000-based scaling) with ease:

builder.Services.AddHumanNumbersDefaults(options =>
{
    // Indian System: Lakhs (10^5) and Crores (10^7)
    options.AddPolicy("Indian", new HumanNumberFormatOptions
    {
        CachedCustomSuffixes = new[] {
            new MagnitudeSuffix(1000m, "K"),
            new MagnitudeSuffix(100_000m, "Lakh"),
            new MagnitudeSuffix(10_000_000m, "Crore")
        },
        Threshold = 1000m,
        DecimalPlaces = 2
    });

    // Chinese System: Wàn (10^4) and Yì (10^8)
    options.AddPolicy("Chinese", new HumanNumberFormatOptions
    {
        CachedCustomSuffixes = new[] {
            new MagnitudeSuffix(10_000m, "Wàn"),
            new MagnitudeSuffix(100_000_000m, "Yì")
        },
        Threshold = 10_000m
    });
});

// Usage
120000m.ToHuman(HumanNumbersConfig.Instance.GetPolicies()["Indian"]); // "1.20 Lakh"
120000m.ToHuman(HumanNumbersConfig.Instance.GetPolicies()["Chinese"]); // "12.00 Wàn"

🚀 Real-World Scenario: Zero-Allocation Telemetry

In high-frequency logging or telemetry, even small string allocations can trigger GC pressure. HumanNumbers allows you to format directly into reusable buffers:

// Reusable buffer (stack or ArrayPool)
Span<char> buffer = stackalloc char[32];

if (largeValue.ToHuman(buffer, out var written))
{
    // Log directly from the span without creating a string
    logger.LogInformation("Metric: {Value}", buffer[..written]);
}

📊 Performance & Engineering Nuance

We benchmark against "Naive" implementations to provide an honest look at the costs of convenience.

🌐 ASP.NET Core: Safe by Default

Many libraries implicitly change JSON output globally, breaking API contracts. HumanNumbers is designed to be non-intrusive.

1. Register Policies

builder.Services.AddHumanNumbersDefaults(options => {
    options.AddPolicy("Compact", new HumanNumberFormatOptions { DecimalPlaces = 1 });
});

2. Selective Serialization

Control exactly what the client sees without breaking your DTOs.

public class AnalyticsDto {
    public decimal RawValue { get; set; } // JSON: 1500000

    [HumanNumber(OutputMode = HumanNumberOutputMode.SerializeAsHuman)]
    public decimal DisplayValue { get; set; } // JSON: "1.50M"
}

3. Explicit Transformations

In Minimal APIs, use HumanOk to trigger the transformation only when intended:

app.MapGet("/stats", () => Results.Extensions.HumanOk(new { Revenue = 1500000 }));

🧠 Design Philosophy

• Predictable Performance: Every feature has a known and stable allocation profile.
• Governance First: Use the Policy system to define "Brand Guidelines" for numbers once, then apply them everywhere.
• Allocation Aware: We leverage Span<char> and ISpanFormattable to ensure that adding "humanity" to your data doesn't sink your GC performance.
• Contract Safety: Your API types remain decimal. We only change the representation during the final serialization step.

🔄 Migration from NumberFormatter

HumanNumbers is the official successor to the legacy NumberFormatter package. It features a modernized API, significantly improved performance (via Span<char>), and a unified policy system.

Key Changes

• Namespace: NumberFormatter → HumanNumbers
• Method Renaming:
  • ToShortString() → ToHuman()
  • ToShortCurrencyString() → ToHumanCurrency()
• Binary Compatibility: A legacy shim is provided in the NumberFormatter namespace (marked as [Obsolete]) to help with a zero-friction transition.

// Legacy (NumberFormatter)
using NumberFormatter;
1500.ToShortString(); 

// Modern (HumanNumbers)
using HumanNumbers;
1500.ToHuman();

📦 Installation

dotnet add package HumanNumbers
dotnet add package HumanNumbers.AspNetCore

🙌 Contributing & License

Licensed under MIT. Contributions are welcome via Issues and Pull Requests.

📈 Appendix: Detailed Benchmarks

Detailed benchmarks below reflect full production runs and may differ slightly from summarized figures above. All results were generated using BenchmarkDotNet v0.14.0 on .NET 10.0 (X64 RyuJIT).

Key Takeaway: While HumanNumbers handles complex thresholds and rounding logic that manual code often misses, it does so with a smaller memory footprint than naive string concatenation approaches.

🔎 Keywords

human-readable numbers, number formatting, suffix formatting, K/M/B formatting, span formatting, zero allocation, .NET performance, telemetry formatting, financial formatting, magnitude formatting.