The Struct concept represents struct-like user-defined types.
The Struct concept allows restricted compile-time reflection over user-defined types. In particular, it allows accessing the names of the members of a user-defined type, and also the value of those members. Structs can also be folded, searched and converted to some types of containers, where more advanced transformations can be performed.
While all types can in theory be made Structs, only a subset of them are actually interesting to see as such. More precisely, it is only interesting to make a type a Struct when it is conceptually a C++ struct, i.e. a mostly dumb aggregate of named data. The way this data is accessed is mostly unimportant to the Struct concept; it could be through getters and setters, through public members, through non-member functions or it could even be generated on-the-fly. The important part, which is made precise below, is that those accessor methods should be move-independent.
Another way to see a Struct is as a map where the keys are the names of the members and the values are the values of those members. However, there are subtle differences like the fact that one can't add a member to a Struct, and also that the order of the members inside a Struct plays a role in determining the equality of Structs, which is not the case for maps.
accessors
A model of Struct is created by specifying a sequence of key/value pairs with the accessors function. The first element of a pair in this sequence represents the "name" of a member of the Struct, while the second element is a function which retrieves this member from an object. The "names" do not have to be in any special form; they just have to be compile-time Comparable. For example, it is common to provide "names" that are hana::strings representing the actual names of the members, but one could provide hana::integral_constants just as well. The values must be functions which, when given an object, retrieve the appropriate member from it.
There are several ways of providing the accessors method, some of which are more flexible and others which are more convenient. First, one can define it through tag-dispatching, as usual.
Secondly, it is possible to provide a nested hana_accessors_impl type, which should be equivalent to a specialization of accessors_impl for tag-dispatching. However, for a type S, this technique only works when the data type of S is S itself, which is the case unless you explicitly asked for something else.
Finally, the most convenient (but least flexible) option is to use the BOOST_HANA_DEFINE_STRUCT, the BOOST_HANA_ADAPT_STRUCT or the BOOST_HANA_ADAPT_ADT macro, which provide a minimal syntactic overhead. See the documentation of these macros for details on how to use them.
Also note that it is not important that the accessor functions retrieve an actual member of the struct (e.g. x.member). Indeed, an accessor function could call a custom getter or even compute the value of the member on the fly:
The only important thing is that the accessor functions are move-independent, a notion which is defined below.
The notion of move-independence presented here defines rigorously when it is legitimate to "double-move" from an object.
A collection of functions f1, ..., fn sharing the same domain is said to be move-independent if for every fresh (not moved-from) object x in the domain, any permutation of the following statements is valid and leaves the zk objects in a fresh (not moved-from) state:
auto zk = (like void or a non-movable, non-copyable type), just pretend the return value is ignored.Intuitively, this ensures that we can treat f1, ..., fn as "accessors" that decompose x into independent subobjects, and that do so without moving from x more than that subobject. This is important because it allows us to optimally decompose Structs into their subparts inside the library.
For any Struct S, the accessors in the accessors<S>() sequence must be move-independent, as defined above.
Comparable (free model)Structs are required to be Comparable. Specifically, two Structs of the same data type S must be equal if and only if all of their members are equal. By default, a model of Comparable doing just that is provided for models of Struct. In particular, note that the comparison of the members is made in the same order as they appear in the hana::members sequence. Foldable (free model)Struct can be folded by considering it as a list of pairs each containing the name of a member and the value associated to that member, in the same order as they appear in the hana::members sequence. By default, a model of Foldable doing just that is provided for models of the Struct concept. Foldable makes it possible to turn a Struct into basically any Sequence, but also into a hana::map by simply using the to<...> function! Searchable (free model)Struct can be searched by considering it as a map where the keys are the names of the members of the Struct, and the values are the members associated to those names. By default, a model of Searchable is provided for any model of the Struct concept. Functions | |
| auto | boost::hana::BOOST_HANA_ADAPT_ADT (...) |
Defines a model of Struct with the given accessors. More... | |
| auto | boost::hana::BOOST_HANA_ADAPT_STRUCT (...) |
Defines a model of Struct with the given members. More... | |
| auto | boost::hana::BOOST_HANA_DEFINE_STRUCT (...) |
Defines members of a structure, while at the same time modeling Struct. More... | |
Variables | |
| template<typename S > | |
| constexpr auto | boost::hana::accessors |
Returns a Sequence of pairs representing the accessors of the data structure. More... | |
| constexpr keys_t | boost::hana::keys {} |
Returns a Sequence containing the name of the members of the data structure. More... | |
| constexpr auto | boost::hana::members |
Returns a Sequence containing the members of a Struct. More... | |
| auto boost::hana::BOOST_HANA_ADAPT_ADT | ( | ... | ) |
#include <boost/hana/fwd/adapt_adt.hpp>
Defines a model of Struct with the given accessors.
Using this macro at global scope will define a model of the Struct concept for the given type. This can be used to easily adapt existing user-defined types in a ad-hoc manner. Unlike BOOST_HANA_ADAPT_STRUCT, this macro requires specifying the way to retrieve each member by providing a function that does the extraction.
T is T itself. This is the case unless you specifically asked for something different; see tag_of's documentation.| auto boost::hana::BOOST_HANA_ADAPT_STRUCT | ( | ... | ) |
#include <boost/hana/fwd/adapt_struct.hpp>
Defines a model of Struct with the given members.
Using this macro at global scope will define a model of the Struct concept for the given type. This can be used to easily adapt existing user-defined types in a ad-hoc manner. Unlike the BOOST_HANA_DEFINE_STRUCT macro, this macro does not require the types of the members to be specified.
T is T itself. This is the case unless you specifically asked for something different; see tag_of's documentation.| auto boost::hana::BOOST_HANA_DEFINE_STRUCT | ( | ... | ) |
#include <boost/hana/fwd/define_struct.hpp>
Defines members of a structure, while at the same time modeling Struct.
Using this macro in the body of a user-defined type will define the given members inside that type, and will also provide a model of the Struct concept for that user-defined type. This macro is often the easiest way to define a model of the Struct concept.
T is T itself. This is the case unless you specifically asked for something different; see tag_of's documentation.
|
constexpr |
#include <boost/hana/fwd/accessors.hpp>
Returns a Sequence of pairs representing the accessors of the data structure.
Given a Struct S, accessors<S>() is a Sequence of Products where the first element of each pair is the "name" of a member of the Struct, and the second element of each pair is a function that can be used to access that member when given an object of the proper data type. As described in the global documentation for Struct, the accessor functions in this sequence must be move-independent.
|
related |
#include <boost/hana/fwd/keys.hpp>
Returns a Sequence containing the name of the members of the data structure.
Given a Struct object, keys returns a Sequence containing the name of all the members of the Struct, in the same order as they appear in the accessors sequence.
|
constexpr |
#include <boost/hana/fwd/members.hpp>
Returns a Sequence containing the members of a Struct.
Given a Struct object, members returns a Sequence containing all the members of the Struct, in the same order as their respective accessor appears in the accessors sequence.