From d2b04d968cc15bc8e4309cc0ba847bb1eeb21de5 Mon Sep 17 00:00:00 2001 From: Andreas Huber Date: Sat, 2 Dec 2006 14:17:26 +0000 Subject: [PATCH] Merged L & C issue fixes from trunk to branch. [SVN r36246] --- binders.html | 181 +++++++++------- function_test.cpp | 101 +++++++-- function_traits.html | 321 +++++++++++++++------------ include/boost/functional.hpp | 16 +- index.html | 405 +++++++++++++++++++++-------------- mem_fun.html | 260 ++++++++++++---------- negators.html | 208 ++++++++++-------- ptr_fun.html | 195 +++++++++-------- 8 files changed, 990 insertions(+), 697 deletions(-) diff --git a/binders.html b/binders.html index b37bfa5..4220ed2 100644 --- a/binders.html +++ b/binders.html @@ -1,132 +1,161 @@ - + + - -Boost Function Object Adapter Library + + + + Boost Function Object Adapter Library + + + -
+
- - - - - - - - -
boost.png (6897 bytes)Home Libraries People FAQ More
+ Home -

Binders

+ Libraries -

The header functional.hpp provides -enhanced versions of both the binder function object adapters from the -C++ Standard Library (§20.3.6):

+ People - + FAQ -

As well as the corresponding helper functions

+ More + + - +

Binders

-

The key benefit of these adapters over those in the Standard -Library is they avoid the problem of references to -references. +

The header functional.hpp + provides enhanced versions of both the binder function object adapters from + the C++ Standard Library (§20.3.6):

-

Usage

+ -
+  
As well as the corresponding helper functions

+
+  
    
+    
  • bind1st
    • 
+
+    
  • bind2nd
    • 
+  

+
+  
The key benefit of these adapters over those in the Standard Library is
+  they avoid the problem of references to
+  references.

+
+  
Usage

+
+  
Usage is identical to the standard binders. For example,

+
+  

+    
 class Foo {
 public:
-  void bar(std::ostream &);
+  void bar(std::ostream &);
   // ...
 };
 // ...
 std::vector<Foo> c;
 // ...
 std::for_each(c.begin(), c.end(), 
-              boost::bind2nd(boost::mem_fun_ref(&Foo::bar), std::cout));
-

+              boost::bind2nd(boost::mem_fun_ref(&Foo::bar), std::cout));
+
+
-

References to References

+

References to References

-

Consider the usage example above

+

Consider the usage example above

-
+  

+    
 class Foo {
 public:
-  void bar(std::ostream &);
+  void bar(std::ostream &);
   // ...
 };
 // ...
 std::for_each(c.begin(), c.end(), 
-              boost::bind2nd(boost::mem_fun_ref(&Foo::bar), std::cout));
-

+              boost::bind2nd(boost::mem_fun_ref(&Foo::bar), std::cout));
+
+
-

If this had been written using std::bind2nd -and std::mem_fun_ref, it would be unlikely to -compile.

+

If this had been written using std::bind2nd and + std::mem_fun_ref, it would be unlikely to compile.

-

The problem arises because bar takes a -reference argument. The Standard defines -std::mem_fun_ref such that it creates a function -object whose second_argument_type will be -std::ostream&.

+

The problem arises because bar takes a reference argument. The + Standard defines std::mem_fun_ref such that it creates a function + object whose second_argument_type will be + std::ostream&.

-

The call to bind2nd creates a -binder2nd which the Standard defines as follows: +

The call to bind2nd creates a binder2nd which the + Standard defines as follows:

-
+  

