Module BlobWriter

Writes binary data to memory.

Functions

new ([sizeOrByteOrder[, size]]) Creates a new BlobWriter instance.
write (value) Writes a value to the output buffer.
number (value) Writes a Lua number to the output buffer.
bool (value) Writes a boolean value to the output buffer.
string (value) Writes a string to the output buffer.
u8 (value) Writes an unsigned 8 bit value to the output buffer.
s8 (value) Writes a signed 8 bit value to the output buffer.
u16 (value) Writes an unsigned 16 bit value to the output buffer.
s16 (value) Writes a signed 16 bit value to the output buffer.
u32 (value) Writes an unsigned 32 bit value to the output buffer.
s32 (value) Writes a signed 32 bit value to the output buffer.
vu32 (value) Writes a length-encoded unsigned 32 bit integer value.
vs32 (value) Writes a length-encoded signed 32 bit integer.
u64 (value) Writes an unsigned 64 bit value to the output buffer.
s64 (value) Writes a signed 64 bit value to the output buffer.
f32 (value) Writes a 32 bit floating point value to the output buffer.
f64 (value) Writes a 64 bit floating point value to the output buffer.
raw (value[, length]) Writes raw binary data to the output buffer.
cstring (value) Writes a string to the output buffer, followed by a null byte.
cdata (value[, typename[, length]]) Writes a cdata object to the output buffer.
table (value) Writes a table to the output buffer.
array (valueType, values[, writeLength]) Writes a sequential table of values.
pack (format, ...) Writes data according to a format string.
clear ([size]) Clears the blob and discards all buffered data.
tostring () Returns the current buffer contents as a string.
length () Returns the number of bytes stored in the blob.
size () Returns the size of the write buffer in bytes
vu32size (value) Returns the number of bytes required to store an unsigned 32 bit value when written by vu32.
vs32size (value) Returns the number of bytes required to store a signed 32 bit value when written by vs32.
setByteOrder (byteOrder) Sets the order in which multi-byte values will be written.
resize (newSize) Resizes the write buffer.


Functions

new ([sizeOrByteOrder[, size]])
Creates a new BlobWriter instance.

Parameters:

  • sizeOrByteOrder number or string optional Size or byte order

    Byte order: Use le or < for little endian; be or > for big endian; host, = or nil to use the host’s native byteOrder (default)

  • size number optional The initial size of the blob in bytes. Default is 1024. Will grow automatically when required.

Returns:

    BlobWriter A new BlobWriter instance.

See also:

Usage:

  • writer = BlobWriter!
  • writer = BlobWriter('<', 1000)
write (value)
Writes a value to the output buffer. Determines the type of the value automatically.

Supported value types are number, string, boolean, table, and cdata.

Parameters:

  • value the value to write

Returns:

    BlobWriter self
number (value)
Writes a Lua number to the output buffer.

Parameters:

  • value number The number to write

Returns:

    BlobWriter self
bool (value)
Writes a boolean value to the output buffer.

The value is written as an unsigned 8 bit value (true = 1, false = 0)

Parameters:

  • value bool The boolean value to write

Returns:

    BlobWriter self
string (value)
Writes a string to the output buffer.

Stores the length of the string as a vu32 field before the actual string data.

Parameters:

  • value string The string to write

Returns:

    BlobWriter self
u8 (value)
Writes an unsigned 8 bit value to the output buffer.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self
s8 (value)
Writes a signed 8 bit value to the output buffer.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self
u16 (value)
Writes an unsigned 16 bit value to the output buffer.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self
s16 (value)
Writes a signed 16 bit value to the output buffer.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self
u32 (value)
Writes an unsigned 32 bit value to the output buffer.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self
s32 (value)
Writes a signed 32 bit value to the output buffer.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self
vu32 (value)
Writes a length-encoded unsigned 32 bit integer value.

The value is written in an encoded format. The length depends on the value; larger values need more space.

Space requirements:

lower bound upper bound # bytes
0 127 1
128 16383 2
16384 2097151 3
2097151 268435455 4
268435456 4294967295 5

vu32size computes the space requirement for an unsigned integer value.

Parameters:

  • value number The unsigned integer value to write

Returns:

    BlobWriter self

See also:

vs32 (value)
Writes a length-encoded signed 32 bit integer.

The value is written in an encoded format. The length depends on the value; larger values need more space.

Space requirements:

lower bound upper bound # bytes
-2147483648 -268435455 5
-268435454 -2097151 4
-2097150 -16383 3
-16382 -127 2
-126 126 1
127 16382 2
16383 2097150 3
2097151 268435454 4
268435455 2147483647 5

vs32size computes the space requirement for a signed integer value.

Parameters:

  • value number The signed integer value to write

Returns:

    BlobWriter self

See also:

u64 (value)
Writes an unsigned 64 bit value to the output buffer.

Lua numbers are only accurate for values < 2 ^ 53. Use the LuaJIT ULL suffix to write large numbers.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self

