From b19b0e4d6617496c8820cf80dc935d7ef33092ba Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Tue, 27 Nov 2001 13:15:30 +0000 Subject: [PATCH] bind.html: Contents, FAQ, Dependencies added. [SVN r11787] --- bind.html | 224 +++++++++++++++++++++++++++++++++++++++++----------- mem_fn.html | 12 +-- 2 files changed, 184 insertions(+), 52 deletions(-) diff --git a/bind.html b/bind.html index dee6dd6..c113a4f 100644 --- a/bind.html +++ b/bind.html @@ -12,7 +12,7 @@
- c++boost.gif (8819 bytes) + c++boost.gif (8819 bytes)

bind.hpp

@@ -23,17 +23,48 @@
-

Files

- +

Contents

-

Purpose

+

Purpose

+

Using bind with functions and function pointers

+

Using bind with function objects

+

Using bind with member function pointers

+

Using nested binds for function composition

+ +

Examples

+

Using bind with standard algorithms

+

Using bind with Boost.Function

+ +

Limitations

+ +

Frequently Asked Questions

+

Why doesn't this compile?

+

Why does this compile? It should not.

+

What is the difference between bind(f, ...) and bind<R>(f, ...)?

+

Does bind work with Windows API functions?

+

Does bind work with COM methods?

+

Does bind work with Mac toolbox functions?

+

Why doesn't bind automatically recognize nonstandard functions?

+ +

Troubleshooting

+ +

Interface

+

Synopsis

+

Common requirements

+

Common definitions

+

bind

+ +

Implementation

+

Files

+

Dependencies

+

Number of Arguments

+

"__stdcall" and "pascal" Support

+

MSVC specific problems and workarounds

+

visit_each support

+ +

Acknowledgements

+ +

Purpose

boost::bind is a generalization of the standard functions @@ -45,7 +76,7 @@ in particular, it does not need the result_type, first_argument_type and second_argument_type standard typedefs.

-

Using bind with functions and function pointers

+

Using bind with functions and function pointers

Given these definitions: @@ -139,7 +170,7 @@ int i = 5; bind(f, ref(i), _1); -

Using bind with function objects

+

Using bind with function objects

bind is not limited to functions; it accepts arbitrary function objects. @@ -177,7 +208,7 @@ bind(std::less<int>, _1, 9)(x); // x < 9 [Note: the ability to omit the return type is not available on all compilers.]

-

Using bind with member function pointers

+

Using bind with member function pointers

Pointers to member functions are not function objects, because they do not @@ -244,7 +275,7 @@ the function object retains a reference to its instance of X and will remain valid even when p goes out of scope or is reset().

-

Using nested binds for function composition

+

Using nested binds for function composition

Some of the arguments passed to bind may be nested bind expressions @@ -289,7 +320,9 @@ int main() } -

Example: using bind with standard algorithms

+

Examples

+ +

Using bind with standard algorithms

 class image;
@@ -322,7 +355,7 @@ void render(image & target)
 }
-

Example: using bind with Boost.Function

+

Using bind with Boost.Function

 class button
@@ -350,7 +383,7 @@ void connect()
 }
-

Limitations

+

Limitations

The function objects generated by bind take their arguments by @@ -394,9 +427,95 @@ partially ordered. corresponding issue has not been resolved yet.]

-

Interface

+

Frequently Asked Questions

-

Synopsis

+

Why doesn't this compile?

+ +

+See the dedicated Troubleshooting section. +

+ +

Why does this compile? It should not.

+ +

+Probably because you used the general bind<R>(f, ...) syntax, thereby +instructing bind to not "inspect" f to detect arity +and return type errors. +

+ +

What is the difference between bind(f, ...) and bind<R>(f, ...)?

+ +

+The first form instructs bind to inspect the type of f in order +to determine its arity (number of arguments) and return type. Arity errors +will be detected at "bind time". This syntax, of course, places some +requirements on f. It must be a function, function pointer, member +function pointer, or a function object that defines a nested type named +result_type; in short, it must be something that bind can +recognize. +

+ +

+The second form instructs bind to not attempt to recognize the +type of f. It is generally used with function objects that do not, or +cannot, expose result_type, but it can also be used with nonstandard +functions. For example, the current implementation does not automatically +recognize variable-argument functions like printf, so you will have to +use bind<int>(printf, ...). +

+ +

+Another important factor to consider is that compilers without partial template +specialization or function template partial ordering support cannot handle the +first form when f is a function object, and in most cases will not handle +the second form when f is a function (pointer) or a member function pointer. +

+ +

Does bind work with Windows API functions?

+ +

+Yes, if you #define BOOST_BIND_ENABLE_STDCALL. +An alternative is to treat the function as a +generic function object and use the +bind<R>(f, ...) syntax. +

+ +

Does bind work with COM methods?

+ +

+Yes, if you #define BOOST_MEM_FN_ENABLE_STDCALL. +

+ +

Does bind work with Mac toolbox functions?

+ +

+Yes, if you #define BOOST_BIND_ENABLE_PASCAL. +An alternative is to treat the function as a +generic function object and use the +bind<R>(f, ...) syntax. +

