Skip to content

HMath.Units

Module index · Numerical conventions

Description

Exact rational unit conversion and API-level dimensional safety. Opaque quantities store SI values; addition/conversion reject incompatible dimensions. Seven SI base exponents are augmented by data and plane-angle tags, so bytes cannot be added to lengths and angles cannot be added to plain scalars. Absolute temperatures and differences are distinct: absolute + absolute and products of absolutes are rejected; subtracting absolutes produces a difference.

On this page

API Purpose
Dimension Opaque nine-exponent dimensional witness: seven SI bases plus data and plane-angle tags.
dimension Exponents in order length, mass, time, current, temperature, amount, luminous intensity, data, plane angle.
dimensionExponents Return nine exact integer exponents ordered as length, mass, time, current, temperature, amount, luminous intensity, data, plane angle.
dimensionless Dimension witness with all nine exponents zero; all unspecified exponents are zero.
lengthDimension Dimension witness with length exponent one; all unspecified exponents are zero.
massDimension Dimension witness with mass exponent one; all unspecified exponents are zero.
timeDimension Dimension witness with time exponent one; all unspecified exponents are zero.
temperatureDimension Dimension witness with temperature exponent one; all unspecified exponents are zero.
angleDimension Dimension witness with plane-angle tag exponent one; all unspecified exponents are zero.
dataDimension Dimension witness with data tag exponent one; all unspecified exponents are zero.
Unit Opaque exact affine unit definition SI=value*scale+offset.
unit SI = value * scale + offset.
unitName Return the display name/symbol of a Unit, for example "m".
unitDimension Return the dimensional-exponent witness of a Unit.
unitScale Return exact Rational scale in the conversion SI = value*scale + offset.
unitOffset Return exact Rational affine offset in SI = value*scale + offset.
unitProduct Multiply two zero-offset units: add dimension exponents and multiply Rational scales.
unitQuotient Divide two zero-offset units: subtract dimension exponents and divide their positive scales.
unitPower Given zero-offset Unit then Integer exponent, multiply its exponents and raise its positive scale to that power.
Quantity Opaque exact SI-valued dimensional quantity,tagging absolute temperatures separately from differences.
quantity Given Unit then Rational value, construct an exact SI-valued Quantity using its scale and offset.
temperatureDifference Given temperature Unit then Rational difference, multiply by its scale while ignoring its affine offset.
quantityDimension Return a Quantity's dimensional-exponent witness, without changing its SI value or absolute-temperature tag.
siValue Return exact Rational SI value of a Quantity.
inUnit Given destination Unit then Quantity, convert its SI value to that unit.
convert Given source Unit, destination Unit, then Rational value, convert exactly through SI.
addQuantity Add equal-dimension quantities.
subtractQuantity Subtract equal-dimension quantities.
multiplyQuantity Multiply SI values and add dimension exponents.
divideQuantity Divide SI values and subtract dimension exponents.
SIPrefix SI prefix name,symbol,and power-of-ten exponent. prefixed rejects affine units.
SIPrefix Declaration and type contract below.
prefixName SI prefix name, such as kilo.
prefixSymbol SI prefix symbol, such as k; micro uses ASCII u in this catalog.
prefixExponent Integer power of ten multiplying the base unit scale.
siPrefixes BIPM prefixes through the 2022 quettaronna and rontoquecto additions.
prefixed Given SIPrefix then zero-offset Unit, multiply its scale by 10^prefixExponent and prepend its symbol.
metre The metre Unit: 1 metre.
kilometre The kilometre Unit: 1000 metres.
centimetre The centimetre Unit: 0.01 metre.
millimetre The millimetre Unit: 0.001 metre.
inch The inch Unit: 0.0254 metre.
foot The foot Unit: 0.3048 metre.
yard The yard Unit: 0.9144 metre.
mile The mile Unit: 1609.344 metres.
nauticalMile The nauticalMile Unit: 1852 metres.
squareMetre The squareMetre Unit: 1 square metre.
hectare The hectare Unit: 10000 square metres.
cubicMetre The cubicMetre Unit: 1 cubic metre.
litre The litre Unit: 0.001 cubic metre.
millilitre The millilitre Unit: 0.000001 cubic metre.
kilogram The kilogram Unit: 1 kilogram.
gram The gram Unit: 0.001 kilogram.
tonne The tonne Unit: 1000 kilograms.
pound The pound Unit: 0.45359237 kilogram.
second The second Unit: 1 second.
minute The minute Unit: 60 seconds.
hour The hour Unit: 3600 seconds.
day The day Unit: 86400 seconds.
metresPerSecond The metresPerSecond Unit: 1 metre per second.
kilometresPerHour The kilometresPerHour Unit: 1000/3600 metres per second.
milesPerHour The milesPerHour Unit: 1609.344/3600 metres per second.
metresPerSecondSquared The metresPerSecondSquared Unit: 1 metre per second squared.
newton The newton Unit: 1 kg*m/s^2.
joule The joule Unit: 1 newton metre.
watt The watt Unit: 1 joule per second.
pascal The pascal Unit: 1 newton per square metre.
bar The bar Unit: 100000 pascals.
atmosphere The atmosphere Unit: 101325 pascals.
kelvin The kelvin Unit: absolute temperature with SI=value.
celsius The celsius Unit: absolute temperature with SI=value+273.15 kelvin.
fahrenheit The fahrenheit Unit: absolute temperature with SI=(value-32)*5/9+273.15 kelvin.
hertz The hertz Unit: 1 inverse second.
bit The bit Unit: 1 data bit.
byte The byte Unit: 8 data bits.
kibibyte The kibibyte Unit: 8192 data bits (1024 bytes).
mebibyte The mebibyte Unit: 8388608 data bits (1024^2 bytes).
gigabyte The gigabyte Unit: 8000000000 data bits (10^9 bytes).
radian The radian Unit: 1 radian.
degree The degree Unit: pi/180 radian, using the stored 50-place Rational pi approximation.
gradian The gradian Unit: pi/200 radian, using the stored Rational pi approximation.
radiansToDegrees Convert radians to degrees by multiplying by 180/pi in the chosen Floating type.
degreesToRadians Convert degrees to radians by multiplying by pi/180 in the chosen Floating type.
radiansToGradians Convert radians to gradians (400 per full turn) by multiplying by 200/pi.
gradiansToRadians Convert gradians to radians by multiplying by pi/200.

