Buffer

Buffer is an utility object that can be created by using data:createBuffer(). It is used to get more control of what you are writing and reading, by providing bunch of methods for reading and writing bytes for specific primitive data types.

Basics

Supported primitives

ⓘ Note

On this page methods, instead of standard type names, will often use primitive names from this table for specifying arguments and return types, keep this in mind while reading this page.

Type name	Size in bytes	Description
byte	1	An unsigned 8 bit length integer. Can contain values in range [0; 255]
short	2	A signed 16 bit length integer. Can contain values in range [-32768; 32767]
ushort	2	An unsigned 16 bit length integer. Can contain values in range [0; 65535]
int	4	A signed 32 bit length integer. Can contain values in range [-2147483648; 2147483647]
uint	4	An unsigned 32 bit length integer. Can contain values in range [0; 4294967295]
long	8	A signed 64 bit length integer. Can contain values in range [-9223372036854775808; 9223372036854775807]
ulong	8	An usigned 64 bit length integer. Can contain values in range [0; 18446744073709551615]
float	4	A single-precision float-pointing number.
double	8	A double-precision float-pointing number.
str	2+Length	A string primitive that can be stored in buffers. Starts with 1 unsigned short defining the length of the string, and followed with string bytes.

Buffer instantiation and capacity

There are two possible ways to instantiate a buffer:

Arguments	Returns	Description
data:createBuffer()	Buffer	Creates a buffer with initial capacity of 512 bytes.
data:createBuffer(capacity integer)	Buffer	Creates a buffer with specified initial capacity.

@see data:createBuffer

Buffer capacity is amount of bytes until buffer will need to reallocate more space. Once it reaches the cap, it reallocates buffer with additional 512 bytes. Buffer can not exceed the amount of allocated memory specified in permissions settings.

How buffer works

Buffers have a pointer to current byte in a buffer, and it is moved by read and write methods. Buffers has same pointer both for write and read operations.

For example:

AA	BB	CC	EE
^^

Right now buffer is pointing to first byte (index 0), so when we do the following:

print(buf:read()) --> 170

@see read

Buffer will be pointing to the next byte:

AA	BB	CC	EE
	^^

---

Now when we will write a byte in a buffer:

buf:write(255)

@see write

It will rewrite the pointed byte, and buffer will be pointing to the next byte.

AA	FF	CC	EE
		^^

---

Once buffer reaches it's current end, read methods will act different

• read will return -1.
• Integer and float pointing read methods will read until end, and will fill remaining bytes with nulls.
• readString, readByteArray, and readBase64 will read until end and stop. If pointer is already at end, it will return empty result.

AA	FF	CC	EE
				^^

print(buf:read()) --> -1
print(buf:readString()) --> ""

@see read, readString

AA	FF	CC	EE
				^^

---

Write methods will add new bytes if buffer is pointing it's current end, and will move the pointer further:

AA	FF	CC	EE
				^^

buf:writeUShort(65535)

@see writeUShort

This is how our buffer will look like now:

AA	FF	CC	EE	FF	FF
						^^

Buffer methods

WIP