Document use with packages for physical units

Suggested by Andrew Keller at
PainterQubits/Unitful.jl#22.

README.md

@@ -39,6 +39,8 @@ easily get the uncertainty of the result according to
   [standard score](https://en.wikipedia.org/wiki/Standard_score) and
   [weighted mean](https://en.wikipedia.org/wiki/Weighted_arithmetic_mean)
 * Easy way to attach the uncertainty to a number using `±` sign
+* Combined with external packages allows for error propagation of measurements
+  with their physical units
 
 Further features are expected to come in the future, see the section "How Can I
 Help?" and the TODO list below.
@@ -279,6 +281,31 @@ mean((3.1±0.32, 3.2±0.38, 3.5±0.61, 3.8±0.25))
 # => 3.4000000000000004 ± 0.2063673908348894
 ```
 
+### Use with ``SIUnits.jl`` and ``Unitful.jl`` ###
+
+Used together with external packages, ``Measurements.jl`` enables you to perform
+calculations of numbers with both uncertainty and physical units.  For example,
+you can use [`SIUnits.jl`](https://github.com/Keno/SIUnits.jl) or
+[`Unitful.jl`](https://github.com/ajkeller34/Unitful.jl).
+
+``` julia
+using Measurements, SIUnits, SIUnits.ShortUnits
+hypot((3 ± 1)*m, (4 ± 2)*m) # Pythagorean theorem
+# => 5.0 ± 1.7088007490635064 m
+(50 ± 1)Ω * (13 ± 2.4)*1e-2*A # Ohm's Law
+# => 6.5 ± 1.20702112657567 kg m²s⁻³A⁻¹
+2pi*sqrt((5.4 ± 0.3)*m / ((9.81 ± 0.01)*m/s^2)) # Pendulum's  period
+# => 4.661677707464357 ± 0.1295128435999655 s
+
+using Measurements, Unitful
+hypot((3 ± 1)*u"m", (4 ± 2)*u"m") # Pythagorean theorem
+# => 5.0 ± 1.7088007490635064 m
+(50 ± 1)*u"Ω" * (13 ± 2.4)*1e-2*u"A" # Ohm's Law
+# => 6.5 ± 1.20702112657567 A Ω
+2pi*sqrt((5.4 ± 0.3)*u"m" / ((9.81 ± 0.01)*u"m/s^2")) # Pendulum's period
+# => 4.661677707464357 ± 0.12951284359996548 s
+```
+
 Development
 -----------
 

docs/examples.rst

@@ -394,3 +394,29 @@ measurements.  They work with real and complex measurements, scalars or arrays:
     # => 2-element Array{Complex{Float64},1}:
     #     2.9+3.0im
     #     2.8+4.6im
+
+Use with ``SIUnits.jl`` and ``Unitful.jl``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use ``Measurements.jl`` in combination with external package in order to
+perform calculation of unitful numbers with uncertainties.  The details depend
+on the specific package adopted, here are a few examples with ``SIUnits.jl`` and
+``Unitful.jl``
+
+.. code-block:: julia
+
+   using Measurements, SIUnits, SIUnits.ShortUnits
+   hypot((3 ± 1)*m, (4 ± 2)*m) # Pythagorean theorem
+   # => 5.0 ± 1.7088007490635064 m
+   (50 ± 1)Ω * (13 ± 2.4)*1e-2*A # Ohm's Law
+   # => 6.5 ± 1.20702112657567 kg m²s⁻³A⁻¹
+   2pi*sqrt((5.4 ± 0.3)*m / ((9.81 ± 0.01)*m/s^2)) # Pendulum's  period
+   # => 4.661677707464357 ± 0.1295128435999655 s
+
+   using Measurements, Unitful
+   hypot((3 ± 1)*u"m", (4 ± 2)*u"m") # Pythagorean theorem
+   # => 5.0 ± 1.7088007490635064 m
+   (50 ± 1)*u"Ω" * (13 ± 2.4)*1e-2*u"A" # Ohm's Law
+   # => 6.5 ± 1.20702112657567 A Ω
+   2pi*sqrt((5.4 ± 0.3)*u"m" / ((9.81 ± 0.01)*u"m/s^2")) # Pendulum's period
+   # => 4.661677707464357 ± 0.12951284359996548 s

docs/index.rst

@@ -33,6 +33,8 @@ These are the main fetures of the package:
   <https://en.wikipedia.org/wiki/Standard_score>`__ and `weighted mean
   <https://en.wikipedia.org/wiki/Weighted_arithmetic_mean>`__
 - Easy way to attach the uncertainty to a number using ``±`` sign
+- Combined with external packages allows for error propagation of measurements
+  with their physical units
 
 Further features are expected to come in the future, see the "How Can I Help?"
 section and the TODO list.

docs/usage.rst

@@ -155,3 +155,14 @@ Functions ``value`` and ``uncertainty`` allows you to get the nominal value and
 the uncertainty of ``x``, be it a single measurement or an array of
 measurements.  They are particularly useful in the case of complex measurements
 or arrays of measurements.
+
+Error Propagation of Numbers with Units
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Measurements.jl`` does not know about physical units, but can be easily
+employed in combination with other packages providing this feature.  Such
+packages are, for example, `SIUnits.jl <https://github.com/Keno/SIUnits.jl>`__
+and `Unitful.jl <https://github.com/ajkeller34/Unitful.jl>`__.  You only have to
+use the ``Measurement`` object as the value of the ``SIQuantity`` object (for
+``SIUnits.jl``) or of the ``Quantity`` object (for ``Unitful.jl``).  See the
+Examples section.