1 [/==============================================================================
2 Copyright (C) 2001-2010 Joel de Guzman
3 Copyright (C) 2001-2005 Dan Marsden
4 Copyright (C) 2001-2010 Thomas Heller
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 ===============================================================================/]
10 [section Extending Actors]
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.
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.
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].
27 [heading Requirements]
29 Let's repeat what we want to have:
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)]]
41 Additionally, we want all the operator() overloads of the regular actor.
43 [heading Defining the actor]
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`]
50 template <typename Expr>
51 struct container_actor
54 typedef actor<Expr> base_type;
55 typedef container_actor<Expr> that_type;
57 container_actor( base_type const& base )
58 : base_type( base ) {}
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; }
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; }
71 [heading Using the actor]
73 Although the member functions do nothing right now, we want to test if we can use
76 First, lets create a generator which wraps the `container_actor` around any other
79 template <typename Expr>
80 container_actor<Expr> const
81 container( actor<Expr> const& expr )
94 (container(arg1).size())(v);
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],
100 Let's have an [link phoenix.modules.core.arguments argument placeholder]
101 which is usable as if it was a STL container:
103 container_actor<expression::argument<1>::type> const con1;
106 The above example can be rewritten as:
118 [heading Adding life to the actor]
120 This one will be even easier!
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:
128 // result_of protocol:
129 template <typename Sig>
132 template <typename This, typename Container>
133 struct result<This(Container)>
135 // Note, remove reference here, because Container can be anything
136 typedef typename boost::remove_reference<Container>::type container_type;
138 // The result will be size_type
139 typedef typename container_type::size_type type;
142 template <typename Container>
143 typename result<size_impl(Container const&)>::type
144 operator()(Container const& container) const
146 return container.size();
150 Good, this was the first part. The second part will be to implement the size member
151 function of `container_actor`:
153 template <typename Expr>
154 struct container_actor
157 typedef actor<Expr> base_type;
158 typedef container_actor<Expr> that_type;
160 container_actor( base_type const& base )
161 : base_type( base ) {}
163 typename expression::function<size_impl, that_type>::type const
166 function<size_impl> const f = size_impl();
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]).