+    
 template <class Operation>
 class binder2nd
     : public unary_function<typename Operation::first_argument_type,
                             typename Operation::result_type> {
 ...
 public:
-  binder2nd(const Operation& x,
-            const typename Operation::second_argument_type& y);
+  binder2nd(const Operation& x,
+            const typename Operation::second_argument_type& y);
   ...
-

+
+
-

Since our operation's second_argument_type is -std::ostream&, the type of y in the -constructor would be std::ostream&&. Since you -cannot have a reference to a reference, at this point we should get a -compilation error because references to references are illegal in C++ -(but see -C++ Standard core language active issues list).

+

Since our operation's second_argument_type is + std::ostream&, the type of y in the constructor would + be std::ostream&&. Since you cannot have a reference to a + reference, at this point we should get a compilation error because + references to references are illegal in C++ (but see C++ + Standard core language active issues list).

-

The binders in this library avoid this problem by using the Boost -call_traits templates.

+

The binders in this library avoid this problem by using the Boost + call_traits + templates.

-

Our constructor is declared +

Our constructor is declared

-
-binder2nd(const Operation& x,
+  

+    
+binder2nd(const Operation& x,
           typename call_traits<
              typename binary_traits<Operation>::second_argument_type
           >::param_type y)
-

+
+
-

As a result, y has a type of std::ostream&, -and our example compiles.

+

As a result, y has a type of std::ostream&, and + our example compiles.

+
-
-

Copyright © 2000 Cadenza New Zealand Ltd. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

+

Valid HTML 4.01 Transitional

-

Revised 28 June 2000

+

Revised + 02 + December, 2006

+

Copyright © 2000 Cadenza New Zealand Ltd.

+ +

Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)

diff --git a/function_test.cpp b/function_test.cpp index 8c2307b..ed7eb8d 100644 --- a/function_test.cpp +++ b/function_test.cpp @@ -1,25 +1,102 @@ // ------------------------------------------------------------------------------ +// Copyright (c) 2000 Cadenza New Zealand Ltd +// Distributed under the Boost Software License, Version 1.0. (See accompany- +// ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +// ------------------------------------------------------------------------------ // Tests for the Boost functional.hpp header file // // Note that functional.hpp relies on partial specialisation to be // effective. If your compiler lacks this feature, very few of the // tests would compile, and so have been excluded from the test. // ------------------------------------------------------------------------------ -// Copyright (c) 2000 -// Cadenza New Zealand Ltd -// -// Permission to use, copy, modify, distribute and sell this software -// and its documentation for any purpose is hereby granted without -// fee, provided that the above copyright notice appears in all copies -// and that both the copyright notice and this permission notice -// appear in supporting documentation. Cadenza New Zealand Ltd makes -// no representations about the suitability of this software for any -// purpose. It is provided "as is" without express or implied -// warranty. -// ------------------------------------------------------------------------------ // $Id$ // ------------------------------------------------------------------------------ // $Log$ +// Revision 1.2.24.1 2006/12/02 14:17:26 andreas_huber69 +// Merged L & C issue fixes from trunk to branch. +// +// Revision 1.3 2006/12/02 13:57:32 andreas_huber69 +// Fixed license & copyright issues. +// +// From Mark Rodgers Fri Dec 1 12:59:14 2006 +// X-Apparently-To: ahd6974-boostorg -at- yahoo.com via 68.142.206.160; Fri, 01 Dec 2006 12:59:41 -0800 +// X-Originating-IP: [195.112.4.54] +// Return-Path: +// Authentication-Results: mta550.mail.mud.yahoo.com from=cadenza.co.nz; domainkeys=neutral (no sig) +// Received: from 195.112.4.54 (EHLO smtp.nildram.co.uk) (195.112.4.54) by mta550.mail.mud.yahoo.com with SMTP; Fri, 01 Dec 2006 12:59:40 -0800 +// Received: from snagglepuss.cadenza.co.nz (81-6-246-87.dyn.gotadsl.co.uk [81.6.246.87]) by smtp.nildram.co.uk (Postfix) with ESMTP id D32EA2B6D8C for ; Fri, 1 Dec 2006 20:59:35 +0000 (GMT) +// Received: from penfold.cadenza.co.nz ([192.168.55.56]) by snagglepuss.cadenza.co.nz with esmtp (Exim 4.63) (envelope-from ) id J9M4Y9-0009TO-9K for ahd6974-boostorg -at- yahoo.com; Fri, 01 Dec 2006 20:58:57 +0000 +// Message-ID: <457097A2.1090305@cadenza.co.nz> +// Date: Fri, 01 Dec 2006 20:59:14 +0000 +// From: "Mark Rodgers" +// User-Agent: Thunderbird 1.5.0.8 (Macintosh/20061025) +// MIME-Version: 1.0 +// To: ahd6974-boostorg -at- yahoo.com [Edit - Delete] +// Subject: Re: [boost] Reminder: Need your permission to correct license & copyright issues +// References: <379990.36007.qm@web33507.mail.mud.yahoo.com> +// In-Reply-To: <379990.36007.qm@web33507.mail.mud.yahoo.com> +// Content-Type: text/plain; charset=ISO-8859-1; format=flowed +// Content-Transfer-Encoding: 7bit +// Content-Length: 812 +// Gidday Andreas +// +// Sure that's fine. I'm happy for you to do 1, 2 and 3. +// +// Regards +// Mark +// +// Andreas Huber wrote: +// > Hello Mark +// > +// > Quite a while ago it was decided that every file that goes into the +// > 1.34 release of the Boost distribution (www.boost.org) needs uniform +// > license and copyright information. For more information please see: +// > +// > +// > +// > You are receiving this email because several files you contributed +// > lack such information or have an old license: +// > +// > boost/functional/functional.hpp +// > boost/libs/functional/binders.html +// > boost/libs/functional/function_test.cpp +// > boost/libs/functional/function_traits.html +// > boost/libs/functional/index.html +// > boost/libs/functional/mem_fun.html +// > boost/libs/functional/negators.html +// > boost/libs/functional/ptr_fun.html +// > boost/people/mark_rodgers.htm +// > +// > I therefore kindly ask you to grant the permission to do the +// > following: +// > +// > 1. For the files above that already have a license text (all except +// > mark_rodgers.htm), replace the license text with: +// > +// > "Distributed under the Boost Software License, Version 1.0. (See +// > accompanying file LICENSE_1_0.txt or copy at +// > http://www.boost.org/LICENSE_1_0.txt)" +// > +// > 2. For the file that does not yet have a license and copyright +// > (mark_rodgers.htm) add the same license text as under 1. and add the +// > following copyright: +// > +// > "(c) Copyright Mark Rodgers 2000" +// > +// > 3. (Optional) I would also want to convert all HTML files to conform +// > the HTML 4.01 Standard by running them through HTML Tidy, see +// > +// > +// > It would be great if you could grant me permission to do 1 & 2 and +// > optionally also 3. +// > +// > Thank you! +// > +// > Regards, +// > +// > Andreas Huber +// > +// // Revision 1.2 2001/09/22 11:52:24 johnmaddock // Intel C++ fixes: no void return types supported. // diff --git a/function_traits.html b/function_traits.html index 13cfe06..c2a841b 100644 --- a/function_traits.html +++ b/function_traits.html @@ -1,137 +1,166 @@ - + + - -Boost Function Object Adapter Library + + + + Boost Function Object Adapter Library + + + -
+
- - - - - - - - -
boost.png (6897 bytes)Home Libraries People FAQ More
+ Home -

Function Object Traits

+ Libraries -

The header functional.hpp provides two -traits class templates for functions and function objects:

+ People - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeContentsDescription
template <typename T>
struct unary_traits - 		function_type - The type of the function or function object itself (i.e., T). -
param_type - The type that should be used to pass the function or function object as a parameter. -
result_type - The type returned by the function or function object. -
argument_type - The type of the argument to the function or function object. -
template <typename T>
struct binary_traits - 		function_type - The type of the function or function object itself (i.e., T). -
param_type - The type that should be used to pass the function or function object as a parameter. -
result_type - The type returned by the function or function object. -
first_argument_type - The type of the first argument to the function or function object. -
second_argument_type - The type of the second argument to the function or function object. -
+ FAQ -

Usage

+ More + + -

unary_traits should be instantiated with -either a function taking a single parameter, or an adaptable unary -function object (i.e., a class derived from -std::unary_function or one which provides the -same typedefs). (See §20.3.1 in the C++ Standard.) +

Function Object Traits

-

binary_traits should be instantiated with -either a function taking two parameters, or an adaptable binary -function object (i.e., a class derived from -std::binary_function or one which provides the -same typedefs). (See §20.3.1 in the C++ Standard.) +

The header functional.hpp + provides two traits class templates for functions and function objects:

-

The most common usage of these templates is in function object -adapters, thus allowing them to adapt plain functions as well as -function objects. You can do this by wherever you would normally -write, for example, + + + -
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeContentsDescription
+ template <typename T>
+ struct unary_traits		function_typeThe type of the function or function object itself + (i.e., T).
param_typeThe type that should be used to pass the function or + function object as a parameter.
result_typeThe type returned by the function or function + object.
argument_typeThe type of the argument to the function or function + object.
+ template <typename T>
+ struct binary_traits		function_typeThe type of the function or function object itself + (i.e., T).
param_typeThe type that should be used to pass the function or + function object as a parameter.
result_typeThe type returned by the function or function + object.
first_argument_typeThe type of the first argument to the function or + function object.
second_argument_typeThe type of the second argument to the function or + function object.
+ +

Usage

+ +

unary_traits should be instantiated with either a function + taking a single parameter, or an adaptable unary function object (i.e., a + class derived from std::unary_function or one which provides the + same typedefs). (See §20.3.1 in the C++ Standard.)

+ +

binary_traits should be instantiated with either a function + taking two parameters, or an adaptable binary function object (i.e., a + class derived from std::binary_function or one which provides the + same typedefs). (See §20.3.1 in the C++ Standard.)

+ +

The most common usage of these templates is in function object adapters, + thus allowing them to adapt plain functions as well as function objects. + You can do this by wherever you would normally write, for example,

+ +
+ 
 typename Operation::argument_type
-
+ + -

simply writing +

simply writing

-
+  

+    
 typename boost::unary_traits<Operation>::argument_type
-

+
+
-

instead. +

instead.

-

Additional Types Defined

+

Additional Types Defined

-

In addition to the standard result and argument typedefs, these -traits templates define two additional types. +

In addition to the standard result and argument typedefs, these traits + templates define two additional types.

-

function_type

+

function_type

-

This is the type of the function or function object, and can be -used in declarations such as

+

This is the type of the function or function object, and can be used in + declarations such as

-
+  

+    
 template <class Predicate>
 class unary_negate : // ...
 {
@@ -139,19 +168,21 @@ class unary_negate : // ...
   private:
     typename unary_traits<Predicate>::function_type pred;
 };
-

+
+
-

If this typedef were not provided, it would not be possible to -declare pred in a way that would allow -unary_negate to be instantiated with a function -type (see the C++ Standard §14.3.1 ¶3). +

If this typedef were not provided, it would not be possible to declare + pred in a way that would allow unary_negate to be + instantiated with a function type (see the C++ Standard §14.3.1 + ¶3).

-

param_type

+

param_type

-

This is a type suitable for passing the function or function object -as a parameter to another function. For example, +

This is a type suitable for passing the function or function object as a + parameter to another function. For example,

-
+  

+    
 template <class Predicate>
 class unary_negate : // ...
 {
@@ -162,35 +193,41 @@ class unary_negate : // ...
     {}
     // ...
 };
-

+
+
-

Function objects are passed by reference to const; function -pointers are passed by value.

+

Function objects are passed by reference to const; function pointers are + passed by value.

+

Limitations

-

Limitations

+

This library uses these traits within all function object adapters, + theoretically rendering ptr_fun obsolete. However, third party + adapters probably won't take advantage of this mechanism, and so + ptr_fun may still be required. Accordingly, this library also + provides improved versions of the standard function + pointer adapters.

-

This library uses these traits within all function object adapters, -theoretically rendering ptr_fun obsolete. -However, third party adapters probably won't take advantage of this -mechanism, and so ptr_fun may still be required. -Accordingly, this library also provides improved versions of the standard function pointer -adapters.

+

These traits templates will also not work with compilers that fail to + support partial specialisation of templates. With these compilers, the + traits templates can only be instantiated with adaptable function objects, + thus requiring ptr_fun to be used, even with the function object + adapters in this library.

+
-

These traits templates will also not work with compilers that fail -to support partial specialisation of templates. With these compilers, -the traits templates can only be instantiated with adaptable function -objects, thus requiring ptr_fun to be used, even -with the function object adapters in this library. +

Valid HTML 4.01 Transitional

-
-

Copyright © 2000 Cadenza New Zealand Ltd. Permission to copy, -use, modify, sell and distribute this document is granted provided -this copyright notice appears in all copies. This document is provided -"as is" without express or implied warranty, and with no claim as to -its suitability for any purpose.

+

Revised + 02 + December, 2006

-

Revised 28 June 2000

+

Copyright © 2000 Cadenza New Zealand Ltd.

+ +

Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)

