diff --git a/base/io.jl b/base/io.jl index 4d7f745b126e5..0f2e7da1d578d 100644 --- a/base/io.jl +++ b/base/io.jl @@ -110,18 +110,31 @@ function copy end function eof end """ - read(stream::IO, T) + read(io::IO, T) -Read a single value of type `T` from `stream`, in canonical binary representation. +Read a single value of type `T` from `io`, in canonical binary representation. - read(stream::IO, String) + read(io::IO, String) -Read the entirety of `stream`, as a String. +Read the entirety of `io`, as a `String`. + +# Examples +```jldoctest +julia> io = IOBuffer("JuliaLang is a GitHub organization"); + +julia> read(io, Char) +'J': ASCII/Unicode U+004a (category Lu: Letter, uppercase) + +julia> io = IOBuffer("JuliaLang is a GitHub organization"); + +julia> read(io, String) +"JuliaLang is a GitHub organization" +``` """ read(stream, t) """ - write(stream::IO, x) + write(io::IO, x) write(filename::AbstractString, x) Write the canonical binary representation of a value to the given I/O stream or file. @@ -129,8 +142,25 @@ Return the number of bytes written into the stream. You can write multiple values with the same `write` call. i.e. the following are equivalent: - write(stream, x, y...) - write(stream, x) + write(stream, y...) + write(io, x, y...) + write(io, x) + write(io, y...) + +# Examples +```jldoctest +julia> io = IOBuffer(); + +julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.") +56 + +julia> String(take!(io)) +"JuliaLang is a GitHub organization. It has many members." + +julia> write(io, "Sometimes those members") + write(io, " write documentation.") +44 + +julia> String(take!(io)) +"Sometimes those members write documentation." +``` """ function write end @@ -199,9 +229,17 @@ wait_readbyte(io::AbstractPipe, byte::UInt8) = wait_readbyte(pipe_reader(io), by wait_close(io::AbstractPipe) = (wait_close(pipe_writer(io)); wait_close(pipe_reader(io))) """ - nb_available(stream) + nb_available(io) Return the number of bytes available for reading before a read from this stream or buffer will block. + +# Examples +```jldoctest +julia> io = IOBuffer("JuliaLang is a GitHub organization"); + +julia> nb_available(io) +34 +``` """ nb_available(io::AbstractPipe) = nb_available(pipe_reader(io)) @@ -358,9 +396,22 @@ htol(x) """ - isreadonly(stream) -> Bool + isreadonly(io) -> Bool Determine whether a stream is read-only. + +# Examples +```jldoctest +julia> io = IOBuffer("JuliaLang is a GitHub organization"); + +julia> isreadonly(io) +true + +julia> io = IOBuffer(); + +julia> isreadonly(io) +false +``` """ isreadonly(s) = isreadable(s) && !iswritable(s) @@ -789,6 +840,7 @@ Advance the stream `io` such that the next-read character will be the first rema which `predicate` returns `false`. If the keyword argument `linecomment` is specified, all characters from that character until the start of the next line are ignored. +# Examples ```jldoctest julia> buf = IOBuffer(" text") IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=8, maxsize=Inf, ptr=1, mark=-1) @@ -819,6 +871,22 @@ end Read `io` until the end of the stream/file and count the number of lines. To specify a file pass the filename as the first argument. EOL markers other than `'\\n'` are supported by passing them as the second argument. + +# Examples +```jldoctest +julia> io = IOBuffer("JuliaLang is a GitHub organization.\n"); + +julia> countlines(io) +1 + +julia> io = IOBuffer("JuliaLang is a GitHub organization."); + +julia> countlines(io) +0 + +julia> countlines(io, '.') +1 +``` """ function countlines(io::IO, eol::Char='\n') isascii(eol) || throw(ArgumentError("only ASCII line terminators are supported")) diff --git a/base/iobuffer.jl b/base/iobuffer.jl index b63e19d983057..ca36ece66542c 100644 --- a/base/iobuffer.jl +++ b/base/iobuffer.jl @@ -38,6 +38,27 @@ Create an `IOBuffer`, which may optionally operate on a pre-existing array. If t readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. The last argument optionally specifies a size beyond which the buffer may not be grown. + +# Examples +```jldoctest +julia> io = IOBuffer("JuliaLang is a GitHub organization.") +IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=35, maxsize=Inf, ptr=1, mark=-1) + +julia> read(io, String) +"JuliaLang is a GitHub organization." + +julia> write(io, "This isn't writable.") +ERROR: ArgumentError: ensureroom failed, IOBuffer is not writeable + +julia> io = IOBuffer(UInt8[], true, true, 34) +IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=34, ptr=1, mark=-1) + +julia> write(io, "JuliaLang is a GitHub organization.") +34 + +julia> String(take!(io)) +"JuliaLang is a GitHub organization" +``` """ IOBuffer(data::AbstractVector{UInt8}, readable::Bool=true, writable::Bool=false, maxsize::Integer=typemax(Int)) = GenericIOBuffer(data, readable, writable, true, false, maxsize) @@ -51,7 +72,18 @@ end """ IOBuffer() -> IOBuffer -Create an in-memory I/O stream. +Create an in-memory I/O stream, which is both readable and writable. + +# Examples +```jldoctest +julia> io = IOBuffer(); + +julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.") +56 + +julia> String(take!(io)) +"JuliaLang is a GitHub organization. It has many members." +``` """ IOBuffer() = IOBuffer(true, true) @@ -59,6 +91,24 @@ IOBuffer() = IOBuffer(true, true) IOBuffer(size::Integer) Create a fixed size IOBuffer. The buffer will not grow dynamically. + +# Examples +```jldoctest +julia> io = IOBuffer(12) +IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=12, ptr=1, mark=-1) + +julia> write(io, "Hello world.") +12 + +julia> String(take!(io)) +"Hello world." + +julia> write(io, "Hello world again.") +12 + +julia> String(take!(io)) +"Hello world " +``` """ IOBuffer(maxsize::Integer) = (x=IOBuffer(StringVector(maxsize), true, true, maxsize); x.size=0; x) @@ -262,6 +312,17 @@ isopen(io::GenericIOBuffer) = io.readable || io.writable || io.seekable || nb_av Obtain the contents of an `IOBuffer` as an array, without copying. Afterwards, the `IOBuffer` is reset to its initial state. + +# Examples +```jldoctest +julia> io = IOBuffer(); + +julia> write(io, "JuliaLang is a GitHub organization.", "It has many members.") +55 + +julia> String(take!(io)) +"JuliaLang is a GitHub organization.It has many members." +``` """ function take!(io::GenericIOBuffer) ismarked(io) && unmark(io)