rename read to read! where a passed array is modified. fixes #5970

JuliaLang · Mar 18, 2014 · 3189946 · 3189946
1 parent d563306
commit 3189946
Show file tree

Hide file tree

Showing 11 changed files with 43 additions and 26 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -254,6 +254,8 @@ Deprecated or removed
 
   * `put!` now returns its first argument, the remote reference ([#5819])
 
+  * `read` methods that modify a passed array are now called `read!` ([#5970])
+
 [#4042]: https://github.com/JuliaLang/julia/issues/4042
 [#5164]: https://github.com/JuliaLang/julia/issues/5164
 [#4026]: https://github.com/JuliaLang/julia/issues/4026
@@ -326,6 +328,7 @@ Deprecated or removed
 [#6073]: https://github.com/JuliaLang/julia/issues/6073
 [#5778]: https://github.com/JuliaLang/julia/issues/5778
 [#6169]: https://github.com/JuliaLang/julia/issues/6169
+[#5970]: https://github.com/JuliaLang/julia/issues/5970
 
 Julia v0.2.0 Release Notes
 ==========================

diff --git a/base/client.jl b/base/client.jl
@@ -164,7 +164,7 @@ function run_repl()
                     if eof(STDIN) # if TTY, can throw InterruptException, must be in try/catch block
                         return
                     end
-                    read(STDIN, buf)
+                    read!(STDIN, buf)
                     ccall(:jl_read_buffer,Void,(Ptr{Void},Cssize_t),buf,length(buf))
                 catch ex
                     if isa(ex,InterruptException)

diff --git a/base/deprecated.jl b/base/deprecated.jl
@@ -423,6 +423,15 @@ Set{T<:Number}(xs::T...) = Set{T}(xs)
 
 @deprecate convert{T}(p::Type{Ptr{T}}, a::Array) convert(p, pointer(a))
 
+@deprecate read(from::IOBuffer, a::Array)            read!(from, a)
+@deprecate read(from::IOBuffer, p::Ptr, nb::Integer) read!(from, p, nb)
+@deprecate read(s::IOStream, a::Array)               read!(s, a)
+@deprecate read(this::AsyncStream, a::Array)         read!(this, a)
+@deprecate read(f::File, a::Array, nel)              read!(f, a, nel)
+@deprecate read(f::File, a::Array)                   read!(f, a)
+@deprecate read(s::IO, a::Array)                     read!(s, a)
+@deprecate read(s::IO, B::BitArray)                  read!(s, B)
+
 # 0.3 discontinued functions
 
 function nnz(X)

diff --git a/base/exports.jl b/base/exports.jl
@@ -1081,6 +1081,7 @@ export
     position,
     RawFD,
     read,
+    read!,
     readall,
     readavailable,
     readbytes!,

diff --git a/base/fs.jl b/base/fs.jl
@@ -37,7 +37,7 @@ export File,
        S_IRGRP, S_IWGRP, S_IXGRP, S_IRWXG,
        S_IROTH, S_IWOTH, S_IXOTH, S_IRWXO
 
-import Base: uvtype, uvhandle, eventloop, fd, position, stat, close, write, read, readbytes, isopen,
+import Base: uvtype, uvhandle, eventloop, fd, position, stat, close, write, read, read!, readbytes, isopen,
             _sizeof_uv_fs, uv_error
 
 include("file_constants.jl")
@@ -193,7 +193,7 @@ function read(f::File, ::Type{Uint8})
     return uint8(ret)
 end
 
-function read{T}(f::File, a::Array{T}, nel=length(a))
+function read!{T}(f::File, a::Array{T}, nel=length(a))
     if nel < 0 || nel > length(a)
         throw(BoundsError())
     end
@@ -215,15 +215,15 @@ function readbytes!(f::File, b::Array{Uint8}, nb=length(b))
     if length(b) < nr
         resize!(b, nr)
     end
-    read(f, b, nr)
+    read!(f, b, nr)
     return nr
 end
-readbytes(io::File) = read(io, Array(Uint8, nb_available(io)))
-readbytes(io::File, nb) = read(io, Array(Uint8, min(nb, nb_available(io))))
+readbytes(io::File) = read!(io, Array(Uint8, nb_available(io)))
+readbytes(io::File, nb) = read!(io, Array(Uint8, min(nb, nb_available(io))))
 
 function readbytes(f::File)
     a = Array(Uint8, nb_available(f))
-    read(f,a)
+    read!(f,a)
     a
 end
 

diff --git a/base/io.jl b/base/io.jl
@@ -115,9 +115,9 @@ read{T}(s::IO, t::Type{T}, d1::Int, dims::Int...) =
 read{T}(s::IO, t::Type{T}, d1::Integer, dims::Integer...) =
     read(s, t, map(int,tuple(d1,dims...)))
 
-read{T}(s::IO, ::Type{T}, dims::Dims) = read(s, Array(T, dims))
+read{T}(s::IO, ::Type{T}, dims::Dims) = read!(s, Array(T, dims))
 
-function read{T}(s::IO, a::Array{T})
+function read!{T}(s::IO, a::Array{T})
     for i = 1:length(a)
         a[i] = read(s, T)
     end
@@ -419,15 +419,15 @@ function read(s::IOStream, ::Type{Uint8})
     uint8(b)
 end
 
-function read{T}(s::IOStream, a::Array{T})
+function read!{T}(s::IOStream, a::Array{T})
     if isbits(T)
         nb = length(a)*sizeof(T)
         if ccall(:ios_readall, Uint,
                  (Ptr{Void}, Ptr{Void}, Uint), s.ios, a, nb) < nb
             throw(EOFError())
         end
     else
-        invoke(read, (IO, Array), s, a)
+        invoke(read!, (IO, Array), s, a)
     end
     a
 end
@@ -549,4 +549,4 @@ end
 # BitArray I/O
 
 write(s::IO, B::BitArray) = write(s, B.chunks)
-read(s::IO, B::BitArray) = read(s, B.chunks)
+read!(s::IO, B::BitArray) = read!(s, B.chunks)
diff --git a/base/iobuffer.jl b/base/iobuffer.jl
@@ -38,7 +38,7 @@ IOBuffer(readable::Bool,writable::Bool) = IOBuffer(Uint8[],readable,writable)
 IOBuffer() = IOBuffer(Uint8[], true, true)
 IOBuffer(maxsize::Int) = (x=IOBuffer(Array(Uint8,maxsize),true,true,maxsize); x.size=0; x)
 
-read(from::IOBuffer, a::Array) = read_sub(from, a, 1, length(a))
+read!(from::IOBuffer, a::Array) = read_sub(from, a, 1, length(a))
 
 function read_sub{T}(from::IOBuffer, a::Array{T}, offs, nel)
     if offs+nel-1 > length(a) || offs < 1 || nel < 0
@@ -47,12 +47,12 @@ function read_sub{T}(from::IOBuffer, a::Array{T}, offs, nel)
     if !isbits(T)
         error("read from IOBuffer only supports bits types or arrays of bits types; got "*string(T))
     end
-    read(from, pointer(a, offs), nel*sizeof(T))
+    read!(from, pointer(a, offs), nel*sizeof(T))
     return a
 end
 
-read(from::IOBuffer, p::Ptr, nb::Integer) = read(from, p, int(nb))
-function read(from::IOBuffer, p::Ptr, nb::Int)
+read!(from::IOBuffer, p::Ptr, nb::Integer) = read!(from, p, int(nb))
+function read!(from::IOBuffer, p::Ptr, nb::Int)
     if !from.readable error("read failed") end
     avail = nb_available(from)
     adv = min(avail,nb)
@@ -182,7 +182,7 @@ function takebuf_array(io::IOBuffer)
     else
         nbytes = nb_available(io)
         a = Array(Uint8, nbytes)
-        data = read(io, a)
+        data = read!(io, a)
     end
     if io.writable
         io.ptr = 1
@@ -240,8 +240,8 @@ function readbytes!(io::IOBuffer, b::Array{Uint8}, nb=length(b))
     read_sub(io, b, 1, nr)
     return nr
 end
-readbytes(io::IOBuffer) = read(io, Array(Uint8, nb_available(io)))
-readbytes(io::IOBuffer, nb) = read(io, Array(Uint8, min(nb, nb_available(io))))
+readbytes(io::IOBuffer) = read!(io, Array(Uint8, nb_available(io)))
+readbytes(io::IOBuffer, nb) = read!(io, Array(Uint8, min(nb, nb_available(io))))
 
 function search(buf::IOBuffer, delim)
     p = pointer(buf.data, buf.ptr)
@@ -253,5 +253,5 @@ function readuntil(io::IOBuffer, delim::Uint8)
     if nb == 0
         nb = nb_available(io)
     end
-    read(io, Array(Uint8, nb))
+    read!(io, Array(Uint8, nb))
 end
diff --git a/base/random.jl b/base/random.jl
@@ -80,7 +80,7 @@ end
 function srand(filename::String, n::Integer)
     open(filename) do io
         a = Array(Uint32, int(n))
-        read(io, a)
+        read!(io, a)
         srand(a)
     end
 end

diff --git a/base/stream.jl b/base/stream.jl
@@ -629,15 +629,15 @@ function readall(stream::AsyncStream)
     return takebuf_string(stream.buffer)
 end
 
-function read{T}(this::AsyncStream, a::Array{T})
+function read!{T}(this::AsyncStream, a::Array{T})
     isbits(T) || error("read from buffer only supports bits types or arrays of bits types")
     nb = length(a)*sizeof(T)
     buf = this.buffer
     @assert buf.seekable == false
     @assert buf.maxsize >= nb
     start_reading(this)
     wait_readnb(this,nb)
-    read(this.buffer, a)
+    read!(this.buffer, a)
     return a
 end
 

diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst
@@ -1356,6 +1356,10 @@ I/O
 
    Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return.
 
+.. function:: read!(stream, array::Array)
+
+   Read binary data from a stream, filling in the argument ``array``.
+
 .. function:: readbytes!(stream, b::Vector{Uint8}, nb=length(b))
 
    Read at most ``nb`` bytes from the stream into ``b``, returning the

diff --git a/test/iobuffer.jl b/test/iobuffer.jl
@@ -10,7 +10,7 @@ let io = IOBuffer()
 seek(io, 0)
 @test read(io,Uint8) == 'a'
 a = Array(Uint8, 2)
-@test read(io, a) == a
+@test read!(io, a) == a
 @test a == ['b','c']
 @test bytestring(io) == "abc"
 seek(io, 1)
@@ -29,7 +29,7 @@ seek(io, 2)
 truncate(io, 10)
 @test ioslength(io) == 10
 io.readable = false
-@test_throws read(io,Uint8[0])
+@test_throws read!(io,Uint8[0])
 truncate(io, 0)
 @test write(io,"boston\ncambridge\n") > 0
 @test takebuf_string(io) == "boston\ncambridge\n"
@@ -122,7 +122,7 @@ end
 # issue 5453
 let io=IOBuffer("abcdef")
 a = Array(Uint8,1024)
-@test_throws read(io,a)
+@test_throws read!(io,a)
 @test eof(io)
 end