struct

This library provides a high level wrapper around LuaJIT's C structs. The main benefit to using structs over Lua tables is performance, as they compile efficiently. They can also be shared between addon instances, as well as services and addons, using the shared library's server and client modules. An additional benefit is strict member and type checking using LuaJIT's native struct evaluation.

The drawback is the typical inflexibility of C structs. New data fields cannot be added at runtime, and existing fields cannot be removed. The type of each field is fixed and cannot be changed, and sizes are constant, which is especially relevant to string fields.

Some inflexibilities are worked around by this library, using metamethods on C structs, which is a feature LuaJIT provides. They are explained on the struct_object page.

This library uses ftypes to describe structs. The ftype refers to the type description (the result of struct.struct and other types described on its own page), whereas struct_object refers to the actual cdata instance.

While this library tries to abstract away the low level nature of C structs a certain understanding of the native mechanics is still helpful.

local struct = require('struct')

❗ Dependency Required

To use this library, you must include struct in the manifest.xml file for your package:

<dependency>struct</dependency>

Tables

The struct table has the following main entries. Type entries are detailed on the ftype page.

• struct.struct Creates a new struct type with the provided fields
• struct.array Creates a new array type with the provided base type
• struct.new Creates a struct_object with the provided ftype
• struct.from_ptr Creates a struct_object with the provided ftype from the provided pointer
• struct.name Names the given ftype
• struct.metatype Assigns a metatype to the given ftype
• struct.copy Creates a memberwise copy of the cdata object, according to the provided ftype
• struct.declare Forward declares a name so it can be used as a reference in an ftype without full definition
• struct.tag Creates an ftype with a provided tag

---

struct.struct

Creates an struct ftype based on the provided fields.

Definition

function struct.struct(info : table = {}, fields : struct_definition) : ftype

Parameters

info table [default: {}]

A table containing metadata for the type definition.

fields struct_definition

A table containing field information.

Return

ftype ftype

The resulting type description.

struct.array

Creates an array ftype based on the provided fields.

Definition

function struct.array(info : table = {}, base : ftype, count : number | '*') : ftype

Parameters

info table [default: {}]

A table containing metadata for the type definition.

base ftype

The base type of the array.

count number | '*'

The element count of the array. '*' for a VLA.

Return

ftype ftype

The resulting type description.

struct.new

Creates a struct object from a given ftype.

Definition

function struct.new(ftype : ftype, ...sizes : number) : struct_object

Parameters

ftype ftype

The type description to create the object from.

...sizes number

Size arguments for VLA structs/arrays.

Return

struct_object struct_object

The resulting cdata struct.

struct.from_ptr

Creates a struct object from a given ftype at the provided address. Does not initialize memory, so whatever data exists there is part of the struct. Useful for data sharing.

Definition

function struct.from_ptr(ftype : ftype, ptr : cdata<ptr> | number) : struct_object

Parameters

ftype ftype

The type description to create the object from.

ptr cdata | number

A pointer or integer address to create the struct at.

Return

struct_object struct_object

The resulting cdata struct.

struct.name

Assigns a name to the provided ftype via typedef. This is only really useful when deserializing data, as struct.struct and struct.array do it automatically.

Definition

function struct.name(ftype : ftype, name : string = nil)

Parameters

ftype ftype

The ftype to name.

name string [default: nil]

The name to assign to the ftype. If not provided will either use the name that is already present on the type, if not found will generate one dynamically. This dynamic generation is used for a vast majority of types in our library and such names are encountered often (they start with _gensym_).

Return

This function does not return any values.

struct.metatype

Assigned a metatable to structs and arrays. The effects of the metatable are detailed on the struct object page.

Definition

function struct.metatype(ftype : ftype)

Parameters

ftype ftype

The ftype to assign a metatable to.

Return

This function does not return any values.

struct.copy

Performs a binary copy of a struct, given the specified ftype. The ftype is not needed for a raw copy, but without it the new struct will be a raw C struct, missing the metatable, and all the conveniences that come with it.

Definition

function struct.copy(object : cdata, ftype : ftype = nil) : struct_object

Parameters

object cdata

The cdata object to copy.

ftype ftype [default: nil]

The ftype to use as a template. If omitted, will simply perform a raw copy.

Return

A binary copy of the provided cdata object.

struct.declare

Forward declares a name for use in a nested ftype definition.

Definition

function struct.declare(name : string)

Parameters

name string

The name to declare the struct as.

Return

This function does not return any values.

struct.tag

Creates an ftype with the specified tag. A tag does effectively nothing but can be used to disambiguate types of the same underlying ctype.

Definition

function struct.tag(ftype : ftype, tag : string) : ftype

Parameters

ftype ftype

The type description to base the tagged type on.

tag string

The tag to assign to it.

Return

ftype ftype

The type description with the specified tag.