Class bitflags
Bitflags module.
The bitflag object makes it easy to manipulate flags in a bitmask.
It has metamethods that do the hard work, adding flags sets them, substracting
unsets them. Comparing flags checks if all flags in the second set are also set
in the first set. The has method checks if all flags in the second set are
also set in the first set, but behaves slightly different.
Indexing allows checking values or setting them by bit index (eg. 0-7 for flags in the first byte).
NOTE: unavailable flags (eg. Windows flags on a Posix system) should not be
omitted, but be assigned a value of 0. This is because the has method will
return false if the flags are checked and the value is 0.
See system.bitflag (the constructor) for extensive examples on usage.
Bit flags
| bitflag:has_all_of (subset) | Checks if all the flags in the given subset are set. |
| bitflag:has_any_of (subset) | Checks if any of the flags in the given subset are set. |
| bitflag:value () | Retrieves the numeric value of the bitflag object. |
| system.bitflag ([value=0]) | Creates a new bitflag object from the given value. |
Bit flags
Bitflag objects can be used to easily manipulate and compare bit flags.
These are primarily for use with the terminal functions, but can be used
in other places as well.
- bitflag:has_all_of (subset)
-
Checks if all the flags in the given subset are set.
If the flags to check has a value
0, it will always returnfalse. So if there are flags that are unsupported on a platform, they can be set to 0 and the has_all_of function will returnfalseif the flags are checked.Parameters:
- subset bitflag the flags to check for.
Returns:
-
boolean
true if all the flags are set, false otherwise.
Usage:
local sys = require 'system' local flags = sys.bitflag(12) -- b1100 local myflags = sys.bitflag(15) -- b1111 print(flags:has_all_of(myflags)) -- false, not all bits in myflags are set in flags print(myflags:has_all_of(flags)) -- true, all bits in flags are set in myflags
- bitflag:has_any_of (subset)
-
Checks if any of the flags in the given subset are set.
If the flags to check has a value
0, it will always returnfalse. So if there are flags that are unsupported on a platform, they can be set to 0 and the has_any_of function will returnfalseif the flags are checked.Parameters:
- subset bitflag the flags to check for.
Returns:
-
boolean
true if any of the flags are set, false otherwise.
Usage:
local sys = require 'system' local flags = sys.bitflag(12) -- b1100 local myflags = sys.bitflag(7) -- b0111 print(flags:has_any_of(myflags)) -- true, some bits in myflags are set in flags print(myflags:has_any_of(flags)) -- true, some bits in flags are set in myflags
- bitflag:value ()
-
Retrieves the numeric value of the bitflag object.
Returns:
-
number
the numeric value of the bitflags.
Usage:
local sys = require 'system' local flags = sys.bitflag() -- b0000 flags[0] = true -- b0001 flags[2] = true -- b0101 print(flags:value()) -- 5
- system.bitflag ([value=0])
-
Creates a new bitflag object from the given value.
Parameters:
- value number the value to create the bitflag object from. (default 0)
Returns:
-
bitflag
bitflag object with the given values set.
Usage:
local sys = require 'system' local flags = sys.bitflag(2) -- b0010 -- get state of individual bits print(flags[0]) -- false print(flags[1]) -- true -- set individual bits flags[0] = true -- b0011 print(flags:value()) -- 3 print(flags) -- "bitflags: 3" -- adding flags (bitwise OR) local flags1 = sys.bitflag(1) -- b0001 local flags2 = sys.bitflag(2) -- b0010 local flags3 = flags1 + flags2 -- b0011 -- substracting flags (bitwise AND NOT) print(flags3:value()) -- 3 flag3 = flag3 - flag3 -- b0000 print(flags3:value()) -- 0 -- comparing flags local flags4 = sys.bitflag(7) -- b0111 local flags5 = sys.bitflag(255) -- b11111111 print(flags5 ~= flags4) -- true, not the same flags local flags6 = sys.bitflag(7) -- b0111 print(flags6 == flags4) -- true, same flags -- comparison of subsets local flags7 = sys.bitflag(0) -- b0000 local flags8 = sys.bitflag(3) -- b0011 local flags9 = sys.bitflag(7) -- b0111 print(flags9:has_all_of(flags8)) -- true, flags8 bits are all set in flags9 print(flags8:has_any_of(flags9)) -- true, some of flags9 bits are set in flags8 print(flags8:has_all_of(flags7)) -- false, flags7 (== 0) is not set in flags8