Documentation

Dimension

data Dimension Source #

Opaque nine-exponent dimensional witness: seven SI bases plus data and plane-angle tags. Construct with dimension.

Instances

Instances details
Show Dimension Source # 
Instance details

Defined in HMath.Units

Methods

showsPrec :: Int -> Dimension -> ShowS #

show :: Dimension -> String #

showList :: [Dimension] -> ShowS #

Eq Dimension Source # 
Instance details

Defined in HMath.Units

Methods

(==) :: Dimension -> Dimension -> Bool #

(/=) :: Dimension -> Dimension -> Bool #

dimension

dimension :: [Integer] -> Either MathError Dimension Source #

Exponents in order length, mass, time, current, temperature, amount, luminous intensity, data, plane angle. Require exactly nine exponents.

dimensionExponents

dimensionExponents :: Dimension -> [Integer] Source #

Return nine exact integer exponents ordered as length, mass, time, current, temperature, amount, luminous intensity, data, plane angle.

dimensionless

dimensionless :: Dimension Source #

Dimension witness with all nine exponents zero; all unspecified exponents are zero. Use to construct or compare dimension-safe units/quantities.

lengthDimension

lengthDimension :: Dimension Source #

Dimension witness with length exponent one; all unspecified exponents are zero. Use to construct or compare dimension-safe units/quantities.

massDimension

massDimension :: Dimension Source #

