Core Number Conversion

This feature converts numeric values into their word representation, automatically updating when the value is changed.

Overview

The Core Number Conversion feature is the foundation of the control. It allows developers to set a numeric value through the Value property and automatically converts it into its corresponding word representation, which is accessible via the Words property. This conversion occurs synchronously as well as asynchronously using methods like ConvertToWordsAsync and ConvertToWordsWithHashAsync.

---

Key Points

Key Point	Description
Value property triggers conversion	Changing the Value property automatically triggers the conversion to words.
Real-time update via event	The OnNumbersChanged event notifies subscribers whenever the number or its word representation changes.
Asynchronous conversion available	Asynchronous methods provide non-blocking conversion functionality and support cancellation tokens.
Read-only Words property	The Words property is read-only and reflects the current word representation of the number.

---

Best Practices

Best Practice	Description
Validate number range before setting Value	Ensure the numeric value is within expected limits to avoid performance issues or conversion errors.
Use asynchronous methods for UI responsiveness	Utilize ConvertToWordsAsync or ConvertToWordsWithHashAsync in UI threads to keep the application responsive.
Subscribe to OnNumbersChanged for dynamic updates	Use the OnNumbersChanged event to refresh UI elements or trigger further processing when conversions occur.
Cache conversion results if reusing values	Enable caching by setting EnableCaching to true to optimize performance when the same number is converted repeatedly.

---

Common Pitfalls

Pitfall	Description
Ignoring cancellation tokens in async methods	Failing to pass or check cancellation tokens may lead to unresponsive UI or long-running tasks.
Overwriting the Value property without event handling	Not subscribing to OnNumbersChanged may lead to missing updates in UI elements that rely on word conversion.
Misusing the synchronous conversion	Using synchronous conversion on the UI thread can cause application hangs if the conversion process is heavy.

---

Usage Scenarios

Scenario	Description
Real-time conversion in data entry screens	As a user enters a number, the control updates its word representation in real-time, providing immediate feedback.
Batch processing in background tasks	Convert large sets of numbers asynchronously in a background service without blocking the main thread.
Data binding in WinForms applications	Bind the Words property to UI labels to automatically reflect changes when the numeric value is updated.

---

Real Life Usage Scenarios

Scenario	Description
Financial applications	Displaying the check amount in words when processing payments or generating reports.
Educational software	Converting numbers to words for language learning or math tutoring applications.
Accessibility features	Providing a textual description of numeric data for visually impaired users in enterprise applications.

---

Troubleshooting Tips

Issue	Possible Cause	Recommended Action
Words property not updating immediately	The Value property may have been updated without subscribing to the OnNumbersChanged event.	Ensure that the OnNumbersChanged event is properly handled in the consuming application.
Conversion takes too long on UI thread	Synchronous conversion on a heavy numeric value might be blocking the UI thread.	Use asynchronous methods (ConvertToWordsAsync) to offload work from the UI thread.
Incorrect word representation returned	Custom formatting settings (e.g., custom separators or culture) might be affecting the conversion result.	Review and adjust formatting properties like CustomSeparator, Culture, and CapitalizeFirst.

---

Code Examples

Example 1: Basic Synchronous Conversion

using SiticoneNetFrameworkUI;

// Create an instance of the control
var humanizer = new SiticoneHumanizerLong();

// Set the numeric value to convert
humanizer.Value = 123;

// Retrieve the word representation
Console.WriteLine("Converted Words: " + humanizer.Words);

// Subscribe to the event to receive updates
humanizer.OnNumbersChanged += (sender, e) =>
{
    Console.WriteLine($"Value changed to: {e.Number}, Words: {e.Words}");
};

Example 2: Asynchronous Conversion with Cancellation

using System;
using System.Threading;
using System.Threading.Tasks;
using SiticoneNetFrameworkUI;

public async Task DemoAsyncConversion()
{
    var humanizer = new SiticoneHumanizerLong();
    CancellationTokenSource cts = new CancellationTokenSource();

    try
    {
        // Perform asynchronous conversion
        string words = await humanizer.ConvertToWordsAsync(456, cts.Token);
        Console.WriteLine("Async Converted Words: " + words);
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine("Conversion was cancelled.");
    }
}

Example 3: Using the OnNumbersChanged Event for UI Updates

using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

public class MainForm : Form
{
    private Label lblWords;
    private SiticoneHumanizerLong humanizer;

    public MainForm()
    {
        lblWords = new Label { Location = new System.Drawing.Point(20, 20), Width = 400 };
        Controls.Add(lblWords);

        humanizer = new SiticoneHumanizerLong();
        humanizer.OnNumbersChanged += Humanizer_OnNumbersChanged;

        // Simulate a value update
        humanizer.Value = 789;
    }

    private void Humanizer_OnNumbersChanged(object sender, NumberChangedEventArgs e)
    {
        // Update UI label with new words
        lblWords.Text = "Converted: " + e.Words;
    }
}

---

Review

Aspect	Review Comments
Simplicity of integration	The control’s core conversion functionality is straightforward, using properties and events for real-time updates.
Flexibility	Provides both synchronous and asynchronous methods to cater to different application needs and performance considerations.
Extensibility	Easily integrates into WinForms applications with clear event notifications and property-based triggers.

---

Summary

Summary Statement	Description
Core Number Conversion provides a robust and flexible solution	The feature converts numeric values into their word representations seamlessly, supports both synchronous and asynchronous conversion, and integrates easily into UI workflows with event notifications and caching for performance.

---

Additional Useful Sections

Integration Checklist

Checklist Item	Status/Notes
Verify Value property usage	Ensure the numeric input is correctly set to trigger conversion.
Handle OnNumbersChanged event properly	Subscribe to update the UI or trigger further processing when conversions occur.
Use asynchronous conversion for heavy operations	Leverage ConvertToWordsAsync to prevent UI blocking in intensive applications.
Review caching configuration	Enable and configure caching (EnableCaching, MaxCacheSize) to optimize performance when needed.

FAQ

Question	Answer
How do I trigger a conversion?	Set the Value property, and the conversion will automatically occur, updating the Words property.
What if I need to update the conversion on the fly?	Subscribe to the OnNumbersChanged event to receive real-time updates when the conversion takes place.
Can I cancel an ongoing asynchronous conversion?	Yes, pass a cancellation token to the asynchronous methods (ConvertToWordsAsync, ConvertToWordsWithHashAsync).

---

This comprehensive documentation for the Core Number Conversion feature should serve as an extensive guide for developers to integrate, utilize, and troubleshoot the control in their .NET WinForms applications.