struct - Windower/packages GitHub Wiki

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>

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

Creates an struct ftype based on the provided fields.

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

info table [default: {}]

A table containing metadata for the type definition.

fields struct_definition

A table containing field information.

ftype ftype

The resulting type description.

Creates an array ftype based on the provided fields.

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

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.

ftype ftype

The resulting type description.

Creates a struct object from a given ftype.

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

ftype ftype

The type description to create the object from.

...sizes number

Size arguments for VLA structs/arrays.

struct_object struct_object

The resulting cdata struct.

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.

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

ftype ftype

The type description to create the object from.

ptr cdata | number

A pointer or integer address to create the struct at.

struct_object struct_object

The resulting cdata struct.

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.

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

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_).

This function does not return any values.

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

function struct.metatype(ftype : ftype)

ftype ftype

The ftype to assign a metatable to.

This function does not return any values.

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.

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

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.

A binary copy of the provided cdata object.

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

function struct.declare(name : string)

name string

The name to declare the struct as.

This function does not return any values.

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

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

ftype ftype

The type description to base the tagged type on.

tag string

The tag to assign to it.

ftype ftype

The type description with the specified tag.