This page is no longer maintained.

The Binder Library is now part of a larger template library:

  "The Lambda Library" available at lambda.cs.utu.fi.

Please update your link.









[Introduction to Binding]  [Introduction to Tuples]  [What's New]  [Copyright]  [Downloading and Installation]  [Portability]  [Contact Information]


   - The Binder Library

What is the Binder Library?

BL is a C++ template library. It implements a simple and versatile function argument binding mechanism, which can be used with STL algorithms. Compared to the rather limited standard binders (bind1st, bind2nd), BL makes argument binding easy and general: arbitrary arguments of (almost) any C++ function can be bound. The BL binding mechanism induces very little or no runtime cost.

In addition to binders, BL implements a tuple abstraction, which is basically a generalisation of the standard pair template. Tuples are convenient in defining functions, which return multiple values.
 

Short Introduction to BL Function Argument Binding

Consider the following two functions:

double exponential(double x, double lambda);
double gaussian(double x, double mean, double standard_deviation);

Obviously the functions compute values from exponential and Gaussian distributions. To use the exponential function within STL algorithms, we could write as follows:

vector<double> x, result; double lambda;
    ...
transform(x.begin(), x.end(), result.begin(),
             bind2nd(ptr_fun(exponential), lambda));

But there it ends. There is no way of using the gaussian function as a function object with standard binders.

BL solves this problem. The arguments which are not bound are specified with special placeholder objects, not as an index of the bind funciton.  Hence, BL has only one bind function (called bind, obviously). The previous example becomes:

transform(x.begin(), x.end(), result.begin(),
             bind(exponential, free1, lambda));

The Gaussian value computation could be programmed as:

double mean, std;
    ...
transform(x.begin(), x.end(), result.begin(),
             bind(gaussian, free1, mean, std));

In these examples, free1 is a placeholder object. The expression bind(gaussian, free1, mean, std)(1.0) is equivalent to gaussian(1.0, mean, std). BL defines two placeholders: free1 and free2. They can appear in arbitrary positions in the argument list.  Arguments can be of arbitrary type, except that volatile qualified types are not currently supported. The target function can be a pointer to nonmember function, pointer to const or nonconst member function, an STL adaptable function object or a BL bindable funciton object. Constructors can not be used as target functions. BL 1.0 supports functions up to 10 arguments.

Function composition with BL

The bind expressions can be recursive. That is, any argument in a bind expression can be replaced with another bind expression.  For example, suppose we have some values in vectors x and y, and for each value pair, we want to compute the gaussian function value of their sum with some mean and std. This can be programmed as:

vector<double> x, y, result; double mean, std;
    ...
transform(x.begin(), x.end(), result.begin(),
             bind(gaussian, bind(plus<double>(), free1, free2), mean, std));

Short Introduction to Tuples

A tuple (or n-tuple) is a fixed size collection of elements. Pairs, triples, etc. are tuples. In BL, an n-element tuple is a template having n parameters. Each parameter defines the type of one element:

tuple<int, float, std::string> is a three-element tuple type, the elements types are int, float and std::string. Tuples can be used quite similarly to the standard pair template. They can be constructed either directly or with make_tuple functions:

tuple<int, float, string> a(1, 3.14, string("foo"));
make_tuple(1, 3.14, string("foo"));

In particular, tuples can be used as function return values. For example, suppose we are writing a matrix decomposition operation SVD. It decomposes one matrix into two matrices and a vector. The traditional way of defining and calling such a function is:

void SVD(const Matrix* A, Matrix* U, Vector* S, Matrix* V).
    ...
Matrix *A, *U, *V; Vector *S;
    ...
SVD(A, U, S, V);

Here, the distinction between input and output values is not necessarily clear. Furthermore, it can not be seen from the function prototype how the results U, S, and V should be initialised.  However, it is not propably worthwile to write a new class to be used as the return value of SVD. The solution is to use a tuple return type. The example becomes:

tuple<Matrix, Vector, Matrix> SVD(const Matrix& A);
    ...
Matrix A, U, V; Vector S;
    ...
tie(U, S, V) = SVD(A);

The tie function template is a special tuple construction function which creates a tuple containing references to the actuals of the tie invocation. The above expression is in effect a multivalued assignment.
 

What's New (Revision History)

02 Feb 2000, v. 1.1.1 Bug fixes
25 Jan 2000, v. 1.1.0 Tuples: Added assignment from std::pairs
  Paricularly, tie(a, b) = make_pair(x, y) is ok.

Tuples: Overloaded operator<<(ostream&, cons<HT, TT>&) for writing tuples into a stream:
  cout << make_tuple(1, 2, "Hello") outputs: (1, 2, Hello)

Tuples: Added get accessors as member functions:
  aTuple.get<N>() is equal to get<N>(aTuple)

Tuples: Added tuple_length template
  tuple_length<a_tuple_type>::value computes the length of a tuple type at compile time

Tuples: assignment operators return a non-const reference to *this, not void anymore

All: namespace can be specified with a define

All: header file ending is changed from .h to .hpp

30. Sep 1999, v. 1.0.2 Bug fixes
20. Sep 1999, v.1.0.1 Bug fixes
17. Sep 1999, v.1.0.0 Initial release

Copyright

Copyright © 1999, 2000 Jaakko Järvi (jaakko.jarvi@cs.utu.fi)

The Binder Library is free software; Permission to copy and use this software is granted, provided this copyright notice appears in all copies. Permission to modify the code and to distribute modified code is granted, provided this copyright notice app ears in all copies, and a notice that the code was modified is included with the copyright notice.

This software is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

Downloading and Installing the Library

Download the file binder_library.1.1.1.tar.gz, and unpack the package:

> gunzip binder_library.1.1.1.tar.gz
> tar xvf binder_library.1.1.1.tar

The extracted files will be placed into bl subdirectory. To use the library, place the directory where bl subdirectory resides in the include search path ( -Idir_name in gcc) and #include <bl/binder.hpp> in your C++ program (if you only use tuples, not the binding mechanism, it is enough to #include & lt;bl/tuple.hpp>). All names in BL are in namespace boost, but this can be changed with a define (see the user's guide).

You may also want to download the BL user's guide/ reference manual (gzipped postscript) (pdf).

and some further reading:

Järvi Jaakko: C++ Function Object Binders Made Easy, Proceedings of The First International Symposium on Generative and Component-Based Software Engineering (GCSE'99), September 28-30 1999, Erfurt, Germany, to appear in LNCS, (contact author).

Järvi Jaakko: Tuples and Multiple Return Values in C++, TUCS Technical Report No 249, March 1999. (slightly outdated, but the idea becomes clear)

Järvi Jaakko: ML-style Tuple Assignment in Standard C++ - Extending the Multiple Return Value Formalism, TUCS Technical Report No 267, April 1999. (slightly outdated, but the idea becomes clear)

The version number is of the form X.Y.Z . Increase in the value of  Z means internal changes which do not alter the functionality of the library (other than fixing bugs). Increase in the value in Y indicates changes that alter the functionality, but are backwards compatible. Change in X means indicates, that changes, which are not backward compatible, have been made.

Note! The library is still somewhat experimental and not heavily tested. New versions containing bug-fixes and modifications are likely to be released every now and then.

Portability

The BL is written in standard C++, so it works(?) with any standard conforming compiler (are there any?).  However, the current version has been tested only with GCC 2.95. I am greatful for any information about problems/success/... with other compilers.

Bugs, Suggestions and Contact Information

Bug reports, bug fixes, suggestions and other feedback are wellcome.  The author's contact information is:

homepage: http://www.cs.utu.fi/staff/jaakko.jarvi
e-mail: jaakko.jarvi@cs.utu.fi.


Visitors since Sep.17, 1999