<!DOCTYPE File PUBLIC "-//Liam Quin//DTD C API Documentation v1.1//EN" "doc.dtd"><File>
<Entry dir="liblqtext">
<Function File="../../src/liblqtext/prflags.c">
<Name>LQT_FlagsToString</Name>
<Class>Tracing
<Purpose>
<P>Returns a printable string representation of the given flags,
primarily intended for humans to read.
The WordFlagNamePairArray argument is an array of (Name, Value)
pairs; for each such pair, if all set bits in Value are also
set in the Flags argument passed to LQT_FlagsToString, the
corresponding Name string is appended to the result.
The array is terminated by a pair with a null Name pointer; this
is used rather than a count so that the array can be initialised
at compile time.</P>

<P>Adjacent Names in the result are separated with the given
separator.
If the flags are zero, the array is searched for a Value of zero, and,
if one is found, the corresponding Name is used; to have a zero value
return an empty string, use a pair with Name pointing to a zero-length
string, not a null pointer.
If no zero Value is found, the string "none" is used instead.</P>
<Returns>
a pointer to a statically allocated string.
<Errors>
Passing null or invalid values for WordFlagNamePairArray or Separator
will cause unpredictable results.
There must be enough memory to allocate the result, which grows
automatically as needed, but never shrinks.
<SeeAlso>
LQT_StringToFlags
</Function>
<Decl>
API char *
LQT_FlagsToString(Flags, WordFlagNamePairArray, Separator)
    unsigned long Flags;
    t_FlagNamePair *WordFlagNamePairArray;
    char *Separator;
</Decl>
</Entry>
