Document and export Base.peek (#28811)

ararslan · web-flow · commit d4d930399cb0 · 2020-05-06T20:56:34.000-04:00
diff --git a/NEWS.md b/NEWS.md
@@ -137,6 +137,7 @@ New library features
 * The introspection macros (`@which`, `@code_typed`, etc.) now work with `do`-block syntax ([#35283]) and with dot syntax ([#35522]).
 * `count` now accepts the `dims` keyword.
 * new in-place `count!` function similar to `sum!`.
+* `peek` is now exported and accepts a type to peek from a stream ([#28811]).
 
 Standard library changes
 ------------------------
diff --git a/base/essentials.jl b/base/essentials.jl
@@ -785,6 +785,31 @@ ismissing(::Any) = false
 ismissing(::Missing) = true
 
 function popfirst! end
+
+"""
+    peek(stream[, T=UInt8])
+
+Read and return a value of type `T` from a stream without advancing the current position
+in the stream.
+
+# Examples
+
+```jldoctest
+julia> b = IOBuffer("julia");
+
+julia> peek(b)
+0x6a
+
+julia> position(b)
+0
+
+julia> peek(b, Char)
+'j': ASCII/Unicode U+006A (category Ll: Letter, lowercase)
+```
+
+!!! compat "Julia 1.5"
+    The method which accepts a type requires Julia 1.5 or later.
+"""
 function peek end
 
 """
diff --git a/base/exports.jl b/base/exports.jl
@@ -795,6 +795,7 @@ export
     bytesavailable,
     ntoh,
     open,
+    peek,
     pipeline,
     Pipe,
     PipeBuffer,
diff --git a/base/io.jl b/base/io.jl
@@ -251,14 +251,16 @@ function unsafe_read(s::IO, p::Ptr{UInt8}, n::UInt)
     nothing
 end
 
-function peek(s::IO)
+function peek(s::IO, ::Type{T}) where T
     mark(s)
-    try read(s, UInt8)
+    try read(s, T)
     finally
         reset(s)
     end
 end
 
+peek(s) = peek(s, UInt8)
+
 # Generic `open` methods
 
 """
@@ -348,11 +350,12 @@ readbytes!(io::AbstractPipe, target::AbstractVector{UInt8}, n=length(target)) =
 
 for f in (
         # peek/mark interface
-        :peek, :mark, :unmark, :reset, :ismarked,
+        :mark, :unmark, :reset, :ismarked,
         # Simple reader functions
         :readavailable, :isreadable)
     @eval $(f)(io::AbstractPipe) = $(f)(pipe_reader(io))
 end
+peek(io::AbstractPipe, ::Type{T}) where {T} = peek(pipe_reader(io), T)
 
 iswritable(io::AbstractPipe) = iswritable(pipe_writer(io))
 isopen(io::AbstractPipe) = isopen(pipe_writer(io)) || isopen(pipe_reader(io))
diff --git a/base/iobuffer.jl b/base/iobuffer.jl
@@ -172,7 +172,7 @@ function unsafe_read(from::GenericIOBuffer, p::Ptr{UInt8}, nb::UInt)
     nothing
 end
 
-function read(from::GenericIOBuffer, T::Union{Type{Int16},Type{UInt16},Type{Int32},Type{UInt32},Type{Int64},Type{UInt64},Type{Int128},Type{UInt128},Type{Float16},Type{Float32},Type{Float64}})
+function peek(from::GenericIOBuffer, T::Union{Type{Int16},Type{UInt16},Type{Int32},Type{UInt32},Type{Int64},Type{UInt64},Type{Int128},Type{UInt128},Type{Float16},Type{Float32},Type{Float64}})
     from.readable || _throw_not_readable()
     avail = bytesavailable(from)
     nb = sizeof(T)
@@ -183,7 +183,12 @@ function read(from::GenericIOBuffer, T::Union{Type{Int16},Type{UInt16},Type{Int3
         ptr::Ptr{T} = pointer(from.data, from.ptr)
         x = unsafe_load(ptr)
     end
-    from.ptr += nb
+    return x
+end
+
+function read(from::GenericIOBuffer, T::Union{Type{Int16},Type{UInt16},Type{Int32},Type{UInt32},Type{Int64},Type{UInt64},Type{Int128},Type{UInt128},Type{Float16},Type{Float32},Type{Float64}})
+    x = peek(from, T)
+    from.ptr += sizeof(T)
     return x
 end
 
@@ -216,7 +221,7 @@ end
     return byte
 end
 
-function peek(from::GenericIOBuffer)
+function peek(from::GenericIOBuffer, ::Type{UInt8})
     from.readable || _throw_not_readable()
     if from.ptr > from.size
         throw(EOFError())
diff --git a/base/iostream.jl b/base/iostream.jl
@@ -525,6 +525,10 @@ end
 
 ## peek ##
 
-function peek(s::IOStream)
-    @_lock_ios s ccall(:ios_peekc, Cint, (Ptr{Cvoid},), s)
+function peek(s::IOStream, ::Type{UInt8})
+    b = @_lock_ios s ccall(:ios_peekc, Cint, (Ptr{Cvoid},), s.ios)
+    if b == -1
+        throw(EOFError())
+    end
+    return b % UInt8
 end
diff --git a/base/iterators.jl b/base/iterators.jl
@@ -1205,7 +1205,7 @@ julia> a = Iterators.Stateful([1,1,1,2,3,4]);
 
 julia> for x in a; x == 1 || break; end
 
-julia> Base.peek(a)
+julia> peek(a)
 3
 
 julia> sum(a) # Sum the remaining elements
diff --git a/base/secretbuffer.jl b/base/secretbuffer.jl
@@ -154,7 +154,7 @@ bytesavailable(io::SecretBuffer) = io.size - io.ptr + 1
 position(io::SecretBuffer) = io.ptr-1
 eof(io::SecretBuffer) = io.ptr > io.size
 isempty(io::SecretBuffer) = io.size == 0
-function peek(io::SecretBuffer)
+function peek(io::SecretBuffer, ::Type{UInt8})
     eof(io) && throw(EOFError())
     return io.data[io.ptr]
 end
diff --git a/base/stream.jl b/base/stream.jl
@@ -1193,9 +1193,9 @@ unmark(x::LibuvStream)   = unmark(x.buffer)
 reset(x::LibuvStream)    = reset(x.buffer)
 ismarked(x::LibuvStream) = ismarked(x.buffer)
 
-function peek(s::LibuvStream)
+function peek(s::LibuvStream, ::Type{T}) where T
     mark(s)
-    try read(s, UInt8)
+    try read(s, T)
     finally
         reset(s)
     end
diff --git a/doc/src/base/io-network.md b/doc/src/base/io-network.md
@@ -19,6 +19,7 @@ Base.read!
 Base.readbytes!
 Base.unsafe_read
 Base.unsafe_write
+Base.peek
 Base.position
 Base.seek
 Base.seekstart
diff --git a/stdlib/Markdown/src/Common/block.jl b/stdlib/Markdown/src/Common/block.jl
@@ -19,7 +19,7 @@ function paragraph(stream::IO, md::MD)
     while !eof(stream)
         char = read(stream, Char)
         if char == '\n' || char == '\r'
-            char == '\r' && !eof(stream) && Char(peek(stream)) == '\n' && read(stream, Char)
+            char == '\r' && !eof(stream) && peek(stream, Char) == '\n' && read(stream, Char)
             if prev_char == '\\'
                 write(buffer, '\n')
             elseif blankline(stream) || parse(stream, md, breaking = true)
diff --git a/stdlib/Markdown/src/Julia/interp.jl b/stdlib/Markdown/src/Julia/interp.jl
@@ -9,7 +9,7 @@ end
 
 function interpinner(stream::IO, greedy = false)
     startswith(stream, '$') || return
-    (eof(stream) || Char(peek(stream)) in whitespace) && return
+    (eof(stream) || peek(stream, Char) in whitespace) && return
     try
         return _parse(stream::IOBuffer, greedy = greedy)
     catch e
diff --git a/stdlib/Markdown/src/parse/parse.jl b/stdlib/Markdown/src/parse/parse.jl
@@ -53,9 +53,7 @@ function parseinline(stream::IO, md::MD, config::Config)
     content = []
     buffer = IOBuffer()
     while !eof(stream)
-        # FIXME: this is broken if we're looking for non-ASCII
-        # characters because peek only returns a single byte.
-        char = Char(peek(stream))
+        char = peek(stream, Char)
         if haskey(config.inner, char) &&
                 (inner = parseinline(stream, md, config.inner[char])) !== nothing
             c = String(take!(buffer))
diff --git a/stdlib/Markdown/src/parse/util.jl b/stdlib/Markdown/src/parse/util.jl
@@ -1,7 +1,5 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
-import Base: peek
-
 macro dotimes(n, body)
     quote
         for i = 1:$(esc(n))
@@ -16,7 +14,7 @@ const whitespace = " \t\r"
 Skip any leading whitespace. Returns io.
 """
 function skipwhitespace(io::IO; newlines = true)
-    while !eof(io) && (Char(peek(io)) in whitespace || (newlines && peek(io) == UInt8('\n')))
+    while !eof(io) && (peek(io, Char) in whitespace || (newlines && peek(io) == UInt8('\n')))
         read(io, Char)
     end
     return io
@@ -182,7 +180,7 @@ function parse_inline_wrapper(stream::IO, delimiter::AbstractString; rep = false
         startswith(stream, delimiter^n) || return nothing
         while startswith(stream, delimiter); n += 1; end
         !rep && n > nmin && return nothing
-        !eof(stream) && Char(peek(stream)) in whitespace && return nothing
+        !eof(stream) && peek(stream, Char) in whitespace && return nothing
 
         buffer = IOBuffer()
         while !eof(stream)
diff --git a/stdlib/Printf/src/Printf.jl b/stdlib/Printf/src/Printf.jl
@@ -56,7 +56,7 @@ function parse(s::AbstractString)
             '\'' in flags && error("printf format flag ' not yet supported")
             conversion == 'n'    && error("printf feature %n not supported")
             push!(list, conversion == '%' ? "%" : (flags,width,precision,conversion))
-            lastparse = isempty(a) ? lastindex(s)+1 : Base.peek(a)[1]
+            lastparse = isempty(a) ? lastindex(s)+1 : peek(a)[1]
         end
         lastidx = idx
     end
diff --git a/stdlib/REPL/src/LineEdit.jl b/stdlib/REPL/src/LineEdit.jl
@@ -8,7 +8,7 @@ using ..Terminals
 import ..Terminals: raw!, width, height, cmove, getX,
                        getY, clear_line, beep
 
-import Base: ensureroom, peek, show, AnyDict, position
+import Base: ensureroom, show, AnyDict, position
 using Base: something
 
 abstract type TextInterface end
diff --git a/stdlib/REPL/src/REPL.jl b/stdlib/REPL/src/REPL.jl
@@ -544,7 +544,7 @@ function hist_from_file(hp, file, path)
         while !isempty(line)
             push!(lines, chomp(line[2:end]))
             eof(file) && break
-            ch = Char(Base.peek(file))
+            ch = peek(file, Char)
             ch == ' '  && error(munged_history_message(path), countlines)
             ch != '\t' && break
             line = hist_getline(file)
diff --git a/stdlib/REPL/src/Terminals.jl b/stdlib/REPL/src/Terminals.jl
@@ -160,6 +160,6 @@ Base.haskey(t::TTYTerminal, key) = haskey(pipe_writer(t), key)
 Base.getindex(t::TTYTerminal, key) = getindex(pipe_writer(t), key)
 Base.get(t::TTYTerminal, key, default) = get(pipe_writer(t), key, default)
 
-Base.peek(t::TTYTerminal) = Base.peek(t.in_stream)
+Base.peek(t::TTYTerminal, ::Type{T}) where {T} = peek(t.in_stream, T)
 
 end # module
diff --git a/test/iobuffer.jl b/test/iobuffer.jl
@@ -332,3 +332,12 @@ end
     @test readline(b) == "Goodbye!"
     close(b)
 end
+
+@testset "peek(::GenericIOBuffer)" begin
+    io = Base.GenericIOBuffer(UInt8[], true, true, false, true, typemax(Int))
+    write(io, "こんにちは")
+    @test peek(io) == 0xe3
+    @test peek(io, Char) == 'こ'
+    @test peek(io, Int32) == -476872221
+    close(io)
+end
diff --git a/test/iostream.jl b/test/iostream.jl
@@ -108,4 +108,15 @@ end
         open(f -> readbytes!(f, y, 102, all=false), path)
         @test y == [x; 0]
     end
-end
+end
+
+@testset "peek(::IOStream)" begin
+    mktemp() do _, file
+        @test_throws EOFError peek(file)
+        mark(file)
+        write(file, "Lávate las manos")
+        flush(file)
+        reset(file)
+        @test peek(file) == 0x4c
+    end
+end
diff --git a/test/iterators.jl b/test/iterators.jl
@@ -678,7 +678,7 @@ end
     end
     let a = @inferred(Iterators.Stateful([1, 1, 1, 2, 3, 4]))
         for x in a; x == 1 || break; end
-        @test Base.peek(a) == 3
+        @test peek(a) == 3
         @test sum(a) == 7
     end
     @test eltype(Iterators.Stateful("a")) == Char
diff --git a/test/secretbuffer.jl b/test/secretbuffer.jl
@@ -11,6 +11,8 @@ using Test
         @test read(secret, String) == str
         seekstart(secret)
 
+        @test peek(secret) == 0x66
+
         @test shred!(secret) === secret
         @test read(secret, String) == ""
         @test str == "foobar"

Original file line number	Diff line number	Diff line change
`@@ -1205,7 +1205,7 @@ julia> a = Iterators.Stateful([1,1,1,2,3,4]);`
`1205`	`1205`
`1206`	`1206`	`julia> for x in a; x == 1 \|\| break; end`
`1207`	`1207`
`1208`		`-julia> Base.peek(a)`
	`1208`	`+julia> peek(a)`
`1209`	`1209`	`3`
`1210`	`1210`
`1211`	`1211`	`julia> sum(a) # Sum the remaining elements`