1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
includefile(header.inc)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::FnWrap2c)(3bobcat)(_CurYrs_)(libbobcat1-dev__CurVers_-x.tar.gz)
(Configurable Binary FnWrapper)
manpagename(FnWrap2c)(Configurabale binary argument wrapper template class)
manpagesynopsis()
bf(#include <bobcat/fnwrap2c>)nl()
manpagedescription()
The bf(FBB::FnWrap2c) class is a configurable binary argument context
wrapper template class. Its primary use is in combination with the generic
algorithms from the standard template libray. The called function expects a
em(local context struct) which is used to pass arguments to the function
called by the generic algorithm which are available in the local context of
the called generic algorithm. The local context struct can be either a
tt(const) or non-tt(const) struct.
The callled function itself may be specified as one of the constructor's
arguments. It must be a (static member) function. Using a (static member)
function has various advantages, especially with the bf(FnWrap?c) classes to
which a em(local context) can be passed:
itemization(
it() There is no introduced uncertainty about the bf(const)-ness of the
callled function, as static member functions do not support
a bf(const) modifier;
it() The passed function can also be a free (global) function to which a
local context is passed;
it() The passed function can be a static member function of the class
using the generic algorithm to which the bf(FBB::FnWrap2c) object is passed. By
passing the calling object in the function's local context, the function may
directly access the calling object's members.
it() The passed function can be a static member function of the class
whose objects are passed to the function via the generic template function s
iterator parameters. In that case the function may directly access the passed
object's members.
it() Since no object is involved in calling the static function, no
ambiguity can arise as to whether an object reference or an object pointer
should be used in calling the function: static (member) functions may be
called without using objects.
)
The bf(FBB::FnWrap2c) template class has the following template parameters:
itemization(
itt(Type1): the type of the first argument passed to bf(FBB::FnWrap2c)'s
bf(operator()()) function. Specify the type as the type of the first parameter
of the function whose address is passed to the constructor (i.e., specify a
plain value or a (const) pointer or reference).
itt(Type2): the type of the second argument passed to bf(FBB::FnWrap2c)'s
bf(operator()()) function. Specify the type as the type of the second parameter
of the function whose address is passed to the constructor.
itt(Context): the bf(local context struct). This bf(struct) is a local
bf(struct), an object of which could have been defined immediatey before
applying the generic algorithm. The local context struct object may specify
values, references or pointers to entities that are available in the local
context where the generic algorithm is called.
If no generic algorithm would have been used, but a local implementation
of the generic algorithm would have been used instead, then the called
function would have received certain arguments. The local context struct is a
replacement of such a function's parameter list, mimicking the function's
parameter list in the bf(struct) definition. The function will now receive a
`standardized' parameter list, defined by the local context struct. The type
of the defined bf(struct) as specified in the parameterlist of the function
whose address is passed to bf(FnWrap2c)'s constructor should be specified for
tt(Context). E.g., tt(LocalStruct &).
When a em(non-const) reference or pointer is specified, the function may
modify the bf(struct)'s value fields identically to the situation where the
field's values are passed to the function as reference parameters.
Local context structs may also be generated using the bf(FBB::LC) local
Context Struct generating template class. Using a template-generated local
context struct reduces namespace and class-pollution: the software engineer
does not have to put any effort in finding an appropriate struct name and
doesn't even have to enter the struct's definition in, e.g., a class
header. The template takes care of the definition an declaration of the proper
type which will thus be available to classes, member functions and free
functions. Cf. the bf(lc)(3bobcat) for details.
itt(ReturnType): the bf(ReturnType) is by default defined as tt(void). By
specifying another type, the bf(FBB::FnWrap2c) object's bf(operator()())
function will return the called function's return value as a value of the
specified type. E.g, by specifying a tt(bool) bf(ReturnType), the
bf(FBB::FnWrap2c) object may be used as a em(Unary Predicate). Alternatively,
pointers or references may be specified as return values.
)
includefile(namespace.inc)
manpagesection(INHERITS FROM)
-
manpagesection(CONSTRUCTOR)
itemization(
itb(FnWrap2c<Type1, Type2, Context [, ReturnType = void]>
(ReturnType (*fun)(Type1, Type2, Context), Context context)) nl()
This constructor expects two arguments: the address of a function to
call from within its bf(operator()()) member, and a local context bf(struct)
which is passed to the called function as its second argument.
When the function pointed to by tt(fun) is called from
bf(FBB::FnWrap2c)bf(::operator()()), it receives the latter function's
arguments as its first two arguments and the local context struct as its third
argument. With (STL) generic algorithms, the template parameters tt(Type1) and
tt(Type2) must define the data type to which iterators eventually point.
Hint: In situations where no context other than the class tt(Class) to
which the class' (static) member function belongs must be used `tt(Class
&obj)' (or a (const) pointer) can be specified as the context parameter,
passing, e.g., tt(*this) as the context. The static member function may then
call any of the non-static member functions of the class tt(Class) using the
normal syntax (e.g., tt(obj.member(argument)) if the static function defines
as its second parameter tt(Class &obj)).
)
manpagesection(OVERLOADED OPERATOR)
The following member function will call the function
that's passed to bf(FBB::FnWrap2c)'s constructor. See the example below.
itemization(
itb(ReturnType operator()(Type1 param1, Type2 param2) const)
This function is called by generic algorithms, receiving the
dereferenced iterators that are managed by the generic algorithm as its
arguments (so, the iterators may point to modifiable tt(Type1) and tt(Type2)
objects). This function calls the function specified at bf(FBB::FnWrap2c)'s
constructor, passing its parameters to that function as its first
two arguments, and the local context as its third argument.
)
manpagesection(TYPEDEFS)
The class defines three types, which are used by generic algorithms:
itemization(
itb(first_argument_type), a synonym for the basic type specified with the
tt(Type1) template parameter. E.g., if tt(Type1) is specified as tt(std::string
const *) then tt(argument_type) will be tt(std::string);
itb(second_argument_type), a synonym for the basic type specified with the
tt(Type2) template parameter.
itb(result_type), a synonym for the basic type specified with the
bf(ReturnType) template parameter.
)
manpagesection(EXAMPLES)
verb(
// accumulating strings from a vector to one big string, using
// `accumulate'
#include <iostream>
#include <numeric>
#include <string>
#include <vector>
#include <bobcat/fnwrap2c>
using namespace std;
using namespace FBB;
class Strings
{
vector<string> d_vs;
public:
Strings()
{
d_vs.push_back("one");
d_vs.push_back("two");
d_vs.push_back("three");
}
void display(ostream &out) const
{
SContext c = {1, out};
cout << "On Exit: " <<
accumulate(
d_vs.begin(), d_vs.end(),
string("HI"),
FnWrap2c<string const &, string const &,
SContext &, string>(&show, c)
) <<
endl;
}
private:
struct SContext
{
size_t nr;
ostream &out;
};
static string show(string const &str1,
string const &str2,
SContext &c)
{
c.out << c.nr++ << " " << str1 << " " << str2 <<
endl;
return str1 + " " + str2;
}
};
int main()
{
Strings s;
s.display(cout);
}
)
After compilation and linking, simply call the program without any
arguments.
manpagefiles()
em(bobcat/fnwrap2c) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(fnwrap)(3bobcat),
bf(fnwrap1)(3bobcat), bf(fnwrap2)(3bobcat),
bf(fnwrap2)(3bobcat), bf(foreach)(3bobcat), bf(lc)(3bobcat),
bf(repeat)(3bobcat)
manpagebugs()
The bf(fnwrap)(3bobcat) function wrapper is easier to use an provides this
class's functionality.
em(Caveat): the template parameter specifying the type of the local
context struct should probably not be specified as a value type as this will
result in copying the local context struct for each call of the tt(FNWrap2c)
object or of the function that it is provided with, making it impossible for
the algorithms to modify value- or pointer-fields of the outermost local
context struct. Instead, the template type specifying the type of the local
context struct should be specified as a pointer or reference template type
when instantiating the tt(FnWrap1c) object.
includefile(trailer.inc)
|