diff --git a/include/boost/functional.hpp b/include/boost/functional.hpp index 39ccc30..b618485 100644 --- a/include/boost/functional.hpp +++ b/include/boost/functional.hpp @@ -1,19 +1,11 @@ // ------------------------------------------------------------------------------ +// Copyright (c) 2000 Cadenza New Zealand Ltd +// Distributed under the Boost Software License, Version 1.0. (See accompany- +// ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +// ------------------------------------------------------------------------------ // Boost functional.hpp header file // See http://www.boost.org/libs/functional for documentation. // ------------------------------------------------------------------------------ -// Copyright (c) 2000 -// Cadenza New Zealand Ltd -// -// Permission to use, copy, modify, distribute and sell this software -// and its documentation for any purpose is hereby granted without -// fee, provided that the above copyright notice appears in all copies -// and that both the copyright notice and this permission notice -// appear in supporting documentation. Cadenza New Zealand Ltd makes -// no representations about the suitability of this software for any -// purpose. It is provided "as is" without express or implied -// warranty. -// ------------------------------------------------------------------------------ // $Id$ // ------------------------------------------------------------------------------ diff --git a/index.html b/index.html index 65766a8..2dd91a0 100644 --- a/index.html +++ b/index.html @@ -1,97 +1,140 @@ - + + - - - -Boost Function Object Adapter Library + + + + + + Boost Function Object Adapter Library + + + -
+
- - - - - - - - -
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
-

