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]
long	8	A signed 64 bit length integer. Can contain values in range [-9223372036854775808; 9223372036854775807]
float	4	A single-precision float-pointing number.
double	8	A double-precision float-pointing number.

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

This buffer example is going to be used in all code snippets below:

AA	BB	CC	EE
^^

Buffer variable will be named buf.

In case if buffer state changes after method invocation, new state of example buffer will be displayed below the code snippet.

General

General methods of a buffer.

getLength

---

Returns length of this buffer.

Arguments	Return Type
Buffer:getLength()	integer

print(buf:getLength()) --> 4

getPosition

---

Returns current pointer position.

Arguments	Return Type
getPosition()	integer

print(buf:getPosition()) --> 0

setPosition

---

Sets current pointer position. Position will be clamped between 0 and current buffer length.

@see getLength

Arguments
setPosition(position integer)

buf:setPosition(2)

AA	BB	CC	EE
		^^

clear

---

Clears this buffer and sets it's pointer position to 0.

Arguments
clear()

buf:clear()

This buffer is empty, no data to display.

available

---

Returns amount of bytes available to read.

Arguments	Return Type
available()	integer

print(buf:available()) --> 4

getMaxCapacity

---

Returns max buffer capacity.

Arguments	Return Type
getMaxCapacity()	integer

print(buf:getMaxCapacity()) --> 1024000

ⓘ Note

This is an output for avatars in unmodified Default permissions group

close

---

Closes this buffer, tells garbage collector to free memory used by it. After closing buffer is unable to use, and any usage attempt will cause an error.

Arguments
close()

buf:close()
buf:read() --! Throws an error with message "This byte buffer is closed and cant be used anymore"

@see read

isClosed

---

Checks if this buffer is closed.

Arguments	Return Type
isClosed()	boolean

buf:close()
print(buf:isClosed())

@see close

Read methods

Methods of buffer related to reading data.

read

---

Reads a byte from this buffer and moves pointer by 1.

Arguments	Return Type
read()	byte

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

AA	BB	CC	EE
	^^

readShort

---

Reads a short from this buffer and moves pointer by 2.

Arguments	Return Type
readShort()	short

print(buf:readShort()) --> -21829

AA	BB	CC	EE
		^^

readUShort

---

Reads a ushort from this buffer and moves pointer by 2.

Arguments	Return Type
readUShort()	ushort

print(buf:readUShort()) --> 43707

AA	BB	CC	EE
		^^

readInt

---

Reads an int from this buffer and moves pointer by 4.

Arguments	Return Type
readInt()	int

print(buf:readInt()) --> -1430532899

AA	BB	CC	EE
				^^

readLong

---

Reads a long from this buffer and moves pointer by 8.

Arguments	Return Type
readLong()	long

print(buf:readLong()) --> -6144092017057071104

AA	BB	CC	EE
				^^

readFloat

---

Reads a float from this buffer and moves pointer by 4.

Arguments	Return Type
readFloat()	float

print(buf:readFloat()) --> -3.336003e-13

AA	BB	CC	EE
				^^

readDouble

---

Reads a double from this buffer and moves pointer by 8.

Arguments	Return Type
readDouble()	double

print(buf:readDouble()) --> -7.757649e-103

AA	BB	CC	EE
				^^

readShortLE

---

Reads a short in little-endian format from this buffer and moves pointer by 2.

Arguments	Return Type
readShortLE()	short

print(buf:readShortLE()) --> -17494

AA	BB	CC	EE
		^^

readUShortLE

---

Reads a ushort in little-endian format from this buffer and moves pointer by 2.

Arguments	Return Type
readUShortLE()	ushort

print(buf:readUShortLE()) --> 48042

AA	BB	CC	EE
		^^

readIntLE

---

Reads an int in little-endian format from this buffer and moves pointer by 4.

Arguments	Return Type
readIntLE()	int

print(buf:readIntLE()) --> -573785174

AA	BB	CC	EE
				^^

readLongLE

---

Reads a long in little-endian format from this buffer and moves pointer by 8.

Arguments	Return Type
readLongLE()	long

print(buf:readLongLE()) --> 3721182122

AA	BB	CC	EE
				^^

readFloatLE

---

Reads a float in little-endian format from this buffer and moves pointer by 4.

Arguments	Return Type
readFloatLE()	float

print(buf:readFloatLE()) --> -1.844071e+18

AA	BB	CC	EE
				^^

readDoubleLE

---

Reads a double in little-endian format from this buffer and moves pointer by 8.

Arguments	Return Type
readDoubleLE()	double

print(buf:readDoubleLE()) --> 1.838508e-314

AA	BB	CC	EE
				^^

readString

---

Reads a string from this buffer.

Arguments	Return Type	Description
readString()	string	Reads all bytes from current buffer position to end of the buffer and returns them in form of UTF-8 string.
readString(length integer)	string	Reads specified amount of bytes from current buffer position and returns them in form of UTF-8 string. If length is more than available bytes amount, length will be clamped.
readString(length integer, encoding BufferEncoding)	string	Reads specified amount of bytes from current buffer position and returns them in form of string with specified encoding. If length is more than available bytes amount, length will be clamped.

print(buf:readString()) --> "ª»ÌÝ"

AA	BB	CC	EE
				^^

readBase64

---

Reads a Base64 string from this buffer.

Arguments	Return Type	Description
readBase64()	string	Reads all bytes from current buffer position to end of the buffer and returns them in form of Base64 encoded byte array.
readBase64(length integer)	string	Reads specified amount of bytes from current buffer position and returns them in form of Base64 encoded byte array. If length is more than available bytes amount, length will be clamped.

print(buf:readBase64()) --> "qrvM7g=="

AA	BB	CC	EE
				^^

readByteArray

---

Reads a byte array from this buffer.

Arguments	Return Type	Description
readByteArray()	string	Reads all bytes from current buffer position to end of the buffer and returns them in form of Lua string byte array.
readByteArray(length integer)	string	Reads specified amount of bytes from current buffer position and returns them in form of Lua string byte array. If length is more than available bytes amount, length will be clamped.

print(buf:readByteArray()) --> [raw data]

AA	BB	CC	EE
				^^