1 /* 2 * Copyright 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #pragma once 18 19 #include <ftl/enum.h> 20 #include <ftl/string.h> 21 22 #include <bitset> 23 #include <cstdint> 24 #include <iterator> 25 #include <initializer_list> 26 #include <string> 27 #include <type_traits> 28 29 // TODO(b/185536303): Align with FTL style. 30 31 namespace android::ftl { 32 33 /* A class for handling flags defined by an enum or enum class in a type-safe way. */ 34 template <typename F> 35 class Flags { 36 // F must be an enum or its underlying type is undefined. Theoretically we could specialize this 37 // further to avoid this restriction but in general we want to encourage the use of enums 38 // anyways. 39 static_assert(std::is_enum_v<F>, "Flags type must be an enum"); 40 using U = std::underlying_type_t<F>; 41 42 public: Flags(F f)43 constexpr Flags(F f) : mFlags(static_cast<U>(f)) {} Flags(std::initializer_list<F> fs)44 constexpr Flags(std::initializer_list<F> fs) : mFlags(combine(fs)) {} Flags()45 constexpr Flags() : mFlags(0) {} Flags(const Flags<F> & f)46 constexpr Flags(const Flags<F>& f) : mFlags(f.mFlags) {} 47 48 // Provide a non-explicit construct for non-enum classes since they easily convert to their 49 // underlying types (e.g. when used with bitwise operators). For enum classes, however, we 50 // should force them to be explicitly constructed from their underlying types to make full use 51 // of the type checker. 52 template <typename T = U> mFlags(t)53 constexpr Flags(T t, std::enable_if_t<!is_scoped_enum_v<F>, T>* = nullptr) : mFlags(t) {} 54 55 template <typename T = U> 56 explicit constexpr Flags(T t, std::enable_if_t<is_scoped_enum_v<F>, T>* = nullptr) mFlags(t)57 : mFlags(t) {} 58 59 class Iterator { 60 using Bits = std::uint64_t; 61 static_assert(sizeof(U) <= sizeof(Bits)); 62 63 public: 64 constexpr Iterator() = default; Iterator(Flags<F> flags)65 Iterator(Flags<F> flags) : mRemainingFlags(flags.mFlags) { (*this)++; } 66 67 // Pre-fix ++ 68 Iterator& operator++() { 69 if (mRemainingFlags.none()) { 70 mCurrFlag = 0; 71 } else { 72 // TODO: Replace with std::countr_zero in C++20. 73 const Bits bit = static_cast<Bits>(__builtin_ctzll(mRemainingFlags.to_ullong())); 74 mRemainingFlags.reset(static_cast<std::size_t>(bit)); 75 mCurrFlag = static_cast<U>(static_cast<Bits>(1) << bit); 76 } 77 return *this; 78 } 79 80 // Post-fix ++ 81 Iterator operator++(int) { 82 Iterator iter = *this; 83 ++*this; 84 return iter; 85 } 86 87 bool operator==(Iterator other) const { 88 return mCurrFlag == other.mCurrFlag && mRemainingFlags == other.mRemainingFlags; 89 } 90 91 bool operator!=(Iterator other) const { return !(*this == other); } 92 93 F operator*() const { return F{mCurrFlag}; } 94 95 // iterator traits 96 97 // In the future we could make this a bidirectional const iterator instead of a forward 98 // iterator but it doesn't seem worth the added complexity at this point. This could not, 99 // however, be made a non-const iterator as assigning one flag to another is a non-sensical 100 // operation. 101 using iterator_category = std::input_iterator_tag; 102 using value_type = F; 103 // Per the C++ spec, because input iterators are not assignable the iterator's reference 104 // type does not actually need to be a reference. In fact, making it a reference would imply 105 // that modifying it would change the underlying Flags object, which is obviously wrong for 106 // the same reason this can't be a non-const iterator. 107 using reference = F; 108 using difference_type = void; 109 using pointer = void; 110 111 private: 112 std::bitset<sizeof(Bits) * 8> mRemainingFlags; 113 U mCurrFlag = 0; 114 }; 115 116 /* 117 * Tests whether the given flag is set. 118 */ test(F flag)119 bool test(F flag) const { 120 U f = static_cast<U>(flag); 121 return (f & mFlags) == f; 122 } 123 124 /* Tests whether any of the given flags are set */ 125 bool any(Flags<F> f = ~Flags<F>()) const { return (mFlags & f.mFlags) != 0; } 126 127 /* Tests whether all of the given flags are set */ all(Flags<F> f)128 bool all(Flags<F> f) const { return (mFlags & f.mFlags) == f.mFlags; } 129 130 constexpr Flags<F> operator|(Flags<F> rhs) const { return static_cast<F>(mFlags | rhs.mFlags); } 131 Flags<F>& operator|=(Flags<F> rhs) { 132 mFlags = mFlags | rhs.mFlags; 133 return *this; 134 } 135 136 Flags<F> operator&(Flags<F> rhs) const { return static_cast<F>(mFlags & rhs.mFlags); } 137 Flags<F>& operator&=(Flags<F> rhs) { 138 mFlags = mFlags & rhs.mFlags; 139 return *this; 140 } 141 142 Flags<F> operator^(Flags<F> rhs) const { return static_cast<F>(mFlags ^ rhs.mFlags); } 143 Flags<F>& operator^=(Flags<F> rhs) { 144 mFlags = mFlags ^ rhs.mFlags; 145 return *this; 146 } 147 148 Flags<F> operator~() { return static_cast<F>(~mFlags); } 149 150 bool operator==(Flags<F> rhs) const { return mFlags == rhs.mFlags; } 151 bool operator!=(Flags<F> rhs) const { return !operator==(rhs); } 152 153 Flags<F>& operator=(const Flags<F>& rhs) { 154 mFlags = rhs.mFlags; 155 return *this; 156 } 157 158 inline Flags<F>& clear(Flags<F> f = static_cast<F>(~static_cast<U>(0))) { 159 return *this &= ~f; 160 } 161 begin()162 Iterator begin() const { return Iterator(*this); } 163 end()164 Iterator end() const { return Iterator(); } 165 166 /* 167 * Returns the stored set of flags. 168 * 169 * Note that this returns the underlying type rather than the base enum class. This is because 170 * the value is no longer necessarily a strict member of the enum since the returned value could 171 * be multiple enum variants OR'd together. 172 */ get()173 U get() const { return mFlags; } 174 string()175 std::string string() const { 176 std::string result; 177 bool first = true; 178 U unstringified = 0; 179 for (const F f : *this) { 180 if (const auto flagName = flag_name(f)) { 181 appendFlag(result, flagName.value(), first); 182 } else { 183 unstringified |= static_cast<U>(f); 184 } 185 } 186 187 if (unstringified != 0) { 188 constexpr auto radix = sizeof(U) == 1 ? Radix::kBin : Radix::kHex; 189 appendFlag(result, to_string(unstringified, radix), first); 190 } 191 192 if (first) { 193 result += "0x0"; 194 } 195 196 return result; 197 } 198 199 private: 200 U mFlags; 201 combine(std::initializer_list<F> fs)202 static constexpr U combine(std::initializer_list<F> fs) { 203 U result = 0; 204 for (const F f : fs) { 205 result |= static_cast<U>(f); 206 } 207 return result; 208 } 209 appendFlag(std::string & str,const std::string_view & flag,bool & first)210 static void appendFlag(std::string& str, const std::string_view& flag, bool& first) { 211 if (first) { 212 first = false; 213 } else { 214 str += " | "; 215 } 216 str += flag; 217 } 218 }; 219 220 // This namespace provides operator overloads for enum classes to make it easier to work with them 221 // as flags. In order to use these, add them via a `using namespace` declaration. 222 namespace flag_operators { 223 224 template <typename F, typename = std::enable_if_t<is_scoped_enum_v<F>>> 225 inline Flags<F> operator~(F f) { 226 return static_cast<F>(~to_underlying(f)); 227 } 228 229 template <typename F, typename = std::enable_if_t<is_scoped_enum_v<F>>> 230 constexpr Flags<F> operator|(F lhs, F rhs) { 231 return static_cast<F>(to_underlying(lhs) | to_underlying(rhs)); 232 } 233 234 } // namespace flag_operators 235 } // namespace android::ftl 236