libGimbal 0.2.0
C17-Based Extended Standard Library and Cross-Language Runtime Framework
Loading...
Searching...
No Matches
gimbal_flags.h
Go to the documentation of this file.
1/*! \file
2 * \brief GblFlagsClass and API for managing flag types
3 * \ingroup meta
4 *
5 * \author 2023 Falco Girgis
6 * \author 2026 Agustín Bellagamba
7 * \copyright MIT License
8 */
9#ifndef GIMBAL_FLAGS_H
10#define GIMBAL_FLAGS_H
11
12#include "gimbal_primitives.h"
13#include "../../strings/gimbal_quark.h"
14
15/*! \name Type System
16 * \brief Type UUID and cast operators
17 * @{
18 */
19#define GBL_FLAGS_TYPE (GblFlags_type()) //!< GblType UUID for flags
20#define GBL_FLAGS_CLASS(klass) (GBL_CLASS_CAST(GblFlags, klass)) //!< Cast a GblClass to GblFlagsClass
21//! @}
22
23/*! \name Helper Macros
24 * \brief Utility macros to aid in representing GblFlagEntry lists
25 * @{
26 */
27#define GBL_FLAGS_ENTRY(flagsValue, nick) { flagsValue, #flagsValue, nick }
28#define GBL_FLAGS_ENTRY_LAST() { 0, NULL, NULL }
29//! @}
30
31#define GBL_SELF_TYPE GblFlagsClass
32
33/*! \brief DSL macro used to declare and register GblFlags
34 *
35 * \param name Name of the GblFlags
36 * \param ... Flag entries in the form:
37 * (value, nick, number)
38 */
39#define GBL_FLAGS(name, ...) GBL_FLAGS_(name, __VA_ARGS__)
40
41GBL_DECLS_BEGIN
42
43//! Attributes for a single bit flag value within a group of GblFlag values
44typedef struct GblFlagEntry {
45 GblFlags value; //!< Value of the flag
46 const char* pName; //!< String name of the flag value
47 const char* pNick; //!< Alternate name of the flag value
48} GblFlagEntry;
49
50/*! \struct GblFlagsClass
51 * \extends GblPrimitiveClass
52 * \brief Static GblClass for storing type data for flags
53 *
54 * GblFlagsClass is a static/persistent class which is created
55 * from a list of GblFlagEntry structures, representing all of
56 * the valid bits for the flag type.
57 */
58GBL_CLASS_DERIVE(GblFlags, GblPrimitive)
59 GblFlags valueMask; //!< Mask of all bits which can be set within the value
60 uint16_t entryCount; //!< Cached number of values in the entry table
61GBL_CLASS_END
62
63// ========== GblFlagsClass ==========
64/*! \name Name Queries
65 * \brief Methods for querying name of flag values
66 * \relatesalso GblFlagsClass
67 * @{
68 */
69GBL_EXPORT const char* GblFlagsClass_nameFromIndex (GBL_CSELF, uint16_t index) GBL_NOEXCEPT;
70GBL_EXPORT const char* GblFlagsClass_nameFromValue (GBL_CSELF, GblFlags value) GBL_NOEXCEPT;
71GBL_EXPORT GblQuark GblFlagsClass_nameQuarkFromIndex (GBL_CSELF, uint16_t index) GBL_NOEXCEPT;
72GBL_EXPORT GblQuark GblFlagsClass_nameQuarkFromValue (GBL_CSELF, GblFlags value) GBL_NOEXCEPT;
73//! @}
74
75/*! \name Nick Queries
76 * \brief Methods for querying nick of flag values
77 * \relatesalso GblFlagsClass
78 * @{
79 */
80GBL_EXPORT const char* GblFlagsClass_nickFromIndex (GBL_CSELF, uint16_t index) GBL_NOEXCEPT;
81GBL_EXPORT const char* GblFlagsClass_nickFromValue (GBL_CSELF, GblFlags value) GBL_NOEXCEPT;
82GBL_EXPORT GblQuark GblFlagsClass_nickQuarkFromIndex (GBL_CSELF, uint16_t index) GBL_NOEXCEPT;
83GBL_EXPORT GblQuark GblFlagsClass_nickQuarkFromValue (GBL_CSELF, GblFlags value) GBL_NOEXCEPT;
84//! @}
85
86/*! \name Value Queries
87 * \brief Methods for querying value of flag values
88 * \relatesalso GblFlagsClass
89 * @{
90 */
91GBL_EXPORT GblFlags GblFlagsClass_valueFromIndex (GBL_CSELF, uint16_t index) GBL_NOEXCEPT;
92GBL_EXPORT GblFlags GblFlagsClass_valueFromName (GBL_CSELF, const char* pName) GBL_NOEXCEPT;
93GBL_EXPORT GblFlags GblFlagsClass_valueFromNick (GBL_CSELF, const char* pNick) GBL_NOEXCEPT;
94GBL_EXPORT GblFlags GblFlagsClass_valueFromNameQuark (GBL_CSELF, GblQuark name) GBL_NOEXCEPT;
95GBL_EXPORT GblFlags GblFlagsClass_valueFromNickQuark (GBL_CSELF, GblQuark nick) GBL_NOEXCEPT;
96GBL_EXPORT GblFlags GblFlagsClass_valueFromString (GBL_CSELF, const char* pString) GBL_NOEXCEPT;
97
98GBL_EXPORT GblBool GblFlagsClass_valueCheck (GBL_CSELF, GblFlags value) GBL_NOEXCEPT;
99
100GBL_EXPORT GBL_RESULT GblFlagsClass_valueAppendString (GBL_CSELF,
101 GblFlags value,
102 GblStringBuffer* pStr) GBL_NOEXCEPT;
103//! @}
104
105/*! \name Index Queries
106 * \brief Methods for querying flag entry indices, returning UINT16_MAX when not found.
107 * \relatesalso GblFlagsClass
108 * @{
109 */
110GBL_EXPORT uint16_t GblFlagsClass_indexFromValue (GBL_CSELF, GblFlags value) GBL_NOEXCEPT;
111GBL_EXPORT uint16_t GblFlagsClass_indexFromName (GBL_CSELF, const char* pName) GBL_NOEXCEPT;
112GBL_EXPORT uint16_t GblFlagsClass_indexFromNick (GBL_CSELF, const char* pNick) GBL_NOEXCEPT;
113GBL_EXPORT uint16_t GblFlagsClass_indexFromNameQuark (GBL_CSELF, GblQuark name) GBL_NOEXCEPT;
114GBL_EXPORT uint16_t GblFlagsClass_indexFromNickQuark (GBL_CSELF, GblQuark nick) GBL_NOEXCEPT;
115//! @}
116
117// ========== GblFlags ==========
118GBL_EXPORT GblType GblFlags_type (void) GBL_NOEXCEPT;
119
120GBL_EXPORT GblType GblFlags_register (const char* pName,
121 const GblFlagEntry* pEntries) GBL_NOEXCEPT;
122/*! \name Flags from Strings
123 * \brief Methods for getting a flags value from string
124 * @{
125 */
126GBL_EXPORT GblFlags GblFlags_fromName (const char* pName, GblType type) GBL_NOEXCEPT;
127GBL_EXPORT GblFlags GblFlags_fromNameQuark (GblQuark name, GblType type) GBL_NOEXCEPT;
128GBL_EXPORT GblFlags GblFlags_fromNick (const char* pNick, GblType type) GBL_NOEXCEPT;
129GBL_EXPORT GblFlags GblFlags_fromNickQuark (GblQuark nick, GblType type) GBL_NOEXCEPT;
130GBL_EXPORT GblFlags GblFlags_fromString (const char* pName, GblType type) GBL_NOEXCEPT;
131//! @}
132
133/*! \name Enums to Strings
134 * \brief Methods for getting a string from a flags value
135 * @{
136 */
137GBL_EXPORT const char* GblFlags_name (GblFlags value, GblType type) GBL_NOEXCEPT;
138GBL_EXPORT GblQuark GblFlags_nameQuark (GblFlags value, GblType type) GBL_NOEXCEPT;
139GBL_EXPORT const char* GblFlags_nick (GblFlags value, GblType type) GBL_NOEXCEPT;
140GBL_EXPORT GblQuark GblFlags_nickQuark (GblFlags value, GblType type) GBL_NOEXCEPT;
141//! @}
142
143GBL_EXPORT GblBool GblFlags_check (GblFlags value, GblType type) GBL_NOEXCEPT;
144GBL_EXPORT GBL_RESULT GblFlags_appendString (GblFlags value,
145 GblType type,
146 GblStringBuffer* pBuffer) GBL_NOEXCEPT;
147
148GBL_DECLS_END
149
150//! \cond GRUG_FREE
151
152#define GBL_FLAGS_(name, ...)
153 GBL_DECLARE_FLAGS(name) {
154 GBL_TUPLE_FOREACH(GBL_FLAGS_DECL_, name, (__VA_ARGS__))
155 };
156 GBL_FLAGS_REGISTER_(name, __VA_ARGS__)
157
158#define GBL_FLAGS_REGISTER_(name, ...)
159 GBL_INLINE GblType name##_type(void) GBL_NOEXCEPT {
160 static GblType type_ = GBL_INVALID_TYPE;
161 if(type_ == GBL_INVALID_TYPE) {
162 type_ = GblType_find(GBL_STRINGIFY(name));
163 if(type_ == GBL_INVALID_TYPE) {
164 static const GblFlagEntry entries_[] = {
165 GBL_TUPLE_FOREACH(GBL_FLAGS_TABLE_, name, (__VA_ARGS__))
166 GBL_FLAGS_ENTRY_LAST()
167 };
168 type_ = GblFlags_register(GBL_STRINGIFY(name), entries_);
169 }
170 }
171 return type_;
172 }
173
174#define GBL_FLAGS_DECL_(name, entry) GBL_FLAGS_DECL__(GBL_EVAL entry)
175#define GBL_FLAGS_DECL__(...) GBL_FLAGS_DECL___(__VA_ARGS__)
176#define GBL_FLAGS_DECL___(value, nick, num)
177 value = num,
178
179#define GBL_FLAGS_TABLE_(name, entry) GBL_FLAGS_TABLE__(GBL_EVAL entry)
180#define GBL_FLAGS_TABLE__(...) GBL_FLAGS_TABLE___(__VA_ARGS__)
181#define GBL_FLAGS_TABLE___(value, nick, num)
182 GBL_FLAGS_ENTRY(value, nick),
183
184//! \endcond
185
186#undef GBL_SELF_TYPE
187
188#endif // GIMBAL_FLAGS_H
GBL_NOEXCEPT
#define GBL_NOEXCEPT
Definition gimbal_compiler.h:152
GBL_INLINE
#define GBL_INLINE
Definition gimbal_compiler.h:332
GBL_DECLS_BEGIN
#define GBL_DECLS_BEGIN
Definition gimbal_decls.h:23
GBL_CLASS_DERIVE
#define GBL_CLASS_DERIVE(...)
Definition gimbal_decls.h:45
GBL_DECLARE_FLAGS
#define GBL_DECLARE_FLAGS(F)
Definition gimbal_decls.h:202
GBL_EXPORT
#define GBL_EXPORT
Definition gimbal_decls.h:253
GBL_CLASS_END
#define GBL_CLASS_END
Definition gimbal_decls.h:61
GBL_FLAGS_ENTRY_LAST
#define GBL_FLAGS_ENTRY_LAST()
Definition gimbal_flags.h:28
GBL_FLAGS_ENTRY
#define GBL_FLAGS_ENTRY(flagsValue, nick)
Definition gimbal_flags.h:27
GBL_STRINGIFY
#define GBL_STRINGIFY(a)
Definition gimbal_macro_composition.h:21
GBL_TUPLE_FOREACH
#define GBL_TUPLE_FOREACH(MACRO_, DATA_, TUPLE_)
Definition gimbal_macro_composition.h:331
GBL_EVAL
#define GBL_EVAL(...)
Definition gimbal_macro_sequences.h:46
GBL_INVALID_TYPE
#define GBL_INVALID_TYPE
GblType UUID of the invalid type.
Definition gimbal_type.h:31
GblFlags
uint32_t GblFlags
Standard-sized flags type, 32-bits across platforms.
Definition gimbal_typedefs.h:37
GblBool
uint8_t GblBool
Basic boolean type, standardized to sizeof(char)
Definition gimbal_typedefs.h:20
GblType
uintptr_t GblType
Meta Type UUID.
Definition gimbal_type.h:52
GblQuark
uintptr_t GblQuark
Uniquely identifiable interned string type.
Definition gimbal_quark.h:67
GblFlagEntry
Attributes for a single bit flag value within a group of GblFlag values.
Definition gimbal_flags.h:44
GblFlagEntry::pName
const char * pName
String name of the flag value.
Definition gimbal_flags.h:46
GblFlagEntry::value
GblFlags value
Value of the flag.
Definition gimbal_flags.h:45
GblFlagEntry::pNick
const char * pNick
Alternate name of the flag value.
Definition gimbal_flags.h:47
GblFlagsClass::valueMask
GblFlags valueMask
Mask of all bits which can be set within the value.
Definition gimbal_flags.h:59
GblFlagsClass::entryCount
uint16_t entryCount
Cached number of values in the entry table.
Definition gimbal_flags.h:60