EIC code displayed by LXR master/​include/​boost/​hana/​fwd/​concept/​struct.hpp	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-18 09:37:58

 /*!
 @file
 Forward declares `boost::hana::Struct`.
 
 Copyright Louis Dionne 2013-2022
 Distributed under the Boost Software License, Version 1.0.
 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
  */
 
 #ifndef BOOST_HANA_FWD_CONCEPT_STRUCT_HPP
 #define BOOST_HANA_FWD_CONCEPT_STRUCT_HPP
 
 #include <boost/hana/config.hpp>
 
 
 namespace boost { namespace hana {
     //! @ingroup group-concepts
     //! @defgroup group-Struct Struct
     //! 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. `Struct`s 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 `Struct`s, 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 `Struct`s, which is not
     //! the case for maps.
     //!
     //!
     //! Minimal complete definition
     //! ---------------------------
     //! `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::string`s representing the actual names
     //! of the members, but one could provide `hana::integral_constant`s 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.
     //! @snippet example/struct.mcd.tag_dispatching.cpp main
     //!
     //! 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.
     //! @snippet example/struct.mcd.nested.cpp main
     //!
     //! 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:
     //! @snippet example/struct.custom_accessor.cpp main
     //!
     //! The only important thing is that the accessor functions are
     //! move-independent, a notion which is defined below.
     //!
     //!
     //! @anchor move-independence
     //! Move-independence
     //! -----------------
     //! 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:
     //! @code
     //!     auto z1 = f1(std::move(x));
     //!     ...
     //!     auto zn = fn(std::move(x));
     //! @endcode
     //!
     //! @note
     //! In the special case where some functions return objects that can't be
     //! bound to with `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 `Struct`s
     //! into their subparts inside the library.
     //!
     //!
     //! Laws
     //! ----
     //! For any `Struct` `S`, the accessors in the `accessors<S>()` sequence
     //! must be move-independent, as defined above.
     //!
     //!
     //! Refined concepts
     //! ----------------
     //! 1. `Comparable` (free model)\n
     //! `Struct`s are required to be `Comparable`. Specifically, two `Struct`s
     //! 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.
     //! @include example/struct/comparable.cpp
     //!
     //! 2. `Foldable` (free model)\n
     //! A `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.
     //! @include example/struct/foldable.cpp
     //! Being a model of `Foldable` makes it possible to turn a `Struct`
     //! into basically any `Sequence`, but also into a `hana::map` by simply
     //! using the `to<...>` function!
     //! @include example/struct/to.cpp
     //!
     //! 3. `Searchable` (free model)\n
     //! A `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.
     //! @include example/struct/searchable.cpp
     template <typename S>
     struct Struct;
 }} // end namespace boost::hana
 
 #endif // !BOOST_HANA_FWD_CONCEPT_STRUCT_HPP

This page was automatically generated by the 2.3.7 LXR engine. The LXR team