Dimension witness with mass exponent one; all unspecified exponents are zero. Use to construct or compare dimension-safe units/quantities.

timeDimension

timeDimension :: Dimension Source #

Dimension witness with time exponent one; all unspecified exponents are zero. Use to construct or compare dimension-safe units/quantities.

temperatureDimension

temperatureDimension :: Dimension Source #

Dimension witness with temperature exponent one; all unspecified exponents are zero. Use to construct or compare dimension-safe units/quantities.

angleDimension

angleDimension :: Dimension Source #

Dimension witness with plane-angle tag exponent one; all unspecified exponents are zero. Use to construct or compare dimension-safe units/quantities.

dataDimension

dataDimension :: Dimension Source #

Dimension witness with data tag exponent one; all unspecified exponents are zero. Use to construct or compare dimension-safe units/quantities.

Unit

data Unit Source #

Opaque exact affine unit definition SI=value*scale+offset. Nonzero offsets are restricted to absolute-temperature units.

Instances

Instances details
Show Unit Source # 
Instance details

Defined in HMath.Units

Methods

showsPrec :: Int -> Unit -> ShowS #

show :: Unit -> String #

showList :: [Unit] -> ShowS #

Eq Unit Source # 
Instance details

Defined in HMath.Units

Methods

(==) :: Unit -> Unit -> Bool #

(/=) :: Unit -> Unit -> Bool #

unit

unit :: String -> Dimension -> Rational -> Rational -> Either MathError Unit Source #

SI = value * scale + offset. Only temperature units may have an offset.

unitName

unitName :: Unit -> String Source #

Return the display name/symbol of a Unit, for example "m". No conversion is performed.

unitDimension

unitDimension :: Unit -> Dimension Source #

Return the dimensional-exponent witness of a Unit. Compatible conversions require equal dimensions.

unitScale

unitScale :: Unit -> Rational Source #

Return exact Rational scale in the conversion SI = value*scale + offset. All public Unit constructors require a positive scale.

unitOffset

unitOffset :: Unit -> Rational Source #

Return exact Rational affine offset in SI = value*scale + offset. Only temperature units may have a nonzero offset.

unitProduct

unitProduct :: Unit -> Unit -> Either MathError Unit Source #

Multiply two zero-offset units: add dimension exponents and multiply Rational scales. Any affine offset returns Left DomainError. This constructs a Unit, not a Quantity.

unitQuotient

unitQuotient :: Unit -> Unit -> Either MathError Unit Source #

Divide two zero-offset units: subtract dimension exponents and divide their positive scales. Affine units fail with DomainError.

unitPower

unitPower :: Unit -> Integer -> Either MathError Unit Source #

Given zero-offset Unit then Integer exponent, multiply its exponents and raise its positive scale to that power. Negative powers are valid; affine units fail.

Quantity

data Quantity Source #

Opaque exact SI-valued dimensional quantity,tagging absolute temperatures separately from differences. Construct with quantity or temperatureDifference.

Instances

Instances details
Show Quantity Source # 
Instance details

Defined in HMath.Units

Methods

showsPrec :: Int -> Quantity -> ShowS #

show :: Quantity -> String #

showList :: [Quantity] -> ShowS #

Eq Quantity Source # 
Instance details

Defined in HMath.Units

Methods

(==) :: Quantity -> Quantity -> Bool #

(/=) :: Quantity -> Quantity -> Bool #

quantity

quantity :: Unit -> Rational -> Quantity Source #

Given Unit then Rational value, construct an exact SI-valued Quantity using its scale and offset. A temperature unit constructs an absolute temperature; use temperatureDifference for differences.

temperatureDifference

temperatureDifference :: Unit -> Rational -> Either MathError Quantity Source #

Given temperature Unit then Rational difference, multiply by its scale while ignoring its affine offset. A non-temperature unit returns Left DomainError. The result is not an absolute temperature.

quantityDimension

