# Currency Features

## Overview

The Currency Features allow developers to present numbers as monetary values by appending a currency symbol and adjusting the conversion process accordingly. This feature leverages the `EnableCurrency` and `CurrencySymbol` properties to transform a numerical input into a formatted monetary expression, ensuring that financial figures are both clear and culturally appropriate.

***

### Key Points

<table><thead><tr><th width="208">Aspect</th><th>Description</th></tr></thead><tbody><tr><td>Monetary Conversion</td><td>When <code>EnableCurrency</code> is true, the conversion prepends the defined <code>CurrencySymbol</code> to the number’s word representation, forming a monetary expression.</td></tr><tr><td>Currency Symbol</td><td>The <code>CurrencySymbol</code> property specifies the symbol (e.g., "$", "€", "£") to be used in the conversion, allowing customization for different currencies.</td></tr></tbody></table>

#### Code Example

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

// Enable currency conversion
humanizer.EnableCurrency = true;

// Set the desired currency symbol
humanizer.CurrencySymbol = "€";

// Convert a number to see the currency formatting in action
humanizer.Number = 1234;
Console.WriteLine("Monetary conversion: " + humanizer.Words);
```

***

### Best Practices

<table><thead><tr><th width="316">Practice</th><th>Recommendation</th></tr></thead><tbody><tr><td>Consistent Currency Settings</td><td>Ensure that the <code>CurrencySymbol</code> is set appropriately across the application to maintain a consistent financial display, especially in multi-currency environments.</td></tr><tr><td>Enable Currency Only When Needed</td><td>Enable the currency feature only for contexts that require financial representations to avoid confusing users when a standard numeric conversion is more appropriate.</td></tr><tr><td>Validate Input Data</td><td>Verify that numerical inputs are valid and represent realistic financial amounts to prevent errors in conversion.</td></tr></tbody></table>

#### Code Example

```csharp
// Example: Setting a consistent currency format for a financial report
humanizer.EnableCurrency = true;
humanizer.CurrencySymbol = "$";
humanizer.Number = 2500;
Console.WriteLine("Formatted monetary value: " + humanizer.Words);
```

***

### Common Pitfalls

<table><thead><tr><th width="294">Pitfall</th><th>Explanation</th></tr></thead><tbody><tr><td>Mismatched Currency Symbols</td><td>Using an incorrect or inconsistent currency symbol may confuse users, especially in applications dealing with multiple currencies.</td></tr><tr><td>Unintended Currency Conversion</td><td>Forgetting to disable <code>EnableCurrency</code> in non-financial contexts may lead to unintended monetary formatting of numbers.</td></tr><tr><td>Incomplete Localization</td><td>Overlooking the need to localize currency symbols and formatting may result in outputs that do not align with regional financial practices.</td></tr></tbody></table>

#### Code Example

```csharp
// Incorrect: Enabling currency conversion without verifying the appropriate currency symbol for the region
try
{
    humanizer.EnableCurrency = true;
    humanizer.CurrencySymbol = ""; // This will throw an exception because the symbol is invalid
    humanizer.Number = 100;
}
catch (ArgumentException ex)
{
    Console.WriteLine("Currency error: " + ex.Message);
}
```

***

### Usage Scenarios

<table><thead><tr><th width="241">Scenario</th><th>How It Works</th></tr></thead><tbody><tr><td>Financial Reports</td><td>Convert numerical values into a monetary format for reports, invoices, or financial dashboards by enabling currency features and setting the correct symbol.</td></tr><tr><td>E-Commerce Applications</td><td>Display product prices with currency symbols to ensure clarity for end users, enhancing trust and readability.</td></tr><tr><td>Budgeting Tools</td><td>Represent budgetary figures in a currency format, making financial planning and analysis more intuitive for users.</td></tr></tbody></table>

#### Code Example

```csharp
// Example: Using currency features in an e-commerce application to display product prices
humanizer.EnableCurrency = true;
humanizer.CurrencySymbol = "£";
humanizer.Number = 1999;
Console.WriteLine("Product price: " + humanizer.Words);
```

***

### Real Life Usage Scenarios

<table><thead><tr><th width="205">Scenario</th><th>Explanation</th></tr></thead><tbody><tr><td>Banking Applications</td><td>Converting account balances and transaction amounts into a formatted currency string enhances clarity and user trust.</td></tr><tr><td>Invoice Generation</td><td>Automatically generating monetary expressions for invoice amounts ensures professional and clear billing documents.</td></tr><tr><td>Retail Systems</td><td>Displaying prices in localized currency formats helps international retailers cater to a global customer base effectively.</td></tr></tbody></table>

#### Code Example

```csharp
// Example: In a banking application, formatting an account balance
humanizer.EnableCurrency = true;
humanizer.CurrencySymbol = "$";
humanizer.Number = 98765;
Console.WriteLine("Account balance in words: " + humanizer.Words);
```

***

### Troubleshooting Tips

<table><thead><tr><th width="220">Tip</th><th>Details</th></tr></thead><tbody><tr><td>Verify Currency Symbol</td><td>Ensure that the <code>CurrencySymbol</code> property is set to a valid, non-empty string to avoid conversion errors.</td></tr><tr><td>Check Feature Toggle</td><td>Confirm that the <code>EnableCurrency</code> property is enabled only when required, and reset it appropriately when switching between financial and non-financial contexts.</td></tr><tr><td>Validate Localization</td><td>When using currency features in conjunction with localization, ensure that the correct culture settings are applied to support proper formatting of decimals and grouping.</td></tr></tbody></table>

#### Code Example

```csharp
// Example: Debugging currency conversion issues
try
{
    humanizer.EnableCurrency = true;
    humanizer.CurrencySymbol = "$";
    humanizer.Number = 1500;
    Console.WriteLine("Currency conversion output: " + humanizer.Words);
}
catch (Exception ex)
{
    Console.WriteLine("Currency conversion troubleshooting: " + ex.Message);
}
```

***

### Review

<table><thead><tr><th width="171">Aspect</th><th>Consideration</th></tr></thead><tbody><tr><td>Clarity</td><td>The currency feature clearly distinguishes financial conversions from standard number-to-word conversions, improving user understanding in financial contexts.</td></tr><tr><td>Integration Ease</td><td>Simple property settings for enabling currency and specifying the symbol make integration straightforward for developers working on financial applications.</td></tr><tr><td>Flexibility</td><td>The feature can be toggled on or off as needed, providing flexibility for applications that require both numeric and monetary representations in different contexts.</td></tr></tbody></table>

***

### Summary

<table><thead><tr><th width="239">Summary Point</th><th>Description</th></tr></thead><tbody><tr><td>Monetary Representation</td><td>Transforms numerical inputs into formatted monetary expressions using the <code>EnableCurrency</code> and <code>CurrencySymbol</code> properties.</td></tr><tr><td>Developer Control</td><td>Provides developers with full control over how financial data is displayed, ensuring consistency and localization where required.</td></tr><tr><td>Easy to Integrate</td><td>Simple integration through property assignments and event notifications makes it an effective tool for financial and retail applications.</td></tr></tbody></table>

#### Final Integration Example

```csharp
using System;
using SiticoneNetFrameworkUI;

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

            // Subscribe to conversion events for monitoring updates
            humanizer.OnNumbersChanged += (sender, e) =>
            {
                Console.WriteLine($"Conversion updated: {e.Words}");
            };

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

            // Enable currency conversion and set the desired currency symbol
            humanizer.EnableCurrency = true;
            humanizer.CurrencySymbol = "$";

            // Perform a monetary conversion
            humanizer.Number = 4500;
            Console.WriteLine("Monetary conversion result: " + humanizer.Words);
        }
    }
}
```

***

This comprehensive documentation should provide developers with clear guidance on using and integrating the Currency Features into their .NET WinForms applications, including key points, best practices, usage scenarios, and troubleshooting tips for a smooth and effective integration experience.
