I/O and Network
I/O and Network
General I/O
Base.STDOUT
Constant
STDOUT
Global variable referring to the standard out stream.
source
Base.STDERR
Constant
STDERR
Global variable referring to the standard error stream.
source
Base.STDIN
Constant
STDIN
Global variable referring to the standard input stream.
source
Base.open
Function
open(filename::AbstractString, [read::Bool, write::Bool, create::Bool, truncate::Bool, append::Bool]) -> IOStream
Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file.
sourceopen(filename::AbstractString, [mode::AbstractString]) -> IOStream
Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of mode
correspond to those from fopen(3)
or Perl open
, and are equivalent to setting the following boolean groups:
Mode | Description |
---|---|
r | read |
r+ | read, write |
w | write, create, truncate |
w+ | read, write, create, truncate |
a | write, create, append |
a+ | read, write, create, append |
open(f::Function, args...)
Apply the function f
to the result of open(args...)
and close the resulting file descriptor upon completion.
Example: open(readstring, "file.txt")
open(command, mode::AbstractString="r", stdio=DevNull)
Start running command
asynchronously, and return a tuple (stream,process)
. If mode
is "r"
, then stream
reads from the process's standard output and stdio
optionally specifies the process's standard input stream. If mode
is "w"
, then stream
writes to the process's standard input and stdio
optionally specifies the process's standard output stream.
open(f::Function, command, mode::AbstractString="r", stdio=DevNull)
Similar to open(command, mode, stdio)
, but calls f(stream)
on the resulting read or write stream, then closes the stream and waits for the process to complete. Returns the value returned by f
.
Base.IOBuffer
Type
IOBuffer([data,],[readable::Bool=true, writable::Bool=true, [maxsize::Int=typemax(Int)]])
Create an IOBuffer
, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown.
IOBuffer() -> IOBuffer
Create an in-memory I/O stream.
sourceIOBuffer(size::Int)
Create a fixed size IOBuffer. The buffer will not grow dynamically.
sourceIOBuffer(string::String)
Create a read-only IOBuffer
on the data underlying the given string.
julia> io = IOBuffer("Haho"); julia> String(take!(io)) "Haho" julia> String(take!(io)) "Haho"source
Base.take!
Method
take!(b::IOBuffer)
Obtain the contents of an IOBuffer
as an array, without copying. Afterwards, the IOBuffer
is reset to its initial state.
Base.fdio
Function
fdio([name::AbstractString, ]fd::Integer[, own::Bool=false]) -> IOStream
Create an IOStream
object from an integer file descriptor. If own
is true
, closing this object will close the underlying descriptor. By default, an IOStream
is closed when it is garbage collected. name
allows you to associate the descriptor with a named file.
Base.flush
Function
flush(stream)
Commit all currently buffered writes to the given stream.
source
Base.close
Function
close(stream)
Close an I/O stream. Performs a flush
first.
Base.write
Function
write(stream::IO, x) write(filename::AbstractString, x)
Write the canonical binary representation of a value to the given I/O stream or file. Returns the number of bytes written into the stream.
You can write multiple values with the same write
call. i.e. the following are equivalent:
write(stream, x, y...) write(stream, x) + write(stream, y...)source
Base.read
Function
read(filename::AbstractString, args...)
Open a file and read its contents. args
is passed to read
: this is equivalent to open(io->read(io, args...), filename)
.
read(stream::IO, T, dims)
Read a series of values of type T
from stream
, in canonical binary representation. dims
is either a tuple or a series of integer arguments specifying the size of the Array{T}
to return.
read(s::IO, nb=typemax(Int))
Read at most nb
bytes from s
, returning a Vector{UInt8}
of the bytes read.
read(s::IOStream, nb::Integer; all=true)
Read at most nb
bytes from s
, returning a Vector{UInt8}
of the bytes read.
If all
is true
(the default), this function will block repeatedly trying to read all requested bytes, until an error or end-of-file occurs. If all
is false
, at most one read
call is performed, and the amount of data returned is device-dependent. Note that not all stream types support the all
option.
read(stream::IO, T)
Read a single value of type T
from stream
, in canonical binary representation.
Base.read!
Function
read!(stream::IO, array::Union{Array, BitArray}) read!(filename::AbstractString, array::Union{Array, BitArray})
Read binary data from an I/O stream or file, filling in array
.
Base.readbytes!
Function
readbytes!(stream::IO, b::AbstractVector{UInt8}, nb=length(b))
Read at most nb
bytes from stream
into b
, returning the number of bytes read. The size of b
will be increased if needed (i.e. if nb
is greater than length(b)
and enough bytes could be read), but it will never be decreased.
readbytes!(stream::IOStream, b::AbstractVector{UInt8}, nb=length(b); all::Bool=true)
Read at most nb
bytes from stream
into b
, returning the number of bytes read. The size of b
will be increased if needed (i.e. if nb
is greater than length(b)
and enough bytes could be read), but it will never be decreased.
See read
for a description of the all
option.
Base.unsafe_read
Function
unsafe_read(io::IO, ref, nbytes::UInt)
Copy nbytes
from the IO
stream object into ref
(converted to a pointer).
It is recommended that subtypes T<:IO
override the following method signature to provide more efficient implementations: unsafe_read(s::T, p::Ptr{UInt8}, n::UInt)
Base.unsafe_write
Function
unsafe_write(io::IO, ref, nbytes::UInt)
Copy nbytes
from ref
(converted to a pointer) into the IO
object.
It is recommended that subtypes T<:IO
override the following method signature to provide more efficient implementations: unsafe_write(s::T, p::Ptr{UInt8}, n::UInt)
Base.position
Function
position(s)
Get the current position of a stream.
source
Base.seek
Function
seek(s, pos)
Seek a stream to the given position.
source
Base.seekstart
Function
seekstart(s)
Seek a stream to its beginning.
source
Base.seekend
Function
seekend(s)
Seek a stream to its end.
source
Base.skip
Function
skip(s, offset)
Seek a stream relative to the current position.
source
Base.mark
Function
mark(s)
Add a mark at the current position of stream s
. Returns the marked position.
See also unmark
, reset
, ismarked
.
Base.unmark
Function
unmark(s)
Remove a mark from stream s
. Returns true
if the stream was marked, false
otherwise.
See also mark
, reset
, ismarked
.
Base.reset
Function
reset(s)
Reset a stream s
to a previously marked position, and remove the mark. Returns the previously marked position. Throws an error if the stream is not marked.
See also mark
, unmark
, ismarked
.
Base.ismarked
Function
ismarked(s)
Returns true
if stream s
is marked.
Base.eof
Function
eof(stream) -> Bool
Tests whether an I/O stream is at end-of-file. If the stream is not yet exhausted, this function will block to wait for more data if necessary, and then return false
. Therefore it is always safe to read one byte after seeing eof
return false
. eof
will return false
as long as buffered data is still available, even if the remote end of a connection is closed.
Base.isreadonly
Function
isreadonly(stream) -> Bool
Determine whether a stream is read-only.
source
Base.iswritable
Function
iswritable(io) -> Bool
Returns true
if the specified IO object is writable (if that can be determined).
Base.isreadable
Function
isreadable(io) -> Bool
Returns true
if the specified IO object is readable (if that can be determined).
Base.isopen
Function
isopen(object) -> Bool
Determine whether an object - such as a stream, timer, or mmap – is not yet closed. Once an object is closed, it will never produce a new event. However, a closed stream may still have data to read in its buffer, use eof
to check for the ability to read data. Use poll_fd
to be notified when a stream might be writable or readable.
Base.Serializer.serialize
Function
serialize(stream, value)
Write an arbitrary value to a stream in an opaque format, such that it can be read back by deserialize
. The read-back value will be as identical as possible to the original. In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image. Ptr
values are serialized as all-zero bit patterns (NULL
).
Base.Serializer.deserialize
Function
deserialize(stream)
Read a value written by serialize
. deserialize
assumes the binary data read from stream
is correct and has been serialized by a compatible implementation of serialize
. It has been designed with simplicity and performance as a goal and does not validate the data read. Malformed data can result in process termination. The caller has to ensure the integrity and correctness of data read from stream
.
Base.Grisu.print_shortest
Function
print_shortest(io, x)
Print the shortest possible representation, with the minimum number of consecutive non-zero digits, of number x
, ensuring that it would parse to the exact same number.
Base.fd
Function
fd(stream)
Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous File
's and IOStream
's not to any of the asynchronous streams.
Base.redirect_stdout
Function
redirect_stdout([stream]) -> (rd, wr)
Create a pipe to which all C and Julia level STDOUT
output will be redirected. Returns a tuple (rd, wr)
representing the pipe ends. Data written to STDOUT
may now be read from the rd
end of the pipe. The wr
end is given for convenience in case the old STDOUT
object was cached by the user and needs to be replaced elsewhere.
stream
must be a TTY
, a Pipe
, or a TCPSocket
.
Base.redirect_stdout
Method
redirect_stdout(f::Function, stream)
Run the function f
while redirecting STDOUT
to stream
. Upon completion, STDOUT
is restored to its prior setting.
stream
must be a TTY
, a Pipe
, or a TCPSocket
.
Base.redirect_stderr
Function
redirect_stderr([stream]) -> (rd, wr)
Like redirect_stdout
, but for STDERR
.
stream
must be a TTY
, a Pipe
, or a TCPSocket
.
Base.redirect_stderr
Method
redirect_stderr(f::Function, stream)
Run the function f
while redirecting STDERR
to stream
. Upon completion, STDERR
is restored to its prior setting.
stream
must be a TTY
, a Pipe
, or a TCPSocket
.
Base.redirect_stdin
Function
redirect_stdin([stream]) -> (rd, wr)
Like redirect_stdout
, but for STDIN
. Note that the order of the return tuple is still (rd, wr)
, i.e. data to be read from STDIN
may be written to wr
.
stream
must be a TTY
, a Pipe
, or a TCPSocket
.
Base.redirect_stdin
Method
redirect_stdin(f::Function, stream)
Run the function f
while redirecting STDIN
to stream
. Upon completion, STDIN
is restored to its prior setting.
stream
must be a TTY
, a Pipe
, or a TCPSocket
.
Base.readchomp
Function
readchomp(x)
Read the entirety of x
as a string and remove a single trailing newline. Equivalent to chomp!(readstring(x))
.
Base.truncate
Function
truncate(file,n)
Resize the file or buffer given by the first argument to exactly n
bytes, filling previously unallocated space with '\0' if the file or buffer is grown.
Base.skipchars
Function
skipchars(stream, predicate; linecomment::Char)
Advance the stream until before the first character for which predicate
returns false
. For example skipchars(stream, isspace)
will skip all whitespace. If keyword argument linecomment
is specified, characters from that character through the end of a line will also be skipped.
Base.DataFmt.countlines
Function
countlines(io::IO, eol::Char='\n')
Read io
until the end of the stream/file and count the number of lines. To specify a file pass the filename as the first argument. EOL markers other than '\n'
are supported by passing them as the second argument.
Base.PipeBuffer
Function
PipeBuffer(data::Vector{UInt8}=UInt8[],[maxsize::Int=typemax(Int)])
An IOBuffer
that allows reading and performs writes by appending. Seeking and truncating are not supported. See IOBuffer
for the available constructors. If data
is given, creates a PipeBuffer
to operate on a data vector, optionally specifying a size beyond which the underlying Array
may not be grown.
Base.readavailable
Function
readavailable(stream)
Read all available data on the stream, blocking the task only if no data is available. The result is a Vector{UInt8,1}
.
Base.IOContext
Type
IOContext
IOContext
provides a mechanism for passing output configuration settings among show
methods.
In short, it is an immutable dictionary that is a subclass of IO
. It supports standard dictionary operations such as getindex
, and can also be used as an I/O stream.
Base.IOContext
Method
IOContext(io::IO, KV::Pair)
Create an IOContext
that wraps a given stream, adding the specified key=>value
pair to the properties of that stream (note that io
can itself be an IOContext
).
use
(key => value) in dict
to see if this particular combination is in the properties setuse
get(dict, key, default)
to retrieve the most recent value for a particular key
The following properties are in common use:
:compact
: Boolean specifying that small values should be printed more compactly, e.g. that numbers should be printed with fewer digits. This is set when printing array elements.:limit
: Boolean specifying that containers should be truncated, e.g. showing…
in place of most elements.:displaysize
: ATuple{Int,Int}
giving the size in rows and columns to use for text output. This can be used to override the display size for called functions, but to get the size of the screen use thedisplaysize
function.
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)) shortsource
Base.IOContext
Method
IOContext(io::IO, context::IOContext)
Create an IOContext
that wraps an alternate IO
but inherits the properties of context
.
Text I/O
Base.show
Method
show(x)
Write an informative text representation of a value to the current output stream. New types should overload show(io, x)
where the first argument is a stream. The representation used by show
generally includes Julia-specific formatting and type information.
Base.showcompact
Function
showcompact(x)
Show a compact representation of a value.
This is used for printing array elements without repeating type information (which would be redundant with that printed once for the whole array), and without line breaks inside the representation of an element.
To offer a compact representation different from its standard one, a custom type should test get(io, :compact, false)
in its normal show
method.
Base.showall
Function
showall(x)
Similar to show
, except shows all elements of arrays.
Base.summary
Function
summary(x)
Return a string giving a brief description of a value. By default returns string(typeof(x))
, e.g. Int64
.
For arrays, returns a string of size and type info, e.g. 10-element Array{Int64,1}
.
julia> summary(1) "Int64" julia> summary(zeros(2)) "2-element Array{Float64,1}"source
Base.print
Function
print(io::IO, x)
Write to io
(or to the default output stream STDOUT
if io
is not given) a canonical (un-decorated) text representation of a value if there is one, otherwise call show
. The representation used by print
includes minimal formatting and tries to avoid Julia-specific details.
julia> print("Hello World!") Hello World! julia> io = IOBuffer(); julia> print(io, "Hello World!") julia> String(take!(io)) "Hello World!"source
Base.println
Function
println(io::IO, xs...)
Print (using print
) xs
followed by a newline. If io
is not supplied, prints to STDOUT
.
Base.print_with_color
Function
print_with_color(color::Union{Symbol, Int}, [io], xs...; bold::Bool = false)
Print xs
in a color specified as a symbol.
color
may take any of the values :normal
, :default
, :bold
, :black
, :blue
, :cyan
, :green
, :light_black
, :light_blue
, :light_cyan
, :light_green
, :light_magenta
, :light_red
, :light_yellow
, :magenta
, :nothing
, :red
, :white
, or :yellow
or an integer between 0 and 255 inclusive. Note that not all terminals support 256 colors. If the keyword bold
is given as true
, the result will be printed in bold.
Base.info
Function
info([io, ] msg..., [prefix="INFO: "])
Display an informational message. Argument msg
is a string describing the information to be displayed. The prefix
keyword argument can be used to override the default prepending of msg
.
julia> info("hello world") INFO: hello world julia> info("hello world"; prefix="MY INFO: ") MY INFO: hello world
See also logging
.
Base.warn
Function
warn([io, ] msg..., [prefix="WARNING: ", once=false, key=nothing, bt=nothing, filename=nothing, lineno::Int=0])
Display a warning. Argument msg
is a string describing the warning to be displayed. Set once
to true and specify a key
to only display msg
the first time warn
is called. If bt
is not nothing
a backtrace is displayed. If filename
is not nothing
both it and lineno
are displayed.
See also logging
.
warn(msg)
Display a warning. Argument msg
is a string describing the warning to be displayed.
julia> warn("Beep Beep") WARNING: Beep Beepsource
Base.logging
Function
logging(io [, m [, f]][; kind=:all]) logging([; kind=:all])
Stream output of informational, warning, and/or error messages to io
, overriding what was otherwise specified. Optionally, divert stream only for module m
, or specifically function f
within m
. kind
can be :all
(the default), :info
, :warn
, or :error
. See Base.log_{info,warn,error}_to
for the current set of redirections. Call logging
with no arguments (or just the kind
) to reset everything.
Base.Printf.@printf
Macro
@printf([io::IOStream], "%Fmt", args...)
Print args
using C printf()
style format specification string, with some caveats: Inf
and NaN
are printed consistently as Inf
and NaN
for flags %a
, %A
, %e
, %E
, %f
, %F
, %g
, and %G
. Furthermore, if a floating point number is equally close to the numeric values of two possible output strings, the output string further away from zero is chosen.
Optionally, an IOStream
may be passed as the first argument to redirect output.
Examples
julia> @printf("%f %F %f %F\n", Inf, Inf, NaN, NaN) Inf Inf NaN NaN julia> @printf "%.0f %.1f %f\n" 0.5 0.025 -0.0078125 1 0.0 -0.007813source
Base.Printf.@sprintf
Macro
@sprintf("%Fmt", args...)
Return @printf
formatted output as string.
Examples
julia> s = @sprintf "this is a %s %15.1f" "test" 34.567; julia> println(s) this is a test 34.6source
Base.sprint
Function
sprint(f::Function, args...)
Call the given function with an I/O stream and the supplied extra arguments. Everything written to this I/O stream is returned as a string.
julia> sprint(showcompact, 66.66666) "66.6667"source
Base.showerror
Function
showerror(io, e)
Show a descriptive representation of an exception object.
source
Base.dump
Function
dump(x)
Show every part of the representation of a value.
source
Base.readstring
Function
readstring(stream::IO) readstring(filename::AbstractString)
Read the entire contents of an I/O stream or a file as a string. The text is assumed to be encoded in UTF-8.
source
Base.readline
Function
readline(stream::IO=STDIN; chomp::Bool=true) readline(filename::AbstractString; chomp::Bool=true)
Read a single line of text from the given I/O stream or file (defaults to STDIN
). When reading from a file, the text is assumed to be encoded in UTF-8. Lines in the input end with '\n'
or "\r\n"
or the end of an input stream. When chomp
is true (as it is by default), these trailing newline characters are removed from the line before it is returned. When chomp
is false, they are returned as part of the line.
Base.readuntil
Function
readuntil(stream::IO, delim) readuntil(filename::AbstractString, delim)
Read a string from an I/O stream or a file, up to and including the given delimiter byte. The text is assumed to be encoded in UTF-8.
source
Base.readlines
Function
readlines(stream::IO=STDIN; chomp::Bool=true) readlines(filename::AbstractString; chomp::Bool=true)
Read all lines of an I/O stream or a file as a vector of strings. Behavior is equivalent to saving the result of reading readline
repeatedly with the same arguments and saving the resulting lines as a vector of strings.
Base.eachline
Function
eachline(stream::IO=STDIN; chomp::Bool=true) eachline(filename::AbstractString; chomp::Bool=true)
Create an iterable EachLine
object that will yield each line from an I/O stream or a file. Iteration calls readline
on the stream argument repeatedly with chomp
passed through, determining whether trailing end-of-line characters are removed. When called with a file name, the file is opened once at the beginning of iteration and closed at the end. If iteration is interrupted, the file will be closed when the EachLine
object is garbage collected.
Base.DataFmt.readdlm
Method
readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, quotes=true, dims, comments=true, comment_char='#')
Read a matrix from the source where each line (separated by eol
) gives one row, with elements separated by the given delimiter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source.
If T
is a numeric type, the result is an array of that type, with any non-numeric elements as NaN
for floating-point types, or zero. Other useful values of T
include String
, AbstractString
, and Any
.
If header
is true
, the first row of data will be read as header and the tuple (data_cells, header_cells)
is returned instead of only data_cells
.
Specifying skipstart
will ignore the corresponding number of initial lines from the input.
If skipblanks
is true
, blank lines in the input will be ignored.
If use_mmap
is true
, the file specified by source
is memory mapped for potential speedups. Default is true
except on Windows. On Windows, you may want to specify true
if the file is large, and is only read once and not written to.
If quotes
is true
, columns enclosed within double-quote (") characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. Specifying dims
as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. If comments
is true
, lines beginning with comment_char
and text following comment_char
in any line are ignored.
Base.DataFmt.readdlm
Method
readdlm(source, delim::Char, eol::Char; options...)
If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a heterogeneous array of numbers and strings is returned.
source
Base.DataFmt.readdlm
Method
readdlm(source, delim::Char, T::Type; options...)
The end of line delimiter is taken as \n
.
Base.DataFmt.readdlm
Method
readdlm(source, delim::Char; options...)
The end of line delimiter is taken as \n
. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a heterogeneous array of numbers and strings is returned.
Base.DataFmt.readdlm
Method
readdlm(source, T::Type; options...)
The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as \n
.
Base.DataFmt.readdlm
Method
readdlm(source; options...)
The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as \n
. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a heterogeneous array of numbers and strings is returned.
Base.DataFmt.writedlm
Function
writedlm(f, A, delim='\t'; opts)
Write A
(a vector, matrix, or an iterable collection of iterable rows) as text to f
(either a filename string or an IO
stream) using the given delimiter delim
(which defaults to tab, but can be any printable Julia object, typically a Char
or AbstractString
).
For example, two vectors x
and y
of the same length can be written as two columns of tab-delimited text to f
by either writedlm(f, [x y])
or by writedlm(f, zip(x, y))
.
Base.DataFmt.readcsv
Function
readcsv(source, [T::Type]; options...)
Equivalent to readdlm
with delim
set to comma, and type optionally defined by T
.
Base.DataFmt.writecsv
Function
writecsv(filename, A; opts)
Equivalent to writedlm
with delim
set to comma.
Base.Base64.Base64EncodePipe
Type
Base64EncodePipe(ostream)
Returns a new write-only I/O stream, which converts any bytes written to it into base64-encoded ASCII bytes written to ostream
. Calling close
on the Base64EncodePipe
stream is necessary to complete the encoding (but does not close ostream
).
julia> io = IOBuffer(); julia> iob64_encode = Base64EncodePipe(io); julia> write(iob64_encode, "Hello!") 6 julia> close(iob64_encode); julia> str = String(take!(io)) "SGVsbG8h" julia> String(base64decode(str)) "Hello!"source
Base.Base64.Base64DecodePipe
Type
Base64DecodePipe(istream)
Returns a new read-only I/O stream, which decodes base64-encoded data read from istream
.
julia> io = IOBuffer(); julia> iob64_decode = Base64DecodePipe(io); julia> write(io, "SGVsbG8h") 8 julia> seekstart(io); julia> String(read(iob64_decode)) "Hello!"source
Base.Base64.base64encode
Function
base64encode(writefunc, args...) base64encode(args...)
Given a write
-like function writefunc
, which takes an I/O stream as its first argument, base64encode(writefunc, args...)
calls writefunc
to write args...
to a base64-encoded string, and returns the string. base64encode(args...)
is equivalent to base64encode(write, args...)
: it converts its arguments into bytes using the standard write
functions and returns the base64-encoded string.
See also base64decode
.
Base.Base64.base64decode
Function
base64decode(string)
Decodes the base64-encoded string
and returns a Vector{UInt8}
of the decoded bytes.
See also base64encode
julia> b = base64decode("SGVsbG8h") 6-element Array{UInt8,1}: 0x48 0x65 0x6c 0x6c 0x6f 0x21 julia> String(b) "Hello!"source
Base.displaysize
Function
displaysize(io) -> (lines, columns)
Return the nominal size of the screen that may be used for rendering output to this io object
sourceMultimedia I/O
Just as text output is performed by print
and user-defined types can indicate their textual representation by overloading show
, Julia provides a standardized mechanism for rich multimedia output (such as images, formatted text, or even audio and video), consisting of three parts:
A function
display(x)
to request the richest available multimedia display of a Julia objectx
(with a plain-text fallback).Overloading
show
allows one to indicate arbitrary multimedia representations (keyed by standard MIME types) of user-defined types.Multimedia-capable display backends may be registered by subclassing a generic
Display
type and pushing them onto a stack of display backends viapushdisplay
.
The base Julia runtime provides only plain-text display, but richer displays may be enabled by loading external modules or by using graphical Julia environments (such as the IPython-based IJulia notebook).
Base.Multimedia.display
Function
display(x) display(d::Display, x) display(mime, x) display(d::Display, mime, x)
Display x
using the topmost applicable display in the display stack, typically using the richest supported multimedia output for x
, with plain-text STDOUT
output as a fallback. The display(d, x)
variant attempts to display x
on the given display d
only, throwing a MethodError
if d
cannot display objects of this type.
There are also two variants with a mime
argument (a MIME type string, such as "image/png"
), which attempt to display x
using the requested MIME type only, throwing a MethodError
if this type is not supported by either the display(s) or by x
. With these variants, one can also supply the "raw" data in the requested MIME type by passing x::AbstractString
(for MIME types with text-based storage, such as text/html or application/postscript) or x::Vector{UInt8}
(for binary MIME types).
Base.Multimedia.redisplay
Function
redisplay(x) redisplay(d::Display, x) redisplay(mime, x) redisplay(d::Display, mime, x)
By default, the redisplay
functions simply call display
. However, some display backends may override redisplay
to modify an existing display of x
(if any). Using redisplay
is also a hint to the backend that x
may be redisplayed several times, and the backend may choose to defer the display until (for example) the next interactive prompt.
Base.Multimedia.displayable
Function
displayable(mime) -> Bool displayable(d::Display, mime) -> Bool
Returns a boolean value indicating whether the given mime
type (string) is displayable by any of the displays in the current display stack, or specifically by the display d
in the second variant.
Base.show
Method
show(stream, mime, x)
The display
functions ultimately call show
in order to write an object x
as a given mime
type to a given I/O stream
(usually a memory buffer), if possible. In order to provide a rich multimedia representation of a user-defined type T
, it is only necessary to define a new show
method for T
, via: show(stream, ::MIME"mime", x::T) = ...
, where mime
is a MIME-type string and the function body calls write
(or similar) to write that representation of x
to stream
. (Note that the MIME""
notation only supports literal strings; to construct MIME
types in a more flexible manner use MIME{Symbol("")}
.)
For example, if you define a MyImage
type and know how to write it to a PNG file, you could define a function show(stream, ::MIME"image/png", x::MyImage) = ...
to allow your images to be displayed on any PNG-capable Display
(such as IJulia). As usual, be sure to import Base.show
in order to add new methods to the built-in Julia function show
.
The default MIME type is MIME"text/plain"
. There is a fallback definition for text/plain
output that calls show
with 2 arguments. Therefore, this case should be handled by defining a 2-argument show(stream::IO, x::MyType)
method.
Technically, the MIME"mime"
macro defines a singleton type for the given mime
string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type.
The first argument to show
can be an IOContext
specifying output format properties. See IOContext
for details.
Base.Multimedia.mimewritable
Function
mimewritable(mime, x)
Returns a boolean value indicating whether or not the object x
can be written as the given mime
type. (By default, this is determined automatically by the existence of the corresponding show
method for typeof(x)
.)
Base.Multimedia.reprmime
Function
reprmime(mime, x)
Returns an AbstractString
or Vector{UInt8}
containing the representation of x
in the requested mime
type, as written by show
(throwing a MethodError
if no appropriate show
is available). An AbstractString
is returned for MIME types with textual representations (such as "text/html"
or "application/postscript"
), whereas binary data is returned as Vector{UInt8}
. (The function istextmime(mime)
returns whether or not Julia treats a given mime
type as text.)
As a special case, if x
is an AbstractString
(for textual MIME types) or a Vector{UInt8}
(for binary MIME types), the reprmime
function assumes that x
is already in the requested mime
format and simply returns x
. This special case does not apply to the "text/plain"
MIME type. This is useful so that raw data can be passed to display(m::MIME, x)
.
Base.Multimedia.stringmime
Function
stringmime(mime, x)
Returns an AbstractString
containing the representation of x
in the requested mime
type. This is similar to reprmime
except that binary data is base64-encoded as an ASCII string.
As mentioned above, one can also define new display backends. For example, a module that can display PNG images in a window can register this capability with Julia, so that calling display(x)
on types with PNG representations will automatically display the image using the module's window.
In order to define a new display backend, one should first create a subtype D
of the abstract class Display
. Then, for each MIME type (mime
string) that can be displayed on D
, one should define a function display(d::D, ::MIME"mime", x) = ...
that displays x
as that MIME type, usually by calling reprmime(mime, x)
. A MethodError
should be thrown if x
cannot be displayed as that MIME type; this is automatic if one calls reprmime
. Finally, one should define a function display(d::D, x)
that queries mimewritable(mime, x)
for the mime
types supported by D
and displays the "best" one; a MethodError
should be thrown if no supported MIME types are found for x
. Similarly, some subtypes may wish to override redisplay(d::D, ...)
. (Again, one should import Base.display
to add new methods to display
.) The return values of these functions are up to the implementation (since in some cases it may be useful to return a display "handle" of some type). The display functions for D
can then be called directly, but they can also be invoked automatically from display(x)
simply by pushing a new display onto the display-backend stack with:
Base.Multimedia.pushdisplay
Function
pushdisplay(d::Display)
Pushes a new display d
on top of the global display-backend stack. Calling display(x)
or display(mime, x)
will display x
on the topmost compatible backend in the stack (i.e., the topmost backend that does not throw a MethodError
).
Base.Multimedia.popdisplay
Function
popdisplay() popdisplay(d::Display)
Pop the topmost backend off of the display-backend stack, or the topmost copy of d
in the second variant.
Base.Multimedia.TextDisplay
Type
TextDisplay(io::IO)
Returns a TextDisplay <: Display
, which displays any object as the text/plain MIME type (by default), writing the text representation to the given I/O stream. (This is how objects are printed in the Julia REPL.)
Base.Multimedia.istextmime
Function
istextmime(m::MIME)
Determine whether a MIME type is text data. MIME types are assumed to be binary data except for a set of types known to be text data (possibly Unicode).
sourceMemory-mapped I/O
Base.Mmap.Anonymous
Type
Mmap.Anonymous(name, readonly, create)
Create an IO
-like object for creating zeroed-out mmapped-memory that is not tied to a file for use in Mmap.mmap
. Used by SharedArray
for creating shared memory arrays.
Base.Mmap.mmap
Method
Mmap.mmap(io::Union{IOStream,AbstractString,Mmap.AnonymousMmap}[, type::Type{Array{T,N}}, dims, offset]; grow::Bool=true, shared::Bool=true) Mmap.mmap(type::Type{Array{T,N}}, dims)
Create an Array
whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory.
The type is an Array{T,N}
with a bits-type element of T
and dimension N
that determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia).
dims
is a tuple or single Integer
specifying the size or length of the array.
The file is passed via the stream argument, either as an open IOStream
or filename string. When you initialize the stream, use "r"
for a "read-only" array, and "w+"
to create a new array used to write values to disk.
If no type
argument is specified, the default is Vector{UInt8}
.
Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position for an IOStream
.
The grow
keyword argument specifies whether the disk file should be grown to accommodate the requested size of array (if the total file size is < requested array size). Write privileges are required to grow the file.
The shared
keyword argument specifies whether the resulting Array
and changes made to it will be visible to other processes mapping the same file.
For example, the following code
# Create a file for mmapping # (you could alternatively use mmap to do this step, too) A = rand(1:20, 5, 30) s = open("/tmp/mmap.bin", "w+") # We'll write the dimensions of the array as the first two Ints in the file write(s, size(A,1)) write(s, size(A,2)) # Now write the data write(s, A) close(s) # Test by reading it back in s = open("/tmp/mmap.bin") # default is read-only m = read(s, Int) n = read(s, Int) A2 = Mmap.mmap(s, Matrix{Int}, (m,n))
creates a m
-by-n
Matrix{Int}
, linked to the file associated with stream s
.
A more portable file would need to encode the word size – 32 bit or 64 bit – and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping).
source
Base.Mmap.mmap
Method
Mmap.mmap(io, BitArray, [dims, offset])
Create a BitArray
whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as mmap
, but the byte representation is different.
Example: B = Mmap.mmap(s, BitArray, (25,30000))
This would create a 25-by-30000 BitArray
, linked to the file associated with stream s
.
Base.Mmap.sync!
Function
Mmap.sync!(array)
Forces synchronization between the in-memory version of a memory-mapped Array
or BitArray
and the on-disk version.
Network I/O
Base.connect
Method
connect([host], port::Integer) -> TCPSocket
Connect to the host host
on port port
.
Base.connect
Method
connect(path::AbstractString) -> PipeEndpoint
Connect to the named pipe / UNIX domain socket at path
.
Base.listen
Method
listen([addr, ]port::Integer; backlog::Integer=BACKLOG_DEFAULT) -> TCPServer
Listen on port on the address specified by addr
. By default this listens on localhost
only. To listen on all interfaces pass IPv4(0)
or IPv6(0)
as appropriate. backlog
determines how many connections can be pending (not having called accept
) before the server will begin to reject them. The default value of backlog
is 511.
Base.listen
Method
listen(path::AbstractString) -> PipeServer
Create and listen on a named pipe / UNIX domain socket.
source
Base.getaddrinfo
Function
getaddrinfo(host::AbstractString) -> IPAddr
Gets the IP address of the host
(may have to do a DNS lookup)
Base.getsockname
Function
getsockname(sock::Union{TCPServer, TCPSocket}) -> (IPAddr, UInt16)
Get the IP address and the port that the given TCPSocket
is connected to (or bound to, in the case of TCPServer
).
Base.IPv4
Type
IPv4(host::Integer) -> IPv4
Returns an IPv4 object from ip address host
formatted as an Integer
.
julia> IPv4(3223256218) ip"192.30.252.154"source
Base.IPv6
Type
IPv6(host::Integer) -> IPv6
Returns an IPv6 object from ip address host
formatted as an Integer
.
julia> IPv6(3223256218) ip"::c01e:fc9a"source
Base.nb_available
Function
nb_available(stream)
Returns the number of bytes available for reading before a read from this stream or buffer will block.
source
Base.accept
Function
accept(server[,client])
Accepts a connection on the given server and returns a connection to the client. An uninitialized client stream may be provided, in which case it will be used instead of creating a new stream.
source
Base.listenany
Function
listenany([host::IPAddr,] port_hint) -> (UInt16, TCPServer)
Create a TCPServer
on any port, using hint as a starting point. Returns a tuple of the actual port that the server was created on and the server itself.
Base.Filesystem.poll_fd
Function
poll_fd(fd, timeout_s::Real=-1; readable=false, writable=false)
Monitor a file descriptor fd
for changes in the read or write availability, and with a timeout given by timeout_s
seconds.
The keyword arguments determine which of read and/or write status should be monitored; at least one of them must be set to true
.
The returned value is an object with boolean fields readable
, writable
, and timedout
, giving the result of the polling.
Base.Filesystem.poll_file
Function
poll_file(path::AbstractString, interval_s::Real=5.007, timeout_s::Real=-1) -> (previous::StatStruct, current::StatStruct)
Monitor a file for changes by polling every interval_s
seconds until a change occurs or timeout_s
seconds have elapsed. The interval_s
should be a long period; the default is 5.007 seconds.
Returns a pair of StatStruct
objects (previous, current)
when a change is detected.
To determine when a file was modified, compare mtime(prev) != mtime(current)
to detect notification of changes. However, using watch_file
for this operation is preferred, since it is more reliable and efficient, although in some situations it may not be available.
Base.Filesystem.watch_file
Function
watch_file(path::AbstractString, timeout_s::Real=-1)
Watch file or directory path
for changes until a change occurs or timeout_s
seconds have elapsed.
The returned value is an object with boolean fields changed
, renamed
, and timedout
, giving the result of watching the file.
This behavior of this function varies slightly across platforms. See https://nodejs.org/api/fs.html#fs_caveats for more detailed information.
source
Base.bind
Function
bind(socket::Union{UDPSocket, TCPSocket}, host::IPAddr, port::Integer; ipv6only=false, reuseaddr=false, kws...)
Bind socket
to the given host:port
. Note that 0.0.0.0
will listen on all devices.
The
ipv6only
parameter disables dual stack mode. Ifipv6only=true
, only an IPv6 stack is created.If
reuseaddr=true
, multiple threads or processes can bind to the same address without error if they all setreuseaddr=true
, but only the last to bind will receive any traffic.
bind(chnl::Channel, task::Task)
Associates the lifetime of chnl
with a task. Channel chnl
is automatically closed when the task terminates. Any uncaught exception in the task is propagated to all waiters on chnl
.
The chnl
object can be explicitly closed independent of task termination. Terminating tasks have no effect on already closed Channel objects.
When a channel is bound to multiple tasks, the first task to terminate will close the channel. When multiple channels are bound to the same task, termination of the task will close all of the bound channels.
julia> c = Channel(0); julia> task = @schedule foreach(i->put!(c, i), 1:4); julia> bind(c,task); julia> for i in c @show i end; i = 1 i = 2 i = 3 i = 4 julia> isopen(c) false
julia> c = Channel(0); julia> task = @schedule (put!(c,1);error("foo")); julia> bind(c,task); julia> take!(c) 1 julia> put!(c,1); ERROR: foo Stacktrace: [1] check_channel_state(::Channel{Any}) at ./channels.jl:131 [2] put!(::Channel{Any}, ::Int64) at ./channels.jl:261source
Base.send
Function
send(socket::UDPSocket, host, port::Integer, msg)
Send msg
over socket
to host:port
.
Base.recv
Function
recv(socket::UDPSocket)
Read a UDP packet from the specified socket, and return the bytes received. This call blocks.
source
Base.recvfrom
Function
recvfrom(socket::UDPSocket) -> (address, data)
Read a UDP packet from the specified socket, returning a tuple of (address, data)
, where address
will be either IPv4 or IPv6 as appropriate.
Base.setopt
Function
setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing)
Set UDP socket options.
multicast_loop
: loopback for multicast packets (default:true
).multicast_ttl
: TTL for multicast packets (default:nothing
).enable_broadcast
: flag must be set totrue
if socket will be used for broadcast messages, or else the UDP system will return an access error (default:false
).ttl
: Time-to-live of packets sent on the socket (default:nothing
).
Base.ntoh
Function
ntoh(x)
Converts the endianness of a value from Network byte order (big-endian) to that used by the Host.
source
Base.hton
Function
hton(x)
Converts the endianness of a value from that used by the Host to Network byte order (big-endian).
source
Base.ltoh
Function
ltoh(x)
Converts the endianness of a value from Little-endian to that used by the Host.
source
Base.htol
Function
htol(x)
Converts the endianness of a value from that used by the Host to Little-endian.
source
Base.ENDIAN_BOM
Constant
ENDIAN_BOM
The 32-bit byte-order-mark indicates the native byte order of the host machine. Little-endian machines will contain the value 0x04030201
. Big-endian machines will contain the value 0x01020304
.
© 2009–2016 Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors
Licensed under the MIT License.
https://docs.julialang.org/en/release-0.6/stdlib/io-network/