Buffer: Difference between revisions

Latest revision as of 10:57, 29 September 2024

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`	`DD`
`^^`

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`	`DD`
	`^^`

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`	`DD`
		`^^`

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`	`BB`	`CC`	`DD`
				`^^`

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

@see read, readString

`AA`	`BB`	`CC`	`DD`
				`^^`

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

`AA`	`BB`	`CC`	`DD`
				`^^`

buf:writeUShort(65535)

@see writeUShort

This is how our buffer will look like now:

`AA`	`BB`	`CC`	`DD`	`FF`	`FF`
						`^^`

Buffer methods

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

`AA`	`BB`	`CC`	`DD`
`^^`

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`	`DD`
		`^^`

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()) --> true

@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`	`DD`
	`^^`

readShort

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

Arguments	Return Type
`readShort()`	`short`

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

`AA`	`BB`	`CC`	`DD`
		`^^`

readUShort

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

Arguments	Return Type
`readUShort()`	`ushort`

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

`AA`	`BB`	`CC`	`DD`
		`^^`

readInt

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

Arguments	Return Type
`readInt()`	`int`

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

`AA`	`BB`	`CC`	`DD`
				`^^`

readLong

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

Arguments	Return Type
`readLong()`	`long`

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

`AA`	`BB`	`CC`	`DD`
				`^^`

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`	`DD`
				`^^`

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`	`DD`
				`^^`

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`	`DD`
		`^^`

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`	`DD`
		`^^`

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`	`DD`
				`^^`

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`	`DD`
				`^^`

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`	`DD`
				`^^`

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`	`DD`
				`^^`

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`	`DD`
				`^^`

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`	`DD`
				`^^`

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`	`DD`
				`^^`

Write methods

write

Writes a byte to this buffer and moves pointer by 1.

Arguments
`write(value byte)`

buf:write(255)

`FF`	`BB`	`CC`	`DD`
	`^^`

writeShort

Writes a short to this buffer and moves pointer by 2.

Arguments
`writeShort(value short)`

buf:writeShort(32767)

`7F`	`FF`	`CC`	`DD`
		`^^`

writeUShort

Writes a ushort to this buffer and moves pointer by 2.

Arguments
`writeUShort(value ushort)`

buf:writeUShort(32767)

`7F`	`FF`	`CC`	`DD`
		`^^`

writeInt

Writes an int to this buffer and moves pointer by 4.

Arguments
`writeInt(value int)`

buf:writeInt(2147483647)

`7F`	`FF`	`FF`	`FF`
				`^^`

writeLong

Writes a long to this buffer and moves pointer by 8.

Arguments
`writeLong(value long)`

buf:writeLong(9223372036854775807)

`7F`	`FF`	`FF`	`FF`	`FF`	`FF`	`FF`	`FF`
								`^^`

writeFloat

Writes a float to this buffer and moves pointer by 4.

Arguments
`writeFloat(value float)`

buf:writeFloat(50.0)

`42`	`48`	`00`	`00`
				`^^`

writeDouble

Writes a double to this buffer and moves pointer by 8.

Arguments
`writeDouble(value double)`

buf:writeDouble(50.0)

`40`	`49`	`00`	`00`	`00`	`00`	`00`	`00`
								`^^`

writeShortLE

Writes a short in little-endian format to this buffer and moves pointer by 2.

Arguments
`writeShortLE(value short)`

buf:writeShortLE(32767)

`FF`	`7F`	`CC`	`DD`
		`^^`

writeUShortLE

Writes a ushort in little-endian format to this buffer and moves pointer by 2.

Arguments
`writeUShortLE(value ushort)`

buf:writeUShortLE(32767)

`FF`	`7F`	`CC`	`DD`
		`^^`

writeIntLE

Writes an int in little-endian format to this buffer and moves pointer by 4.

Arguments
`writeIntLE(value int)`

buf:writeIntLE(2147483647)

`FF`	`FF`	`FF`	`7F`
				`^^`

writeLongLE

Writes a long in little-endian format to this buffer and moves pointer by 8.

Arguments
`writeLongLE(value long)`

buf:writeLongLE(9223372036854775807)

`FF`	`FF`	`FF`	`FF`	`FF`	`FF`	`FF`	`7F`
								`^^`

writeFloatLE

Writes a float in little-endian format to this buffer and moves pointer by 4.

Arguments
`writeFloatLE(value float)`

buf:writeFloatLE(50.0)

`00`	`00`	`48`	`42`
				`^^`

writeDoubleLE

Writes a double in little-endian format to this buffer and moves pointer by 8.

Arguments
`writeDoubleLE(value double)`

buf:writeDoubleLE(50.0)

`00`	`00`	`00`	`00`	`00`	`00`	`49`	`40`
								`^^`

writeString

Writes a string in buffer, and returns it's length in bytes.

Arguments	Return type	Description
`writeString(value string)`	integer	Writes a string in UTF-8 encoding.
`writeString(value string, encoding BufferEncoding)`	integer	Writes a string in specified encoding.

print(buf:writeString("Hello, world!")) --> 13

`48`	`65`	`6C`	`6C`	`6F`	`2C`	`20`	`77`	`6F`	`72`	`6C`	`64`	`21`
													`^^`

writeBase64

Decodes Base64 byte array and writes in to buffer. Returns amount of written bytes.

Arguments	Return type
`writeBase64(value string)`	integer

print(buf:writeBase64("TWVvdw==")) --> 4

`4D`	`65`	`6F`	`77`
				`^^`

writeByteArray

Write a lua string byte array to buffer. Returns amount of written bytes.

Arguments	Return type
`writeByteArray(value string)`	integer

print(buf:writeByteArray("\xAA\xBB\xCC\xDD")) --> 4

`AA`	`BB`	`CC`	`DD`
				`^^`

Streams

Methods for working with Input and Output streams

readFromStream

Reads provided stream, and writes it's data to this buffer. Returns amount of bytes written to buffer.

Arguments	Return type	Description
`readFromStream(stream InputStream)`	integer	Reads provided stream to either max capacity of buffer, or end of stream.
`readFromStream(stream InputStream, amount integer)`	integer	Trying to read specified amount of bytes from provided stream. Resulting amount of read bytes might be less than specified.

-- Opening resource from avatar resources
local is = resources:get("buf_read_test.txt")
-- Reading content of resource, printing it's length
print(buf:readFromStream(is)) --> 13
-- Resetting buffer position so it can read string from start
buf:setPosition(0)
-- Reading string
print(buf:readString()) --> "Hello, world!"
-- Closing input stream
is:close()

@see resources:get, setPosition, readString

`48`	`65`	`6C`	`6C`	`6F`	`2C`	`20`	`77`	`6F`	`72`	`6C`	`64`	`21`
													`^^`

writeToStream

Writes bytes from this buffer to provided output stream. Returns amount of bytes written to stream.

Arguments	Return type	Description
`writeToStream(stream OutputStream)`	integer	Writes all available bytes to provided stream.
`writeToStream(stream OutputStream, amount integer)`	integer	Writes specified amount of bytes from current position to provided stream.

-- Opening output stream with FileAPI
local os = file:openWriteStream("buf_write_test.txt")
-- Preparing future file content
buf:writeString("Hello, world!")
-- Resetting buffer position, so buffer can write data to stream from start
buf:setPosition(0)
-- Writing file data
buf:writeToStream(os)
-- Closing output stream
os:close()

@see file:openWriteStream, writeString, setPosition, OutputStream:close

`48`	`65`	`6C`	`6C`	`6F`	`2C`	`20`	`77`	`6F`	`72`	`6C`	`64`	`21`
													`^^`