pfr/doc/pfr.qbk

[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]