New in version 1.3.0: This class was added.
Buffer is a mutable block of memory that can be read or written to in a structured manner, and
passed to streams to efficiently read or write directly to memory without needing to go through an
ByteArray. Buffers may be Closeable if they hold a managed resource (e.g. mmap()’d
buffers); see Closeable and ClosingScope.
Cursors and Capacity¶
Buffer has the concept of a
cursor and a
capacity, both exposed as properties.
cursor is the current position of the buffer; all read and write operations to the buffer
will start at this position in the buffer’s backing storage. The cursor is mutable, and can be
changed at will.
capacity is the maximum position of the cursor, and thus the maximum amount of data that can
be written to or read from the buffer. The
capacity is also mutable, but cannot be changed at
will i.e. it can be read from and the read value may be changed but it cannot be written to.
ByteArrayBuffer class exists as an in-memory implemention of
Buffer has several functions for reading data out of it. Each read method increments the
cursor value by the size of the type being read.
readByte- reads a singular byte at the
readShort- reads a singular short at the
readInt- reads a singular int at the
readLong- reads a singular long at the
readArray- reads a sequence of bytes at the
All methods imply big-endian reads. The
are provided for little endian reads.
Buffer has several functions for writing data into it. Each write method increments
cursor value by the size of the type being written.
writeByte- writes a singular byte at the
writeShort- reads a singular short at the
writeInt- writes a singular int at the
writeLong- writes a singular long at the
writeArray- writes a sequence of bytes at the
All methods imply big-endian writes. The
methods are provided for little endian reads.
Buffer interface should not be implemented in common modules.
Buffer implementations are designed to allow efficient writing or reading directly from the
backing storage, via the
address method. However, some buffers may not be backed by a
memory-mapped object. The
supportsAddress function should be called by anything asking for a
Buffer object’s internal address.
supportsAddressreturns true, use the
addressmethod with a callback that will take the direct
CPointer<ByteVar>of the backing memory for the buffer.
supportsAddressreturns false, use the
writeArraymethods for fallback support.