Skip to content

DataBlock

Type

DataBlock

A DataBlock is a simple block of binary data, with various functions to help deal with reading/writing raw binary data to the block.

Properties

Property Type Description
size integer The size of the block (in bytes)
crc integer The CRC of the data

Constructors

DataBlock.new()

Creates a new, empty DataBlock (size will be 0).

DataBlock.new(size)

Creates a new DataBlock of size bytes, with each byte set to 0.

Parameters

  • size (integer): The size (in bytes) of the block

Functions

Overview

General

AsString() -> string SetData(data) Clear() Resize(newSize, preserveData) -> boolean Copy(other) -> boolean CopyTo(other, [offset], [length]) -> boolean ImportFile(path, [offset], [length]) -> boolean ExportFile(path, [offset], [length]) -> boolean FillData(value) -> boolean

Reading

ReadInt8(offset) -> integer ReadUInt8(offset) -> integer ReadInt16(offset) -> integer ReadUInt16(offset) -> integer ReadInt32(offset) -> integer ReadUInt32(offset) -> integer ReadInt64(offset) -> integer ReadUInt64(offset) -> integer ReadString(offset, length, [nullTerminated]) -> string

Writing

Attention

Note that these functions overwrite data, they do not insert

WriteInt8(offset, value, allowExpand) -> boolean WriteUInt8(offset, value, allowExpand) -> boolean WriteInt16(offset, value, allowExpand) -> boolean WriteUInt16(offset, value, allowExpand) -> boolean WriteInt32(offset, value, allowExpand) -> boolean WriteUInt32(offset, value, allowExpand) -> boolean WriteInt64(offset, value, allowExpand) -> boolean WriteUInt64(offset, value, allowExpand) -> boolean WriteString(offset, value, allowExpand) -> boolean

AsString

Gets the data as a lua string.

Returns

  • string: The data as a string

SetData

Sets the data contained within this DataBlock to the given string, resizing if necessary.

Parameters

  • data (string): The data to import

Example

local data = DataBlock.new(10)
App.LogMessage('Size is ' .. data.size) -- 10

local str = 'This is a string that is 43 characters long'
data:SetData(str)
App.LogMessage('Size is ' .. data.size) -- 43

Clear

Clears all data and sets size to 0.

Resize

Resizes the block to newSize.

Parameters

  • newSize (integer): The new size of the block. If 0 the resize will fail (use Clear instead)
  • preserveData (boolean): If true, existing byte values in the block will be preserved, otherwise all bytes will be set to 0

Returns

  • boolean: true if the resize was successful

Copy

Copies data from another DataBlock.

Parameters

  • other (DataBlock): The DataBlock to copy data from

Returns

  • boolean: true on success

CopyTo

Copies data to another DataBlock.

Parameters

  • other (DataBlock): The DataBlock to copy data to
  • [offset] (integer): Only copy bytes starting from this offset. Default is 0
  • [length] (integer): Copy this number of bytes. Default is 0, which means all bytes to the end of the block will be copied

Returns

  • boolean: true on success

ImportFile

Imports data from a file on disk at path.

Parameters

  • path (string): The path to the file on disk
  • [offset] (integer): Only import data starting from this offset in the file. Default is 0
  • [length] (integer): Import this number of bytes. Default is 0, which means all bytes to the end of the file will be imported

Returns

  • boolean: true on success

ExportFile

Exports data to a file on disk at path.

Parameters

  • path (string): The path to the file on disk. The file will be created if it doesn't already exist
  • [offset] (integer): Only export data starting from this offset. Default is 0
  • [length] (integer): Export this number of bytes. Default is 0, which means all bytes to the end of the block will be exported

Returns

  • boolean: true on success

FillData

Sets all bytes in the block to value.

Parameters

  • value (integer): The value to set all bytes to (0-255)

Returns

  • boolean: false if the block is empty

ReadInt8

Reads the byte at offset bytes into the block as an 8-bit (1 byte) signed integer.

Parameters

  • offset (integer): The offset to the start of the data to read

Returns

  • integer: The value read, or nil if the offset was invalid

ReadUInt8

Reads the byte at offset bytes into the block as an 8-bit (1 byte) unsigned integer.

Parameters

  • offset (integer): The offset to the start of the data to read

Returns

  • integer: The value read, or nil if the offset was invalid

ReadInt16

Reads the bytes beginning at offset bytes into the block as a 16-bit (2 byte) signed integer.

Parameters

  • offset (integer): The offset to the start of the data to read

Returns

  • integer: The value read, or nil if the offset was invalid

ReadUInt16

Reads the bytes beginning at offset bytes into the block as a 16-bit (2 byte) unsigned integer.

Parameters

  • offset (integer): The offset to the start of the data to read

Returns

  • integer: The value read, or nil if the offset was invalid

ReadInt32

Reads the bytes beginning at offset bytes into the block as a 32-bit (4 byte) signed integer.

Parameters

  • offset (integer): The offset to the start of the data to read

Returns

  • integer: The value read, or nil if the offset was invalid

ReadUInt32

