1 /*! 2 @file 3 Forward declares `boost::hana::Product`. 4 5 @copyright Louis Dionne 2013-2017 6 Distributed under the Boost Software License, Version 1.0. 7 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt) 8 */ 9 10 #ifndef BOOST_HANA_FWD_CONCEPT_PRODUCT_HPP 11 #define BOOST_HANA_FWD_CONCEPT_PRODUCT_HPP 12 13 #include <boost/hana/config.hpp> 14 15 16 namespace boost { namespace hana { 17 //! @ingroup group-concepts 18 //! @defgroup group-Product Product 19 //! Represents types that are generic containers of two elements. 20 //! 21 //! This concept basically represents types that are like `std::pair`. 22 //! The motivation for making such a precise concept is similar to the 23 //! motivation behind the `Sequence` concept; there are many different 24 //! implementations of `std::pair` in different libraries, and we would 25 //! like to manipulate any of them generically. 26 //! 27 //! Since a `Product` is basically a pair, it is unsurprising that the 28 //! operations provided by this concept are getting the first and second 29 //! element of a pair, creating a pair from two elements and other 30 //! simmilar operations. 31 //! 32 //! @note 33 //! Mathematically, this concept represents types that are category 34 //! theoretical [products][1]. This is also where the name comes 35 //! from. 36 //! 37 //! 38 //! Minimal complete definition 39 //! --------------------------- 40 //! `first`, `second` and `make` 41 //! 42 //! `first` and `second` must obviously return the first and the second 43 //! element of the pair, respectively. `make` must take two arguments `x` 44 //! and `y` representing the first and the second element of the pair, 45 //! and return a pair `p` such that `first(p) == x` and `second(p) == y`. 46 //! @include example/product/make.cpp 47 //! 48 //! 49 //! Laws 50 //! ---- 51 //! For a model `P` of `Product`, the following laws must be satisfied. 52 //! For every data types `X` and `Y`, there must be a unique function 53 //! @f$ \mathtt{make} : X \times Y \to P @f$ such that for every `x`, `y`, 54 //! @code 55 //! x == first(make<P>(x, y)) 56 //! y == second(make<P>(x, y)) 57 //! @endcode 58 //! 59 //! @note 60 //! This law is less general than the universal property typically used to 61 //! define category theoretical products, but it is vastly enough for what 62 //! we need. 63 //! 64 //! This is basically saying that a `Product` must be the most general 65 //! object able to contain a pair of objects `(P1, P2)`, but nothing 66 //! more. Since the categorical product is defined by a universal 67 //! property, all the models of this concept are isomorphic, and 68 //! the isomorphism is unique. In other words, there is one and only 69 //! one way to convert one `Product` to another. 70 //! 71 //! Another property that must be satisfied by `first` and `second` is 72 //! that of @ref move-independence, which ensures that we can optimally 73 //! decompose a `Product` into its two members without making redundant 74 //! copies. 75 //! 76 //! 77 //! Refined concepts 78 //! ---------------- 79 //! 1. `Comparable` (free model)\n 80 //! Two products `x` and `y` are equal iff they are equal element-wise, 81 //! by comparing the first element before the second element. 82 //! @include example/product/comparable.cpp 83 //! 84 //! 2. `Orderable` (free model)\n 85 //! Products are ordered using a lexicographical ordering as-if they 86 //! were 2-element tuples. 87 //! 88 //! 3. `Foldable` (free model)\n 89 //! Folding a `Product` `p` is equivalent to folding a list containing 90 //! `first(p)` and `second(p)`, in that order. 91 //! 92 //! 93 //! Concrete models 94 //! --------------- 95 //! `hana::pair` 96 //! 97 //! 98 //! [1]: http://en.wikipedia.org/wiki/Product_(category_theory) 99 template <typename P> 100 struct Product; 101 }} // end namespace boost::hana 102 103 #endif // !BOOST_HANA_FWD_CONCEPT_PRODUCT_HPP 104