cc.otavia.buffer

A wrapper of java.nio.ByteBuffer, with separate reader and writer offsets.

A buffer is a logically sequential stretch of memory with a certain capacity, an offset for writing, and an offset for reading. Buffers may be composed of multiple components, where each component is a guaranteed contiguous chunk of memory.

=== Creating a buffer === Buffers are created by allocators, and their allocate family of methods. A number of standard allocators exist, and are available through static methods on the BufferAllocator interface.

=== Buffer life cycle === The buffer has a life cycle, where it is allocated, used, and deallocated. When the buffer is initially allocated, a pairing close() call will deallocate it.

=== Thread-safety === Buffer are not thread-safe.

=== Accessing data === Data access methods fall into two classes:

1. Access that are based on, and updates, the read or write offset positions.
   • These accessor methods are typically called readX or writeX.
2. Access that take offsets as arguments, and do not update read or write offset positions.
   • These accessor methods are typically called getX or setX.

A buffer contains two mutable offset positions: one for reading and one for writing. These positions use zero-based indexing , such that the first byte of data in the buffer is placed at offset 0, and the last byte in the buffer is at offset capacity - 1. The readerOffset() is the offset into the buffer from which the next read will take place, and is initially zero. The reader offset must always be less than or equal to the writerOffset(). The writerOffset() is likewise the offset into the buffer where the next write will take place. The writer offset is also initially zero, and must be less than or equal to the capacity.

This carves the buffer into three regions, as demonstrated by this diagram:

| discardable bytes | readable bytes | writable bytes |
|:------------------|:--------------:|:--------------:|
|                   |   (CONTENT)    |                |
|                   |                |                |
0 <= readerOffset <= writerOffset <= capacity 

=== Byte Order === Buffers are always big endian, and this cannot be changed. Usages that need to get, set, read, or write, little-endian values will have to flip the byte order of the values they read and write.

=== Splitting buffers === The split() method is not support.

=== Buffers as constants === Constants buffer is not support, use Array[Byte] directly.

Interface for allocating Buffers.

An exception thrown when an operation is attempted on a Buffer when it has been closed.

The ByteCursor scans through a sequence of bytes. This is similar to ByteProcessor, but for external iteration rather than internal iteration. The external iteration allows the callers to control the pace of the iteration.

Provides a mechanism to iterate over a collection of bytes.