--- name: "wrap2c" section: "3bobcat" platform: "linux" package: "libbobcat1-dev" version: "1.11.0-1" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/wrap2c" --- # wrap2c(3bobcat) Configurabale binary argument wrapper template class ## NAME Wrap2c - Configurabale binary argument wrapper template class ## SYNOPSIS **#include \**\ ## DESCRIPTION The **FBB::Wrap2c** class is a configurable binary argument wrapper template class. Its primary use is in combination with the generic algorithms from the standard template libray. The called function expects a *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 *const* or non-*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 **Wrap?c** classes to which a *local context* can be passed: - o There is no introduced uncertainty about the **const**-ness of the callled function, as static member functions do not support a **const** modifier; - o The passed function can also be a free (global) function to which a local context is passed; - o The passed function can be a static member function of the class using the generic algorithm to which the **FBB::Wrap2c** object is passed. By passing the calling object in the function's local context, the function may directly access the calling object's members. - o 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. - o 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 **FBB::Wrap2c** template class has the following template parameters: - o *Type1*: the type of the first object passed to **FBB::Wrap2c::operator()()**'s function. Specify a **plain** type, do not specify a pointer or reference type: if pointers or references are used, it will become obvious later on, as the template will be able to handle (const) references and pointers. Values are handled as const-references. - o *Type2*: the type of the second object passed to **FBB::Wrap2c::operator()()**'s function. Specify a **plain** type, do not specify a pointer or reference type: if pointers or references are used, it will become obvious later on, as the template will be able to handle (const) references and pointers. Values are handled as const-references. - o *Context*: the type of the **local context struct**. This **struct** is a local **struct**, that should be defined immediatey before applying the generic algorithm, specifying 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 **struct** definition. The function will now receive a \`standardized' parameter list, defined by the local context struct. The typename of the defined **struct** should be passed to the template as its second parameter. A concrete local context **struct** may be passed as either a *const* or non-*const* reference or pointer to **FBB::Wrap2c**'s constructor. When using a *non-const* reference or pointer, the function may modify the **struct**'s value fields identically to the situation in which the field's values would have been passed to the function as reference parameters. - o *ReturnType*: the **ReturnType** is by default defined as *void*. By specifying another type, the **FBB::Wrap2c** object's **operator()()** function will pass the called function's return value as a value of the specified type. E.g, by specifying a *bool* **ReturnType**, the **FBB::Wrap2c** object may be interpreted as a *Binary Predicate* ## NAMESPACE **FBB**\ All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace **FBB**. ## INHERITS FROM \- ## CONSTRUCTORS - o **Wrap2c\** **(ReturnType (\*fun)(Type1 &, Type2 &, Context &), Context &context)**:\ \ This is an example of the form in which the class's constructurs may be called. Each constructor expects two arguments: the address of a function to call from within its **operator()()** member, and a local context **struct** which is passed to the called function as its second argument. - All three arguments that are passed to the function pointed to by *fun* and the context struct itself may be passed as: \ reference, \ pointer,\ const reference, or \ const pointer. \ (albeit that the restriction applies that the types of the *context* constructor parameter and the function's *context* parameter must be identical (e.g., both pointers or both const references)). - Therefore, the class supports 64 different types of constructors. E.g.: - - o **Wrap2c\** **(ReturnType (\*fun)(Type1 &, Type2 \*, Context const &),** **Context const &context)**:\ or - o **Wrap2c\** **(ReturnType (\*fun)(Type1 const \*, Type2 &, Context \*),** **Context \*context)**:\ \ Hint: In situations where no context other than the class *Class* to which the class' (static) member function belongs must be used \`*Class &obj*' (or (const) pointer) can be specified as the context parameter (and *Class* itself as the context template parameter), passing, e.g., *\*this* as the context. The static member function may then call any of its class member functions *member(Type \[const\] \[&,\*\])* as *obj.member(argument1, argument2)*. ## OVERLOADED OPERATORS In normal situations the following member functions will call the function that's passed to **FBB::Wrap2c**'s constructor. See the example below. - o **ReturnType operator()(Type1 ¶m, Type1 ¶m) const**:\ This function is called by generic algorithms, receiving the dereferenced iterator that is managed by the generic algorithm as its argument (so, the iterator points to modifiable *Type* objects). - There are 16 overloaded versions of this function, one for each of the 4 x 4 combinations of the first two parameter types specified for the function whose address is passed to the class's constructor (i.e., each parameter may be specified as reference, pointer, const reference or const pointer). - Some (but not all) overloaded versions are: - o **ReturnType operator()(Type1 ¶m, Type1 \*param) const**:\ or: - o **ReturnType operator()(Type1 const \*param, Type1 ¶m) const**:\ ## TYPEDEFS The class defines three types, which are used by generic algorithms: - o **first\_argument\_type**:\ , a synonym for **Type1**; - o **second\_argument\_type**:\ , a synonym for **Type2**; - o **result\_type**:\ , a synonym for **ReturnType**. ## EXAMPLES ``` // accumulating strings from a vector to one big string, using // `accumulate' #include #include #include #include #include using namespace std; using namespace FBB; class Strings { vector 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"), Wrap2c < 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); } ``` ## FILES *bobcat/wrap2c* - defines the class interface ## SEE ALSO [**bobcat**(7)](/bobcat/7.md), [**wrap1**(3bobcat)](/wrap1/3bobcat.md), [**wrap2**(3bobcat)](/wrap2/3bobcat.md), [**wrap2**(3bobcat)](/wrap2/3bobcat.md) ## BUGS No Reported Bugs. ## DISTRIBUTION FILES - o *bobcat\_1.11.0-x.dsc*: detached signature; - o *bobcat\_1.11.0-x.tar.gz*: source archive; - o *bobcat\_1.11.0-x\_i386.changes*: change log; - o *libbobcat1\_1.11.0-x\_i386.deb*: debian package holding the libraries; - o *libbobcat1-dev\_1.11.0-x\_i386.deb*: debian package holding the libraries, headers and manual pages; - o *http://sourceforge.net/projects/bobcat*: public archive location; ## BOBCAT Bobcat is an acronym of \`Brokken's Own Base Classes And Templates'. ## COPYRIGHT This is free software, distributed under the terms of the GNU General Public License (GPL). ## AUTHOR Frank B. Brokken (**f.b.brokken@rug.nl**).