Usage:

    writer:u64(72057594037927936ULL)
s64 (value)
Writes a signed 64 bit value to the output buffer.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self

See also:

f32 (value)
Writes a 32 bit floating point value to the output buffer.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self
f64 (value)
Writes a 64 bit floating point value to the output buffer.

Parameters:

  • value number The value to write

Returns:

    BlobWriter self
raw (value[, length])
Writes raw binary data to the output buffer.

Parameters:

  • value string or cdata A string or cdata with the data to write
  • length number optional Length of data. Not required for strings and cdata with discernable size (i.e. cdata that does not contain pointers). See also ffi.sizeof.

Returns:

    BlobWriter self
cstring (value)
Writes a string to the output buffer, followed by a null byte.

Parameters:

  • value string The string to write

Returns:

    BlobWriter self
cdata (value[, typename[, length]])
Writes a cdata object to the output buffer. See examples/cdata.lua for example code on how to implement transparent cdata serialization.

Parameters:

  • value cdata A cdata object
  • typename string optional The type name of the cdata object as declared with ffi.cdef. Not required when the metatype has a __typename field
  • length number optional Length of data. Not required for cdata with discernable size (i.e. cdata that does not contain pointers, or has a metatype with a __serialize method). See also ffi.sizeof.

Returns:

    BlobWriter self
table (value)
Writes a table to the output buffer.

Supported field types are number, string, bool and table. Functions are ignored. Cyclic references throw an error.

Parameters:

  • value table The table to write

Returns:

    BlobWriter self
array (valueType, values[, writeLength])
Writes a sequential table of values. All values must be of the same type.

Parameters:

  • valueType string Type of the values in the array

    Valid types are s8, u8, s16, u16, s32, u32, vs32, vu32, s64, u64, f32, f64, number, string, bool, cstring, table, and cdata.

    Stores the array length as a vu32 encoded value before the actual table values (see parameter writeLength)

  • values table A sequential table of values of type valueType

    Maximum allowed length is 2 ^ 32 - 1 values. Behavior is undefined for table keys that are not sequential, or not starting at index 1.

  • writeLength boolean optional If false, no preceding length information will be written (default true)

Returns:

    BlobWriter self
pack (format, ...)
Writes data according to a format string.

Parameters:

  • format string

    Data format descriptor string. The format string syntax is loosely based on the format that Lua 5.3’s string.pack accepts, but does not implement all features and uses fixed instead of native data sizes.

    Supported format specifiers:

    • Byte order:
      • <: little endian
      • >: big endian
      • =: host endian, default

      Byte order can be switched any number of times in a format string.

    • Integer types:
      • b / B: signed/unsigned 8 bits
      • h / H: signed/unsigned 16 bits
      • l / L: signed/unsigned 32 bits
      • v / V: signed/unsigned variable length 32 bits (see vs32 / vu32)
      • q / Q: signed/unsigned 64 bits
    • Boolean:
      • y: 8 bits boolean value
    • Floating point types:
      • f: 32 bits floating point
      • d, n: 64 bits floating point
    • String types:
      • z: zero terminated string
      • s: string with preceding length information. Length is stored as a vu32 encoded value
    • Raw data:
      • c[length]: Raw binary data
    • Table:
      • t: table as written by table
    • cdata:
      • C: cdata as written by cdata. Supports only ctypes that have a metatable with serialization information
  • ... values to write

Returns:

    BlobWriter self

See also:

Usage:

    writer:pack('Bfy', 255, 23.0, true)
clear ([size])
Clears the blob and discards all buffered data.

Parameters:

  • size number optional Set the writer buffer size to this value. If nil, the currently allocated buffer is reused.

Returns:

    BlovWriter self
tostring ()
Returns the current buffer contents as a string.

Returns:

    string A string with the current buffer contents
length ()
Returns the number of bytes stored in the blob.

Returns:

    number The number of bytes stored in the blob
size ()
Returns the size of the write buffer in bytes

Returns:

    number Write buffer size in bytes
vu32size (value)
Returns the number of bytes required to store an unsigned 32 bit value when written by vu32.

Parameters:

  • value number The unsigned 32 bit value to write

Returns:

    number The number of bytes required by vu32 to store value
vs32size (value)
Returns the number of bytes required to store a signed 32 bit value when written by vs32.

Parameters:

  • value number The signed 32 bit value to write

Returns:

    number The number of bytes required by vs32 to store value
setByteOrder (byteOrder)
Sets the order in which multi-byte values will be written.

Parameters:

  • byteOrder string Byte order

    Can be either le or < for little endian, be or > for big endian, or host or nil for native host byte order.

Returns:

    BlobWriter self
resize (newSize)
Resizes the write buffer.

Data currently in the buffer is preserved. If the new size is smaller than the current length of the data, the data will be truncated.

Parameters:

  • newSize number The new size of the write buffer

Returns:

    BlobWriter self
generated by LDoc 1.4.6 Last updated 2021-02-13 23:25:51