Siticone Humanizer Int

The SiticoneHumanizerInt is a production-ready component designed to convert numerical values (integers and decimals) into their written English representation. Unlike simple converters, it offers extensive customization for grammatical rules, currency formatting, ordinal numbers, and historical notation styles (Roman numerals). It includes performance features like caching and asynchronous processing for high-volume applications.

Core Data

The primary properties for inputting numbers and retrieving the converted text.

Property	Type	Description & Usage Example
`Number`	decimal	humanizer.Number = 1234; The number to convert. Changing this property immediately triggers the conversion logic and updates the `Words` property.
`Words`	string	lblResult.Text = humanizer.Words; Read-Only. Returns the converted text representation (e.g., "One thousand two hundred thirty-four").

Text & Grammar

Customize the linguistic style and grammatical rules used during conversion.

Property	Type	Description & Usage Example
`OutputCasing`	Casing	humanizer.OutputCasing = Casing.Title; Controls the capitalization of the result. Options: `Lower`, `Upper`, `Title` (default).
`UseAndInHundreds`	bool	humanizer.UseAndInHundreds = true; If true, adds "and" between hundreds and tens (British style: "One hundred and twenty"). If false, American style ("One hundred twenty").
`UseOrdinal`	bool	humanizer.UseOrdinal = true; Converts numbers to rank/position format (e.g., "First", "Second", "One hundredth").
`UseShortScale`	bool	humanizer.UseShortScale = true; Determines how large numbers are named. `True` = Short Scale (US/UK modern: Billion = 10⁹). `False` = Long Scale (Traditional European: Billion = 10¹²).
`NegativePrefix`	string	humanizer.NegativePrefix = "Negative"; The word used to denote negative numbers (default is "minus").

Special Formats

Options for specific formatting needs like currency and historical numbering.

Property	Type	Description & Usage Example
`EnableCurrency`	bool	humanizer.EnableCurrency = true; Formats the output as a monetary value, prefixing it with the `CurrencySymbol`.
`CurrencySymbol`	string	humanizer.CurrencySymbol = "$"; The symbol to prepend when `EnableCurrency` is true.
`UseRomanNumerals`	bool	humanizer.UseRomanNumerals = true; Converts the integer part of the number to Roman Numerals (e.g., 2023 -> MMXXIII). Supported range: 1 to 3999.

Performance & Caching

Features designed to optimize performance in high-throughput scenarios.

Property	Type	Description & Usage Example
`EnableCaching`	bool	humanizer.EnableCaching = true; Stores previously converted results in an LRU (Least Recently Used) cache to speed up repeated conversions of the same numbers.
`CacheSize`	int	humanizer.CacheSize = 5000; The maximum number of entries to store in the cache. Default is 1000.
`EnableAsync`	bool	humanizer.EnableAsync = true; Enables asynchronous processing capabilities. While standard property setting remains synchronous, this flag configures internal readiness for async operations.
`AsyncTimeout`	int	humanizer.AsyncTimeout = 5000; Timeout in milliseconds for asynchronous operations to prevent hanging.

Localization

Property	Type	Description & Usage Example
`CurrentCulture`	CultureInfo	humanizer.CurrentCulture = new CultureInfo("en-US"); Sets the cultural context for number formatting (e.g., decimal separators). Note: The word generation logic primarily targets English structure but respects number parsing rules of the culture.

Public Methods

Utilities for manual or asynchronous conversion control.

Static & Async Methods

// Static method for quick one-off conversions without instantiating the component
string text = SiticoneHumanizerInt.NumberToWords(
    number: 123, 
    useAndInHundreds: true, 
    negativePrefix: "minus", 
    useOrdinal: false, 
    useShortScale: true
);

// Asynchronous instance method for non-blocking UI updates
string asyncText = await humanizer.NumberToWordsAsync(9999);

// Clear the internal memory cache
humanizer.ClearCache();

Events

Hooks for reacting to changes and errors.

Event Handling

// Fires whenever the Number property is updated and a new string is generated
humanizer.OnNumbersChanged += (s, e) => 
{
                Console.WriteLine($"Converted {e.Number} to: {e.Words}");
                Console.WriteLine($"Timestamp: {e.Timestamp}");
};

// Fires if an exception occurs (e.g., during async processing)
humanizer.OnError += (s, e) => 
{
                MessageBox.Show($"Error in {e.Operation}: {e.Exception.Message}");
};

// Fires when any configuration property is modified
humanizer.OnSettingsChanged += (s, e) => 
{
                Debug.WriteLine($"Setting {e.PropertyName} changed from {e.OldValue} to {e.NewValue}");
};

Designer & Smart Tags

The component features a rich design-time experience with a comprehensive Smart Tag panel.

Feature Category	Capabilities
`Value Presets`	Quickly set `Number` to common testing values: Zero, Small (42), Hundred, Thousand, Million, Negative.
`Styling Presets`	One-click configuration for common use cases: Formal Style: "Negative" prefix, "And" in hundreds, Title case. Casual Style: "Minus", no "And", Lowercase. Ordinal Style: Enables ordinal conversion. Currency Style: Enables currency mode with symbol. Roman Style: Switches to Roman numerals.
`Actions`	Copy Result: Copies the current `Words` text to clipboard. Show Sample Conversions: Displays a message box with the current settings applied to a variety of test numbers. Copy/Paste Settings: Transfer configuration between components.

Detailed Usage Examples

Example 1: Check Writing (Currency Mode)

Format a number for printing on a bank check.

C# - Check Printing

private void PrintCheckAmount(decimal amount)
{
    humanizer.Number = amount;
    humanizer.EnableCurrency = true;
    humanizer.CurrencySymbol = "Dollars"; // Or symbol like "$"
    humanizer.UseAndInHundreds = true;
    humanizer.OutputCasing = Casing.Title;
    
                // Output Example (1250.50): "$ One Thousand Two Hundred and Fifty point Five Zero"
    lblCheckText.Text = humanizer.Words;
}

Example 2: Ranking Display (Ordinal)

Converting a leaderboard position into text (e.g., 1 -> "First").

C# - Ordinal Ranking

private void UpdateLeaderboard(int rank)
{
    humanizer.Number = rank;
    humanizer.UseOrdinal = true;
    humanizer.OutputCasing = Casing.Title;
    
                // Output Example (21): "Twenty-First"
    lblRank.Text = "You finished in " + humanizer.Words + " place!";
}

Example 3: Copyright Date (Roman Numerals)

Displaying the current year in Roman numerals for a footer.

C# - Roman Numerals

private void SetFooterDate()
{
    humanizer.Number = DateTime.Now.Year;
    humanizer.UseRomanNumerals = true;
    
                // Output Example (2023): "MMXXIII"
    lblCopyright.Text = $"© {humanizer.Words} MyCompany Inc.";
}