quantityDimension :: Quantity -> Dimension Source #

Return a Quantity's dimensional-exponent witness, without changing its SI value or absolute-temperature tag.

siValue

siValue :: Quantity -> Rational Source #

Return exact Rational SI value of a Quantity. For absolute temperature this is an absolute kelvin value; preserve quantityDimension when interpreting the number.

inUnit

inUnit :: Unit -> Quantity -> Either MathError Rational Source #

Given destination Unit then Quantity, convert its SI value to that unit. Reject incompatible dimensions. Apply affine offsets only for absolute temperatures, not differences.

convert

convert :: Unit -> Unit -> Rational -> Either MathError Rational Source #

Given source Unit, destination Unit, then Rational value, convert exactly through SI. Incompatible dimensions fail. Example: convert kilometre metre 2 == Right 2000.

addQuantity

addQuantity :: Quantity -> Quantity -> Either MathError Quantity Source #

Add equal-dimension quantities. Two absolute temperatures cannot be added; absolute plus difference produces an absolute temperature. Incompatible dimensions return Left DomainError.

subtractQuantity

subtractQuantity :: Quantity -> Quantity -> Either MathError Quantity Source #

Subtract equal-dimension quantities. Absolute minus absolute produces a difference; difference minus absolute is invalid. Incompatible dimensions return Left DomainError.

multiplyQuantity

multiplyQuantity :: Quantity -> Quantity -> Either MathError Quantity Source #

Multiply SI values and add dimension exponents. Any absolute-temperature operand fails with DomainError; temperature differences can participate in products.

divideQuantity

divideQuantity :: Quantity -> Quantity -> Either MathError Quantity Source #

Divide SI values and subtract dimension exponents. Reject a zero divisor or absolute-temperature operands. Result preserves exact Rational arithmetic.

SIPrefix

data SIPrefix Source #

SI prefix name,symbol,and power-of-ten exponent. prefixed rejects affine units.

Constructors

SIPrefix 

Fields

Instances

Instances details
Show SIPrefix Source # 
Instance details

Defined in HMath.Units

Methods

showsPrec :: Int -> SIPrefix -> ShowS #

show :: SIPrefix -> String #

showList :: [SIPrefix] -> ShowS #

Eq SIPrefix Source # 
Instance details

Defined in HMath.Units

Methods

(==) :: SIPrefix -> SIPrefix -> Bool #

(/=) :: SIPrefix -> SIPrefix -> Bool #

siPrefixes

siPrefixes :: [SIPrefix] Source #

BIPM prefixes through the 2022 quettaronna and rontoquecto additions. Source: https://www.bipm.org/en/measurement-units/si-prefixes

prefixed

prefixed :: SIPrefix -> Unit -> Either MathError Unit Source #

Given SIPrefix then zero-offset Unit, multiply its scale by 10^prefixExponent and prepend its symbol. Reject affine units or absolute exponent above 10000.

metre

metre :: Unit Source #

The metre Unit: 1 metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

kilometre

kilometre :: Unit Source #

The kilometre Unit: 1000 metres. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

centimetre

centimetre :: Unit Source #

The centimetre Unit: 0.01 metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

millimetre

millimetre :: Unit Source #

The millimetre Unit: 0.001 metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

inch

inch :: Unit Source #

The inch Unit: 0.0254 metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

foot

foot :: Unit Source #

The foot Unit: 0.3048 metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

yard

yard :: Unit Source #

The yard Unit: 0.9144 metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

mile

mile :: Unit Source #

The mile Unit: 1609.344 metres. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

nauticalMile

nauticalMile :: Unit Source #

The nauticalMile Unit: 1852 metres. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

squareMetre

squareMetre :: Unit Source #

The squareMetre Unit: 1 square metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

hectare

hectare :: Unit Source #

The hectare Unit: 10000 square metres. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

cubicMetre

cubicMetre :: Unit Source #

The cubicMetre Unit: 1 cubic metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

