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 2025-03-02 19:43:40