From bb4fd73c317cc88beb5e58c1abf52138abed107f Mon Sep 17 00:00:00 2001 From: Thijs Schreijer Date: Thu, 20 Jun 2024 23:16:29 +0200 Subject: Release v0.4.0 (#24) --- docs/classes/bitflags.html | 305 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 docs/classes/bitflags.html (limited to 'docs/classes') diff --git a/docs/classes/bitflags.html b/docs/classes/bitflags.html new file mode 100644 index 0000000..f063149 --- /dev/null +++ b/docs/classes/bitflags.html @@ -0,0 +1,305 @@ + + + + + Lua-System docs + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

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 return false. So if there are flags that are +unsupported on a platform, they can be set to 0 and the has_all_of function will +return false if 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 return false. So if there are flags that are +unsupported on a platform, they can be set to 0 and the has_any_of function will +return false if 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
    +
+ +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-06-20 23:11:37 +
+
+ + -- cgit v1.2.3-55-g6feb