Formatting Features

This feature provides various options to control how numeric values are formatted, including decimal places, notation styles, separators, custom format patterns, and rounding behavior.

Overview

The Formatting Features section of the SiticoneHumanizerFloat control enables developers to configure the display of numeric values in a variety of ways. This includes setting the maximum decimal places, selecting from multiple notation styles (such as Standard, Scientific, Engineering, Compact, and Binary), enabling or disabling thousand separators, trimming trailing zeros, specifying custom format patterns, and choosing the rounding mode. These options ensure that the control can be integrated seamlessly into different .NET WinForms applications requiring specialized numeric formatting.

---

Key Points

Item	Description
MaxDecimalPlaces	Determines the maximum number of decimal places to display (range: 0 to 17).
Notation	Specifies the format style; options include Standard, Scientific, Engineering, Compact, Binary.
UseThousandsSeparator	Enables or disables the inclusion of thousands separators in the formatted output.
TrimTrailingZeros	Removes unnecessary zeros after the decimal point to create a cleaner output.
CustomFormat	Allows for a user-defined numeric format pattern (must match the valid regex pattern).
RoundingMode	Determines the method of rounding (e.g., HalfUp, HalfEven, Truncate, Ceiling, Floor, SignificantDigits).

---

Best Practices

Aspect	Recommendation
Use appropriate Notation	Choose the notation style that best fits the data context (e.g., Scientific for very small or large numbers).
Limit Decimal Places	Set MaxDecimalPlaces to an optimal value to balance precision and readability.
Validate CustomFormat	Ensure any custom format string provided complies with the allowed format pattern to avoid exceptions.
Select suitable RoundingMode	Use the rounding mode that aligns with the business logic, especially when handling financial data.
Enable/Disable Separators	Toggle UseThousandsSeparator based on locale and user preference to improve clarity in large numbers.

---

Common Pitfalls

Issue	Description	Resolution
CustomFormat Regex Mismatch	Providing a custom format string that doesn't match the regex pattern (^[#0.,]+$) triggers an exception.	Validate the format string before assigning it to the CustomFormat property.
Inappropriate Decimal Places	Setting MaxDecimalPlaces too high or too low can lead to formatting issues or loss of information.	Choose a value within the allowed range (0 to 17) that balances precision and display clarity.
Wrong RoundingMode Selection	Using an unsuitable rounding mode may result in unexpected numeric values, especially with edge cases.	Understand each RoundingMode and test with sample values to ensure proper behavior in your application context.

---

Usage Scenarios

Scenario	Description
Financial Applications	Use Standard notation with a fixed number of decimal places and appropriate rounding (e.g., HalfUp) to display currency values.
Scientific Data Visualization	Utilize Scientific or Engineering notation to present very large or small measurement values accurately.
Compact Data Display	Apply Compact notation to present large numbers with suffixes, enhancing readability on dashboards.
Locale-Sensitive Applications	Combine CustomFormat and UseThousandsSeparator with localized settings to adhere to regional display standards.

Code Example: Configuring Formatting Features

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

// Set maximum decimal places to 5
humanizer.MaxDecimalPlaces = 5;

// Use Scientific notation for formatting numbers
humanizer.Notation = SiticoneHumanizerFloat.NotationStyle.Scientific;

// Enable thousands separator and trim trailing zeros for a clean display
humanizer.UseThousandsSeparator = true;
humanizer.TrimTrailingZeros = true;

// Provide a custom format pattern (ensure it meets the valid regex pattern)
humanizer.CustomFormat = "#,0.##";

// Set the rounding mode to HalfUp
humanizer.RoundingMode = SiticoneHumanizerFloat.RoundingModeEx.HalfUp;

// Set a sample value for demonstration
humanizer.Value = 1234567.890123;

// Display the formatted value
Console.WriteLine("Formatted Value: " + humanizer.Humanized);

---

Real Life Usage Scenarios

Scenario	Description
Dashboard Reporting	Presenting large figures (e.g., revenue, user counts) in a compact format with suffixes for quick interpretation.
Scientific Instrumentation	Displaying measurement data in scientific or engineering notation to maintain high precision.
International E-Commerce	Using localized formatting to adapt currency and number representations based on the user’s region.

Code Example: Dashboard Integration

// Example: Displaying user statistics on a dashboard
var userStatsHumanizer = new SiticoneHumanizerFloat
{
    MaxDecimalPlaces = 2,
    Notation = SiticoneHumanizerFloat.NotationStyle.Compact,
    UseThousandsSeparator = true,
    TrimTrailingZeros = true
};

userStatsHumanizer.Value = 1523000; // Example: Number of active users
Console.WriteLine("Active Users: " + userStatsHumanizer.Humanized);
// Expected output might be "1.52M" depending on the suffix settings

---

Troubleshooting Tips

Issue	Possible Cause	Suggested Action
Unexpected rounding behavior	The selected RoundingMode may not be suitable for the current numeric value.	Experiment with different RoundingMode values to achieve the desired rounding behavior.
Custom format exceptions	The provided custom format does not match the allowed pattern.	Double-check the custom format string against the regex (^[#0.,]+$) and adjust accordingly.
Inconsistent separator display	Locale settings or custom separator values may conflict with Culture defaults.	Review the DecimalSeparator and ThousandsSeparator values to ensure consistency with the target culture.

---

Review

Aspect	Review Notes
Flexibility	The control provides a wide range of formatting options making it suitable for diverse application needs.
Usability	Clear properties and enum options make it easy to configure and integrate the control.
Potential Issues	Custom format and rounding settings require careful validation to avoid unexpected results.
Integration Ease	Comprehensive code samples and usage scenarios simplify the integration process into .NET WinForms apps.

---

Summary

Summary Point	Description
Comprehensive Formatting Options	Allows precise control over numeric display including decimal places, notation, separators, and rounding.
Versatile Integration	Can be configured for a variety of applications ranging from financial to scientific and dashboard reporting.
Ease of Customization	Enables developers to easily adapt numeric formatting using custom patterns and localized settings.
Extensive Documentation	The provided code examples and usage scenarios help streamline the integration and troubleshooting process.

---

Additional Considerations

Consideration	Description
Testing Across Cultures	Test the control with various Culture settings to ensure numbers and separators render correctly.
Performance with High Precision	When using high precision (many decimal places), verify the control's performance remains optimal.
Error Handling	Implement try-catch blocks around formatting calls to gracefully handle potential FloatHumanizerExceptions.

Code Example: Handling Exceptions

try
{
    // Set a potentially problematic custom format
    humanizer.CustomFormat = "invalid_format";
}
catch (ArgumentException ex)
{
    Console.WriteLine("Error setting custom format: " + ex.Message);
}

---

By following this documentation and using the provided examples, developers can integrate and customize the Formatting Features of the SiticoneHumanizerFloat control effectively in their .NET WinForms applications.