-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Unit conversion and manipulation library.
--
-- A library for creating and manipulating physical quantities, which are
-- a numerical value associated with a unit of measurement. 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 simplification.
@package quantities
@version 0.4.0
-- | 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
-- simplification.
module Data.Quantities
-- | Create a Quantity by parsing a string. Uses an
-- UndefinedUnitError for undefined units. Handles arithmetic
-- expressions as well.
--
--
-- >>> fromString "25 m/s"
-- Right 25.0 meter / second
--
-- >>> fromString "fakeunit"
-- Left (UndefinedUnitError "fakeunit")
--
-- >>> fromString "ft + 12in"
-- Right 2.0 foot
--
--
-- This function also supports unit conversions, by placing "=>" in
-- between two valid expressions. This behavior is undefined (and returns
-- a ScalingFactorError) if the quantity to be converted to has a
-- magnitude.
--
--
-- >>> fromString "min => s"
-- Right 60.0 second
--
-- >>> fromString "2 ft + 6 in => ft"
-- Right 2.5 foot
--
-- >>> fromString "m => 3 ft"
-- Left (ScalingFactorError 3.0 foot)
--
--
-- Make sure not to use dimensional quantities in exponents.
--
--
-- >>> fromString "m ** 2"
-- Right 1.0 meter ** 2
--
-- >>> fromString "m ** (2s)"
-- Left (ParserError "Used non-dimensionless exponent in ( Right 1.0 meter ) ** ( Right 2.0 second )")
--
fromString :: String -> Either (QuantityError Double) (Quantity Double)
-- | Parse units from a string. Equivalent to fmap units .
-- fromString
--
--
-- >>> unitsFromString "N * s"
-- Right newton second
--
unitsFromString :: String -> Either (QuantityError Double) CompoundUnit
-- | Holds information about defined units, prefixes, and bases. Used when
-- parsing new units and performing units conversions.
data Definitions
-- | Combination of magnitude and units.
data Quantity a
-- | Numerical magnitude of quantity.
--
--
-- >>> magnitude <$> fromString "100 N * m"
-- Right 100.0
--
magnitude :: Quantity a -> a
-- | Units associated with quantity.
--
--
-- >>> units <$> fromString "3.4 m/s^2"
-- Right meter / second ** 2
--
units :: Quantity a -> CompoundUnit
-- | Data type to hold compound units, which are simple units multiplied
-- together.
data CompoundUnit
-- | Convert quantity to given units.
--
--
-- >>> convert <$> fromString "m" <*> unitsFromString "ft"
-- Right (Right 3.280839895013123 foot)
--
convert :: (Fractional a) => Quantity a -> CompoundUnit -> Either (QuantityError a) (Quantity a)
-- | Convert a quantity to its base units.
--
--
-- >>> convertBase <$> fromString "newton"
-- Right 1000.0 gram meter / second ** 2
--
convertBase :: (Fractional a) => Quantity a -> Quantity a
-- | Computes dimensionality of quantity.
--
--
-- >>> dimensionality <$> fromString "newton"
-- Right [length] [mass] / [time] ** 2
--
dimensionality :: Quantity a -> CompoundUnit
-- | Adds two quantities. Second quantity is converted to units of first
-- quantity.
addQuants :: (Fractional a) => Quantity a -> Quantity a -> Either (QuantityError a) (Quantity a)
-- | Subtract two quantities. Second quantity is converted to units of
-- first quantity.
subtractQuants :: (Fractional a) => Quantity a -> Quantity a -> Either (QuantityError a) (Quantity a)
-- | Multiplies two quantities.
multiplyQuants :: (Num a) => Quantity a -> Quantity a -> Quantity a
-- | Divides two quantities.
divideQuants :: (Fractional a) => Quantity a -> Quantity a -> Quantity a
-- | Exponentiates a quantity with an integer
exptQuants :: (Real a, Floating a) => Quantity a -> a -> Quantity a
-- | Create quantities with custom definitions.
--
--
-- >>> let myDefString = defaultDefString ++ "\nmy_unit = 100 s"
--
-- >>> let (Right d) = readDefinitions myDefString
--
-- >>> let myFromString = fromString' d
--
-- >>> myFromString "25 my_unit"
-- Right 25.0 my_unit
--
fromString' :: Definitions -> String -> Either (QuantityError Double) (Quantity Double)
-- | Convert string of definitions into Definitions structure. See
-- source code for defaultDefString for an example.
readDefinitions :: String -> Either (QuantityError Double) Definitions
-- | View the source code for this declaration to see what units and
-- prefixes are defined by default.
--
-- This string holds the definitions for units and prefixes. Base units
-- are defined by the name of the unit, the name of the base in brackets,
-- and any aliases for the unit after that, all separated by equal signs:
-- meter = [length] = m. Prefixes are defined by placing a dash
-- after all identifiers, and providing a value for the prefix:
-- milli- = 1e-3 = m-. Other units are defined by using
-- previously defined units in an expression: minute = 60 *
-- second = min.
--
-- The reason these definitions aren't placed in a text file is so you
-- don't have to operate your whole program in the IO monad. Users can
-- copy this file into their source and modify definitions, or simply add
-- a few definitions to the end of this string.
--
-- These definitions are taken almost verbatim from the Pint unit
-- conversion library for the Python programming language. Check them out
-- on GitHub.
defaultDefString :: String
-- | Custom error type
data QuantityError a
-- | Used when trying to parse an undefined unit.
UndefinedUnitError :: String -> QuantityError a
-- | Used when converting units that do not have the same dimensionality
-- (example: convert meter to second).
DimensionalityError :: CompoundUnit -> CompoundUnit -> QuantityError a
-- | Used internally when defining units and a unit is already defined.
UnitAlreadyDefinedError :: String -> QuantityError a
-- | Used internally when defining units and a prefix is already defined.
PrefixAlreadyDefinedError :: String -> QuantityError a
-- | Used when a string cannot be parsed.
ParserError :: String -> QuantityError a
-- | Used when two quantities come from different Definitions.
DifferentDefinitionsError :: CompoundUnit -> CompoundUnit -> QuantityError a
-- | Used when a scaling factor is present in a unit conversion.
ScalingFactorError :: (Quantity a) -> QuantityError a
-- | Useful for monadic computations with 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)
type QuantityComputation a = Either (QuantityError a)