-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Statically checked physical dimensions,
-- using Type Families and Data Kinds.
--
-- Dimensional is a library providing data types for performing
-- arithmetic with physical quantities and units. Information about the
-- physical dimensions of the quantities and units is embedded in their
-- types and the validity of operations is verified by the type checker
-- at compile time. The boxing and unboxing of numerical values as
-- quantities is done by multiplication and division with units. The
-- library is designed to, as far as is practical, enforce/encourage best
-- practices of unit usage. Version 1 of the dimensional package differs
-- from earlier version in that the dimension tracking is implemented
-- using Closed Type Families and Data Kinds rather than functional
-- dependencies. This enables a number of features, including improved
-- support for unit names and quantities with statically-unknown
-- dimensions. Requires GHC 8.0 or later.
@package dimensional
@version 1.2
-- | This module defines physical dimensions expressed in terms of the SI
-- base dimensions, including arithmetic.
module Numeric.Units.Dimensional.Dimensions.TermLevel
-- | A physical dimension, encoded as 7 integers, representing a
-- factorization of the dimension into the 7 SI base dimensions. By
-- convention they are stored in the same order as in the
-- Dimension data kind.
data Dimension'
Dim' :: !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> Dimension'
-- | Dimensional values inhabit this class, which allows access to a
-- term-level representation of their dimension.
class HasDynamicDimension a => HasDimension a
-- | Obtains a term-level representation of a value's dimension.
dimension :: HasDimension a => a -> Dimension'
-- | Dimensional values, or those that are only possibly dimensional,
-- inhabit this class, which allows access to a term-level representation
-- of their dimension.
class HasDynamicDimension a
-- | Gets the 'DynamicDimension of a dynamic dimensional value, which may
-- be NoDimension if it does not represent a dimensional value of
-- any Dimension.
--
-- A default implementation is available for types that are also in the
-- HasDimension typeclass.
dynamicDimension :: HasDynamicDimension a => a -> DynamicDimension
-- | Gets the 'DynamicDimension of a dynamic dimensional value, which may
-- be NoDimension if it does not represent a dimensional value of
-- any Dimension.
--
-- A default implementation is available for types that are also in the
-- HasDimension typeclass.
dynamicDimension :: (HasDynamicDimension a, HasDimension a) => a -> DynamicDimension
-- | The dimension of a dynamic value, which may not have any dimension at
-- all.
data DynamicDimension
-- | The value has no valid dimension.
NoDimension :: DynamicDimension
-- | The value has the given dimension.
SomeDimension :: Dimension' -> DynamicDimension
-- | The value may be interpreted as having any dimension.
AnyDimension :: DynamicDimension
-- | Forms the product of two dimensions.
(*) :: Dimension' -> Dimension' -> Dimension'
infixl 7 *
-- | Forms the quotient of two dimensions.
(/) :: Dimension' -> Dimension' -> Dimension'
infixl 7 /
-- | Raises a dimension to an integer power.
(^) :: Dimension' -> Int -> Dimension'
infixr 8 ^
-- | Forms the reciprocal of a dimension.
recip :: Dimension' -> Dimension'
-- | Takes the nth root of a dimension, if it exists.
--
-- n must not be zero.
--
--
-- nroot (negate n) d == nroot n (recip d)
--
nroot :: Int -> Dimension' -> Maybe Dimension'
-- | Takes the square root of a dimension, if it exists.
--
--
-- sqrt d == nroot 2 d
--
sqrt :: Dimension' -> Maybe Dimension'
-- | Takes the cube root of a dimension, if it exists.
--
--
-- cbrt d == nroot 3 d
--
cbrt :: Dimension' -> Maybe Dimension'
-- | The dimension of dimensionless values.
dOne :: Dimension'
dLength :: Dimension'
dMass :: Dimension'
dTime :: Dimension'
dElectricCurrent :: Dimension'
dThermodynamicTemperature :: Dimension'
dAmountOfSubstance :: Dimension'
dLuminousIntensity :: Dimension'
-- | Converts a dimension to a list of 7 integers, representing the
-- exponent associated with each of the 7 SI base dimensions in the
-- standard order.
asList :: Dimension' -> [Int]
-- | Combines two DynamicDimensions, determining the
-- DynamicDimension of a quantity that must match both inputs.
--
-- This is the lattice meet operation for DynamicDimension.
matchDimensions :: DynamicDimension -> DynamicDimension -> DynamicDimension
-- | Determines if a value that has a DynamicDimension is compatible
-- with a specified Dimension'.
isCompatibleWith :: HasDynamicDimension a => a -> Dimension' -> Bool
-- | Determines if a value that has a DynamicDimension in fact has
-- any valid dimension at all.
hasSomeDimension :: HasDynamicDimension a => a -> Bool
instance GHC.Generics.Generic Numeric.Units.Dimensional.Dimensions.TermLevel.DynamicDimension
instance Data.Data.Data Numeric.Units.Dimensional.Dimensions.TermLevel.DynamicDimension
instance GHC.Show.Show Numeric.Units.Dimensional.Dimensions.TermLevel.DynamicDimension
instance GHC.Classes.Ord Numeric.Units.Dimensional.Dimensions.TermLevel.DynamicDimension
instance GHC.Classes.Eq Numeric.Units.Dimensional.Dimensions.TermLevel.DynamicDimension
instance GHC.Generics.Generic Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
instance Data.Data.Data Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
instance GHC.Classes.Ord Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
instance GHC.Classes.Eq Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
instance GHC.Show.Show Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
instance Numeric.Units.Dimensional.Dimensions.TermLevel.HasDynamicDimension Numeric.Units.Dimensional.Dimensions.TermLevel.DynamicDimension
instance Numeric.Units.Dimensional.Dimensions.TermLevel.HasDynamicDimension Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
instance Numeric.Units.Dimensional.Dimensions.TermLevel.HasDimension Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
instance Control.DeepSeq.NFData Numeric.Units.Dimensional.Dimensions.TermLevel.DynamicDimension
instance Control.DeepSeq.NFData Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
instance GHC.Base.Semigroup Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
instance GHC.Base.Monoid Numeric.Units.Dimensional.Dimensions.TermLevel.Dimension'
-- | This module defines type-level physical dimensions expressed in terms
-- of the SI base dimensions using NumType for type-level
-- integers.
--
-- Type-level arithmetic, synonyms for the base dimensions, and
-- conversion to the term-level are included.
module Numeric.Units.Dimensional.Dimensions.TypeLevel
-- | Represents a physical dimension in the basis of the 7 SI base
-- dimensions, where the respective dimensions are represented by type
-- variables using the following convention:
--
--
-- - l: Length
-- - m: Mass
-- - t: Time
-- - i: Electric current
-- - th: Thermodynamic temperature
-- - n: Amount of substance
-- - j: Luminous intensity
--
--
-- For the equivalent term-level representation, see Dimension'
data Dimension
Dim :: TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> Dimension
-- | Multiplication of dimensions corresponds to adding of the base
-- dimensions' exponents.
type family (a :: Dimension) * (b :: Dimension)
infixl 7 *
-- | Division of dimensions corresponds to subtraction of the base
-- dimensions' exponents.
type family (a :: Dimension) / (d :: Dimension)
infixl 7 /
-- | Powers of dimensions corresponds to multiplication of the base
-- dimensions' exponents by the exponent.
--
-- We limit ourselves to integer powers of Dimensionals as fractional
-- powers make little physical sense.
type family (d :: Dimension) ^ (x :: TypeInt)
infixr 8 ^
-- | The reciprocal of a dimension is defined as the result of dividing
-- DOne by it, or of negating each of the base dimensions'
-- exponents.
type Recip (d :: Dimension) = DOne / d
-- | Roots of dimensions corresponds to division of the base dimensions'
-- exponents by the order of the root.
type family NRoot (d :: Dimension) (x :: TypeInt)
-- | Square root is a special case of NRoot with order 2.
type Sqrt d = NRoot d 'Pos2
-- | Cube root is a special case of NRoot with order 3.
type Cbrt d = NRoot d 'Pos3
-- | The type-level dimension of dimensionless values.
type DOne = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
type DLength = 'Dim 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
type DMass = 'Dim 'Zero 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero
type DTime = 'Dim 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero 'Zero
type DElectricCurrent = 'Dim 'Zero 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero
type DThermodynamicTemperature = 'Dim 'Zero 'Zero 'Zero 'Zero 'Pos1 'Zero 'Zero
type DAmountOfSubstance = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1 'Zero
type DLuminousIntensity = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1
-- | A KnownDimension is one for which we can construct a term-level
-- representation. Each validly constructed type of kind Dimension
-- has a KnownDimension instance.
--
-- While KnownDimension is a constraint synonym, the presence of
-- KnownDimension d in a context allows use of
-- dimension :: Proxy d -> Dimension'.
type KnownDimension (d :: Dimension) = HasDimension (Proxy d)
instance (Numeric.NumType.DK.Integers.KnownTypeInt l, Numeric.NumType.DK.Integers.KnownTypeInt m, Numeric.NumType.DK.Integers.KnownTypeInt t, Numeric.NumType.DK.Integers.KnownTypeInt i, Numeric.NumType.DK.Integers.KnownTypeInt th, Numeric.NumType.DK.Integers.KnownTypeInt n, Numeric.NumType.DK.Integers.KnownTypeInt j) => Numeric.Units.Dimensional.Dimensions.TermLevel.HasDynamicDimension (Data.Proxy.Proxy ('Numeric.Units.Dimensional.Dimensions.TypeLevel.Dim l m t i th n j))
instance (Numeric.NumType.DK.Integers.KnownTypeInt l, Numeric.NumType.DK.Integers.KnownTypeInt m, Numeric.NumType.DK.Integers.KnownTypeInt t, Numeric.NumType.DK.Integers.KnownTypeInt i, Numeric.NumType.DK.Integers.KnownTypeInt th, Numeric.NumType.DK.Integers.KnownTypeInt n, Numeric.NumType.DK.Integers.KnownTypeInt j) => Numeric.Units.Dimensional.Dimensions.TermLevel.HasDimension (Data.Proxy.Proxy ('Numeric.Units.Dimensional.Dimensions.TypeLevel.Dim l m t i th n j))
-- | Provides both term-level and type-level representations for physical
-- dimensions in a single import for convenience.
--
-- Presuming that users intend to work primarily with type level
-- dimensions, this module hides arithmetic operators over term level
-- dimensions and aliases for the base term-level dimensions to avoid
-- namespace pollution. These features are available directly from
-- Numeric.Units.Dimensional.Dimensions.TermLevel if desired.
module Numeric.Units.Dimensional.Dimensions
-- | Dimensional values inhabit this class, which allows access to a
-- term-level representation of their dimension.
class HasDynamicDimension a => HasDimension a
-- | Obtains a term-level representation of a value's dimension.
dimension :: HasDimension a => a -> Dimension'
-- | Dimensional values, or those that are only possibly dimensional,
-- inhabit this class, which allows access to a term-level representation
-- of their dimension.
class HasDynamicDimension a
-- | Gets the 'DynamicDimension of a dynamic dimensional value, which may
-- be NoDimension if it does not represent a dimensional value of
-- any Dimension.
--
-- A default implementation is available for types that are also in the
-- HasDimension typeclass.
dynamicDimension :: HasDynamicDimension a => a -> DynamicDimension
-- | Gets the 'DynamicDimension of a dynamic dimensional value, which may
-- be NoDimension if it does not represent a dimensional value of
-- any Dimension.
--
-- A default implementation is available for types that are also in the
-- HasDimension typeclass.
dynamicDimension :: (HasDynamicDimension a, HasDimension a) => a -> DynamicDimension
-- | The dimension of a dynamic value, which may not have any dimension at
-- all.
data DynamicDimension
-- | The value has no valid dimension.
NoDimension :: DynamicDimension
-- | The value has the given dimension.
SomeDimension :: Dimension' -> DynamicDimension
-- | The value may be interpreted as having any dimension.
AnyDimension :: DynamicDimension
-- | A physical dimension, encoded as 7 integers, representing a
-- factorization of the dimension into the 7 SI base dimensions. By
-- convention they are stored in the same order as in the
-- Dimension data kind.
data Dimension'
Dim' :: !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> Dimension'
-- | Combines two DynamicDimensions, determining the
-- DynamicDimension of a quantity that must match both inputs.
--
-- This is the lattice meet operation for DynamicDimension.
matchDimensions :: DynamicDimension -> DynamicDimension -> DynamicDimension
-- | Determines if a value that has a DynamicDimension is compatible
-- with a specified Dimension'.
isCompatibleWith :: HasDynamicDimension a => a -> Dimension' -> Bool
-- | Determines if a value that has a DynamicDimension in fact has
-- any valid dimension at all.
hasSomeDimension :: HasDynamicDimension a => a -> Bool
-- | The dimension of dimensionless values.
dOne :: Dimension'
-- | Converts a dimension to a list of 7 integers, representing the
-- exponent associated with each of the 7 SI base dimensions in the
-- standard order.
asList :: Dimension' -> [Int]
module Numeric.Units.Dimensional.UnitNames.InterchangeNames
-- | Represents the authority which issued an interchange name for a unit.
data InterchangeNameAuthority
-- | The interchange name originated with the Unified Code for Units of
-- Measure.
UCUM :: InterchangeNameAuthority
-- | The interchange name originated with the dimensional library.
DimensionalLibrary :: InterchangeNameAuthority
-- | The interchange name originated with a user of the dimensional
-- library.
Custom :: InterchangeNameAuthority
data InterchangeName
InterchangeName :: String -> InterchangeNameAuthority -> Bool -> InterchangeName
[name] :: InterchangeName -> String
[authority] :: InterchangeName -> InterchangeNameAuthority
[isAtomic] :: InterchangeName -> Bool
-- | Determines the authority which issued the interchange name of a unit
-- or unit name. For composite units, this is the least-authoritative
-- interchange name of any constituent name.
--
-- Note that the least-authoritative authority is the one sorted as
-- greatest by the Ord instance of
-- InterchangeNameAuthority.
class HasInterchangeName a
interchangeName :: HasInterchangeName a => a -> InterchangeName
instance GHC.Generics.Generic Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeName
instance Data.Data.Data Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeName
instance GHC.Classes.Ord Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeName
instance GHC.Classes.Eq Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeName
instance GHC.Generics.Generic Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeNameAuthority
instance Data.Data.Data Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeNameAuthority
instance GHC.Show.Show Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeNameAuthority
instance GHC.Classes.Ord Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeNameAuthority
instance GHC.Classes.Eq Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeNameAuthority
instance Numeric.Units.Dimensional.UnitNames.InterchangeNames.HasInterchangeName Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeName
instance Control.DeepSeq.NFData Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeName
instance GHC.Show.Show Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeName
instance Control.DeepSeq.NFData Numeric.Units.Dimensional.UnitNames.InterchangeNames.InterchangeNameAuthority
-- | Provides a type level representation of Variants of dimensional
-- values, which may be quantities or units.
module Numeric.Units.Dimensional.Variants
-- | The kind of variants of dimensional values.
data Variant
-- | The value is a quantity, stored as an ExactPi multiple of its
-- value in its dimension's SI coherent unit.
DQuantity :: ExactPi' -> Variant
-- | The value is a unit, possibly a Metric unit.
DUnit :: Metricality -> Variant
-- | Encodes whether a unit is a metric unit, that is, whether it can be
-- combined with a metric prefix to form a related unit.
data Metricality
-- | Capable of receiving a metric prefix.
Metric :: Metricality
-- | Incapable of receiving a metric prefix.
NonMetric :: Metricality
-- | Forms the product of two Variants.
--
-- The product of units is a non-metric unit.
--
-- The product of quantities is a quantity.
type family (v1 :: Variant) * (v2 :: Variant) :: Variant
infixl 7 *
type family (v1 :: Variant) / (v2 :: Variant) :: Variant
-- | Weakens a Variant by forgetting possibly uninteresting
-- type-level information.
type family Weaken (v :: Variant) :: Variant
-- | Two Variants are compatible when dimensional values of the
-- first may be converted into the second merely by changing the
-- representation of their values.
type CompatibleVariants v1 v2 = ( 'True ~ AreCompatible v1 v2)
instance GHC.Generics.Generic Numeric.Units.Dimensional.Variants.Variant
instance GHC.Generics.Generic Numeric.Units.Dimensional.Variants.Metricality
instance Data.Data.Data Numeric.Units.Dimensional.Variants.Metricality
instance GHC.Classes.Ord Numeric.Units.Dimensional.Variants.Metricality
instance GHC.Classes.Eq Numeric.Units.Dimensional.Variants.Metricality
instance Control.DeepSeq.NFData Numeric.Units.Dimensional.Variants.Metricality
-- | This module provides types and functions for manipulating unit names.
--
-- Please note that the details of the name representation may be less
-- stable than the other APIs provided by this package, as new features
-- using them are still being developed.
module Numeric.Units.Dimensional.UnitNames
-- | The name of a unit.
data UnitName (m :: Metricality)
-- | Represents the name of an atomic unit or prefix.
data NameAtom (m :: NameAtomType)
data Prefix
-- | The name of a metric prefix.
type PrefixName = NameAtom 'PrefixAtom
-- | Encodes whether a unit is a metric unit, that is, whether it can be
-- combined with a metric prefix to form a related unit.
data Metricality
-- | Capable of receiving a metric prefix.
Metric :: Metricality
-- | Incapable of receiving a metric prefix.
NonMetric :: Metricality
-- | Constructs an atomic name for a custom unit.
atom :: String -> String -> String -> UnitName 'NonMetric
-- | Forms a UnitName from a Metric name by applying a metric
-- prefix.
applyPrefix :: Prefix -> UnitName 'Metric -> UnitName 'NonMetric
-- | Form a UnitName by taking the product of two others.
(*) :: UnitName m1 -> UnitName m2 -> UnitName 'NonMetric
infixl 7 *
-- | Form a UnitName by dividing one by another.
(/) :: UnitName m1 -> UnitName m2 -> UnitName 'NonMetric
infixl 7 /
-- | Form a UnitName by raising a name to an integer power.
(^) :: UnitName m -> Int -> UnitName 'NonMetric
infixr 8 ^
-- | Forms the product of a list of UnitNames.
--
-- If you wish to form a heterogenous product of Metric and
-- NonMetric units you should apply weaken to the
-- Metric ones.
product :: Foldable f => f (UnitName 'NonMetric) -> UnitName 'NonMetric
reduce :: UnitName m -> UnitName m
-- | Constructs a UnitName by applying a grouping operation to
-- another UnitName, which may be useful to express precedence.
grouped :: UnitName m -> UnitName 'NonMetric
-- | The name of the base unit associated with a specified dimension.
baseUnitName :: Dimension' -> UnitName 'NonMetric
-- | A list of all Prefixes defined by the SI.
siPrefixes :: [Prefix]
-- | The name of the unit of dimensionless values.
nOne :: UnitName 'NonMetric
-- | The name of a metric prefix.
prefixName :: Prefix -> PrefixName
-- | The scale factor denoted by a metric prefix.
scaleFactor :: Prefix -> Rational
-- | The type of a unit name transformation that may be associated with an
-- operation that takes a single unit as input.
type UnitNameTransformer = (forall m. UnitName m -> UnitName 'NonMetric)
-- | The type of a unit name transformation that may be associated with an
-- operation that takes two units as input.
type UnitNameTransformer2 = (forall m1 m2. UnitName m1 -> UnitName m2 -> UnitName 'NonMetric)
-- | Convert a UnitName which may or may not be Metric to one
-- which is certainly NonMetric.
weaken :: UnitName m -> UnitName 'NonMetric
-- | Attempt to convert a UnitName which may or may not be
-- Metric to one which is certainly Metric.
strengthen :: UnitName m -> Maybe (UnitName 'Metric)
-- | Convert a UnitName of one Metricality into a name of
-- another metricality by strengthening or weakening if neccessary.
-- Because it may not be possible to strengthen, the result is returned
-- in a Maybe wrapper.
relax :: forall m1 m2. (Typeable m1, Typeable m2) => UnitName m1 -> Maybe (UnitName m2)
-- | The full name of the unit in international English
name_en :: NameAtom m -> String
-- | The abbreviated name of the unit in international English
abbreviation_en :: NameAtom m -> String
asAtomic :: UnitName m -> Maybe (NameAtom ( 'UnitAtom m))
-- | Re-exports the raw Quantity constructor from the
-- Numeric.Units.Dimensional.Internal module, along with coerce,
-- for convenience in converting between raw representations and
-- dimensional values.
--
-- Note that use of these constructs requires the user to verify the
-- dimensional safety of the conversion, because the coercion doesn't
-- explicitly mention the unit of the representation. Note also that the
-- Quantity constructor constructs a SQuantity which may
-- have a scale factor other than One.
--
-- Note that the haddock documentation doesn't mention the
-- Quantity constructor because it is a part of the
-- Dimensional associated data family, but it is exported by this
-- module.
module Numeric.Units.Dimensional.Coercion
-- | The function coerce allows you to safely convert between
-- values of types that have the same representation with no run-time
-- overhead. In the simplest case you can use it instead of a newtype
-- constructor, to go from the newtype's concrete type to the abstract
-- type. But it also works in more complicated settings, e.g. converting
-- a list of newtypes to a list of concrete types.
coerce :: Coercible a b => a -> b
-- | A dimensional value, either a Quantity or a Unit,
-- parameterized by its Dimension and representation.
data family Dimensional v :: Dimension -> Type -> Type
-- | Unwraps a possibly-scaled SQuantity, yielding its underlying
-- representation.
--
-- This is a type-restricted version of coerce.
unQuantity :: SQuantity s d a -> a
-- | Summary
--
-- In this module we provide data types for performing arithmetic with
-- physical quantities and units. Information about the physical
-- dimensions of the quantities/units is embedded in their types and the
-- validity of operations is verified by the type checker at compile
-- time. The boxing and unboxing of numerical values as quantities is
-- done by multiplication and division of units, of which an incomplete
-- set is provided.
--
-- We limit ourselves to "Newtonian" physics. We do not attempt to
-- accommodate relativistic physics in which e.g. addition of length and
-- time would be valid.
--
-- As far as possible and/or practical the conventions and guidelines of
-- NIST's "Guide for the Use of the International System of Units (SI)"
-- [1] are followed. Occasionally we will reference specific
-- sections from the guide and deviations will be explained.
--
-- Disclaimer
--
-- Merely an engineer, the author doubtlessly uses a language and
-- notation that makes mathematicians and physicist cringe. He does not
-- mind constructive criticism (or pull requests).
--
-- The sets of functions and units defined herein are incomplete and
-- reflect only the author's needs to date. Again, patches are welcome.
--
-- Usage
--
-- Preliminaries
--
-- This module requires GHC 7.8 or later. We utilize Data Kinds,
-- TypeNats, Closed Type Families, etc. Clients of the module are
-- generally not required to use these extensions.
--
-- Clients probably will want to use the NegativeLiterals extension.
--
-- Examples
--
-- We have defined operators and units that allow us to define and work
-- with physical quantities. A physical quantity is defined by
-- multiplying a number with a unit (the type signature is optional).
--
--
-- v :: Velocity Prelude.Double
-- v = 90 *~ (kilo meter / hour)
--
--
-- It follows naturally that the numerical value of a quantity is
-- obtained by division by a unit.
--
--
-- numval :: Prelude.Double
-- numval = v /~ (meter / second)
--
--
-- The notion of a quantity as the product of a numerical value and a
-- unit is supported by 7.1 "Value and numerical value of a quantity" of
-- [1]. While the above syntax is fairly natural it is unfortunate
-- that it must violate a number of the guidelines in [1], in
-- particular 9.3 "Spelling unit names with prefixes", 9.4 "Spelling unit
-- names obtained by multiplication", 9.5 "Spelling unit names obtained
-- by division".
--
-- As a more elaborate example of how to use the module we define a
-- function for calculating the escape velocity of a celestial body
-- [2].
--
--
-- escapeVelocity :: (Floating a) => Mass a -> Length a -> Velocity a
-- escapeVelocity m r = sqrt (two * g * m / r)
-- where
-- two = 2 *~ one
-- g = 6.6720e-11 *~ (newton * meter ^ pos2 / kilo gram ^ pos2)
--
--
-- For completeness we should also show an example of the error messages
-- we will get from GHC when performing invalid arithmetic. In the best
-- case GHC will be able to use the type synonyms we have defined in its
-- error messages.
--
--
-- let x = 1 *~ meter + 1 *~ second
--
-- Couldn't match type 'Numeric.NumType.DK.Integers.Zero
-- with 'Numeric.NumType.DK.Integers.Pos1
-- Expected type: Unit 'Metric DLength a
-- Actual type: Unit 'Metric DTime a
-- In the second argument of `(*~)', namely `second'
-- In the second argument of `(+)', namely `1 *~ second'
--
--
-- In other cases the error messages aren't very friendly.
--
--
-- let x = 1 *~ meter / (1 *~ second) + 1 *~ kilo gram
--
-- Couldn't match type 'Numeric.NumType.DK.Integers.Zero
-- with 'Numeric.NumType.DK.Integers.Neg1
-- Expected type: Quantity DMass a
-- Actual type: Dimensional
-- ('DQuantity V.* 'DQuantity) (DLength / DTime) a
-- In the first argument of `(+)', namely `1 *~ meter / (1 *~ second)'
-- In the expression: 1 *~ meter / (1 *~ second) + 1 *~ kilo gram
-- In an equation for `x':
-- x = 1 *~ meter / (1 *~ second) + 1 *~ kilo gram
--
--
-- It is the author's experience that the usefulness of the compiler
-- error messages is more often than not limited to pinpointing the
-- location of errors.
--
-- Notes
--
-- Future work
--
-- While there is an insane amount of units in use around the world it is
-- reasonable to provide those in relatively widespread use. Units
-- outside of SI will most likely be added on an as-needed basis.
--
-- Additional physics models could be implemented. See [3] for
-- ideas.
--
-- Related work
--
-- Henning Thielemann numeric prelude has a physical units library,
-- however, checking of dimensions is dynamic rather than static. Aaron
-- Denney has created a toy example of statically checked physical
-- dimensions covering only length and time. HaskellWiki has pointers
-- [4] to these.
--
-- Also see Samuel Hoffstaetter's blog post [5] which uses
-- techniques similar to this library.
--
-- Libraries with similar functionality exist for other programming
-- languages and may serve as inspiration. The author has found the Java
-- library JScience [6] and the Fortress programming language
-- [7] particularly noteworthy.
--
-- References
--
--
-- - http://physics.nist.gov/Pubs/SP811/
-- - http://en.wikipedia.org/wiki/Escape_velocity
--
-- - http://jscience.org/api/org/jscience/physics/models/package-summary.html
-- - http://www.haskell.org/haskellwiki/Physical_units
--
-- - http://liftm.wordpress.com/2007/06/03/scientificdimension-type-arithmetic-and-physical-units-in-haskell/
-- - http://jscience.org/
-- - http://research.sun.com/projects/plrg/fortress.pdf
--
module Numeric.Units.Dimensional
-- | A dimensional value, either a Quantity or a Unit,
-- parameterized by its Dimension and representation.
data family Dimensional v :: Dimension -> Type -> Type
-- | A unit of measurement.
type Unit (m :: Metricality) = Dimensional ( 'DUnit m)
-- | A dimensional quantity.
type Quantity = SQuantity One
-- | Encodes whether a unit is a metric unit, that is, whether it can be
-- combined with a metric prefix to form a related unit.
data Metricality
-- | Capable of receiving a metric prefix.
Metric :: Metricality
-- | Incapable of receiving a metric prefix.
NonMetric :: Metricality
-- | Represents a physical dimension in the basis of the 7 SI base
-- dimensions, where the respective dimensions are represented by type
-- variables using the following convention:
--
--
-- - l: Length
-- - m: Mass
-- - t: Time
-- - i: Electric current
-- - th: Thermodynamic temperature
-- - n: Amount of substance
-- - j: Luminous intensity
--
--
-- For the equivalent term-level representation, see Dimension'
data Dimension
Dim :: TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> Dimension
-- | Multiplication of dimensions corresponds to adding of the base
-- dimensions' exponents.
type family (a :: Dimension) * (b :: Dimension)
infixl 7 *
-- | Division of dimensions corresponds to subtraction of the base
-- dimensions' exponents.
type family (a :: Dimension) / (d :: Dimension)
infixl 7 /
-- | Powers of dimensions corresponds to multiplication of the base
-- dimensions' exponents by the exponent.
--
-- We limit ourselves to integer powers of Dimensionals as fractional
-- powers make little physical sense.
type family (d :: Dimension) ^ (x :: TypeInt)
infixr 8 ^
-- | Roots of dimensions corresponds to division of the base dimensions'
-- exponents by the order of the root.
type family NRoot (d :: Dimension) (x :: TypeInt)
-- | Square root is a special case of NRoot with order 2.
type Sqrt d = NRoot d 'Pos2
-- | Cube root is a special case of NRoot with order 3.
type Cbrt d = NRoot d 'Pos3
-- | The reciprocal of a dimension is defined as the result of dividing
-- DOne by it, or of negating each of the base dimensions'
-- exponents.
type Recip (d :: Dimension) = DOne / d
-- | A physical dimension, encoded as 7 integers, representing a
-- factorization of the dimension into the 7 SI base dimensions. By
-- convention they are stored in the same order as in the
-- Dimension data kind.
data Dimension'
Dim' :: !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> Dimension'
-- | Dimensional values inhabit this class, which allows access to a
-- term-level representation of their dimension.
class HasDynamicDimension a => HasDimension a
-- | Obtains a term-level representation of a value's dimension.
dimension :: HasDimension a => a -> Dimension'
-- | A KnownDimension is one for which we can construct a term-level
-- representation. Each validly constructed type of kind Dimension
-- has a KnownDimension instance.
--
-- While KnownDimension is a constraint synonym, the presence of
-- KnownDimension d in a context allows use of
-- dimension :: Proxy d -> Dimension'.
type KnownDimension (d :: Dimension) = HasDimension (Proxy d)
-- | Forms a Quantity by multipliying a number and a unit.
(*~) :: Num a => a -> Unit m d a -> Quantity d a
infixl 7 *~
-- | Divides a Quantity by a Unit of the same physical
-- dimension, obtaining the numerical value of the quantity expressed in
-- that unit.
(/~) :: Fractional a => Quantity d a -> Unit m d a -> a
infixl 7 /~
-- | Raises a Quantity or Unit to an integer power.
--
-- Because the power chosen impacts the Dimension of the result,
-- it is necessary to supply a type-level representation of the exponent
-- in the form of a Proxy to some TypeInt. Convenience
-- values pos1, pos2, neg1, ... are supplied by
-- the Numeric.NumType.DK.Integers module. The most commonly used
-- ones are also reexported by Numeric.Units.Dimensional.Prelude.
--
-- The intimidating type signature captures the similarity between these
-- operations and ensures that composite Units are
-- NotPrefixable.
(^) :: (Fractional a, KnownTypeInt i, KnownVariant v, KnownVariant (Weaken v)) => Dimensional v d1 a -> Proxy i -> Dimensional (Weaken v) (d1 ^ i) a
infixr 8 ^
-- | Computes the nth root of a Quantity using **.
--
-- The NRoot type family will prevent application of this operator
-- where the result would have a fractional dimension or where n is zero.
--
-- Because the root chosen impacts the Dimension of the result, it
-- is necessary to supply a type-level representation of the root in the
-- form of a Proxy to some TypeInt. Convenience values
-- pos1, pos2, neg1, ... are supplied by the
-- Numeric.NumType.DK.Integers module. The most commonly used ones
-- are also reexported by Numeric.Units.Dimensional.Prelude.
--
-- Also available in prefix form, see nroot.
(^/) :: (KnownTypeInt n, Floating a) => Quantity d a -> Proxy n -> Quantity (NRoot d n) a
infixr 8 ^/
-- | Raises a dimensionless quantity to a dimensionless power.
(**) :: Floating a => Dimensionless a -> Dimensionless a -> Dimensionless a
infixr 8 **
-- | Multiplies two Quantitys or two Units.
--
-- The intimidating type signature captures the similarity between these
-- operations and ensures that composite Units are
-- NonMetric.
(*) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 * v2), Num a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 * v2) (d1 * d2) a
infixl 7 *
-- | Divides one Quantity by another or one Unit by another.
--
-- The intimidating type signature captures the similarity between these
-- operations and ensures that composite Units are
-- NotPrefixable.
(/) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 / v2), Fractional a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 / v2) (d1 / d2) a
infixl 7 /
-- | Adds two Quantitys.
(+) :: Num a => Quantity d a -> Quantity d a -> Quantity d a
infixl 6 +
-- | Subtracts one Quantity from another.
(-) :: Num a => Quantity d a -> Quantity d a -> Quantity d a
infixl 6 -
-- | Negates the value of a Quantity.
negate :: Num a => Quantity d a -> Quantity d a
-- | Takes the absolute value of a Quantity.
abs :: Num a => Quantity d a -> Quantity d a
-- | Takes the sign of a Quantity. The functions abs and
-- signum satisy the law that:
--
--
-- abs x * signum x == x
--
--
-- The sign is either negate _1 (negative), _0 (zero),
-- or _1 (positive).
signum :: Num a => Quantity d a -> Dimensionless a
-- | Forms the reciprocal of a Quantity, which has the reciprocal
-- dimension.
--
--
-- >>> recip $ 47 *~ hertz
-- 2.127659574468085e-2 s
--
recip :: Fractional a => Quantity d a -> Quantity (Recip d) a
-- | Computes the nth root of a Quantity using **.
--
-- The NRoot type family will prevent application of this operator
-- where the result would have a fractional dimension or where n is zero.
--
-- Because the root chosen impacts the Dimension of the result, it
-- is necessary to supply a type-level representation of the root in the
-- form of a Proxy to some TypeInt. Convenience values
-- pos1, pos2, neg1, ... are supplied by the
-- Numeric.NumType.DK.Integers module. The most commonly used ones
-- are also reexported by Numeric.Units.Dimensional.Prelude.
--
-- n must not be zero. Negative roots are defined such that nroot
-- (Proxy :: Proxy (Negate n)) x == nroot (Proxy :: Proxy n) (recip
-- x).
--
-- Also available in operator form, see ^/.
nroot :: (KnownTypeInt n, Floating a) => Proxy n -> Quantity d a -> Quantity (NRoot d n) a
-- | Computes the square root of a Quantity using **.
--
-- The NRoot type family will prevent application where the
-- supplied quantity does not have a square dimension.
--
--
-- (x :: Area Double) >= _0 ==> sqrt x == nroot pos2 x
--
sqrt :: Floating a => Quantity d a -> Quantity (Sqrt d) a
-- | Computes the cube root of a Quantity using **.
--
-- The NRoot type family will prevent application where the
-- supplied quantity does not have a cubic dimension.
--
--
-- (x :: Volume Double) >= _0 ==> cbrt x == nroot pos3 x
--
cbrt :: Floating a => Quantity d a -> Quantity (Cbrt d) a
exp :: Floating a => Dimensionless a -> Dimensionless a
log :: Floating a => Dimensionless a -> Dimensionless a
-- | Takes the logarithm of the second argument in the base of the first.
--
--
-- >>> logBase _2 _8
-- 3.0
--
logBase :: Floating a => Dimensionless a -> Dimensionless a -> Dimensionless a
sin :: Floating a => Dimensionless a -> Dimensionless a
cos :: Floating a => Dimensionless a -> Dimensionless a
tan :: Floating a => Dimensionless a -> Dimensionless a
asin :: Floating a => Dimensionless a -> Dimensionless a
acos :: Floating a => Dimensionless a -> Dimensionless a
atan :: Floating a => Dimensionless a -> Dimensionless a
sinh :: Floating a => Dimensionless a -> Dimensionless a
cosh :: Floating a => Dimensionless a -> Dimensionless a
tanh :: Floating a => Dimensionless a -> Dimensionless a
asinh :: Floating a => Dimensionless a -> Dimensionless a
acosh :: Floating a => Dimensionless a -> Dimensionless a
atanh :: Floating a => Dimensionless a -> Dimensionless a
-- | The standard two argument arctangent function. Since it interprets its
-- two arguments in comparison with one another, the input may have any
-- dimension.
--
--
-- >>> atan2 _0 _1
-- 0.0
--
--
--
-- >>> atan2 _1 _0
-- 1.5707963267948966
--
--
--
-- >>> atan2 _0 (negate _1)
-- 3.141592653589793
--
--
--
-- >>> atan2 (negate _1) _0
-- -1.5707963267948966
--
atan2 :: RealFloat a => Quantity d a -> Quantity d a -> Dimensionless a
-- | Applies *~ to all values in a functor.
(*~~) :: (Functor f, Num a) => f a -> Unit m d a -> f (Quantity d a)
infixl 7 *~~
-- | Applies /~ to all values in a functor.
(/~~) :: forall f m d a. (Functor f, Fractional a) => f (Quantity d a) -> Unit m d a -> f a
infixl 7 /~~
-- | The sum of all elements in a foldable structure.
--
--
-- >>> sum ([] :: [Mass Double])
-- 0.0 kg
--
--
--
-- >>> sum [12.4 *~ meter, 1 *~ foot]
-- 12.7048 m
--
sum :: (Num a, Foldable f) => f (Quantity d a) -> Quantity d a
-- | The arithmetic mean of all elements in a foldable structure.
--
--
-- >>> mean [pi, _7]
-- 5.070796326794897
--
mean :: (Fractional a, Foldable f) => f (Quantity d a) -> Quantity d a
-- | The product of all elements in a foldable structure.
--
--
-- >>> product ([] :: [Dimensionless Double])
-- 1.0
--
--
--
-- >>> product [pi, _4, 0.36 *~ one]
-- 4.523893421169302
--
product :: (Num a, Foldable f) => f (Dimensionless a) -> Dimensionless a
-- | The length of the foldable data structure as a Dimensionless.
-- This can be useful for purposes of e.g. calculating averages.
--
--
-- >>> dimensionlessLength ["foo", "bar"]
-- 2
--
dimensionlessLength :: (Num a, Foldable f) => f b -> Dimensionless a
-- | Returns a list of quantities between given bounds.
--
--
-- n <= 0 ==> nFromTo (x :: Mass Double) (y :: Mass Double) n == [x, y]
--
--
--
-- (x :: Length Double) <= (y :: Length Double) ==> all (\z -> x <= z && z <= y) (nFromTo x y n)
--
--
--
-- >>> nFromTo _0 _3 2
-- [0.0,1.0,2.0,3.0]
--
--
--
-- >>> nFromTo _1 _0 7
-- [1.0,0.875,0.75,0.625,0.5,0.375,0.25,0.125,0.0]
--
--
--
-- >>> nFromTo _0 _1 (-5)
-- [0.0,1.0]
--
nFromTo :: (Fractional a, Integral b) => Quantity d a -> Quantity d a -> b -> [Quantity d a]
-- | The type-level dimension of dimensionless values.
type DOne = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
type DLength = 'Dim 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
type DMass = 'Dim 'Zero 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero
type DTime = 'Dim 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero 'Zero
type DElectricCurrent = 'Dim 'Zero 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero
type DThermodynamicTemperature = 'Dim 'Zero 'Zero 'Zero 'Zero 'Pos1 'Zero 'Zero
type DAmountOfSubstance = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1 'Zero
type DLuminousIntensity = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1
type Dimensionless = Quantity DOne
type Length = Quantity DLength
type Mass = Quantity DMass
type Time = Quantity DTime
type ElectricCurrent = Quantity DElectricCurrent
type ThermodynamicTemperature = Quantity DThermodynamicTemperature
type AmountOfSubstance = Quantity DAmountOfSubstance
type LuminousIntensity = Quantity DLuminousIntensity
-- | The constant for zero is polymorphic, allowing it to express zero
-- Length or Capacitance or Velocity etc, in
-- addition to the Dimensionless value zero.
_0 :: Num a => Quantity d a
_1 :: Num a => Dimensionless a
_2 :: Num a => Dimensionless a
_3 :: Num a => Dimensionless a
_4 :: Num a => Dimensionless a
_5 :: Num a => Dimensionless a
_6 :: Num a => Dimensionless a
_7 :: Num a => Dimensionless a
_8 :: Num a => Dimensionless a
_9 :: Num a => Dimensionless a
pi :: Floating a => Dimensionless a
-- | Twice pi.
--
-- For background on tau see
-- http://tauday.com/tau-manifesto (but also feel free to review
-- http://www.thepimanifesto.com).
tau :: Floating a => Dimensionless a
-- | A polymorphic Unit which can be used in place of the coherent
-- SI base unit of any dimension. This allows polymorphic quantity
-- creation and destruction without exposing the Dimensional
-- constructor.
siUnit :: forall d a. (KnownDimension d, Num a) => Unit 'NonMetric d a
-- | The unit one has dimension DOne and is the base unit of
-- dimensionless values.
--
-- As detailed in 7.10 "Values of quantities expressed simply as numbers:
-- the unit one, symbol 1" of [1] the unit one generally does not
-- appear in expressions. However, for us it is necessary to use
-- one as we would any other unit to perform the "boxing" of
-- dimensionless values.
one :: Num a => Unit 'NonMetric DOne a
-- | Forms a new atomic Unit by specifying its UnitName and
-- its definition as a multiple of another Unit.
--
-- Use this variant when the scale factor of the resulting unit is
-- irrational or Approximate. See mkUnitQ for when it is
-- rational and mkUnitZ for when it is an integer.
--
-- Note that supplying zero as a definining quantity is invalid, as the
-- library relies upon units forming a group under multiplication.
--
-- Supplying negative defining quantities is allowed and handled
-- gracefully, but is discouraged on the grounds that it may be
-- unexpected by other readers.
mkUnitR :: Floating a => UnitName m -> ExactPi -> Unit m1 d a -> Unit m d a
-- | Forms a new atomic Unit by specifying its UnitName and
-- its definition as a multiple of another Unit.
--
-- Use this variant when the scale factor of the resulting unit is
-- rational. See mkUnitZ for when it is an integer and
-- mkUnitR for the general case.
--
-- For more information see mkUnitR.
mkUnitQ :: Fractional a => UnitName m -> Rational -> Unit m1 d a -> Unit m d a
-- | Forms a new atomic Unit by specifying its UnitName and
-- its definition as a multiple of another Unit.
--
-- Use this variant when the scale factor of the resulting unit is an
-- integer. See mkUnitQ for when it is rational and mkUnitR
-- for the general case.
--
-- For more information see mkUnitR.
mkUnitZ :: Num a => UnitName m -> Integer -> Unit m1 d a -> Unit m d a
-- | Extracts the UnitName of a Unit.
name :: Unit m d a -> UnitName m
-- | Extracts the exact value of a Unit, expressed in terms of the
-- SI coherent derived unit (see siUnit) of the same
-- Dimension.
--
-- Note that the actual value may in some cases be approximate, for
-- example if the unit is defined by experiment.
exactValue :: Unit m d a -> ExactPi
-- | Discards potentially unwanted type level information about a
-- Unit.
weaken :: Unit m d a -> Unit 'NonMetric d a
-- | Attempts to convert a Unit which may or may not be
-- Metric to one which is certainly Metric.
strengthen :: Unit m d a -> Maybe (Unit 'Metric d a)
-- | Forms the exact version of a Unit.
exactify :: Unit m d a -> Unit m d ExactPi
-- | Shows the value of a Quantity expressed in a specified
-- Unit of the same Dimension.
--
--
-- >>> showIn watt $ (37 *~ volt) * (4 *~ ampere)
-- "148.0 W"
--
showIn :: (Show a, Fractional a) => Unit m d a -> Quantity d a -> String
-- | A KnownVariant is one whose term-level Dimensional values we
-- can represent with an associated data family instance and manipulate
-- with certain functions, not all of which are exported from the
-- package.
--
-- Each validly constructed type of kind Variant has a
-- KnownVariant instance.
class KnownVariant (v :: Variant)
-- | Maps over the underlying representation of a dimensional value. The
-- caller is responsible for ensuring that the supplied function respects
-- the dimensional abstraction. This means that the function must
-- preserve numerical values, or linearly scale them while preserving the
-- origin.
dmap :: KnownVariant v => (a1 -> a2) -> Dimensional v d a1 -> Dimensional v d a2
-- | Convenient conversion between numerical types while retaining
-- dimensional information.
--
--
-- >>> let x = (37 :: Rational) *~ poundMass
--
-- >>> changeRep x :: Mass Double
-- 16.78291769 kg
--
changeRep :: (KnownVariant v, Real a, Fractional b) => Dimensional v d a -> Dimensional v d b
-- | Convenient conversion from exactly represented values while retaining
-- dimensional information.
changeRepApproximate :: (KnownVariant v, Floating b) => Dimensional v d ExactPi -> Dimensional v d b
-- | Converts a Unit into a lens from Quantitys to values.
asLens :: Fractional a => Unit m d a -> forall f. Functor f => (a -> f a) -> Quantity d a -> f (Quantity d a)
-- | Summary
--
-- This module defines type synonyms for common dimensionalities and the
-- associated quantity types. Additional dimensionalities and quantity
-- types will be added on an as-needed basis.
--
-- The definitions in this module are grouped so that a type synonym for
-- the dimensionality is defined first in terms of base dimension
-- exponents. Then a type synonym for the corresponding quantity type is
-- defined. If there are several quantity types with the same
-- dimensionality type synonyms are provided for each quantity type.
--
-- References
--
--
-- - http://physics.nist.gov/Pubs/SP811/
--
module Numeric.Units.Dimensional.Quantities
type Area = Quantity DArea
type Volume = Quantity DVolume
type Velocity = Quantity DVelocity
type Acceleration = Quantity DAcceleration
type WaveNumber = Quantity DWaveNumber
type MassDensity = Quantity DMassDensity
type Density = MassDensity
type SpecificVolume = Quantity DSpecificVolume
type CurrentDensity = Quantity DCurrentDensity
type MagneticFieldStrength = Quantity DMagneticFieldStrength
type AmountOfSubstanceConcentration = Quantity DAmountOfSubstanceConcentration
type Concentration = AmountOfSubstanceConcentration
type Luminance = Quantity DLuminance
type PlaneAngle = Dimensionless
type SolidAngle = Dimensionless
type Frequency = Quantity DFrequency
type Force = Quantity DForce
type Pressure = Quantity DPressure
type Stress = Quantity DStress
type Energy = Quantity DEnergy
type Work = Quantity DWork
type QuantityOfHeat = Quantity DQuantityOfHeat
type Power = Quantity DPower
type RadiantFlux = Quantity DRadiantFlux
type ElectricCharge = Quantity DElectricCharge
type QuantityOfElectricity = Quantity DQuantityOfElectricity
type ElectricPotential = Quantity DElectricPotential
type PotentialDifference = Quantity DPotentialDifference
type ElectromotiveForce = Quantity DElectromotiveForce
type Capacitance = Quantity DCapacitance
type ElectricResistance = Quantity DElectricResistance
type ElectricConductance = Quantity DElectricConductance
type MagneticFlux = Quantity DMagneticFlux
type MagneticFluxDensity = Quantity DMagneticFluxDensity
type Inductance = Quantity DInductance
type LuminousFlux = Quantity DLuminousFlux
type Illuminance = Quantity DIlluminance
type CelsiusTemperature = Quantity DCelsiusTemperature
type Activity = Quantity DActivity
type AbsorbedDose = Quantity DAbsorbedDose
type SpecificEnergy = Quantity DSpecificEnergy
type Kerma = Quantity DKerma
type DoseEquivalent = Quantity DDoseEquivalent
type AmbientDoseEquivalent = DoseEquivalent
type DirectionalDoseEquivalent = DoseEquivalent
type PersonalDoseEquivalent = DoseEquivalent
type EquivalentDose = DoseEquivalent
type CatalyticActivity = Quantity DCatalyticActivity
type AngularVelocity = Quantity DAngularVelocity
type AngularAcceleration = Quantity DAngularAcceleration
type DynamicViscosity = Quantity DDynamicViscosity
type MomentOfForce = Quantity DMomentOfForce
type SurfaceTension = Quantity DSurfaceTension
type HeatFluxDensity = Quantity DHeatFluxDensity
type Irradiance = Quantity DIrradiance
type RadiantIntensity = Quantity DRadiantIntensity
type Radiance = Quantity DRadiance
type HeatCapacity = Quantity DHeatCapacity
type Entropy = Quantity DEntropy
type SpecificHeatCapacity = Quantity DSpecificHeatCapacity
type SpecificEntropy = Quantity DSpecificEntropy
type ThermalConductivity = Quantity DThermalConductivity
type EnergyDensity = Quantity DEnergyDensity
type ElectricFieldStrength = Quantity DElectricFieldStrength
type ElectricChargeDensity = Quantity DElectricChargeDensity
type ElectricFluxDensity = Quantity DElectricFluxDensity
type Permittivity = Quantity DPermittivity
type Permeability = Quantity DPermeability
type MolarEnergy = Quantity DMolarEnergy
type MolarEntropy = Quantity DMolarEntropy
type MolarHeatCapacity = Quantity DMolarHeatCapacity
type Exposure = Quantity DExposure
type AbsorbedDoseRate = Quantity DAbsorbedDoseRate
type Impulse = Quantity DImpulse
type Momentum = Quantity DMomentum
type MassFlow = Quantity DMassFlow
type VolumeFlow = Quantity DVolumeFlow
type GravitationalParameter = Quantity DGravitationalParameter
type KinematicViscosity = Quantity DKinematicViscosity
type FirstMassMoment = Quantity DFirstMassMoment
type MomentOfInertia = Quantity DMomentOfInertia
type AngularMomentum = Quantity DAngularMomentum
type ThermalResistivity = Quantity DThermalResistivity
type ThermalConductance = Quantity DThermalConductance
type ThermalResistance = Quantity DThermalResistance
type HeatTransferCoefficient = Quantity DHeatTransferCoefficient
type ThermalAdmittance = HeatTransferCoefficient
type ThermalInsulance = Quantity DThermalInsulance
type Jerk = Quantity DJerk
type Angle = PlaneAngle
type Thrust = Force
type Torque = MomentOfForce
type EnergyPerUnitMass = SpecificEnergy
-- | Constructs a unit of area from a unit of length, taking the area of a
-- square whose sides are that length.
--
--
-- >>> 64 *~ square meter == (8 *~ meter) ^ pos2
-- True
--
square :: (Fractional a, Typeable m) => Unit m DLength a -> Unit 'NonMetric DArea a
-- | Constructs a unit of volume from a unit of length, taking the volume
-- of a cube whose sides are that length.
--
--
-- >>> 64 *~ cubic meter == (4 *~ meter) ^ pos3
-- True
--
cubic :: (Fractional a, Typeable m) => Unit m DLength a -> Unit 'NonMetric DVolume a
type DArea = 'Dim 'Pos2 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
type DVolume = 'Dim 'Pos3 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
type DVelocity = 'Dim 'Pos1 'Zero 'Neg1 'Zero 'Zero 'Zero 'Zero
type DAcceleration = 'Dim 'Pos1 'Zero 'Neg2 'Zero 'Zero 'Zero 'Zero
type DWaveNumber = 'Dim 'Neg1 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
type DMassDensity = 'Dim 'Neg3 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero
type DDensity = DMassDensity
type DSpecificVolume = 'Dim 'Pos3 'Neg1 'Zero 'Zero 'Zero 'Zero 'Zero
type DCurrentDensity = 'Dim 'Neg2 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero
type DMagneticFieldStrength = 'Dim 'Neg1 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero
type DAmountOfSubstanceConcentration = 'Dim 'Neg3 'Zero 'Zero 'Zero 'Zero 'Pos1 'Zero
type DConcentration = DAmountOfSubstanceConcentration
type DLuminance = 'Dim 'Neg2 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1
type DPlaneAngle = DOne
type DSolidAngle = DOne
type DFrequency = 'Dim 'Zero 'Zero 'Neg1 'Zero 'Zero 'Zero 'Zero
type DForce = 'Dim 'Pos1 'Pos1 'Neg2 'Zero 'Zero 'Zero 'Zero
type DPressure = 'Dim 'Neg1 'Pos1 'Neg2 'Zero 'Zero 'Zero 'Zero
type DStress = DPressure
type DEnergy = 'Dim 'Pos2 'Pos1 'Neg2 'Zero 'Zero 'Zero 'Zero
type DWork = DEnergy
type DQuantityOfHeat = DEnergy
type DPower = 'Dim 'Pos2 'Pos1 'Neg3 'Zero 'Zero 'Zero 'Zero
type DRadiantFlux = DPower
type DElectricCharge = 'Dim 'Zero 'Zero 'Pos1 'Pos1 'Zero 'Zero 'Zero
type DQuantityOfElectricity = DElectricCharge
type DElectricPotential = 'Dim 'Pos2 'Pos1 'Neg3 'Neg1 'Zero 'Zero 'Zero
type DPotentialDifference = DElectricPotential
type DElectromotiveForce = DElectricPotential
type DCapacitance = 'Dim 'Neg2 'Neg1 'Pos4 'Pos2 'Zero 'Zero 'Zero
type DElectricResistance = 'Dim 'Pos2 'Pos1 'Neg3 'Neg2 'Zero 'Zero 'Zero
type DElectricConductance = 'Dim 'Neg2 'Neg1 'Pos3 'Pos2 'Zero 'Zero 'Zero
type DMagneticFlux = 'Dim 'Pos2 'Pos1 'Neg2 'Neg1 'Zero 'Zero 'Zero
type DMagneticFluxDensity = 'Dim 'Zero 'Pos1 'Neg2 'Neg1 'Zero 'Zero 'Zero
type DInductance = 'Dim 'Pos2 'Pos1 'Neg2 'Neg2 'Zero 'Zero 'Zero
type DLuminousFlux = DLuminousIntensity
type DIlluminance = 'Dim 'Neg2 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1
type DCelsiusTemperature = DThermodynamicTemperature
type DActivity = DFrequency
type DAbsorbedDose = 'Dim 'Pos2 'Zero 'Neg2 'Zero 'Zero 'Zero 'Zero
type DSpecificEnergy = DAbsorbedDose
type DKerma = DAbsorbedDose
type DDoseEquivalent = DAbsorbedDose
type DAmbientDoseEquivalent = DDoseEquivalent
type DDirectionalDoseEquivalent = DDoseEquivalent
type DPersonalDoseEquivalent = DDoseEquivalent
type DEquivalentDose = DDoseEquivalent
type DCatalyticActivity = 'Dim 'Zero 'Zero 'Neg1 'Zero 'Zero 'Pos1 'Zero
type DAngularVelocity = DFrequency
type DAngularAcceleration = 'Dim 'Zero 'Zero 'Neg2 'Zero 'Zero 'Zero 'Zero
type DDynamicViscosity = 'Dim 'Neg1 'Pos1 'Neg1 'Zero 'Zero 'Zero 'Zero
type DMomentOfForce = DEnergy
type DSurfaceTension = 'Dim 'Zero 'Pos1 'Neg2 'Zero 'Zero 'Zero 'Zero
type DHeatFluxDensity = 'Dim 'Zero 'Pos1 'Neg3 'Zero 'Zero 'Zero 'Zero
type DIrradiance = DHeatFluxDensity
type DRadiantIntensity = DPower
type DRadiance = DIrradiance
type DHeatCapacity = 'Dim 'Pos2 'Pos1 'Neg2 'Zero 'Neg1 'Zero 'Zero
type DEntropy = DHeatCapacity
type DSpecificHeatCapacity = 'Dim 'Pos2 'Zero 'Neg2 'Zero 'Neg1 'Zero 'Zero
type DSpecificEntropy = DSpecificHeatCapacity
type DThermalConductivity = 'Dim 'Pos1 'Pos1 'Neg3 'Zero 'Neg1 'Zero 'Zero
type DEnergyDensity = DPressure
type DElectricFieldStrength = 'Dim 'Pos1 'Pos1 'Neg3 'Neg1 'Zero 'Zero 'Zero
type DElectricChargeDensity = 'Dim 'Neg3 'Zero 'Pos1 'Pos1 'Zero 'Zero 'Zero
type DElectricFluxDensity = 'Dim 'Neg2 'Zero 'Pos1 'Pos1 'Zero 'Zero 'Zero
type DPermittivity = 'Dim 'Neg3 'Neg1 'Pos4 'Pos2 'Zero 'Zero 'Zero
type DPermeability = 'Dim 'Pos1 'Pos1 'Neg2 'Neg2 'Zero 'Zero 'Zero
type DMolarEnergy = 'Dim 'Pos2 'Pos1 'Neg2 'Zero 'Zero 'Neg1 'Zero
type DMolarEntropy = 'Dim 'Pos2 'Pos1 'Neg2 'Zero 'Neg1 'Neg1 'Zero
type DMolarHeatCapacity = DMolarEntropy
type DExposure = 'Dim 'Zero 'Neg1 'Pos1 'Pos1 'Zero 'Zero 'Zero
type DAbsorbedDoseRate = 'Dim 'Pos2 'Zero 'Neg3 'Zero 'Zero 'Zero 'Zero
type DImpulse = 'Dim 'Pos1 'Pos1 'Neg1 'Zero 'Zero 'Zero 'Zero
type DMomentum = DImpulse
type DMassFlow = 'Dim 'Zero 'Pos1 'Neg1 'Zero 'Zero 'Zero 'Zero
type DVolumeFlow = 'Dim 'Pos3 'Zero 'Neg1 'Zero 'Zero 'Zero 'Zero
type DGravitationalParameter = 'Dim 'Pos3 'Zero 'Neg2 'Zero 'Zero 'Zero 'Zero
type DKinematicViscosity = 'Dim 'Pos2 'Zero 'Neg1 'Zero 'Zero 'Zero 'Zero
type DFirstMassMoment = 'Dim 'Pos1 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero
type DMomentOfInertia = 'Dim 'Pos2 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero
type DAngularMomentum = 'Dim 'Pos2 'Pos1 'Neg1 'Zero 'Zero 'Zero 'Zero
type DThermalResistivity = 'Dim 'Neg1 'Neg1 'Pos3 'Zero 'Pos1 'Zero 'Zero
type DThermalConductance = 'Dim 'Pos2 'Pos1 'Neg3 'Zero 'Neg1 'Zero 'Zero
type DThermalResistance = 'Dim 'Neg2 'Neg1 'Pos3 'Zero 'Pos1 'Zero 'Zero
type DHeatTransferCoefficient = 'Dim 'Zero 'Pos1 'Neg3 'Zero 'Neg1 'Zero 'Zero
type DThermalAdmittance = DHeatTransferCoefficient
type DThermalInsulance = 'Dim 'Zero 'Neg1 'Pos3 'Zero 'Pos1 'Zero 'Zero
type DJerk = 'Dim 'Pos1 'Zero 'Neg3 'Zero 'Zero 'Zero 'Zero
type DAngle = DPlaneAngle
type DThrust = DForce
type DTorque = DMomentOfForce
type DEnergyPerUnitMass = DSpecificEnergy
-- | Summary
--
-- This module defines the SI prefixes, the SI base units and the SI
-- derived units. It also defines the units outside of the SI that are
-- accepted for use with the SI. Any chapters, sections or tables
-- referenced are from [1] unless otherwise specified.
--
-- References
--
--
-- - http://physics.nist.gov/Pubs/SP811/
-- - http://en.wikipedia.org/wiki/Minute_of_arc
-- - http://en.wikipedia.org/wiki/Astronomical_unit
--
module Numeric.Units.Dimensional.SIUnits
metre :: Num a => Unit 'Metric DLength a
meter :: Num a => Unit 'Metric DLength a
gram :: Fractional a => Unit 'Metric DMass a
second :: Num a => Unit 'Metric DTime a
ampere :: Num a => Unit 'Metric DElectricCurrent a
kelvin :: Num a => Unit 'Metric DThermodynamicTemperature a
mole :: Num a => Unit 'Metric DAmountOfSubstance a
candela :: Num a => Unit 'Metric DLuminousIntensity a
radian :: Num a => Unit 'Metric DPlaneAngle a
steradian :: Num a => Unit 'Metric DSolidAngle a
hertz :: Num a => Unit 'Metric DFrequency a
newton :: Num a => Unit 'Metric DForce a
pascal :: Num a => Unit 'Metric DPressure a
joule :: Num a => Unit 'Metric DEnergy a
watt :: Num a => Unit 'Metric DPower a
coulomb :: Num a => Unit 'Metric DElectricCharge a
volt :: Num a => Unit 'Metric DElectricPotential a
farad :: Num a => Unit 'Metric DCapacitance a
ohm :: Num a => Unit 'Metric DElectricResistance a
siemens :: Num a => Unit 'Metric DElectricConductance a
weber :: Num a => Unit 'Metric DMagneticFlux a
tesla :: Num a => Unit 'Metric DMagneticFluxDensity a
henry :: Num a => Unit 'Metric DInductance a
lumen :: Num a => Unit 'Metric DLuminousFlux a
lux :: Num a => Unit 'Metric DIlluminance a
degreeCelsius :: Num a => Unit 'Metric DCelsiusTemperature a
fromDegreeCelsiusAbsolute :: Floating a => a -> ThermodynamicTemperature a
toDegreeCelsiusAbsolute :: Floating a => ThermodynamicTemperature a -> a
becquerel :: Num a => Unit 'Metric DActivity a
gray :: Num a => Unit 'Metric DAbsorbedDose a
sievert :: Num a => Unit 'Metric DDoseEquivalent a
katal :: Num a => Unit 'Metric DCatalyticActivity a
minute :: Num a => Unit 'NonMetric DTime a
hour :: Num a => Unit 'NonMetric DTime a
day :: Num a => Unit 'NonMetric DTime a
hectare :: Fractional a => Unit 'NonMetric DArea a
litre :: Fractional a => Unit 'Metric DVolume a
liter :: Fractional a => Unit 'Metric DVolume a
tonne :: Num a => Unit 'Metric DMass a
metricTon :: Num a => Unit 'Metric DMass a
degree :: Floating a => Unit 'NonMetric DPlaneAngle a
arcminute :: Floating a => Unit 'NonMetric DPlaneAngle a
arcsecond :: Floating a => Unit 'NonMetric DPlaneAngle a
degreeOfArc :: Floating a => Unit 'NonMetric DPlaneAngle a
minuteOfArc :: Floating a => Unit 'NonMetric DPlaneAngle a
secondOfArc :: Floating a => Unit 'NonMetric DPlaneAngle a
astronomicalUnit :: Num a => Unit 'NonMetric DLength a
deka :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
deca :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
hecto :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
kilo :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
mega :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
giga :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
tera :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
peta :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
exa :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
zetta :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
yotta :: Num a => Unit 'Metric d a -> Unit 'NonMetric d a
deci :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
centi :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
milli :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
micro :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
nano :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
pico :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
femto :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
atto :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
zepto :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
yocto :: Fractional a => Unit 'Metric d a -> Unit 'NonMetric d a
data Prefix
applyPrefix :: Fractional a => Prefix -> Unit 'Metric d a -> Unit 'NonMetric d a
-- | A list of all Prefixes defined by the SI.
siPrefixes :: [Prefix]
-- | Summary
--
-- This module supplies a convenient set of imports for working with the
-- dimensional package, including aliases for common Quantitys and
-- Dimensions, and a comprehensive set of SI units and units
-- accepted for use with the SI.
--
-- It re-exports the Prelude, hiding arithmetic functions whose
-- names collide with the dimensionally-typed versions supplied by this
-- package.
module Numeric.Units.Dimensional.Prelude
-- | Dimensional values inhabit this class, which allows access to a
-- term-level representation of their dimension.
class HasDynamicDimension a => HasDimension a
-- | Obtains a term-level representation of a value's dimension.
dimension :: HasDimension a => a -> Dimension'
-- | A physical dimension, encoded as 7 integers, representing a
-- factorization of the dimension into the 7 SI base dimensions. By
-- convention they are stored in the same order as in the
-- Dimension data kind.
data Dimension'
Dim' :: !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> Dimension'
-- | A KnownDimension is one for which we can construct a term-level
-- representation. Each validly constructed type of kind Dimension
-- has a KnownDimension instance.
--
-- While KnownDimension is a constraint synonym, the presence of
-- KnownDimension d in a context allows use of
-- dimension :: Proxy d -> Dimension'.
type KnownDimension (d :: Dimension) = HasDimension (Proxy d)
-- | Cube root is a special case of NRoot with order 3.
type Cbrt d = NRoot d 'Pos3
-- | Square root is a special case of NRoot with order 2.
type Sqrt d = NRoot d 'Pos2
-- | Roots of dimensions corresponds to division of the base dimensions'
-- exponents by the order of the root.
type family NRoot (d :: Dimension) (x :: TypeInt)
-- | Powers of dimensions corresponds to multiplication of the base
-- dimensions' exponents by the exponent.
--
-- We limit ourselves to integer powers of Dimensionals as fractional
-- powers make little physical sense.
type family (d :: Dimension) ^ (x :: TypeInt)
infixr 8 ^
-- | The reciprocal of a dimension is defined as the result of dividing
-- DOne by it, or of negating each of the base dimensions'
-- exponents.
type Recip (d :: Dimension) = DOne / d
-- | Division of dimensions corresponds to subtraction of the base
-- dimensions' exponents.
type family (a :: Dimension) / (d :: Dimension)
infixl 7 /
-- | Multiplication of dimensions corresponds to adding of the base
-- dimensions' exponents.
type family (a :: Dimension) * (b :: Dimension)
infixl 7 *
type DLuminousIntensity = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1
type DAmountOfSubstance = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1 'Zero
type DThermodynamicTemperature = 'Dim 'Zero 'Zero 'Zero 'Zero 'Pos1 'Zero 'Zero
type DElectricCurrent = 'Dim 'Zero 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero
type DTime = 'Dim 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero 'Zero
type DMass = 'Dim 'Zero 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero
type DLength = 'Dim 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
-- | The type-level dimension of dimensionless values.
type DOne = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
-- | Represents a physical dimension in the basis of the 7 SI base
-- dimensions, where the respective dimensions are represented by type
-- variables using the following convention:
--
--
-- - l: Length
-- - m: Mass
-- - t: Time
-- - i: Electric current
-- - th: Thermodynamic temperature
-- - n: Amount of substance
-- - j: Luminous intensity
--
--
-- For the equivalent term-level representation, see Dimension'
data Dimension
Dim :: TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> Dimension
-- | Encodes whether a unit is a metric unit, that is, whether it can be
-- combined with a metric prefix to form a related unit.
data Metricality
-- | Capable of receiving a metric prefix.
Metric :: Metricality
-- | Incapable of receiving a metric prefix.
NonMetric :: Metricality
-- | A KnownVariant is one whose term-level Dimensional values we
-- can represent with an associated data family instance and manipulate
-- with certain functions, not all of which are exported from the
-- package.
--
-- Each validly constructed type of kind Variant has a
-- KnownVariant instance.
class KnownVariant (v :: Variant) where {
-- | A dimensional value, either a Quantity or a Unit,
-- parameterized by its Dimension and representation.
data family Dimensional v :: Dimension -> Type -> Type;
}
-- | A dimensional quantity.
type Quantity = SQuantity One
-- | A unit of measurement.
type Unit (m :: Metricality) = Dimensional ( 'DUnit m)
-- | A polymorphic Unit which can be used in place of the coherent
-- SI base unit of any dimension. This allows polymorphic quantity
-- creation and destruction without exposing the Dimensional
-- constructor.
siUnit :: forall d a. (KnownDimension d, Num a) => Unit 'NonMetric d a
-- | Shows the value of a Quantity expressed in a specified
-- Unit of the same Dimension.
--
--
-- >>> showIn watt $ (37 *~ volt) * (4 *~ ampere)
-- "148.0 W"
--
showIn :: (Show a, Fractional a) => Unit m d a -> Quantity d a -> String
type LuminousIntensity = Quantity DLuminousIntensity
type AmountOfSubstance = Quantity DAmountOfSubstance
type ThermodynamicTemperature = Quantity DThermodynamicTemperature
type ElectricCurrent = Quantity DElectricCurrent
type Time = Quantity DTime
type Mass = Quantity DMass
type Length = Quantity DLength
type Dimensionless = Quantity DOne
-- | Extracts the UnitName of a Unit.
name :: Unit m d a -> UnitName m
-- | Extracts the exact value of a Unit, expressed in terms of the
-- SI coherent derived unit (see siUnit) of the same
-- Dimension.
--
-- Note that the actual value may in some cases be approximate, for
-- example if the unit is defined by experiment.
exactValue :: Unit m d a -> ExactPi
-- | Discards potentially unwanted type level information about a
-- Unit.
weaken :: Unit m d a -> Unit 'NonMetric d a
-- | Attempts to convert a Unit which may or may not be
-- Metric to one which is certainly Metric.
strengthen :: Unit m d a -> Maybe (Unit 'Metric d a)
-- | Forms the exact version of a Unit.
exactify :: Unit m d a -> Unit m d ExactPi
-- | Forms a Quantity by multipliying a number and a unit.
(*~) :: Num a => a -> Unit m d a -> Quantity d a
infixl 7 *~
-- | Divides a Quantity by a Unit of the same physical
-- dimension, obtaining the numerical value of the quantity expressed in
-- that unit.
(/~) :: Fractional a => Quantity d a -> Unit m d a -> a
infixl 7 /~
-- | Multiplies two Quantitys or two Units.
--
-- The intimidating type signature captures the similarity between these
-- operations and ensures that composite Units are
-- NonMetric.
(*) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 * v2), Num a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 * v2) (d1 * d2) a
infixl 7 *
-- | Divides one Quantity by another or one Unit by another.
--
-- The intimidating type signature captures the similarity between these
-- operations and ensures that composite Units are
-- NotPrefixable.
(/) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 / v2), Fractional a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 / v2) (d1 / d2) a
infixl 7 /
-- | Forms the reciprocal of a Quantity, which has the reciprocal
-- dimension.
--
--
-- >>> recip $ 47 *~ hertz
-- 2.127659574468085e-2 s
--
recip :: Fractional a => Quantity d a -> Quantity (Recip d) a
-- | Raises a Quantity or Unit to an integer power.
--
-- Because the power chosen impacts the Dimension of the result,
-- it is necessary to supply a type-level representation of the exponent
-- in the form of a Proxy to some TypeInt. Convenience
-- values pos1, pos2, neg1, ... are supplied by
-- the Numeric.NumType.DK.Integers module. The most commonly used
-- ones are also reexported by Numeric.Units.Dimensional.Prelude.
--
-- The intimidating type signature captures the similarity between these
-- operations and ensures that composite Units are
-- NotPrefixable.
(^) :: (Fractional a, KnownTypeInt i, KnownVariant v, KnownVariant (Weaken v)) => Dimensional v d1 a -> Proxy i -> Dimensional (Weaken v) (d1 ^ i) a
infixr 8 ^
-- | Negates the value of a Quantity.
negate :: Num a => Quantity d a -> Quantity d a
-- | Adds two Quantitys.
(+) :: Num a => Quantity d a -> Quantity d a -> Quantity d a
infixl 6 +
-- | Subtracts one Quantity from another.
(-) :: Num a => Quantity d a -> Quantity d a -> Quantity d a
infixl 6 -
-- | Takes the absolute value of a Quantity.
abs :: Num a => Quantity d a -> Quantity d a
-- | Takes the sign of a Quantity. The functions abs and
-- signum satisy the law that:
--
--
-- abs x * signum x == x
--
--
-- The sign is either negate _1 (negative), _0 (zero),
-- or _1 (positive).
signum :: Num a => Quantity d a -> Dimensionless a
-- | Computes the nth root of a Quantity using **.
--
-- The NRoot type family will prevent application of this operator
-- where the result would have a fractional dimension or where n is zero.
--
-- Because the root chosen impacts the Dimension of the result, it
-- is necessary to supply a type-level representation of the root in the
-- form of a Proxy to some TypeInt. Convenience values
-- pos1, pos2, neg1, ... are supplied by the
-- Numeric.NumType.DK.Integers module. The most commonly used ones
-- are also reexported by Numeric.Units.Dimensional.Prelude.
--
-- n must not be zero. Negative roots are defined such that nroot
-- (Proxy :: Proxy (Negate n)) x == nroot (Proxy :: Proxy n) (recip
-- x).
--
-- Also available in operator form, see ^/.
nroot :: (KnownTypeInt n, Floating a) => Proxy n -> Quantity d a -> Quantity (NRoot d n) a
-- | Computes the square root of a Quantity using **.
--
-- The NRoot type family will prevent application where the
-- supplied quantity does not have a square dimension.
--
--
-- (x :: Area Double) >= _0 ==> sqrt x == nroot pos2 x
--
sqrt :: Floating a => Quantity d a -> Quantity (Sqrt d) a
-- | Computes the cube root of a Quantity using **.
--
-- The NRoot type family will prevent application where the
-- supplied quantity does not have a cubic dimension.
--
--
-- (x :: Volume Double) >= _0 ==> cbrt x == nroot pos3 x
--
cbrt :: Floating a => Quantity d a -> Quantity (Cbrt d) a
-- | Computes the nth root of a Quantity using **.
--
-- The NRoot type family will prevent application of this operator
-- where the result would have a fractional dimension or where n is zero.
--
-- Because the root chosen impacts the Dimension of the result, it
-- is necessary to supply a type-level representation of the root in the
-- form of a Proxy to some TypeInt. Convenience values
-- pos1, pos2, neg1, ... are supplied by the
-- Numeric.NumType.DK.Integers module. The most commonly used ones
-- are also reexported by Numeric.Units.Dimensional.Prelude.
--
-- Also available in prefix form, see nroot.
(^/) :: (KnownTypeInt n, Floating a) => Quantity d a -> Proxy n -> Quantity (NRoot d n) a
infixr 8 ^/
-- | Applies *~ to all values in a functor.
(*~~) :: (Functor f, Num a) => f a -> Unit m d a -> f (Quantity d a)
infixl 7 *~~
-- | Applies /~ to all values in a functor.
(/~~) :: forall f m d a. (Functor f, Fractional a) => f (Quantity d a) -> Unit m d a -> f a
infixl 7 /~~
-- | The sum of all elements in a foldable structure.
--
--
-- >>> sum ([] :: [Mass Double])
-- 0.0 kg
--
--
--
-- >>> sum [12.4 *~ meter, 1 *~ foot]
-- 12.7048 m
--
sum :: (Num a, Foldable f) => f (Quantity d a) -> Quantity d a
-- | The product of all elements in a foldable structure.
--
--
-- >>> product ([] :: [Dimensionless Double])
-- 1.0
--
--
--
-- >>> product [pi, _4, 0.36 *~ one]
-- 4.523893421169302
--
product :: (Num a, Foldable f) => f (Dimensionless a) -> Dimensionless a
-- | The arithmetic mean of all elements in a foldable structure.
--
--
-- >>> mean [pi, _7]
-- 5.070796326794897
--
mean :: (Fractional a, Foldable f) => f (Quantity d a) -> Quantity d a
-- | The length of the foldable data structure as a Dimensionless.
-- This can be useful for purposes of e.g. calculating averages.
--
--
-- >>> dimensionlessLength ["foo", "bar"]
-- 2
--
dimensionlessLength :: (Num a, Foldable f) => f b -> Dimensionless a
-- | Returns a list of quantities between given bounds.
--
--
-- n <= 0 ==> nFromTo (x :: Mass Double) (y :: Mass Double) n == [x, y]
--
--
--
-- (x :: Length Double) <= (y :: Length Double) ==> all (\z -> x <= z && z <= y) (nFromTo x y n)
--
--
--
-- >>> nFromTo _0 _3 2
-- [0.0,1.0,2.0,3.0]
--
--
--
-- >>> nFromTo _1 _0 7
-- [1.0,0.875,0.75,0.625,0.5,0.375,0.25,0.125,0.0]
--
--
--
-- >>> nFromTo _0 _1 (-5)
-- [0.0,1.0]
--
nFromTo :: (Fractional a, Integral b) => Quantity d a -> Quantity d a -> b -> [Quantity d a]
exp :: Floating a => Dimensionless a -> Dimensionless a
log :: Floating a => Dimensionless a -> Dimensionless a
sin :: Floating a => Dimensionless a -> Dimensionless a
cos :: Floating a => Dimensionless a -> Dimensionless a
tan :: Floating a => Dimensionless a -> Dimensionless a
asin :: Floating a => Dimensionless a -> Dimensionless a
acos :: Floating a => Dimensionless a -> Dimensionless a
atan :: Floating a => Dimensionless a -> Dimensionless a
sinh :: Floating a => Dimensionless a -> Dimensionless a
cosh :: Floating a => Dimensionless a -> Dimensionless a
tanh :: Floating a => Dimensionless a -> Dimensionless a
asinh :: Floating a => Dimensionless a -> Dimensionless a
acosh :: Floating a => Dimensionless a -> Dimensionless a
atanh :: Floating a => Dimensionless a -> Dimensionless a
-- | Raises a dimensionless quantity to a dimensionless power.
(**) :: Floating a => Dimensionless a -> Dimensionless a -> Dimensionless a
infixr 8 **
-- | Takes the logarithm of the second argument in the base of the first.
--
--
-- >>> logBase _2 _8
-- 3.0
--
logBase :: Floating a => Dimensionless a -> Dimensionless a -> Dimensionless a
-- | The standard two argument arctangent function. Since it interprets its
-- two arguments in comparison with one another, the input may have any
-- dimension.
--
--
-- >>> atan2 _0 _1
-- 0.0
--
--
--
-- >>> atan2 _1 _0
-- 1.5707963267948966
--
--
--
-- >>> atan2 _0 (negate _1)
-- 3.141592653589793
--
--
--
-- >>> atan2 (negate _1) _0
-- -1.5707963267948966
--
atan2 :: RealFloat a => Quantity d a -> Quantity d a -> Dimensionless a
-- | The unit one has dimension DOne and is the base unit of
-- dimensionless values.
--
-- As detailed in 7.10 "Values of quantities expressed simply as numbers:
-- the unit one, symbol 1" of [1] the unit one generally does not
-- appear in expressions. However, for us it is necessary to use
-- one as we would any other unit to perform the "boxing" of
-- dimensionless values.
one :: Num a => Unit 'NonMetric DOne a
-- | The constant for zero is polymorphic, allowing it to express zero
-- Length or Capacitance or Velocity etc, in
-- addition to the Dimensionless value zero.
_0 :: Num a => Quantity d a
_1 :: Num a => Dimensionless a
_2 :: Num a => Dimensionless a
_3 :: Num a => Dimensionless a
_4 :: Num a => Dimensionless a
_5 :: Num a => Dimensionless a
_6 :: Num a => Dimensionless a
_7 :: Num a => Dimensionless a
_8 :: Num a => Dimensionless a
_9 :: Num a => Dimensionless a
pi :: Floating a => Dimensionless a
-- | Twice pi.
--
-- For background on tau see
-- http://tauday.com/tau-manifesto (but also feel free to review
-- http://www.thepimanifesto.com).
tau :: Floating a => Dimensionless a
-- | Convenient conversion between numerical types while retaining
-- dimensional information.
--
--
-- >>> let x = (37 :: Rational) *~ poundMass
--
-- >>> changeRep x :: Mass Double
-- 16.78291769 kg
--
changeRep :: (KnownVariant v, Real a, Fractional b) => Dimensional v d a -> Dimensional v d b
-- | Convenient conversion from exactly represented values while retaining
-- dimensional information.
changeRepApproximate :: (KnownVariant v, Floating b) => Dimensional v d ExactPi -> Dimensional v d b
-- | Converts a Unit into a lens from Quantitys to values.
asLens :: Fractional a => Unit m d a -> forall f. Functor f => (a -> f a) -> Quantity d a -> f (Quantity d a)
-- | Forms a new atomic Unit by specifying its UnitName and
-- its definition as a multiple of another Unit.
--
-- Use this variant when the scale factor of the resulting unit is
-- irrational or Approximate. See mkUnitQ for when it is
-- rational and mkUnitZ for when it is an integer.
--
-- Note that supplying zero as a definining quantity is invalid, as the
-- library relies upon units forming a group under multiplication.
--
-- Supplying negative defining quantities is allowed and handled
-- gracefully, but is discouraged on the grounds that it may be
-- unexpected by other readers.
mkUnitR :: Floating a => UnitName m -> ExactPi -> Unit m1 d a -> Unit m d a
-- | Forms a new atomic Unit by specifying its UnitName and
-- its definition as a multiple of another Unit.
--
-- Use this variant when the scale factor of the resulting unit is
-- rational. See mkUnitZ for when it is an integer and
-- mkUnitR for the general case.
--
-- For more information see mkUnitR.
mkUnitQ :: Fractional a => UnitName m -> Rational -> Unit m1 d a -> Unit m d a
-- | Forms a new atomic Unit by specifying its UnitName and
-- its definition as a multiple of another Unit.
--
-- Use this variant when the scale factor of the resulting unit is an
-- integer. See mkUnitQ for when it is rational and mkUnitR
-- for the general case.
--
-- For more information see mkUnitR.
mkUnitZ :: Num a => UnitName m -> Integer -> Unit m1 d a -> Unit m d a
pos5 :: Proxy Pos5
pos4 :: Proxy Pos4
pos3 :: Proxy Pos3
pos2 :: Proxy Pos2
pos1 :: Proxy Pos1
zero :: Proxy Zero
neg1 :: Proxy Neg1
neg2 :: Proxy Neg2
neg3 :: Proxy Neg3
neg4 :: Proxy Neg4
neg5 :: Proxy Neg5
-- | A class for categories. Instances should satisfy the laws
--
--
-- f . id = f -- (right identity)
-- id . f = f -- (left identity)
-- f . (g . h) = (f . g) . h -- (associativity)
--
class Category (cat :: k -> k -> Type)
-- | the identity morphism
id :: Category cat => cat a a
-- | morphism composition
(.) :: Category cat => cat b c -> cat a b -> cat a c
infixr 9 .
-- | The largest element of a non-empty structure.
maximum :: (Foldable t, Ord a) => t a -> a
-- | The least element of a non-empty structure.
minimum :: (Foldable t, Ord a) => t a -> a
-- | Append two lists, i.e.,
--
--
-- [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
-- [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
--
--
-- If the first list is not finite, the result is the first list.
(++) :: () => [a] -> [a] -> [a]
infixr 5 ++
-- | The value of seq a b is bottom if a is bottom, and
-- otherwise equal to b. In other words, it evaluates the first
-- argument a to weak head normal form (WHNF). seq is
-- usually introduced to improve performance by avoiding unneeded
-- laziness.
--
-- A note on evaluation order: the expression seq a b does
-- not guarantee that a will be evaluated before
-- b. The only guarantee given by seq is that the both
-- a and b will be evaluated before seq
-- returns a value. In particular, this means that b may be
-- evaluated before a. If you need to guarantee a specific order
-- of evaluation, you must use the function pseq from the
-- "parallel" package.
seq :: () => a -> b -> b
-- | filter, applied to a predicate and a list, returns the list of
-- those elements that satisfy the predicate; i.e.,
--
--
-- filter p xs = [ x | x <- xs, p x]
--
filter :: () => (a -> Bool) -> [a] -> [a]
-- | zip takes two lists and returns a list of corresponding pairs.
--
--
-- zip [1, 2] ['a', 'b'] = [(1, 'a'), (2, 'b')]
--
--
-- If one input list is short, excess elements of the longer list are
-- discarded:
--
--
-- zip [1] ['a', 'b'] = [(1, 'a')]
-- zip [1, 2] ['a'] = [(1, 'a')]
--
--
-- zip is right-lazy:
--
--
-- zip [] _|_ = []
-- zip _|_ [] = _|_
--
zip :: () => [a] -> [b] -> [(a, b)]
-- | The print function outputs a value of any printable type to the
-- standard output device. Printable types are those that are instances
-- of class Show; print converts values to strings for
-- output using the show operation and adds a newline.
--
-- For example, a program to print the first 20 integers and their powers
-- of 2 could be written as:
--
--
-- main = print ([(n, 2^n) | n <- [0..19]])
--
print :: Show a => a -> IO ()
-- | Extract the first component of a pair.
fst :: () => (a, b) -> a
-- | Extract the second component of a pair.
snd :: () => (a, b) -> b
-- | otherwise is defined as the value True. It helps to make
-- guards more readable. eg.
--
--
-- f x | x < 0 = ...
-- | otherwise = ...
--
otherwise :: Bool
-- | map f xs is the list obtained by applying f
-- to each element of xs, i.e.,
--
--
-- map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
-- map f [x1, x2, ...] == [f x1, f x2, ...]
--
map :: () => (a -> b) -> [a] -> [b]
-- | Application operator. This operator is redundant, since ordinary
-- application (f x) means the same as (f $ x).
-- However, $ has low, right-associative binding precedence, so it
-- sometimes allows parentheses to be omitted; for example:
--
--
-- f $ g $ h x = f (g (h x))
--
--
-- It is also useful in higher-order situations, such as map
-- ($ 0) xs, or zipWith ($) fs xs.
--
-- Note that ($) is levity-polymorphic in its result type, so
-- that foo $ True where foo :: Bool -> Int# is well-typed
($) :: () => (a -> b) -> a -> b
infixr 0 $
-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b
-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b
-- | The Bounded class is used to name the upper and lower limits of
-- a type. Ord is not a superclass of Bounded since types
-- that are not totally ordered may also have upper and lower bounds.
--
-- The Bounded class may be derived for any enumeration type;
-- minBound is the first constructor listed in the data
-- declaration and maxBound is the last. Bounded may also
-- be derived for single-constructor datatypes whose constituent types
-- are in Bounded.
class Bounded a
minBound :: Bounded a => a
maxBound :: Bounded a => a
-- | Class Enum defines operations on sequentially ordered types.
--
-- The enumFrom... methods are used in Haskell's translation of
-- arithmetic sequences.
--
-- Instances of Enum may be derived for any enumeration type
-- (types whose constructors have no fields). The nullary constructors
-- are assumed to be numbered left-to-right by fromEnum from
-- 0 through n-1. See Chapter 10 of the Haskell
-- Report for more details.
--
-- For any type that is an instance of class Bounded as well as
-- Enum, the following should hold:
--
--
--
--
-- enumFrom x = enumFromTo x maxBound
-- enumFromThen x y = enumFromThenTo x y bound
-- where
-- bound | fromEnum y >= fromEnum x = maxBound
-- | otherwise = minBound
--
class Enum a
-- | the successor of a value. For numeric types, succ adds 1.
succ :: Enum a => a -> a
-- | the predecessor of a value. For numeric types, pred subtracts
-- 1.
pred :: Enum a => a -> a
-- | Convert from an Int.
toEnum :: Enum a => Int -> a
-- | Convert to an Int. It is implementation-dependent what
-- fromEnum returns when applied to a value that is too large to
-- fit in an Int.
fromEnum :: Enum a => a -> Int
-- | Used in Haskell's translation of [n..] with [n..] =
-- enumFrom n, a possible implementation being enumFrom n = n :
-- enumFrom (succ n). For example:
--
--
-- enumFrom 4 :: [Integer] = [4,5,6,7,...]
enumFrom 6 :: [Int] = [6,7,8,9,...,maxBound ::
-- Int]
enumFrom :: Enum a => a -> [a]
-- | Used in Haskell's translation of [n,n'..] with [n,n'..] =
-- enumFromThen n n', a possible implementation being
-- enumFromThen n n' = n : n' : worker (f x) (f x n'),
-- worker s v = v : worker s (s v), x = fromEnum n' -
-- fromEnum n and f n y | n > 0 = f (n - 1) (succ y) | n <
-- 0 = f (n + 1) (pred y) | otherwise = y For example:
--
--
-- enumFromThen 4 6 :: [Integer] = [4,6,8,10...]
enumFromThen 6 2 :: [Int] = [6,2,-2,-6,...,minBound ::
-- Int]
enumFromThen :: Enum a => a -> a -> [a]
-- | Used in Haskell's translation of [n..m] with [n..m] =
-- enumFromTo n m, a possible implementation being enumFromTo n
-- m | n <= m = n : enumFromTo (succ n) m | otherwise = []. For
-- example:
--
--
-- enumFromTo 6 10 :: [Int] = [6,7,8,9,10]
enumFromTo 42 1 :: [Integer] = []
enumFromTo :: Enum a => a -> a -> [a]
-- | Used in Haskell's translation of [n,n'..m] with [n,n'..m]
-- = enumFromThenTo n n' m, a possible implementation being
-- enumFromThenTo n n' m = worker (f x) (c x) n m, x =
-- fromEnum n' - fromEnum n, c x = bool (>=) ((x
-- 0) f n y | n > 0 = f (n - 1) (succ y) | n < 0 = f (n +
-- 1) (pred y) | otherwise = y and worker s c v m | c v m = v :
-- worker s c (s v) m | otherwise = [] For example:
--
--
-- enumFromThenTo 4 2 -6 :: [Integer] =
-- [4,2,0,-2,-4,-6]
enumFromThenTo 6 8 2 :: [Int] = []
enumFromThenTo :: Enum a => a -> a -> a -> [a]
-- | The Eq class defines equality (==) and inequality
-- (/=). All the basic datatypes exported by the Prelude
-- are instances of Eq, and Eq may be derived for any
-- datatype whose constituents are also instances of Eq.
--
-- The Haskell Report defines no laws for Eq. However, ==
-- is customarily expected to implement an equivalence relationship where
-- two values comparing equal are indistinguishable by "public"
-- functions, with a "public" function being one not allowing to see
-- implementation details. For example, for a type representing
-- non-normalised natural numbers modulo 100, a "public" function doesn't
-- make the difference between 1 and 201. It is expected to have the
-- following properties:
--
--
-- - Reflexivity x == x = True
-- - Symmetry x == y = y == x
-- - Transitivity if x == y && y == z =
-- True, then x == z = True
-- - Substitutivity if x == y = True and
-- f is a "public" function whose return type is an instance of
-- Eq, then f x == f y = True
-- - Negation x /= y = not (x ==
-- y)
--
--
-- Minimal complete definition: either == or /=.
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool
infix 4 ==
infix 4 /=
-- | Trigonometric and hyperbolic functions and related functions.
--
-- The Haskell Report defines no laws for Floating. However,
-- '(+)', '(*)' and exp are customarily expected to define an
-- exponential field and have the following properties:
--
--
-- - exp (a + b) = @exp a * exp b
-- - exp (fromInteger 0) = fromInteger 1
--
class Fractional a => Floating a
-- | Fractional numbers, supporting real division.
--
-- The Haskell Report defines no laws for Fractional. However,
-- '(+)' and '(*)' are customarily expected to define a division ring and
-- have the following properties:
--
--
-- - recip gives the multiplicative inverse x
-- * recip x = recip x * x = fromInteger 1
--
--
-- Note that it isn't customarily expected that a type instance of
-- Fractional implement a field. However, all instances in
-- base do.
class Num a => Fractional a
-- | Conversion from a Rational (that is Ratio
-- Integer). A floating literal stands for an application of
-- fromRational to a value of type Rational, so such
-- literals have type (Fractional a) => a.
fromRational :: Fractional a => Rational -> a
-- | Integral numbers, supporting integer division.
--
-- The Haskell Report defines no laws for Integral. However,
-- Integral instances are customarily expected to define a
-- Euclidean domain and have the following properties for the 'div'/'mod'
-- and 'quot'/'rem' pairs, given suitable Euclidean functions f
-- and g:
--
--
-- - x = y * quot x y + rem x y with rem x y
-- = fromInteger 0 or g (rem x y) < g
-- y
-- - x = y * div x y + mod x y with mod x y
-- = fromInteger 0 or f (mod x y) < f
-- y
--
--
-- An example of a suitable Euclidean function, for Integer's
-- instance, is abs.
class (Real a, Enum a) => Integral a
-- | integer division truncated toward zero
quot :: Integral a => a -> a -> a
-- | integer remainder, satisfying
--
--
-- (x `quot` y)*y + (x `rem` y) == x
--
rem :: Integral a => a -> a -> a
-- | integer division truncated toward negative infinity
div :: Integral a => a -> a -> a
-- | integer modulus, satisfying
--
--
-- (x `div` y)*y + (x `mod` y) == x
--
mod :: Integral a => a -> a -> a
-- | simultaneous quot and rem
quotRem :: Integral a => a -> a -> (a, a)
-- | simultaneous div and mod
divMod :: Integral a => a -> a -> (a, a)
-- | conversion to Integer
toInteger :: Integral a => a -> Integer
infixl 7 `quot`
infixl 7 `rem`
infixl 7 `div`
infixl 7 `mod`
-- | The Monad class defines the basic operations over a
-- monad, a concept from a branch of mathematics known as
-- category theory. From the perspective of a Haskell programmer,
-- however, it is best to think of a monad as an abstract datatype
-- of actions. Haskell's do expressions provide a convenient
-- syntax for writing monadic expressions.
--
-- Instances of Monad should satisfy the following laws:
--
--
--
-- Furthermore, the Monad and Applicative operations should
-- relate as follows:
--
--
--
-- The above laws imply:
--
--
--
-- and that pure and (<*>) satisfy the applicative
-- functor laws.
--
-- The instances of Monad for lists, Maybe and IO
-- defined in the Prelude satisfy these laws.
class Applicative m => Monad (m :: Type -> Type)
-- | Sequentially compose two actions, passing any value produced by the
-- first as an argument to the second.
(>>=) :: Monad m => m a -> (a -> m b) -> m b
-- | Sequentially compose two actions, discarding any value produced by the
-- first, like sequencing operators (such as the semicolon) in imperative
-- languages.
(>>) :: Monad m => m a -> m b -> m b
-- | Inject a value into the monadic type.
return :: Monad m => a -> m a
-- | Fail with a message. This operation is not part of the mathematical
-- definition of a monad, but is invoked on pattern-match failure in a
-- do expression.
--
-- As part of the MonadFail proposal (MFP), this function is moved to its
-- own class MonadFail (see Control.Monad.Fail for more
-- details). The definition here will be removed in a future release.
fail :: Monad m => String -> m a
infixl 1 >>=
infixl 1 >>
-- | The Functor class is used for types that can be mapped over.
-- Instances of Functor should satisfy the following laws:
--
--
-- fmap id == id
-- fmap (f . g) == fmap f . fmap g
--
--
-- The instances of Functor for lists, Maybe and IO
-- satisfy these laws.
class Functor (f :: Type -> Type)
fmap :: Functor f => (a -> b) -> f a -> f b
-- | Replace all locations in the input with the same value. The default
-- definition is fmap . const, but this may be
-- overridden with a more efficient version.
(<$) :: Functor f => a -> f b -> f a
infixl 4 <$
-- | Basic numeric class.
--
-- The Haskell Report defines no laws for Num. However, '(+)' and
-- '(*)' are customarily expected to define a ring and have the following
-- properties:
--
--
-- - Associativity of (+) (x + y) + z = x +
-- (y + z)
-- - Commutativity of (+) x + y = y +
-- x
-- - fromInteger 0 is the additive identity
-- x + fromInteger 0 = x
-- - negate gives the additive inverse x +
-- negate x = fromInteger 0
-- - Associativity of (*) (x * y) * z = x *
-- (y * z)
-- - fromInteger 1 is the multiplicative
-- identity x * fromInteger 1 = x and
-- fromInteger 1 * x = x
-- - Distributivity of (*) with respect to (+) a * (b
-- + c) = (a * b) + (a * c) and (b + c) * a =
-- (b * a) + (c * a)
--
--
-- Note that it isn't customarily expected that a type instance of
-- both Num and Ord implement an ordered ring. Indeed, in
-- base only Integer and Rational do.
class Num a
-- | Conversion from an Integer. An integer literal represents the
-- application of the function fromInteger to the appropriate
-- value of type Integer, so such literals have type
-- (Num a) => a.
fromInteger :: Num a => Integer -> a
-- | The Ord class is used for totally ordered datatypes.
--
-- Instances of Ord can be derived for any user-defined datatype
-- whose constituent types are in Ord. The declared order of the
-- constructors in the data declaration determines the ordering in
-- derived Ord instances. The Ordering datatype allows a
-- single comparison to determine the precise ordering of two objects.
--
-- The Haskell Report defines no laws for Ord. However,
-- <= is customarily expected to implement a non-strict partial
-- order and have the following properties:
--
--
-- - Transitivity if x <= y && y <=
-- z = True, then x <= z = True
-- - Reflexivity x <= x = True
-- - Antisymmetry if x <= y && y <=
-- x = True, then x == y = True
--
--
-- Note that the following operator interactions are expected to hold:
--
--
-- - x >= y = y <= x
-- - x < y = x <= y && x /= y
-- - x > y = y < x
-- - x < y = compare x y == LT
-- - x > y = compare x y == GT
-- - x == y = compare x y == EQ
-- - min x y == if x <= y then x else y = True
-- - max x y == if x >= y then x else y = True
--
--
-- Minimal complete definition: either compare or <=.
-- Using compare can be more efficient for complex types.
class Eq a => Ord a
compare :: Ord a => a -> a -> Ordering
(<) :: Ord a => a -> a -> Bool
(<=) :: Ord a => a -> a -> Bool
(>) :: Ord a => a -> a -> Bool
(>=) :: Ord a => a -> a -> Bool
max :: Ord a => a -> a -> a
min :: Ord a => a -> a -> a
infix 4 >=
infix 4 >
infix 4 <
infix 4 <=
-- | Parsing of Strings, producing values.
--
-- Derived instances of Read make the following assumptions, which
-- derived instances of Show obey:
--
--
-- - If the constructor is defined to be an infix operator, then the
-- derived Read instance will parse only infix applications of the
-- constructor (not the prefix form).
-- - Associativity is not used to reduce the occurrence of parentheses,
-- although precedence may be.
-- - If the constructor is defined using record syntax, the derived
-- Read will parse only the record-syntax form, and furthermore,
-- the fields must be given in the same order as the original
-- declaration.
-- - The derived Read instance allows arbitrary Haskell
-- whitespace between tokens of the input string. Extra parentheses are
-- also allowed.
--
--
-- For example, given the declarations
--
--
-- infixr 5 :^:
-- data Tree a = Leaf a | Tree a :^: Tree a
--
--
-- the derived instance of Read in Haskell 2010 is equivalent to
--
--
-- instance (Read a) => Read (Tree a) where
--
-- readsPrec d r = readParen (d > app_prec)
-- (\r -> [(Leaf m,t) |
-- ("Leaf",s) <- lex r,
-- (m,t) <- readsPrec (app_prec+1) s]) r
--
-- ++ readParen (d > up_prec)
-- (\r -> [(u:^:v,w) |
-- (u,s) <- readsPrec (up_prec+1) r,
-- (":^:",t) <- lex s,
-- (v,w) <- readsPrec (up_prec+1) t]) r
--
-- where app_prec = 10
-- up_prec = 5
--
--
-- Note that right-associativity of :^: is unused.
--
-- The derived instance in GHC is equivalent to
--
--
-- instance (Read a) => Read (Tree a) where
--
-- readPrec = parens $ (prec app_prec $ do
-- Ident "Leaf" <- lexP
-- m <- step readPrec
-- return (Leaf m))
--
-- +++ (prec up_prec $ do
-- u <- step readPrec
-- Symbol ":^:" <- lexP
-- v <- step readPrec
-- return (u :^: v))
--
-- where app_prec = 10
-- up_prec = 5
--
-- readListPrec = readListPrecDefault
--
--
-- Why do both readsPrec and readPrec exist, and why does
-- GHC opt to implement readPrec in derived Read instances
-- instead of readsPrec? The reason is that readsPrec is
-- based on the ReadS type, and although ReadS is mentioned
-- in the Haskell 2010 Report, it is not a very efficient parser data
-- structure.
--
-- readPrec, on the other hand, is based on a much more efficient
-- ReadPrec datatype (a.k.a "new-style parsers"), but its
-- definition relies on the use of the RankNTypes language
-- extension. Therefore, readPrec (and its cousin,
-- readListPrec) are marked as GHC-only. Nevertheless, it is
-- recommended to use readPrec instead of readsPrec
-- whenever possible for the efficiency improvements it brings.
--
-- As mentioned above, derived Read instances in GHC will
-- implement readPrec instead of readsPrec. The default
-- implementations of readsPrec (and its cousin, readList)
-- will simply use readPrec under the hood. If you are writing a
-- Read instance by hand, it is recommended to write it like so:
--
--
-- instance Read T where
-- readPrec = ...
-- readListPrec = readListPrecDefault
--
class Read a
-- | attempts to parse a value from the front of the string, returning a
-- list of (parsed value, remaining string) pairs. If there is no
-- successful parse, the returned list is empty.
--
-- Derived instances of Read and Show satisfy the
-- following:
--
--
--
-- That is, readsPrec parses the string produced by
-- showsPrec, and delivers the value that showsPrec started
-- with.
readsPrec :: Read a => Int -> ReadS a
-- | The method readList is provided to allow the programmer to give
-- a specialised way of parsing lists of values. For example, this is
-- used by the predefined Read instance of the Char type,
-- where values of type String should be are expected to use
-- double quotes, rather than square brackets.
readList :: Read a => ReadS [a]
class (Num a, Ord a) => Real a
-- | the rational equivalent of its real argument with full precision
toRational :: Real a => a -> Rational
-- | Efficient, machine-independent access to the components of a
-- floating-point number.
class (RealFrac a, Floating a) => RealFloat a
-- | a constant function, returning the radix of the representation (often
-- 2)
floatRadix :: RealFloat a => a -> Integer
-- | a constant function, returning the number of digits of
-- floatRadix in the significand
floatDigits :: RealFloat a => a -> Int
-- | a constant function, returning the lowest and highest values the
-- exponent may assume
floatRange :: RealFloat a => a -> (Int, Int)
-- | The function decodeFloat applied to a real floating-point
-- number returns the significand expressed as an Integer and an
-- appropriately scaled exponent (an Int). If
-- decodeFloat x yields (m,n), then x
-- is equal in value to m*b^^n, where b is the
-- floating-point radix, and furthermore, either m and
-- n are both zero or else b^(d-1) <= abs m <
-- b^d, where d is the value of floatDigits
-- x. In particular, decodeFloat 0 = (0,0). If the
-- type contains a negative zero, also decodeFloat (-0.0) =
-- (0,0). The result of decodeFloat x is
-- unspecified if either of isNaN x or
-- isInfinite x is True.
decodeFloat :: RealFloat a => a -> (Integer, Int)
-- | encodeFloat performs the inverse of decodeFloat in the
-- sense that for finite x with the exception of -0.0,
-- uncurry encodeFloat (decodeFloat x) =
-- x. encodeFloat m n is one of the two closest
-- representable floating-point numbers to m*b^^n (or
-- ±Infinity if overflow occurs); usually the closer, but if
-- m contains too many bits, the result may be rounded in the
-- wrong direction.
encodeFloat :: RealFloat a => Integer -> Int -> a
-- | exponent corresponds to the second component of
-- decodeFloat. exponent 0 = 0 and for finite
-- nonzero x, exponent x = snd (decodeFloat x)
-- + floatDigits x. If x is a finite floating-point
-- number, it is equal in value to significand x * b ^^
-- exponent x, where b is the floating-point radix.
-- The behaviour is unspecified on infinite or NaN values.
exponent :: RealFloat a => a -> Int
-- | The first component of decodeFloat, scaled to lie in the open
-- interval (-1,1), either 0.0 or of absolute
-- value >= 1/b, where b is the floating-point
-- radix. The behaviour is unspecified on infinite or NaN
-- values.
significand :: RealFloat a => a -> a
-- | multiplies a floating-point number by an integer power of the radix
scaleFloat :: RealFloat a => Int -> a -> a
-- | True if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: RealFloat a => a -> Bool
-- | True if the argument is an IEEE infinity or negative infinity
isInfinite :: RealFloat a => a -> Bool
-- | True if the argument is too small to be represented in
-- normalized format
isDenormalized :: RealFloat a => a -> Bool
-- | True if the argument is an IEEE negative zero
isNegativeZero :: RealFloat a => a -> Bool
-- | True if the argument is an IEEE floating point number
isIEEE :: RealFloat a => a -> Bool
-- | Extracting components of fractions.
class (Real a, Fractional a) => RealFrac a
-- | The function properFraction takes a real fractional number
-- x and returns a pair (n,f) such that x =
-- n+f, and:
--
--
-- - n is an integral number with the same sign as x;
-- and
-- - f is a fraction with the same type and sign as
-- x, and with absolute value less than 1.
--
--
-- The default definitions of the ceiling, floor,
-- truncate and round functions are in terms of
-- properFraction.
properFraction :: (RealFrac a, Integral b) => a -> (b, a)
-- | truncate x returns the integer nearest x
-- between zero and x
truncate :: (RealFrac a, Integral b) => a -> b
-- | round x returns the nearest integer to x; the
-- even integer if x is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b
-- | ceiling x returns the least integer not less than
-- x
ceiling :: (RealFrac a, Integral b) => a -> b
-- | floor x returns the greatest integer not greater than
-- x
floor :: (RealFrac a, Integral b) => a -> b
-- | Conversion of values to readable Strings.
--
-- Derived instances of Show have the following properties, which
-- are compatible with derived instances of Read:
--
--
-- - The result of show is a syntactically correct Haskell
-- expression containing only constants, given the fixity declarations in
-- force at the point where the type is declared. It contains only the
-- constructor names defined in the data type, parentheses, and spaces.
-- When labelled constructor fields are used, braces, commas, field
-- names, and equal signs are also used.
-- - If the constructor is defined to be an infix operator, then
-- showsPrec will produce infix applications of the
-- constructor.
-- - the representation will be enclosed in parentheses if the
-- precedence of the top-level constructor in x is less than
-- d (associativity is ignored). Thus, if d is
-- 0 then the result is never surrounded in parentheses; if
-- d is 11 it is always surrounded in parentheses,
-- unless it is an atomic expression.
-- - If the constructor is defined using record syntax, then
-- show will produce the record-syntax form, with the fields given
-- in the same order as the original declaration.
--
--
-- For example, given the declarations
--
--
-- infixr 5 :^:
-- data Tree a = Leaf a | Tree a :^: Tree a
--
--
-- the derived instance of Show is equivalent to
--
--
-- instance (Show a) => Show (Tree a) where
--
-- showsPrec d (Leaf m) = showParen (d > app_prec) $
-- showString "Leaf " . showsPrec (app_prec+1) m
-- where app_prec = 10
--
-- showsPrec d (u :^: v) = showParen (d > up_prec) $
-- showsPrec (up_prec+1) u .
-- showString " :^: " .
-- showsPrec (up_prec+1) v
-- where up_prec = 5
--
--
-- Note that right-associativity of :^: is ignored. For example,
--
--
-- - show (Leaf 1 :^: Leaf 2 :^: Leaf 3) produces the
-- string "Leaf 1 :^: (Leaf 2 :^: Leaf 3)".
--
class Show a
-- | Convert a value to a readable String.
--
-- showsPrec should satisfy the law
--
--
-- showsPrec d x r ++ s == showsPrec d x (r ++ s)
--
--
-- Derived instances of Read and Show satisfy the
-- following:
--
--
--
-- That is, readsPrec parses the string produced by
-- showsPrec, and delivers the value that showsPrec started
-- with.
showsPrec :: Show a => Int -> a -> ShowS
-- | A specialised variant of showsPrec, using precedence context
-- zero, and returning an ordinary String.
show :: Show a => a -> String
-- | The method showList is provided to allow the programmer to give
-- a specialised way of showing lists of values. For example, this is
-- used by the predefined Show instance of the Char type,
-- where values of type String should be shown in double quotes,
-- rather than between square brackets.
showList :: Show a => [a] -> ShowS
-- | A functor with application, providing operations to
--
--
-- - embed pure expressions (pure), and
-- - sequence computations and combine their results (<*>
-- and liftA2).
--
--
-- A minimal complete definition must include implementations of
-- pure and of either <*> or liftA2. If it
-- defines both, then they must behave the same as their default
-- definitions:
--
--
-- (<*>) = liftA2 id
--
--
--
-- liftA2 f x y = f <$> x <*> y
--
--
-- Further, any definition must satisfy the following:
--
--
--
-- The other methods have the following default definitions, which may be
-- overridden with equivalent specialized implementations:
--
--
--
-- As a consequence of these laws, the Functor instance for
-- f will satisfy
--
--
--
-- It may be useful to note that supposing
--
--
-- forall x y. p (q x y) = f x . g y
--
--
-- it follows from the above that
--
--
-- liftA2 p (liftA2 q u v) = liftA2 f u . liftA2 g v
--
--
-- If f is also a Monad, it should satisfy
--
--
--
-- (which implies that pure and <*> satisfy the
-- applicative functor laws).
class Functor f => Applicative (f :: Type -> Type)
-- | Lift a value.
pure :: Applicative f => a -> f a
-- | Sequential application.
--
-- A few functors support an implementation of <*> that is
-- more efficient than the default one.
(<*>) :: Applicative f => f (a -> b) -> f a -> f b
-- | Sequence actions, discarding the value of the first argument.
(*>) :: Applicative f => f a -> f b -> f b
-- | Sequence actions, discarding the value of the second argument.
(<*) :: Applicative f => f a -> f b -> f a
infixl 4 <*>
infixl 4 *>
infixl 4 <*
-- | Data structures that can be folded.
--
-- For example, given a data type
--
--
-- data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--
--
-- a suitable instance would be
--
--
-- instance Foldable Tree where
-- foldMap f Empty = mempty
-- foldMap f (Leaf x) = f x
-- foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--
--
-- This is suitable even for abstract types, as the monoid is assumed to
-- satisfy the monoid laws. Alternatively, one could define
-- foldr:
--
--
-- instance Foldable Tree where
-- foldr f z Empty = z
-- foldr f z (Leaf x) = f x z
-- foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--
--
-- Foldable instances are expected to satisfy the following
-- laws:
--
--
-- foldr f z t = appEndo (foldMap (Endo . f) t ) z
--
--
--
-- foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--
--
--
-- fold = foldMap id
--
--
--
-- length = getSum . foldMap (Sum . const 1)
--
--
-- sum, product, maximum, and minimum
-- should all be essentially equivalent to foldMap forms, such
-- as
--
--
-- sum = getSum . foldMap Sum
--
--
-- but may be less defined.
--
-- If the type is also a Functor instance, it should satisfy
--
--
-- foldMap f = fold . fmap f
--
--
-- which implies that
--
--
-- foldMap f . fmap g = foldMap (f . g)
--
class Foldable (t :: Type -> Type)
-- | Map each element of the structure to a monoid, and combine the
-- results.
foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m
-- | Right-associative fold of a structure.
--
-- In the case of lists, foldr, when applied to a binary operator,
-- a starting value (typically the right-identity of the operator), and a
-- list, reduces the list using the binary operator, from right to left:
--
--
-- foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
--
--
-- Note that, since the head of the resulting expression is produced by
-- an application of the operator to the first element of the list,
-- foldr can produce a terminating expression from an infinite
-- list.
--
-- For a general Foldable structure this should be semantically
-- identical to,
--
--
-- foldr f z = foldr f z . toList
--
foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b
-- | Left-associative fold of a structure.
--
-- In the case of lists, foldl, when applied to a binary operator,
-- a starting value (typically the left-identity of the operator), and a
-- list, reduces the list using the binary operator, from left to right:
--
--
-- foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn
--
--
-- Note that to produce the outermost application of the operator the
-- entire input list must be traversed. This means that foldl'
-- will diverge if given an infinite list.
--
-- Also note that if you want an efficient left-fold, you probably want
-- to use foldl' instead of foldl. The reason for this is
-- that latter does not force the "inner" results (e.g. z f
-- x1 in the above example) before applying them to the operator
-- (e.g. to (f x2)). This results in a thunk chain
-- O(n) elements long, which then must be evaluated from the
-- outside-in.
--
-- For a general Foldable structure this should be semantically
-- identical to,
--
--
-- foldl f z = foldl f z . toList
--
foldl :: Foldable t => (b -> a -> b) -> b -> t a -> b
-- | A variant of foldr that has no base case, and thus may only be
-- applied to non-empty structures.
--
--
-- foldr1 f = foldr1 f . toList
--
foldr1 :: Foldable t => (a -> a -> a) -> t a -> a
-- | A variant of foldl that has no base case, and thus may only be
-- applied to non-empty structures.
--
--
-- foldl1 f = foldl1 f . toList
--
foldl1 :: Foldable t => (a -> a -> a) -> t a -> a
-- | Test whether the structure is empty. The default implementation is
-- optimized for structures that are similar to cons-lists, because there
-- is no general way to do better.
null :: Foldable t => t a -> Bool
-- | Returns the size/length of a finite structure as an Int. The
-- default implementation is optimized for structures that are similar to
-- cons-lists, because there is no general way to do better.
length :: Foldable t => t a -> Int
-- | Does the element occur in the structure?
elem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `elem`
-- | Functors representing data structures that can be traversed from left
-- to right.
--
-- A definition of traverse must satisfy the following laws:
--
--
--
-- A definition of sequenceA must satisfy the following laws:
--
--
--
-- where an applicative transformation is a function
--
--
-- t :: (Applicative f, Applicative g) => f a -> g a
--
--
-- preserving the Applicative operations, i.e.
--
--
--
-- and the identity functor Identity and composition of functors
-- Compose are defined as
--
--
-- newtype Identity a = Identity a
--
-- instance Functor Identity where
-- fmap f (Identity x) = Identity (f x)
--
-- instance Applicative Identity where
-- pure x = Identity x
-- Identity f <*> Identity x = Identity (f x)
--
-- newtype Compose f g a = Compose (f (g a))
--
-- instance (Functor f, Functor g) => Functor (Compose f g) where
-- fmap f (Compose x) = Compose (fmap (fmap f) x)
--
-- instance (Applicative f, Applicative g) => Applicative (Compose f g) where
-- pure x = Compose (pure (pure x))
-- Compose f <*> Compose x = Compose ((<*>) <$> f <*> x)
--
--
-- (The naturality law is implied by parametricity.)
--
-- Instances are similar to Functor, e.g. given a data type
--
--
-- data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--
--
-- a suitable instance would be
--
--
-- instance Traversable Tree where
-- traverse f Empty = pure Empty
-- traverse f (Leaf x) = Leaf <$> f x
-- traverse f (Node l k r) = Node <$> traverse f l <*> f k <*> traverse f r
--
--
-- This is suitable even for abstract types, as the laws for
-- <*> imply a form of associativity.
--
-- The superclass instances should satisfy the following:
--
--
-- - In the Functor instance, fmap should be equivalent
-- to traversal with the identity applicative functor
-- (fmapDefault).
-- - In the Foldable instance, foldMap should be
-- equivalent to traversal with a constant applicative functor
-- (foldMapDefault).
--
class (Functor t, Foldable t) => Traversable (t :: Type -> Type)
-- | Map each element of a structure to an action, evaluate these actions
-- from left to right, and collect the results. For a version that
-- ignores the results see traverse_.
traverse :: (Traversable t, Applicative f) => (a -> f b) -> t a -> f (t b)
-- | Evaluate each action in the structure from left to right, and collect
-- the results. For a version that ignores the results see
-- sequenceA_.
sequenceA :: (Traversable t, Applicative f) => t (f a) -> f (t a)
-- | Map each element of a structure to a monadic action, evaluate these
-- actions from left to right, and collect the results. For a version
-- that ignores the results see mapM_.
mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)
-- | Evaluate each monadic action in the structure from left to right, and
-- collect the results. For a version that ignores the results see
-- sequence_.
sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)
-- | The class of semigroups (types with an associative binary operation).
--
-- Instances should satisfy the associativity law:
--
--
class Semigroup a
-- | An associative operation.
(<>) :: Semigroup a => a -> a -> a
infixr 6 <>
-- | The class of monoids (types with an associative binary operation that
-- has an identity). Instances should satisfy the following laws:
--
--
--
-- The method names refer to the monoid of lists under concatenation, but
-- there are many other instances.
--
-- Some types can be viewed as a monoid in more than one way, e.g. both
-- addition and multiplication on numbers. In such cases we often define
-- newtypes and make those instances of Monoid, e.g.
-- Sum and Product.
--
-- NOTE: Semigroup is a superclass of Monoid since
-- base-4.11.0.0.
class Semigroup a => Monoid a
-- | Identity of mappend
mempty :: Monoid a => a
-- | An associative operation
--
-- NOTE: This method is redundant and has the default
-- implementation mappend = '(<>)' since
-- base-4.11.0.0.
mappend :: Monoid a => a -> a -> a
-- | Fold a list using the monoid.
--
-- For most types, the default definition for mconcat will be
-- used, but the function is included in the class definition so that an
-- optimized version can be provided for specific types.
mconcat :: Monoid a => [a] -> a
data Bool
False :: Bool
True :: Bool
-- | The character type Char is an enumeration whose values
-- represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
-- characters, see http://www.unicode.org/ for details). This set
-- extends the ISO 8859-1 (Latin-1) character set (the first 256
-- characters), which is itself an extension of the ASCII character set
-- (the first 128 characters). A character literal in Haskell has type
-- Char.
--
-- To convert a Char to or from the corresponding Int value
-- defined by Unicode, use toEnum and fromEnum from the
-- Enum class respectively (or equivalently ord and
-- chr).
data Char
-- | Double-precision floating point numbers. It is desirable that this
-- type be at least equal in range and precision to the IEEE
-- double-precision type.
data Double
-- | Single-precision floating point numbers. It is desirable that this
-- type be at least equal in range and precision to the IEEE
-- single-precision type.
data Float
-- | A fixed-precision integer type with at least the range [-2^29 ..
-- 2^29-1]. The exact range for a given implementation can be
-- determined by using minBound and maxBound from the
-- Bounded class.
data Int
-- | Invariant: Jn# and Jp# are used iff value doesn't fit in
-- S#
--
-- Useful properties resulting from the invariants:
--
--
data Integer
-- | The Maybe type encapsulates an optional value. A value of type
-- Maybe a either contains a value of type a
-- (represented as Just a), or it is empty (represented
-- as Nothing). Using Maybe is a good way to deal with
-- errors or exceptional cases without resorting to drastic measures such
-- as error.
--
-- The Maybe type is also a monad. It is a simple kind of error
-- monad, where all errors are represented by Nothing. A richer
-- error monad can be built using the Either type.
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering
-- | Arbitrary-precision rational numbers, represented as a ratio of two
-- Integer values. A rational number may be constructed using the
-- % operator.
type Rational = Ratio Integer
-- | A value of type IO a is a computation which, when
-- performed, does some I/O before returning a value of type a.
--
-- There is really only one way to "perform" an I/O action: bind it to
-- Main.main in your program. When your program is run, the I/O
-- will be performed. It isn't possible to perform I/O from an arbitrary
-- function, unless that function is itself in the IO monad and
-- called at some point, directly or indirectly, from Main.main.
--
-- IO is a monad, so IO actions can be combined using
-- either the do-notation or the >> and >>=
-- operations from the Monad class.
data IO a
-- | A Word is an unsigned integral type, with the same size as
-- Int.
data Word
-- | The Either type represents values with two possibilities: a
-- value of type Either a b is either Left
-- a or Right b.
--
-- The Either type is sometimes used to represent a value which is
-- either correct or an error; by convention, the Left constructor
-- is used to hold an error value and the Right constructor is
-- used to hold a correct value (mnemonic: "right" also means "correct").
--
-- Examples
--
-- The type Either String Int is the type
-- of values which can be either a String or an Int. The
-- Left constructor can be used only on Strings, and the
-- Right constructor can be used only on Ints:
--
--
-- >>> let s = Left "foo" :: Either String Int
--
-- >>> s
-- Left "foo"
--
-- >>> let n = Right 3 :: Either String Int
--
-- >>> n
-- Right 3
--
-- >>> :type s
-- s :: Either String Int
--
-- >>> :type n
-- n :: Either String Int
--
--
-- The fmap from our Functor instance will ignore
-- Left values, but will apply the supplied function to values
-- contained in a Right:
--
--
-- >>> let s = Left "foo" :: Either String Int
--
-- >>> let n = Right 3 :: Either String Int
--
-- >>> fmap (*2) s
-- Left "foo"
--
-- >>> fmap (*2) n
-- Right 6
--
--
-- The Monad instance for Either allows us to chain
-- together multiple actions which may fail, and fail overall if any of
-- the individual steps failed. First we'll write a function that can
-- either parse an Int from a Char, or fail.
--
--
-- >>> import Data.Char ( digitToInt, isDigit )
--
-- >>> :{
-- let parseEither :: Char -> Either String Int
-- parseEither c
-- | isDigit c = Right (digitToInt c)
-- | otherwise = Left "parse error"
--
-- >>> :}
--
--
-- The following should work, since both '1' and '2'
-- can be parsed as Ints.
--
--
-- >>> :{
-- let parseMultiple :: Either String Int
-- parseMultiple = do
-- x <- parseEither '1'
-- y <- parseEither '2'
-- return (x + y)
--
-- >>> :}
--
--
--
-- >>> parseMultiple
-- Right 3
--
--
-- But the following should fail overall, since the first operation where
-- we attempt to parse 'm' as an Int will fail:
--
--
-- >>> :{
-- let parseMultiple :: Either String Int
-- parseMultiple = do
-- x <- parseEither 'm'
-- y <- parseEither '2'
-- return (x + y)
--
-- >>> :}
--
--
--
-- >>> parseMultiple
-- Left "parse error"
--
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b
-- | The readIO function is similar to read except that it
-- signals parse failure to the IO monad instead of terminating
-- the program.
readIO :: Read a => String -> IO a
-- | The readLn function combines getLine and readIO.
readLn :: Read a => IO a
-- | The computation appendFile file str function appends
-- the string str, to the file file.
--
-- Note that writeFile and appendFile write a literal
-- string to a file. To write a value of any printable type, as with
-- print, use the show function to convert the value to a
-- string first.
--
--
-- main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])
--
appendFile :: FilePath -> String -> IO ()
-- | The computation writeFile file str function writes the
-- string str, to the file file.
writeFile :: FilePath -> String -> IO ()
-- | The readFile function reads a file and returns the contents of
-- the file as a string. The file is read lazily, on demand, as with
-- getContents.
readFile :: FilePath -> IO String
-- | The interact function takes a function of type
-- String->String as its argument. The entire input from the
-- standard input device is passed to this function as its argument, and
-- the resulting string is output on the standard output device.
interact :: (String -> String) -> IO ()
-- | The getContents operation returns all user input as a single
-- string, which is read lazily as it is needed (same as
-- hGetContents stdin).
getContents :: IO String
-- | Read a line from the standard input device (same as hGetLine
-- stdin).
getLine :: IO String
-- | Read a character from the standard input device (same as
-- hGetChar stdin).
getChar :: IO Char
-- | The same as putStr, but adds a newline character.
putStrLn :: String -> IO ()
-- | Write a string to the standard output device (same as hPutStr
-- stdout).
putStr :: String -> IO ()
-- | Write a character to the standard output device (same as
-- hPutChar stdout).
putChar :: Char -> IO ()
-- | Raise an IOException in the IO monad.
ioError :: () => IOError -> IO a
-- | File and directory names are values of type String, whose
-- precise meaning is operating system dependent. Files can be opened,
-- yielding a handle which can then be used to operate on the contents of
-- that file.
type FilePath = String
-- | Construct an IOException value with a string describing the
-- error. The fail method of the IO instance of the
-- Monad class raises a userError, thus:
--
--
-- instance Monad IO where
-- ...
-- fail s = ioError (userError s)
--
userError :: String -> IOError
-- | The Haskell 2010 type for exceptions in the IO monad. Any I/O
-- operation may raise an IOException instead of returning a
-- result. For a more general type of exception, including also those
-- that arise in pure code, see Exception.
--
-- In Haskell 2010, this is an opaque type.
type IOError = IOException
-- | notElem is the negation of elem.
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`
-- | Determines whether all elements of the structure satisfy the
-- predicate.
all :: Foldable t => (a -> Bool) -> t a -> Bool
-- | Determines whether any element of the structure satisfies the
-- predicate.
any :: Foldable t => (a -> Bool) -> t a -> Bool
-- | or returns the disjunction of a container of Bools. For the
-- result to be False, the container must be finite; True,
-- however, results from a True value finitely far from the left
-- end.
or :: Foldable t => t Bool -> Bool
-- | and returns the conjunction of a container of Bools. For the
-- result to be True, the container must be finite; False,
-- however, results from a False value finitely far from the left
-- end.
and :: Foldable t => t Bool -> Bool
-- | Map a function over all the elements of a container and concatenate
-- the resulting lists.
concatMap :: Foldable t => (a -> [b]) -> t a -> [b]
-- | The concatenation of all the elements of a container of lists.
concat :: Foldable t => t [a] -> [a]
-- | Evaluate each monadic action in the structure from left to right, and
-- ignore the results. For a version that doesn't ignore the results see
-- sequence.
--
-- As of base 4.8.0.0, sequence_ is just sequenceA_,
-- specialized to Monad.
sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()
-- | Map each element of a structure to a monadic action, evaluate these
-- actions from left to right, and ignore the results. For a version that
-- doesn't ignore the results see mapM.
--
-- As of base 4.8.0.0, mapM_ is just traverse_, specialized
-- to Monad.
mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()
-- | unwords is an inverse operation to words. It joins words
-- with separating spaces.
--
--
-- >>> unwords ["Lorem", "ipsum", "dolor"]
-- "Lorem ipsum dolor"
--
unwords :: [String] -> String
-- | words breaks a string up into a list of words, which were
-- delimited by white space.
--
--
-- >>> words "Lorem ipsum\ndolor"
-- ["Lorem","ipsum","dolor"]
--
words :: String -> [String]
-- | unlines is an inverse operation to lines. It joins
-- lines, after appending a terminating newline to each.
--
--
-- >>> unlines ["Hello", "World", "!"]
-- "Hello\nWorld\n!\n"
--
unlines :: [String] -> String
-- | lines breaks a string up into a list of strings at newline
-- characters. The resulting strings do not contain newlines.
--
-- Note that after splitting the string at newline characters, the last
-- part of the string is considered a line even if it doesn't end with a
-- newline. For example,
--
--
-- >>> lines ""
-- []
--
--
--
-- >>> lines "\n"
-- [""]
--
--
--
-- >>> lines "one"
-- ["one"]
--
--
--
-- >>> lines "one\n"
-- ["one"]
--
--
--
-- >>> lines "one\n\n"
-- ["one",""]
--
--
--
-- >>> lines "one\ntwo"
-- ["one","two"]
--
--
--
-- >>> lines "one\ntwo\n"
-- ["one","two"]
--
--
-- Thus lines s contains at least as many elements as
-- newlines in s.
lines :: String -> [String]
-- | The read function reads input from a string, which must be
-- completely consumed by the input process. read fails with an
-- error if the parse is unsuccessful, and it is therefore
-- discouraged from being used in real applications. Use readMaybe
-- or readEither for safe alternatives.
--
--
-- >>> read "123" :: Int
-- 123
--
--
--
-- >>> read "hello" :: Int
-- *** Exception: Prelude.read: no parse
--
read :: Read a => String -> a
-- | equivalent to readsPrec with a precedence of 0.
reads :: Read a => ReadS a
-- | Case analysis for the Either type. If the value is
-- Left a, apply the first function to a; if it
-- is Right b, apply the second function to b.
--
-- Examples
--
-- We create two values of type Either String
-- Int, one using the Left constructor and another
-- using the Right constructor. Then we apply "either" the
-- length function (if we have a String) or the
-- "times-two" function (if we have an Int):
--
--
-- >>> let s = Left "foo" :: Either String Int
--
-- >>> let n = Right 3 :: Either String Int
--
-- >>> either length (*2) s
-- 3
--
-- >>> either length (*2) n
-- 6
--
either :: () => (a -> c) -> (b -> c) -> Either a b -> c
-- | The lex function reads a single lexeme from the input,
-- discarding initial white space, and returning the characters that
-- constitute the lexeme. If the input string contains only white space,
-- lex returns a single successful `lexeme' consisting of the
-- empty string. (Thus lex "" = [("","")].) If there is
-- no legal lexeme at the beginning of the input string, lex fails
-- (i.e. returns []).
--
-- This lexer is not completely faithful to the Haskell lexical syntax in
-- the following respects:
--
--
-- - Qualified names are not handled properly
-- - Octal and hexadecimal numerics are not recognized as a single
-- token
-- - Comments are not treated properly
--
lex :: ReadS String
-- | readParen True p parses what p parses,
-- but surrounded with parentheses.
--
-- readParen False p parses what p
-- parses, but optionally surrounded with parentheses.
readParen :: () => Bool -> ReadS a -> ReadS a
-- | A parser for a type a, represented as a function that takes a
-- String and returns a list of possible parses as
-- (a,String) pairs.
--
-- Note that this kind of backtracking parser is very inefficient;
-- reading a large structure may be quite slow (cf ReadP).
type ReadS a = String -> [(a, String)]
-- | An infix synonym for fmap.
--
-- The name of this operator is an allusion to $. Note the
-- similarities between their types:
--
--
-- ($) :: (a -> b) -> a -> b
-- (<$>) :: Functor f => (a -> b) -> f a -> f b
--
--
-- Whereas $ is function application, <$> is
-- function application lifted over a Functor.
--
-- Examples
--
-- Convert from a Maybe Int to a
-- Maybe String using show:
--
--
-- >>> show <$> Nothing
-- Nothing
--
-- >>> show <$> Just 3
-- Just "3"
--
--
-- Convert from an Either Int Int to
-- an Either Int String using
-- show:
--
--
-- >>> show <$> Left 17
-- Left 17
--
-- >>> show <$> Right 17
-- Right "17"
--
--
-- Double each element of a list:
--
--
-- >>> (*2) <$> [1,2,3]
-- [2,4,6]
--
--
-- Apply even to the second element of a pair:
--
--
-- >>> even <$> (2,2)
-- (2,True)
--
(<$>) :: Functor f => (a -> b) -> f a -> f b
infixl 4 <$>
-- | lcm x y is the smallest positive integer that both
-- x and y divide.
lcm :: Integral a => a -> a -> a
-- | gcd x y is the non-negative factor of both x
-- and y of which every common factor of x and
-- y is also a factor; for example gcd 4 2 = 2,
-- gcd (-4) 6 = 2, gcd 0 4 = 4.
-- gcd 0 0 = 0. (That is, the common divisor
-- that is "greatest" in the divisibility preordering.)
--
-- Note: Since for signed fixed-width integer types, abs
-- minBound < 0, the result may be negative if one of the
-- arguments is minBound (and necessarily is if the other
-- is 0 or minBound) for such types.
gcd :: Integral a => a -> a -> a
-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^
odd :: Integral a => a -> Bool
even :: Integral a => a -> Bool
-- | utility function that surrounds the inner show function with
-- parentheses when the Bool parameter is True.
showParen :: Bool -> ShowS -> ShowS
-- | utility function converting a String to a show function that
-- simply prepends the string unchanged.
showString :: String -> ShowS
-- | utility function converting a Char to a show function that
-- simply prepends the character unchanged.
showChar :: Char -> ShowS
-- | equivalent to showsPrec with a precedence of 0.
shows :: Show a => a -> ShowS
-- | The shows functions return a function that prepends the
-- output String to an existing String. This allows
-- constant-time concatenation of results using function composition.
type ShowS = String -> String
-- | The unzip3 function takes a list of triples and returns three
-- lists, analogous to unzip.
unzip3 :: () => [(a, b, c)] -> ([a], [b], [c])
-- | unzip transforms a list of pairs into a list of first
-- components and a list of second components.
unzip :: () => [(a, b)] -> ([a], [b])
-- | The zipWith3 function takes a function which combines three
-- elements, as well as three lists and returns a list of their
-- point-wise combination, analogous to zipWith.
zipWith3 :: () => (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d]
-- | zipWith generalises zip by zipping with the function
-- given as the first argument, instead of a tupling function. For
-- example, zipWith (+) is applied to two lists to
-- produce the list of corresponding sums.
--
-- zipWith is right-lazy:
--
--
-- zipWith f [] _|_ = []
--
zipWith :: () => (a -> b -> c) -> [a] -> [b] -> [c]
-- | zip3 takes three lists and returns a list of triples, analogous
-- to zip.
zip3 :: () => [a] -> [b] -> [c] -> [(a, b, c)]
-- | List index (subscript) operator, starting from 0. It is an instance of
-- the more general genericIndex, which takes an index of any
-- integral type.
(!!) :: () => [a] -> Int -> a
infixl 9 !!
-- | lookup key assocs looks up a key in an association
-- list.
lookup :: Eq a => a -> [(a, b)] -> Maybe b
-- | reverse xs returns the elements of xs in
-- reverse order. xs must be finite.
reverse :: () => [a] -> [a]
-- | break, applied to a predicate p and a list
-- xs, returns a tuple where first element is longest prefix
-- (possibly empty) of xs of elements that do not satisfy
-- p and second element is the remainder of the list:
--
--
-- break (> 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
-- break (< 9) [1,2,3] == ([],[1,2,3])
-- break (> 9) [1,2,3] == ([1,2,3],[])
--
--
-- break p is equivalent to span (not .
-- p).
break :: () => (a -> Bool) -> [a] -> ([a], [a])
-- | span, applied to a predicate p and a list xs,
-- returns a tuple where first element is longest prefix (possibly empty)
-- of xs of elements that satisfy p and second element
-- is the remainder of the list:
--
--
-- span (< 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4])
-- span (< 9) [1,2,3] == ([1,2,3],[])
-- span (< 0) [1,2,3] == ([],[1,2,3])
--
--
-- span p xs is equivalent to (takeWhile p xs,
-- dropWhile p xs)
span :: () => (a -> Bool) -> [a] -> ([a], [a])
-- | splitAt n xs returns a tuple where first element is
-- xs prefix of length n and second element is the
-- remainder of the list:
--
--
-- splitAt 6 "Hello World!" == ("Hello ","World!")
-- splitAt 3 [1,2,3,4,5] == ([1,2,3],[4,5])
-- splitAt 1 [1,2,3] == ([1],[2,3])
-- splitAt 3 [1,2,3] == ([1,2,3],[])
-- splitAt 4 [1,2,3] == ([1,2,3],[])
-- splitAt 0 [1,2,3] == ([],[1,2,3])
-- splitAt (-1) [1,2,3] == ([],[1,2,3])
--
--
-- It is equivalent to (take n xs, drop n xs) when
-- n is not _|_ (splitAt _|_ xs = _|_).
-- splitAt is an instance of the more general
-- genericSplitAt, in which n may be of any integral
-- type.
splitAt :: () => Int -> [a] -> ([a], [a])
-- | drop n xs returns the suffix of xs after the
-- first n elements, or [] if n > length
-- xs:
--
--
-- drop 6 "Hello World!" == "World!"
-- drop 3 [1,2,3,4,5] == [4,5]
-- drop 3 [1,2] == []
-- drop 3 [] == []
-- drop (-1) [1,2] == [1,2]
-- drop 0 [1,2] == [1,2]
--
--
-- It is an instance of the more general genericDrop, in which
-- n may be of any integral type.
drop :: () => Int -> [a] -> [a]
-- | take n, applied to a list xs, returns the
-- prefix of xs of length n, or xs itself if
-- n > length xs:
--
--
-- take 5 "Hello World!" == "Hello"
-- take 3 [1,2,3,4,5] == [1,2,3]
-- take 3 [1,2] == [1,2]
-- take 3 [] == []
-- take (-1) [1,2] == []
-- take 0 [1,2] == []
--
--
-- It is an instance of the more general genericTake, in which
-- n may be of any integral type.
take :: () => Int -> [a] -> [a]
-- | dropWhile p xs returns the suffix remaining after
-- takeWhile p xs:
--
--
-- dropWhile (< 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
-- dropWhile (< 9) [1,2,3] == []
-- dropWhile (< 0) [1,2,3] == [1,2,3]
--
dropWhile :: () => (a -> Bool) -> [a] -> [a]
-- | takeWhile, applied to a predicate p and a list
-- xs, returns the longest prefix (possibly empty) of
-- xs of elements that satisfy p:
--
--
-- takeWhile (< 3) [1,2,3,4,1,2,3,4] == [1,2]
-- takeWhile (< 9) [1,2,3] == [1,2,3]
-- takeWhile (< 0) [1,2,3] == []
--
takeWhile :: () => (a -> Bool) -> [a] -> [a]
-- | cycle ties a finite list into a circular one, or equivalently,
-- the infinite repetition of the original list. It is the identity on
-- infinite lists.
cycle :: () => [a] -> [a]
-- | replicate n x is a list of length n with
-- x the value of every element. It is an instance of the more
-- general genericReplicate, in which n may be of any
-- integral type.
replicate :: () => Int -> a -> [a]
-- | repeat x is an infinite list, with x the
-- value of every element.
repeat :: () => a -> [a]
-- | iterate f x returns an infinite list of repeated
-- applications of f to x:
--
--
-- iterate f x == [x, f x, f (f x), ...]
--
--
-- Note that iterate is lazy, potentially leading to thunk
-- build-up if the consumer doesn't force each iterate. See 'iterate\''
-- for a strict variant of this function.
iterate :: () => (a -> a) -> a -> [a]
-- | scanr1 is a variant of scanr that has no starting value
-- argument.
scanr1 :: () => (a -> a -> a) -> [a] -> [a]
-- | scanr is the right-to-left dual of scanl. Note that
--
--
-- head (scanr f z xs) == foldr f z xs.
--
scanr :: () => (a -> b -> b) -> b -> [a] -> [b]
-- | scanl1 is a variant of scanl that has no starting value
-- argument:
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: () => (a -> a -> a) -> [a] -> [a]
-- | scanl is similar to foldl, but returns a list of
-- successive reduced values from the left:
--
--
-- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--
--
-- Note that
--
--
-- last (scanl f z xs) == foldl f z xs.
--
scanl :: () => (b -> a -> b) -> b -> [a] -> [b]
-- | Return all the elements of a list except the last one. The list must
-- be non-empty.
init :: () => [a] -> [a]
-- | Extract the last element of a list, which must be finite and
-- non-empty.
last :: () => [a] -> a
-- | Extract the elements after the head of a list, which must be
-- non-empty.
tail :: () => [a] -> [a]
-- | Extract the first element of a list, which must be non-empty.
head :: () => [a] -> a
-- | The maybe function takes a default value, a function, and a
-- Maybe value. If the Maybe value is Nothing, the
-- function returns the default value. Otherwise, it applies the function
-- to the value inside the Just and returns the result.
--
-- Examples
--
-- Basic usage:
--
--
-- >>> maybe False odd (Just 3)
-- True
--
--
--
-- >>> maybe False odd Nothing
-- False
--
--
-- Read an integer from a string using readMaybe. If we succeed,
-- return twice the integer; that is, apply (*2) to it. If
-- instead we fail to parse an integer, return 0 by default:
--
--
-- >>> import Text.Read ( readMaybe )
--
-- >>> maybe 0 (*2) (readMaybe "5")
-- 10
--
-- >>> maybe 0 (*2) (readMaybe "")
-- 0
--
--
-- Apply show to a Maybe Int. If we have Just
-- n, we want to show the underlying Int n. But if
-- we have Nothing, we return the empty string instead of (for
-- example) "Nothing":
--
--
-- >>> maybe "" show (Just 5)
-- "5"
--
-- >>> maybe "" show Nothing
-- ""
--
maybe :: () => b -> (a -> b) -> Maybe a -> b
-- | uncurry converts a curried function to a function on pairs.
--
-- Examples
--
--
-- >>> uncurry (+) (1,2)
-- 3
--
--
--
-- >>> uncurry ($) (show, 1)
-- "1"
--
--
--
-- >>> map (uncurry max) [(1,2), (3,4), (6,8)]
-- [2,4,8]
--
uncurry :: () => (a -> b -> c) -> (a, b) -> c
-- | curry converts an uncurried function to a curried function.
--
-- Examples
--
--
-- >>> curry fst 1 2
-- 1
--
curry :: () => ((a, b) -> c) -> a -> b -> c
-- | the same as flip (-).
--
-- Because - is treated specially in the Haskell grammar,
-- (- e) is not a section, but an application of
-- prefix negation. However, (subtract
-- exp) is equivalent to the disallowed section.
subtract :: Num a => a -> a -> a
-- | asTypeOf is a type-restricted version of const. It is
-- usually used as an infix operator, and its typing forces its first
-- argument (which is usually overloaded) to have the same type as the
-- second.
asTypeOf :: () => a -> a -> a
-- | until p f yields the result of applying f
-- until p holds.
until :: () => (a -> Bool) -> (a -> a) -> a -> a
-- | Strict (call-by-value) application operator. It takes a function and
-- an argument, evaluates the argument to weak head normal form (WHNF),
-- then calls the function with that value.
($!) :: () => (a -> b) -> a -> b
infixr 0 $!
-- | flip f takes its (first) two arguments in the reverse
-- order of f.
--
--
-- >>> flip (++) "hello" "world"
-- "worldhello"
--
flip :: () => (a -> b -> c) -> b -> a -> c
-- | const x is a unary function which evaluates to x for
-- all inputs.
--
--
-- >>> const 42 "hello"
-- 42
--
--
--
-- >>> map (const 42) [0..3]
-- [42,42,42,42]
--
const :: () => a -> b -> a
-- | Same as >>=, but with the arguments interchanged.
(=<<) :: Monad m => (a -> m b) -> m a -> m b
infixr 1 =<<
-- | A String is a list of characters. String constants in Haskell
-- are values of type String.
type String = [Char]
-- | A special case of error. It is expected that compilers will
-- recognize this and insert error messages which are more appropriate to
-- the context in which undefined appears.
undefined :: HasCallStack => a
-- | A variant of error that does not produce a stack trace.
errorWithoutStackTrace :: () => [Char] -> a
-- | error stops execution and displays an error message.
error :: HasCallStack => [Char] -> a
-- | Boolean "and"
(&&) :: Bool -> Bool -> Bool
infixr 3 &&
-- | Boolean "or"
(||) :: Bool -> Bool -> Bool
infixr 2 ||
-- | Boolean "not"
not :: Bool -> Bool
-- | Summary
--
-- This module defines units that are not part of the SI, with the
-- exception of those defined in the
-- Numeric.Units.Dimensional.SIUnits module (units outside of the
-- SI accepted for use with the SI).
--
-- Any chapters, sections or tables referenced are from [1] unless
-- otherwise specified.
--
-- Neper, bel, shannon and the like
--
-- The units of section 5.1.2 are purposefully (but not permanently)
-- omitted. In fact the logarithmic units (see section 8.7) are
-- problematic and it is not clear how to implement them. Perhaps with a
-- conversion function similar to for degrees Celsius.
--
-- References
--
--
-- - http://physics.nist.gov/Pubs/SP811/
--
-- - http://www.iau.org/science/publications/proceedings_rules/units/
-- - http://en.m.wikipedia.org/wiki/Pressure
-- - http://en.m.wikipedia.org/wiki/Torr
--
module Numeric.Units.Dimensional.NonSI
electronVolt :: Floating a => Unit 'Metric DEnergy a
unifiedAtomicMassUnit :: Floating a => Unit 'Metric DMass a
dalton :: Floating a => Unit 'Metric DMass a
-- | One gee is the standard value of the acceleration due to gravity at
-- the Earth's surface, as standardized by CIPM.
--
-- Note that local values of acceleration due to gravity will differ from
-- the standard gravity.
--
-- See here for further information.
--
--
-- >>> 1 *~ gee
-- 9.80665 m s^-2
--
--
--
-- >>> 1 *~ gee :: Acceleration Rational
-- 196133 % 20000 m s^-2
--
gee :: Fractional a => Unit 'Metric DAcceleration a
-- | One avoirdupois pound is a mass, exactly defined in terms of the
-- kilogram by the international yard and pound agreement of 1959.
--
-- See here for further information.
--
--
-- >>> 1 *~ poundMass
-- 0.45359237 kg
--
--
--
-- >>> 1 *~ poundMass :: Mass Rational
-- 45359237 % 100000000 kg
--
poundMass :: Fractional a => Unit 'NonMetric DMass a
-- | One avoirdupois ounce is one sixteenth of a poundMass.
--
-- See here for further information.
--
--
-- >>> 1 *~ ounce
-- 2.8349523125e-2 kg
--
--
--
-- 16 *~ ounce === 1 *~ poundMass
--
--
--
-- >>> 1 *~ ounce :: Mass Rational
-- 45359237 % 1600000000 kg
--
ounce :: Fractional a => Unit 'NonMetric DMass a
-- | The pound-force is equal to the gravitational force exerted on a mass
-- of one avoirdupois pound on the surface of Earth.
--
-- This definition is based on standard gravity (the gee) and the
-- international avoirdupois poundMass.
--
-- See here for further information.
--
--
-- >>> 1 *~ poundForce
-- 4.4482216152605 m kg s^-2
--
--
--
-- 1 *~ poundForce === 1 *~ poundMass * (1 *~ gee)
--
--
--
-- >>> 1 *~ poundForce :: Force Rational
-- 8896443230521 % 2000000000000 m kg s^-2
--
poundForce :: Fractional a => Unit 'NonMetric DForce a
-- | One mechanical horsepower is by definition the power necessary to
-- apply a force of 550 poundForce through a distance of one
-- foot per second.
--
-- See here for further information.
--
--
-- >>> 1 *~ horsepower
-- 745.6998715822702 m^2 kg s^-3
--
--
--
-- 1 *~ horsepower === 550 *~ poundForce * (1 *~ foot) / (1 *~ second)
--
--
--
-- >>> 1 *~ horsepower :: Power Rational
-- 37284993579113511 % 50000000000000 m^2 kg s^-3
--
horsepower :: Fractional a => Unit 'NonMetric DPower a
-- | One btu is is the QuantityOfHeat required to raise the
-- temperature of 1 avoirdupois poundMass of liquid water by 1
-- degreeFahrenheit at a constant pressure of one
-- atmosphere.
--
-- Because this value must be determined experimentally and varies with
-- temperature, several standardized values of the btu have arisen. This
-- is the value based on the International Steam Table calorie, defined
-- by the Fifth International Conference on the Properties of Steam.
--
-- See here for further information.
--
--
-- >>> 1 *~ btu
-- 1055.05585262 m^2 kg s^-2
--
--
--
-- >>> 1 *~ btu :: Energy Rational
-- 52752792631 % 50000000 m^2 kg s^-2
--
btu :: Fractional a => Unit 'NonMetric DEnergy a
-- | One short ton is two thousand poundMass.
--
-- See here for further information.
--
--
-- >>> 1 *~ shortTon
-- 907.18474 kg
--
--
--
-- >>> 1 *~ shortTon :: Mass Rational
-- 45359237 % 50000 kg
--
shortTon :: Fractional a => Unit 'NonMetric DMass a
-- | One nautical mile is a unit of length, set by international agreement
-- as being exactly 1 852 meters.
--
-- Historically, it was defined as the distance spanned by one minute of
-- arc along a meridian of the Earth.
--
-- See here for further information.
--
--
-- >>> 1 *~ nauticalMile
-- 1852.0 m
--
--
--
-- >>> 1 *~ nauticalMile :: Length Rational
-- 1852 % 1 m
--
nauticalMile :: Num a => Unit 'NonMetric DLength a
-- | One knot is a velocity equal to one nauticalMile per
-- hour.
--
-- See here for further information.
--
--
-- >>> 1 *~ knot
-- 0.5144444444444445 m s^-1
--
--
--
-- >>> 1 *~ knot :: Velocity Rational
-- 463 % 900 m s^-1
--
knot :: Fractional a => Unit 'NonMetric DVelocity a
-- | One revolution is an angle equal to 2 pi radians; a full circle.
--
-- See here for further information.
--
--
-- >>> 1 *~ revolution
-- 6.283185307179586
--
--
--
-- 1 *~ revolution === _2 * pi * (1 *~ radian)
--
--
--
-- 1 *~ revolution === 360 *~ degree
--
revolution :: Floating a => Unit 'NonMetric DOne a
solid :: Floating a => Unit 'NonMetric DOne a
-- | The slug is a unit of mass associated with Imperial units and United
-- States customary units. It is a mass that accelerates by 1 foot per
-- second per second when a force of one pound is exerted on it.
--
-- This definition is based on standard gravity (the gee), the
-- international foot, and the international avoirdupois
-- poundMass.
--
-- See here for further information.
--
--
-- >>> 1 *~ slug
-- 14.593902937206364 kg
--
--
--
-- >>> 1 *~ slug :: Mass Rational
-- 8896443230521 % 609600000000 kg
--
slug :: Fractional a => Unit 'NonMetric DMass a
-- | One psi is a pressure of one poundForce per square
-- inch of area.
--
-- See here for further information.
--
--
-- >>> 1 *~ psi
-- 6894.757293168362 m^-1 kg s^-2
--
--
--
-- >>> 1 *~ psi :: Pressure Rational
-- 8896443230521 % 1290320000 m^-1 kg s^-2
--
psi :: Fractional a => Unit 'NonMetric DPressure a
teaspoon :: Fractional a => Unit 'NonMetric DVolume a
-- | One international foot is one third of an international yard.
--
-- See here for further information.
--
--
-- >>> 1 *~ foot
-- 0.3048 m
--
--
--
-- 3 *~ foot === 1 *~ yard
--
--
--
-- >>> 1 *~ foot :: Length Rational
-- 381 % 1250 m
--
foot :: Fractional a => Unit 'NonMetric DLength a
-- | One inch is one twelth of a foot.
--
-- This inch is based on the international foot.
--
-- See here for further information.
--
--
-- >>> 1 *~ inch
-- 2.54e-2 m
--
--
--
-- 12 *~ inch === 1 *~ foot
--
--
--
-- >>> 1 *~ inch :: Length Rational
-- 127 % 5000 m
--
inch :: Fractional a => Unit 'NonMetric DLength a
-- | One mil is one thousandth of an inch.
--
-- This mil is based on the international inch.
--
-- See here for further information.
--
--
-- >>> 1 *~ mil
-- 2.54e-5 m
--
--
--
-- 1000 *~ mil === 1 *~ inch
--
--
--
-- >>> 1 *~ mil :: Length Rational
-- 127 % 5000000 m
--
mil :: Fractional a => Unit 'NonMetric DLength a
-- | One yard, as defined by international agreement in 1959, is precisely
-- 0.9144 meter.
--
-- See here for further information.
--
--
-- >>> 1 *~ yard
-- 0.9144 m
--
--
--
-- >>> 1 *~ yard :: Length Rational
-- 1143 % 1250 m
--
yard :: Fractional a => Unit 'NonMetric DLength a
-- | One mile is 5 280 feet.
--
-- This mile is based on the international foot.
--
-- See here for further information.
--
--
-- >>> 1 *~ mile
-- 1609.344 m
--
--
--
-- 1 *~ mile === 5280 *~ foot
--
--
--
-- >>> 1 *~ mile :: Length Rational
-- 201168 % 125 m
--
mile :: Fractional a => Unit 'NonMetric DLength a
-- | One acre is 43 560 square feet.
--
-- This acre is based on the international foot. For the acre
-- based on the US Survey Foot, see usSurveyAcre. While both acres
-- are in use, the difference between them is of little consequence for
-- most applications in which either is used.
--
-- See here for further information.
--
--
-- >>> 1 *~ acre
-- 4046.8564224 m^2
--
--
--
-- 1 *~ acre === 43560 *~ foot ^ pos2
--
--
--
-- >>> 1 *~ acre :: Area Rational
-- 316160658 % 78125 m^2
--
acre :: Fractional a => Unit 'NonMetric DArea a
-- | One US survey foot is 1200/3937 meter.
--
-- For the international foot, see foot. Note that this is not the
-- foot in routine use in the United States.
--
-- See here for further information.
--
--
-- >>> 1 *~ usSurveyFoot
-- 0.3048006096012192 m
--
--
--
-- >>> 1 *~ usSurveyFoot :: Length Rational
-- 1200 % 3937 m
--
usSurveyFoot :: Fractional a => Unit 'NonMetric DLength a
-- | One inch is one twelth of a foot.
--
-- This inch is based on the usSurveyFoot. For the inch based on
-- the international foot, see inch. Note that this is not the
-- inch in routine use in the United States.
--
-- See here for further information.
--
--
-- >>> 1 *~ usSurveyInch
-- 2.54000508001016e-2 m
--
--
--
-- 12 *~ usSurveyInch === 1 *~ usSurveyFoot
--
--
--
-- >>> 1 *~ usSurveyInch :: Length Rational
-- 100 % 3937 m
--
usSurveyInch :: Fractional a => Unit 'NonMetric DLength a
-- | One mil is one thousandth of an inch.
--
-- This mil is based on the usSurveyInch. For the mil based on the
-- international inch, see mil. Note that this is not the mil in
-- routine use in the United States.
--
-- See here for further information.
--
--
-- >>> 1 *~ usSurveyMil
-- 2.54000508001016e-5 m
--
--
--
-- 1000 *~ usSurveyMil === 1 *~ usSurveyInch
--
--
--
-- >>> 1 *~ usSurveyMil :: Length Rational
-- 1 % 39370 m
--
usSurveyMil :: Fractional a => Unit 'NonMetric DLength a
-- | One yard is three feet.
--
-- This yard is based on the usSurveyFoot. For the international
-- yard, see yard. Note that this is not the yard in routine use
-- in the United States.
--
-- See here for further information.
--
--
-- >>> 1 *~ usSurveyYard
-- 0.9144018288036576 m
--
--
--
-- 1 *~ usSurveyYard === 3 *~ usSurveyFoot
--
--
--
-- >>> 1 *~ usSurveyYard :: Length Rational
-- 3600 % 3937 m
--
usSurveyYard :: Fractional a => Unit 'NonMetric DLength a
-- | One US survey mile is 5 280 US survey feet.
--
-- This mile is based on the usSurveyFoot. For the mile based on
-- the international foot, see mile. Note that this is not the
-- mile in routine use in the United States.
--
-- See here for further information.
--
--
-- >>> 1 *~ usSurveyMile
-- 1609.3472186944373 m
--
--
--
-- 1 *~ usSurveyMile === 5280 *~ usSurveyFoot
--
--
--
-- >>> 1 *~ usSurveyMile :: Length Rational
-- 6336000 % 3937 m
--
usSurveyMile :: Fractional a => Unit 'NonMetric DLength a
-- | One acre is 43 560 square feet.
--
-- This acre is based on the usSurveyFoot. For the acre based on
-- the international foot, see acre. While both acres are in use,
-- the difference between them is of little consequence for most
-- applications in which either is used. This is the only acre defined by
-- the UCUM.
--
-- See here for further information.
--
--
-- >>> 1 *~ usSurveyAcre
-- 4046.872609874252 m^2
--
--
--
-- 1 *~ usSurveyAcre === 43560 *~ usSurveyFoot ^ pos2
--
--
--
-- >>> 1 *~ usSurveyAcre :: Area Rational
-- 62726400000 % 15499969 m^2
--
usSurveyAcre :: Fractional a => Unit 'NonMetric DArea a
-- | One mean Julian year is a unit of measurement of time defined as
-- exactly 365.25 days of 86 400 seconds each.
--
-- See here for further information.
--
--
-- >>> 1 *~ year
-- 3.15576e7 s
--
--
--
-- >>> 1 *~ year :: Time Rational
-- 31557600 % 1 s
--
year :: Num a => Unit 'NonMetric DTime a
-- | One mean Julian century is one hundred mean Julian years.
--
--
-- >>> 1 *~ century
-- 3.15576e9 s
--
--
--
-- >>> 1 *~ century :: Time Rational
-- 3155760000 % 1 s
--
century :: Num a => Unit 'NonMetric DTime a
-- | The bar is exactly 100 000 pascal.
--
-- From Wikipedia:
--
-- It is about equal to the atmospheric pressure on Earth at sea level.
--
--
-- >>> 1 *~ bar
-- 100000.0 m^-1 kg s^-2
--
--
--
-- >>> 1 *~ bar :: Pressure Rational
-- 100000 % 1 m^-1 kg s^-2
--
bar :: Num a => Unit 'Metric DPressure a
-- | The "standard atmosphere".
--
-- From Wikipedia [3]:
--
-- The standard atmosphere (atm) is an established constant. It is
-- approximately equal to typical air pressure at earth mean sea level.
--
--
-- >>> 1 *~ atmosphere
-- 101325.0 m^-1 kg s^-2
--
--
--
-- >>> 1 *~ atmosphere :: Pressure Rational
-- 101325 % 1 m^-1 kg s^-2
--
atmosphere :: Num a => Unit 'NonMetric DPressure a
-- | The "technical atmosphere"
--
-- From Wikipedia:
--
-- A technical atmosphere (symbol: at) is a non-SI unit of pressure equal
-- to one kilogram-force per square centimeter.
--
--
-- >>> 1 *~ technicalAtmosphere
-- 98066.5 m^-1 kg s^-2
--
--
--
-- >>> 1 *~ technicalAtmosphere :: Pressure Rational
-- 196133 % 2 m^-1 kg s^-2
--
technicalAtmosphere :: Fractional a => Unit 'NonMetric DPressure a
-- | The conventional value for the pressure exerted by a 1 mm high column
-- of mercury.
--
-- Per Wikipedia [4], one mmHg (millimeter of mercury) is defined
-- as:
--
-- The pressure exerted at the base of a column of fluid exactly 1 mm
-- high, when the density of the fluid is exactly 13.5951 g/cm^3, at a
-- place where the acceleration of gravity is exactly 9.80665 m/s^2.
--
-- The chosen fluid density approximately corresponds to that of mercury
-- at 0 deg. Under most conditions, 1 mmHg is approximately equal to 1
-- torr.
--
--
-- >>> 1 *~ mmHg
-- 133.322 m^-1 kg s^-2
--
--
--
-- >>> 1 *~ mmHg :: Pressure Rational
-- 66661 % 500 m^-1 kg s^-2
--
mmHg :: Fractional a => Unit 'NonMetric DPressure a
-- | The conventional value for the pressure exerted by a 1 inch high
-- column of mercury.
--
-- Column inches of mercury are also used to measure pressure, especially
-- in meteorological or aeronautical contexts in the United States.
--
-- This is the value defined by UCUM. For the value defined by NIST, see
-- inHg_NIST.
--
--
-- >>> 1 *~ inHg
-- 3386.3788 m^-1 kg s^-2
--
--
--
-- >>> 1 *~ inHg :: Pressure Rational
-- 8465947 % 2500 m^-1 kg s^-2
--
inHg :: Fractional a => Unit 'NonMetric DPressure a
-- | The conventional value for the pressure exerted by a 1 inch high
-- column of mercury.
--
-- Column inches of mercury are also used to measure pressure, especially
-- in meteorological or aeronautical contexts in the United States.
--
-- This is the value defined by UCUM. For the value defined by NIST, see
-- inHg_NIST.
--
--
-- >>> 1 *~ inHg_UCUM
-- 3386.3788 m^-1 kg s^-2
--
--
--
-- >>> 1 *~ inHg_UCUM :: Pressure Rational
-- 8465947 % 2500 m^-1 kg s^-2
--
inHg_UCUM :: Fractional a => Unit 'NonMetric DPressure a
-- | The conventional value for the pressure exerted by a 1 inch high
-- column of mercury.
--
-- Column inches of mercury are also used to measure pressure, especially
-- in meteorological or aeronautical contexts in the United States.
--
-- This is the value defined by NIST. For the value defined by UCUM, see
-- inHg_UCUM.
--
--
-- >>> 1 *~ inHg_NIST
-- 3386.389 m^-1 kg s^-2
--
--
--
-- >>> 1 *~ inHg_NIST :: Pressure Rational
-- 3386389 % 1000 m^-1 kg s^-2
--
inHg_NIST :: Fractional a => Unit 'NonMetric DPressure a
-- | One torr (symbol: Torr) is defined as 1/760 atmosphere, which
-- is approximately equal to 1 mmHg.
--
-- See here for further information.
--
--
-- >>> 1 *~ torr
-- 133.32236842105263 m^-1 kg s^-2
--
--
--
-- >>> 1 *~ torr :: Pressure Rational
-- 20265 % 152 m^-1 kg s^-2
--
torr :: Fractional a => Unit 'NonMetric DPressure a
-- | The rad is a deprecated unit of AbsorbedDose, defined as 0.01
-- gray.
--
-- See here for further information.
--
--
-- >>> 1 *~ rad
-- 1.0e-2 m^2 s^-2
--
--
--
-- >>> 1 *~ rad :: AbsorbedDose Rational
-- 1 % 100 m^2 s^-2
--
rad :: Fractional a => Unit 'Metric DAbsorbedDose a
-- | One Stokes is a unit of KinematicViscosity equal to 1 cm^2
-- / s.
--
-- See here for further information.
--
--
-- >>> 1 *~ stokes
-- 1.0e-4 m^2 s^-1
--
--
--
-- >>> 1 *~ stokes :: KinematicViscosity Rational
-- 1 % 10000 m^2 s^-1
--
stokes :: Fractional a => Unit 'Metric DKinematicViscosity a
-- | One degree Fahrenheit is a unit of relative temperature equal to 5/9
-- kelvin.
--
-- Note that although the Fahrenheit scale is an absolute temperature
-- scale, this unit is a unit of difference within that scale and
-- measures relative temperature.
--
-- See here for further information.
--
--
-- >>> 1 *~ degreeFahrenheit
-- 0.5555555555555556 K
--
--
--
-- >>> 1 *~ degreeFahrenheit :: ThermodynamicTemperature Rational
-- 5 % 9 K
--
degreeFahrenheit :: Fractional a => Unit 'NonMetric DThermodynamicTemperature a
-- | One degree Rankine is a unit of relative temperature equal to 5/9
-- kelvin.
--
-- Note that although the Rankine scale is an absolute temperature scale,
-- this unit is a unit of difference within that scale and measures
-- relative temperature.
--
-- See here for further information.
--
--
-- >>> 1 *~ degreeRankine
-- 0.5555555555555556 K
--
--
--
-- >>> 1 *~ degreeRankine :: ThermodynamicTemperature Rational
-- 5 % 9 K
--
degreeRankine :: Fractional a => Unit 'NonMetric DThermodynamicTemperature a
-- | One imperial gallon is defined exactly in terms of the liter by
-- the Weights and Measures Act 1985.
--
-- See here for further information.
--
--
-- >>> 1 *~ imperialGallon
-- 4.54609e-3 m^3
--
--
--
-- >>> 1 *~ imperialGallon :: Volume Rational
-- 454609 % 100000000 m^3
--
imperialGallon :: Fractional a => Unit 'NonMetric DVolume a
-- | One imperial quart is one quarter of an imperialGallon.
--
-- See here for further information.
--
--
-- >>> 1 *~ imperialQuart
-- 1.1365225e-3 m^3
--
--
--
-- >>> 1 *~ imperialQuart :: Volume Rational
-- 454609 % 400000000 m^3
--
imperialQuart :: Fractional a => Unit 'NonMetric DVolume a
-- | One imperial pint is one half of an imperialQuart.
--
-- See here for further information.
--
--
-- >>> 1 *~ imperialPint
-- 5.6826125e-4 m^3
--
--
--
-- >>> 1 *~ imperialPint :: Volume Rational
-- 454609 % 800000000 m^3
--
imperialPint :: Fractional a => Unit 'NonMetric DVolume a
-- | One imperial cup is one half of an imperialPint.
--
-- This unit is not in common use and is does not appear in some sources
-- describing the imperial fluid volume units.
--
-- See here for further information.
--
--
-- >>> 1 *~ imperialCup
-- 2.84130625e-4 m^3
--
--
--
-- >>> 1 *~ imperialCup :: Volume Rational
-- 454609 % 1600000000 m^3
--
imperialCup :: Fractional a => Unit 'NonMetric DVolume a
-- | One imperial gill is one quarter of an imperialPint.
--
-- See here for further information.
--
--
-- >>> 1 *~ imperialGill
-- 1.420653125e-4 m^3
--
--
--
-- >>> 1 *~ imperialGill :: Volume Rational
-- 454609 % 3200000000 m^3
--
imperialGill :: Fractional a => Unit 'NonMetric DVolume a
-- | One imperial fluid ounce is one twentieth of an imperialPint.
--
-- See here for further information.
--
--
-- >>> 1 *~ imperialFluidOunce
-- 2.84130625e-5 m^3
--
--
--
-- >>> 1 *~ imperialFluidOunce :: Volume Rational
-- 454609 % 16000000000 m^3
--
imperialFluidOunce :: Fractional a => Unit 'NonMetric DVolume a
-- | One US liquid gallon is a volume of 231 cubic inches.
--
-- See here for further information.
--
--
-- >>> 1 *~ usGallon
-- 3.785411784e-3 m^3
--
--
--
-- >>> 1 *~ usGallon :: Volume Rational
-- 473176473 % 125000000000 m^3
--
usGallon :: Fractional a => Unit 'NonMetric DVolume a
-- | One US liquid quart is one quarter of a usGallon.
--
-- See here for further information.
--
--
-- >>> 1 *~ usQuart
-- 9.46352946e-4 m^3
--
--
--
-- >>> 1 *~ usQuart :: Volume Rational
-- 473176473 % 500000000000 m^3
--
usQuart :: Fractional a => Unit 'NonMetric DVolume a
-- | One US liquid pint is one half of a usQuart.
--
-- See here for further information.
--
--
-- >>> 1 *~ usPint
-- 4.73176473e-4 m^3
--
--
--
-- >>> 1 *~ usPint :: Volume Rational
-- 473176473 % 1000000000000 m^3
--
usPint :: Fractional a => Unit 'NonMetric DVolume a
-- | One US liquid cup is one half of a usPint.
--
-- See here for further information.
--
--
-- >>> 1 *~ usCup
-- 2.365882365e-4 m^3
--
--
--
-- >>> 1 *~ usCup :: Volume Rational
-- 473176473 % 2000000000000 m^3
--
usCup :: Fractional a => Unit 'NonMetric DVolume a
-- | One US liquid gill is one half of a usCup.
--
-- See here for further information.
--
--
-- >>> 1 *~ usGill
-- 1.1829411825e-4 m^3
--
--
--
-- >>> 1 *~ usGill :: Volume Rational
-- 473176473 % 4000000000000 m^3
--
usGill :: Fractional a => Unit 'NonMetric DVolume a
-- | One US fluid ounce is 1128 usGallon or 18 usCup.
--
-- See here for further information.
--
--
-- >>> 1 *~ usFluidOunce
-- 2.95735295625e-5 m^3
--
--
--
-- >>> 1 *~ usFluidOunce :: Volume Rational
-- 473176473 % 16000000000000 m^3
--
usFluidOunce :: Fractional a => Unit 'NonMetric DVolume a
-- | One Ångström is 1/10 nano meter.
--
-- See here for further information.
--
--
-- >>> 1 *~ angstrom
-- 1.0e-10 m
--
--
--
-- >>> 1 *~ angstrom :: Length Rational
-- 1 % 10000000000 m
--
angstrom :: Fractional a => Unit 'NonMetric DLength a
-- | One Gauss is 1/10000 tesla.
--
-- See here for further information.
--
--
-- >>> 1 *~ gauss
-- 1.0e-4 kg s^-2 A^-1
--
--
--
-- >>> 1 *~ gauss :: MagneticFluxDensity Rational
-- 1 % 10000 kg s^-2 A^-1
--
gauss :: Fractional a => Unit 'NonMetric DMagneticFluxDensity a
-- | Defines convenience functions for inspecting and manipulating
-- quantities with RealFloat floating-point representations.
--
-- The dimensionally-typed versions of functions from Patrick Perry's
-- ieee754 package copy that package's API as closely as
-- possible, by permission. In turn they are based on the tango
-- math library for the D language.
module Numeric.Units.Dimensional.Float
-- | True if the representation of the argument is too small to be
-- represented in normalized format.
isDenormalized :: RealFloat a => Quantity d a -> Bool
-- | True if the representation of the argument is an IEEE infinity
-- or negative infinity.
--
--
-- >>> isInfinite (_1 / _0)
-- True
--
--
--
-- >>> isInfinite (42 *~ micro farad)
-- False
--
isInfinite :: RealFloat a => Quantity d a -> Bool
-- | True if the representation of the argument is an IEEE
-- "not-a-number" (NaN) value.
--
--
-- >>> isNaN _3
-- False
--
--
--
-- >>> isNaN (_1 / _0)
-- False
--
--
--
-- >>> isNaN (asin _4)
-- True
--
isNaN :: RealFloat a => Quantity d a -> Bool
-- | True if the representation of the argument is an IEEE negative
-- zero.
--
--
-- >>> isNegativeZero _0
-- False
--
--
--
-- >>> isNegativeZero $ (-1e-200 *~ one) * (1e-200 *~ one)
-- True
--
isNegativeZero :: RealFloat a => Quantity d a -> Bool
-- | True if the representation of the argument is a number and is
-- not infinite.
--
--
-- >>> isFiniteNumber (_1 / _0)
-- False
--
--
--
-- >>> isFiniteNumber (_0 / _0)
-- False
--
--
--
-- >>> isFiniteNumber (_3 / _2)
-- True
--
isFiniteNumber :: RealFloat a => Quantity d a -> Bool
-- | Multiplies a floating-point quantity by an integer power of the radix
-- of the representation type.
--
-- Use floatRadix to determine the radix.
--
--
-- >>> let x = 3 *~ meter
--
-- >>> scaleFloat 3 x
-- 24.0 m
--
scaleFloat :: RealFloat a => Int -> Quantity d a -> Quantity d a
-- | An infinite floating-point quantity.
infinity :: IEEE a => Quantity d a
-- | The smallest representable positive quantity whose representation is
-- normalized.
minNormal :: IEEE a => Quantity d a
-- | The largest representable finite floating-point quantity.
maxFinite :: IEEE a => Quantity d a
-- | The smallest positive value x such that _1 + x is
-- representable.
epsilon :: IEEE a => Dimensionless a
-- | Default NaN quantity.
nan :: IEEE a => Quantity d a
-- | Return the next smallest representable floating-point quantity
-- (Infinity and NaN are unchanged).
predIEEE :: IEEE a => Quantity d a -> Quantity d a
-- | Return the next largest representable floating-point quantity
-- (Infinity and NaN are unchanged).
succIEEE :: IEEE a => Quantity d a -> Quantity d a
-- | Given two floating-point quantities with the same sign, return the
-- quantity whose representation is halfway between their representations
-- on the IEEE number line. If the signs of the values differ or either
-- is NaN, the value is undefined.
bisectIEEE :: IEEE a => Quantity d a -> Quantity d a -> Quantity d a
-- | copySign x y returns the quantity x with its sign
-- changed to match that of y.
copySign :: IEEE a => Quantity d a -> Quantity d a -> Quantity d a
-- | Quiet NaN quantity with a positive integer payload. Payload
-- must be less than maxNaNPayload of the representation type.
--
-- Beware that while some platforms allow using 0 as a payload, this
-- behavior is not portable.
nanWithPayload :: IEEE a => Word64 -> Quantity d a
-- | The payload stored in a NaN quantity. Undefined if the
-- argument is not NaN.
nanPayload :: IEEE a => Quantity d a -> Word64
-- | Maximum NaN payload for type a.
maxNaNPayload :: IEEE a => a -> Word64
-- | Return True if two floating-point quantities are exactly
-- (bitwise) equal.
identicalIEEE :: IEEE a => Quantity d a -> Quantity d a -> Bool
-- | Return the minimum of two quantities; if one value is NaN,
-- return the other. Prefer the first if both values are NaN.
minNum :: RealFloat a => Quantity d a -> Quantity d a -> Quantity d a
-- | Return the maximum of two quantities; if one value is NaN,
-- return the other. Prefer the first if both values are NaN.
maxNum :: RealFloat a => Quantity d a -> Quantity d a -> Quantity d a
-- | Return the minimum of two quantities; if one value is NaN,
-- return it. Prefer the first if both values are NaN.
minNaN :: RealFloat a => Quantity d a -> Quantity d a -> Quantity d a
-- | Return the maximum of two quantities; if one value is NaN,
-- return it. Prefer the first if both values are NaN.
maxNaN :: RealFloat a => Quantity d a -> Quantity d a -> Quantity d a
-- | Defines types for manipulation of quantities with fixed point
-- representations.
module Numeric.Units.Dimensional.FixedPoint
-- | A dimensional value, either a Quantity or a Unit,
-- parameterized by its Dimension and representation.
data family Dimensional v :: Dimension -> Type -> Type
-- | A unit of measurement.
type Unit (m :: Metricality) = Dimensional ( 'DUnit m)
-- | A dimensional quantity.
type Quantity = SQuantity One
-- | A dimensional quantity, stored as an ExactPi' multiple of its
-- value in its dimension's SI coherent unit.
--
-- The name is an abbreviation for scaled quantity.
type SQuantity s = Dimensional ( 'DQuantity s)
-- | Encodes whether a unit is a metric unit, that is, whether it can be
-- combined with a metric prefix to form a related unit.
data Metricality
-- | Capable of receiving a metric prefix.
Metric :: Metricality
-- | Incapable of receiving a metric prefix.
NonMetric :: Metricality
-- | Represents a physical dimension in the basis of the 7 SI base
-- dimensions, where the respective dimensions are represented by type
-- variables using the following convention:
--
--
-- - l: Length
-- - m: Mass
-- - t: Time
-- - i: Electric current
-- - th: Thermodynamic temperature
-- - n: Amount of substance
-- - j: Luminous intensity
--
--
-- For the equivalent term-level representation, see Dimension'
data Dimension
Dim :: TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> TypeInt -> Dimension
-- | Multiplication of dimensions corresponds to adding of the base
-- dimensions' exponents.
type family (a :: Dimension) * (b :: Dimension)
infixl 7 *
-- | Division of dimensions corresponds to subtraction of the base
-- dimensions' exponents.
type family (a :: Dimension) / (d :: Dimension)
infixl 7 /
-- | Powers of dimensions corresponds to multiplication of the base
-- dimensions' exponents by the exponent.
--
-- We limit ourselves to integer powers of Dimensionals as fractional
-- powers make little physical sense.
type family (d :: Dimension) ^ (x :: TypeInt)
infixr 8 ^
-- | Roots of dimensions corresponds to division of the base dimensions'
-- exponents by the order of the root.
type family NRoot (d :: Dimension) (x :: TypeInt)
-- | The reciprocal of a dimension is defined as the result of dividing
-- DOne by it, or of negating each of the base dimensions'
-- exponents.
type Recip (d :: Dimension) = DOne / d
-- | A physical dimension, encoded as 7 integers, representing a
-- factorization of the dimension into the 7 SI base dimensions. By
-- convention they are stored in the same order as in the
-- Dimension data kind.
data Dimension'
Dim' :: !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> !Int -> Dimension'
-- | Dimensional values inhabit this class, which allows access to a
-- term-level representation of their dimension.
class HasDynamicDimension a => HasDimension a
-- | Obtains a term-level representation of a value's dimension.
dimension :: HasDimension a => a -> Dimension'
-- | A KnownDimension is one for which we can construct a term-level
-- representation. Each validly constructed type of kind Dimension
-- has a KnownDimension instance.
--
-- While KnownDimension is a constraint synonym, the presence of
-- KnownDimension d in a context allows use of
-- dimension :: Proxy d -> Dimension'.
type KnownDimension (d :: Dimension) = HasDimension (Proxy d)
-- | Forms a possibly scaled SQuantity by multipliying a number and
-- a unit.
(*~) :: forall s m d a b. (RealFrac a, Integral b, MinCtxt s a) => a -> Unit m d a -> SQuantity s d b
infixl 7 *~
-- | Divides a possibly scaled SQuantity by a Unit of the
-- same physical dimension, obtaining the numerical value of the quantity
-- expressed in that unit.
(/~) :: forall s m d a b. (Real a, Fractional b, MinCtxt s b) => SQuantity s d a -> Unit m d b -> b
infixl 7 /~
-- | Multiplies two Quantitys or two Units.
--
-- The intimidating type signature captures the similarity between these
-- operations and ensures that composite Units are
-- NonMetric.
(*) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 * v2), Num a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 * v2) (d1 * d2) a
infixl 7 *
-- | Divides one Quantity by another or one Unit by another.
--
-- The intimidating type signature captures the similarity between these
-- operations and ensures that composite Units are
-- NotPrefixable.
(/) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 / v2), Fractional a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 / v2) (d1 / d2) a
infixl 7 /
-- | Adds two possibly scaled SQuantitys, preserving any scale
-- factor.
--
-- Use in conjunction with changeRepRound to combine quantities
-- with differing scale factors.
(+) :: Num a => SQuantity s d a -> SQuantity s d a -> SQuantity s d a
infixl 6 +
-- | Subtracts one possibly scaled SQuantity from another,
-- preserving any scale factor.
--
-- Use in conjunction with changeRepRound to combine quantities
-- with differing scale factors.
(-) :: Num a => SQuantity s d a -> SQuantity s d a -> SQuantity s d a
infixl 6 -
-- | Negates the value of a possibly scaled SQuantity, preserving
-- any scale factor.
negate :: Num a => SQuantity s d a -> SQuantity s d a
-- | Takes the absolute value of a possibly scaled SQuantity,
-- preserving any scale factor.
abs :: Num a => SQuantity s d a -> SQuantity s d a
expD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
logD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
sinD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
cosD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
tanD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
asinD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
acosD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
atanD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
sinhD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
coshD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
tanhD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
asinhD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
acoshD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
atanhD :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne b
-- | The standard two argument arctangent function. Since it interprets its
-- two arguments in comparison with one another, the input may have any
-- dimension.
atan2D :: (Integral a, Integral b, MinCtxt s1 Double, MinCtxt s2 Double, MinCtxt s3 Double) => SQuantity s1 DOne a -> SQuantity s2 DOne a -> SQuantity s3 DOne b
expVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
logVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
sinVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
cosVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
tanVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
asinVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
acosVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
atanVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
sinhVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
coshVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
tanhVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
asinhVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
acoshVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
atanhVia :: (Integral a, RealFrac b, Floating b, Integral c, MinCtxt s1 b, MinCtxt s2 b) => Proxy b -> SQuantity s1 DOne a -> SQuantity s2 DOne c
-- | The standard two argument arctangent function. Since it interprets its
-- two arguments in comparison with one another, the input may have any
-- dimension.
atan2Via :: forall s1 s2 s3 a b c d. (Integral a, RealFloat b, Integral c, MinCtxt s1 b, MinCtxt s2 b, MinCtxt s3 b, KnownDimension d) => Proxy b -> SQuantity s1 d a -> SQuantity s2 d a -> SQuantity s3 DOne c
-- | Applies *~ to all values in a functor.
(*~~) :: (Functor f, RealFrac a, Integral b, MinCtxt s a) => f a -> Unit m d a -> f (SQuantity s d b)
infixl 7 *~~
-- | Applies /~ to all values in a functor.
(/~~) :: (Functor f, Real a, Fractional b, MinCtxt s b) => f (SQuantity s d a) -> Unit m d b -> f b
infixl 7 /~~
-- | The sum of all elements in a list.
sum :: (Num a, Foldable f) => f (SQuantity s d a) -> SQuantity s d a
-- | The arithmetic mean of all elements in a list.
mean :: (Fractional a, Foldable f) => f (SQuantity s d a) -> SQuantity s d a
-- | Rescales a fixed point quantity, accomodating changes both in its
-- scale factor and its representation type.
--
-- Note that this uses an arbitrary precision representation of
-- pi, which may be quite slow.
rescale :: forall a b d s1 s2. (Integral a, Integral b, KnownExactPi s1, KnownExactPi s2) => SQuantity s1 d a -> SQuantity s2 d b
-- | Rescales a fixed point quantity, accomodating changes both in its
-- scale factor and its representation type.
--
-- Expected to outperform rescale when a FiniteBits context
-- is available for the source and destination representation types.
rescaleFinite :: (Integral a, FiniteBits a, Integral b, FiniteBits b, KnownExactPi s1, KnownExactPi s2) => SQuantity s1 d a -> SQuantity s2 d b
-- | Approximately rescales a fixed point quantity, accomodating changes
-- both in its scale factor and its representation type.
--
-- Uses approximate arithmetic by way of an intermediate Double
-- representation.
rescaleD :: (Integral a, Integral b, KnownExactPi s1, KnownExactPi s2) => SQuantity s1 d a -> SQuantity s2 d b
-- | Approximately rescales a fixed point quantity, accomodating changes
-- both in its scale factor and its representation type.
--
-- Uses approximate arithmetic by way of an intermediate Floating
-- type, to which a proxy must be supplied.
rescaleVia :: forall a b c d s1 s2. (Integral a, RealFrac b, Floating b, Integral c, KnownExactPi s1, KnownExactPi s2) => Proxy b -> SQuantity s1 d a -> SQuantity s2 d c
-- | A KnownVariant is one whose term-level Dimensional values we
-- can represent with an associated data family instance and manipulate
-- with certain functions, not all of which are exported from the
-- package.
--
-- Each validly constructed type of kind Variant has a
-- KnownVariant instance.
class KnownVariant (v :: Variant)
-- | Maps over the underlying representation of a dimensional value. The
-- caller is responsible for ensuring that the supplied function respects
-- the dimensional abstraction. This means that the function must
-- preserve numerical values, or linearly scale them while preserving the
-- origin.
dmap :: KnownVariant v => (a1 -> a2) -> Dimensional v d a1 -> Dimensional v d a2
-- | Convenient conversion between numerical types while retaining
-- dimensional information.
changeRep :: forall v1 v2 d a b. (KnownVariant v1, KnownVariant v2, CompatibleVariants v1 v2, MinCtxt (ScaleFactor v1 / ScaleFactor v2) b, Real a, Fractional b) => Dimensional v1 d a -> Dimensional v2 d b
-- | Convenient conversion to types with Integral representations
-- using round.
changeRepRound :: forall v1 v2 d a b. (KnownVariant v1, KnownVariant v2, CompatibleVariants v1 v2, MinCtxt (ScaleFactor v1 / ScaleFactor v2) a, RealFrac a, Integral b) => Dimensional v1 d a -> Dimensional v2 d b
-- | Convenient conversion from exactly represented values while retaining
-- dimensional information.
changeRepApproximate :: (KnownVariant v, Floating b) => Dimensional v d ExactPi -> Dimensional v d b
-- | The type-level dimension of dimensionless values.
type DOne = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
type DLength = 'Dim 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero
type DMass = 'Dim 'Zero 'Pos1 'Zero 'Zero 'Zero 'Zero 'Zero
type DTime = 'Dim 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero 'Zero
type DElectricCurrent = 'Dim 'Zero 'Zero 'Zero 'Pos1 'Zero 'Zero 'Zero
type DThermodynamicTemperature = 'Dim 'Zero 'Zero 'Zero 'Zero 'Pos1 'Zero 'Zero
type DAmountOfSubstance = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1 'Zero
type DLuminousIntensity = 'Dim 'Zero 'Zero 'Zero 'Zero 'Zero 'Zero 'Pos1
type Dimensionless = Quantity DOne
type Length = Quantity DLength
type Mass = Quantity DMass
type Time = Quantity DTime
type ElectricCurrent = Quantity DElectricCurrent
type ThermodynamicTemperature = Quantity DThermodynamicTemperature
type AmountOfSubstance = Quantity DAmountOfSubstance
type LuminousIntensity = Quantity DLuminousIntensity
-- | The constant for zero is polymorphic, allowing it to express zero
-- Length or Capacitance or Velocity etc, in
-- addition to the Dimensionless value zero.
_0 :: Num a => SQuantity s d a
-- | The least positive representable value in a given fixed-point scaled
-- quantity type.
epsilon :: Integral a => SQuantity s d a
_1 :: (Integral a, KnownExactPi s) => SQuantity s DOne a
_2 :: (Integral a, KnownExactPi s) => SQuantity s DOne a
_3 :: (Integral a, KnownExactPi s) => SQuantity s DOne a
_4 :: (Integral a, KnownExactPi s) => SQuantity s DOne a
_5 :: (Integral a, KnownExactPi s) => SQuantity s DOne a
_6 :: (Integral a, KnownExactPi s) => SQuantity s DOne a
_7 :: (Integral a, KnownExactPi s) => SQuantity s DOne a
_8 :: (Integral a, KnownExactPi s) => SQuantity s DOne a
_9 :: (Integral a, KnownExactPi s) => SQuantity s DOne a
pi :: (Integral a, KnownExactPi s) => SQuantity s DOne a
-- | Twice pi.
--
-- For background on tau see
-- http://tauday.com/tau-manifesto (but also feel free to review
-- http://www.thepimanifesto.com).
tau :: (Integral a, KnownExactPi s) => SQuantity s DOne a
-- | A polymorphic Unit which can be used in place of the coherent
-- SI base unit of any dimension. This allows polymorphic quantity
-- creation and destruction without exposing the Dimensional
-- constructor.
siUnit :: forall d a. (KnownDimension d, Num a) => Unit 'NonMetric d a
-- | The unit one has dimension DOne and is the base unit of
-- dimensionless values.
--
-- As detailed in 7.10 "Values of quantities expressed simply as numbers:
-- the unit one, symbol 1" of [1] the unit one generally does not
-- appear in expressions. However, for us it is necessary to use
-- one as we would any other unit to perform the "boxing" of
-- dimensionless values.
one :: Num a => Unit 'NonMetric DOne a
-- | Forms a new atomic Unit by specifying its UnitName and
-- its definition as a multiple of another Unit.
--
-- Use this variant when the scale factor of the resulting unit is
-- irrational or Approximate. See mkUnitQ for when it is
-- rational and mkUnitZ for when it is an integer.
--
-- Note that supplying zero as a definining quantity is invalid, as the
-- library relies upon units forming a group under multiplication.
--
-- Supplying negative defining quantities is allowed and handled
-- gracefully, but is discouraged on the grounds that it may be
-- unexpected by other readers.
mkUnitR :: Floating a => UnitName m -> ExactPi -> Unit m1 d a -> Unit m d a
-- | Forms a new atomic Unit by specifying its UnitName and
-- its definition as a multiple of another Unit.
--
-- Use this variant when the scale factor of the resulting unit is
-- rational. See mkUnitZ for when it is an integer and
-- mkUnitR for the general case.
--
-- For more information see mkUnitR.
mkUnitQ :: Fractional a => UnitName m -> Rational -> Unit m1 d a -> Unit m d a
-- | Forms a new atomic Unit by specifying its UnitName and
-- its definition as a multiple of another Unit.
--
-- Use this variant when the scale factor of the resulting unit is an
-- integer. See mkUnitQ for when it is rational and mkUnitR
-- for the general case.
--
-- For more information see mkUnitR.
mkUnitZ :: Num a => UnitName m -> Integer -> Unit m1 d a -> Unit m d a
-- | Extracts the UnitName of a Unit.
name :: Unit m d a -> UnitName m
-- | Extracts the exact value of a Unit, expressed in terms of the
-- SI coherent derived unit (see siUnit) of the same
-- Dimension.
--
-- Note that the actual value may in some cases be approximate, for
-- example if the unit is defined by experiment.
exactValue :: Unit m d a -> ExactPi
-- | Discards potentially unwanted type level information about a
-- Unit.
weaken :: Unit m d a -> Unit 'NonMetric d a
-- | Attempts to convert a Unit which may or may not be
-- Metric to one which is certainly Metric.
strengthen :: Unit m d a -> Maybe (Unit 'Metric d a)
-- | Forms the exact version of a Unit.
exactify :: Unit m d a -> Unit m d ExactPi
-- | A dimensionless number with n fractional bits, using a
-- representation of type a.
type Q n a = SQuantity (QScale n) DOne a
-- | A binary scale factor.
type QScale n = (One / (ExactNatural (2 ^ n)))
-- | A single-turn angle represented as a signed 8-bit integer.
type Angle8 = SQuantity (Pi * (QScale 7)) DPlaneAngle Int8
-- | A single-turn angle represented as a signed 16-bit integer.
type Angle16 = SQuantity (Pi * (QScale 15)) DPlaneAngle Int16
-- | A single-turn angle represented as a signed 32-bit integer.
type Angle32 = SQuantity (Pi * (QScale 31)) DPlaneAngle Int32
-- | Provides a Functor instance for Dimensional.
--
-- Note that this instance is dubious, because it allows you to break the
-- dimensional abstraction. See dmap for more information.
--
-- Note that, while this instance overlaps with that given for
-- Dimensionless, it is confluent with that instance.
--
-- Note that this is an orphan instance.
module Numeric.Units.Dimensional.Functor
instance Numeric.Units.Dimensional.Internal.KnownVariant v => GHC.Base.Functor (Numeric.Units.Dimensional.Internal.Dimensional v d)
-- | Defines types for manipulation of units and quantities without phantom
-- types for their dimensions.
module Numeric.Units.Dimensional.Dynamic
-- | A Quantity whose Dimension is only known dynamically.
data AnyQuantity a
-- | Possibly a Quantity whose Dimension is only known
-- dynamically.
--
-- By modeling the absence of a value, this type differs from
-- AnyQuantity in that it may not be a Quantity of any
-- Dimension whatsoever, but in exchange it gains instances for
-- the common numeric classes. It's therefore useful for manipulating,
-- and not merely storing, quantities of unknown dimension.
--
-- This type also contains a polydimensionalZero, representing
-- zero value of any dimension.
--
-- Note that the Eq instance for DynQuantity equates all
-- representations of an invalid value, and also does not equate
-- polydimensional zero with zero of any specific dimension.
data DynQuantity a
-- | The class of types that can be used to model Quantitys that are
-- certain to have a value with some dimension.
class Demotable (q :: Type -> Type)
-- | The class of types that can be used to model Quantitys whose
-- Dimensions are only known dynamically.
class Promotable (q :: Type -> Type)
-- | Dimensional values, or those that are only possibly dimensional,
-- inhabit this class, which allows access to a term-level representation
-- of their dimension.
class HasDynamicDimension a
-- | Gets the 'DynamicDimension of a dynamic dimensional value, which may
-- be NoDimension if it does not represent a dimensional value of
-- any Dimension.
--
-- A default implementation is available for types that are also in the
-- HasDimension typeclass.
dynamicDimension :: HasDynamicDimension a => a -> DynamicDimension
-- | Gets the 'DynamicDimension of a dynamic dimensional value, which may
-- be NoDimension if it does not represent a dimensional value of
-- any Dimension.
--
-- A default implementation is available for types that are also in the
-- HasDimension typeclass.
dynamicDimension :: (HasDynamicDimension a, HasDimension a) => a -> DynamicDimension
-- | The dimension of a dynamic value, which may not have any dimension at
-- all.
data DynamicDimension
-- | The value has no valid dimension.
NoDimension :: DynamicDimension
-- | The value has the given dimension.
SomeDimension :: Dimension' -> DynamicDimension
-- | The value may be interpreted as having any dimension.
AnyDimension :: DynamicDimension
-- | Converts a dynamic quantity such as an AnyQuantity or a
-- DynQuantity into a Quantity, or to Nothing if the
-- dynamic quantity cannot be represented in the narrower result type.
promoteQuantity :: forall a d q. (Promotable q, KnownDimension d) => q a -> Maybe (Quantity d a)
-- | Forgets information about a Quantity or AnyQuantity,
-- yielding an AnyQuantity or a DynQuantity.
demoteQuantity :: (Demotable q, Promotable d) => q a -> d a
-- | Forms a dynamic quantity by multipliying a number and a dynamic unit.
(*~) :: (Floating a, Promotable q) => a -> AnyUnit -> q a
-- | Divides a dynamic quantity by a dynamic unit, obtaining the numerical
-- value of the quantity expressed in that unit if they are of the same
-- physical dimension, or Nothing otherwise.
(/~) :: (Floating a, Promotable q) => q a -> AnyUnit -> Maybe a
-- | A DynQuantity which does not correspond to a value of any
-- dimension.
invalidQuantity :: DynQuantity a
-- | A DynQuantity which corresponds to zero value of any dimension.
--
-- When combined through arithmetic with other DynQuantitys,
-- inference is performed. For example, adding a length to
-- polydimensional zero produces that length. Adding two polydimensional
-- zeros produces another. Taking the sine of a polydimensional zero
-- interprets it as a dimensionless zero and produces a dimensionless
-- result.
--
-- Note that division by polydimensionalZero produces a
-- polydimensional result, which may be an error or some representation
-- of infinity, as determined by the underlying arithmetic type. This
-- behavior was chosen for consistency with the behavior of division by
-- zero DynQuantitys of a specific dimension.
polydimensionalZero :: Num a => DynQuantity a
-- | A Unit whose Dimension is only known dynamically.
data AnyUnit
-- | Converts a Unit of statically known Dimension into an
-- AnyUnit.
demoteUnit :: forall m d a. KnownDimension d => Unit m d a -> AnyUnit
-- | Converts an AnyUnit into a Unit of statically known
-- Dimension, or Nothing if the dimension does not match.
--
-- The result is represented in ExactPi, conversion to other
-- representations is possible using changeRepApproximate.
--
-- The result is always tagged as NonMetric, conversion to a
-- Metric unit can be attempted using strengthen.
promoteUnit :: forall d. KnownDimension d => AnyUnit -> Maybe (Unit 'NonMetric d ExactPi)
-- | Converts a Unit of statically known Dimension into an
-- AnyUnit.
--
-- This is the same as the more general demoteUnit but is useful
-- in certain circumstances to avoid needlessly introducing an ambiguous
-- type variable.
demoteUnit' :: KnownDimension d => Unit m d ExactPi -> AnyUnit
-- | The dynamic SI coherent unit of a given dimension.
siUnit :: Dimension' -> AnyUnit
anyUnitName :: AnyUnit -> UnitName 'NonMetric
-- | Forms the product of two dynamic units.
(*) :: AnyUnit -> AnyUnit -> AnyUnit
-- | Forms the quotient of two dynamic units.
(/) :: AnyUnit -> AnyUnit -> AnyUnit
-- | Raises a dynamic unit to an integer power.
(^) :: Integral a => AnyUnit -> a -> AnyUnit
-- | Forms the reciprocal of a dynamic unit.
recip :: AnyUnit -> AnyUnit
-- | Applies a prefix to a dynamic unit. Returns Nothing if the
-- Unit was NonMetric and thus could not accept a prefix.
applyPrefix :: Prefix -> AnyUnit -> Maybe AnyUnit
instance GHC.Generics.Generic Numeric.Units.Dimensional.Dynamic.AnyUnit
instance GHC.Generics.Generic1 Numeric.Units.Dimensional.Dynamic.DynQuantity
instance GHC.Generics.Generic (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance Data.Data.Data a => Data.Data.Data (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance GHC.Generics.Generic1 Numeric.Units.Dimensional.Dynamic.AnyQuantity
instance GHC.Generics.Generic (Numeric.Units.Dimensional.Dynamic.AnyQuantity a)
instance Data.Data.Data a => Data.Data.Data (Numeric.Units.Dimensional.Dynamic.AnyQuantity a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Numeric.Units.Dimensional.Dynamic.AnyQuantity a)
instance GHC.Show.Show Numeric.Units.Dimensional.Dynamic.AnyUnit
instance Numeric.Units.Dimensional.Dimensions.TermLevel.HasDynamicDimension Numeric.Units.Dimensional.Dynamic.AnyUnit
instance Numeric.Units.Dimensional.Dimensions.TermLevel.HasDimension Numeric.Units.Dimensional.Dynamic.AnyUnit
instance Numeric.Units.Dimensional.UnitNames.InterchangeNames.HasInterchangeName Numeric.Units.Dimensional.Dynamic.AnyUnit
instance GHC.Base.Semigroup Numeric.Units.Dimensional.Dynamic.AnyUnit
instance GHC.Base.Monoid Numeric.Units.Dimensional.Dynamic.AnyUnit
instance Numeric.Units.Dimensional.Dynamic.Promotable Numeric.Units.Dimensional.Dynamic.AnyQuantity
instance Numeric.Units.Dimensional.Dynamic.Promotable Numeric.Units.Dimensional.Dynamic.DynQuantity
instance GHC.Classes.Eq a => GHC.Classes.Eq (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance GHC.Show.Show a => GHC.Show.Show (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance Numeric.Units.Dimensional.Dimensions.TermLevel.HasDynamicDimension (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance GHC.Num.Num a => GHC.Num.Num (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance GHC.Real.Fractional a => GHC.Real.Fractional (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance GHC.Float.Floating a => GHC.Float.Floating (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance GHC.Num.Num a => GHC.Base.Semigroup (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance GHC.Num.Num a => GHC.Base.Monoid (Numeric.Units.Dimensional.Dynamic.DynQuantity a)
instance Numeric.Units.Dimensional.Dimensions.TypeLevel.KnownDimension d => Numeric.Units.Dimensional.Dynamic.Demotable (Numeric.Units.Dimensional.Internal.Quantity d)
instance Numeric.Units.Dimensional.Dynamic.Demotable Numeric.Units.Dimensional.Dynamic.AnyQuantity
instance GHC.Show.Show a => GHC.Show.Show (Numeric.Units.Dimensional.Dynamic.AnyQuantity a)
instance Numeric.Units.Dimensional.Dimensions.TermLevel.HasDynamicDimension (Numeric.Units.Dimensional.Dynamic.AnyQuantity a)
instance Numeric.Units.Dimensional.Dimensions.TermLevel.HasDimension (Numeric.Units.Dimensional.Dynamic.AnyQuantity a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Numeric.Units.Dimensional.Dynamic.AnyQuantity a)
instance GHC.Num.Num a => GHC.Base.Semigroup (Numeric.Units.Dimensional.Dynamic.AnyQuantity a)
instance GHC.Num.Num a => GHC.Base.Monoid (Numeric.Units.Dimensional.Dynamic.AnyQuantity a)