add a note about reinterpret's memory layout

README.md

@@ -342,3 +342,70 @@ julia> s
  Foo(44, "d")
  Foo(55, "e")
 ```
+
+## Advanced: StructArrays versus struct-of-arrays layout in higher-dimensional array
+
+Regular arrays of structs can sometimes be reinterpreted as arrays of primitive values with an added
+initial dimension.
+
+```julia
+julia> v = [1.0+3im, 2.0-im]
+2-element Vector{ComplexF64}:
+ 1.0 + 3.0im
+ 2.0 - 1.0im
+
+julia> reinterpret(reshape, Float64, v)
+2×2 reinterpret(reshape, Float64, ::Vector{ComplexF64}) with eltype Float64:
+ 1.0   2.0
+ 3.0  -1.0
+```
+
+However, the situation is more complex for the `StructArray` format, where `s = StructArray(v)` is
+stored as two separate `Vector{Float64}`. `reinterpret` on `StructArray` returns an
+"array-of-structs" layout, as the reinterpretation works element-wise:
+
+```julia
+julia> s = StructArray([1.0+3im, 2.0-im])
+2-element StructArray(::Vector{Float64}, ::Vector{Float64}) with eltype ComplexF64:
+ 1.0 + 1.0im
+ 2.0 - 1.0im
+
+julia> reinterpret(reshape, Float64, s) # The actual memory is `([1.0, 2.0], [3.0, -1.0])`
+2×2 reinterpret(reshape, Float64, StructArray(::Vector{Float64}, ::Vector{Float64})) with eltype Float64:
+ 1.0   2.0
+ 3.0  -1.0
+```
+
+If you already have a `StructArray`, the easiest way is to get the higher-dimensional
+"struct-of-arrays" layout is to directly stack the components in memory order:
+
+```julia
+julia> using StackViews # lazily cat/stack arrays in a new tailing dimension
+
+julia> StackView(StructArrays.components(s)...)
+2×2 StackView{Float64, 2, 2, Tuple{Vector{Float64}, Vector{Float64}}}:
+ 1.0   3.0
+ 2.0  -1.0
+```
+
+StructArrays also provides a way to reconstruct from a given memory block via `dims` keyword:
+
+```julia
+julia> v = Float64[1 3; 2 -1]
+2×2 Matrix{Float64}:
+ 1.0   3.0
+ 2.0  -1.0
+
+julia> StructArray{ComplexF64}(v, dims=1) # the actual memory is `([1.0, 3.0], [2.0, -1.0])`
+2-element StructArray(view(::Matrix{Float64}, 1, :), view(::Matrix{Float64}, 2, :)) with eltype ComplexF64:
+ 1.0 + 2.0im
+ 3.0 - 1.0im
+
+julia> s = StructArray{ComplexF64}(v, dims=2) # the actual memory is `([1.0, 2.0], [3.0, -1.0])`
+2-element StructArray(view(::Matrix{Float64}, :, 1), view(::Matrix{Float64}, :, 2)) with eltype ComplexF64:
+ 1.0 + 3.0im
+ 2.0 - 1.0im
+```
+
+This, however, depends on the underlying data layout and how you interpret the memory block. You
+should use this with caution because otherwise it might give you unexpected results.