abstract class IO
Overview
The IO
class is the basis for all input and output in Crystal.
This class is inherited by types like File
, Socket
and IO::Memory
and
provides many useful methods for reading from and writing to an IO, like #print
, #puts
,
#gets
and #printf
.
The only requirement for a type including the IO
module is to define
these two methods:
#read(slice : Bytes)
: read at most slice.size bytes from IO into slice and return the number of bytes read#write(slice : Bytes)
: write the whole slice into the IO
For example, this is a simple IO
on top of a Bytes
:
class SimpleSliceIO < IO
def initialize(@slice : Bytes)
end
def read(slice : Bytes)
slice.size.times { |i| slice[i] = @slice[i] }
@slice += slice.size
slice.size
end
def write(slice : Bytes)
slice.size.times { |i| @slice[i] = slice[i] }
@slice += slice.size
nil
end
end
slice = Slice.new(9) { |i| ('a'.ord + i).to_u8 }
String.new(slice) # => "abcdefghi"
io = SimpleSliceIO.new(slice)
io.gets(3) # => "abc"
io.print "xyz"
String.new(slice) # => "abcxyzghi"
Encoding
An IO
can be set an encoding with the #set_encoding
method. When this is
set, all string operations (#gets
, #gets_to_end
, #read_char
, #<<
, #print
, #puts
#printf
) will write in the given encoding, and read from the given encoding.
Byte operations (#read
, #write
, #read_byte
, #write_byte
) never do
encoding/decoding operations.
If an encoding is not set, the default one is UTF-8.
Mixing string and byte operations might not give correct results and should be avoided, as string operations might need to read extra bytes in order to get characters in the given encoding.
Direct Known Subclasses
- Flate::Reader
- Flate::Writer
- Gzip::Reader
- Gzip::Writer
- HTTP::Server::Response
- HTTP::WebSocket::Protocol::StreamIO
- IO::Delimited
- IO::FileDescriptor
- IO::Hexdump
- IO::Memory
- IO::MultiWriter
- IO::Sized
- IO::Stapled
- OpenSSL::DigestIO
- OpenSSL::SSL::Socket
- Socket
- String::Builder
- Zlib::Reader
- Zlib::Writer
Defined in:
io.crio/encoding.cr
io/error.cr
Class Method Summary
-
.copy(src, dst, limit : Int)
Copy at most limit bytes from src to dst.
-
.copy(src, dst)
Copy all contents from src to dst.
-
.pipe(read_blocking = false, write_blocking = false) : Tuple(IO::FileDescriptor, IO::FileDescriptor)
Creates a pair of pipe endpoints (connected to each other) and returns them as a two-element
Tuple
. -
.pipe(read_blocking = false, write_blocking = false, &block)
Creates a pair of pipe endpoints (connected to each other) and passes them to the given block.
Instance Method Summary
-
#<<(obj) : self
Writes the given object into this
IO
. -
#close
Closes this
IO
. -
#closed?
Returns
true
if thisIO
is closed. - #each_byte(&block) : Nil
- #each_byte
- #each_char(&block) : Nil
- #each_char
- #each_line(*args, **options, &block) : Nil
- #each_line(*args, **options)
-
#encoding : String
Returns this
IO
's encoding. -
#flush
Flushes buffered data, if any.
-
#gets(delimiter : Char, limit : Int, chomp = false) : String?
Reads until delimiter is found, limit bytes are read, or the end of the
IO
is reached. -
#gets(delimiter : Char, chomp = false) : String?
Reads until delimiter is found, or the end of the
IO
is reached. -
#gets(chomp = true) : String?
Reads a line from this
IO
. -
#gets(limit : Int, chomp = false) : String?
Reads a line of at most limit bytes from this
IO
. -
#gets(delimiter : String, chomp = false) : String?
Reads until delimiter is found or the end of the
IO
is reached. - #gets_to_end : String
-
#peek : Bytes?
Peeks into this IO, if possible.
-
#pos
Returns the current position (in bytes) in this
IO
. -
#pos=(value)
Sets the current position (in bytes) in this
IO
. -
#print(*objects : _) : Nil
Writes the given objects into this
IO
by invokingto_s(io)
on each of the objects. -
#print(obj) : Nil
Same as
#<<
. -
#printf(format_string, *args) : Nil
Writes a formatted string to this IO.
-
#printf(format_string, args : Array | Tuple) : Nil
Writes a formatted string to this IO.
-
#puts(*objects : _) : Nil
Writes the given objects, each followed by a newline character.
-
#puts : Nil
Writes a newline character.
-
#puts(obj) : Nil
Writes the given object to this
IO
followed by a newline character. -
#puts(string : String) : Nil
Writes the given string to this
IO
followed by a newline character unless the string already ends with one. -
#read(slice : Bytes)
Reads at most slice.size bytes from this
IO
into slice. -
#read_at(offset, bytesize, &block)
Yields an
IO
to read a section inside this IO. -
#read_byte : UInt8?
Reads a single byte from this
IO
. -
#read_bytes(type, format : IO::ByteFormat = IO::ByteFormat::SystemEndian)
Reads an instance of the given type from this
IO
using the specified format. - #read_char : Char?
-
#read_fully(slice : Bytes)
Tries to read exactly
slice.size
bytes from thisIO
into slice. -
#read_fully?(slice : Bytes)
Tries to read exactly
slice.size
bytes from thisIO
into slice. - #read_line(*args, **options) : String
-
#read_string(bytesize : Int) : String
Reads an UTF-8 encoded string of exactly bytesize bytes.
-
#read_utf8(slice : Bytes)
Reads UTF-8 decoded bytes into the given slice.
-
#read_utf8_byte
Reads a single decoded UTF-8 byte from this
IO
. -
#rewind
Rewinds this
IO
. -
#seek(offset, whence : Seek = Seek::Set)
Seeks to a given offset (in bytes) according to the whence argument.
-
#set_encoding(encoding : String, invalid : Symbol? = nil)
Sets the encoding of this
IO
. -
#skip(bytes_count : Int) : Nil
Reads and discards exactly bytes_count bytes.
-
#skip_to_end : Nil
Reads and discards bytes from
self
until there are no more bytes. -
#tell
Same as
#pos
. -
#tty? : Bool
Returns
true
if thisIO
is associated with a terminal device (tty),false
otherwise. -
#write(slice : Bytes) : Nil
Writes the contents of slice into this
IO
. -
#write_byte(byte : UInt8)
Writes a single byte into this
IO
. -
#write_bytes(object, format : IO::ByteFormat = IO::ByteFormat::SystemEndian)
Writes the given object to this
IO
using the specified format. -
#write_utf8(slice : Bytes)
Writes a slice of UTF-8 encoded bytes to this
IO
, using the current encoding.
Instance methods inherited from class Reference
==(other : self)==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference)
same?(other : Nil) same?, to_s(io : IO) : Nil to_s
Constructor methods inherited from class Reference
new
new
Instance methods inherited from class Object
!=(other)
!=,
!~(other)
!~,
==(other)
==,
===(other : JSON::Any)===(other : YAML::Any)
===(other) ===, =~(other) =~, class class, dup dup, hash(hasher)
hash hash, inspect(io : IO)
inspect inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s
to_s(io : IO) to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&block) try, unsafe_as(type : T.class) forall T unsafe_as
Constructor methods inherited from class Object
from_json(string_or_io, root : String) : selffrom_json(string_or_io) : self from_json, from_yaml(string_or_io : String | IO) : self from_yaml
Class Method Detail
Copy at most limit bytes from src to dst.
io = IO::Memory.new "hello"
io2 = IO::Memory.new
IO.copy io, io2, 3
io2.to_s # => "hel"
Copy all contents from src to dst.
io = IO::Memory.new "hello"
io2 = IO::Memory.new
IO.copy io, io2
io2.to_s # => "hello"
Creates a pair of pipe endpoints (connected to each other)
and returns them as a two-element Tuple
.
reader, writer = IO.pipe
writer.puts "hello"
writer.puts "world"
reader.gets # => "hello"
reader.gets # => "world"
Creates a pair of pipe endpoints (connected to each other) and passes them to the given block. Both endpoints are closed after the block.
IO.pipe do |reader, writer|
writer.puts "hello"
writer.puts "world"
reader.gets # => "hello"
reader.gets # => "world"
end
Instance Method Detail
Writes the given object into this IO
.
This ends up calling to_s(io)
on the object.
io = IO::Memory.new
io << 1
io << '-'
io << "Crystal"
io.to_s # => "1-Crystal"
Invokes the given block with each byte (UInt8
) in this IO
.
io = IO::Memory.new("aあ")
io.each_byte do |byte|
puts byte
end
Output:
97
227
129
130
Returns an Iterator
for the bytes in this IO
.
io = IO::Memory.new("aあ")
iter = io.each_byte
iter.next # => 97
iter.next # => 227
iter.next # => 129
iter.next # => 130
Invokes the given block with each Char
in this IO
.
io = IO::Memory.new("あめ")
io.each_char do |char|
puts char
end
Output:
あ
め
Returns an Iterator
for the chars in this IO
.
io = IO::Memory.new("あめ")
iter = io.each_char
iter.next # => 'あ'
iter.next # => 'め'
Invokes the given block with each line in this IO
, where a line
is defined by the arguments passed to this method, which can be the same
ones as in the #gets
methods.
io = IO::Memory.new("hello\nworld")
io.each_line do |line|
puts line.chomp.reverse
end
Output:
olleh
dlrow
Returns an Iterator
for the lines in this IO
, where a line
is defined by the arguments passed to this method, which can be the same
ones as in the #gets
methods.
io = IO::Memory.new("hello\nworld")
iter = io.each_line
iter.next # => "hello"
iter.next # => "world"
Flushes buffered data, if any.
IO
defines this is a no-op method, but including types may override.
Reads until delimiter is found, limit bytes are read, or the end of the IO
is reached.
Returns nil
if called at the end of this IO
.
io = IO::Memory.new "hello\nworld"
io.gets('o', 3) # => "hel"
io.gets('r', 10) # => "lo\nwor"
io.gets('z', 10) # => "ld"
io.gets('w', 10) # => nil
Reads until delimiter is found, or the end of the IO
is reached.
Returns nil
if called at the end of this IO
.
io = IO::Memory.new "hello\nworld"
io.gets('o') # => "hello"
io.gets('r') # => "\nwor"
io.gets('z') # => "ld"
io.gets('w') # => nil
Reads a line from this IO
. A line is terminated by the \n
character.
Returns nil
if called at the end of this IO
.
By default the newline is removed from the returned string,
unless chomp is false
.
io = IO::Memory.new "hello\nworld\nfoo\n"
io.gets # => "hello"
io.gets(chomp: false) # => "world\n"
io.gets # => "foo"
io.gets # => nil
Reads a line of at most limit bytes from this IO
.
A line is terminated by the \n
character.
Returns nil
if called at the end of this IO
.
io = IO::Memory.new "hello\nworld"
io.gets(3) # => "hel"
io.gets(3) # => "lo\n"
io.gets(3) # => "wor"
io.gets(3) # => "ld"
io.gets(3) # => nil
Reads until delimiter is found or the end of the IO
is reached.
Returns nil
if called at the end of this IO
.
io = IO::Memory.new "hello\nworld"
io.gets("wo") # => "hello\nwo"
io.gets("wo") # => "rld"
io.gets("wo") # => nil
Reads the rest of this IO
data as a String
.
io = IO::Memory.new "hello world"
io.gets_to_end # => "hello world"
Peeks into this IO, if possible.
It returns:
nil
if this IO isn't peekable- an empty slice if it is, but EOF was reached
- a non-empty slice if some data can be peeked
The returned bytes are only valid data until a next call to any method that reads from this IO is invoked.
By default this method returns nil
, but IO implementations
that provide buffering or wrap other IOs should override
this method.
Returns the current position (in bytes) in this IO
.
The IO
class raises on this method, but some subclasses, notable
IO::FileDescriptor
and IO::Memory
implement it.
File.write("testfile", "hello")
file = File.new("testfile")
file.pos # => 0
file.gets(2) # => "he"
file.pos # => 2
Sets the current position (in bytes) in this IO
.
The IO
class raises on this method, but some subclasses, notable
IO::FileDescriptor
and IO::Memory
implement it.
File.write("testfile", "hello")
file = File.new("testfile")
file.pos = 3
file.gets_to_end # => "lo"
Writes the given objects into this IO
by invoking to_s(io)
on each of the objects.
io = IO::Memory.new
io.print 1, '-', "Crystal"
io.to_s # => "1-Crystal"
Same as #<<
.
io = IO::Memory.new
io.print 1
io.print '-'
io.print "Crystal"
io.to_s # => "1-Crystal"
Writes a formatted string to this IO.
For details on the format string, see Kernel::sprintf
.
Writes a formatted string to this IO.
For details on the format string, see Kernel::sprintf
.
Writes the given objects, each followed by a newline character.
io = IO::Memory.new
io.puts 1, '-', "Crystal"
io.to_s # => "1\n-\nCrystal\n"
Writes a newline character.
io = IO::Memory.new
io.puts
io.to_s # => "\n"
Writes the given object to this IO
followed by a newline character.
io = IO::Memory.new
io.puts 1
io.puts "Crystal"
io.to_s # => "1\nCrystal\n"
Writes the given string to this IO
followed by a newline character
unless the string already ends with one.
io = IO::Memory.new
io.puts "hello\n"
io.puts "world"
io.to_s # => "hello\nworld\n"
Reads at most slice.size bytes from this IO
into slice.
Returns the number of bytes read, which is 0 if and only if there is no
more data to read (so checking for 0 is the way to detect end of file).
io = IO::Memory.new "hello"
slice = Bytes.new(4)
io.read(slice) # => 4
slice # => Bytes[104, 101, 108, 108]
io.read(slice) # => 1
slice # => Bytes[111, 101, 108, 108]
io.read(slice) # => 0
Yields an IO
to read a section inside this IO.
The IO
class raises on this method, but some subclasses, notable
File
and IO::Memory
implement it.
Multiple sections can be read concurrently.
Reads a single byte from this IO
. Returns nil
if there is no more
data to read.
io = IO::Memory.new "a"
io.read_byte # => 97
io.read_byte # => nil
Reads an instance of the given type from this IO
using the specified format.
This ends up invoking type.from_io(self, format)
, so any type defining a
from_io(io : IO, format : IO::ByteFormat = IO::ByteFormat::SystemEndian)
method can be read in this way.
See Int.from_io
and Float.from_io
.
io = IO::Memory.new
io.puts "\u{4}\u{3}\u{2}\u{1}"
io.rewind
io.read_bytes(Int32, IO::ByteFormat::LittleEndian) # => 0x01020304
Reads a single Char
from this IO
. Returns nil
if there is no
more data to read.
io = IO::Memory.new "あ"
io.read_char # => 'あ'
io.read_char # => nil
Tries to read exactly slice.size
bytes from this IO
into slice.
Raises EOFError
if there aren't slice.size
bytes of data.
io = IO::Memory.new "123451234"
slice = Bytes.new(5)
io.read_fully(slice) # => 5
slice # => Bytes[49, 50, 51, 52, 53]
io.read_fully(slice) # raises IO::EOFError
Tries to read exactly slice.size
bytes from this IO
into slice.
Returns nil
if there aren't slice.size
bytes of data, otherwise
returns the number of bytes read.
io = IO::Memory.new "123451234"
slice = Bytes.new(5)
io.read_fully?(slice) # => 5
slice # => Bytes[49, 50, 51, 52, 53]
io.read_fully?(slice) # => nil
Reads an UTF-8 encoded string of exactly bytesize bytes.
Raises EOFError
if there are not enough bytes to build
the string.
io = IO::Memory.new("hello world")
io.read_string(5) # => "hello"
io.read_string(1) # => " "
io.read_string(6) # raises IO::EOFError
Reads UTF-8 decoded bytes into the given slice. Returns the number of UTF-8 bytes read.
If no encoding is set, this is the same as #read(slice)
.
bytes = "你".encode("GB2312") # => Bytes[196, 227]
io = IO::Memory.new(bytes)
io.set_encoding("GB2312")
buffer = uninitialized UInt8[1024]
bytes_read = io.read_utf8(buffer.to_slice) # => 3
buffer.to_slice[0, bytes_read] # => Bytes[228, 189, 160]
"你".bytes # => [228, 189, 160]
Reads a single decoded UTF-8 byte from this IO
.
Returns nil
if there is no more data to read.
If no encoding is set, this is the same as #read_byte
.
bytes = "你".encode("GB2312") # => Bytes[196, 227]
io = IO::Memory.new(bytes)
io.set_encoding("GB2312")
io.read_utf8_byte # => 228
io.read_utf8_byte # => 189
io.read_utf8_byte # => 160
io.read_utf8_byte # => nil
"你".bytes # => [228, 189, 160]
Seeks to a given offset (in bytes) according to the whence argument.
The IO
class raises on this method, but some subclasses, notable
IO::FileDescriptor
and IO::Memory
implement it.
Returns self
.
File.write("testfile", "abc")
file = File.new("testfile")
file.gets(3) # => "abc"
file.seek(1, IO::Seek::Set)
file.gets(2) # => "bc"
file.seek(-1, IO::Seek::Current)
file.gets(1) # => "c"
Sets the encoding of this IO
.
The invalid argument can be:
nil
: an exception is raised on invalid byte sequences:skip
: invalid byte sequences are ignored
String operations (#gets
, #gets_to_end
, #read_char
, #<<
, #print
, #puts
#printf
) will use this encoding.
Reads and discards exactly bytes_count bytes.
Raises IO::EOFError
if there aren't at least bytes_count bytes.
io = IO::Memory.new "hello world"
io.skip(6)
io.gets # => "world"
io.skip(1) # raises IO::EOFError
Reads and discards bytes from self
until there
are no more bytes.
Returns true
if this IO
is associated with a terminal device (tty), false
otherwise.
IO returns false
, but including types may override.
STDIN.tty? # => true
IO::Memory.new.tty? # => false
Writes the contents of slice into this IO
.
io = IO::Memory.new
slice = Bytes.new(4) { |i| ('a'.ord + i).to_u8 }
io.write(slice)
io.to_s # => "abcd"
Writes a single byte into this IO
.
io = IO::Memory.new
io.write_byte 97_u8
io.to_s # => "a"
Writes the given object to this IO
using the specified format.
This ends up invoking object.to_io(self, format)
, so any object defining a
to_io(io : IO, format : IO::ByteFormat = IO::ByteFormat::SystemEndian)
method can be written in this way.
See Int#to_io
and Float#to_io
.
io = IO::Memory.new
io.write_bytes(0x01020304, IO::ByteFormat::LittleEndian)
io.rewind
io.gets(4) # => "\u{4}\u{3}\u{2}\u{1}"
Writes a slice of UTF-8 encoded bytes to this IO
, using the current encoding.