BitField

A simple bit32 library to support bit fields.

Why BitField?

Here is how boolean flags would be represented normally vs with a bit field:

-- Avoid this
local skins = {
	Default = true,
	Red = false,
	Yellow = true,
	Blue = true,
	White = false
}

-- Use a single integer instead!
local skins = 13 -- 0b01101

Both store fundamentally the same data, but storing boolean data in an integer optimizes memory usage.

Documentation

-- Creating a bit field
BitField.new(list of keys) -> new BitField object
local field = BitField.new {"a", "b", "c", "d"} -- Put your flag names / keys here, max 32 keys
-- You can change a flag name later on, and the data won't be affected as long as the order of the flags remains the same

-- Getting the index of a key
field.KeyIndex[key] -> index
print(field.KeyIndex["a"]) -- 1 (0b0001)
print(field.KeyIndex["b"]) -- 2 (0b0010)
print(field.KeyIndex["c"]) -- 4 (0b0100)
print(field.KeyIndex["d"]) -- 8 (0b1000)

-- Getting the key of an index
field.KeyIndex[index] -> key
print(field.IndexKey[1]) -- a
print(field.IndexKey[2]) -- b
print(field.IndexKey[4]) -- c
print(field.IndexKey[8]) -- d

local data = 5 -- 0b0101
--      Flag order: dcba

-- Checking if the flag in a data field is enabled
field:Get(data, key) -> boolean
print(field:Get(data, "a")) -- true
print(field:Get(data, "b")) -- false

-- Setting the value of a flag in a data field
field:Set(data, key, value) -> new data field
print(field:Set(data, "a", false)) -- 4 (0b0100)
print(field:Set(data, "b", true)) -- 7 (0b0111)

-- Adding a flag in a data field
field:Add(data, key) -> new data field
print(field:Add(data, "b")) -- 7 (0b0111)
print(field:Add(data, "a")) -- 5 (0b0101)

-- Toggling a flag in a data field
field:Toggle(data, key) -> new data field
print(field:Toggle(data, "a")) -- 4 (0b0100)

-- Creating a new data field with specified flags enabled
field:Encode(list of keys) -> new data field
print(field:Encode {"a", "b"}) -- 3 (0b0011)

-- Getting a list of all flags enabled in a data field
field:Decode(data) -> list of keys
print(field:Decode(data)) -- {"a", "c"}

-- Checking if the data field has any flags enabled
field:HasAny(data) -> boolean
print(field:HasAny(0b0000)) -- false
print(field:HasAny(0b0111)) -- true
print(field:HasAny(0b1111)) -- true

-- Checking if all the flags in a data field are enabled
field:HasAll(data) -> boolean
print(field:HasAll(0b0000)) -- false
print(field:HasAll(0b0111)) -- false
print(field:HasAll(0b1111)) -- true

-- Checking if all the flags in a data field are disabled
field:HasNone(data) -> boolean
print(field:HasNone(0b0000)) -- true
print(field:HasNone(0b0111)) -- false
print(field:HasNone(0b1111)) -- false