--- name: "fnwrap2c" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "2.08.01-1" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/fnwrap2c" --- # fnwrap2c(3bobcat) Configurabale binary argument wrapper template class ## NAME FnWrap2c - Configurabale binary argument wrapper template class ## SYNOPSIS **#include \**\ ## DESCRIPTION The **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 *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 **FnWrap?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::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. - 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::FnWrap2c** template class has the following template parameters: - o *Type1*: the type of the first argument passed to **FBB::FnWrap2c**’s **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). - o *Type2*: the type of the second argument passed to **FBB::FnWrap2c**’s **operator()()** function. Specify the type as the type of the second parameter of the function whose address is passed to the constructor. - o *Context*: the **local context struct**. This **struct** is a local **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 **struct** definition. The function will now receive a \`standardized’ parameter list, defined by the local context struct. The type of the defined **struct** as specified in the parameterlist of the function whose address is passed to **FnWrap2c**’s constructor should be specified for *Context*. E.g., *LocalStruct &*. - When a *non-const* reference or pointer is specified, the function may modify the **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 **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 [**lc**(3bobcat)](/lc/3bobcat.md) for details. - - o *ReturnType*: the **ReturnType** is by default defined as *void*. By specifying another type, the **FBB::FnWrap2c** object’s **operator()()** function will return the called function’s return value as a value of the specified type. E.g, by specifying a *bool* **ReturnType**, the **FBB::FnWrap2c** object may be used as a *Unary Predicate*. Alternatively, pointers or references may be specified as return values. ## NAMESPACE **FBB**\ All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace **FBB**. ## INHERITS FROM \- ## CONSTRUCTOR - o **FnWrap2c\** **(ReturnType (\*fun)(Type1, Type2, Context), Context context)**:\ \ This 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. - When the function pointed to by *fun* is called from **FBB::FnWrap2c::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 *Type1* and *Type2* must define the data type to which iterators eventually point. - 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 a (const) pointer) can be specified as the context parameter, passing, e.g., *\*this* as the context. The static member function may then call any of the non-static member functions of the class *Class* using the normal syntax (e.g., *obj.member(argument)* if the static function defines as its second parameter *Class &obj*). ## OVERLOADED OPERATOR The following member function will call the function that’s passed to **FBB::FnWrap2c**’s constructor. See the example below. - o **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 *Type1* and *Type2* objects). This function calls the function specified at **FBB::FnWrap2c**’s constructor, passing its parameters to that function as its first two arguments, and the local context as its third argument. ## TYPEDEFS The class defines three types, which are used by generic algorithms: - o **first\_argument\_type**:\ , a synonym for the basic type specified with the *Type1* template parameter. E.g., if *Type1* is specified as *std::string* *const \** then *argument\_type* will be *std::string*; - o **second\_argument\_type**:\ , a synonym for the basic type specified with the *Type2* template parameter. - o **result\_type**:\ , a synonym for the basic type specified with the **ReturnType** template parameter. ## 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"), FnWrap2c(&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. ## FILES *bobcat/fnwrap2c* - defines the class interface ## SEE ALSO [**bobcat**(7)](/bobcat/7.md), [**fnwrap**(3bobcat)](/fnwrap/3bobcat.md), [**fnwrap1**(3bobcat)](/fnwrap1/3bobcat.md), [**fnwrap2**(3bobcat)](/fnwrap2/3bobcat.md), [**fnwrap2**(3bobcat)](/fnwrap2/3bobcat.md), [**foreach**(3bobcat)](/foreach/3bobcat.md), [**lc**(3bobcat)](/lc/3bobcat.md), [**repeat**(3bobcat)](/repeat/3bobcat.md) ## BUGS The [**fnwrap**(3bobcat)](/fnwrap/3bobcat.md) function wrapper is easier to use an provides this class’s functionality. *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 *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 *FnWrap1c* object. ## DISTRIBUTION FILES - o *bobcat\_2.08.01-x.dsc*: detached signature; - o *bobcat\_2.08.01-x.tar.gz*: source archive; - o *bobcat\_2.08.01-x\_i386.changes*: change log; - o *libbobcat1\_2.08.01-x\_\*.deb*: debian package holding the libraries; - o *libbobcat1-dev\_2.08.01-x\_\*.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**).