Core Number Conversion

A feature that converts numerical values into their corresponding word representations and notifies consumers via events when conversions occur or errors are encountered.

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

Aspect	Description
Numerical Input	Uses the Number property to set the value to be converted.
Word Conversion Output	Retrieves the conversion result from the read-only Words property.
Event Notification	Notifies consumers when conversions occur via OnNumbersChanged and handles errors via OnError.
Range Enforcement	Enforces valid numerical input ranges based on the supported limits (MinSupportedIntValue and MaxSupportedIntValue).

Code Example

// 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

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

Code Example

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

---

Common Pitfalls

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

Code Example

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

---

Usage Scenarios

Scenario	How It Works
Standard Conversion	Set the Number property to obtain the conversion result in the Words property automatically.
Event-Based Notification	Use the OnNumbersChanged event to trigger further actions in the application when a number is converted.
Error Handling During Conversion	Leverage the OnError event to log or handle exceptions that occur during the conversion process.

Code Example

// 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

Scenario	Explanation
Financial Application	Converting numerical amounts into words for printing checks or invoices with proper error notification.
Educational Software	Demonstrating number-to-word conversion for teaching basic numerical literacy and language constructs.
Accessibility Tools	Providing a textual representation of numerical data to assistive technologies.

Code Example

// 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

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

Code Example

// 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

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

---

Summary

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

Final Integration Example

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.