8.30 Flags

8.30.1 Routines

8.30.1.1 which_bit

include std/flags.e
namespace flags
public function which_bit(object theValue)

Tests if the supplied value has only a single bit on in its representation.

Parameters:
  1. theValue : an object to test.
Returns:

An integer, either 0 if it contains multiple bits, zero bits or is an invalid value, otherwise the bit number set. The right-most bit is position 1 and the leftmost bit is position 32.

Examples:
? which_bit(2) --> 2
? which_bit(0) --> 0
? which_bit(3) --> 0
? which_bit(4)          --> 3
? which_bit(17)         --> 0
? which_bit(1.7)        --> 0
? which_bit(-2)         --> 0
? which_bit("one")      --> 0
? which_bit(0x80000000) --> 32

8.30.1.2 flags_to_string

include std/flags.e
namespace flags
public function flags_to_string(object flag_bits, sequence flag_names,
        integer expand_flags = 0)

Returns a list of strings that represent the human-readable identities of the supplied flag(s).

Parameters:
  1. flag_bits : Either a single 32-bit set of flags (a flag value), or a list of such flag values. The function returns the names for these flag values.
  2. flag_names : A sequence of two-element sub-sequences. Each sub-sequence is contains {FlagValue, FlagName}, where FlagName is a string and FlagValue is the set of bits that set the flag on.
  3. expand_flags: An integer. 0 (the default) means that the flag values in flag_bits are not broken down to their single-bit values. eg. #0c returns the name of #0c and not the names for #08 and #04. When expand_flags is non-zero then each bit in the flag_bits parameter is scanned for a matching name.
Returns:

A sequence. This contains the name(s) for each supplied flag value(s).

Comments:
  • The number of strings in the returned value depends on expand_flags is non-zero and whether flags_bits is an atom or sequence.
  • When flag_bits is an atom, you get returned a sequence of strings, one for each matching name (according to expand_flags option).
  • When flag_bits is a sequence, it is assumed to represent a list of atomic flags. That is, {#1, #4} is a set of two flags for which you want their names. In this case, you get returned a sequence that contains one sequence for each element in flag_bits, which in turn contain the matching name(s).
  • When a flag's name can not be found in flag_names, this function returns the name of "?".
Examples:
include std/console.e
sequence s
s = {
	{#00000000, "WS_OVERLAPPED"},
	{#80000000, "WS_POPUP"},
	{#40000000, "WS_CHILD"},
	{#20000000, "WS_MINIMIZE"},
	{#10000000, "WS_VISIBLE"},
	{#08000000, "WS_DISABLED"},
	{#44000000, "WS_CLIPPINGCHILD"},
	{#04000000, "WS_CLIPSIBLINGS"},
	{#02000000, "WS_CLIPCHILDREN"},
	{#01000000, "WS_MAXIMIZE"},
	{#00C00000, "WS_CAPTION"},
	{#00800000, "WS_BORDER"},
	{#00400000, "WS_DLGFRAME"},
	{#00100000, "WS_HSCROLL"},
	{#00200000, "WS_VSCROLL"},
	{#00080000, "WS_SYSMENU"},
	{#00040000, "WS_THICKFRAME"},
	{#00020000, "WS_MINIMIZEBOX"},
	{#00010000, "WS_MAXIMIZEBOX"},
	{#00300000, "WS_SCROLLBARS"},
	{#00CF0000, "WS_OVERLAPPEDWINDOW"},
	$
}
display( flags_to_string( {#0C20000,2,9,0}, s,1))
--> {
-->     "WS_BORDER",
-->     "WS_DLGFRAME",
-->     "WS_MINIMIZEBOX"
-->   },
-->   {
-->     "?"
-->   },
-->   {
-->     "?"
-->   },
-->   {
-->     "WS_OVERLAPPED"
-->   }
--> }
display( flags_to_string( #80000000, s))
--> {
-->   "WS_POPUP"
--> }
display( flags_to_string( #00C00000, s))
--> {
-->   "WS_CAPTION"
--> }
display( flags_to_string( #44000000, s))
--> {
-->   "WS_CLIPPINGCHILD"
--> }
display( flags_to_string( #44000000, s, 1))
--> {
-->   "WS_CHILD",
-->   "WS_CLIPSIBLINGS"
--> }
display( flags_to_string( #00000000, s))
--> {
-->   "WS_OVERLAPPED"
--> }
display( flags_to_string( #00CF0000, s))
--> {
-->   "WS_OVERLAPPEDWINDOW"
--> }
display( flags_to_string( #00CF0000, s, 1))
--> {
-->   "WS_BORDER",
-->   "WS_DLGFRAME",
-->   "WS_SYSMENU",
-->   "WS_THICKFRAME",
-->   "WS_MINIMIZEBOX",
-->   "WS_MAXIMIZEBOX"
--> }