Version 3.3.1.2

UnitNumberUtility class

Namespace: Sirenix.Utilities.Editor
Assembly: Sirenix.Utilities.Editor
public static class UnitNumberUtility
Tools for converting between units, for example, converting from inches to meters.
Inheritance
  • System.Object
  • UnitNumberUtility

Methods

AddCustomUnit(String, String[], UnitCategory, Decimal)
Adds a custom unit to the UnitNumberUtility, that can also be used with the . Call this using InitializeOnLoad or InitializeOnLoadMethod.
public static void AddCustomUnit(string name, string[] symbols, UnitCategory unitCategory, decimal multiplier)
Parameters
System.String name

The name of the unit. Duplicate names are not allowed.

System.String[] symbols

Symbols used for the unit. First value in the array will be used as the primary symbol. Atleast 1 value required. Duplicate symbols are not allowed within the same category.

UnitCategory unitCategory

The category of the unit. Units can only be converted to another of the same category. Custom categories are allowed.

System.Decimal multiplier

The multiplier to convert the unit from the base value. For example, meters are the base unit of the distance category, therefore centimeters have a multipler of 100.

AddCustomUnit(String, String[], UnitCategory, Func<Decimal, Decimal>, Func<Decimal, Decimal>)
Adds a custom unit to the UnitNumberUtility, that can also be used with the . This overload allows for custom conversion methods but, if possible, the multiplier overloads should be prefered. Call this using InitializeOnLoad or InitializeOnLoadMethod.
public static void AddCustomUnit(string name, string[] symbols, UnitCategory unitCategory, Func<decimal, decimal> convertToBase, Func<decimal, decimal> convertFromBase)
Parameters
System.String name

The name of the unit. Duplicate names are not allowed.

System.String[] symbols

Symbols used for the unit. First value in the array will be used as the primary symbol. Atleast 1 value required. Duplicate symbols are not allowed within the same category.

UnitCategory unitCategory

The category of the unit. Units can only be converted to another of the same category. Custom categories are allowed.

System.Func<System.Decimal, System.Decimal> convertToBase

Method for converting a given value of the custom unit to the base unit. For example, for centimeter, use: x => x / 100m;.

System.Func<System.Decimal, System.Decimal> convertFromBase

Method for converting a given value of the base unit to the custom unit. For example, for centimeter, use: x => x * 100m;.

AddCustomUnit(String, String[], String, Decimal)
Adds a custom unit to the UnitNumberUtility, that can also be used with the . Call this using InitializeOnLoad or InitializeOnLoadMethod.
public static void AddCustomUnit(string name, string[] symbols, string unitCategory, decimal multiplier)
Parameters
System.String name

The name of the unit. Duplicate names are not allowed.

System.String[] symbols

Symbols used for the unit. First value in the array will be used as the primary symbol. Atleast 1 value required. Duplicate symbols are not allowed within the same category.

System.String unitCategory

The category of the unit. Units can only be converted to another of the same category. Custom categories are allowed.

System.Decimal multiplier

The multiplier to convert the unit from the base value. For example, meters are the base unit of the distance category, therefore centimeters have a multipler of 100.

AddCustomUnit(String, String[], String, Func<Decimal, Decimal>, Func<Decimal, Decimal>)
Adds a custom unit to the UnitNumberUtility, that can also be used with the . This overload allows for custom conversion methods but, if possible, the multiplier overloads should be prefered. Call this using InitializeOnLoad or InitializeOnLoadMethod.
public static void AddCustomUnit(string name, string[] symbols, string unitCategory, Func<decimal, decimal> convertToBase, Func<decimal, decimal> convertFromBase)
Parameters
System.String name

The name of the unit. Duplicate names are not allowed.

System.String[] symbols

Symbols used for the unit. First value in the array will be used as the primary symbol. Atleast 1 value required. Duplicate symbols are not allowed within the same category.

System.String unitCategory

The category of the unit. Units can only be converted to another of the same category. Custom categories are allowed.

System.Func<System.Decimal, System.Decimal> convertToBase

Method for converting a given value of the custom unit to the base unit. For example, for centimeter, use: x => x / 100m;.

System.Func<System.Decimal, System.Decimal> convertFromBase

Method for converting a given value of the base unit to the custom unit. For example, for centimeter, use: x => x * 100m;.

CanConvertBetween(Units, Units)
Indicates whether or not a value can be converted between the given a and b units.
public static bool CanConvertBetween(Units a, Units b)
Parameters
Units a

Unit a.

Units b

Unit b.

Returns
System.Boolean

true if both units have the same category. Otherwise false.

CanConvertBetween(UnitInfo, UnitInfo)
Indicates whether or not a value can be converted between the given a and b units.
public static bool CanConvertBetween(UnitInfo a, UnitInfo b)
Parameters
UnitInfo a

Unit a.

UnitInfo b

Unit b.

Returns
System.Boolean

true if both units have the same category. Otherwise false.

ConvertUnitFromTo(Decimal, Units, Units)
Converts between two units. The units must be of the same category.
public static decimal ConvertUnitFromTo(decimal value, Units from, Units to)
Parameters
System.Decimal value

The value to convert. Should be in the from units.

Units from

The unit to convert the value from. value should be in this unit.

Units to

