Header
-<boost/call_traits.hpp>
-
-All of the contents of <boost/call_traits.hpp> are -defined inside namespace boost.
- -The template class call_traits<T> encapsulates the -"best" method to pass a parameter of some type T to or -from a function, and consists of a collection of typedefs defined -as in the table below. The purpose of call_traits is to ensure -that problems like "references to references" -never occur, and that parameters are passed in the most efficient -manner possible (see examples). In each -case if your existing practice is to use the type defined on the -left, then replace it with the call_traits defined type on the -right.
- -Note that for compilers that do not support either partial -specialization or member templates, no benefit will occur from -using call_traits: the call_traits defined types will always be -the same as the existing practice in this case. In addition if -only member templates and not partial template specialisation is -support by the compiler (for example Visual C++ 6) then call_traits -can not be used with array types (although it can be used to -solve the reference to reference problem).
- -Existing practice - |
- call_traits equivalent - |
- Description - |
- Notes - |
-
T |
-
|
- Defines a type that - represents the "value" of type T. Use this for - functions that return by value, or possibly for stored - values of type T. | -2 - |
-
T& |
-
|
- Defines a type that - represents a reference to type T. Use for functions that - would normally return a T&. | -1 - |
-
const T& |
-
|
- Defines a type that - represents a constant reference to type T. Use for - functions that would normally return a const T&. | -1 - |
-
const T& |
-
|
- Defines a type that - represents the "best" way to pass a parameter - of type T to a function. | -1,3 - |
-
Notes:
- --
-
- If T is already reference type, then call_traits is - defined such that references to - references do not occur (requires partial - specialization). -
- If T is an array type, then call_traits defines
value_type- as a "constant pointer to type" rather than an - "array of type" (requires partial - specialization). Note that if you are using value_type as - a stored value then this will result in storing a "constant - pointer to an array" rather than the array itself. - This may or may not be a good thing depending upon what - you actually need (in other words take care!).
- - If T is a small built in type or a pointer, then
param_type- is defined asT const, instead ofT - const&. This can improve the ability of the - compiler to optimize loops in the body of the function if - they depend upon the passed parameter, the semantics of - the passed parameter is otherwise unchanged (requires - partial specialization).
-
- -
Copy constructibility
- -The following table defines which call_traits types can always -be copy-constructed from which other types, those entries marked -with a '?' are true only if and only if T is copy constructible:
- -| - | To: - |
- ||||
| From: | -T - |
- value_type - |
- reference - |
- const_reference - |
- param_type - |
-
| T | -? - |
- ? - |
- Y - |
- Y - |
- Y - |
-
| value_type | -? - |
- ? - |
- N - |
- N - |
- Y - |
-
| reference | -? - |
- ? - |
- Y - |
- Y - |
- Y - |
-
| const_reference | -? - |
- N - |
- N - |
- Y - |
- Y - |
-
| param_type | -? - |
- ? - |
- N - |
- N - |
- Y - |
-
- -
If T is an assignable type the following assignments are -possible:
- -| - | To: - |
- ||||
| From: | -T - |
- value_type - |
- reference - |
- const_reference - |
- param_type - |
-
| T | -Y - |
- Y - |
- - - |
- - - |
- - - |
-
| value_type | -Y - |
- Y - |
- - - |
- - - |
- - - |
-
| reference | -Y - |
- Y - |
- - - |
- - - |
- - - |
-
| const_reference | -Y - |
- Y - |
- - - |
- - - |
- - - |
-
| param_type | -Y - |
- Y - |
- - - |
- - - |
- - - |
-
- -
Examples
- -The following table shows the effect that call_traits has on -various types, the table assumes that the compiler supports -partial specialization: if it doesn't then all types behave in -the same way as the entry for "myclass", and call_traits -can not be used with reference or array types.
- -| - | Call_traits type: - |
- ||||
Original type T - |
- value_type - |
- reference - |
- const_reference - |
- param_type - |
- Applies to: - |
-
myclass - |
- myclass - |
- myclass& - |
- const - myclass& - |
- myclass - const& - |
- All user - defined types. - |
-
int - |
- int - |
- int& - |
- const int& - |
- int const - |
- All small - built-in types. - |
-
int* - |
- int* - |
- int*& - |
- int*const& - |
- int* const - |
- All - pointer types. - |
-
int& - |
- int& - |
- int& - |
- const int& - |
- int& - |
- All - reference types. - |
-
const int& - |
- const int& - |
- const int& - |
- const int& - |
- const int& - |
- All - constant-references. - |
-
int[3] - |
- const int* - |
- int(&)[3] - |
- const int(&)[3] - |
- const int* - const - |
- All array - types. - |
-
const int[3] - |
- const int* - |
- const int(&)[3] - |
- const int(&)[3] - |
- const int* - const - |
- All - constant-array types. - |
-
- -
Example 1:
- -The following class is a trivial class that stores some type T -by value (see the call_traits_test.cpp -file), the aim is to illustrate how each of the available call_traits -typedefs may be used:
- -template <class T>
-struct contained
-{
- // define our typedefs first, arrays are stored by value
- // so value_type is not the same as result_type:
- typedef typename boost::call_traits<T>::param_type param_type;
- typedef typename boost::call_traits<T>::reference reference;
- typedef typename boost::call_traits<T>::const_reference const_reference;
- typedef T value_type;
- typedef typename boost::call_traits<T>::value_type result_type;
-
- // stored value:
- value_type v_;
-
- // constructors:
- contained() {}
- contained(param_type p) : v_(p){}
- // return byval:
- result_type value() { return v_; }
- // return by_ref:
- reference get() { return v_; }
- const_reference const_get()const { return v_; }
- // pass value:
- void call(param_type p){}
-
-};
-
-Example 2 (the reference to reference -problem):
- -Consider the definition of std::binder1st:
- -template <class Operation>
-class binder1st :
- public unary_function<Operation::second_argument_type, Operation::result_type>
-{
-protected:
- Operation op;
- Operation::first_argument_type value;
-public:
- binder1st(const Operation& x, const Operation::first_argument_type& y);
- Operation::result_type operator()(const Operation::second_argument_type& x) const;
-};
-
-Now consider what happens in the relatively common case that
-the functor takes its second argument as a reference, that
-implies that Operation::second_argument_type is a
-reference type, operator() will now end up taking a
-reference to a reference as an argument, and that is not
-currently legal. The solution here is to modify operator()
-to use call_traits:
Operation::result_type operator()(call_traits<Operation::second_argument_type>::param_type x) const;- -
Now in the case that Operation::second_argument_type
-is a reference type, the argument is passed as a reference, and
-the no "reference to reference" occurs.
Example 3 (the make_pair problem):
- -If we pass the name of an array as one (or both) arguments to std::make_pair,
-then template argument deduction deduces the passed parameter as
-"const reference to array of T", this also applies to
-string literals (which are really array literals). Consequently
-instead of returning a pair of pointers, it tries to return a
-pair of arrays, and since an array type is not copy-constructible
-the code fails to compile. One solution is to explicitly cast the
-arguments to make_pair to pointers, but call_traits provides a
-better (i.e. automatic) solution (and one that works safely even
-in generic code where the cast might do the wrong thing):
template <class T1, class T2>
-std::pair<
- typename boost::call_traits<T1>::value_type,
- typename boost::call_traits<T2>::value_type>
- make_pair(const T1& t1, const T2& t2)
-{
- return std::pair<
- typename boost::call_traits<T1>::value_type,
- typename boost::call_traits<T2>::value_type>(t1, t2);
-}
-
-Here, the deduced argument types will be automatically -degraded to pointers if the deduced types are arrays, similar -situations occur in the standard binders and adapters: in -principle in any function that "wraps" a temporary -whose type is deduced. Note that the function arguments to make_pair -are not expressed in terms of call_traits: doing so would prevent -template argument deduction from functioning.
- -Example 4 (optimising fill):
- -The call_traits template will "optimize" the passing -of a small built-in type as a function parameter, this mainly has -an effect when the parameter is used within a loop body. In the -following example (see algo_opt_examples.cpp), -a version of std::fill is optimized in two ways: if the type -passed is a single byte built-in type then std::memset is used to -effect the fill, otherwise a conventional C++ implemention is -used, but with the passed parameter "optimized" using -call_traits:
- -namespace detail{
-
-template <bool opt>
-struct filler
-{
- template <typename I, typename T>
- static void do_fill(I first, I last, typename boost::call_traits<T>::param_type val);
- {
- while(first != last)
- {
- *first = val;
- ++first;
- }
- }
-};
-
-template <>
-struct filler<true>
-{
- template <typename I, typename T>
- static void do_fill(I first, I last, T val)
- {
- memset(first, val, last-first);
- }
-};
-
-}
-
-template <class I, class T>
-inline void fill(I first, I last, const T& val)
-{
- enum{ can_opt = boost::is_pointer<I>::value
- && boost::is_arithmetic<T>::value
- && (sizeof(T) == 1) };
- typedef detail::filler<can_opt> filler_t;
- filler_t::template do_fill<I,T>(first, last, val);
-}
-
-Footnote: the reason that this is "optimal" for -small built-in types is that with the value passed as "T -const" instead of "const T&" the compiler is -able to tell both that the value is constant and that it is free -of aliases. With this information the compiler is able to cache -the passed value in a register, unroll the loop, or use -explicitly parallel instructions: if any of these are supported. -Exactly how much mileage you will get from this depends upon your -compiler - we could really use some accurate benchmarking -software as part of boost for cases like this.
- -Note that the function arguments to fill are not expressed in -terms of call_traits: doing so would prevent template argument -deduction from functioning. Instead fill acts as a "thin -wrapper" that is there to perform template argument -deduction, the compiler will optimise away the call to fill all -together, replacing it with the call to filler<>::do_fill, -which does use call_traits.
- -Rationale
- -The following notes are intended to briefly describe the -rational behind choices made in call_traits.
- -All user-defined types follow "existing practice" -and need no comment.
- -Small built-in types (what the standard calls fundamental -types [3.9.1]) differ from existing practice only in the param_type -typedef. In this case passing "T const" is compatible -with existing practice, but may improve performance in some cases -(see Example 4), in any case this should never -be any worse than existing practice.
- -Pointers follow the same rational as small built-in types.
- -For reference types the rational follows Example -2 - references to references are not allowed, so the call_traits -members must be defined such that these problems do not occur. -There is a proposal to modify the language such that "a -reference to a reference is a reference" (issue #106, -submitted by Bjarne Stroustrup), call_traits<T>::value_type -and call_traits<T>::param_type both provide the same effect -as that proposal, without the need for a language change (in -other words it's a workaround).
- -For array types, a function that takes an array as an argument -will degrade the array type to a pointer type: this means that -the type of the actual parameter is different from its declared -type, something that can cause endless problems in template code -that relies on the declared type of a parameter. For example:
- -template <class T>
-struct A
-{
- void foo(T t);
-};
-
-In this case if we instantiate A<int[2]> -then the declared type of the parameter passed to member function -foo is int[2], but it's actual type is const int*, if we try to -use the type T within the function body, then there is a strong -likelyhood that our code will not compile:
- -template <class T>
-void A<T>::foo(T t)
-{
- T dup(t); // doesn't compile for case that T is an array.
-}
-
-By using call_traits the degradation from array to pointer is -explicit, and the type of the parameter is the same as it's -declared type:
- -template <class T>
-struct A
-{
- void foo(call_traits<T>::value_type t);
-};
-
-template <class T>
-void A<T>::foo(call_traits<T>::value_type t)
-{
- call_traits<T>::value_type dup(t); // OK even if T is an array type.
-}
-
-For value_type (return by value), again only a pointer may be -returned, not a copy of the whole array, and again call_traits -makes the degradation explicit. The value_type member is useful -whenever an array must be explicitly degraded to a pointer - Example 3 provides the test case (Footnote: the -array specialisation for call_traits is the least well understood -of all the call_traits specialisations, if the given semantics -cause specific problems for you, or don't solve a particular -array-related problem, then I would be interested to hear about -it. Most people though will probably never need to use this -specialisation).
- -- -
Revised 01 September 2000
- -© Copyright boost.org 2000. 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.
- -Based on contributions by Steve Cleary, Beman Dawes, Howard -Hinnant and John Maddock.
- -Maintained by John -Maddock, the latest version of this file can be found at www.boost.org, and the boost -discussion list at www.egroups.com/list/boost.
- -.
- -- -
- - diff --git a/call_traits_test.cpp b/call_traits_test.cpp deleted file mode 100644 index 0c7155e..0000000 --- a/call_traits_test.cpp +++ /dev/null @@ -1,366 +0,0 @@ - // boost::compressed_pair test program - - // (C) Copyright John Maddock 2000. Permission to copy, use, modify, sell and - // distribute this software is granted provided this copyright notice appears - // in all copies. This software is provided "as is" without express or implied - // warranty, and with no claim as to its suitability for any purpose. - -// standalone test program for
Header
-boost/cast.hpp
-Cast Functions
-The header boost/cast.hpp
-provides polymorphic_cast, polymorphic_downcast,
-and numeric_cast template functions designed
-to complement the C++ Standard's built-in casts.
The program cast_test.cpp can be used to -verify these function templates work as expected.
-polymorphic_cast was suggested by Bjarne Stroustrup in "The C++
-Programming Language".
-polymorphic_downcast was contributed by Dave
-Abrahams.
-numeric_cast was contributed by Kevlin
-Henney.
Namespace synopsis
-
- namespace boost {
- namespace cast {
- // all synopsis below included here
- }
- using ::boost::cast::polymorphic_cast;
- using ::boost::cast::polymorphic_downcast;
- using ::boost::cast::bad_numeric_cast;
- using ::boost::cast::numeric_cast;
-}
-
-Polymorphic casts
-Pointers to polymorphic objects (objects of classes which define at least one -virtual function) are sometimes downcast or crosscast. Downcasting means -casting from a base class to a derived class. Crosscasting means casting -across an inheritance hierarchy diagram, such as from one base to the other in a -Y diagram hierarchy.
-Such casts can be done with old-style casts, but this approach is never to be -recommended. Old-style casts are sorely lacking in type safety, suffer -poor readability, and are difficult to locate with search tools.
-The C++ built-in static_cast can be used for efficiently downcasting -pointers to polymorphic objects, but provides no error detection for the case -where the pointer being cast actually points to the wrong derived class. The polymorphic_downcast -template retains the efficiency of static_cast for non-debug -compilations, but for debug compilations adds safety via an assert() that a dynamic_cast -succeeds.
-The C++ built-in dynamic_cast can be used for downcasts and crosscasts -of pointers to polymorphic objects, but error notification in the form of a -returned value of 0 is inconvenient to test, or worse yet, easy to forget to -test. The polymorphic_cast template performs a dynamic_cast, -and throws an exception if the dynamic_cast returns 0.
-A polymorphic_downcast is preferred when debug-mode tests will cover -100% of the object types possibly cast and when non-debug-mode efficiency is an -issue. If these two conditions are not present, polymorphic_cast is -preferred. It must also be used for crosscasts. It does an assert( -dynamic_cast<Derived>(x) == x ) where x is the base pointer, ensuring that -not only is a non-zero pointer returned, but also that it correct in the -presence of multiple inheritance. . Warning:: Because polymorphic_downcast -uses assert(), it violates the One Definition Rule if NDEBUG is inconsistently -defined across translation units.
-The C++ built-in dynamic_cast must be used to cast references rather -than pointers. It is also the only cast that can be used to check whether -a given interface is supported; in that case a return of 0 isn't an error -condition.
-polymorphic_cast and polymorphic_downcast synopsis
---template <class Derived, class Base> -inline Derived polymorphic_cast(Base* x); -// Throws: std::bad_cast if ( dynamic_cast<Derived>(x) == 0 ) -// Returns: dynamic_cast<Derived>(x) - -template <class Derived, class Base> -inline Derived polymorphic_downcast(Base* x); -// Effects: assert( dynamic_cast<Derived>(x) == x ); -// Returns: static_cast<Derived>(x)-
polymorphic_downcast example
-
- #include <boost/cast.hpp>
-...
-class Fruit { public: virtual ~Fruit(){}; ... };
-class Banana : public Fruit { ... };
-...
-void f( Fruit * fruit ) {
-// ... logic which leads us to believe it is a Banana
- Banana * banana = boost::polymorphic_downcast<Banana*>(fruit);
- ...
-
-numeric_cast
-A static_cast, implicit_cast or implicit conversion will not -detect failure to preserve range for numeric casts. The numeric_cast -template function are similar to static_cast and certain (dubious) -implicit conversions in this respect, except that they detect loss of numeric -range. An exception is thrown when a runtime value preservation check fails.
-The requirements on the argument and result types are:
----
-- Both argument and result types are CopyConstructible [20.1.3].
-- Both argument and result types are Numeric, defined by
-std::numeric_limits<>::is_specialized- being true.- The argument can be converted to the result type using static_cast.
-
numeric_cast synopsis
-
- class bad_numeric_cast : public std::bad_cast {...};
-
-template<typename Target, typename Source>
- inline Target numeric_cast(Source arg);
- // Throws: bad_numeric_cast unless, in converting arg from Source to Target,
- // there is no loss of negative range, and no underflow, and no
- // overflow, as determined by std::numeric_limits
- // Returns: static_cast<Target>(arg)
-
-numeric_cast example
-
- #include <boost/cast.hpp>
-using namespace boost::cast;
-
-void ariane(double vx)
-{
- ...
- unsigned short dx = numeric_cast<unsigned short>(vx);
- ...
-}
-
-numeric_cast rationale
-The form of the throws condition is specified so that != is not a required -operation.
--
Revised 28 June, 2000
-© Copyright boost.org 1999. 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.
- - - - diff --git a/cast_test.cpp b/cast_test.cpp deleted file mode 100644 index 1602f16..0000000 --- a/cast_test.cpp +++ /dev/null @@ -1,153 +0,0 @@ -// boost utility cast test program -----------------------------------------// - -// (C) Copyright boost.org 1999. Permission to copy, use, modify, sell -// and distribute this software is granted provided this copyright -// notice appears in all copies. This software is provided "as is" without -// express or implied warranty, and with no claim as to its suitability for -// any purpose. - -// See http://www.boost.org for most recent version including documentation. - -// Revision History -// 28 Jun 00 implicit_cast removed (Beman Dawes) -// 30 Aug 99 value_cast replaced by numeric_cast -// 3 Aug 99 Initial Version - -#includeHeader
-<boost/compressed_pair.hpp>
-
-All of the contents of <boost/compressed_pair.hpp> are -defined inside namespace boost.
- -The class compressed pair is very similar to std::pair, but if -either of the template arguments are empty classes, then the -"empty member optimisation" is applied to compress the -size of the pair.
- -template <class T1, class T2>
-class compressed_pair
-{
-public:
- typedef T1 first_type;
- typedef T2 second_type;
- typedef typename call_traits<first_type>::param_type first_param_type;
- typedef typename call_traits<second_type>::param_type second_param_type;
- typedef typename call_traits<first_type>::reference first_reference;
- typedef typename call_traits<second_type>::reference second_reference;
- typedef typename call_traits<first_type>::const_reference first_const_reference;
- typedef typename call_traits<second_type>::const_reference second_const_reference;
-
- compressed_pair() : base() {}
- compressed_pair(first_param_type x, second_param_type y);
- explicit compressed_pair(first_param_type x);
- explicit compressed_pair(second_param_type y);
-
- first_reference first();
- first_const_reference first() const;
-
- second_reference second();
- second_const_reference second() const;
-
- void swap(compressed_pair& y);
-};
-
-The two members of the pair can be accessed using the member -functions first() and second(). Note that not all member -functions can be instantiated for all template parameter types. -In particular compressed_pair can be instantiated for reference -and array types, however in these cases the range of constructors -that can be used are limited. If types T1 and T2 are the same -type, then there is only one version of the single-argument -constructor, and this constructor initialises both values in the -pair to the passed value.
- -Note that compressed_pair can not be instantiated if either of -the template arguments is an enumerator type, unless there is -compiler support for boost::is_enum, or if boost::is_enum is -specialised for the enumerator type.
- -Finally, compressed_pair requires compiler support for partial -specialisation of class templates - without that support -compressed_pair behaves just like std::pair.
- -- -
Revised 08 March 2000
- -© Copyright boost.org 2000. 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.
- -Based on contributions by Steve Cleary, Beman Dawes, Howard -Hinnant and John Maddock.
- -Maintained by John -Maddock, the latest version of this file can be found at www.boost.org, and the boost -discussion list at www.egroups.com/list/boost.
- -- - diff --git a/compressed_pair_test.cpp b/compressed_pair_test.cpp deleted file mode 100644 index 940896b..0000000 --- a/compressed_pair_test.cpp +++ /dev/null @@ -1,156 +0,0 @@ - // boost::compressed_pair test program - - // (C) Copyright John Maddock 2000. Permission to copy, use, modify, sell and - // distribute this software is granted provided this copyright notice appears - // in all copies. This software is provided "as is" without express or implied - // warranty, and with no claim as to its suitability for any purpose. - -// standalone test program for