From 87c18aab8c32d4ec07ea166721ae847b72f7418a Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Sun, 12 Jul 2020 23:27:07 +0300 Subject: libcamera: flags: Add type-safe enum-based flags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a Flags template class that provide type-safe bitwise operators on enum values. This allows using enum types for bit fields, without giving away type-safety as usually done when storing combined flags in integer variables. Signed-off-by: Laurent Pinchart Reviewed-by: Niklas Söderlund Reviewed-by: Jacopo Mondi --- src/libcamera/base/flags.cpp | 192 +++++++++++++++++++++++++++++++++++++++++ src/libcamera/base/meson.build | 1 + 2 files changed, 193 insertions(+) create mode 100644 src/libcamera/base/flags.cpp (limited to 'src') diff --git a/src/libcamera/base/flags.cpp b/src/libcamera/base/flags.cpp new file mode 100644 index 00000000..3e4320ac --- /dev/null +++ b/src/libcamera/base/flags.cpp @@ -0,0 +1,192 @@ +/* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * Copyright (C) 2020, Google Inc. + * + * flags.cpp - Type-safe enum-based bitfields + */ + +#include + +/** + * \file base/flags.h + * \brief Enum-based bit fields + */ + +namespace libcamera { + +/** + * \class Flags + * \brief Type-safe container for enum-based bitfields + * + * The Flags template class provides type-safe bitwise operators on enum values. + * It allows using enum types for bitfields, while preventing unsafe casts from + * integer types and mixing of flags from different enum types. + * + * To use the Flags class, declare an enum containing the desired bit flags, and + * use the Flags class to store bitfields based on the enum. If bitwise + * operators on the underlying enum are also desired, they can be enabled with + * the LIBCAMERA_FLAGS_ENABLE_OPERATORS(enum) macro. + */ + +/** + * \typedef Flags::Type + * \brief The underlying data type of the enum + */ + +/** + * \fn Flags::Flags() + * \brief Construct a Flags instance with a zero value + */ + +/** + * \fn Flags::Flags(E flag) + * \brief Construct a Flags instance storing the \a flag + * \param[in] flag The initial value + */ + +/** + * \fn Flags &Flags::operator&=(E flag) + * \brief Store the bitwise AND of this Flags and the \a flag in this Flags + * \param[in] flag The second operand + * \return A reference to this Flags + */ + +/** + * \fn Flags &Flags::operator&=(Flags other) + * \brief Store the bitwise AND of this Flags and the \a other Flags in this Flags + * \param[in] other The second operand + * \return A reference to this Flags + */ + +/** + * \fn Flags &Flags::operator|=(E flag) + * \brief Store the bitwise OR of this Flags and the \a flag in this Flags + * \param[in] flag The second operand + * \return A reference to this Flags + */ + +/** + * \fn Flags &Flags::operator|=(Flags other) + * \brief Store the bitwise OR of this Flags and the \a other Flags in this Flags + * \param[in] other The second operand + * \return A reference to this Flags + */ + +/** + * \fn Flags &Flags::operator^=(E flag) + * \brief Store the bitwise XOR of this Flags and the \a flag in this Flags + * \param[in] flag The second operand + * \return A reference to this Flags + */ + +/** + * \fn Flags &Flags::operator^=(Flags other) + * \brief Store the bitwise XOR of this Flags and the \a other Flags in this Flags + * \param[in] other The second operand + * \return A reference to this Flags + */ + +/** + * \fn bool Flags::operator==(E flag) + * \brief Compare flags for equality + * \param[in] flag The second operand + * \return True if the Flags and \a flag are equal, false otherwise + */ + +/** + * \fn bool Flags::operator==(Flags other) + * \brief Compare flags for equality + * \param[in] other The second operand + * \return True if the Flags and \a other are equal, false otherwise + */ + +/** + * \fn bool Flags::operator!=(E flag) + * \brief Compare flags for non-equality + * \param[in] flag The second operand + * \return True if the Flags and \a flag are not equal, false otherwise + */ + +/** + * \fn bool Flags::operator!=(Flags other) + * \brief Compare flags for non-equality + * \param[in] other The second operand + * \return True if the Flags and \a other are not equal, false otherwise + */ + +/** + * \fn Flags::operator Type() const + * \brief Convert the Flags to the underlying integer type + * \return The Flags value as an integer + */ + +/** + * \fn Flags::operator bool() const + * \brief Convert the Flags to a boolean + * \return True if at least one flag is set, false otherwise + */ + +/** + * \fn Flags Flags::operator&(E flag) const + * \brief Compute the bitwise AND of this Flags and the \a flag + * \param[in] flag The second operand + * \return A Flags containing the result of the AND operation + */ + +/** + * \fn Flags Flags::operator&(Flags other) const + * \brief Compute the bitwise AND of this Flags and the \a other Flags + * \param[in] other The second operand + * \return A Flags containing the result of the AND operation + */ + +/** + * \fn Flags Flags::operator|(E flag) const + * \brief Compute the bitwise OR of this Flags and the \a flag + * \param[in] flag The second operand + * \return A Flags containing the result of the OR operation + */ + +/** + * \fn Flags Flags::operator|(Flags other) const + * \brief Compute the bitwise OR of this Flags and the \a other Flags + * \param[in] other The second operand + * \return A Flags containing the result of the OR operation + */ + +/** + * \fn Flags Flags::operator^(E flag) const + * \brief Compute the bitwise XOR of this Flags and the \a flag + * \param[in] flag The second operand + * \return A Flags containing the result of the XOR operation + */ + +/** + * \fn Flags Flags::operator^(Flags other) const + * \brief Compute the bitwise XOR of this Flags and the \a other Flags + * \param[in] other The second operand + * \return A Flags containing the result of the XOR operation + */ + +/** + * \fn Flags Flags::operator~() const + * \brief Compute the bitwise NOT of this Flags + * \return A Flags containing the result of the NOT operation + */ + +/** + * \fn bool Flags::operator!() const + * \brief Check if flags are set + * \return True if no flags is set, false otherwise + */ + +/** + * \def LIBCAMERA_FLAGS_ENABLE_OPERATORS(enum) + * \brief Enable bitwise operations on the \a enum enumeration + * + * This macro enables the bitwise AND, OR, XOR and NOT operators on the given + * \a enum. This allows the enum values to be safely used in bitwise operations + * with the Flags<> class. + */ + +} /* namespace libcamera */ diff --git a/src/libcamera/base/meson.build b/src/libcamera/base/meson.build index 87172157..d799c66d 100644 --- a/src/libcamera/base/meson.build +++ b/src/libcamera/base/meson.build @@ -7,6 +7,7 @@ libcamera_base_sources = files([ 'event_dispatcher_poll.cpp', 'event_notifier.cpp', 'file.cpp', + 'flags.cpp', 'log.cpp', 'message.cpp', 'object.cpp', -- cgit v1.2.1