Improved Function Object Adapters

-

The header functional.hpp -provides enhancements to the function object adapters specified in the C++ -Standard Library (sections 20.3.5, through to 20.3.8). The enhancements are -principally possible due to two changes:

-
    -
  1. We use the Boost call_traits - templates to avoid the problem of references - to references, and to improve the efficiency of parameter + Home + + Libraries + + People + + FAQ + + More + + + +

    Improved Function Object Adapters

    + +

    The header functional.hpp + provides enhancements to the function object adapters specified in the C++ + Standard Library (sections 20.3.5, through to 20.3.8). The enhancements are + principally possible due to two changes:

    + +
      +
    1. We use the Boost call_traits templates to avoid the + problem of references to references, + and to improve the efficiency of parameter passing.
      2. -
    2. We use two function object traits class - templates to avoid the need for ptr_fun - with the adapters in this library.
      3. -
    -

    Contents

    -

    The header contains the following function and class templates:

    - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + +
    Function object traits - unary_traits
    - binary_traits    		Used to determine the types of function objects' and - functions' arguments. Eliminate the necessity for ptr_fun.
    Negatorsunary_negate
    - binary_negate
    - not1
    - not2    		Based on section 20.3.5 of the standard.
    Bindersbinder1st
    - binder2nd
    - bind1st
    - bind2nd    		Based on section 20.3.6 of the standard.
    Adapters for pointers to functionspointer_to_unary_function
    - pointer_to_binary_function
    - ptr_fun    		Based on section 20.3.7 of the standard. Not required for - use with this library since the binders and negators can adapt functions, - but may be needed with third party adapters.
    Adapters for pointers to member + +
  2. We use two function object traits + class templates to avoid the need for ptr_fun with the adapters in this library.
    3. + + +

    Contents

    + +

    The header contains the following function and class templates:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - -
    Function object + traitsunary_traits
    + binary_traits    		Used to determine the types of function objects' and + functions' arguments. Eliminate the necessity for + ptr_fun.
    Negatorsunary_negate
    + binary_negate
    + not1
    + not2    		Based on section 20.3.5 of the standard.
    Bindersbinder1st
    + binder2nd
    + bind1st
    + bind2nd    		Based on section 20.3.6 of the standard.
    Adapters for pointers to functionsmem_fun_t
    - mem_fun1_t
    - const_mem_fun_t
    - const_mem_fun1_t
    - mem_fun_ref_t
    - mem_fun1_ref_t
    - const_mem_fun_ref_t
    - const_mem_fun1_ref_t
    - mem_fun
    - mem_fun_ref    		Based on section 20.3.8 of the standard.
    -

    Usage

    -

    Using these adapters should be pretty much the same as using the standard -function object adapters; the only differences are that you need to write boost:: -instead of std::, and that you will get fewer headaches.

    -

    For example, suppose you had a Person class that contained a set_name -function: -

    - 
    +
