Data.Quantities

This package is used to create and manipulate physical quantities, which are a numerical value associated with a unit of measurement.

In this package, values with units are represented with the Quantity type. Included is an expression parser and a huge list of predefined quantities with which to parse strings into a Quantity datatype. Once created, a quantity can be converted to different units or queried for its dimensionality. A user can also operate on quantities arithmetically, and doing so uses automatic unit conversion and simplifcation.

Constructors

Currently, one constructor is supported to create quantities: fromString. There is an included expression parser that can parse values and strings corresponding to builtin units. To view defined unit types, look at the source code for defaultDefString.

fromString :: String -> Either QuantityError Quantity

Create a Quantity by parsing a string. Uses an UndefinedUnitError for undefined units.

>>> fromString "25 m/s"
Right 25.0 meter / second
>>> fromString "fakeunit"
Left (UndefinedUnitError "fakeunit")

unitsFromString :: String -> Either QuantityError CompositeUnit

Parse units from a string. Equivalent to fmap units . fromString

>>> unitsFromString "N * s"
Right [newton,second]

data Quantity

Combination of magnitude and units.

Instances

Eq Quantity

Ord Quantity

Show Quantity

magnitude :: Quantity -> Double

Numerical magnitude of quantity.

>>> magnitude <$> fromString "100 N * m"
Right 100.0

units :: Quantity -> CompositeUnit

Units associated with quantity.

>>> units <$> fromString "3.4 m/s^2"
Right [meter,second ** -2.0]

type CompositeUnit = [SimpleUnit]

Collection of SimpleUnits. Represents combination of simple units.

data SimpleUnit

Representation of single unit. For example: "mm^2" is represented as

 SimpleUnit { symbol = "meter", prefix = "milli", power = 2.0 }

Instances

Eq SimpleUnit

Ord SimpleUnit

Show SimpleUnit

Conversion

These functions are used to convert quantities from one unit type to another.

convert :: Quantity -> CompositeUnit -> Either QuantityError Quantity

Convert quantity to given units.

>>> convert <$> fromString "m" <*> unitsFromString "ft"
Right (Right 3.280839895013123 foot)

convertBase :: Quantity -> Quantity

Convert a quantity to its base units.

>>> convertBase <$> fromString "newton"
Right 1000.0 gram meter / second ** 2.0

dimensionality :: Quantity -> CompositeUnit

Computes dimensionality of quantity.

>>> dimensionality <$> fromString "newton"
Right [length,mass,time ** -2.0]

Quantity arithmetic

Once created, quantities can be manipulated using the included arithmetic functions.

>>> let (Right x) = fromString "m/s"
>>> let (Right y) = fromString "mile/hr"
>>> x `multiplyQuants` y
1.0 meter mile / hour / second
>>> x `divideQuants` y
1.0 hour meter / mile / second
>>> x `addQuants` y
Right 1.4470399999999999 meter / second
>>> x `subtractQuants` y
Right 0.55296 meter / second
>>> x `exptQuants` 1.5
1.0 meter ** 1.5 / second ** 1.5

The functions multiplyQuants, divideQuants, and exptQuants change units, and the units of the result are reduced to simplest terms.

>>> x `divideQuants` x
1.0
>>> fmap (multiplyQuants x) $ fromString "s"
Right 1.0 meter
>>> x `exptQuants` 0
1.0

addQuants :: Quantity -> Quantity -> Either QuantityError Quantity

Adds two quantities. Second quantity is converted to units of first quantity.

subtractQuants :: Quantity -> Quantity -> Either QuantityError Quantity

Subtract two quantities. Second quantity is converted to units of first quantity.

multiplyQuants :: Quantity -> Quantity -> Quantity

Multiplies two quantities.

divideQuants :: Quantity -> Quantity -> Quantity

Divides two quantities.

exptQuants :: Quantity -> Double -> Quantity

Exponentiates a quantity with a double.

Error type

data QuantityError

Custom error type

Constructors

UndefinedUnitError String

Used when trying to parse an undefined unit.

DimensionalityError CompositeUnit CompositeUnit

Used when converting units that do not have the same dimensionality (example: convert meter to second).

UnitAlreadyDefinedError String

Used internally when defining units and a unit is already defined.

PrefixAlreadyDefinedError String

Used internally when defining units and a prefix is already defined.

ParserError String

Used when a string cannot be parsed.

Instances

Eq QuantityError

Show QuantityError

type QuantityComputation = Either QuantityError

Computation monad that propagates QuantityErrors. Some examples:

 computation :: QuantityComputation Quantity
 computation = do
   x <- fromString "mile/hr"
   y <- unitsFromString "m/s"
   convert x y

Returns Right 0.44704 meter / second

 computation :: QuantityComputation Quantity
 computation = do
   x <- fromString "BADUNIT"
   convertBase x

Returns Left (UndefinedUnitError BADUNIT)

comp :: QuantityComputation Quantity