1/*!
2@file
3Forward declares `boost::hana::Comonad`.
4
5Copyright Louis Dionne 2013-2022
6Distributed 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_COMONAD_HPP
11#define BOOST_HANA_FWD_CONCEPT_COMONAD_HPP
12
13#include <boost/hana/config.hpp>
14
15
16namespace boost { namespace hana {
17 // Note: We use a multiline C++ comment because there's a double backslash
18 // symbol in the documentation (for LaTeX), which triggers
19 // warning: multi-line comment [-Wcomment]
20 // on GCC.
21
22 /*!
23 @ingroup group-concepts
24 @defgroup group-Comonad Comonad
25 The `Comonad` concept represents context-sensitive computations and
26 data.
27
28 Formally, the Comonad concept is dual to the Monad concept.
29 But unless you're a mathematician, you don't care about that and it's
30 fine. So intuitively, a Comonad represents context sensitive values
31 and computations. First, Comonads make it possible to extract
32 context-sensitive values from their context with `extract`.
33 In contrast, Monads make it possible to wrap raw values into
34 a given context with `lift` (from Applicative).
35
36 Secondly, Comonads make it possible to apply context-sensitive values
37 to functions accepting those, and to return the result as a
38 context-sensitive value using `extend`. In contrast, Monads make
39 it possible to apply a monadic value to a function accepting a normal
40 value and returning a monadic value, and to return the result as a
41 monadic value (with `chain`).
42
43 Finally, Comonads make it possible to wrap a context-sensitive value
44 into an extra layer of context using `duplicate`, while Monads make
45 it possible to take a value with an extra layer of context and to
46 strip it with `flatten`.
47
48 Whereas `lift`, `chain` and `flatten` from Applicative and Monad have
49 signatures
50 \f{align*}{
51 \mathtt{lift}_M &: T \to M(T) \\
52 \mathtt{chain} &: M(T) \times (T \to M(U)) \to M(U) \\
53 \mathtt{flatten} &: M(M(T)) \to M(T)
54 \f}
55
56 `extract`, `extend` and `duplicate` from Comonad have signatures
57 \f{align*}{
58 \mathtt{extract} &: W(T) \to T \\
59 \mathtt{extend} &: W(T) \times (W(T) \to U) \to W(U) \\
60 \mathtt{duplicate} &: W(T) \to W(W(T))
61 \f}
62
63 Notice how the "arrows" are reversed. This symmetry is essentially
64 what we mean by Comonad being the _dual_ of Monad.
65
66 @note
67 The [Typeclassopedia][1] is a nice Haskell-oriented resource for further
68 reading about Comonads.
69
70
71 Minimal complete definition
72 ---------------------------
73 `extract` and (`extend` or `duplicate`) satisfying the laws below.
74 A `Comonad` must also be a `Functor`.
75
76
77 Laws
78 ----
79 For all Comonads `w`, the following laws must be satisfied:
80 @code
81 extract(duplicate(w)) == w
82 transform(duplicate(w), extract) == w
83 duplicate(duplicate(w)) == transform(duplicate(w), duplicate)
84 @endcode
85
86 @note
87 There are several equivalent ways of defining Comonads, and this one
88 is just one that was picked arbitrarily for simplicity.
89
90
91 Refined concept
92 ---------------
93 1. Functor\n
94 Every Comonad is also required to be a Functor. At first, one might think
95 that it should instead be some imaginary concept CoFunctor. However, it
96 turns out that a CoFunctor is the same as a `Functor`, hence the
97 requirement that a `Comonad` also is a `Functor`.
98
99
100 Concrete models
101 ---------------
102 `hana::lazy`
103
104 [1]: https://wiki.haskell.org/Typeclassopedia#Comonad
105
106 */
107 template <typename W>
108 struct Comonad;
109}} // end namespace boost::hana
110
111#endif // !BOOST_HANA_FWD_CONCEPT_COMONAD_HPP
112

source code of boost/libs/hana/include/boost/hana/fwd/concept/comonad.hpp