+
    		pointer_to_unary_function
    + pointer_to_binary_function
    + ptr_fun    		Based on section 20.3.7 of the standard. Not required + for use with this library since the binders and negators can adapt + functions, but may be needed with third party adapters.
    Adapters for pointers to member + functionsmem_fun_t
    + mem_fun1_t
    + const_mem_fun_t
    + const_mem_fun1_t
    + mem_fun_ref_t
    + mem_fun1_ref_t
    + const_mem_fun_ref_t
    + const_mem_fun1_ref_t
    + mem_fun
    + mem_fun_ref    		Based on section 20.3.8 of the standard.
    + +

    Usage

    + +

    Using these adapters should be pretty much the same as using the + standard function object adapters; the only differences are that you need + to write boost:: instead of std::, and that you will get + fewer headaches.

    + +

    For example, suppose you had a Person class that contained a + set_name function:

    + +
    + 
     class Person
 {
   public:
@@ -99,86 +142,122 @@ class Person
   // ...
 };
    -
    -

    You could rename a bunch of people in a collection, c, by writing

    -
    - 
    +
    + +

    You could rename a bunch of people in a collection, c, by + writing

    + +
    + 
     std::for_each(c.begin(), c.end(), 
-              boost::bind2nd(boost::mem_fun_ref(&Person::set_name), "Fred"));
+              boost::bind2nd(boost::mem_fun_ref(&Person::set_name), "Fred"));
    -
    -

    If the standard adapters had been used instead then this code would normally -fail to compile, because set_name takes a reference -argument. Refer to the comments in the binder -documentation to explain why this is so.

    -

    Compiler Compatibility

    -

    The header and test program have been -compiled with the following compilers:

    - - - - - - - - - - - - - - - - - - - - - -
    CompilerComments
    Borland C++Builder 4 Update 2No known issues.
    Borland C++ 5.5No known issues.
    g++ 2.95.2No known issues.
    Microsoft Visual C++ Service Pack 3Compiler lacks partial specialisation, so this library - offers little more than is provided by the standard adapters: -
      -
    • The call_traits mechanism is unable to prevent - references to references, and so the adapters in this library will be - usable in fewer situations.
      • -
    • The function_traits mechanism is unable to - determine the argument and result types of functions, therefore ptr_fun - continues to be required to adapt functions. -
    -
    -

    Future Directions

    -

    This library's primary focus is to solve the problem of references to -references while maintaining as much compatibility as possible with the standard -library. This allows you to use the techniques you read about in books and -magazines with many of today's compilers.

    -

    In the longer term, even better solutions are likely:

    -
      -
    1. Several Boost members are working on expression template libraries. These - will allow a more natural syntax for combining and adapting functions. As - this is a new technology, it may be some time before it has matured and is - widely supported by major compilers but shows great promise. In the - meantime, the functional.hpp library fills the gap.
      2. -
    2. The Standard Committee has recognised the problem of references to - references occurring during template instantiation and has moved to fix the - standard (see the C++ + + +

      If the standard adapters had been used instead then this code would + normally fail to compile, because set_name takes a reference + argument. Refer to the comments in the binder + documentation to explain why this is so.

      + +

      Compiler Compatibility

      + +

      The header and test program have been + compiled with the following compilers:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CompilerComments
      Borland C++Builder 4 Update 2No known issues.
      Borland C++ 5.5No known issues.
      g++ 2.95.2No known issues.
      Microsoft Visual C++ Service Pack 3 + Compiler lacks partial specialisation, so this library offers little + more than is provided by the standard adapters: + +
        +
      • The call_traits mechanism is unable to prevent + references to references, and so the adapters in this library will + be usable in fewer situations.
        • + +
      • The function_traits mechanism is unable to determine + the argument and result types of functions, therefore + ptr_fun continues to be required to adapt functions.
        • +
      +
      + +

      Future Directions

      + +

      This library's primary focus is to solve the problem of references to + references while maintaining as much compatibility as possible with the + standard library. This allows you to use the techniques you read about in + books and magazines with many of today's compilers.

      + +

      In the longer term, even better solutions are likely:

      + +
        +
      1. Several Boost members are working on expression template libraries. + These will allow a more natural syntax for combining and adapting + functions. As this is a new technology, it may be some time before it has + matured and is widely supported by major compilers but shows great + promise. In the meantime, the functional.hpp library fills the gap.
        2. + +
      2. The Standard Committee has recognised the problem of references to + references occurring during template instantiation and has moved to fix + the standard (see the C++ standard core language active issues list).
        3. -
      -

      Author

      -

      Mark Rodgers

      -

      Acknowledgements

      -

      Thanks to John Maddock for -suggesting the mechanism that allowed the function objects traits to work -correctly. Jens Maurer provided -invaluable feedback during the formal -review process. -

      -

      Copyright © 2000 Cadenza New Zealand Ltd. Permission to copy, use, modify, -sell and distribute this document is granted provided this copyright notice -appears in all copies. This document is provided "as is" without -express or implied warranty, and with no claim as to its suitability for any -purpose.

      -

      Revised 28 June 2000

      +
    +

    Author

    + +

    Mark Rodgers

    + +

    Acknowledgements

    + +

    Thanks to John Maddock for + suggesting the mechanism that allowed the function objects traits to work + correctly. Jens Maurer provided + invaluable feedback during the formal review process.

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 02 + December, 2006

    + +

    Copyright © 2000 Cadenza New Zealand Ltd.

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)

    - diff --git a/mem_fun.html b/mem_fun.html index 84b70ec..3fcff5f 100644 --- a/mem_fun.html +++ b/mem_fun.html @@ -1,171 +1,201 @@ - + + - -Boost Function Object Adapter Library + + + + Boost Function Object Adapter Library + + + -
    +
    - - - - - - - - -
    boost.png (6897 bytes)Home Libraries People FAQ More
    + Home -

    Member Function Adapters

    + Libraries -

    The header functional.hpp includes -improved versions of the full range of member function adapters from -the the C++ Standard Library (§ 20.3.8):

    + People -
      -
    • mem_fun_t
      • -
    • mem_fun1_t
      • -
    • const_mem_fun_t
      • -
    • const_mem_fun1_t
      • -
    • mem_fun_ref_t
      • -
    • mem_fun1_ref_t
      • -
    • const_mem_fun_ref_t
      • -
    • const_mem_fun1_ref_t
      • -
    + FAQ -

    as well as the corresponding overloaded helper functions

    -

      -
    • mem_fun
      • -
    • mem_fun_ref
      • -
    + More + + -

    The following changes have been made to the adapters as specified -in the Standard:

    +

    Member Function Adapters

    -
      -
    • The first_argument_type typedef has been -corrected for the const_ family of member -function adapters (see below).
      • +

      The header functional.hpp + includes improved versions of the full range of member function adapters + from the the C++ Standard Library (§20.3.8):

      -
    • The argument passed to mem_fun1_t and its -variants is passed using the -call_traits::param_type for the member -function's argument type. -
    +
      +
    • mem_fun_t
      • -

      first_argument_type

      +
    • mem_fun1_t
      • -

      The standard specifies const_mem_fun1_t, for example, like this: +

    • const_mem_fun_t
      • -
      +    
    • const_mem_fun1_t
      • 
+
+    
    • mem_fun_ref_t
      • 
+
+    
    • mem_fun1_ref_t
      • 
+
+    
    • const_mem_fun_ref_t
      • 
+
+    
    • const_mem_fun1_ref_t
      • 
