1 // Copyright 2018 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef BASE_TRAITS_BAG_H_
6 #define BASE_TRAITS_BAG_H_
8 #include <initializer_list>
10 #include <type_traits>
13 #include "base/parameter_pack.h"
14 #include "base/template_util.h"
15 #include "third_party/abseil-cpp/absl/types/optional.h"
17 // A bag of Traits (structs / enums / etc...) can be an elegant alternative to
18 // the builder pattern and multiple default arguments for configuring things.
19 // Traits are terser than the builder pattern and can be evaluated at compile
20 // time, however they require the use of variadic templates which complicates
21 // matters. This file contains helpers that make Traits easier to use.
23 // WARNING: Trait bags are currently too heavy for non-constexpr usage in prod
24 // code due to template bloat, although adding NOINLINE to template constructors
25 // configured via trait bags can help.
28 // struct EnableFeatureX {};
29 // struct UnusedTrait {};
30 // enum Color { RED, BLUE };
32 // struct ValidTraits {
33 // ValidTraits(EnableFeatureX);
34 // ValidTraits(Color);
37 // DoSomethingAwesome(); // Use defaults (Color::BLUE &
38 // // feature X not enabled)
39 // DoSomethingAwesome(EnableFeatureX(), // Turn feature X on
40 // Color::RED); // And make it red.
41 // DoSomethingAwesome(UnusedTrait(), // Compile time error.
44 // DoSomethingAwesome might be defined as:
46 // template <class... ArgTypes,
47 // class CheckArgumentsAreValid = std::enable_if_t<
48 // trait_helpers::AreValidTraits<ValidTraits,
49 // ArgTypes...>::value>>
50 // constexpr void DoSomethingAwesome(ArgTypes... args)
51 // : enable_feature_x(
52 // trait_helpers::HasTrait<EnableFeatureX, ArgTypes...>()),
53 // color(trait_helpers::GetEnum<Color, EnumTraitA::BLUE>(args...)) {}
56 namespace trait_helpers {
58 // Represents a trait that has been removed by a predicate.
61 // Predicate used to remove any traits from the given list of types by
62 // converting them to EmptyTrait. E.g.
64 // template <typename... Args>
65 // void MyFunc(Args... args) {
66 // DoSomethingWithTraits(
67 // base::trait_helpers::Exclude<UnwantedTrait1,
68 // UnwantedTrait2>::Filter(args)...);
71 // NB It's possible to actually remove the unwanted trait from the pack, but
72 // that requires constructing a filtered tuple and applying it to the function,
73 // which isn't worth the complexity over ignoring EmptyTrait.
74 template <typename... TraitsToExclude>
77 std::enable_if_t<ParameterPack<
78 TraitsToExclude...>::template HasType<T>::value>* = nullptr>
79 static constexpr EmptyTrait Filter(T t) {
84 std::enable_if_t<!ParameterPack<
85 TraitsToExclude...>::template HasType<T>::value>* = nullptr>
86 static constexpr T Filter(T t) {
91 // CallFirstTag is an argument tag that helps to avoid ambiguous overloaded
92 // functions. When the following call is made:
93 // func(CallFirstTag(), arg...);
94 // the compiler will give precedence to an overload candidate that directly
95 // takes CallFirstTag. Another overload that takes CallSecondTag will be
96 // considered iff the preferred overload candidates were all invalids and
97 // therefore discarded.
98 struct CallSecondTag {};
99 struct CallFirstTag : CallSecondTag {};
101 // A trait filter class |TraitFilterType| implements the protocol to get a value
102 // of type |ArgType| from an argument list and convert it to a value of type
103 // |TraitType|. If the argument list contains an argument of type |ArgType|, the
104 // filter class will be instantiated with that argument. If the argument list
105 // contains no argument of type |ArgType|, the filter class will be instantiated
106 // using the default constructor if available; a compile error is issued
107 // otherwise. The filter class must have the conversion operator TraitType()
108 // which returns a value of type TraitType.
110 // |InvalidTrait| is used to return from GetTraitFromArg when the argument is
111 // not compatible with the desired trait.
112 struct InvalidTrait {};
114 // Returns an object of type |TraitFilterType| constructed from |arg| if
115 // compatible, or |InvalidTrait| otherwise.
116 template <class TraitFilterType,
118 class CheckArgumentIsCompatible = std::enable_if_t<
119 std::is_constructible<TraitFilterType, ArgType>::value>>
120 constexpr TraitFilterType GetTraitFromArg(CallFirstTag, ArgType arg) {
121 return TraitFilterType(arg);
124 template <class TraitFilterType, class ArgType>
125 constexpr InvalidTrait GetTraitFromArg(CallSecondTag, ArgType arg) {
126 return InvalidTrait();
129 // Returns an object of type |TraitFilterType| constructed from a compatible
130 // argument in |args...|, or default constructed if none of the arguments are
131 // compatible. This is the implementation of GetTraitFromArgList() with a
132 // disambiguation tag.
133 template <class TraitFilterType,
135 class TestCompatibleArgument = std::enable_if_t<any_of(
136 {std::is_constructible<TraitFilterType, ArgTypes>::value...})>>
137 constexpr TraitFilterType GetTraitFromArgListImpl(CallFirstTag,
139 return std::get<TraitFilterType>(std::make_tuple(
140 GetTraitFromArg<TraitFilterType>(CallFirstTag(), args)...));
143 template <class TraitFilterType, class... ArgTypes>
144 constexpr TraitFilterType GetTraitFromArgListImpl(CallSecondTag,
146 static_assert(std::is_constructible<TraitFilterType>::value,
147 "The traits bag is missing a required trait.");
148 return TraitFilterType();
151 // Constructs an object of type |TraitFilterType| from a compatible argument in
152 // |args...|, or using the default constructor, and returns its associated trait
153 // value using conversion to |TraitFilterType::ValueType|. If there are more
154 // than one compatible argument in |args|, generates a compile-time error.
155 template <class TraitFilterType, class... ArgTypes>
156 constexpr typename TraitFilterType::ValueType GetTraitFromArgList(
159 count({std::is_constructible<TraitFilterType, ArgTypes>::value...},
161 "The traits bag contains multiple traits of the same type.");
162 return GetTraitFromArgListImpl<TraitFilterType>(CallFirstTag(), args...);
165 // Helper class to implemnent a |TraitFilterType|.
166 template <typename T, typename _ValueType = T>
167 struct BasicTraitFilter {
168 using ValueType = _ValueType;
170 constexpr BasicTraitFilter(ValueType v) : value(v) {}
172 constexpr operator ValueType() const { return value; }
174 ValueType value = {};
177 template <typename ArgType, ArgType DefaultValue>
178 struct EnumTraitFilter : public BasicTraitFilter<ArgType> {
179 constexpr EnumTraitFilter() : BasicTraitFilter<ArgType>(DefaultValue) {}
180 constexpr EnumTraitFilter(ArgType arg) : BasicTraitFilter<ArgType>(arg) {}
183 template <typename ArgType>
184 struct OptionalEnumTraitFilter
185 : public BasicTraitFilter<ArgType, absl::optional<ArgType>> {
186 constexpr OptionalEnumTraitFilter()
187 : BasicTraitFilter<ArgType, absl::optional<ArgType>>(absl::nullopt) {}
188 constexpr OptionalEnumTraitFilter(ArgType arg)
189 : BasicTraitFilter<ArgType, absl::optional<ArgType>>(arg) {}
192 // Tests whether multiple given argtument types are all valid traits according
193 // to the provided ValidTraits. To use, define a ValidTraits
194 template <typename ArgType>
195 struct RequiredEnumTraitFilter : public BasicTraitFilter<ArgType> {
196 constexpr RequiredEnumTraitFilter(ArgType arg)
197 : BasicTraitFilter<ArgType>(arg) {}
200 // Note EmptyTrait is always regarded as valid to support filtering.
201 template <class ValidTraits, class T>
202 using IsValidTrait = disjunction<std::is_constructible<ValidTraits, T>,
203 std::is_same<T, EmptyTrait>>;
205 // Tests whether a given trait type is valid or invalid by testing whether it is
206 // convertible to the provided ValidTraits type. To use, define a ValidTraits
209 // struct ValidTraits {
210 // ValidTraits(MyTrait);
214 // You can 'inherit' valid traits like so:
216 // struct MoreValidTraits {
217 // MoreValidTraits(ValidTraits); // Pull in traits from ValidTraits.
218 // MoreValidTraits(MyOtherTrait);
221 template <class ValidTraits, class... ArgTypes>
222 using AreValidTraits =
223 bool_constant<all_of({IsValidTrait<ValidTraits, ArgTypes>::value...})>;
225 // Helper to make getting an enum from a trait more readable.
226 template <typename Enum, typename... Args>
227 static constexpr Enum GetEnum(Args... args) {
228 return GetTraitFromArgList<RequiredEnumTraitFilter<Enum>>(args...);
231 // Helper to make getting an enum from a trait with a default more readable.
232 template <typename Enum, Enum DefaultValue, typename... Args>
233 static constexpr Enum GetEnum(Args... args) {
234 return GetTraitFromArgList<EnumTraitFilter<Enum, DefaultValue>>(args...);
237 // Helper to make getting an optional enum from a trait with a default more
239 template <typename Enum, typename... Args>
240 static constexpr absl::optional<Enum> GetOptionalEnum(Args... args) {
241 return GetTraitFromArgList<OptionalEnumTraitFilter<Enum>>(args...);
244 // Helper to make checking for the presence of a trait more readable.
245 template <typename Trait, typename... Args>
246 struct HasTrait : ParameterPack<Args...>::template HasType<Trait> {
248 count({std::is_constructible<Trait, Args>::value...}, true) <= 1,
249 "The traits bag contains multiple traits of the same type.");
252 // If you need a template vararg constructor to delegate to a private
253 // constructor, you may need to add this to the private constructor to ensure
254 // it's not matched by accident.
255 struct NotATraitTag {};
257 } // namespace trait_helpers
260 #endif // BASE_TRAITS_BAG_H_