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
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. |
str
|
N | A string primitive that can be stored in buffers. |
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
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
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 |
|
^^
|