+
    + +

    as well as the corresponding overloaded helper functions

    + +
      +
    • mem_fun
      • + +
    • mem_fun_ref
      • +
    + +

    The following changes have been made to the adapters as specified in the + Standard:

    + +
      +
    • The first_argument_type typedef has been corrected for the + const_ family of member function adapters (see below).
      • + +
    • The argument passed to mem_fun1_t and its variants is passed + using the call_traits::param_type for the member function's + argument type.
      • +
    + +

    first_argument_type

    + +

    The standard specifies const_mem_fun1_t, for example, like + this:

    + +
    + 
     template <class S, class T, class A> class const_mem_fun1_t
   : public binary_function<T*, A, S> {
 public:
   explicit const_mem_fun1_t(S (T::*p)(A) const);
   S operator()(const T* p, A x) const;
 };
-
    + + -

    Note that the first argument to -binary_function is T* -despite the fact that the first argument to operator() is -actually of type const T*. +

    Note that the first argument to binary_function is T* + despite the fact that the first argument to operator() is actually + of type const T*.

    -

    Does this matter? Well, consider what happens when we write +

    Does this matter? Well, consider what happens when we write

    -
    +  
    
+    
     struct Foo { void bar(int) const; };
 const Foo *cp = new Foo;
-std::bind1st(std::mem_fun(&Foo::bar), cp);
-
    
+std::bind1st(std::mem_fun(&Foo::bar), cp);
+
    +
    -

    We have created a const_mem_fun1_t object -which will effectively contain the following +

    We have created a const_mem_fun1_t object which will + effectively contain the following

    -
    +  
    
+    
     typedef Foo* first_argument_type;
-
    
+
    +
    -

    The bind1st will then create a -binder1st object that will use this -typedef as the type of a member which will be -initialised with cp. In other words, we will -need to initialise a Foo* member with a -const Foo* pointer! Clearly this is not -possible, so to implement this your Standard Library vendor will have -had to cast away the constness of cp, probably -within the body of bind1st. +

    The bind1st will then create a binder1st object that + will use this typedef as the type of a member which will be + initialised with cp. In other words, we will need to initialise a + Foo* member with a const Foo* pointer! Clearly this + is not possible, so to implement this your Standard Library vendor will + have had to cast away the constness of cp, probably within the + body of bind1st.

    -

    This hack will not suffice with the improved binders in this library, so we have had to -provide corrected versions of the member function adapters as well. +

    This hack will not suffice with the improved binders in this library, so we have had to provide + corrected versions of the member function adapters as well.

    +

    Argument Types

    -

    Argument Types

    +

    The standard defines mem_fun1_t, for example, like this + (§20.3.8 ¶2):

    -

    The standard defines mem_fun1_t, for example, like this -(§20.3.8 ¶2): - -

    +  
    
+    
     template <class S, class T, class A> class mem_fun1_t
   : public binary_function<T*, A, S> {
 public:
   explicit mem_fun1_t(S (T::*p)(A));
   S operator()(T* p, A x) const;
 };
-
    
+
    +
    -

    Note that the second argument to operator() is -exactly the same type as the argument to the member function. If this -is a value type, the argument will be passed by value and copied twice. +

    Note that the second argument to operator() is exactly the same + type as the argument to the member function. If this is a value type, the + argument will be passed by value and copied twice.

    -

    However, if we were to try and eliminate this inefficiency by -instead declaring the argument as const A&, then -if A were a reference type, we would have a reference to a reference, -which is currently illegal (but see C++ -core language issue number 106) +

    However, if we were to try and eliminate this inefficiency by instead + declaring the argument as const A&, then if A were a + reference type, we would have a reference to a reference, which is + currently illegal (but see C++ core + language issue number 106)

    -

    So the way in which we want to declare the second argument for -operator() depends on whether or not the member -function's argument is a reference. If it is a reference, we want to -declare it simply as A; if it is a value we want -to declare it as const A&. +

    So the way in which we want to declare the second argument for + operator() depends on whether or not the member function's + argument is a reference. If it is a reference, we want to declare it simply + as A; if it is a value we want to declare it as + const A&.

    -

    The Boost call_traits class -template contains a param_type typedef, which -uses partial specialisation to make precisely this decision. By -declaring the operator() as +

    The Boost call_traits class + template contains a param_type typedef, which uses partial + specialisation to make precisely this decision. By declaring the + operator() as

    -
    +  
    
+    
     S operator()(T* p, typename call_traits<A>::param_type x) const
-
    
