Ввод-вывод и сеть

Общий ввод-вывод

# Base.stdout — Constant

stdout::IO

Глобальная переменная, которая ссылается на стандартный выходной поток.

# Base.stderr — Constant

stderr::IO

Глобальная переменная, которая ссылается на стандартный поток ошибок.

# Base.stdin — Constant

stdin::IO

Глобальная переменная, которая ссылается на стандартный входной поток.

# Base.read — Method

read(filename::AbstractString)

Считывает все содержимое файла как Vector{UInt8}.

read(filename::AbstractString, String)

Считывает все содержимое файла как строку.

read(filename::AbstractString, args...)

Открывает файл и считывает его содержимое. args передается в read: это эквивалентно open(io->read(io, args...), filename).

# Base.write — Method

write(filename::AbstractString, content)

Записывает каноническое двоичное представление content в файл, который будет создан, если он еще не существует, или перезаписан в противном случае.

Возвращает количество байтов, записанных в файл.

# Base.open — Function

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`

read

открыть для чтения

!write

write

открыть для записи

truncate | append

create

создать, если не существует

!read & write | truncate | append

truncate

обрезать до нулевого размера

!read & write

append

выполнять поиск до конца

false

По умолчанию, если ключевые слова не передаются, файлы будут открыты только для чтения. Возвращается поток для доступа к открытому файлу.

Именованный аргумент lock определяет, будут ли операции заблокированы для безопасного многопотокового доступа.

Совместимость: Julia 1.5

Аргумент lock впервые реализован в Julia 1.5.

open(filename::AbstractString, [mode::AbstractString]; lock = true) -> IOStream

Альтернативный синтаксис открытия, в котором вместо пяти логических аргументов используется описатель режима, основанного на операциях со строками. Значения mode соответствуют значениям из fopen(3) или Perl open и эквивалентны настройке следующих логических групп:

Режим Описание Именованные аргументы

Режим	Описание	Именованные аргументы
`r`	чтение	нет
`w`	чтение, создание, обрезка	`write = true`
`a`	чтение, создание, присоединение	`append = true`
`r+`	чтение, запись	`read = true, write = true`
`w+`	чтение, запись, создание, обрезка	`truncate = true, read = true`
`a+`	чтение, запись, создание, присоединение	`append = true, read = true`

r

чтение

нет

w

чтение, создание, обрезка

write = true

a

чтение, создание, присоединение

append = true

r+

чтение, запись

read = true, write = true

w+

чтение, запись, создание, обрезка

truncate = true, read = true

a+

чтение, запись, создание, присоединение

append = true, read = true

Примеры

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")

Совместимость: Julia 1.5

Аргумент lock впервые реализован в Julia 1.5.

open(fd::OS_HANDLE) -> IO

Инкапсулирует необработанный дескриптор файла в тип ввода-вывода с поддержкой Julia и принимает владение дескриптором файлового устройства. Вызывает open(Libc.dup(fd)), чтобы предотвратить передачу владения исходным дескриптором.

Не вызывайте эту функцию для дескриптора, которым уже владеет другая часть системы.

open(command, mode::AbstractString, stdio=devnull)

Выполняет command в асинхронном режиме. Аналогично open(command, stdio; read, write), за исключением того, что флаги чтения и записи задаются с использованием строки режима вместо именованных аргументов. Возможны следующие строки режима:

Режим Описание Именованные аргументы

Режим	Описание	Именованные аргументы
`r`	чтение	нет
`w`	запись	`write = true`
`r+`	чтение, запись	`read = true, write = true`
`w+`	чтение, запись	`read = true, write = true`

r

чтение

нет

w

запись

write = true

r+

чтение, запись

read = true, write = true

w+

чтение, запись

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 — Type

IOStream

Буферизованный поток ввода-вывода, в который инкапсулирован дескриптор файла ОС. В большинстве случаев используется для представления файлов, возвращаемых open.

# Base.IOBuffer — Type

IOBuffer([data::AbstractVector{UInt8}]; keywords...) -> IOBuffer

Создает поток ввода-вывода в памяти, который может дополнительно выполнять операции с уже существующим массивом.

Возможно, потребуются необязательные именованные аргументы:

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! — Method

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.Pipe — Type

Pipe()

Создает неинициализированный объект Pipe (конвейер), в частности для операций ввода-вывода между несколькими процессами.

Соответствующий конец конвейера будет автоматически инициализирован, если объект используется при порождении процесса. Это может быть полезно для легкого получения ссылок в конвейерах процессов, например:

julia> err = Pipe()

# После этого `err` будет инициализирован и можно будет прочитать поток stderr
# `foo` из конвейера `err` или передать `err` в другие конвейеры.
julia> run(pipeline(pipeline(`foo`, stderr=err), `cat`), wait=false)

# Теперь уничтожим половину конвейера, предназначенную для записи, чтобы половина, предназначенная для чтения, получила EOF
julia> closewrite(err)

julia> read(err, String)
"stderr messages"

См. также описание Base.link_pipe!.

# Base.link_pipe! — Function

link_pipe!(pipe; reader_supports_async=false, writer_supports_async=false)

Инициализирует pipe и связывает конечную точку in с конечной точкой out. Именованные аргументы reader_supports_async и writer_supports_async соответствуют OVERLAPPED в Windows и O_NONBLOCK в системах POSIX. Они должны иметь значение true, если только не будут использоваться внешней программой (например, выводом команды, выполненной с помощью run).

# Base.fdio — Function

fdio([name::AbstractString, ]fd::Integer[, own::Bool=false]) -> IOStream

Создает объект IOStream на основе целочисленного дескриптора файла. Если own имеет значение true, то при закрытии этого объекта также закрывается базовый дескриптор. По умолчанию IOStream закрывается при выполнении сборки мусора. name позволяет связать дескриптор с именованным файлом.

# Base.flush — Function

flush(stream)

Фиксирует все ранее буферизованные операции записи в заданном потоке.

# Base.close — Function

close(stream)

Закрывает поток ввода-вывода. Сначала выполняется flush.

# Base.closewrite — Function

closewrite(stream)

Прекращает запись половины полнодуплексного потока ввода-вывода. Сначала выполняется flush. Уведомляет другую сторону о том, что запись данных в базовый файл больше не выполняется. Эта операция может не поддерживаться для некоторых типов ввода-вывода.

Если реализовано, closewrite приводит к тому, что последующие вызовы read или eof, которые блокировались бы, вместо этого выдают EOF или возвращают true соответственно. Если поток уже закрыт, это идемпотентно.

Примеры

julia> io = Base.BufferStream(); # в этом случае блокировка никогда не выполняется, поэтому операции чтения и записи доступны для той же задачи

julia> write(io, "request");

julia> # при вызове здесь `read(io)` применяется постоянная блокировка

julia> closewrite(io);

julia> read(io, String)
"request"

# Base.write — Function

write(io::IO, x)

Записывает каноническое двоичное представление значения в заданный поток ввода-вывода или файл. Возвращает количество байтов, записанных в поток. См. также описание функции print, которая записывает текстовое представление (в кодировке, зависящей от io).

Порядок следования байтов в записанном значении зависит от порядка следования байтов в хост-системе. В процессе записи или чтения выполняет преобразование в фиксированный порядок следования байтов или из него (например, с помощью htol и ltoh), чтобы результаты были согласованными для различных платформ.

Можно выполнить запись нескольких значений с вызовом одного write, то есть следующие значения являются эквивалентными:

write(io, x, y...)
write(io, x) + write(io, y...)

Примеры

Согласованная сериализация:

julia> fname = tempname(); # произвольное временное имя файла

julia> open(fname,"w") do f
           # Убедиться в том, что выполняется запись 64-разрядного целочисленного значения в формате прямого порядка следования байтов
           write(f,htol(Int64(42)))
       end
8

julia> open(fname,"r") do f
           # Выполнить обратное преобразование в основной порядок следования байтов и основной целочисленный тип
           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."

Определяемые пользователем типы основных данных без методов write можно записать, а затем инкапсулировать в Ref:

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 — Function

read(io::IO, T)

Считывает отдельное значение типа T из io в каноническом двоичном представлении.

Обратите внимание, что 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))

Считывает не более nb байтов из s, возвращая Vector{UInt8} со считанными байтами.

read(s::IOStream, nb::Integer; all=true)

Считывает не более nb байтов из s, возвращая Vector{UInt8} со считанными байтами.

Если all имеет значение true (по умолчанию), эта функция будет постоянно блокироваться при попытке считать все запрашиваемые байты до тех пор, пока не произойдет ошибка или не будет достигнут конец файла. Если all имеет значение false, выполняется не более одного вызова read, и возвращаемый объем данных будет зависеть от устройства. Обратите внимание, что параметр all может не поддерживаться для некоторых типов потока.

read(command::Cmd)

Выполняет command и возвращает результирующий вывод как массив байтов.

read(command::Cmd, String)

Выполняет command и возвращает результирующий вывод как String.

# Base.read! — Function

read!(stream::IO, array::AbstractArray)
read!(filename::AbstractString, array::AbstractArray)

Считывает двоичные данные из потока ввода-вывода или файла, заполняя array.

# Base.readbytes! — Function

readbytes!(stream::IO, b::AbstractVector{UInt8}, nb=length(b))

Считывает не более nb байтов из stream в b, возвращая количество считанных байтов. Размер b увеличивается при необходимости (то есть если nb больше length(b) и удалось считать достаточное количество байтов), но никогда не уменьшается.

readbytes!(stream::IOStream, b::AbstractVector{UInt8}, nb=length(b); all::Bool=true)

# Base.unsafe_read — Function

unsafe_read(io::IO, ref, nbytes::UInt)

Копирует nbytes из объекта потока IO в ref (преобразовывается в указатель).

В подтипах T<:IO рекомендуется переопределять следующую сигнатуру метода, чтобы обеспечить более эффективные реализации: unsafe_read(s::T, p::Ptr{UInt8}, n::UInt).

# Base.unsafe_write — Function

unsafe_write(io::IO, ref, nbytes::UInt)

Копирует nbytes из ref (преобразовывается в указатель) в объект IO.

В подтипах T<:IO рекомендуется переопределять следующую сигнатуру метода, чтобы обеспечить более эффективные реализации: unsafe_write(s::T, p::Ptr{UInt8}, n::UInt).

# Base.readeach — Function

readeach(io::IO, T)

Возвращает итерируемый объект, выдающий read(io, T).

См. также описание skipchars, eachline и readuntil.

Совместимость: Julia 1.6

Для 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 — Function

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

Для метода, принимающего тип, требуется версия Julia не ниже 1.5.

# Base.position — Function

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 — Function

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 — Function

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 — Function

seekend(s)

Выполняет поиск по потоку вплоть до достижения его конца.

# Base.skip — Function

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 — Function

mark(s::IO)

Добавляет метку в текущей позиции потока s. Возвращает позицию с меткой.

См. также описание unmark, reset и ismarked.

# Base.unmark — Function

unmark(s::IO)

Удаляет метку из потока s. Возвращает true, если поток был помечен, в противном случае возвращает false.

См. также описание mark, reset и ismarked.

# Base.reset — Method

reset(s::IO)

Сбрасывает поток s до ранее отмеченной позиции, а затем удаляет метку. Возвращает ранее отмеченную позицию. Если поток не помечен, выдает ошибку.

См. также описание mark, unmark и ismarked.

# Base.ismarked — Function

ismarked(s::IO)

Возвращает true, если поток s помечен.

См. также описание mark, unmark и reset.

# Base.eof — Function

eof(stream) -> Bool

Проверяет, находится ли поток ввода-вывода в конце файла. Если поток еще не исчерпан, эта функция блокируется, ожидая дополнительных данных (при необходимости), а затем возвращает false. Поэтому всегда безопасно считывать по одному байту после того, как eof возвращает false. eof будет возвращать false, пока доступны буферизованные данные, даже если удаленный конец соединения закрыт.

Примеры

julia> b = IOBuffer("my buffer");

julia> eof(b)
false

julia> seekend(b);

julia> eof(b)
true

# Base.isreadonly — Function

isreadonly(io) -> Bool

Определяет, имеет ли поток свойство «только чтение».

Примеры

julia> io = IOBuffer("JuliaLang is a GitHub organization");

julia> isreadonly(io)
true

julia> io = IOBuffer();

julia> isreadonly(io)
false

# Base.iswritable — Function

iswritable(path::String)

Возвращает значение true, если согласно разрешениям доступа для данного объекта path текущий пользователь может выполнять запись в него.

Это разрешение может измениться до того, как пользователь вызовет open, поэтому рекомендуется вызвать open отдельно и в случае сбоя обработать ошибку вместо того, чтобы сначала вызывать iswritable.

В настоящее время эта функция некорректно опрашивает ACL файловой системы Windows, поэтому может возвращать неверные результаты.

Совместимость: Julia 1.11

Для этой функции требуется версия Julia не ниже 1.11.

См. также описание ispath, isexecutable и isreadable.

iswritable(io) -> Bool

Возвращает 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 — Function

isreadable(path::String)

Возвращает значение true, если согласно разрешениям доступа для данного объекта path текущий пользователь может выполнять чтение из него.

Совместимость: Julia 1.11

Для этой функции требуется версия Julia не ниже 1.11.

См. также описание ispath, isexecutable и iswritable.

isreadable(io) -> Bool

Возвращает 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.isexecutable — Function

isexecutable(path::String)

Возвращает true, если заданный path имеет разрешения исполняемого файла.

Это разрешение может измениться до того, как пользователь выполнит path, поэтому рекомендуется выполнить файл и в случае сбоя обработать ошибку вместо того, чтобы сначала вызывать isexecutable.

До Julia 1.6 опрос ACL файловой системы Windows производился некорректно, поэтому для любого файла возвращалось значение true. Начиная с версии Julia 1.6 функция правильно определяет, помечен ли файл как исполняемый.

См. также описание ispath, isreadable и iswritable.

# Base.isopen — Function

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 — Function

fd(stream)

Возвращает дескриптор файла, который резервирует поток или файл. Обратите внимание, что эта функция применима только к синхронным File и IOStream, но не к асинхронным потокам.

# Base.redirect_stdio — Function

redirect_stdio(;stdin=stdin, stderr=stderr, stdout=stdout)

Перенаправляет подмножество потоков stdin, stderr, stdout. Каждый аргумент должен быть IOStream, TTY, Pipe, сокетом или devnull.

Совместимость: Julia 1.7

Для 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) # не поддерживается

Кроме того, аргумент stdin может не быть тем же дескриптором, что и stdout или stderr.

julia> io = open(...)

julia> redirect_stdio(f, stdout=io, stdin=io) # не поддерживается

Совместимость: Julia 1.7

Для redirect_stdio требуется версия Julia не ниже 1.7.

# Base.redirect_stdout — Function

redirect_stdout([stream]) -> stream

Создает канал передачи, в который перенаправляется весь вывод stdout уровня С и Julia. Возвращает поток, представляющий концы канала передачи. Данные, записываемые в stdout, нельзя считать из конца rd канала передачи.

stream должны быть совместимыми объектами, например IOStream, TTY, Pipe, сокетом или devnull.

См. также описание redirect_stdio.

# Base.redirect_stdout — Method

redirect_stdout(f::Function, stream)

Выполняет функцию f при перенаправлении stdout в stream. По завершении будут восстановлены исходные параметры stdout.

# Base.redirect_stderr — Function

redirect_stderr([stream]) -> stream

Аналогично redirect_stdout, но для stderr.

stream должны быть совместимыми объектами, например IOStream, TTY, Pipe, сокетом или devnull.

См. также описание redirect_stdio.

# Base.redirect_stderr — Method

redirect_stderr(f::Function, stream)

Выполняет функцию f при перенаправлении stderr в stream. По завершении будут восстановлены исходные параметры stderr.

# Base.redirect_stdin — Function

redirect_stdin([stream]) -> stream

Аналогично redirect_stdout, но для stdin. Обратите внимание, что направление потока изменяется на обратное.

stream должны быть совместимыми объектами, например IOStream, TTY, Pipe, сокетом или devnull.

См. также описание redirect_stdio.

# Base.redirect_stdin — Method

redirect_stdin(f::Function, stream)

Выполняет функцию f при перенаправлении stdin в stream. По завершении будут восстановлены исходные параметры stdin.

# Base.readchomp — Function

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 — Function

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 — Function

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 — Function

countlines(io::IO; eol::AbstractChar = '\n')
countlines(filename::AbstractString; eol::AbstractChar = '\n')

Считывает io вплоть до конца потока или файла и подсчитывает количество строк. Чтобы указать файл, передайте имя файла как первый аргумент. Маркеры конца строки, отличные от , поддерживаются путем их передачи в виде второго аргумента. Последняя непустая строка в io учитывается, даже если она не заканчивается маркером конца строки, совпадая по длине со значением, возвращаемым 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) # при подсчете строк перемещается указатель файла
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 — Function

PipeBuffer(data::AbstractVector{UInt8}=UInt8[]; maxsize::Integer = typemax(Int))

Объект IOBuffer, который позволяет выполнять чтение и запись путем присоединения. Поиск и обрезка не поддерживаются. См. IOBuffer, где приведено описание доступных конструкторов. Если задан аргумент data, создается PipeBuffer, который выполняет операции с вектором данных, дополнительно указывая размер, свыше которого базовый массив Array нельзя увеличить.

# Base.readavailable — Function

readavailable(stream)

Считывает доступные буферизованные данные из потока. Фактический ввод-вывод выполняется только в том случае, если данные еще не были буферизованы. Результатом является Vector{UInt8}.

Возвращаемый объем данных будет зависеть от реализации; например, он может зависеть от внутреннего выбора размера буфера. Вместо этого обычно следует использовать другие функции, такие как read.

# Base.IOContext — Type

IOContext

IOContext предоставляет механизм для передачи параметров конфигурации вывода между методами show.

Иными словами, это неизменяемый словарь, который является подклассом IO. Он поддерживает стандартные операции со словарями, такие как getindex, и также может использоваться как поток ввода-вывода.

# Base.IOContext — Method

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 совместимым терминалом, а также любым флагом командной строки --color при запуске julia.

Примеры

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 — Method

IOContext(io::IO, context::IOContext)

Создает IOContext, который инкапсулирует альтернативный IO, но при этом наследует свойства context.

Текстовый ввод-вывод

# Base.show — Method

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). В таких методах рекомендуется проверять ключ :compact IOContext (часто проверяется как get(io, :compact, false)::Bool) потока io, поскольку некоторые контейнеры отображают элементы путем вызова этого метода с :compact => true.

См. также описание функции print, которая записывает недекорированные представления.

Примеры

julia> show("Hello World!")
"Hello World!"
julia> print("Hello World!")
Hello World!

# Base.summary — Function

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 — Function

print([io::IO], xs...)

Записывает каноническое (недекорированное) текстовое представление в io (или в выходной поток по умолчанию stdout, если io не задан). Представление, используемое 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 — Function

println([io::IO], xs...)

Выводит xs (используя print) в 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 — Function

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 вывод должен быть невидимым в терминале, но все равно доступным для копирования. Эти свойства можно использовать в любой комбинации.

См. также описание print, println и show.

Не все терминалы поддерживают вывод курсива. Некоторые терминалы интерпретируют курсив как обращение или мигание.

Совместимость: Julia 1.7

Именованные аргументы, за исключением color и bold, были добавлены в Julia 1.7.

Совместимость: Julia 1.10

Поддержка вывода курсива была добавлена в Julia 1.10.

# Base.sprint — Function

sprint(f::Function, args...; context=nothing, sizehint=0)

Вызывает данную функцию с потоком ввода-вывода и предоставленными дополнительными аргументами. Все данные, записанные в этот поток ввода-вывода, возвращаются как строка. context может быть объектом IOContext, свойства которого будут использоваться, объектом Pair, который задает свойство и его значение, или кортежем объектов Pair, которые задают несколько свойств и их значения. sizehint задает предпочтительную емкость буфера (в байтах).

Необязательному именованному аргументу context можно присвоить пару :key=>value, кортеж пар :key=>value или объект IO либо IOContext, атрибуты которого используются для потока ввода-вывода, передаваемого в f. В необязательном аргументе sizehint указывается предпочтительный размер (в байтах), который выделяется для буфера, используемого для записи строки.

Совместимость: Julia 1.7

Для передачи кортежа в именованном аргументе 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 — Function

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 — Function

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 — Macro

@dump expr

Отображает все части представления данного выражения. Эквивалентно dump(:(expr)).

# Base.readline — Function

readline(io::IO=stdin; keep::Bool=false)
readline(filename::AbstractString; keep::Bool=false)

Считывает одну строку текста из заданного потока ввода-вывода или файла (по умолчанию stdin). При чтении из файла предполагается, что для текста используется кодировка UTF-8. Строки во входном конце с или "\r\n" или в конце входного потока. Если keep имеет значение false (по умолчанию), эти конечные символы новой строки удаляются из строки, прежде чем она будет возвращена. Если keep имеет значение true, они возвращаются как часть строки.

Возвращает String. См. также описание функции copyline, которая выполняет запись в другой поток (который может быть предварительно выделенным IOBuffer) на месте.

Кроме того, см. описание функции readuntil для считывания до более общих разделителей.

Примеры

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 — Function

readuntil(stream::IO, delim; keep::Bool = false)
readuntil(filename::AbstractString, delim; keep::Bool = false)

Считывает строку из потока ввода-вывода stream или файла до заданного разделителя. Разделителем может быть UInt8, AbstractChar, строка или вектор. Именованный аргумент keep определяет, включается ли разделитель в результат. Предполагается, что для текста используется кодировка UTF-8.

Возвращает String, если delim является AbstractChar или строкой, в противном случае возвращает Vector{typeof(delim)}. См. также описание функции copyuntil, которая выполняет запись в другой поток (который может быть предварительно выделенным IOBuffer) на месте.

Примеры

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 — Function

readlines(io::IO=stdin; keep::Bool=false)
readlines(filename::AbstractString; keep::Bool=false)

Считывает все строки в потоке ввода-вывода или файле как вектор строковых значений. Поведение аналогично многократному сохранению результата считывания 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 — Function

eachline(io::IO=stdin; keep::Bool=false)
eachline(filename::AbstractString; keep::Bool=false)

Создает итерируемый объект EachLine, который выдает каждую строку из потока ввода-вывода или файла. При итерации многократно вызывается readline для аргумента потока с передачей аргумента keep, который определяет, сохраняются ли конечные символы конца строки. При вызове с именем строки файл открывается однократно в начале итерации и закрывается после ее завершения. Если итерация прерывается, файл будет закрыт при удалении объекта EachLine сборщиком мусора.

Для перебора каждой строки в String можно использовать eachline(IOBuffer(str)).

Iterators.reverse можно использовать для объекта EachLine с целью считывания строк в обратном порядке (для файлов, буферов и других потоков ввода-вывода, поддерживающих seek), а также можно использовать 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

В Julia 1.8 необходимо использовать Iterators.reverse или last с итераторами eachline.

# Base.copyline — Function

copyline(out::IO, io::IO=stdin; keep::Bool=false)
copyline(out::IO, filename::AbstractString; keep::Bool=false)

Копирует одну строку текста из потока ввода-вывода stream или файла в поток out, возвращая out.

При чтении из файла предполагается, что для текста используется кодировка UTF-8. Строки во входном конце с или "\r\n" или в конце входного потока. Если keep имеет значение false (по умолчанию), эти конечные символы новой строки удаляются из строки, прежде чем она будет возвращена. Если keep имеет значение true, они возвращаются как часть строки.

Действует аналогично функции readline, которая возвращает String; однако copyline выполняет запись непосредственно в out, не выделяя память для строки. (Это можно использовать, например, для считывания данных в предварительно выделенный IOBuffer.)

Кроме того, см. описание функции copyuntil для считывания до более общих разделителей.

Примеры

julia> write("my_file.txt", "JuliaLang is a GitHub organization.\nIt has many members.\n");

julia> String(take!(copyline(IOBuffer(), "my_file.txt")))
"JuliaLang is a GitHub organization."

julia> String(take!(copyline(IOBuffer(), "my_file.txt", keep=true)))
"JuliaLang is a GitHub organization.\n"

julia> rm("my_file.txt")

# Base.copyuntil — Function

copyuntil(out::IO, stream::IO, delim; keep::Bool = false)
copyuntil(out::IO, filename::AbstractString, delim; keep::Bool = false)

Копирует строку из потока ввода-вывода stream или файла до указанного разделителя в поток out, возвращая out. Разделителем может быть UInt8, AbstractChar, строка или вектор. Именованный аргумент keep определяет, включается ли разделитель в результат. Предполагается, что для текста используется кодировка UTF-8.

Действует аналогично функции readuntil, которая возвращает String; однако copyuntil выполняет запись непосредственно в out, не выделяя память для строки. (Это можно использовать, например, для считывания данных в предварительно выделенный IOBuffer.)

Примеры

julia> write("my_file.txt", "JuliaLang is a GitHub organization.\nIt has many members.\n");

julia> String(take!(copyuntil(IOBuffer(), "my_file.txt", 'L')))
"Julia"

julia> String(take!(copyuntil(IOBuffer(), "my_file.txt", '.', keep = true)))
"JuliaLang is a GitHub organization."

julia> rm("my_file.txt")

# Base.displaysize — Function

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)

Мультимедийный ввод-вывод

Подобно тому как вывод текста осуществляется с помощью print, а пользовательские типы могут указывать свое текстовое представление путем перегрузки show, Julia предоставляет стандартизированный механизм для вывода разнообразных мультимедийных данных (таких как изображения, форматированный текст или даже аудио и видео), состоящий из трех частей.

Функция display(x) для запроса самого обширного доступного мультимедийного отображения объекта Julia x (с резервным вариантом в виде обычного текста).
Перегрузка show позволяет указывать произвольные мультимедийные представления (с привязкой к стандартным типам MIME) типов, определяемых пользователем.
Бэкенды отображения с поддержкой мультимедиа могут быть зарегистрированы путем подклассификации универсального типа AbstractDisplay и размещения их в стеке бэкендов отображения с помощью pushdisplay.

Базовая среда выполнения Julia обеспечивает только отображение обычного текста, но для более широких возможностей отображения можно загрузить внешние модули или использовать графические среды Julia (например, записную книжку IJulia на базе IPython).

# Base.Multimedia.AbstractDisplay — Type

AbstractDisplay

Абстрактный супертип для устройств с форматированным выводом. TextDisplay является его подтипом.

# Base.Multimedia.display — Function

display(x)
display(d::AbstractDisplay, x)
display(mime, x)
display(d::AbstractDisplay, mime, x)

Отображает x с помощью самого верхнего применимого дисплея в стеке дисплеев, как правило, использующего максимально полный из поддерживаемых мультимедийных выводов для x, с выводом обычного текста stdout в качестве резервного варианта. Вариант display(d, x) пытается отобразить x только на данном дисплее d, выдавая MethodError, если d не поддерживает отображение объектов такого типа.

В целом нельзя предполагать, что вывод display переходит в stdout (в отличие от print(x) или show(x)). Например, display(x) может открыть отдельное окно с изображением. display(x) означает «отображать x с максимальным качеством для текущих устройств вывода». Если требуется текстовый вывод типа REPL, который гарантированно переходит в stdout, следует использовать вместо этого show(stdout, "text/plain", x).

Кроме того, есть два варианта с аргументом mime (строка типа MIME, например "image/png"), которые пытаются отображать x только с помощью запрашиваемого типа MIME, выдавая MethodError, если этот тип не поддерживается дисплеями или x. Используя эти варианты, можно также предоставлять «необработанные» данные запрошенного типа MIME, передавая x::AbstractString (для типов MIME с текстовым хранилищем, таким как text/html или application/postscript) или x::Vector{UInt8} (для двоичных типов MIME).

Чтобы настроить отображение экземпляров типа, перегрузите show вместо display, как описывается в разделе руководства Настраиваемая структурная распечатка.

# Base.Multimedia.redisplay — Function

redisplay(x)
redisplay(d::AbstractDisplay, x)
redisplay(mime, x)
redisplay(d::AbstractDisplay, mime, x)

По умолчанию функции redisplay просто вызывают display. Однако некоторые бэкенды отображения могут переопределять redisplay, чтобы изменить существующее отображение x (если есть). Использование redisplay также сообщает бэкенду, что x может отображаться многократно и бэкенд может отложить отображение до тех пор, пока (например) не отобразится следующая интерактивная командная строка.

# Base.Multimedia.displayable — Function

displayable(mime) -> Bool
displayable(d::AbstractDisplay, mime) -> Bool

Возвращает логическое значение, указывающее, поддерживается ли отображение данного типа mime (строка) каким-либо дисплеем в текущем стеке или, в частности, дисплеем d во втором варианте.

# Base.show — Method

show(io::IO, mime, x)

Функции display, в конечном счете, вызывают show, чтобы по возможности записать объект x как данный тип mime в заданный поток ввода-вывода io (обычно это буфер памяти). Чтобы предоставить расширенное мультимедийное представление определяемого пользователем типа T, необходимо просто определить новый метод show для T с помощью show(io, ::MIME"mime", x::T) = ... где mime представляет собой строку типа MIME, а в теле функции вызывается функция write (или аналогичная) для записи этого представления x в io. (Обратите внимание, что нотация MIME"" поддерживает только литеральные строки; для более гибкого построения типов MIME используйте MIME{Symbol("")}.)

Например, если определен тип MyImage и известно, как он записывается в файл PNG, можно определить функцию show(io, ::MIME"image/png", x::MyImage) = ..., чтобы разрешить отображение изображений в AbstractDisplay с поддержкой PNG (например, IJulia). Как обычно, необходимо использовать import Base.show, чтобы добавить новые методы во встроенную функцию Julia show.

Строго говоря, макрос MIME"mime" определяет одинарный тип для данной строки mime, позволяя использовать механизмы диспетчеризации Julia при определении способа отображения объектов любого заданного типа.

Тип MIME по умолчанию — MIME"text/plain". Существует резервное определение для вывода text/plain, которое вызывает show с двумя аргументами, поэтому не всегда обязательно добавлять метод для этого случая. Если тип использует настраиваемый человекочитаемый вывод, следует определить show(::IO, ::MIME"text/plain", ::T). Например, тип Day использует 1 day как вывод для типа MIME text/plain, а Day(1) — как вывод 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

Типы контейнеров обычно реализуют show с тремя аргументами путем вызова show(io, MIME"text/plain"(), x) для элементов x, причем :compact => true задается в IOContext, передаваемом как первый аргумент.

# Base.Multimedia.showable — Function

showable(mime, x)

Возвращает логическое значение, указывающее, можно ли записать объект x как данный тип mime.

(По умолчанию это определяется автоматически самим существованием соответствующего метода show для typeof(x). Некоторые типы предоставляют пользовательские методы showable, например, если доступные форматы MIME зависят от значения x.)

Примеры

julia> showable(MIME("text/plain"), rand(5))
true

julia> showable("image/png", rand(5))
false

# Base.repr — Method

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.

В отдельных случаях, если x является AbstractString (для текстовых типов MIME) или Vector{UInt8} (для двоичных типов MIME), функция repr предполагает, что x уже имеет запрашиваемый формат mime, и просто возвращает x. Это неприменимо для типа MIME "text/plain". Этот способ используется для передачи необработанных данных в display(m::MIME, x).

В частности, repr("text/plain", x) обычно представляет собой версию «структурной распечатки программного кода» для x, разработанного для потребления человеком. См. также описание метода repr(x), который возвращает строку, соответствующую show(x), что может быть более приближенным к способу ввода значения x в Julia.

Примеры

julia> A = [1 2; 3 4];

julia> repr("text/plain", A)
"2×2 Matrix{Int64}:\n 1  2\n 3  4"

# Base.Multimedia.MIME — Type

MIME

Тип, представляющий стандартный формат веб-данных. MIME расшифровывается как Multipurpose Internet Mail Extensions (многоцелевые расширения интернет-почты), поскольку этот стандарт изначально использовался для описания мультимедийных вложений в сообщения электронной почты.

Объект MIME можно передать как второй аргумент в show, чтобы запросить вывод в этом формате.

Примеры

julia> show(stdout, MIME("text/plain"), "hi")
"hi"

# Base.Multimedia.@MIME_str — Macro

@MIME_str

Вспомогательный макрос для записи типов MIME, обычно используемый при добавлении методов в show. Например, синтаксис show(io::IO, ::MIME"text/html", x::MyType) = ... можно использовать для определения способа записи HTML-представления MyType.

Как уже говорилось выше, можно также определить новые бэкенды отображения. Например, модуль, который может отображать PNG-изображения в окне, может зарегистрировать эту возможность в Julia, так что при вызове display(x) для типов с PNG-представлениями изображение будет автоматически отображаться в окне модуля.

Чтобы определить новый бэкенд отображения, необходимо сначала создать подтип D абстрактного класса AbstractDisplay. Затем для каждого типа MIME (строки mime), который может быть отображен в D, следует определить функцию 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) о типах mime, поддерживаемых D, и выводит лучший из них. Если для x не найдено ни одного поддерживаемого типа MIME, должна возникнуть ошибка MethodError. Аналогичным образом, некоторые подтипы могут переопределять redisplay(d::D, ...). (Опять же, чтобы добавить новые методы для отображения (display), нужно import Base.display.) Возвращаемые значения этих функций зависят от реализации (поскольку в некоторых случаях может быть полезно возвращать «дескриптор» отображения какого-либо типа). Затем функции отображения для D можно вызывать напрямую, но они также могут быть вызваны автоматически из display(x), просто путем отправки нового дисплея в стек бэкендов отображения с помощью соответствующей функции.

# Base.Multimedia.pushdisplay — Function

pushdisplay(d::AbstractDisplay)

Передает новое отображение d поверх глобального стека дисплеев и бэкендов. При вызове display(x) или display(mime, x) x отображается на самом верхнем совместимом бэкенде в стеке (то есть самом верхнем бэкенде, который не выдает MethodError).

# Base.Multimedia.popdisplay — Function

popdisplay()
popdisplay(d::AbstractDisplay)

Удаляет самый верхний бэкенд из стека дисплеев и бэкендов или самую верхнюю копию d во втором варианте.

# Base.Multimedia.TextDisplay — Type

TextDisplay(io::IO)

Возвращает TextDisplay <: AbstractDisplay, где все объекты отображаются как тип MIME text/plain (по умолчанию), причем текстовое представление записывается в заданный поток ввода-вывода. (Именно так объекты выводятся в REPL Julia.)

# Base.Multimedia.istextmime — Function

istextmime(m::MIME)

Определяет, является ли тип MIME текстовыми данными. Предполагается, что типы MIME являются двоичными данными за исключением набора типов, которые заведомо относятся к текстовым данным (возможно, Юникод).

Примеры

julia> istextmime(MIME("text/plain"))
true

julia> istextmime(MIME("image/png"))
false

Сетевой ввод-вывод

# Base.bytesavailable — Function

bytesavailable(io)

Возвращает количество байтов, доступных для чтения до выполнения чтения из этого потока; в противном случае буфер блокируется.

Примеры

julia> io = IOBuffer("JuliaLang is a GitHub organization");

julia> bytesavailable(io)
34

# Base.ntoh — Function

ntoh(x)

Преобразовывает порядок следования байтов для значения из порядка байтов в сети (обратный порядок) в порядок, используемый хостом.

# Base.hton — Function

hton(x)

Преобразовывает порядок следования байтов для значения из порядка байтов хоста в порядок, используемый сетью (обратный порядок).

# Base.ltoh — Function

ltoh(x)

Преобразовывает порядок следования байтов для значения из прямого порядка байтов в порядок, используемый хостом.

# Base.htol — Function

htol(x)

Преобразовывает порядок следования байтов для значения из порядка байтов хоста в прямой порядок.

# Base.ENDIAN_BOM — Constant

ENDIAN_BOM

32-разрядная метка порядка следования байтов указывает на собственный порядок байтов на хост-компьютере. Компьютеры с обратным порядком байтов будут содержать значение 0x04030201. Компьютеры с обратным порядком байтов будут содержать значение 0x01020304.