]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/============================================================================== |
2 | Copyright (C) 2001-2010 Joel de Guzman | |
3 | Copyright (C) 2001-2005 Dan Marsden | |
4 | Copyright (C) 2001-2010 Thomas Heller | |
5 | ||
6 | Distributed under the Boost Software License, Version 1.0. (See accompanying | |
7 | file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
8 | ===============================================================================/] | |
9 | ||
10 | [section Extending Actors] | |
11 | ||
12 | [link phoenix.inside.actor Actors] are one of the main parts of the | |
13 | library, and one of the many customization points. The default actor implementation | |
14 | provides several operator() overloads which deal with the evaluation of expressions. | |
15 | ||
16 | For some use cases this might not be enough. For convenience it is thinkable to | |
17 | provide custom member functions which generate new expressions. An example is the | |
18 | [link phoenix.modules.statement.___if_else_____statement '''if_else_''' | |
19 | Statement] which provides an additional else member for generating a lazy if-else | |
20 | expression. With this the actual Phoenix expression becomes more expressive. | |
21 | ||
22 | Another scenario is to give actors the semantics of a certain well known interface | |
23 | or concept. This tutorial like section will provide information on how to implement | |
24 | a custom actor which is usable as if it were a | |
25 | [@http://www.sgi.com/tech/stl/Container.html STL Container]. | |
26 | ||
27 | [heading Requirements] | |
28 | ||
29 | Let's repeat what we want to have: | |
30 | ||
31 | [table | |
32 | [[Expression] [Semantics]] | |
33 | [[`a.begin()`] [Returns an iterator pointing to the first element in the container.]] | |
34 | [[`a.end()`] [Returns an iterator pointing one past the last element in the container.]] | |
35 | [[`a.size()`] [Returns the size of the container, that is, its number of elements.]] | |
36 | [[`a.max_size()`] [Returns the largest size that this container can ever have.]] | |
37 | [[`a.empty()`] [Equivalent to a.size() == 0. (But possibly faster.)]] | |
38 | [[`a.swap(b)`] [Equivalent to swap(a,b)]] | |
39 | ] | |
40 | ||
41 | Additionally, we want all the operator() overloads of the regular actor. | |
42 | ||
43 | [heading Defining the actor] | |
44 | ||
45 | The first version of our `container_actor` interface will show the general | |
46 | principle. This will be continually extended. For the sake of simplicity, | |
47 | every member function generator will return [link phoenix.modules.core.nothing `nothing`] | |
48 | at first. | |
49 | ||
50 | template <typename Expr> | |
51 | struct container_actor | |
52 | : actor<Expr> | |
53 | { | |
54 | typedef actor<Expr> base_type; | |
55 | typedef container_actor<Expr> that_type; | |
56 | ||
57 | container_actor( base_type const& base ) | |
58 | : base_type( base ) {} | |
59 | ||
60 | expression::null<mpl::void_>::type const begin() const { return nothing; } | |
61 | expression::null<mpl::void_>::type const end() const { return nothing; } | |
62 | expression::null<mpl::void_>::type const size() const { return nothing; } | |
63 | expression::null<mpl::void_>::type const max_size() const { return nothing; } | |
64 | expression::null<mpl::void_>::type const empty() const { return nothing; } | |
65 | ||
66 | // Note that swap is the only function needing another container. | |
67 | template <typename Container> | |
68 | expression::null<mpl::void_>::type const swap( actor<Container> const& ) const { return nothing; } | |
69 | }; | |
70 | ||
71 | [heading Using the actor] | |
72 | ||
73 | Although the member functions do nothing right now, we want to test if we can use | |
74 | our new actor. | |
75 | ||
76 | First, lets create a generator which wraps the `container_actor` around any other | |
77 | expression: | |
78 | ||
79 | template <typename Expr> | |
80 | container_actor<Expr> const | |
81 | container( actor<Expr> const& expr ) | |
82 | { | |
83 | return expr; | |
84 | } | |
85 | ||
86 | Now let's test this: | |
87 | ||
88 | std::vector<int> v; | |
89 | v.push_back(0); | |
90 | v.push_back(1); | |
91 | v.push_back(2); | |
92 | v.push_back(3); | |
93 | ||
94 | (container(arg1).size())(v); | |
95 | ||
96 | Granted, this is not really elegant and not very practical (we could have just | |
97 | used phoenix::begin(v) from the [link phoenix.modules.stl.algorithm Phoenix algorithm module], | |
98 | but we can do better. | |
99 | ||
100 | Let's have an [link phoenix.modules.core.arguments argument placeholder] | |
101 | which is usable as if it was a STL container: | |
102 | ||
103 | container_actor<expression::argument<1>::type> const con1; | |
104 | // and so on ... | |
105 | ||
106 | The above example can be rewritten as: | |
107 | ||
108 | std::vector<int> v; | |
109 | v.push_back(0); | |
110 | v.push_back(1); | |
111 | v.push_back(2); | |
112 | v.push_back(3); | |
113 | ||
114 | (con1.size())(v); | |
115 | ||
116 | Wow, that was easy! | |
117 | ||
118 | [heading Adding life to the actor] | |
119 | ||
120 | This one will be even easier! | |
121 | ||
122 | First, we define a [link phoenix.modules.function lazy function] which | |
123 | evaluates the expression we want to implement. | |
124 | Following is the implementation of the size function: | |
125 | ||
126 | struct size_impl | |
127 | { | |
128 | // result_of protocol: | |
129 | template <typename Sig> | |
130 | struct result; | |
131 | ||
132 | template <typename This, typename Container> | |
133 | struct result<This(Container)> | |
134 | { | |
135 | // Note, remove reference here, because Container can be anything | |
136 | typedef typename boost::remove_reference<Container>::type container_type; | |
137 | ||
138 | // The result will be size_type | |
139 | typedef typename container_type::size_type type; | |
140 | }; | |
141 | ||
142 | template <typename Container> | |
143 | typename result<size_impl(Container const&)>::type | |
144 | operator()(Container const& container) const | |
145 | { | |
146 | return container.size(); | |
147 | } | |
148 | }; | |
149 | ||
150 | Good, this was the first part. The second part will be to implement the size member | |
151 | function of `container_actor`: | |
152 | ||
153 | template <typename Expr> | |
154 | struct container_actor | |
155 | : actor<Expr> | |
156 | { | |
157 | typedef actor<Expr> base_type; | |
158 | typedef container_actor<Expr> that_type; | |
159 | ||
160 | container_actor( base_type const& base ) | |
161 | : base_type( base ) {} | |
162 | ||
163 | typename expression::function<size_impl, that_type>::type const | |
164 | size() const | |
165 | { | |
166 | function<size_impl> const f = size_impl(); | |
167 | return f(*this); | |
168 | } | |
169 | ||
170 | // the rest ... | |
171 | }; | |
172 | ||
173 | It is left as an exercise to the user to implement the missing parts by reusing | |
174 | functions from the [link phoenix.modules.stl.algorithm Phoenix Algorithm Module] | |
175 | (the impatient take a look here: [@../../example/container_actor.cpp container_actor.cpp]). | |
176 | ||
177 | [endsect] |