Merge pull request #17 from ExpandingMan/nounitsdocs

Add clearer docs for explicit NoUnits conversions

Author: Ouroboros42

README.md

@@ -34,6 +34,15 @@ For quantities that are unitless in a given system, the exact unit specified wil
     julia> natural(10u"N", unitless, u"s^-1")
     1.5326173119543876 s^-1
 ```
+To explicitly check that dimensionless quantities are returned as regular floats, specify `NoUnits`, for
+example
+```julia
+julia> natural(1u"km/s", NoUnits)
+3.3356409519815205e-6
+
+julia> natural(1u"kg", NoUnits)
+ERROR: DimensionError:  and kg c^2 are not dimensionally compatible.
+```
 The unit that will be used by `natural` can be found using `naturalunit`.
 ```julia
     julia> naturalunit(10u"N")
@@ -76,4 +85,4 @@ Any `NaturalSystem` can be called as a function like `natural`.
 
     julia> unitless(u"kg")
     4.5946711112415865e7
-```
+```

src/natural.jl

@@ -58,6 +58,9 @@ naturalunit(q, units::Units...) = naturalunit(q, DEFAULT_UNITS, units...)
 
 Express `q` in terms of the produts of the given `units`, using natural conversions from `system`.
 If no `units` are specified, uses the default units for `system`. 
+
+To explicilty check that the the returned values is dimensionless and therefore of a `Real` type, set
+`NoUnits`, e.g. `natural(q, sys, NoUnits)`.
 """
 function natural(q, system::NaturalSystem, units::Units...)
     unit = naturalunit(q, system, units...)
@@ -70,4 +73,4 @@ natural(q, units::Units...) = natural(q, DEFAULT_UNITS, units...)
 # For convenience when using custom unit systems
 (system::NaturalSystem)(q, units::Units...) = natural(q, system, units...)
 
-const unitless = QG_UNITS
+const unitless = QG_UNITS

test/runtests.jl

@@ -19,4 +19,6 @@ using Test
     @test (@inferred natural(u"G"^(-1//2), QG_UNITS, u"μg")) ≈ 21.7u"μg" rtol = 0.05
 
     @inferred natural(u"kg^2 / m", PARTICLE_UNITS)
+
+    @test_throws Unitful.DimensionError natural(1u"kg", NoUnits)
 end