+
    +
    -

    we achieve the desired result - we improve efficiency without -generating references to references.

    +

    we achieve the desired result - we improve efficiency without generating + references to references.

    -

    Limitations

    +

    Limitations

    -

    The call traits template used to realise some improvements relies -on partial specialisation, so these improvements are only available on -compilers that support that feature. With other compilers, the -argument passed to the member function (in the -mem_fun1_t family) will always be passed by -reference, thus generating the possibility of references to references. +

    The call traits template used to realise some improvements relies on + partial specialisation, so these improvements are only available on + compilers that support that feature. With other compilers, the argument + passed to the member function (in the mem_fun1_t family) will + always be passed by reference, thus generating the possibility of + references to references.

    +
    -
    +

    Valid HTML 4.01 Transitional

    -

    Copyright © 2000 Cadenza New Zealand Ltd. Permission to copy, -use, modify, sell and distribute this document is granted provided -this copyright notice appears in all copies. This document is provided -"as is" without express or implied warranty, and with no claim as to -its suitability for any purpose.

    +

    Revised + 02 December, 2006

    -

    Revised 28 June 2000

    +

    Copyright © 2000 Cadenza New Zealand Ltd.

    +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)

    diff --git a/negators.html b/negators.html index 51dac6b..c17c64e 100644 --- a/negators.html +++ b/negators.html @@ -1,132 +1,158 @@ - + + - -Boost Function Object Adapter Library + + + + Boost Function Object Adapter Library + + + -
    +
    - - - - - - - - -
    boost.png (6897 bytes)Home Libraries People FAQ More
    + Home -

    Negators

    + Libraries -

    The header functional.hpp provides -enhanced versions of both the negator adapters from the C++ Standard -Library (§20.3.5):

    + People -
      -
    • unary_negate
      • -
    • binary_negate
      • -
    + FAQ -

    As well as the corresponding helper functions

    + More + + -
      -
    • not1
      • -
    • not2
      • -
    +

    Negators

    -

    However, the negators in this library improve on the standard -versions in two ways: +

    The header functional.hpp + provides enhanced versions of both the negator adapters from the C++ + Standard Library (§20.3.5):

    -
      -
    • They use function object traits -to avoid the need for ptr_fun when negating a -function rather than an adaptable function object. -
      • -
    • They use Boost call traits to determine -the best way to declare their arguments and pass them through -to the adapted function (see below). -
      • -
    +
      +
    • unary_negate
      • -

      Usage

      +
    • binary_negate
      • +
    -

    Usage is identical to the standard negators. For example,

    +

    As well as the corresponding helper functions

    -
    -bool bad(const Foo &foo) { ... }
+  
      
+    
    • not1
      • 
+
+    
    • not2
      • 
+  
    
+
+  
    However, the negators in this library improve on the standard versions
+  in two ways:
    
+
+  
      
+    
    • They use function object traits to
+    avoid the need for ptr_fun when negating a function rather than
+    an adaptable function object.
      • 
+
+    
    • They use Boost call traits to determine the best
+    way to declare their arguments and pass them through to the adapted
+    function (see below).
      • 
+  
    
+
+  
    Usage
    
+
+  
    Usage is identical to the standard negators. For example,
    
+
+  
    
+    
    +bool bad(const Foo &foo) { ... }
 ...
 std::vector<Foo> c;
 ...
 std::find_if(c.begin(), c.end(), boost::not1(bad));
-
    
+
    +
    -

    Argument Types

    +

    Argument Types

    -

    The C++ Standard (§20.3.5) defines unary negate -like this (binary negate is similar):

    +

    The C++ Standard (§20.3.5) defines unary negate like this (binary + negate is similar):

    -
    +  
    
+    
     template <class Predicate>
   class unary_negate
     : public unary_function<typename Predicate::argument_type,bool> {
 public:
-  explicit unary_negate(const Predicate& pred);
-  bool operator()(const typename Predicate::argument_type& x) const;
-};
    
+  explicit unary_negate(const Predicate& pred);
+  bool operator()(const typename Predicate::argument_type& x) const;
+};
+
    +
    -

    Note that if the Predicate's argument_type is -a reference, the type of operator()'s argument -would be a reference to a reference. Currently this is illegal in C++ -(but see the -C++ standard core language active issues list).

    +

    Note that if the Predicate's argument_type is a reference, the + type of operator()'s argument would be a reference to a reference. + Currently this is illegal in C++ (but see the C++ + standard core language active issues list).

    -

    However, if we instead defined operator() -to accept Predicate's argument_type unmodified, this would be -needlessly inefficient if it were a value type; the argument would be -copied twice - once when calling unary_negate's -operator(), and again when operator() -called the adapted function.

    +

    However, if we instead defined operator() to accept Predicate's + argument_type unmodified, this would be needlessly inefficient if it were a + value type; the argument would be copied twice - once when calling + unary_negate's operator(), and again when + operator() called the adapted function.

    -

    So how we want to declare the argument for -operator() depends on whether or not the -Predicate's argument_type is a reference. If it -is a reference, we want to declare it simply as -argument_type; if it is a value we want to -declare it as const argument_type&. +

    So how we want to declare the argument for operator() depends + on whether or not the Predicate's argument_type is a reference. If + it is a reference, we want to declare it simply as argument_type; + if it is a value we want to declare it as + const argument_type&.

    -

    The Boost call_traits class -template contains a param_type typedef, which -uses partial specialisation to make precisely this decision. If we were -to declare operator() as

    +

    The Boost call_traits class + template contains a param_type typedef, which uses partial + specialisation to make precisely this decision. If we were to declare + operator() as

    -
    +  
    
+    
     bool operator()(typename call_traits<typename Predicate::argument_type>::param_type x) const
-
    