+ +

Why doesn't bind automatically recognize nonstandard functions?

+ +

+Non-portable extensions, in general, should default to off to prevent vendor +lock-in. Had the appropriate macros been defined +automatically, you could +have accidentally taken advantage of them without realizing that your code is, +perhaps, no longer portable. In addition, some compilers have the option to +make __stdcall their default calling convention, in which case no +separate support would be necessary. +

+ +

Troubleshooting

+ +

+This section is still under development. +

+ +

Interface

+ +

Synopsis

 namespace boost
@@ -452,7 +571,7 @@ namespace
 }
-

Common requirements

+

Common requirements

All implementation-defined-N types returned by bind are @@ -465,7 +584,7 @@ All implementation-defined-placeholder-N types are CopyConstructible. Their copy constructors do not throw exceptions.

-

Common definitions

+

Common definitions

The function µ(x, v1, v2, ..., vm), where m is a nonnegative integer, is defined as: @@ -481,7 +600,7 @@ when x is (a copy of) a function object returned by bind; -

bind

+

bind

template<class R, class F> implementation-defined-1 bind(F f)

@@ -592,7 +711,29 @@ implicitly converted to R. Effects: equivalent to bind<R>(boost::mem_fn(f), a1, a2);

-

Implementation

+

Implementation

+ +

Files

+ + +

Dependencies

+ + +

Number of Arguments

This implementation supports function objects with up to nine arguments. @@ -600,7 +741,7 @@ This is an implementation detail, not an inherent limitation of the design.

-

__stdcall support

+

"__stdcall" and "pascal" Support

Some platforms allow several types of (member) functions that differ by their @@ -611,7 +752,8 @@ stack - if any.)

For example, Windows API functions and COM interface member functions use a -calling convention known as __stdcall. +calling convention known as __stdcall. Mac toolbox functions use a +pascal calling convention.

@@ -624,6 +766,11 @@ To use bind with __stdcall member functions, #define macro BOOST_MEM_FN_ENABLE_STDCALL before including <boost/bind.hpp>.

+

+To use bind with pascal functions, #define the macro +BOOST_BIND_ENABLE_PASCAL before including <boost/bind.hpp>. +

+

[Note: this is a non-portable extension. It is not part of the interface.]

@@ -632,7 +779,7 @@ macro BOOST_MEM_FN_ENABLE_STDCALL before including <boost/bind.hpp& [Note: Some compilers provide only minimal support for the __stdcall keyword.]

-

MSVC specific problems and workarounds

+

MSVC specific problems and workarounds

Microsoft Visual C++ (up to version 7.0) does not fully support the @@ -673,33 +820,18 @@ interface, and is not guaranteed to work on other compilers, or persist between library versions. In short, don't use it unless you absolutely have to.]

-

Visitor support

- -

-[Note: this is an experimental feature. It may evolve over time -when other libraries start to exploit it; or it may be removed altogether if -no other library needs it. It is not part of the interface.] -

+

visit_each support

-For better integration with other libraries, the function objects returned by -bind define a member function -

- -
-template<class Visitor> void accept(Visitor & v);
-
- -

-that applies v, as a function object, to its internal state. Using -accept is implementation-specific and not intended for end users. +Function objects returned by bind support the experimental and +undocumented, as of yet, visit_each enumeration interface.

See bind_visitor.cpp for an example.

-

Acknowledgements

+

Acknowledgements

Earlier efforts that have influenced the library design: diff --git a/mem_fn.html b/mem_fn.html index 7c977dc..5d0f58a 100644 --- a/mem_fn.html +++ b/mem_fn.html @@ -12,7 +12,7 @@
- c++boost.gif (8819 bytes) + c++boost.gif (8819 bytes)

mem_fn.hpp

@@ -31,7 +31,7 @@ std::mem_fun[_ref] adaptors?

Should I replace every occurence of std::mem_fun[_ref] with mem_fn in my existing code?

-

Will mem_fn work with COM methods?

+

Does mem_fn work with COM methods?

Why isn't BOOST_MEM_FN_ENABLE_STDCALL defined automatically?

Interface

Synopsis

@@ -42,7 +42,7 @@ with mem_fn in my existing code?

Files

Dependencies

Number of Arguments

-

__stdcall Support

+

"__stdcall" Support

Acknowledgements

Purpose

@@ -196,7 +196,7 @@ that need adaptable function objects in order to function might not like mem_fn.

-

Will mem_fn work with COM methods?

+

Does mem_fn work with COM methods?

Yes, if you #define BOOST_MEM_FN_ENABLE_STDCALL. @@ -352,7 +352,7 @@ is of type T [const], (get_pointer(t)->*pmf)(a1, a2)libs/bind/mem_fn_void_test.cpp (test for void returns) -

Dependencies

+

Dependencies

@@ -365,7 +365,7 @@ This is not an inherent limitation of the design, but an implementation detail.

-

__stdcall Support

+

"__stdcall" Support

Some platforms allow several types of member functions that differ by their