# decode_flags

Definition: | string res = decode_flags(sequence FlagSet, atom v, string sep="+")
Description: | Create a human readable string for a bit field. FlagSet: a table of {flag,text} pairs. v: the value to be deciphered. sep: a separator, default "+". Returns a string representing the bit settings of v.
pwa/p2js: | Supported.
Comments: | This is useful anywhere you have a bitmap field and want to show a human-readable version. Further examples can be found in demo\arwendemo\filedump.exw Obviously each application must define its own FlagSet(s). The order of FlagSet determines the order things appear in the result. If a description begins with '-', the separator(optional p3) is omitted. A decription(s) of "" can be used to ignore/suppress specific bit settings. The first entry in FlagSet can be eg {0,"closed"} to specify the "no bits set" meaning. Any bits not recognised/ignored are returned as a hex value at the start.
Example 1: |
    -- (these "FILE_ATTRIBUTE_XXX" flags can be found in demo\arwen\constants.e)
    constant FileFlagSet = {{FILE_ATTRIBUTE_READONLY,  "R"},
                            {FILE_ATTRIBUTE_SYSTEM,    "S"},
                            {FILE_ATTRIBUTE_HIDDEN,    "H"},
                            {FILE_ATTRIBUTE_DIRECTORY, "D"}}

    ? decode_flags(FileFlagSet,#17,"")  -- "RSHD"
Example 2: |
    constant FileFlagSet = {{FILE_ATTRIBUTE_READONLY,  "Read"},
                            {FILE_ATTRIBUTE_SYSTEM,    "System"},
                            {FILE_ATTRIBUTE_HIDDEN,    "Hidden"},
                            {FILE_ATTRIBUTE_DIRECTORY, "Directory"}}

    ? decode_flags(FileFlagSet,#17)     -- "Read+System+Hidden+Directory"
Example 3: |
    -- Multiple bits are handled with appropriate common sense:
    constant RW = {{#0003, "rw"},
                    #0001, "r"},
                    #0002, "w"},
                    #FF00, ""}}
    ?decode_flags(RW,#03) -- "rw"
    ?decode_flags(RW,#01) -- "r"
    ?decode_flags(RW,#02) -- "w"
    ?decode_flags(RW,#102) -- "w"
    -- The "rw" entry only triggers when all bits are set, whereas the
    -- #FF00 triggers/ignores any bits, since length(description) is 0.
Implementation: | See builtins\pdecodeflags.e (an autoinclude) for details of the actual implementation. See also test\t71decode_flags.exw which is entirely dedicated to testing this function.