IO::Buffer

        # IO::Buffer < Object

---
# Includes:
Comparable (from ruby core)

(from ruby core)
---
IO::Buffer is a low-level efficient buffer for input/output. There are
three ways of using buffer:

*   Create an empty buffer with ::new, fill it with data using #copy or
    #set_value, #set_string, get data with #get_string;
*   Create a buffer mapped to some string with ::for, then it could be
    used both for reading with #get_string or #get_value, and writing
    (writing will change the source string, too);
*   Create a buffer mapped to some file with ::map, then it could be
    used for reading and writing the underlying file.


Interaction with string and file memory is performed by efficient
low-level C mechanisms like `memcpy`.

The class is meant to be an utility for implementing more high-level
mechanisms like Fiber::SchedulerInterface#io_read and
Fiber::SchedulerInterface#io_write.

**Examples of usage:**

Empty buffer:

    buffer = IO::Buffer.new(8)  # create empty 8-byte buffer
    #  =>
    # #<IO::Buffer 0x0000555f5d1a5c50+8 INTERNAL>
    # ...
    buffer
    #  =>
    # <IO::Buffer 0x0000555f5d156ab0+8 INTERNAL>
    # 0x00000000  00 00 00 00 00 00 00 00
    buffer.set_string('test', 2) # put there bytes of the "test" string, starting from offset 2
    # => 4
    buffer.get_string  # get the result
    # => "\x00\x00test\x00\x00"

Buffer from string:

    string = 'data'
    buffer = IO::Buffer.for(str)
    #  =>
    # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
    # ...
    buffer
    #  =>
    # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
    # 0x00000000  64 61 74 61                                     data

    buffer.get_string(2)  # read content starting from offset 2
    # => "ta"
    buffer.set_string('---', 1) # write content, starting from offset 1
    # => 3
    buffer
    #  =>
    # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
    # 0x00000000  64 2d 2d 2d                                     d---
    string  # original string changed, too
    # => "d---"

Buffer from file:

    File.write('test.txt', 'test data')
    # => 9
    buffer = IO::Buffer.map(File.open('test.txt'))
    #  =>
    # #<IO::Buffer 0x00007f3f0768c000+9 MAPPED IMMUTABLE>
    # ...
    buffer.get_string(5, 2) # read 2 bytes, starting from offset 5
    # => "da"
    buffer.set_string('---', 1) # attempt to write
    # in `set_string': Buffer is not writable! (IO::Buffer::AccessError)

    # To create writable file-mapped buffer
    # Open file for read-write, pass size, offset, and flags=0
    buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 9, 0, 0)
    buffer.set_string('---', 1)
    # => 3 -- bytes written
    File.read('test.txt')
    # => "t--- data"

**The class is experimental and the interface is subject to change.**
---
# Constants:

BIG_ENDIAN
:   [not documented]
DEFAULT_SIZE
:   [not documented]
EXTERNAL
:   [not documented]
HOST_ENDIAN
:   [not documented]
INTERNAL
:   [not documented]
LITTLE_ENDIAN
:   [not documented]
LOCKED
:   [not documented]
MAPPED
:   [not documented]
NETWORK_ENDIAN
:   [not documented]
PAGE_SIZE
:   [not documented]
PRIVATE
:   [not documented]
READONLY
:   [not documented]


# Class methods:

    for
    map
    new

# Instance methods:

    <=>
    clear
    copy
    empty?
    external?
    free
    get_string
    get_value
    hexdump
    inspect
    internal?
    locked
    locked?
    mapped?
    null?
    pread
    pwrite
    read
    readonly?
    resize
    set_string
    set_value
    size
    slice
    to_s
    transfer
    valid?
    write