Reads the bytes beginning at offset bytes into the block as a 32-bit (4 byte) unsigned integer.

Parameters

  • offset (integer): The offset to the start of the data to read

Returns

  • integer: The value read, or nil if the offset was invalid

ReadInt64

Reads the bytes beginning at offset bytes into the block as a 64-bit (8 byte) signed integer.

Parameters

  • offset (integer): The offset to the start of the data to read

Returns

  • integer: The value read, or nil if the offset was invalid

ReadUInt64

Reads the bytes beginning at offset bytes into the block as a 64-bit (8 byte) unsigned integer.

Parameters

  • offset (integer): The offset to the start of the data to read

Returns

  • integer: The value read, or nil if the offset was invalid

ReadString

Reads length bytes beginning at offset bytes into the block as a string.

Parameters

  • offset (integer): The offset to the start of the data to read
  • length (integer): The number of bytes to read
  • [nullTerminated] (boolean): If true, the string will end at the first 0 after offset, or length bytes after offset, whichever comes first. Default is false

Returns

  • string: The string that was read, or an empty string if the offset was invalid

Example

local data = DataBlock.new()
data:SetData('one two\0three')

local one = data:ReadString(0, 3)
local three = data:ReadString(8, 5)

App.LogMessage(one .. ' (' .. #one .. ')')     -- one (3)
App.LogMessage(three .. ' (' .. #three .. ')') -- three (5)

local twoThree = data:ReadString(4, 9, false)
local twoThreeNT = data:ReadString(4, 9, true)

App.LogMessage('twoThree: ' .. #twoThree)     -- twoThree: 9
App.LogMessage('twoThreeNT: ' .. #twoThreeNT) -- twoThreeNT: 3

WriteInt8

Writes value as an 8-bit (1 byte) signed integer at offset bytes into the block.

Parameters

  • offset (integer): The offset to write data to
  • value (integer): The value to write
  • allowExpand (boolean): If true, the data will be expanded to accomodate the written value if it goes past the end of the data, otherwise nothing will be written if offset is invalid

Returns

  • boolean: true if the value was written successfully

WriteUInt8

Writes value as an 8-bit (1 byte) unsigned integer at offset bytes into the block.

Parameters

  • offset (integer): The offset to write data to
  • value (integer): The value to write
  • allowExpand (boolean): If true, the data will be expanded to accomodate the written value if it goes past the end of the data, otherwise nothing will be written if offset is invalid

Returns

  • boolean: true if the value was written successfully

WriteInt16

Writes value as a 16-bit (2 byte) signed integer at offset bytes into the block.

Parameters

  • offset (integer): The offset to write data to
  • value (integer): The value to write
  • allowExpand (boolean): If true, the data will be expanded to accomodate the written value if it goes past the end of the data, otherwise nothing will be written if offset is invalid

Returns

  • boolean: true if the value was written successfully

WriteUInt16

Writes value as a 16-bit (2 byte) unsigned integer at offset bytes into the block.

Parameters

  • offset (integer): The offset to write data to
  • value (integer): The value to write
  • allowExpand (boolean): If true, the data will be expanded to accomodate the written value if it goes past the end of the data, otherwise nothing will be written if offset is invalid

Returns

  • boolean: true if the value was written successfully

WriteInt32

Writes value as a 32-bit (4 byte) signed integer at offset bytes into the block.

Parameters

  • offset (integer): The offset to write data to
  • value (integer): The value to write
  • allowExpand (boolean): If true, the data will be expanded to accomodate the written value if it goes past the end of the data, otherwise nothing will be written if offset is invalid

Returns

  • boolean: true if the value was written successfully

WriteUInt32

Writes value as a 32-bit (4 byte) unsigned integer at offset bytes into the block.

Parameters

  • offset (integer): The offset to write data to
  • value (integer): The value to write
  • allowExpand (boolean): If true, the data will be expanded to accomodate the written value if it goes past the end of the data, otherwise nothing will be written if offset is invalid

Returns

  • boolean: true if the value was written successfully

WriteInt64

Writes value as a 64-bit (8 byte) signed integer at offset bytes into the block.

Parameters

  • offset (integer): The offset to write data to
  • value (integer): The value to write
  • allowExpand (boolean): If true, the data will be expanded to accomodate the written value if it goes past the end of the data, otherwise nothing will be written if offset is invalid

Returns

  • boolean: true if the value was written successfully

WriteUInt64

Writes value as a 64-bit (8 byte) unsigned integer at offset bytes into the block.

Parameters

  • offset (integer): The offset to write data to
  • value (integer): The value to write
  • allowExpand (boolean): If true, the data will be expanded to accomodate the written value if it goes past the end of the data, otherwise nothing will be written if offset is invalid

Returns

  • boolean: true if the value was written successfully

WriteString

Writes the given string value at offset bytes into the block.

Parameters

  • offset (integer): The offset to write data to
  • value (string): The value to write
  • allowExpand (boolean): If true, the data will be expanded to accomodate the written value if it goes past the end of the data, otherwise nothing will be written if offset is invalid

Returns

  • boolean: true if the value was written successfully