Reference

wrap1c(3bobcat)

Configurabale unary argument wrapper template class

NAME

FBB::Wrap1c - Configurabale unary argument wrapper template class

SYNOPSIS

#include <bobcat/wrap1c>

DESCRIPTION

The FBB::Wrap1c class is a configurable unary 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 called 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::Wrap1c 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::Wrap1c template class has the following template parameters:

o

Type: the type of the object passed to FBB::Wrap1c's operator()() 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 (const) pointers. Note that plain values are handled as const-references, and that called functions should therefore not use value parameter types but const & types instead.

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::Wrap1c'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 void by default. By specifying another type, the FBB::Wrap1c 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::Wrap1c object may be interpreted as a Unary Predicate

NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

-

CONSTRUCTORS

o

Wrap1c<Type, Context [, ReturnType = void]> (ReturnType (*fun)(Type &, 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.

Both 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 16 different types of constructors. E.g.:

o

Wrap1c<Type, Context [, ReturnType = void]> (ReturnType (*fun)(Type &, Context const &), Context const &context):

or

o

Wrap1c<Type, Context [, ReturnType = void]> (ReturnType (*fun)(Type *, Context &), Context &context):

When the function pointed to by fun is called from FBB::Wrap1c::operator()(), it receives the latter function's argument as its first argument. The template parameter Type is the data type to which iterators (as specified in, e.g., std::for_each()) 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 (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(argument).

OVERLOADED OPERATORS

In normal situations the following member functions will call the function that's passed to FBB::Wrap1c's constructor. See the example below.

o

ReturnType operator()(Type &param) 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). This operator is used when the first parameter of the specified function pointer is a reference parameter.

o

ReturnType operator()(Type const &param) 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 immutable Type objects). This operator is used when the first parameter of the specified function pointer is a const reference parameter.

o

ReturnType operator()(Type *param) 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 pointers to modifiable Type objects). This operator is used when the first parameter of the specified function pointer is a pointer parameter.

o

ReturnType operator()(Type const *param) 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 pointers to immutable Type objects). This operator is used when the first parameter of the specified function pointer is a const pointer parameter.

TYPEDEFS

The class defines two types, which are used by generic algorithms:

o

argument_type:
, a synonym for Type;

o

result_type:
, a synonym for ReturnType.

EXAMPLES

    // inserting strings to a configurable stream, together with a 
    // order-number, until the first empty string is encountered,
    // using find_if():
    #include <iostream>
    #include <vector>
    #include <string>
    #include <algorithm>
    #include <bobcat/wrap1c>
    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("");
                d_vs.push_back("three");
            }
            void display(ostream &out) const
            {
                SContext c = {1, out};
                find_if(d_vs.begin(), d_vs.end(),
                    Wrap1c<string, SContext, bool>
                         (&Strings::untilEmpty, c));
            }
        private:
            struct SContext
            {
                size_t nr;
                ostream &out;
            };
            static bool untilEmpty(string const &str, SContext &c)
            {
                if (str.empty())
                    return true;        // stop
                c.out << c.nr++ << " " << str << endl;
                return false;           // don't stop
            }
    };
    int main()
    {
        Strings s;
        s.display(cout);
    }

FILES

bobcat/wrap1c - defines the class interface

SEE ALSO

bobcat(7), wrap1(3bobcat), wrap2(3bobcat), wrap2c(3bobcat)

BUGS

None Reported.

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 ([email protected]).