531 lines
18 KiB
Plaintext
531 lines
18 KiB
Plaintext
[library Boost.PFR
|
|
[quickbook 1.6]
|
|
[version 2.0]
|
|
[copyright 2016-2021 Antony Polukhin]
|
|
[category Language Features Emulation]
|
|
[license
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
[@http://www.boost.org/LICENSE_1_0.txt])
|
|
]
|
|
]
|
|
|
|
[section Intro]
|
|
|
|
Boost.PFR is a C++14 library for a very basic reflection. It gives you access to structure elements by index and provides other `std::tuple` like methods for user defined types without macro or boilerplate code:
|
|
|
|
[import ../example/motivating_example0.cpp]
|
|
[pfr_motivating_example]
|
|
|
|
See [link boost_pfr.limitations_and_configuration [*limitations]].
|
|
|
|
|
|
[h2 Usecase example]
|
|
|
|
Imagine that you are writing the wrapper library for a database. Depending on the usage of Boost.PFR users code will look differently:
|
|
|
|
[table:hand_made_vs_pfr_1
|
|
[[ Without Boost.PFR ] [ With Boost.PFR ]]
|
|
[[
|
|
```
|
|
#include <db/api.hpp>
|
|
|
|
struct user_info {
|
|
std::int64_t id;
|
|
std::string name, email, login;
|
|
};
|
|
|
|
user_info retrieve_friend(std::string_view name) {
|
|
std::tuple info_tuple
|
|
= db::one_row_as<std::int64_t, std::string, std::string, std::string>(
|
|
"SELECT id, name, email, login FROM user_infos WHERE name=$0",
|
|
name
|
|
);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
user_info info {
|
|
std::move(std::get<0>(info_tuple)),
|
|
std::move(std::get<1>(info_tuple)),
|
|
std::move(std::get<2>(info_tuple)),
|
|
std::move(std::get<3>(info_tuple)),
|
|
}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
auto friend_info = ask_user_for_friend(std::move(info));
|
|
|
|
db::insert(
|
|
"INSERT INTO user_infos(id, name, email, login) VALUES ($0, $1, $2, $3)",
|
|
std::move(friend_info.id), //////////////////////////////////////////////
|
|
std::move(friend_info.name), // Users are forced to move individual fields
|
|
std::move(friend_info.email), // because your library can not iterate over
|
|
std::move(friend_info.login) // the fields of a user provided structure
|
|
);
|
|
|
|
return friend_info;
|
|
}
|
|
```
|
|
][
|
|
```
|
|
#include <db/api.hpp>
|
|
|
|
struct user_info {
|
|
std::int64_t id;
|
|
std::string name, email, login;
|
|
};
|
|
|
|
user_info retrieve_friend(std::string_view name) {
|
|
// With Boost.PFR you can put data directly into user provided structures
|
|
user_info info = db::one_row_as<user_info>(
|
|
"SELECT id, name, email, login FROM user_infos WHERE name=$0",
|
|
name
|
|
);
|
|
|
|
////////////////// No boilerplate code to move data around /////////////////////
|
|
|
|
|
|
|
|
|
|
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
auto friend_info = ask_user_for_friend(std::move(info));
|
|
|
|
db::insert(
|
|
"INSERT INTO user_infos(id, name, email, login) VALUES ($0, $1, $2, $3)",
|
|
friend_info ////////////////////////////////////////////////////////////
|
|
// Boost.PFR allows you to iterate over all the fields of a
|
|
// user provided structure
|
|
//
|
|
);
|
|
|
|
return friend_info;
|
|
}
|
|
```
|
|
]]
|
|
]
|
|
|
|
Otherwise your library could require a customization point for a user type:
|
|
|
|
|
|
[table:hand_made_vs_pfr_2
|
|
[[ Without Boost.PFR ] [ With Boost.PFR ]]
|
|
[[
|
|
```
|
|
#include <db/api.hpp>
|
|
|
|
struct user_info {
|
|
std::int64_t id;
|
|
std::string name, email, login;
|
|
};
|
|
|
|
/// Customizations via hand-written code or macro like BOOST_FUSION_ADAPT_STRUCT ///
|
|
auto db_api_tie(user_info& ui) noexcept {
|
|
return std::tie(ui.id, ui.name, ui.email, ui.login);
|
|
}
|
|
|
|
auto db_api_tie(const user_info& ui) noexcept {
|
|
return std::tie(ui.id, ui.name, ui.email, ui.login);
|
|
}
|
|
////////////////////////////////////////////////////////////////////////////////////
|
|
```
|
|
][
|
|
```
|
|
#include <db/api.hpp>
|
|
|
|
struct user_info {
|
|
std::int64_t id;
|
|
std::string name, email, login;
|
|
};
|
|
|
|
//////// With Boost.PFR there's no need in hand written customizations /////////////
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////
|
|
```
|
|
]]
|
|
]
|
|
|
|
|
|
With Boost.PFR the code is shorter, more readable and more pleasant to write.
|
|
|
|
|
|
|
|
[h2 Out of the box functionality ]
|
|
|
|
Boost.PFR adds the following out-of-the-box functionality for aggregate initializable structures:
|
|
|
|
* comparison functions
|
|
* heterogeneous comparators
|
|
* hash
|
|
* IO streaming
|
|
* access to members by index
|
|
* member type retrieval
|
|
* methods for cooperation with `std::tuple`
|
|
* methods to visit each field of the structure
|
|
|
|
Boost.PFR is a header only library that does not depend on Boost. You can just copy the content of the "include" folder [@https://github.com/boostorg/pfr from the github] into your project, and the library will work fine.
|
|
|
|
[caution Recommended C++ Standards are C++17 and above. Library requires at least C++14! Pre C++14 compilers (C++11, C++03...) are not supported]
|
|
|
|
[endsect]
|
|
|
|
|
|
[section Short Examples for the Impatient]
|
|
|
|
[import ../example/quick_examples.cpp]
|
|
|
|
|
|
[table:quick_examples
|
|
[[ Code snippet ] [ Reference: ]]
|
|
[
|
|
[ [pfr_quick_examples_get] ]
|
|
[ [funcref boost::pfr::get] ]
|
|
][
|
|
[ [pfr_quick_examples_ops] ]
|
|
[
|
|
|
|
[headerref boost/pfr/ops.hpp Header boost/pfr/ops.hpp]:
|
|
|
|
* [funcref boost::pfr::eq]
|
|
|
|
* [funcref boost::pfr::ne]
|
|
|
|
* [funcref boost::pfr::gt]
|
|
|
|
* ...
|
|
|
|
]
|
|
][
|
|
[ [pfr_quick_examples_for_each] ]
|
|
[
|
|
[funcref boost::pfr::for_each_field]
|
|
|
|
[funcref boost::pfr::io]
|
|
]
|
|
][
|
|
[ [pfr_quick_examples_functions_for] ]
|
|
[ [macroref BOOST_PFR_FUNCTIONS_FOR] ]
|
|
][
|
|
[ [pfr_quick_examples_eq_fields] ]
|
|
[
|
|
[headerref boost/pfr/ops_fields.hpp Header boost/pfr/ops_fields.hpp ]:
|
|
|
|
* [funcref boost::pfr::eq_fields]
|
|
|
|
* [funcref boost::pfr::ne_fields]
|
|
|
|
* [funcref boost::pfr::gt_fields]
|
|
|
|
* ...
|
|
|
|
[headerref boost/pfr/io_fields.hpp Header boost/pfr/io_fields.hpp ]
|
|
|
|
* [funcref boost::pfr::io_fields]
|
|
|
|
]
|
|
][
|
|
[ [pfr_quick_examples_for_each_idx] ]
|
|
[ [funcref boost::pfr::for_each_field] ]
|
|
][
|
|
[ [pfr_quick_examples_tuple_size] ]
|
|
[ [classref boost::pfr::tuple_size] ]
|
|
][
|
|
[ [pfr_quick_examples_structure_to_tuple] ]
|
|
[ [funcref boost::pfr::structure_to_tuple] ]
|
|
][
|
|
[ [pfr_quick_examples_structure_tie] ]
|
|
[ [funcref boost::pfr::structure_tie] ]
|
|
]]
|
|
|
|
|
|
|
|
[endsect]
|
|
|
|
|
|
[section Tutorial]
|
|
|
|
[import ../example/sample_printing.cpp]
|
|
[import ../example/get.cpp]
|
|
|
|
|
|
[section Why tuples are bad and aggregates are more preferable?]
|
|
|
|
`std::tuple` and `std::pair` are good for generic programming, however they have disadvantages. First of all, code that uses them becomes barely readable. Consider two definitions:
|
|
|
|
[table:tuples_vs_aggregates
|
|
[[ Tuple ] [ Aggregate ]]
|
|
[[
|
|
```
|
|
using auth_info_tuple = std::tuple<
|
|
std::int64_t, // What does this integer represents?
|
|
std::int64_t,
|
|
std::time_t
|
|
>;
|
|
```
|
|
][
|
|
```
|
|
struct auth_info_aggregate {
|
|
std::int64_t user_id; // Oh, now I see!
|
|
std::int64_t session_id;
|
|
std::time_t valid_till;
|
|
};
|
|
```
|
|
]]
|
|
]
|
|
|
|
Definition via aggregate initializable structure is much more clear. Same story with usages: `return std::get<1>(value);` vs. `return value.session_id;`.
|
|
|
|
Another advantage of aggregates is a more efficient copy, move construction and assignments.
|
|
|
|
Because of the above issues some guidelines recommend to [*use aggregates instead of tuples]. However aggregates fail when it comes to the functional like programming.
|
|
|
|
Boost.PFR library [*provides tuple like methods for aggregate initializable structures], making aggregates usable in contexts where only tuples were useful.
|
|
|
|
[endsect]
|
|
|
|
[section Accessing structure member by index] [pfr_example_get] [endsect]
|
|
[section Custom printing of aggregates] [pfr_sample_printing] [endsect]
|
|
|
|
|
|
[section Three ways of getting operators ]
|
|
|
|
There are three ways to start using Boost.PFR hashing, comparison and streaming for type `T` in your code. Each method has its own drawbacks and suits own cases.
|
|
|
|
[table:ops_comp Different approaches for operators
|
|
[[ Approach
|
|
][ When to use
|
|
][ Operators could be found by ADL ][ Works for local types ][ Usable locally, without affecting code from other scopes ][ Ignores implicit conversion operators ][ Respects user defined operators ]]
|
|
|
|
[[
|
|
[headerref boost/pfr/ops.hpp boost/pfr/ops.hpp: eq, ne, gt, lt, le, ge]
|
|
|
|
[headerref boost/pfr/io.hpp boost/pfr/io.hpp: io]
|
|
][
|
|
Use when you need to compare values by provided for them operators or via field-by-field comparison.
|
|
][ no ][ yes ][ yes ][ no ][ yes ]]
|
|
|
|
[[
|
|
[macroref BOOST_PFR_FUNCTIONS_FOR BOOST_PFR_FUNCTIONS_FOR(T)]
|
|
][
|
|
Use near the type definition to define the whole set of operators for your type.
|
|
][ yes ][ no ][ no ][ yes for T ] [ no (compile time error) ]]
|
|
|
|
[[
|
|
[headerref boost/pfr/ops_fields.hpp boost/pfr/ops_fields.hpp: eq_fields, ne_fields, gt_fields, lt_fields, le_fields, ge_fields]
|
|
|
|
[headerref boost/pfr/io.hpp boost/pfr/io_fields.hpp: io_fields]
|
|
][
|
|
Use to implement the required set of operators for your type.
|
|
][ no ][ yes ][ yes ][ yes ][ yes ]]
|
|
]
|
|
|
|
More detailed description follows:
|
|
|
|
[*1. `eq, ne, gt, lt, le, ge, io` approach]
|
|
|
|
This method is good if you're writing generic algorithms and need to use operators from Boost.PFR only if there are no operators defined for the type:
|
|
|
|
```
|
|
#include <boost/pfr/ops.hpp>
|
|
|
|
template <class T>
|
|
struct uniform_comparator_less {
|
|
bool operator()(const T& lhs, const T& rhs) const noexcept {
|
|
// If T has operator< or conversion operator then it is used.
|
|
return boost::pfr::lt(lhs, rhs);
|
|
}
|
|
};
|
|
```
|
|
This methods effects are local to the function. It works even for local types, like structures defined in functions.
|
|
|
|
|
|
[*2. BOOST_PFR_FUNCTIONS_FOR(T) approach]
|
|
|
|
This method is good if you're writing a structure and wish to define operators for that structure.
|
|
```
|
|
#include <boost/pfr/functions_for.hpp>
|
|
|
|
struct pair_like {
|
|
int first;
|
|
short second;
|
|
};
|
|
|
|
BOOST_PFR_FUNCTIONS_FOR(pair_like) // Defines operators
|
|
|
|
// ...
|
|
|
|
assert(pair_like{1, 2} < pair_like{1, 3});
|
|
```
|
|
Argument Dependant Lookup works well. `std::less` will find the operators for `struct pair_like`. [macroref BOOST_PFR_FUNCTIONS_FOR BOOST_PFR_FUNCTIONS_FOR(T)]
|
|
can not be used for local types. It does not respect conversion operators of `T`, so for example the following code
|
|
will output different values:
|
|
```
|
|
#include <boost/pfr/functions_for.hpp>
|
|
|
|
struct empty {
|
|
operator std::string() { return "empty{}"; }
|
|
};
|
|
// Uncomment to get different output:
|
|
// BOOST_PFR_FUNCTIONS_FOR(empty)
|
|
|
|
// ...
|
|
std::cout << empty{}; // Outputs `empty{}` if BOOST_PFR_FUNCTIONS_FOR(empty) is commented out, '{}' otherwise.
|
|
```
|
|
|
|
[*3. `eq_fields, ne_fields, gt_fields, lt_fields, le_fields, ge_fields, io_fields` approach]
|
|
|
|
This method is good if you're willing to provide only some operators for your type:
|
|
|
|
```
|
|
#include <boost/pfr/io_fields.hpp>
|
|
|
|
struct pair_like {
|
|
int first;
|
|
std::string second;
|
|
};
|
|
|
|
inline std::ostream& operator<<(std::ostream& os, const pair_like& x) {
|
|
return os << bost::pfr::io_fields(x);
|
|
}
|
|
```
|
|
|
|
All the `*_fields` functions do ignore user defined operators and work only with fields of a type. This makes them perfect for defining you own operators.
|
|
|
|
[endsect]
|
|
|
|
|
|
[section Reflection of unions ]
|
|
|
|
You could use tuple-like representation if a type contains union. But be sure that operations for union are manually defined:
|
|
|
|
```
|
|
#include <boost/pfr/ops.hpp>
|
|
|
|
union test_union {
|
|
int i;
|
|
float f;
|
|
};
|
|
|
|
inline bool operator==(test_union l, test_union r) noexcept; // Compile time error without this operator
|
|
|
|
bool some_function(test_union f1, test_union f2) {
|
|
return boost::pfr::eq(f1, f2); // OK
|
|
}
|
|
|
|
```
|
|
|
|
Reflection of unions is disabled in the Boost.PFR library for safety reasons. Alas, there's no way to find out [*active] member of a union and accessing an inactive member is an Undefined Behavior. For example, library could always return the first member, but ostreaming `u` in `union {char* c; long long ll; } u; u.ll= 1;` will crash your program with an invalid pointer dereference.
|
|
|
|
Any attempt to reflect unions leads to a compile time error. In many cases a static assert is triggered that outputs the following message:
|
|
|
|
```
|
|
error: static_assert failed "====================> Boost.PFR: For safety reasons it is forbidden
|
|
to reflect unions. See `Reflection of unions` section in the docs for more info."
|
|
```
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|
|
|
|
|
|
[section Limitations and Configuration]
|
|
|
|
[caution Recommended C++ Standards are C++17 and above. Library requires at least C++14! Pre C++14 compilers (C++11, C++03...) are not supported. ]
|
|
|
|
Boost.PFR library works with types that satisfy the requirements of `SimpleAggregate`: aggregate types without base classes, `const` fields, references, or C arrays:
|
|
|
|
```
|
|
struct simple_aggregate { // SimpleAggregate
|
|
std::string name;
|
|
int age;
|
|
boost::uuids::uuid uuid;
|
|
};
|
|
|
|
struct empty { // SimpleAggregate
|
|
};
|
|
|
|
struct aggregate : empty { // not a SimpleAggregate
|
|
std::string name;
|
|
int age;
|
|
boost::uuids::uuid uuid;
|
|
};
|
|
```
|
|
The library may work with aggregates that don't satisfy the requirements of `SimpleAggregate`, but the behavior tends to be non-portable.
|
|
|
|
[h2 Configuration Macro]
|
|
|
|
By default Boost.PFR [*auto-detects your compiler abilities] and automatically defines the configuration macro into appropriate values. If you wish to override that behavior, just define:
|
|
[table:linkmacro Macros
|
|
[[Macro name] [Effect]]
|
|
[[*BOOST_PFR_USE_CPP17*] [Define to `1` if you wish to override Boost.PFR choice and use C++17 structured bindings for reflection. Define to `0` to override Boost.PFR choice and disable C++17 structured bindings usage.]]
|
|
[[*BOOST_PFR_USE_LOOPHOLE*] [Define to `1` if you wish to override Boost.PFR choice and exploit [@http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_active.html#2118 CWG 2118] for reflection. Define to `0` to override Boost.PFR choice and disable CWG 2118 usage.]]
|
|
[[*BOOST_PFR_USE_STD_MAKE_INTEGRAL_SEQUENCE*] [Define to `0` if you are hit by the template instantiation depth issues with `std::make_integer_sequence` and wish to use Boost.PFR version of that metafunction. Define to `1` to override Boost.PFR detection logic. ]]
|
|
]
|
|
|
|
|
|
[h2 Details on Limitations]
|
|
|
|
The Boost.PFRs reflection has some limitations that depend on a C++ Standard and compiler capabilities:
|
|
|
|
* Static variables are ignored
|
|
* T must be aggregate initializable without empty base classes
|
|
* if T contains C arrays or it is inherited from non-empty type then the result of reflection may differ depending on the C++ version and library configuration
|
|
* Additional limitations if [*BOOST_PFR_USE_CPP17 == 0]:
|
|
* Non of the member fields should have a template constructor from one parameter.
|
|
* Additional limitations if [*BOOST_PFR_USE_LOOPHOLE == 0]:
|
|
* T must be constexpr aggregate initializable and all its fields must be constexpr default constructible
|
|
* [funcref boost::pfr::get], [funcref boost::pfr::structure_to_tuple], [funcref boost::pfr::structure_tie], [headerref boost/pfr/core.hpp boost::pfr::tuple_element] require T to be a POD type with built-in types only.
|
|
|
|
|
|
[endsect]
|
|
|
|
[section How it works]
|
|
|
|
Short description:
|
|
|
|
# at compile-time: use aggregate initialization to detect fields count in user-provided structure
|
|
* [*BOOST_PFR_USE_CPP17 == 1]:
|
|
# at compile-time: structured bindings are used to decompose a type `T` to known amount of fields
|
|
* [*BOOST_PFR_USE_CPP17 == 0 && BOOST_PFR_USE_LOOPHOLE == 1]:
|
|
# at compile-time: use aggregate initialization to detect fields count in user-provided structure
|
|
# at compile-time: make a structure that is convertible to anything and remember types it has been converted to during aggregate initialization of user-provided structure
|
|
# at compile-time: using knowledge from previous steps create a tuple with exactly the same layout as in user-provided structure
|
|
# at compile-time: find offsets for each field in user-provided structure using the tuple from previous step
|
|
# at run-time: get pointer to each field, knowing the structure address and each field offset
|
|
# at run-time: a tuple of references to fields is returned => all the tuple methods are available for the structure
|
|
* [*BOOST_PFR_USE_CPP17 == 0 && BOOST_PFR_USE_LOOPHOLE == 0]:
|
|
# at compile-time: let `I` be is an index of current field, it equals 0
|
|
# at run-time: `T` is constructed and field `I` is aggregate initialized using a separate instance of structure that is convertible to anything [note Additional care is taken to make sure that all the information about `T` is available to the compiler and that operations on `T` have no side effects, so the compiler can optimize away the unnecessary temporary objects.]
|
|
# at compile-time: `I += 1`
|
|
# at compile-time: if `I` does not equal fields count goto step [~c.] from inside of the conversion operator of the structure that is convertible to anything
|
|
# at compile-time: using knowledge from previous steps create a tuple with exactly the same layout as in user-provided structure
|
|
# at compile-time: find offsets for each field in user-provided structure using the tuple from previous step
|
|
# at run-time: get pointer to each field, knowing the structure address and each field offset
|
|
# at run-time: a tuple of references to fields is returned => all the tuple methods are available for the structure
|
|
|
|
Long description of some basics: [@https://youtu.be/UlNUNxLtBI0 Antony Polukhin: Better C++14 reflections].
|
|
Long description of some basics of C++14 with [link boost_pfr.limitations_and_configuration [*BOOST_PFR_USE_LOOPHOLE == 0]]: [@https://youtu.be/abdeAew3gmQ Antony Polukhin: C++14 Reflections Without Macros, Markup nor External Tooling].
|
|
Description of the [*BOOST_PFR_USE_LOOPHOLE == 1] technique by its inventor Alexandr Poltavsky [@http://alexpolt.github.io/type-loophole.html in his blog].
|
|
|
|
[endsect]
|
|
|
|
[section Acknowledgements]
|
|
|
|
Many thanks to Bruno Dutra for showing the technique to precisely reflect aggregate initializable type in C++14 [@https://github.com/apolukhin/magic_get/issues/5 Manual type registering/structured bindings might be unnecessary].
|
|
|
|
Many thanks to Alexandr Poltavsky for initial implementation the [*BOOST_PFR_USE_LOOPHOLE == 1] technique and for describing it [@http://alexpolt.github.io/type-loophole.html in his blog].
|
|
|
|
Many thanks to Chris Beck for implementing the detect-offsets-and-get-field-address functionality that avoids Undefined Behavior of reinterpret_casting layout compatible structures.
|
|
|
|
Many thanks to the Boost people who participated in the formal review, especially to Benedek Thaler, Steven Watanabe and Andrzej Krzemienski.
|
|
|
|
[endsect]
|
|
|
|
[xinclude autodoc_pfr.xml]
|