TechnicalUnits.WinForms 1.2.0.98

TechnicalUnits

A .NET library for working with SI units and engineering notation - format numeric values with SI prefixes, parse user input back to base values, and define/convert between units.

Motivation

Engineering and scientific applications frequently need to:

• Display values like 1.50 MHz, 3.30 mV, or 10.0 mT.
• Accept user input in engineering notation (e.g., "3u3" for 3.3 µ or "1k5" for 1500).
• Convert between units (e.g., inches to meters, Celsius to Kelvin).

TechnicalUnits provides a small, focused library that handles all of this - with UI controls for Avalonia and WinForms.

Features

• Unit system with SI base units, derived units, and dimensional analysis.
• Formatting of double values with SI prefixes (k, M, µ, n, etc.).
• Parsing of strings back to numeric values, including unit conversion.
• Math expression evaluation (optional) - evaluate expressions like "2 * pi * 1k".
• UI controls for Avalonia and WinForms with validation and increment/decrement logic.

Architecture

The library is organized into the following layers:

1. Unit Definitions (TechnicalUnits.UnitDefinition)

Defines the unit system:

Built-in units:

SIUnits provides the seven SI base units and all named SI derived units:

Units provides commonly used derived and non-SI units organized by category:

Units can be combined using operators to create new dimensions:

using TechnicalUnits.UnitDefinition;

// Newton = kg·m/s²
var newton = SIUnits.Kilogram * SIUnits.Meter / (SIUnits.Second * SIUnits.Second);

2. Formatting + Parsing (TechnicalUnits.Formatting)

Formatting styles (SIStyles):

3. Extension Methods (TechnicalUnits.Extensions)

FormatSimple is a lightweight formatting path with fewer options - useful when you just need quick SI-prefixed output.

4. Math Expression Evaluation (TechnicalUnits.Math)

5. UI Control Infrastructure

Quickstart

Install

dotnet add package TechnicalUnits

Formatting

using TechnicalUnits.Extensions;
using TechnicalUnits.UnitDefinition;

// Full formatting with SI prefixes
string text = SIUnits.Volt.Format(0.0033);       // "3.30 mV"
string text2 = SIUnits.Hertz.Format(1500000);    // "1.50 MHz"

// Control precision
string text3 = SIUnits.Meter.Format(1.23e3, precision: 2);  // "1.23 km"

Lightweight Formatting (FormatSimple)

A simpler API with fewer options - useful when you just need quick SI-prefixed output:

using TechnicalUnits.Extensions;
using TechnicalUnits.UnitDefinition;

string text = SIUnits.Tesla.FormatSimple(0.010);                 // "10 mT"
string text2 = SIUnits.Tesla.FormatSimple(0.010, precision: 1);  // "10.0 mT"

FormatSimple automatically shortens trailing zeros by default (configurable via the shortenTrailingZeros parameter).

String Interpolation with SI Notation

Use the SI() extension method to format interpolated strings with SI prefixes using the :SI format specifier:

using TechnicalUnits.UnitDefinition;
using static TechnicalUnits.Formatting.FormattableStringExtensions;

double thickness = 25e-9;
double frequency = 1.5e6;

// Basic usage with unit symbol
string text = SI($"Thickness = {thickness:SI}", "m");   // "Thickness = 25 nm"
string text2 = SI($"Frequency = {frequency:SI}", "Hz"); // "Frequency = 1.5 MHz"

// With Unit object
string text3 = SI($"Thickness = {thickness:SI}", SIUnits.Meter);

// With precision (SI0-SI9)
string text4 = SI($"Value = {thickness:SI3}", "m");     // "Value = 25.000 nm"

// Multiple values in one string
string text5 = SI($"d={thickness:SI}, f={frequency:SI}", "");

Note: C# doesn't allow custom format specifiers directly in $"" strings. The SI() wrapper enables the :SI specifier by accepting a FormattableString.

For full control over formatting, create a custom TechnicalUnitsFormatProvider:

using TechnicalUnits.Formatting;
using TechnicalUnits.UnitDefinition;
using static TechnicalUnits.Formatting.FormattableStringExtensions;

var provider = new TechnicalUnitsFormatProvider
{
    UnitOptions = new UnitOptions(SIUnits.Volt),
    FormattingOptions = FormattingOptions.Default.Clone()
};
provider.FormattingOptions.FractionalPrecision = 2;

