From 24e2c151136fc7d565f9f9babcf24b199eb6c6f3 Mon Sep 17 00:00:00 2001 From: Alexander Gavrilov Date: Wed, 13 Jun 2012 11:00:54 +0400 Subject: [PATCH] Enhance docs on bitfield refs to cover a question raised on chat recently. --- LUA_API.rst | 11 ++++++++++- Lua API.html | 11 +++++++++-- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/LUA_API.rst b/LUA_API.rst index 9fb37375d..0736b02b7 100644 --- a/LUA_API.rst +++ b/LUA_API.rst @@ -219,12 +219,21 @@ Bitfield references ------------------- Bitfields behave like special fixed-size containers. -The ``_enum`` property points to the bitfield type. +Consider them to be something in between structs and +fixed-size vectors. +The ``_enum`` property points to the bitfield type. Numerical indices correspond to the shift value, and if a subfield occupies multiple bits, the ``ipairs`` order would have a gap. +Since currently there is no API to allocate a bitfield +object fully in GC-managed lua heap, consider using the +lua table assignment feature outlined below in order to +pass bitfield values to dfhack API functions that need +them, e.g. ``matinfo:matches{metal=true}``. + + Named types =========== diff --git a/Lua API.html b/Lua API.html index 1576652d6..568090a76 100644 --- a/Lua API.html +++ b/Lua API.html @@ -534,10 +534,17 @@ use #ref, or just

Bitfield references

Bitfields behave like special fixed-size containers. -The _enum property points to the bitfield type.

-

Numerical indices correspond to the shift value, +Consider them to be something in between structs and +fixed-size vectors.

+

The _enum property points to the bitfield type. +Numerical indices correspond to the shift value, and if a subfield occupies multiple bits, the ipairs order would have a gap.

+

Since currently there is no API to allocate a bitfield +object fully in GC-managed lua heap, consider using the +lua table assignment feature outlined below in order to +pass bitfield values to dfhack API functions that need +them, e.g. matinfo:matches{metal=true}.