# module IO::Buffered

##
Overview

The `IO::Buffered` mixin enhances an `IO` with input/output buffering.

The buffering behaviour can be turned on/off with the `#sync=` and `#read_buffering=` methods.

Additionally, several methods, like `#gets`, are implemented in a more efficient way.

##
Direct including types

- Compress::Deflate::Reader
- Compress::Gzip::Reader
- Compress::Zlib::Reader
- IO::FileDescriptor
- OpenSSL::SSL::Socket
- Socket

##
Defined in:

io/buffered.cr

##
Instance Method Summary

- #buffer_size : Int32

  Return the buffer size used

- #buffer_size=(value)

  Set the buffer size of both the read and write buffer Cannot be changed after any of the buffers have been allocated

- #close : Nil

  Flushes and closes the underlying `IO`.

- #flush

  Flushes any buffered data and the underlying `IO`.

- #flush_on_newline=(flush_on_newline)

  Turns on/off flushing the underlying `IO` when a newline is written.

- #flush_on_newline? : Bool

  Determines if this `IO` flushes automatically when a newline is written.

- #peek : Bytes

  Returns the bytes hold in the read buffer.

- #pos : Int64

  Returns the current position (in bytes) in this `IO`.

- #read(slice : Bytes) : Int32

  Buffered implementation of `IO#read(slice)`.

- #read_buffering=(read_buffering)

  Turns on/off `IO` read buffering.

- #read_buffering? : Bool

  Determines whether this `IO` buffers reads.

- #rewind

  Rewinds the underlying `IO`.

- #sync=(sync)

  Turns on/off `IO` write buffering.

- #sync? : Bool

  Determines if this `IO` does write buffering.

- #unbuffered_close

  Closes the wrapped `IO`.

- #unbuffered_flush

  Flushes the wrapped `IO`.

- #unbuffered_read(slice : Bytes)

  Reads at most slice.size bytes from the wrapped `IO` into slice.

- #unbuffered_rewind

  Rewinds the wrapped `IO`.

- #unbuffered_write(slice : Bytes)

  Writes slice entirely into the wrapped `IO`.

- #write(slice : Bytes) : Nil

  Buffered implementation of `IO#write(slice)`.

##
Instance Method Detail

def buffer_size : Int32 #

Return the buffer size used

def buffer_size=(value) #

Set the buffer size of both the read and write buffer Cannot be changed after any of the buffers have been allocated

def close : Nil #

Flushes and closes the underlying `IO`.

def flush #

Flushes any buffered data and the underlying `IO`. Returns `self`.

def flush_on_newline=(flush_on_newline) #

Turns on/off flushing the underlying `IO` when a newline is written.

def flush_on_newline? : Bool #

Determines if this `IO` flushes automatically when a newline is written.

def peek : Bytes #

Returns the bytes hold in the read buffer.

This method only performs a read to return peek data if the current buffer is empty: otherwise no read is performed and whatever is in the buffer is returned.

def pos : Int64 #

Returns the current position (in bytes) in this `IO`.

    File.write("testfile", "hello")

    file = File.new("testfile")
    file.pos     # => 0
    file.gets(2) # => "he"
    file.pos     # => 2

def read(slice : Bytes) : Int32 #

Buffered implementation of `IO#read(slice)`.

def read_buffering=(read_buffering) #

Turns on/off `IO` read buffering.

def read_buffering? : Bool #

Determines whether this `IO` buffers reads.

def rewind #

Rewinds the underlying `IO`. Returns `self`.

def sync=(sync) #

Turns on/off `IO` write buffering. When sync is set to `true`, no buffering will be done (that is, writing to this `IO` is immediately synced to the underlying `IO`).

def sync? : Bool #

Determines if this `IO` does write buffering. If `true`, no buffering is done.

abstract def unbuffered_close #

Closes the wrapped `IO`.

TODO Add return type restriction `Nil`

abstract def unbuffered_flush #

Flushes the wrapped `IO`.

TODO Add return type restriction `Nil`

abstract def unbuffered_read(slice : Bytes) #

Reads at most slice.size bytes from the wrapped `IO` into slice. Returns the number of bytes read.

TODO Add return type restriction `Int32`

abstract def unbuffered_rewind #

Rewinds the wrapped `IO`.

TODO Add return type restriction `Nil`

abstract def unbuffered_write(slice : Bytes) #

Writes slice entirely into the wrapped `IO`.

TODO Add return type restriction `Nil`

def write(slice : Bytes) : Nil #

Buffered implementation of `IO#write(slice)`.