string text = SI($"Voltage = {0.0033:SI}", provider);  // "Voltage = 3.30 mV"

Parsing

using TechnicalUnits.Extensions;
using TechnicalUnits.UnitDefinition;

double value = SIUnits.Hertz.Parse("1.5 kHz");   // 1500.0
double value2 = SIUnits.Volt.Parse("3u3");        // 0.0000033 (SI prefix as decimal separator)

Parsing with Alternate Units

using TechnicalUnits.Extensions;
using TechnicalUnits.UnitDefinition;

// Parse "10.0in" as meters, using Inch and Mil as alternate units
double meters = SIUnits.Meter.Parse("10.0in", [Units.Inch, Units.Mil]);  // 0.254

// Parse "10.0mil" as meters
double meters2 = SIUnits.Meter.Parse("10.0mil", [Units.Inch, Units.Mil]); // 0.0000254

Defining Custom Units

using TechnicalUnits.UnitDefinition;

// Derived unit with a linear conversion factor
var centimeter = new DerivedUnit("centimeter", "cm", 0.01, SIUnits.Meter);

// Derived unit with conversion functions (for non-linear conversions)
var celsius = new DerivedUnit(
    "celsius", "°C",
    fromBaseUnitFunc: k => k - 273.15,
    toBaseUnitFunc: c => c + 273.15,
    baseUnit: SIUnits.Kelvin);

// Convert between base and derived
double kelvin = celsius.ToBase(100.0);   // 373.15
double degC = celsius.FromBase(373.15);  // 100.0

Looking Up Units by Name or Symbol

using TechnicalUnits.UnitDefinition;

Unit? volt = UnitsLocator.FindBySymbol("V");     // case-sensitive symbol lookup
Unit? meter = UnitsLocator.FindByName("length");  // case-insensitive name lookup

// Enumerate all registered units
IReadOnlyList<Unit> all = UnitsLocator.AllUnits;

Math Expression Evaluation

The MathEvaluator class can parse and evaluate infix mathematical expressions containing SI-prefixed numbers, functions, constants, and unit conversions:

using TechnicalUnits.Math;
using TechnicalUnits.Formatting;
using TechnicalUnits.UnitDefinition;

var evaluator = new MathEvaluator();
var unitOpts = new UnitOptions(SIUnits.Volt);
var fmtOpts = FormattingOptions.Default;

double result = evaluator.Evaluate("2 * pi * 1k", unitOpts, fmtOpts, warnings: null);
// result ≈ 6283.185...

double result2 = evaluator.Evaluate("sqrt(2) * 100m", unitOpts, fmtOpts, warnings: null);
// result2 ≈ 0.14142... (100m = 0.1 in base units)

When used via ITechnicalUnitsControl (with EnableMath = true), expression evaluation is enabled automatically in the UI controls.

Unit conversions use bracket notation inside expressions:

100 [°C>K]          → 373.15

Built-in Constants

Constants are stored in MathEvaluator.Constants and can be added or removed at runtime.

Built-in Functions

Single-argument: abs, acos, asin, atan, ceiling, cos, cosh, exp, floor, log, log10, sin, sinh, sqrt, tan, tanh

Two-argument: max, min, pow

Custom functions can be registered via MathEvaluator.RegisterFunction.

UI Controls

The core library defines the ITechnicalUnitsControl interface and shared TechnicalUnitsControlMixin logic. Framework-specific packages provide ready-to-use controls:

TechnicalUnits.Avalonia

dotnet add package TechnicalUnits.Avalonia

Provides TechnicalUnitsUpDown - an Avalonia control that integrates with Avalonia's data binding and styling. It includes a Spinner and TextBox template part.

TechnicalUnits.WinForms

dotnet add package TechnicalUnits.WinForms

Provides:

Increment/Decrement Behavior

The TechnicalUnitsControlMixin provides smart up/down behavior based on keyboard modifiers:

Configuration

FormattingOptions

Note: FormattingOptions.Default is a shared singleton instance. Use .Clone() if you need to modify options without side effects.

UnitOptions

UnitOptions supports implicit conversion from Unit, so you can pass a Unit directly where a UnitOptions is expected.

License

TechnicalUnits is licensed under the terms of the MIT license (http://opensource.org/licenses/MIT, see LICENSE.txt).