ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
bitwise.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of the module \alib_enumops of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
8ALIB_EXPORT namespace alib {
9
10/// This is the reference documentation of sub-namespace \c enumops of the \aliblink, which
11/// holds types of library module \alib_enumops.
12///
13/// Extensive documentation for this module is provided with
14/// \ref alib_mod_enums "ALib Module Enums - Programmer's Manual".
15///
16/// \attention
17/// All operators are declared in the global namespace, other than this
18/// namespace documentation indicates!
19namespace enumops {
20
21// #################################################################################################
22// struct BitwiseTraits
23// #################################################################################################
24
25//==================================================================================================
26/// Simple type trait that inherits <c>std::false_type</c> by default.
27/// If specialized for an enumeration type \p{TEnum} to inherit <c>std::true_type</c>, the
28/// following operators set of \alib operators become applicable to elements of \p{TEnum}:
29///
30/// - \alib{enumops::bitwise;operator&}
31/// - \alib{enumops::bitwise;operator&=}
32/// - \alib{enumops::bitwise;operator|}
33/// - \alib{enumops::bitwise;operator|=}
34/// - \alib{enumops::bitwise;operator^}
35/// - \alib{enumops::bitwise;operator^=}
36/// - \alib{enumops::bitwise;operator~}
37/// - \alib{enumops::bitwise;operator+} (Alias for \alib{enumops::bitwise;operator|})
38/// - \alib{enumops::bitwise;operator-} (Alias for a combination of operators
39/// \alib{enumops::bitwise;operator&} and \alib{enumops::bitwise;operator~})
40/// - \alib{enumops::bitwise;operator+=} (An alias for \alib{enumops::bitwise;operator|=})
41/// - \alib{enumops::bitwise;operator-=} (Removes given bit(s) )
42///
43/// \attention
44/// Likewise with the operators introduced with the type trait \alib{enumops;ArithmeticalTraits},
45/// this documentation "fakes" the operators into namespace <c>alib::enumops</c>,
46/// while in fact they are defined in the global namespace.<br>
47/// See \ref alib_enums_arithmetic_standard "corresponding note" in the Programmer's Manual
48/// for details.
49///
50/// <b>Restrictions</b><br>
51/// For technical reasons, this concept is not applicable to enum types that are defined as
52/// \c private or \c protected inner types of structs or classes.
53///
54/// \see
55/// - Macro \ref ALIB_ENUMS_MAKE_BITWISE, which specializes this type trait for a given
56/// enumeration type.
57/// - For details and a source code sample see chapter \ref alib_enums_arithmetic_bitwise
58/// of the Programmer's Manual of the module \alib_enumops.
59///
60/// \I{#############################################################################################}
61/// # Restrictions #
62/// For technical reasons, this concept is not applicable to enum types that are defined as
63/// \c private or \c protected inner types of structs or classes.
64///
65/// # Reference Documentation #
66///
67/// @tparam TEnum The enum type to enable bitwise operators for.
68//==================================================================================================
69template<typename TEnum>
70requires std::is_enum<TEnum>::value
71struct BitwiseTraits : std::false_type {};
72
74
75/// Concept that is satisfied if the type trait \alib{enumops;BitwiseTraits}
76/// is specialized for type \p{TEnum} to inherit <c>std::true_type</c>.
77/// @tparam TEnum The type to test.
78template<typename TEnum>
80
82
83} // namespace alib[::enumops]
84} // namespace [alib]
85
86// #################################################################################################
87// Bitwise Operators
88// #################################################################################################
89// For documentation, all operators and enum related template functions are faked into namespace
90// alib::enumops
91#if DOXYGEN
92namespace alib { namespace enumops {
93/// Operators available to elements of enumerations if \alib{enumops;BitwiseTraits} is
94/// specialized.
95///
96/// \note
97/// This namespace exits only in the documentation to collect the operators.
98/// When parsed by a C++ compiler, <b>the operators reside in the global namespace</b> and
99/// functions \alib{enumops::bitwise;HasBits}, \alib{enumops::bitwise;CountElements},
100/// \alib{enumops::bitwise;ToBitwiseEnumeration} and \alib{enumops::bitwise;ToSequentialEnumeration}
101/// reside in namespace \ref alib.
102///
103/// As required, when parsed by a C++ compiler, the operators reside in the global namespace.
105#endif
106
107
108/// Bitwise \b and operator usable with scoped enum types.<br>
109/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
110/// template enum type \p{TEnum} to inherit \c std::true_type.
111///
112/// @tparam TEnum Enumeration type.
113/// @param lhs First operand.
114/// @param rhs Second operand.
115/// @return The result of a bitwise and operation of the underlying enum values.
117template<typename TEnum>
119constexpr TEnum operator& (TEnum lhs, TEnum rhs) noexcept
120{
121 using TBits= typename std::underlying_type<TEnum>::type;
122 return TEnum(TBits(lhs) & TBits(rhs));
123}
124
125/// Bitwise assignment operator usable with scoped enum types.<br>
126/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
127/// template enum type \p{TEnum} to inherit \c std::true_type.
128///
129/// @tparam TEnum Enumeration type.
130/// @param[in,out] lhs Reference to the first operand. Receives the result.
131/// @param rhs Second operand.
132/// @return The new value of \p{lhs} which is set to <c>lhs & rhs</c>.
134template<typename TEnum>
136constexpr TEnum operator&= (TEnum& lhs, TEnum rhs) noexcept
137{
138 using TBits= typename std::underlying_type<TEnum>::type;
139 return lhs= TEnum( TBits(lhs) & TBits(rhs) );
140}
141
142/// Bitwise \b or operator usable with scoped enum types.<br>
143/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
144/// template enum type \p{TEnum} to inherit \c std::true_type.
145///
146/// @tparam TEnum Enumeration type.
147/// @param lhs First operand.
148/// @param rhs Second operand.
149/// @return The result of a bitwise or operation of the underlying enum values.
151template<typename TEnum>
153constexpr TEnum operator| (TEnum lhs, TEnum rhs) noexcept
154{
155 using TBits= typename std::underlying_type<TEnum>::type;
156 return TEnum(TBits(lhs) | TBits(rhs));
157}
158
159/// Bitwise <b>or assignment</b> operator usable with scoped enum types.<br>
160/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
161/// template enum type \p{TEnum} to inherit \c std::true_type.
162///
163/// @tparam TEnum Enumeration type.
164/// @param[in,out] lhs Reference to the first operand. Receives the result.
165/// @param rhs Second operand.
166/// @return The new value of \p{lhs} which is set to <c>lhs | rhs</c>.
168template<typename TEnum>
170constexpr TEnum operator|= (TEnum& lhs, TEnum rhs) noexcept
171{
172 using TBits= typename std::underlying_type<TEnum>::type;
173 return lhs= TEnum( TBits(lhs) | TBits(rhs) );
174}
175
176/// Bitwise \b xor operator usable with scoped enum types.<br>
177/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
178/// template enum type \p{TEnum} to inherit \c std::true_type.
179///
180/// @tparam TEnum Enumeration type.
181/// @param lhs First operand.
182/// @param rhs Second operand.
183/// @return The result of a bitwise xor operation of the underlying enum values.
185template<typename TEnum>
187constexpr TEnum operator^ (TEnum lhs, TEnum rhs) noexcept
188{
189 using TBits= typename std::underlying_type<TEnum>::type;
190 return TEnum(TBits(lhs) ^ TBits(rhs));
191}
192
193/// Bitwise <b>xor assignment</b> operator usable with scoped enum types.<br>
194/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
195/// template enum type \p{TEnum} to inherit \c std::true_type.
196///
197/// @tparam TEnum Enumeration type.
198/// @param[in,out] lhs Reference to the first operand. Receives the result.
199/// @param rhs Second operand.
200/// @return The new value of \p{lhs} which is set to <c>lhs ^ rhs</c>.
202template<typename TEnum>
204constexpr TEnum operator^= (TEnum& lhs, TEnum rhs) noexcept
205{
206 using TBits= typename std::underlying_type<TEnum>::type;
207 return lhs= TEnum( TBits(lhs) ^ TBits(rhs) );
208}
209
210/// Bitwise \b not operator usable with scoped enum types.<br>
211/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
212/// template enum type \p{TEnum} to inherit \c std::true_type.
213///
214/// \note To remove one or more bits from a scoped enum value, operator <b>&=</b> with this operator
215/// applied to \p{op} can be used.
216/// A shortcut to this is given with \ref operator-=.
217///
218/// @tparam TEnum Enumeration type.
219/// @param op The operand to be negated.
220/// @return The result of a bitwise negation of \p{op}.
222template<typename TEnum>
224constexpr TEnum operator~ (TEnum op) noexcept
225{
226 using TBits= typename std::underlying_type<TEnum>::type;
227 return TEnum( ~ TBits(op) );
228}
229
230
231/// Alias to bitwise \b or operator usable with scoped enum types.<br>
232/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
233/// template enum type \p{TEnum} to inherit \c std::true_type and if \alib{enumops;ArithmeticalTraits}
234/// is \b not specialized to inherit \c std::true_type. The latter is to avoid ambiguities in
235/// situations where an enum is both, arithmetical and bitwise.
236///
237/// @tparam TEnum Enumeration type.
238/// @param lhs First operand.
239/// @param rhs Second operand.
240/// @return The result of a bitwise or operation of the underlying enum values.
242template<typename TEnum>
243requires ( alib::enumops::IsBitwise <TEnum>
245constexpr TEnum operator+ (TEnum lhs, TEnum rhs) noexcept
246{
247 using TBits= typename std::underlying_type<TEnum>::type;
248 return TEnum(TBits(lhs) | TBits(rhs));
249}
250
251/// Alias for bitwise <b>or assignment</b> operator usable with scoped enum types.<br>
252/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
253/// template enum type \p{TEnum} to inherit \c std::true_type and if \alib{enumops;ArithmeticalTraits}
254/// is \b not specialized to inherit \c std::true_type. The latter is to avoid ambiguities in
255/// situations where an enum is both, arithmetical and bitwise.
256///
257/// @tparam TEnum Enumeration type.
258/// @param[in,out] lhs Reference to the first operand. Receives the result.
259/// @param rhs Second operand.
260/// @return The new value of \p{lhs} which is set to <c>lhs | rhs</c>.
262template<typename TEnum>
263requires ( alib::enumops::IsBitwise <TEnum>
265constexpr TEnum operator+= (TEnum& lhs, TEnum rhs) noexcept
266{
267 using TBits= typename std::underlying_type<TEnum>::type;
268 return lhs= TEnum( TBits(lhs) | TBits(rhs) );
269}
270
271/// Removes bit(s) found in \p{rhs} from \p{lhs} an returns result. This is a shortcut to:
272///
273/// lhs & !rhs
274///
275/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
276/// template enum type \p{TEnum} to inherit \c std::true_type and if \alib{enumops;ArithmeticalTraits}
277/// is \b not specialized to inherit \c std::true_type. The latter is to avoid ambiguities in
278/// situations where an enum is both, arithmetical and bitwise.
279///
280/// @tparam TEnum Enumeration type.
281/// @param lhs First operand.
282/// @param rhs Second operand.
283/// @return The result of <c>lhs & !rhs</c>.
285template<typename TEnum>
286requires ( alib::enumops::IsBitwise <TEnum>
288constexpr TEnum operator- (TEnum lhs, TEnum rhs) noexcept
289{
290 using TBits= typename std::underlying_type<TEnum>::type;
291 return TEnum( TBits(lhs) & (~TBits(rhs)) );
292}
293
294/// Removes bit(s) found in \p{rhs} from \p{lhs}. This is a shortcut to:
295///
296/// lhs &= !rhs
297///
298/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
299/// template enum type \p{TEnum} to inherit \c std::true_type and if \alib{enumops;ArithmeticalTraits}
300/// is \b not specialized to inherit \c std::true_type. The latter is to avoid ambiguities in
301/// situations where an enum is both, arithmetical and bitwise.
302///
303/// @tparam TEnum Enumeration type.
304/// @param[in,out] lhs Reference to the first operand. Receives the result.
305/// @param rhs Second operand.
306/// @return The new value of \p{lhs} which is set to <c>lhs & ( ~rhs )</c>.
308template<typename TEnum>
309requires ( alib::enumops::IsBitwise <TEnum>
311constexpr TEnum operator-= (TEnum& lhs, TEnum rhs) noexcept
312{
313 using TBits= typename std::underlying_type<TEnum>::type;
314 return lhs= TEnum( TBits(lhs) & (~TBits(rhs)) );
315}
316
317#if !DOXYGEN
318ALIB_EXPORT namespace alib {
319#endif
320
321/// Tests if the integral value of the given enum \p{element} contains all bits set in
322/// \p{selection}.
323/// In other words, returns result of:
324///
325/// ( element & selection ) == selection
326///
327/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
328/// template enum type \p{TEnum} to inherit \c std::true_type.
329///
330/// @tparam TEnum Enumeration type. Deduced by the compiler.
331/// @param element Bitset to be tested.
332/// @param selection Second operand.
333/// @return \c true if all bits of \p{selection} are set in \p{element}.
334template<typename TEnum>
336constexpr bool HasBits(TEnum element, TEnum selection) noexcept
337{
338 using TBits= typename std::underlying_type<TEnum>::type;
339 return ( TBits(element) & TBits(selection) ) == TBits(selection);
340}
341
342/// Tests if the integral value of the given enum \p{element} contains at least one of the bits
343/// set in \p{selection}.
344/// In other words, returns result of:
345///
346/// ( element & selection ) != 0
347///
348/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
349/// template enum type \p{TEnum} to inherit \c std::true_type.
350///
351/// @tparam TEnum Enumeration type. Deduced by the compiler.
352/// @param element Bitset to be tested.
353/// @param selection Second operand.
354/// @return \c true if one of the bits of \p{selection} are set in \p{element}.
355template<typename TEnum>
357constexpr bool HasOneOf(TEnum element, TEnum selection) noexcept
358{
359 using TBits= typename std::underlying_type<TEnum>::type;
360 return ( TBits(element) & TBits(selection) ) != TBits(0);
361}
362
363/// Returns the number of bitwise enumeration elements set in the given value.
364/// In other words, the bits given in \p value are counted and the number is returned.
365///
366/// Selected by the compiler only if \alib{enumops;BitwiseTraits} is specialized for
367/// template enum type \p{TEnum} to inherit \c std::true_type.
368///
369/// @param value A single or composite selection of bits.
370/// @return The result of a call to #alib::lang::BitCount().
371template<typename TEnum>
373constexpr int CountElements( TEnum value )
374{ return lang::BitCount(UnderlyingIntegral(value)); }
375
376#if DOXYGEN
377}}} // doxygen namespace [alib::enumops::bitwise]
378#else
379} // namespace [alib]
380#endif
381
382
#define ALIB_WARNINGS_RESTORE
Definition alib.inl:705
#define ALIB_WARNINGS_IGNORE_DOCS
Definition alib.inl:688
#define ALIB_EXPORT
Definition alib.inl:488
ALIB_EXPORT constexpr TEnum operator&=(TEnum &lhs, TEnum rhs) noexcept
Definition bitwise.inl:136
ALIB_EXPORT constexpr TEnum operator^(TEnum lhs, TEnum rhs) noexcept
Definition bitwise.inl:187
constexpr int CountElements(TEnum value)
Definition bitwise.inl:373
ALIB_EXPORT constexpr TEnum operator|=(TEnum &lhs, TEnum rhs) noexcept
Definition bitwise.inl:170
ALIB_EXPORT constexpr TEnum operator^=(TEnum &lhs, TEnum rhs) noexcept
Definition bitwise.inl:204
constexpr bool HasOneOf(TEnum element, TEnum selection) noexcept
Definition bitwise.inl:357
ALIB_EXPORT constexpr TEnum operator~(TEnum op) noexcept
Definition bitwise.inl:224
ALIB_EXPORT constexpr TEnum operator&(TEnum lhs, TEnum rhs) noexcept
Definition bitwise.inl:119
constexpr bool HasBits(TEnum element, TEnum selection) noexcept
Definition bitwise.inl:336
ALIB_EXPORT constexpr TEnum operator|(TEnum lhs, TEnum rhs) noexcept
Definition bitwise.inl:153
std::underlying_type_t< TEnum > constexpr UnderlyingIntegral(TEnum element) noexcept
constexpr int BitCount(TIntegral value)
Definition bits.inl:222