> For the complete documentation index, see [llms.txt](https://docs-siticoneframework.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/data-formatting-and-display/siticone-humanizerfloat/additional-public-methods.md).

# Additional Public Methods

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

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

***

### Best Practices

<table><thead><tr><th width="297">Aspect</th><th>Recommendation</th></tr></thead><tbody><tr><td>Use Humanize for Consistency</td><td>Use the Humanize method for uniform conversion of numbers to a human-readable format across various parts of the application.</td></tr><tr><td>Define Custom Units Thoughtfully</td><td>When adding custom units, ensure the conversion factors are accurate and meaningful within the application context.</td></tr><tr><td>Validate Ranges in Normalization</td><td>Ensure that the normalization range is correctly defined (min &#x3C; max) before calling the Normalize method to avoid runtime errors.</td></tr></tbody></table>

***

### Common Pitfalls

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

***

### Usage Scenarios

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

#### Code Example: Using Humanize

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

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

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

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

#### Code Example: Custom Measurement in Industrial Application

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

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

***

### Summary

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

***

### Additional Considerations

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

#### Code Example: Comprehensive Exception Handling

```csharp
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.