litre

litre :: Unit Source #

The litre Unit: 0.001 cubic metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

millilitre

millilitre :: Unit Source #

The millilitre Unit: 0.000001 cubic metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

kilogram

kilogram :: Unit Source #

The kilogram Unit: 1 kilogram. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

gram

gram :: Unit Source #

The gram Unit: 0.001 kilogram. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

tonne

tonne :: Unit Source #

The tonne Unit: 1000 kilograms. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

pound

pound :: Unit Source #

The pound Unit: 0.45359237 kilogram. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

second

second :: Unit Source #

The second Unit: 1 second. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

minute

minute :: Unit Source #

The minute Unit: 60 seconds. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

hour

hour :: Unit Source #

The hour Unit: 3600 seconds. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

day

day :: Unit Source #

The day Unit: 86400 seconds. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

metresPerSecond

metresPerSecond :: Unit Source #

The metresPerSecond Unit: 1 metre per second. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

kilometresPerHour

kilometresPerHour :: Unit Source #

The kilometresPerHour Unit: 1000/3600 metres per second. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

milesPerHour

milesPerHour :: Unit Source #

The milesPerHour Unit: 1609.344/3600 metres per second. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

metresPerSecondSquared

metresPerSecondSquared :: Unit Source #

The metresPerSecondSquared Unit: 1 metre per second squared. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

newton

newton :: Unit Source #

The newton Unit: 1 kg*m/s^2. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

joule

joule :: Unit Source #

The joule Unit: 1 newton metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

watt

watt :: Unit Source #

The watt Unit: 1 joule per second. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

pascal

pascal :: Unit Source #

The pascal Unit: 1 newton per square metre. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

bar

bar :: Unit Source #

The bar Unit: 100000 pascals. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

atmosphere

atmosphere :: Unit Source #

The atmosphere Unit: 101325 pascals. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

kelvin

kelvin :: Unit Source #

The kelvin Unit: absolute temperature with SI=value. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

celsius

celsius :: Unit Source #

The celsius Unit: absolute temperature with SI=value+273.15 kelvin. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

fahrenheit

fahrenheit :: Unit Source #

The fahrenheit Unit: absolute temperature with SI=(value-32)*5/9+273.15 kelvin. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

hertz

hertz :: Unit Source #

The hertz Unit: 1 inverse second. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

bit

bit :: Unit Source #

The bit Unit: 1 data bit. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

byte

byte :: Unit Source #

The byte Unit: 8 data bits. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

kibibyte

kibibyte :: Unit Source #

The kibibyte Unit: 8192 data bits (1024 bytes). Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

mebibyte

mebibyte :: Unit Source #

The mebibyte Unit: 8388608 data bits (1024^2 bytes). Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

gigabyte

gigabyte :: Unit Source #

The gigabyte Unit: 8000000000 data bits (10^9 bytes). Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

radian

radian :: Unit Source #

The radian Unit: 1 radian. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

degree

degree :: Unit Source #

The degree Unit: pi/180 radian, using the stored 50-place Rational pi approximation. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

gradian

gradian :: Unit Source #

The gradian Unit: pi/200 radian, using the stored Rational pi approximation. Non-temperature definitions use an exact Rational scale and zero affine offset. Use quantity or convert to construct/convert values; temperature differences use temperatureDifference.

radiansToDegrees

radiansToDegrees :: Floating a => a -> a Source #

Convert radians to degrees by multiplying by 180/pi in the chosen Floating type. No finite-input validation is added.

degreesToRadians

degreesToRadians :: Floating a => a -> a Source #

Convert degrees to radians by multiplying by pi/180 in the chosen Floating type.

radiansToGradians

radiansToGradians :: Floating a => a -> a Source #

Convert radians to gradians (400 per full turn) by multiplying by 200/pi.

gradiansToRadians

gradiansToRadians :: Floating a => a -> a Source #

Convert gradians to radians by multiplying by pi/200.