To unit to convert the value to. Must be the same category as from.

Returns
System.Decimal

The value converted to to units.

Exceptions
System.Exception

Throws when either 'from' or 'to' units are invalid, or when the units are of different categories.

ConvertUnitFromTo(Decimal, UnitInfo, UnitInfo)
Converts between two units. The units must be of the same category.
public static decimal ConvertUnitFromTo(decimal value, UnitInfo fromUnitInfo, UnitInfo toUnitInfo)
Parameters
System.Decimal value

The value to convert. Should be in the fromUnitInfo units.

UnitInfo fromUnitInfo

The unit to convert the value from. value should be in this unit.

UnitInfo toUnitInfo

To unit to convert the value to. Must be the same category as fromUnitInfo.

Returns
System.Decimal

The value converted to toUnitInfo units.

Exceptions
System.Exception

Throws when either 'fromUnitInfo' or 'toUnitInfo' units are invalid, or when the units are of different categories.

ConvertUnitFromToWithError(Decimal, UnitInfo, UnitInfo, out String)
public static decimal ConvertUnitFromToWithError(decimal value, UnitInfo fromUnitInfo, UnitInfo toUnitInfo, out string error)
Parameters
System.Decimal value

UnitInfo fromUnitInfo

UnitInfo toUnitInfo

System.String error

Returns
System.Decimal

GetAllUnitInfos()
Gets all UnitInfo registered, both built-in and custom.
public static IEnumerable<UnitInfo> GetAllUnitInfos()
Returns
System.Collections.Generic.IEnumerable<UnitInfo>

Enumerable of both built-in and custom units.

GetUnitInfo(Units)
Gets the UnitInfo for the given Units enum value.
public static UnitInfo GetUnitInfo(Units unit)
Parameters
Units unit

Units enum value.

Returns
UnitInfo

UnitInfo for the unit.

Exceptions
System.Exception

Throws for invalid unit input.

GetUnitInfoByName(String)
Gets the UnitInfo with the corrosponding name.
public static UnitInfo GetUnitInfoByName(string unitName)
Parameters
System.String unitName

The name of the unit.

Returns
UnitInfo

UnitInfo for the name.

Exceptions
System.Exception

Throws when no unit with the given name is found.

MatchUnitInfoBySymbol(String, String)
Finds the UnitInfo that best fits the given symbol within the given category.
public static UnitInfo MatchUnitInfoBySymbol(string symbol, string unitCategory)
Parameters
System.String symbol

The symbol to find a unit for.

System.String unitCategory

The category to look for units within.

Returns
UnitInfo

The UnitInfo that best matches the given symbol.

Exceptions
System.Exception

Throws when no match was found.

TryConvertUnitFromTo(Decimal, Units, Units, out Decimal)
Converts between two units. The units must be of the same category.
public static bool TryConvertUnitFromTo(decimal value, Units from, Units to, out decimal converted)
Parameters
System.Decimal value

The value to convert. Should be in the from units.

Units from

The unit to convert the value from. value should be in this unit.

Units to

To unit to convert the value to. Must be the same category as from.

System.Decimal converted

The value converted to to units.

Returns
System.Boolean

true when the unit was successfully converted. Otherwise false.

TryConvertUnitFromTo(Decimal, UnitInfo, UnitInfo, out Decimal)
Converts between two units. The units must be of the same category.
public static bool TryConvertUnitFromTo(decimal value, UnitInfo fromUnitInfo, UnitInfo toUnitInfo, out decimal converted)
Parameters
System.Decimal value

The value to convert. Should be in the fromUnitInfo units.

UnitInfo fromUnitInfo

The unit to convert the value from. value should be in this unit.

UnitInfo toUnitInfo

To unit to convert the value to. Must be the same category as fromUnitInfo.

System.Decimal converted

The value converted to toUnitInfo units.

Returns
System.Boolean

true when the unit was successfully converted. Otherwise false.

Exceptions
System.ArgumentNullException

Throws if either fromUnitInfo or toUnitInfo is null.

TryGetUnitInfo(Units, out UnitInfo)
Gets the UnitInfo for the given Units enum value.
public static bool TryGetUnitInfo(Units unit, out UnitInfo unitInfo)
Parameters
Units unit

Units enum value.

UnitInfo unitInfo

The UnitInfo matching the given unit value.

Returns
System.Boolean

true when a UnitInfo was found. Otherwise false.

TryGetUnitInfoByName(String, out UnitInfo)
Gets the UnitInfo with the given name.
public static bool TryGetUnitInfoByName(string unitName, out UnitInfo unitInfo)
Parameters
System.String unitName

The name of the unit.

UnitInfo unitInfo

The UnitInfo matching the given name.

Returns
System.Boolean

true when a UnitInfo was found. Otherwise false.

TryMatchUnitInfoBySymbol(String, String, out UnitInfo)
Finds the UnitInfo that best fits the given symbol within the given category.
public static bool TryMatchUnitInfoBySymbol(string symbol, string unitCategory, out UnitInfo unitInfo)
Parameters
System.String symbol

The symbol to find a unit for.

System.String unitCategory

The category to look for units within.

UnitInfo unitInfo

The UnitInfo that best matches the given symbol.

Returns
System.Boolean

true when a UnitInfo was found. Otherwise false.