# Core Number Conversion

## Overview

The Core Number Conversion feature provides developers with the ability to set a numerical value using the `Number` property and automatically receive its word-based textual representation through the read-only `Words` property. In addition, this feature leverages events—`OnNumbersChanged` for successful conversions and `OnError` for error conditions—to keep the application logic informed about conversion state changes.

***

### Sections

Below are comprehensive documentation sections with tables for clarification, code examples for integration, and detailed usage scenarios.

***

### Key Points

<table><thead><tr><th width="234">Aspect</th><th>Description</th></tr></thead><tbody><tr><td>Numerical Input</td><td>Uses the <code>Number</code> property to set the value to be converted.</td></tr><tr><td>Word Conversion Output</td><td>Retrieves the conversion result from the read-only <code>Words</code> property.</td></tr><tr><td>Event Notification</td><td>Notifies consumers when conversions occur via <code>OnNumbersChanged</code> and handles errors via <code>OnError</code>.</td></tr><tr><td>Range Enforcement</td><td>Enforces valid numerical input ranges based on the supported limits (<code>MinSupportedIntValue</code> and <code>MaxSupportedIntValue</code>).</td></tr></tbody></table>

#### Code Example

```csharp
// Initialize the control
var humanizer = new SiticoneHumanizerInt();

// Subscribe to the conversion and error events
humanizer.OnNumbersChanged += (sender, e) =>
{
    Console.WriteLine($"Conversion Result: {e.Words}");
};

humanizer.OnError += (sender, e) =>
{
    Console.WriteLine($"Error during conversion in operation '{e.Operation}': {e.Exception.Message}");
};

// Set a valid number to trigger conversion
humanizer.Number = 1234;
Console.WriteLine("Converted words: " + humanizer.Words);
```

***

### Best Practices

<table><thead><tr><th width="272">Practice</th><th>Recommendation</th></tr></thead><tbody><tr><td>Range Validation</td><td>Always ensure that the number assigned to the <code>Number</code> property is within the valid range to avoid exceptions.</td></tr><tr><td>Event Handling</td><td>Implement robust error handling by subscribing to the <code>OnError</code> event and ensuring that event handlers execute quickly.</td></tr><tr><td>Synchronous vs Asynchronous</td><td>Use the synchronous conversion for immediate needs and the asynchronous method if performance or UI responsiveness is a concern.</td></tr><tr><td>Property Reassignment</td><td>Be aware that modifying properties like <code>NegativePrefix</code> or style options may force an immediate update to the conversion.</td></tr></tbody></table>

#### Code Example

```csharp
try
{
    // Set a valid number within the range
    humanizer.Number = 500;
}
catch (ArgumentOutOfRangeException ex)
{
    Console.WriteLine("Invalid number: " + ex.Message);
}
```

***

### Common Pitfalls

<table><thead><tr><th width="305">Pitfall</th><th>Explanation</th></tr></thead><tbody><tr><td>Out-of-Range Values</td><td>Assigning values outside the supported range may throw an exception and disrupt the application flow.</td></tr><tr><td>Ignoring Event Subscriptions</td><td>Failing to subscribe to conversion events might leave the application unaware of errors or state changes.</td></tr><tr><td>Overlooking Synchronous Blocking</td><td>Performing conversions synchronously in UI threads can block the UI; consider using asynchronous methods when needed.</td></tr></tbody></table>

#### Code Example

```csharp
// Incorrect: Setting a number outside the supported range
try
{
    humanizer.Number = int.MaxValue + 1m;
}
catch (ArgumentOutOfRangeException ex)
{
    Console.WriteLine("Error: " + ex.Message);
}
```

***

### Usage Scenarios

<table><thead><tr><th width="295">Scenario</th><th>How It Works</th></tr></thead><tbody><tr><td>Standard Conversion</td><td>Set the <code>Number</code> property to obtain the conversion result in the <code>Words</code> property automatically.</td></tr><tr><td>Event-Based Notification</td><td>Use the <code>OnNumbersChanged</code> event to trigger further actions in the application when a number is converted.</td></tr><tr><td>Error Handling During Conversion</td><td>Leverage the <code>OnError</code> event to log or handle exceptions that occur during the conversion process.</td></tr></tbody></table>

#### Code Example

