more detailed docstring for read! and write

[mgkuhn]

The old read! docstring failed to describe how many bytes the
function reads and what its return value is.

[stevengj]

This isn't quite right — the number of bytes is only sizeof(a) if isbitstype(eltype(a)).

A more general and accurate description would be:

Read `length(a)` consecutive values of type `eltype(a)` from an I/O stream or file into `a`, returning `a`.

[Seelengrab]

Does the function even work for non-isbits?

[mgkuhn]

@Seelengrab: If isbitstype(T)==false, then read!(..., a::AbstractArray{T,N}) just runs

for i in eachindex(a)
    a[i] = read(s, T)
end

i.e. falls back to whatever read() method was provided for type T, and the number of bytes read will depend on what that does. Also, it seems read!(..., a::Ref{T}) currently doesn't have such a fallback and therefore is only intended for isbitstype(T)==true.

[Seelengrab]

Right, that's what I mean - non-bitstypes can't really be read like that, because of the pointers contained within. They need to be properly deserialized and recreated in a more complicated manner.

[mgkuhn]

I've now updated this docstring PR:

• I've used for read! phrasing similar to what @stevengj suggested
• I've added a note that read!(..., Ref{T}) is only intended for primitive types. I first wasn't sure whether it should be documented at all (as it seems an unsafe function when used with non-primitive types), but then saw that it was already mentioned in the docstring of write.
• The write docstring now also covers writing arrays.

[vtjnash]

Suggested change

	julia> write(stdout, [0x41 0x42; 0x43 0x44], 0x0a)
	julia> write(stdout, UInt8['A' 'B'; 'C' 'D'], '\n')

[vtjnash]

Suggested change

	If `a` is an `Array` and `isbitstype(T)` is true, this function reads
	`size(a)` bytes directly into memory. Otherwise, each element of
	`a::AbstractArray{T}` is read with a call to `read(stream, T)`.
	If `isbitstype(T)` is true, this function reads `sizeof(a)` bytes
	directly into memory. Otherwise, each element of `a` is populated
	sequentially by a call to `read(stream, T)`.

[N5N3]

Not sure if sizeof(a) is accurate here.
Base.sizeof is not defined for most AbstractArray and it falls back to Core.sizeof by default.

BTW, if we expect AbstractArrays to behave like Arrays, then the optimization for StridedArrays needs to check elsize(A) == elsize(Array{eltype(A)}) to avoid possible padding mismatch.

[vtjnash]

yeah, maybe sizeof(T) * length(a) bytes would be better then? (more accurate yet would be Base.aligned_sizeof, but that seems a bit overly pedantic to me)