Merge pull request #619 from JuliaArrays/cjf/reinterpret-docfix

Fix docs for reinterpret

Author: c42f

docs/src/pages/api.md

@@ -241,16 +241,47 @@ Another common way of storing the same data is as a 3×`N` `Matrix{Float64}`.
 Rather conveniently, such types have *exactly* the same binary layout in memory,
 and therefore we can use `reinterpret` to convert between the two formats
 ```julia
-function svectors(x::Matrix{Float64})
-    @assert size(x,1) == 3
-    reinterpret(SVector{3,Float64}, x, (size(x,2),))
+function svectors(x::Matrix{T}, ::Val{N}) where {T,N}
+    size(x,1) == N || error("sizes mismatch")
+    isbitstype(T) || error("use for bitstypes only")
+    reinterpret(SVector{N,T}, vec(x))
 end
 ```
-Such a conversion does not copy the data, rather it refers to the *same* memory
-referenced by two different Julia `Array`s. Arguably, a `Vector` of `SVector`s
-is preferable to a `Matrix` because (a) it provides a better abstraction of the
-objects contained in the array and (b) it allows the fast *StaticArrays* methods
-to act on elements.
+Such a conversion does not copy the data, rather it refers to the *same* memory.
+Arguably, a `Vector` of `SVector`s is often preferable to a `Matrix` because it
+provides a better abstraction of the objects contained in the array and it
+allows the fast *StaticArrays* methods to act on elements.
+
+However, the resulting object is a Base.ReinterpretArray, not an Array, which
+carries some runtime penalty on every single access. If you can afford the
+memory for a copy and can live with the non-shared mutation semantics, then it
+is better to pull a copy by e.g.
+```julia
+function svectorscopy(x::Matrix{T}, ::Val{N}) where {T,N}
+    size(x,1) == N || error("sizes mismatch")
+    isbitstype(T) || error("use for bitstypes only")
+    copy(reinterpret(SVector{N,T}, vec(x)))
+end
+```
+For example:
+```
+julia> M=reshape(collect(1:6), (2,3))
+2×3 Array{Int64,2}:
+ 1  3  5
+ 2  4  6
+
+julia> svectors(M, Val{2}())
+3-element reinterpret(SArray{Tuple{2},Int64,1,2}, ::Array{Int64,1}):
+ [1, 2]
+ [3, 4]
+ [5, 6]
+
+julia> svectorscopy(M, Val{2}())
+3-element Array{SArray{Tuple{2},Int64,1,2},1}:
+ [1, 2]
+ [3, 4]
+ [5, 6]
+```
 
 ### Working with mutable and immutable arrays