Additional Public Methods

This feature provides a set of methods that extend the control's functionality by offering utility operations for custom unit conversions, value normalization, and alternative numeric representations.

Overview

The Additional Public Methods of the SiticoneHumanizerFloat control empower developers to perform extra operations on numeric values beyond simple formatting. These methods include converting any given number to a human-readable string, adding custom unit conversions, converting the value to a specified custom unit, and normalizing the value within a defined range. This collection of methods facilitates versatile numeric data manipulation within .NET WinForms applications.

---

Key Points

Item	Description
Humanize(double number)	Converts a specified number to its human-readable string representation based on the current formatting settings.
AddCustomUnit	Allows the addition of custom unit conversions by associating a unit name with a conversion factor.
ConvertTo	Converts the current numeric value to a previously added custom unit using the specified conversion factor.
Normalize	Normalizes the current value within a specified range, returning a result between 0 and 1.

---

Best Practices

Aspect	Recommendation
Use Humanize for Consistency	Use the Humanize method for uniform conversion of numbers to a human-readable format across various parts of the application.
Define Custom Units Thoughtfully	When adding custom units, ensure the conversion factors are accurate and meaningful within the application context.
Validate Ranges in Normalization	Ensure that the normalization range is correctly defined (min < max) before calling the Normalize method to avoid runtime errors.

---

Common Pitfalls

Issue	Description	Resolution
Invalid Custom Unit Definitions	Adding a custom unit with an empty unit name or a non-positive conversion factor will trigger an exception.	Validate unit names and conversion factors before calling AddCustomUnit.
Unrecognized Unit in Conversion	Calling ConvertTo with a unit name that has not been added will cause an exception.	Confirm that the unit exists by using AddCustomUnit before invoking ConvertTo.
Incorrect Range for Normalization	Supplying a minimum value that is greater than or equal to the maximum value in Normalize results in an error.	Ensure that the min value is less than the max value when using Normalize.

---

Usage Scenarios

Scenario	Description
Dynamic Data Formatting	Use Humanize to convert dynamic numeric values into readable strings for dashboards or reports.
Custom Unit Conversion	Integrate custom measurement units (e.g., kilometers, miles, or custom industry-specific units) by adding them with AddCustomUnit and converting using ConvertTo.
Data Normalization	Normalize sensor data or user inputs to a standard scale (0 to 1) for further processing or visualization.

Code Example: Using Humanize

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

// Convert a given number to a human-readable string
double sampleNumber = 1234567.89;
string humanReadable = humanizer.Humanize(sampleNumber);

Console.WriteLine("Human-readable format: " + humanReadable);

Code Example: Adding and Using Custom Units

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

// Add a custom unit conversion for "miles" where 1 unit equals 1.60934 kilometers
humanizer.AddCustomUnit("miles", 1.60934);

// Set a sample value (assumed to be in kilometers)
humanizer.Value = 1609.34;

// Convert the value to "miles"
double milesValue = humanizer.ConvertTo("miles");

Console.WriteLine("Value in miles: " + milesValue);
// Expected output: 1609.34 / 1.60934 = 100 (approximately)

Code Example: Normalizing a Value

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

// Set a sample value
humanizer.Value = 75;

// Normalize the value within a range (e.g., min: 50, max: 100)
double normalizedValue = humanizer.Normalize(50, 100);

Console.WriteLine("Normalized Value: " + normalizedValue);
// Expected output: (75 - 50) / (100 - 50) = 0.5

---

Real Life Usage Scenarios

Scenario	Description
Real-Time Analytics	Use Humanize to convert and display real-time numeric data in a human-readable format for monitoring dashboards.
Custom Measurement Systems	Add industry-specific units to seamlessly convert and display values (e.g., converting sensor data into user-friendly units).
Data Normalization for UI Scaling	Normalize values from various data sources to a common scale for graphical representation or progress indicators.

Code Example: Custom Measurement in Industrial Application

// Example: Converting sensor data from meters to feet using a custom unit conversion
var sensorHumanizer = new SiticoneHumanizerFloat();

// Add a custom conversion unit for "feet" (1 meter = 3.28084 feet)
sensorHumanizer.AddCustomUnit("feet", 3.28084);

// Set sensor data in meters
sensorHumanizer.Value = 100;

// Convert the sensor data to feet
double feetValue = sensorHumanizer.ConvertTo("feet");

Console.WriteLine("Sensor data in feet: " + feetValue);

---

Troubleshooting Tips

Issue	Possible Cause	Suggested Action
Exception in AddCustomUnit	Unit name is empty or conversion factor is non-positive.	Verify inputs before calling AddCustomUnit to ensure that unitName is not null/whitespace and conversionFactor is positive.
Exception in ConvertTo	The specified unit name has not been added to the custom unit dictionary.	Confirm the unit exists by checking that AddCustomUnit was called with the correct unit name before ConvertTo.
Normalization Range Error	The minimum value provided is not less than the maximum value.	Ensure that the parameters for Normalize are in the correct order (min < max).

---

Review

Aspect	Review Notes
Flexibility	The methods extend the control’s functionality by enabling custom unit conversions, normalization, and humanization.
Ease of Integration	Well-defined methods simplify the addition of custom units and provide intuitive operations like normalization and humanization.
Potential Issues	Developers must validate inputs to avoid exceptions, especially when working with custom units and normalization ranges.
Integration with Other Features	Seamlessly integrates with formatting, validation, and localization features for a comprehensive numeric display solution.

---

Summary

Summary Point	Description
Extended Functionality	Additional Public Methods provide essential utilities to convert, normalize, and customize numeric data beyond standard formatting.
Customization Options	Methods such as AddCustomUnit and ConvertTo enable developers to define and use domain-specific units.
Enhanced Data Handling	Normalize offers a straightforward way to scale data within a predefined range, useful for visualization and analytics.
Simplified Integration	The provided methods are designed to work in tandem with the control’s core formatting features for versatile application scenarios.

---

Additional Considerations

Consideration	Description
Input Validation	Always validate the inputs for custom unit conversion and normalization to ensure consistency and prevent runtime errors.
Reusability Across Modules	These methods can be reused across different modules of the application where numeric data conversion or normalization is required.
Future Enhancements	Consider extending the methods to support additional custom operations as new requirements emerge in your application domain.

Code Example: Comprehensive Exception Handling

try
{
    // Attempt to add a custom unit with an invalid name or factor
    humanizer.AddCustomUnit("", -1);
}
catch (ArgumentException ex)
{
    Console.WriteLine("Custom unit error: " + ex.Message);
}

try
{
    // Attempt to convert using a non-existent custom unit
    double result = humanizer.ConvertTo("nonexistent_unit");
}
catch (ArgumentException ex)
{
    Console.WriteLine("Conversion error: " + ex.Message);
}

---

By leveraging the Additional Public Methods of the SiticoneHumanizerFloat control, developers can enhance the way numeric values are handled and displayed within their applications. These methods offer a robust toolkit for custom conversions, normalization, and humanization, ensuring that numeric data can be presented accurately and in a format that meets the specific needs of diverse application scenarios.