units-list
A simple library oriented around providing easy and usable string-based units while still remaining extensible. Tries to be both simpler than the units package, and be more extensible than the dimensional package.
Example
worldPopulationInBillions = dimension "billion*people" 8.142
worldPopulation = fmap floor $ applyPos "billion" (*1e9) worldPopulationInBillions
daysInYear = dimension "days/years" 365
caloriePerDay = dimension "calories/days/people" 2000
caloriesPerYear = caloriePerDay !* daysInYear !* worldPopulation
> 5943659999270000 calories / years
Since everything has units, I chose Symbols to be the core dimensional type of this project.
Debug tip:
When getting an error like Could not match kind symbol with * in a polymorphic function like this assertSame :: Dimension n a -> Dimension n a -> Dimension n a, Try changing the type signature to assertSame :: forall k a (n :: [(k,Int')]). Dimension n a -> Dimension n a -> Dimension n a. This happened once, please report any other problems/solutions to ashok.kimmel@gmail.com, so I can add them to this README.
Implementation
A dimension is difined quite simply as:
type Dimension :: forall k. [(k,Int')] -> Type -> Type
newtype Dimension a b = MkDimension b
deriving stock (Eq,Ord,Functor)
There are two invariants: The Int' should never be zero, and the Dimension should be ordered. This means that there is only 1 valid type that satisfies the invariants per dimension.
k represents the kind used to index dimensions. One example is Symbols, another would be a Metric kind, another might be CaseInsenstiveStrings,etc.
Int' represents the datatype used in this repository to represent Integers.
data Int' = Pos Nat | Neg Nat
Neg n represents -(n+1).
If you really need to create a dimension, you are encouraged to use ToNegInt and ToPosInt from Dimensions.TypeLevelInt, as implementation may change.
Creation
There are 8 ways to create dimensions
dim :: b -> forall a -> Dimension (ValidParse @Symbol a) b
dims ::Functor f => f b -> forall a -> f (Dimension (ValidParse @Symbol a) b)
dimension :: forall a -> forall b. b -> Dimension (ValidParse @Symbol a) b
dimensions :: forall a -> forall f b. Functor f => f b -> f (Dimension (ValidParse @Symbol a) b)
dimensionPoly :: forall a -> forall b. b -> Dimension (ValidParse a) b
dimensionsPoly :: forall a -> forall f b. Functor f => f b -> f (Dimension (ValidParse a) b)
dimNP :: forall a -> forall b. b -> Dimension (Format a) b
dimNPs :: forall a -> forall f b. Functor f => f b -> f (Dimension (Format a) b)
dim,dims,dimension and dimensions are the most common ones. They only work on symbols however, so if you want to use a different base, they would fail. dim and dims are like their longer counterparts just with the arguments flipped. dimensions is just dimension but lifted over a functor. Inspired by the ReadMe for the Dimensional library. The polymorphic versions suffer from type ambiguity as the kind of the resulting Dimension is unknown. It is reccomended that you add a wrapper if you plan to use a seperate dimension. dimNP is if you don't want to use the built in parser and want to manually specify the dimensions.
Note on parser
The parser is very simple:
it checks for *,and /, splits them into sections,
checks for ^ in the subsections and creates the dimensions accordingly.
As a result, all of the following are valid
:k! Parse "*******" -> ['("", TI.Pos 1), '("", TI.Pos 1), '("", TI.Pos 1),'("", TI.Pos 1), '("", TI.Pos 1), '("", TI.Pos 1), '("", TI.Pos 1),'("", TI.Pos 1)]
:k! Parse "*/*/***^201" -> ['("", TI.Pos 1), '("", TI.Pos 1), '("", TI.Neg 0),'("", TI.Pos 1), '("", TI.Neg 0), '("", TI.Pos 1), '("", TI.Pos 1),'("", TI.Pos 201)]
:k! Parse "second/(meter*kilogram)" -> [("kilogram),Pos 1),("(meter",Neg 0),("second",Pos 1)]
dimension ensures that the invariants are upheld, but still allows annoyances. Check the types!
Given the annoyance inherent to type level coding, this may not change.
Note on printer
The printer will not print the actual type as it is stored. e.g.
dimension "second/meter" 2 -> 2 second/meter
Despite the fact that the ordering of meter is actually before second, the printer tries to print the positive dimensions first. A useful note for debugging type errors.
Multiplying,dision,etc.
!+,!-,!*,!/,divD can be used for multiplying and dividing dimensions.
They are mostly just specialized forms of liftD2, which works on two of the same and combineD2, which multiplies the two types.
rt,rtn,!^,!^^ all allow for exponentiation and roots. They need type level arguments. rt,!^^ work on Int's, while rt and !^ work on Nats.
The type families !*,!/,RT,RTN all work at the type level and can be used with the NoParse functions to avoid parsing.
transform :: forall s t x a. TT.ToInt (LookupD0 s x) => (a -> a, a -> a) -> Dimension x a -> Dimension (Replace s t x) a
This is used to completely switch a type parameter, whether it shows up in the positive or negative. Common usage would be with prefixes, kilogram to gram,etc.
transformPos :: forall s t x a. (TL.KnownNat (TI.ToNatural (LookupD0 s x))) => (a -> a) -> Dimension x a -> Dimension (Replace s t x) a
Like transform but only needs the switch in the positive direction. However, it requries that the dimension only occurs a positive number of times. Useful when you know that your unit occurs in the positive place.
apply :: forall x a. forall s -> TT.ToInt (LookupD0 s x) => (a -> a, a -> a) -> Dimension x a -> Dimension (Delete s x) a
Like transform, but consumes the dimension. Can be useful with things like billion, or mole.
applyPos :: forall x a. forall s -> (TL.KnownNat (TI.ToNatural (LookupD0 s x))) => (a -> a) -> Dimension x a -> Dimension (Delete s x) a
apply but only needs 1 function. I used this to eliminate the billion in the example.
same :: forall s t x. (forall a. Dimension x a -> Dimension (Replace s t x) a)
Assert that two things are the same, and replace one with another. Example: g gram grams all symbolize the same thing, but some places might use different ones.
mkisos :: forall y x a. Dimension x a -> Dimension (Isos y x) a
the same as repeated usage of same, uses a type level list.
inject :: (n -> n) -> forall a -> Dimension b n -> Dimension (a !* b) n
Allows you to add a dimension to a type, using a function. Example, adding a mole,
replace :: forall a -> Dimension b n -> Dimension (a !* b) n
replace = inject id
Replace can be used to replace simple things, even if you don't want to do it multiple times.
Example: replace (Parse "billion/thousand^3")
undimension, requires all tags be eliminated already.
getDimension allow you to specify the dimension, and getDimensionNP allows you to manually parse things.
Extending:
To extend this to a non-symbol base kind, define a ToDimension(for parsing), FromDimension (for printing), and Compare (for preserving invariants). Then you should probably define your own dim,dims,etc. functions and importing that module. The functionality should remain the same.
You can also use the MatchAll class and the match function to define custom transformations along Symbols. Example: Get rid of all kilo prefixes in a dimension.
