Add note about broadcasting etc. to the readme (#154)

* add note about broadcasting etc. to readme

* upgrade to warning

* syntax colour

* tweak

* tweak

Author: mcabbott

README.md

@@ -87,3 +87,38 @@ These types have methods that perform many operations efficiently,
 including elementary algebra operations like multiplication and addition,
 as well as linear algebra methods like
 `norm`, `adjoint`, `transpose` and `vec`.
+
+## Warning!
+
+Broadcasting operations and `map`, `mapreduce` are also done efficiently, by evaluating the function being applied only once:
+
+```julia
+julia> map(sqrt, Fill(4, 2,5))  # one evaluation, not 10, to save time
+2×5 Fill{Float64}: entries equal to 2.0
+
+julia> println.(Fill(pi, 10))
+π
+10-element Fill{Nothing}: entries equal to nothing
+```
+
+Notice that this will only match the behaviour of a dense matrix from `fill` if the function is pure. And that this shortcut is taken *before* any other fused broadcast:
+
+```julia
+julia> map(_ -> rand(), Fill("pi", 2,5))  # not a pure function!
+2×5 Fill{Float64}: entries equal to 0.7201617100284206
+
+julia> map(_ -> rand(), fill("4", 2,5))  # 10 evaluations, different answer!
+2×5 Matrix{Float64}:
+ 0.43675   0.270809  0.56536   0.0948089  0.24655
+ 0.959363  0.79598   0.238662  0.401909   0.317716
+
+julia> ones(1,5) .+ (_ -> rand()).(Fill("vec", 2))  # Fill broadcast is done first
+2×5 Matrix{Float64}:
+ 1.51796  1.51796  1.51796  1.51796  1.51796
+ 1.51796  1.51796  1.51796  1.51796  1.51796
+
+julia> ones(1,5) .+ (_ -> rand()).(fill("vec", 2))  # fused, 10 evaluations
+2×5 Matrix{Float64}:
+ 1.51337  1.17578  1.19815  1.43035  1.2987
+ 1.30253  1.21909  1.61755  1.02645  1.77681
+```