+
    +
    -

    the desired result would be achieved - we would eliminate -references to references without loss of efficiency. In fact, the -actual declaration is slightly more complicated because of the use of -function object traits, but the effect remains the same.

    +

    the desired result would be achieved - we would eliminate references to + references without loss of efficiency. In fact, the actual declaration is + slightly more complicated because of the use of function object traits, but + the effect remains the same.

    -

    Limitations

    +

    Limitations

    -

    Both the function object traits and call traits used to realise -these improvements rely on partial specialisation, these improvements -are only available on compilers that support that feature. With other -compilers, the negators in this library behave very much like those -in the Standard - ptr_fun will be required to -adapt functions, and references to references will not be avoided. +

    Both the function object traits and call traits used to realise these + improvements rely on partial specialisation, these improvements are only + available on compilers that support that feature. With other compilers, the + negators in this library behave very much like those in the Standard - + ptr_fun will be required to adapt functions, and references to + references will not be avoided.

    +
    -
    -

    Copyright © 2000 Cadenza New Zealand Ltd. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

    +

    Valid HTML 4.01 Transitional

    -

    Revised 28 June 2000

    +

    Revised + 02 + December, 2006

    +

    Copyright © 2000 Cadenza New Zealand Ltd.

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)

    diff --git a/ptr_fun.html b/ptr_fun.html index c7a919d..d5b2eb0 100644 --- a/ptr_fun.html +++ b/ptr_fun.html @@ -1,135 +1,158 @@ - + + - -Boost Function Object Adapter Library + + + + Boost Function Object Adapter Library + + + -
    +
    - - - - - - - - -
    boost.png (6897 bytes)Home Libraries People FAQ More
    + Home -

    Function Pointer Adapters

    + Libraries -

    The header functional.hpp provides -enhanced versions of both the function pointer adapters from the C++ -Standard Library (§ 20.3.7):

    + People -
      -
    • pointer_to_unary_function
      • -
    • pointer_to_binary_function
      • -
    + FAQ -

    As well as the corresponding helper function template:

    + More + + -
      -
    • ptr_fun
      • -
    +

    Function Pointer Adapters

    -

    However, you should not need to use the adapters in conjunction -with the adapters in this library due to our use of function object traits. You will -however need to use them if your implementation fails to work properly -with our traits classes (due to lack if partial specialisation), or if -you wish to use a function object adapter from a third party. +

    The header functional.hpp + provides enhanced versions of both the function pointer adapters from the + C++ Standard Library (§20.3.7):

    -

    Usage

    +
      +
    • pointer_to_unary_function
      • -

      If you need to use these adapters, usage is identical to the -standard function pointer adapters. For example,

      +
    • pointer_to_binary_function
      • +
    -
    +  
    As well as the corresponding helper function template:
    
+
+  
      
+    
    • ptr_fun
      • 
+  
    
+
+  
    However, you should not need to use the adapters in conjunction with the
+  adapters in this library due to our use of function object traits. You will however need to
+  use them if your implementation fails to work properly with our traits
+  classes (due to lack if partial specialisation), or if you wish to use a
+  function object adapter from a third party.
    
+
+  
    Usage
    
+
+  
    If you need to use these adapters, usage is identical to the standard
+  function pointer adapters. For example,
    
+
+  
    
+    
     bool bad(std::string foo) { ... }
 ...
 std::vector<std::string> c;
 ...
 std::vector<std::string>::iterator it
      = std::find_if(c.begin(), c.end(), std::not1(boost::ptr_fun(bad)));
-
    
+
    +
    -

    Note however that this library contains enhanced negators that support function object traits, -so the line above could equally be written +

    Note however that this library contains enhanced negators that support function object traits, so the + line above could equally be written

    -
    +  
    
+    
     std::vector<std::string>::iterator it
      = std::find_if(c.begin(), c.end(), boost::not1(bad));
-
    
+
    +
    -

    Argument Types

    +

    Argument Types

    -

    The standard defines -pointer_to_unary_function like this -(§20.3.8 ¶2): +

    The standard defines pointer_to_unary_function like this + (§20.3.8 ¶2):

    -
    +  
    
+    
     template <class Arg, class Result>
 class pointer_to_unary_function : public unary_function<Arg, Result> {
 public:
   explicit pointer_to_unary_function(Result (* f)(Arg));
   Result operator()(Arg x) const;
 };
-
    
+
    +
    -

    Note that the argument to operator() is -exactly the same type as the argument to the wrapped function. If this -is a value type, the argument will be passed by value and copied twice. -pointer_to_binary_function has a similar problem. +

    Note that the argument to operator() is exactly the same type + as the argument to the wrapped function. If this is a value type, the + argument will be passed by value and copied twice. + pointer_to_binary_function has a similar problem.

    -

    However, if we were to try and eliminate this inefficiency by -instead declaring the argument as const Arg&, then -if Arg were a reference type, we would have a reference to a reference, -which is currently illegal (but see C++ -core language issue number 106) +

    However, if we were to try and eliminate this inefficiency by instead + declaring the argument as const Arg&, then if Arg were a + reference type, we would have a reference to a reference, which is + currently illegal (but see C++ core + language issue number 106)

    -

    So the way in which we want to declare the argument for -operator() depends on whether or not the -wrapped function's argument is a reference. If it -is a reference, we want to declare it simply as -Arg; if it is a value we want to -declare it as const Arg&. +

    So the way in which we want to declare the argument for + operator() depends on whether or not the wrapped function's + argument is a reference. If it is a reference, we want to declare it simply + as Arg; if it is a value we want to declare it as + const Arg&.

    -

    The Boost call_traits class -template contains a param_type typedef, which -uses partial specialisation to make precisely this decision. By -declaring the operator() as +

    The Boost call_traits class + template contains a param_type typedef, which uses partial + specialisation to make precisely this decision. By declaring the + operator() as

    -
    +  
    
+    
     Result operator()(typename call_traits<Arg>::param_type x) const
-
    
+
    +
    -

    we achieve the desired result - we improve efficiency without -generating references to references.

    +

    we achieve the desired result - we improve efficiency without generating + references to references.

    -

    Limitations

    +

    Limitations

    -

    The call traits template used to realise this improvement relies -on partial specialisation, so this improvement is only available on -compilers that support that feature. With other compilers, the -argument passed to the function will always be passed by -reference, thus generating the possibility of references to references. +

    The call traits template used to realise this improvement relies on + partial specialisation, so this improvement is only available on compilers + that support that feature. With other compilers, the argument passed to the + function will always be passed by reference, thus generating the + possibility of references to references.

    +
    -
    +

    Valid HTML 4.01 Transitional

    -

    Copyright © 2000 Cadenza New Zealand Ltd. Permission to copy, -use, modify, sell and distribute this document is granted provided -this copyright notice appears in all copies. This document is provided -"as is" without express or implied warranty, and with no claim as to -its suitability for any purpose.

    +

    Revised + 02 + December, 2006

    -

    Revised 28 June 2000

    +

    Copyright © 2000 Cadenza New Zealand Ltd.

    +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)