```csharp
// Standard usage scenario: updating a label in a WinForms app
humanizer.OnNumbersChanged += (sender, e) =>
{
    // Assume lblConversionResult is a label on the form
    lblConversionResult.Text = e.Words;
};

// Trigger conversion by setting the Number property
humanizer.Number = 2021;
```

***

### Real Life Usage Scenarios

<table><thead><tr><th width="208">Scenario</th><th>Explanation</th></tr></thead><tbody><tr><td>Financial Application</td><td>Converting numerical amounts into words for printing checks or invoices with proper error notification.</td></tr><tr><td>Educational Software</td><td>Demonstrating number-to-word conversion for teaching basic numerical literacy and language constructs.</td></tr><tr><td>Accessibility Tools</td><td>Providing a textual representation of numerical data to assistive technologies.</td></tr></tbody></table>

#### Code Example

```csharp
// In a financial application, converting a numeric currency value to words for check printing
humanizer.EnableCurrency = true;
humanizer.CurrencySymbol = "$";
humanizer.Number = 1500;
Console.WriteLine("Monetary value in words: " + humanizer.Words);
```

***

### Troubleshooting Tips

<table><thead><tr><th width="254">Tip</th><th>Details</th></tr></thead><tbody><tr><td>Validate Input Range</td><td>Always check that the assigned value is within the allowed range to prevent exceptions.</td></tr><tr><td>Review Event Handler Logic</td><td>Ensure that event handlers for <code>OnNumbersChanged</code> and <code>OnError</code> execute efficiently and do not block the UI thread.</td></tr><tr><td>Asynchronous Operations</td><td>When using asynchronous conversions, verify that the <code>AsyncTimeout</code> is set appropriately and that cancellation tokens are managed.</td></tr><tr><td>Debug Logging</td><td>Use logging within event handlers to capture detailed conversion data and exceptions for debugging purposes.</td></tr></tbody></table>

#### Code Example

```csharp
// Example: Logging within the OnError event handler
humanizer.OnError += (sender, e) =>
{
    // Log error details for debugging purposes
    Debug.WriteLine($"Error in operation {e.Operation}: {e.Exception}");
};
```

***

### Review

<table><thead><tr><th width="236">Aspect</th><th>Consideration</th></tr></thead><tbody><tr><td>Functional Completeness</td><td>The Core Number Conversion feature covers numerical input, conversion, and event-based notification effectively.</td></tr><tr><td>Ease of Integration</td><td>Simple property setting and event subscription make it easy for developers to integrate this feature into WinForms apps.</td></tr><tr><td>Extensibility</td><td>Future enhancements (e.g., additional cultures or conversion formats) can be added without disrupting current functionality.</td></tr></tbody></table>

***

### Summary

<table><thead><tr><th width="270">Summary Point</th><th>Description</th></tr></thead><tbody><tr><td>Core Conversion Functionality</td><td>Provides conversion from numerical values to words using the <code>Number</code> and <code>Words</code> properties.</td></tr><tr><td>Event-Driven Notifications</td><td>Notifies applications of successful conversions and errors through the <code>OnNumbersChanged</code> and <code>OnError</code> events.</td></tr><tr><td>Developer-Friendly</td><td>Easy to integrate with clear guidelines, code examples, and robust error handling, making it a valuable tool for WinForms apps.</td></tr></tbody></table>

#### Final Integration Example

```csharp
using System;
using SiticoneNetFrameworkUI;

namespace DemoApp
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize the humanizer control
            var humanizer = new SiticoneHumanizerInt();

            // Subscribe to events for conversion notifications and error handling
            humanizer.OnNumbersChanged += (sender, e) =>
            {
                Console.WriteLine($"Number {e.Number} converted to words: {e.Words}");
            };

            humanizer.OnError += (sender, e) =>
            {
                Console.WriteLine($"Error during conversion in {e.Operation}: {e.Exception.Message}");
            };

            // Perform a conversion
            try
            {
                humanizer.Number = 9876;
                Console.WriteLine("Conversion complete. Result: " + humanizer.Words);
            }
            catch (Exception ex)
            {
                Console.WriteLine("An error occurred: " + ex.Message);
            }
        }
    }
}
```

***

This comprehensive documentation should provide developers with all the necessary insights, code examples, and troubleshooting guidelines to effectively integrate and use the Core Number Conversion feature in their .NET WinForms applications.