I/O 和网络
通用 I/O
Base.stdout
— 常量stdout::IO
引用标准输出流的全局变量。
Base.stderr
— 常量stderr::IO
引用标准错误流的全局变量。
Base.stdin
— 常量stdin::IO
引用标准输入流的全局变量。
Base.open
— 函数open(f::Function, args...; kwargs...)
将函数 f
应用于 open(args...; kwargs...)
的结果,并在完成后关闭生成的描述符。
示例
julia> write("myfile.txt", "Hello world!");
julia> open(io->read(io, String), "myfile.txt")
"Hello world!"
julia> rm("myfile.txt")
open(filename::AbstractString; lock = true, keywords...) -> IOStream
以五个布尔关键字参数指定的模式打开文件
关键字 | 描述 | 默认值 |
---|---|---|
read | 以只读方式打开 | !write |
write | 以只写方式打开 | truncate | append |
create | 如果不存在则创建 | !read & write | truncate | append |
truncate | 截断为零大小 | !read & write |
append | 移至末尾 | false |
当没有传递关键字参数时,默认情况下以只读方式打开文件。返回用于访问打开文件的流。
lock
关键字参数控制操作是否将被锁定以进行安全的多线程访问。
lock
参数在 Julia 1.5 中可用。
open(filename::AbstractString, [mode::AbstractString]; lock = true) -> IOStream
open 的替代语法,其中使用基于字符串的模式说明符而不是五个布尔值。mode
的值对应于 fopen(3)
或 Perl open
中的值,等效于设置以下布尔值组
模式 | 描述 | 关键字 |
---|---|---|
r | read | 无 |
w | write, create, truncate | write = true |
a | write, create, append | append = true |
r+ | read, write | read = true, write = true |
w+ | read, write, create, truncate | truncate = true, read = true |
a+ | read, write, create, append | append = true, read = true |
lock
关键字参数控制操作是否将被锁定以进行安全的多线程访问。
示例
julia> io = open("myfile.txt", "w");
julia> write(io, "Hello world!");
julia> close(io);
julia> io = open("myfile.txt", "r");
julia> read(io, String)
"Hello world!"
julia> write(io, "This file is read only")
ERROR: ArgumentError: write failed, IOStream is not writeable
[...]
julia> close(io)
julia> io = open("myfile.txt", "a");
julia> write(io, "This stream is not read only")
28
julia> close(io)
julia> rm("myfile.txt")
lock
参数在 Julia 1.5 中可用。
open(fd::OS_HANDLE) -> IO
获取原始文件描述符,将其包装在 Julia 感知 I/O 类型中,并获取对 fd 句柄的所有权。调用 open(Libc.dup(fd))
以避免对原始句柄的所有权捕获。
不要在系统其他部分已拥有句柄的句柄上调用此函数。
open(command, mode::AbstractString, stdio=devnull)
异步运行 command
。类似于 open(command, stdio; read, write)
,但通过模式字符串而不是关键字参数指定读写标志。可能的模式字符串为
模式 | 描述 | 关键字 |
---|---|---|
r | read | 无 |
w | write | write = true |
r+ | read, write | read = true, write = true |
w+ | read, write | read = true, write = true |
open(command, stdio=devnull; write::Bool = false, read::Bool = !write)
异步开始运行 command
,并返回一个 process::IO
对象。如果 read
为 true,则来自进程的读取来自进程的标准输出,并且 stdio
可选地指定进程的标准输入流。如果 write
为 true,则写入转到进程的标准输入,并且 stdio
可选地指定进程的标准输出流。进程的标准错误流连接到当前全局 stderr
。
open(f::Function, command, args...; kwargs...)
类似于 open(command, args...; kwargs...)
,但在生成的进程流上调用 f(stream)
,然后关闭输入流并等待进程完成。在成功的情况下返回 f
返回的值。如果进程失败或尝试将任何内容打印到 stdout,则抛出错误。
Base.IOStream
— 类型IOStream
包装操作系统文件描述符的缓冲 I/O 流。主要用于表示由 open
返回的文件。
Base.IOBuffer
— 类型IOBuffer([data::AbstractVector{UInt8}]; keywords...) -> IOBuffer
创建一个内存中 I/O 流,它可以选择在预先存在的数组上运行。
它可以接受可选的关键字参数
read
,write
,append
:将操作限制在缓冲区;有关详细信息,请参阅open
。truncate
:将缓冲区大小截断为零长度。maxsize
:指定缓冲区不能超过的尺寸。sizehint
:建议缓冲区的容量 (data
必须实现sizehint!(data, size)
)。
当没有给出 data
时,缓冲区默认情况下既可读又可写。
示例
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> io = IOBuffer(b"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[], read=true, write=true, maxsize=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"
julia> length(read(IOBuffer(b"data", read=true, truncate=false)))
4
julia> length(read(IOBuffer(b"data", read=true, truncate=true)))
0
IOBuffer(string::String)
在给定字符串的底层数据上创建一个只读 IOBuffer
。
示例
julia> io = IOBuffer("Haho");
julia> String(take!(io))
"Haho"
julia> String(take!(io))
"Haho"
Base.take!
— 方法take!(b::IOBuffer)
获得 IOBuffer
的内容作为数组。之后,IOBuffer
将重置为其初始状态。
示例
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."
Base.fdio
— 函数fdio([name::AbstractString, ]fd::Integer[, own::Bool=false]) -> IOStream
从整数文件描述符创建 IOStream
对象。如果 own
为 true
,则关闭此对象将关闭底层描述符。默认情况下,IOStream
在垃圾回收时关闭。name
允许将描述符与命名文件关联起来。
Base.flush
— 函数flush(stream)
将当前所有缓冲的写入提交到给定的流。
Base.close
— 函数close(stream)
关闭 I/O 流。首先执行 flush
。
Base.closewrite
— 函数closewrite(stream)
关闭全双工 I/O 流的写半部分。首先执行 flush
。通知另一端不会再将数据写入底层文件。并非所有 I/O 类型都支持此功能。
示例
julia> io = Base.BufferStream(); # this never blocks, so we can read and write on the same Task
julia> write(io, "request");
julia> # calling `read(io)` here would block forever
julia> closewrite(io);
julia> read(io, String)
"request"
Base.write
— 函数write(io::IO, x)
将值的规范二进制表示写入给定的 I/O 流或文件。返回写入流的字节数。另请参阅 print
以写入文本表示形式 (其编码可能取决于 io
)。
写入值的字节序取决于主机系统的字节序。在写入/读取时转换为/从固定字节序 (例如,使用 htol
和 ltoh
) 以获得跨平台一致的结果。
您可以使用相同的 write
调用写入多个值。即,以下等效
write(io, x, y...)
write(io, x) + write(io, y...)
示例
一致的序列化
julia> fname = tempname(); # random temporary filename
julia> open(fname,"w") do f
# Make sure we write 64bit integer in little-endian byte order
write(f,htol(Int64(42)))
end
8
julia> open(fname,"r") do f
# Convert back to host byte order and host integer type
Int(ltoh(read(f,Int64)))
end
42
合并写入调用
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."
当包装在 Ref
中时,没有 write
方法的用户定义的纯数据类型可以被写入
julia> struct MyStruct; x::Float64; end
julia> io = IOBuffer()
IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=Inf, ptr=1, mark=-1)
julia> write(io, Ref(MyStruct(42.0)))
8
julia> seekstart(io); read!(io, Ref(MyStruct(NaN)))
Base.RefValue{MyStruct}(MyStruct(42.0))
Base.read
— 函数read(io::IO, T)
从 io
中读取一个类型为 T
的单一值,以规范二进制表示形式。
请注意,Julia 不会为您转换字节序。为此,请使用 ntoh
或 ltoh
。
read(io::IO, String)
将整个 io
读取为 String
(另请参阅 readchomp
)。
示例
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(filename::AbstractString)
将文件的整个内容读取为 Vector{UInt8}
。
read(filename::AbstractString, String)
将文件的整个内容读取为字符串。
read(filename::AbstractString, args...)
打开文件并读取其内容。args
传递给 read
:这等效于 open(io->read(io, args...), filename)
。
read(s::IO, nb=typemax(Int))
从 s
中最多读取 nb
个字节,返回一个包含已读取字节的 Vector{UInt8}
。
read(s::IOStream, nb::Integer; all=true)
从 s
中最多读取 nb
个字节,返回一个包含已读取字节的 Vector{UInt8}
。
如果 all
为 true
(默认值),则此函数将重复阻塞,尝试读取所有请求的字节,直到发生错误或文件结束。如果 all
为 false
,则最多执行一次 read
调用,并且返回的数据量取决于设备。请注意,并非所有流类型都支持 all
选项。
read(command::Cmd)
运行 command
并将结果输出作为字节数组返回。
read(command::Cmd, String)
运行 command
并将结果输出作为 String
返回。
Base.read!
— 函数read!(stream::IO, array::AbstractArray)
read!(filename::AbstractString, array::AbstractArray)
从 I/O 流或文件中读取二进制数据,填充 array
。
Base.readbytes!
— 函数readbytes!(stream::IO, b::AbstractVector{UInt8}, nb=length(b))
从 stream
中最多读取 nb
个字节到 b
中,返回读取的字节数。如果需要(即,如果 nb
大于 length(b)
并且可以读取足够的字节),b
的大小将增加,但它永远不会减少。
readbytes!(stream::IOStream, b::AbstractVector{UInt8}, nb=length(b); all::Bool=true)
从 stream
中最多读取 nb
个字节到 b
中,返回读取的字节数。如果需要(即,如果 nb
大于 length(b)
并且可以读取足够的字节),b
的大小将增加,但它永远不会减少。
如果 all
为 true
(默认值),则此函数将重复阻塞,尝试读取所有请求的字节,直到发生错误或文件结束。如果 all
为 false
,则最多执行一次 read
调用,并且返回的数据量取决于设备。请注意,并非所有流类型都支持 all
选项。
Base.unsafe_read
— 函数unsafe_read(io::IO, ref, nbytes::UInt)
将 nbytes
从 IO
流对象复制到 ref
(转换为指针)。
建议子类型 T<:IO
覆盖以下方法签名,以提供更有效的实现:unsafe_read(s::T, p::Ptr{UInt8}, n::UInt)
Base.unsafe_write
— 函数unsafe_write(io::IO, ref, nbytes::UInt)
将 nbytes
从 ref
(转换为指针)复制到 IO
对象中。
建议子类型 T<:IO
覆盖以下方法签名,以提供更有效的实现:unsafe_write(s::T, p::Ptr{UInt8}, n::UInt)
Base.readeach
— 函数readeach(io::IO, T)
返回一个可迭代对象,生成 read(io, T)
。
另请参阅 skipchars
,eachline
,readuntil
。
readeach
需要 Julia 1.6 或更高版本。
示例
julia> io = IOBuffer("JuliaLang is a GitHub organization.\n It has many members.\n");
julia> for c in readeach(io, Char)
c == '\n' && break
print(c)
end
JuliaLang is a GitHub organization.
Base.peek
— 函数peek(stream[, T=UInt8])
从流中读取并返回一个类型为 T
的值,而不推进流中的当前位置。另请参阅 startswith(stream, char_or_string)
。
示例
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)
接受类型的方法需要 Julia 1.5 或更高版本。
Base.position
— 函数position(l::Lexer)
返回当前位置。
position(s)
获取流的当前位置。
示例
julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> seek(io, 5);
julia> position(io)
5
julia> skip(io, 10);
julia> position(io)
15
julia> seekend(io);
julia> position(io)
35
Base.seek
— 函数seek(s, pos)
将流定位到给定位置。
示例
julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> seek(io, 5);
julia> read(io, Char)
'L': ASCII/Unicode U+004C (category Lu: Letter, uppercase)
Base.seekstart
— 函数seekstart(s)
将流定位到其开头。
示例
julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> seek(io, 5);
julia> read(io, Char)
'L': ASCII/Unicode U+004C (category Lu: Letter, uppercase)
julia> seekstart(io);
julia> read(io, Char)
'J': ASCII/Unicode U+004A (category Lu: Letter, uppercase)
Base.seekend
— 函数seekend(s)
将流定位到其末尾。
Base.skip
— 函数skip(s, offset)
相对于当前位置定位流。
示例
julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> seek(io, 5);
julia> skip(io, 10);
julia> read(io, Char)
'G': ASCII/Unicode U+0047 (category Lu: Letter, uppercase)
Base.mark
— 函数Base.unmark
— 函数Base.reset
— 方法Base.ismarked
— 函数Base.eof
— 函数eof(stream) -> Bool
测试 I/O 流是否处于文件结束状态。如果流尚未耗尽,则此函数将阻塞以等待更多数据(如果需要),然后返回 false
。因此,在看到 eof
返回 false
后,始终可以安全地读取一个字节。只要缓冲的数据可用,即使连接的远程端已关闭,eof
也将返回 false
。
示例
julia> b = IOBuffer("my buffer");
julia> eof(b)
false
julia> seekend(b);
julia> eof(b)
true
Base.isreadonly
— 函数isreadonly(io) -> Bool
确定流是否为只读。
示例
julia> io = IOBuffer("JuliaLang is a GitHub organization");
julia> isreadonly(io)
true
julia> io = IOBuffer();
julia> isreadonly(io)
false
Base.iswritable
— 函数iswritable(io) -> Bool
如果指定的 IO 对象不可写,则返回 false
。
示例
julia> open("myfile.txt", "w") do io
print(io, "Hello world!");
iswritable(io)
end
true
julia> open("myfile.txt", "r") do io
iswritable(io)
end
false
julia> rm("myfile.txt")
Base.isreadable
— 函数isreadable(io) -> Bool
如果指定的 IO 对象不可读,则返回 false
。
示例
julia> open("myfile.txt", "w") do io
print(io, "Hello world!");
isreadable(io)
end
false
julia> open("myfile.txt", "r") do io
isreadable(io)
end
true
julia> rm("myfile.txt")
Base.isopen
— 函数isopen(object) -> Bool
确定对象(例如流或计时器)是否尚未关闭。对象关闭后,将永远不会产生新的事件。但是,由于已关闭的流在其缓冲区中可能仍有数据可读,因此使用 eof
检查是否可以读取数据。使用 FileWatching
包来接收流可能可写或可读的通知。
示例
julia> io = open("my_file.txt", "w+");
julia> isopen(io)
true
julia> close(io)
julia> isopen(io)
false
Base.fd
— 函数fd(stream)
返回支持流或文件的 文件描述符。请注意,此函数仅适用于同步 File
和 IOStream
,而不适用于任何异步流。
Base.redirect_stdio
— 函数redirect_stdio(;stdin=stdin, stderr=stderr, stdout=stdout)
重定向流 stdin
、stderr
、stdout
的子集。每个参数必须是 IOStream
、TTY
、Pipe
、套接字或 devnull
。
redirect_stdio
需要 Julia 1.7 或更高版本。
redirect_stdio(f; stdin=nothing, stderr=nothing, stdout=nothing)
重定向流 stdin
、stderr
、stdout
的子集,调用 f()
并恢复每个流。
每个流的可能值为
nothing
表示不应重定向流。path::AbstractString
将流重定向到path
处的文件。io
是IOStream
、TTY
、Pipe
、套接字或devnull
。
示例
julia> redirect_stdio(stdout="stdout.txt", stderr="stderr.txt") do
print("hello stdout")
print(stderr, "hello stderr")
end
julia> read("stdout.txt", String)
"hello stdout"
julia> read("stderr.txt", String)
"hello stderr"
边缘情况
可以将同一个参数传递给 stdout
和 stderr
julia> redirect_stdio(stdout="log.txt", stderr="log.txt", stdin=devnull) do
...
end
但是不支持将同一个文件的两个不同描述符传递过去。
julia> io1 = open("same/path", "w")
julia> io2 = open("same/path", "w")
julia> redirect_stdio(f, stdout=io1, stderr=io2) # not supported
此外,stdin
参数不能与 stdout
或 stderr
相同。
julia> io = open(...)
julia> redirect_stdio(f, stdout=io, stdin=io) # not supported
redirect_stdio
需要 Julia 1.7 或更高版本。
Base.redirect_stdout
— 函数redirect_stdout([stream]) -> stream
创建一个管道,所有 C 和 Julia 级别 stdout
输出将被重定向到该管道。返回代表管道端的流。现在可以从管道的 rd
端读取写入 stdout
的数据。
stream
必须是兼容的对象,例如 IOStream
、TTY
、Pipe
、套接字或 devnull
。
另请参阅 redirect_stdio
。
Base.redirect_stdout
— 方法Base.redirect_stderr
— 函数redirect_stderr([stream]) -> stream
与 redirect_stdout
相似,但针对 stderr
。
stream
必须是兼容的对象,例如 IOStream
、TTY
、Pipe
、套接字或 devnull
。
另请参阅 redirect_stdio
。
Base.redirect_stderr
— 方法Base.redirect_stdin
— 函数redirect_stdin([stream]) -> stream
与 redirect_stdout
相似,但针对 stdin
。请注意,流的方向相反。
stream
必须是兼容的对象,例如 IOStream
、TTY
、Pipe
、套接字或 devnull
。
另请参阅 redirect_stdio
。
Base.redirect_stdin
— 方法Base.readchomp
— 函数readchomp(x)
将整个 x
读取为字符串,并删除一个尾随换行符(如果有)。等效于 chomp(read(x, String))
。
示例
julia> write("my_file.txt", "JuliaLang is a GitHub organization.\nIt has many members.\n");
julia> readchomp("my_file.txt")
"JuliaLang is a GitHub organization.\nIt has many members."
julia> rm("my_file.txt");
Base.truncate
— 函数truncate(file, n)
将第一个参数给出的文件或缓冲区的大小调整为正好 n
个字节,如果文件或缓冲区增大,则用 '\0' 填充先前未分配的空间。
示例
julia> io = IOBuffer();
julia> write(io, "JuliaLang is a GitHub organization.")
35
julia> truncate(io, 15)
IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=15, maxsize=Inf, ptr=16, mark=-1)
julia> String(take!(io))
"JuliaLang is a "
julia> io = IOBuffer();
julia> write(io, "JuliaLang is a GitHub organization.");
julia> truncate(io, 40);
julia> String(take!(io))
"JuliaLang is a GitHub organization.\0\0\0\0\0"
Base.skipchars
— 函数skipchars(predicate, io::IO; linecomment=nothing)
推进流 io
,以便下一个读取的字符将是第一个剩余的字符,对于该字符,predicate
返回 false
。如果指定了关键字参数 linecomment
,则从该字符到下一行开头的所有字符都将被忽略。
示例
julia> buf = IOBuffer(" text")
IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=8, maxsize=Inf, ptr=1, mark=-1)
julia> skipchars(isspace, buf)
IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=8, maxsize=Inf, ptr=5, mark=-1)
julia> String(readavailable(buf))
"text"
Base.countlines
— 函数countlines(io::IO; eol::AbstractChar = '\n')
countlines(filename::AbstractString; eol::AbstractChar = '\n')
读取 io
直到流/文件的末尾,并计算行数。要指定文件,请将文件名作为第一个参数传递。除了 '\n'
之外的 EOL 标记通过作为第二个参数传递来支持。io
的最后一个非空行将被计数,即使它没有以 EOL 结尾,这与 eachline
和 readlines
返回的长度匹配。
要计算 String
的行数,可以使用 countlines(IOBuffer(str))
。
示例
julia> io = IOBuffer("JuliaLang is a GitHub organization.\n");
julia> countlines(io)
1
julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> countlines(io)
1
julia> eof(io) # counting lines moves the file pointer
true
julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> countlines(io, eol = '.')
1
julia> write("my_file.txt", "JuliaLang is a GitHub organization.\n")
36
julia> countlines("my_file.txt")
1
julia> countlines("my_file.txt", eol = 'n')
4
julia> rm("my_file.txt")
Base.PipeBuffer
— 函数PipeBuffer(data::Vector{UInt8}=UInt8[]; maxsize::Integer = typemax(Int))
一个 IOBuffer
,它允许读取并通过追加执行写入。不支持查找和截断。有关可用构造函数,请参阅 IOBuffer
。如果给定了 data
,则创建一个 PipeBuffer
以对数据向量进行操作,可以选择指定一个大小,超过该大小,底层 Array
就不能再增长了。
Base.readavailable
— 函数readavailable(stream)
从流中读取可用的缓冲数据。只有在没有数据被缓冲的情况下才会执行实际的 I/O 操作。结果是一个 Vector{UInt8}
。
返回的数据量取决于实现;例如,它可以取决于内部缓冲区大小的选择。其他函数,如 read
,通常应该使用。
Base.IOContext
— 类型IOContext
IOContext
提供了一种机制,用于在 show
方法之间传递输出配置设置。
简而言之,它是一个不可变字典,是 IO
的子类。它支持标准字典操作,如 getindex
,并且也可以用作 I/O 流。
Base.IOContext
— 方法IOContext(io::IO, KV::Pair...)
创建一个包含给定流的 IOContext
,将指定的 key=>value
对添加到该流的属性中(注意,io
本身可以是 IOContext
)。
- 使用
(key => value) in io
查看此特定组合是否在属性集中 - 使用
get(io, key, default)
获取特定键的最新值
以下属性是常用的
:compact
:布尔值,指定是否应以更紧凑的方式打印值,例如,数字应使用较少的位数打印。当打印数组元素时,会设置此属性。:compact
输出不应包含换行符。:limit
:布尔值,指定容器是否应该被截断,例如,在大多数元素的位置显示…
。:displaysize
:一个Tuple{Int,Int}
,给出用于文本输出的行和列的大小。这可用于覆盖被调用函数的显示大小,但要获取屏幕的大小,请使用displaysize
函数。:typeinfo
:一个Type
,表征已打印的关于即将显示的对象类型的的信息。这主要在显示相同类型的对象集合时有用,以便避免冗余的类型信息(例如,[Float16(0)]
可以显示为 "Float16[0.0]" 而不是 "Float16[Float16(0.0)]":在显示数组元素时,:typeinfo
属性将被设置为Float16
)。:color
:布尔值,指定是否支持/期望 ANSI 颜色/转义代码。默认情况下,这取决于io
是否是兼容的终端,以及启动julia
时是否存在任何--color
命令行标志。
示例
julia> io = IOBuffer();
julia> printstyled(IOContext(io, :color => true), "string", color=:red)
julia> String(take!(io))
"\e[31mstring\e[39m"
julia> printstyled(io, "string", color=:red)
julia> String(take!(io))
"string"
julia> print(IOContext(stdout, :compact => false), 1.12341234)
1.12341234
julia> print(IOContext(stdout, :compact => true), 1.12341234)
1.12341
julia> function f(io::IO)
if get(io, :short, false)
print(io, "short")
else
print(io, "loooooong")
end
end
f (generic function with 1 method)
julia> f(stdout)
loooooong
julia> f(IOContext(stdout, :short => true))
short
Base.IOContext
— 方法IOContext(io::IO, context::IOContext)
创建一个包含备用 IO
的 IOContext
,但继承 context
的属性。
文本 I/O
Base.show
— 方法show([io::IO = stdout], x)
将值 x
的文本表示形式写入输出流 io
。新类型 T
应该重载 show(io::IO, x::T)
。show
使用的表示形式通常包括特定于 Julia 的格式和类型信息,并且应尽可能地是可解析的 Julia 代码。
repr
返回 show
的输出作为字符串。
对于类型为 T
的对象的更详细的人类可读文本输出,请另外定义 show(io::IO, ::MIME"text/plain", ::T)
。建议在这些方法中检查 io
的 :compact
IOContext
键(通常检查为 get(io, :compact, false)::Bool
),因为某些容器通过使用 :compact => true
调用此方法来显示其元素。
另请参阅 print
,它写入未修饰的表示形式。
示例
julia> show("Hello World!")
"Hello World!"
julia> print("Hello World!")
Hello World!
Base.summary
— 函数summary(io::IO, x)
str = summary(x)
打印到流 io
,或返回一个字符串 str
,给出值的简短描述。默认情况下返回 string(typeof(x))
,例如 Int64
.
对于数组,返回一个包含大小和类型信息的字符串,例如 10-element Array{Int64,1}
。
示例
julia> summary(1)
"Int64"
julia> summary(zeros(2))
"2-element Vector{Float64}"
Base.print
— 函数print([io::IO], xs...)
将规范(未修饰)文本表示形式写入 io
(如果未提供 io
,则写入默认输出流 stdout
)。print
使用的表示形式包含最少的格式,并尝试避免特定于 Julia 的细节。
print
回退到调用 show
,因此大多数类型只需定义 show
即可。如果你的类型具有单独的“普通”表示形式,请定义 print
。例如,show
使用引号显示字符串,而 print
使用不带引号的字符串显示字符串。
另请参阅 println
、string
、printstyled
.
示例
julia> print("Hello World!")
Hello World!
julia> io = IOBuffer();
julia> print(io, "Hello", ' ', :World!)
julia> String(take!(io))
"Hello World!"
Base.println
— 函数println([io::IO], xs...)
使用 print
打印 xs
到 io
,并在其后跟一个换行符。如果未提供 io
,则打印到默认输出流 stdout
.
另请参阅 printstyled
以添加颜色等。
示例
julia> println("Hello, world")
Hello, world
julia> io = IOBuffer();
julia> println(io, "Hello", ',', " world.")
julia> String(take!(io))
"Hello, world.\n"
Base.printstyled
— 函数printstyled([io], xs...; bold::Bool=false, italic::Bool=false, underline::Bool=false, blink::Bool=false, reverse::Bool=false, hidden::Bool=false, color::Union{Symbol,Int}=:normal)
以符号或整数指定的颜色打印 xs
,可选地以粗体形式打印。
关键字 color
可以取以下任意值::normal
、:italic
、:default
、:bold
、:black
、:blink
、:blue
、:cyan
、:green
、:hidden
、:light_black
、:light_blue
、:light_cyan
、:light_green
、:light_magenta
、:light_red
、:light_white
、:light_yellow
、:magenta
、:nothing
、:red
、:reverse
、:underline
、:white
或 :yellow
,或者介于 0 和 255 之间的整数(含)。请注意,并非所有终端都支持 256 色。
关键字 bold=true
、italic=true
、underline=true
、blink=true
的含义不言自明。关键字 reverse=true
使用交换的前景色和背景色打印,而 hidden=true
在终端中应该是不可见的,但仍然可以复制。这些属性可以以任何组合使用。
并非所有终端都支持斜体输出。某些终端将斜体解释为反转或闪烁。
除了 color
和 bold
之外的关键字是在 Julia 1.7 中添加的。
对斜体输出的支持是在 Julia 1.10 中添加的。
Base.sprint
— 函数sprint(f::Function, args...; context=nothing, sizehint=0)
使用给定的 I/O 流和提供的额外参数调用给定函数。写入此 I/O 流的所有内容都将作为字符串返回。context
可以是 IOContext
,其属性将被使用,一个 Pair
,指定属性及其值,或者一个 Pair
元组,指定多个属性及其值。sizehint
建议缓冲区(以字节为单位)的容量。
可选的关键字参数 context
可以设置为 :key=>value
对,:key=>value
对的元组,或者 IO
或 IOContext
对象,其属性用于传递给 f
的 I/O 流。可选的 sizehint
是一个建议的大小(以字节为单位),用于分配用于写入字符串的缓冲区。
将元组传递给关键字 context
需要 Julia 1.7 或更高版本。
示例
julia> sprint(show, 66.66666; context=:compact => true)
"66.6667"
julia> sprint(showerror, BoundsError([1], 100))
"BoundsError: attempt to access 1-element Vector{Int64} at index [100]"
Base.showerror
— 函数showerror(io, e)
显示异常对象 e
的描述性表示形式。此方法用于在调用 throw
后显示异常。
示例
julia> struct MyException <: Exception
msg::String
end
julia> function Base.showerror(io::IO, err::MyException)
print(io, "MyException: ")
print(io, err.msg)
end
julia> err = MyException("test exception")
MyException("test exception")
julia> sprint(showerror, err)
"MyException: test exception"
julia> throw(MyException("test exception"))
ERROR: MyException: test exception
Base.dump
— 函数dump(x; maxdepth=8)
显示值的表示形式的每个部分。输出的深度在 maxdepth
处被截断。
示例
julia> struct MyStruct
x
y
end
julia> x = MyStruct(1, (2,3));
julia> dump(x)
MyStruct
x: Int64 1
y: Tuple{Int64, Int64}
1: Int64 2
2: Int64 3
julia> dump(x; maxdepth = 1)
MyStruct
x: Int64 1
y: Tuple{Int64, Int64}
Base.Meta.@dump
— 宏@dump expr
显示给定表达式的表示形式的每个部分。等效于 dump(:(expr))
.
Base.readline
— 函数readline(io::IO=stdin; keep::Bool=false)
readline(filename::AbstractString; keep::Bool=false)
从给定的 I/O 流或文件(默认为 stdin
)中读取一行文本。当从文件中读取时,文本被假定为以 UTF-8 编码。输入中的行以 '\n'
或 "\r\n"
或输入流的结尾结束。当 keep
为假(默认情况下为假)时,这些尾随换行符将在返回行之前从行中删除。当 keep
为真时,它们将作为行的一部分返回。
示例
julia> write("my_file.txt", "JuliaLang is a GitHub organization.\nIt has many members.\n");
julia> readline("my_file.txt")
"JuliaLang is a GitHub organization."
julia> readline("my_file.txt", keep=true)
"JuliaLang is a GitHub organization.\n"
julia> rm("my_file.txt")
julia> print("Enter your name: ")
Enter your name:
julia> your_name = readline()
Logan
"Logan"
Base.readuntil
— 函数readuntil(stream::IO, delim; keep::Bool = false)
readuntil(filename::AbstractString, delim; keep::Bool = false)
从 I/O 流或文件中读取字符串,直到给定的分隔符。分隔符可以是 UInt8
、AbstractChar
、字符串或向量。关键字参数 keep
控制分隔符是否包含在结果中。文本被假定为以 UTF-8 编码。
示例
julia> write("my_file.txt", "JuliaLang is a GitHub organization.\nIt has many members.\n");
julia> readuntil("my_file.txt", 'L')
"Julia"
julia> readuntil("my_file.txt", '.', keep = true)
"JuliaLang is a GitHub organization."
julia> rm("my_file.txt")
Base.readlines
— 函数readlines(io::IO=stdin; keep::Bool=false)
readlines(filename::AbstractString; keep::Bool=false)
将 I/O 流或文件的全部行作为字符串向量读取。行为等同于保存使用相同参数重复读取 readline
的结果,并将结果行保存为字符串向量。另请参阅 eachline
以在不一次读取所有行的情况下迭代行。
示例
julia> write("my_file.txt", "JuliaLang is a GitHub organization.\nIt has many members.\n");
julia> readlines("my_file.txt")
2-element Vector{String}:
"JuliaLang is a GitHub organization."
"It has many members."
julia> readlines("my_file.txt", keep=true)
2-element Vector{String}:
"JuliaLang is a GitHub organization.\n"
"It has many members.\n"
julia> rm("my_file.txt")
Base.eachline
— 函数eachline(io::IO=stdin; keep::Bool=false)
eachline(filename::AbstractString; keep::Bool=false)
创建一个可迭代的 EachLine
对象,该对象将从 I/O 流或文件中生成每一行。迭代会对流参数重复调用 readline
,并将 keep
传递过去,以确定是否保留尾随换行符。当使用文件名调用时,文件将在迭代开始时打开并在结束时关闭。如果迭代被中断,则该文件将在 EachLine
对象被垃圾回收时关闭。
要迭代 String
中的每一行,可以使用 eachline(IOBuffer(str))
。
Iterators.reverse
可以用于 EachLine
对象以反向顺序读取行(对于支持 seek
的文件、缓冲区和其他 I/O 流),而 first
或 last
可用于分别提取初始行或最后一行。
示例
julia> write("my_file.txt", "JuliaLang is a GitHub organization.\n It has many members.\n");
julia> for line in eachline("my_file.txt")
print(line)
end
JuliaLang is a GitHub organization. It has many members.
julia> rm("my_file.txt");
Julia 1.8 是使用 Iterators.reverse
或 last
与 eachline
迭代器所需的。
Base.displaysize
— 函数displaysize([io::IO]) -> (lines, columns)
返回可用于将输出呈现到此 IO
对象的屏幕的名义大小。如果没有提供输入,则读取环境变量 LINES
和 COLUMNS
。如果未设置这些变量,则返回默认大小 (24, 80)
。
示例
julia> withenv("LINES" => 30, "COLUMNS" => 100) do
displaysize()
end
(30, 100)
要获取你的 TTY 大小,
julia> displaysize(stdout)
(34, 147)
多媒体 I/O
就像文本输出是由 print
执行的,并且用户定义的类型可以通过重载 show
来指示其文本表示形式一样,Julia 提供了一种标准化机制来实现丰富的多媒体输出(如图像、格式化文本,甚至音频和视频),它由三部分组成
- 函数
display(x)
用于请求 Julia 对象x
的最丰富可用多媒体显示(使用纯文本作为备用)。 - 重载
show
允许用户为用户定义的类型指定任意多媒体表示(通过标准 MIME 类型进行索引)。 - 支持多媒体显示的后端可以通过继承泛型
AbstractDisplay
类型并通过pushdisplay
将它们推入显示后端栈来注册。
Julia 运行时基础只提供纯文本显示,但可以通过加载外部模块或使用图形化 Julia 环境(如基于 IPython 的 IJulia 笔记本)来启用更丰富的显示。
Base.Multimedia.AbstractDisplay
— 类型AbstractDisplay
丰富显示输出设备的抽象超类型。 TextDisplay
是它的子类型。
Base.Multimedia.display
— 函数display(x)
display(d::AbstractDisplay, x)
display(mime, x)
display(d::AbstractDisplay, mime, x)
使用显示栈中最顶层的适用显示来显示 x
,通常使用 x
支持的最丰富的多媒体输出,使用纯文本 stdout
输出作为备用。display(d, x)
变体尝试仅在给定的显示 d
上显示 x
,如果 d
无法显示此类型的对象,则抛出 MethodError
。
通常,您不能假设 display
输出会进入 stdout
(不像 print(x)
或 show(x)
)。例如,display(x)
可能会打开一个带有图像的单独窗口。display(x)
表示“以您当前输出设备所能提供的最佳方式显示 x
”。如果您想要保证进入 stdout
的类似 REPL 的文本输出,请改用 show(stdout, "text/plain", x)
。
还有两个带有 mime
参数(MIME 类型字符串,如 "image/png"
)的变体,它们尝试仅使用请求的 MIME 类型来显示 x
,如果显示或 x
不支持此类型,则抛出 MethodError
。使用这些变体,还可以通过传递 x::AbstractString
(对于具有基于文本存储的 MIME 类型,如 text/html 或 application/postscript)或 x::Vector{UInt8}
(对于二进制 MIME 类型)来提供请求的 MIME 类型的“原始”数据。
Base.Multimedia.redisplay
— 函数redisplay(x)
redisplay(d::AbstractDisplay, x)
redisplay(mime, x)
redisplay(d::AbstractDisplay, mime, x)
默认情况下,redisplay
函数只是调用 display
。但是,一些显示后端可能会覆盖 redisplay
以修改 x
的现有显示(如果有)。使用 redisplay
也是对后端的一个提示,表明 x
可能会被多次重新显示,后端可以选择将显示推迟到(例如)下一个交互式提示。
Base.Multimedia.displayable
— 函数displayable(mime) -> Bool
displayable(d::AbstractDisplay, mime) -> Bool
返回一个布尔值,指示给定的 mime
类型(字符串)是否可由当前显示栈中的任何显示显示,或更具体地说,是否可由第二个变体中的显示 d
显示。
Base.show
— 方法show(io::IO, mime, x)
display
函数最终调用 show
,以便将对象 x
作为给定的 mime
类型写入给定的 I/O 流 io
(通常是内存缓冲区),如果可能。为了提供用户定义类型 T
的丰富多媒体表示,只需通过以下方式为 T
定义一个新的 show
方法:show(io, ::MIME"mime", x::T) = ...
,其中 mime
是一个 MIME 类型字符串,函数体调用 write
(或类似的函数)将 x
的该表示写入 io
。(请注意,MIME""
表示法仅支持文字字符串;要以更灵活的方式构造 MIME
类型,请使用 MIME{Symbol("")}
。)
例如,如果您定义了一个 MyImage
类型,并且知道如何将其写入 PNG 文件,您就可以定义一个函数 show(io, ::MIME"image/png", x::MyImage) = ...
,以允许您的图像在任何支持 PNG 的 AbstractDisplay
(如 IJulia)上显示。与往常一样,请确保 import Base.show
,以便为 Julia 内置函数 show
添加新方法。
从技术上讲,MIME"mime"
宏为给定的 mime
字符串定义了一个单例类型,这使得我们能够利用 Julia 的调度机制来确定如何显示任何给定类型的对象。
默认 MIME 类型为 MIME"text/plain"
。对于 text/plain
输出,有一个回退定义会调用具有 2 个参数的 show
,因此并非总是需要为这种情况添加方法。但是,如果类型受益于自定义人类可读输出,则应定义 show(::IO, ::MIME"text/plain", ::T)
。例如,Day
类型使用 1 day
作为 text/plain
MIME 类型的输出,并使用 Day(1)
作为 2 参数 show
的输出。
示例
julia> struct Day
n::Int
end
julia> Base.show(io::IO, ::MIME"text/plain", d::Day) = print(io, d.n, " day")
julia> Day(1)
1 day
容器类型通常通过对元素 x
调用 show(io, MIME"text/plain"(), x)
来实现 3 参数 show
,其中 :compact => true
设置在作为第一个参数传递的 IOContext
中。
Base.Multimedia.showable
— 函数showable(mime, x)
返回一个布尔值,指示对象 x
是否可以作为给定的 mime
类型写入。
(默认情况下,这是通过 typeof(x)
的相应 show
方法是否存在来自动确定的。有些类型提供自定义的 showable
方法;例如,如果可用的 MIME 格式取决于 x
的值。)
示例
julia> showable(MIME("text/plain"), rand(5))
true
julia> showable("image/png", rand(5))
false
Base.repr
— 方法repr(mime, x; context=nothing)
返回一个 AbstractString
或 Vector{UInt8}
,其中包含 x
在请求的 mime
类型中的表示,如由 show(io, mime, x)
写入(如果找不到合适的 show
,则抛出 MethodError
)。对于具有文本表示的 MIME 类型(如 "text/html"
或 "application/postscript"
),返回一个 AbstractString
,而二进制数据则作为 Vector{UInt8}
返回。(函数 istextmime(mime)
返回 Julia 是否将给定的 mime
类型视为文本。)
可选的关键字参数 context
可以设置为 :key=>value
对或 IO
或 IOContext
对象,其属性用于传递给 show
的 I/O 流。
作为一种特殊情况,如果 x
是 AbstractString
(对于文本 MIME 类型)或 Vector{UInt8}
(对于二进制 MIME 类型),repr
函数假设 x
已经处于请求的 mime
格式,并只返回 x
。此特殊情况不适用于 "text/plain"
MIME 类型。这很有用,因为可以将原始数据传递给 display(m::MIME, x)
。
特别是,repr("text/plain", x)
通常是 x
的“漂亮打印”版本,旨在供人类阅读。另请参见 repr(x)
,以返回与 show(x)
相对应的字符串,该字符串可能更接近在 Julia 中输入 x
的值的方式。
示例
julia> A = [1 2; 3 4];
julia> repr("text/plain", A)
"2×2 Matrix{Int64}:\n 1 2\n 3 4"
Base.Multimedia.MIME
— 类型MIME
表示标准互联网数据格式的类型。“MIME”代表“多用途互联网邮件扩展”,因为该标准最初用于描述电子邮件的附件。
MIME
对象可以作为第二个参数传递给 show
,以请求该格式的输出。
示例
julia> show(stdout, MIME("text/plain"), "hi")
"hi"
Base.Multimedia.@MIME_str
— 宏@MIME_str
用于编写 MIME
类型的便利宏,通常在为 show
添加方法时使用。例如,语法 show(io::IO, ::MIME"text/html", x::MyType) = ...
可以用来定义如何写入 MyType
的 HTML 表示。
如上所述,您还可以定义新的显示后端。例如,可以显示窗口中 PNG 图像的模块可以将此功能注册到 Julia,以便在对具有 PNG 表示的类型调用 display(x)
时,将自动使用模块的窗口显示图像。
为了定义新的显示后端,首先应该创建一个抽象类 AbstractDisplay
的子类型 D
。然后,对于可以在 D
上显示的每个 MIME 类型(mime
字符串),应该定义一个函数 display(d::D, ::MIME"mime", x) = ...
,该函数将 x
显示为该 MIME 类型,通常通过调用 show(io, mime, x)
或 repr(io, mime, x)
。如果 x
不能作为该 MIME 类型显示,则应该抛出 MethodError
;如果调用 show
或 repr
,这是自动的。最后,应该定义一个函数 display(d::D, x)
,该函数查询 showable(mime, x)
以获取 D
支持的 mime
类型,并显示“最佳”类型;如果找不到 x
的任何支持的 MIME 类型,则应该抛出 MethodError
。类似地,一些子类型可能希望覆盖 redisplay(d::D, ...)
。(同样,应该 import Base.display
以向 display
添加新方法。)这些函数的返回值取决于实现(因为在某些情况下,返回某种类型的显示“句柄”可能很有用)。D
的显示函数可以直接调用,但也可以通过以下方式从 display(x)
自动调用:
Base.Multimedia.pushdisplay
— 函数pushdisplay(d::AbstractDisplay)
将新的显示 d
推入全局显示后端栈的顶部。调用 display(x)
或 display(mime, x)
将在栈中与 x
最匹配的后端上显示 x
(即,不抛出 MethodError
的最顶层后端)。
Base.Multimedia.popdisplay
— 函数popdisplay()
popdisplay(d::AbstractDisplay)
将最顶层后端从显示后端栈中弹出,或弹出第二个变体中的 d
的最顶层副本。
Base.Multimedia.TextDisplay
— 类型TextDisplay(io::IO)
返回一个 TextDisplay <: AbstractDisplay
,它以文本/普通 MIME 类型(默认)显示任何对象,并将文本表示写入给定的 I/O 流。(这是在 Julia REPL 中打印对象的方式。)
Base.Multimedia.istextmime
— 函数istextmime(m::MIME)
确定 MIME 类型是否为文本数据。假设 MIME 类型为二进制数据,除非是一组已知为文本数据(可能是 Unicode)的类型。
示例
julia> istextmime(MIME("text/plain"))
true
julia> istextmime(MIME("image/png"))
false
网络 I/O
Base.bytesavailable
— 函数bytesavailable(io)
返回在从此流或缓冲区读取之前可用于读取的字节数,以防止读取阻塞。
示例
julia> io = IOBuffer("JuliaLang is a GitHub organization");
julia> bytesavailable(io)
34
Base.ntoh
— 函数ntoh(x)
将值的字节序从网络字节序(大端)转换为主机使用的字节序。
Base.hton
— 函数hton(x)
将值的字节序从主机使用的字节序转换为网络字节序(大端)。
Base.ltoh
— 函数ltoh(x)
将值的字节序从小端转换为主机使用的字节序。
Base.htol
— 函数htol(x)
将值的字节序从主机使用的字节序转换为小端。
Base.ENDIAN_BOM
— 常量ENDIAN_BOM
32 位字节序标记指示主机机器的本机字节序。小端机器将包含值 0x04030201
。大端机器将包含值 0x01020304
。