[library Boost.TR1    [quickbook 1.4]    [copyright 2005 John Maddock]    [purpose An implementation of the C++ Technical Report on Standard Library Extensions]    [license        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])]    [authors [Maddock, John]]    [category misc]    [last-revision $Date: 2008-10-09 13:33:50 -0400 (Thu, 09 Oct 2008) $]][section:intro Introduction]The TR1 library provides an implementation of the C++ Technical Report on Standard Library Extensions.This library does not itself implement the TR1 components, rather it's a thin wrapper that will include your standard library's TR1 implementation (if it has one), otherwise it will include the BoostLibrary equivalents, and import them into namespace `std::tr1`.[endsect][section:usage Usage]There are two things you need to decide before using the Boost.TR1 library: whether to use your standard library's native TR1 implementation (if it has one),and which include style to use.[section:native Whether to use Your Native TR1 Library]If your standard library implements the TR1, and you want to makeuse of it, rather than use the Boost equivalents, then you will need totake some explicit action to enable it: this may be a pre-processordefine, a special compiler switch, or a different include path.You will need to consult your compilers documentation to find out which of theseactions you need to take.Provided Boost is [link boost_tr1.config correctly configured], everything shouldnow "just work", and code written to use Boost.TR1 will includeyour standard library's native headers rather than the Boost ones.[endsect][section:include_style Header Include Style]There are two ways you can include the Boost.TR1 headers, for example if you are interested in shared_ptr then you can either use:   #include <boost/tr1/memory.hpp>   or:   #include <memory>   The first option is the preferred method for other Boost librariesto use.  The second option is standard-conforming, but requires that youadd `boost-install-path/boost/tr1/tr1` to your compiler's include search path.  Note that you must not copy the headers in boost/tr1/tr1 into a directorycalled "include", doing so will cause them to cease working.[blurb [*Important Note #1]\n\nThe include path order is very important if you want this library to work correctly.  If you get compiler errors then suspect the include paths.  Thecorrect order is:\n\n1) boost-root/boost/tr1/tr1\n2) boost-root\n3) Any other standard library replacements (STLport for example).\n4) Your regular standard library.][blurb [*Important Note #2: GNU C++ Users]Normally this library should "just work" with the GNU C++ compiler.However, if Boost is installed in `/usr/include` then you may get an errormessage of the form:``In file included from /usr/include/boost/tr1/tuple.hpp:5,                 from boost-failure.cxx:1:/usr/include/boost/tr1/detail/config.hpp:60:26: error: no include path in which to search for utility``In this case try defining the macro `BOOST_TR1_DISABLE_INCLUDE_NEXT` when building,and if that doesn't work, define the macro `BOOST_TR1_GCC_INCLUDE_PATH` to the name of the directory containing gcc's include files: this is likely to be something like "g++-v4" but unfortunately varies from distribution to distribution.][blurb [*Important Note #3: Borland C++ Users]Borland's compiler has a particularly broken form of `#include`, thatwill actually look for a file named `array.h` if you `#include <array>`.In order to make this library work with Borland's compiler you will need toset up the include paths as follows:1) boost-root/boost/tr1/tr1/bcc32\n2) boost-root/boost/tr1/tr1\n3) boost-root\n4) Any other standard library replacements (STLport for example).\n5) Your regular standard library.\n][blurb [*Important Note #4: Sun C++ Users]Sun's compiler has a particularly interesting form of `#include`, thatwill actually look for a file named `array.SUNWCCh` if you `#include <array>`.In order to make this library work with Sun's compiler you will need toset up the include paths as follows:1) boost-root/boost/tr1/tr1/sun\n2) boost-root/boost/tr1/tr1\n3) boost-root\n4) Any other standard library replacements (STLport for example).\n5) Your regular standard library.\n][endsect][section:writing_code Writing Code]Regardless of how the includes are setup, user code written to work with Boost.TR1 is exactly the same as code written to use a native tr1 implementation.  That is, references to classes and functionsneed to explicitly use the `std::tr1` namespace or a `using std::tr1`statement.  For example,    std::tr1::tuple<int, std::string> t = std::tr1::make_tuple(10, "hello");or  using std::tr1;  tuple<int, std::string> t = make_tuple(10, "hello");[endsect][endsect][section:config Configuration]Configuring Boost.TR1 is no different to configuring any other part ofBoost; in the majority of cases you shouldn't actually need to do anything at all.However, because Boost.TR1 will inject Boost components into namespace std::tr1it is more than usually sensitive to an incorrect configuration.The intention is that [@../../libs/config/index.html Boost.Config] will automatically define the configurationmacros used by this library, so that if your standard library is set up tosupport TR1 (note that few are at present) then this will be detected and Boost.TR1will use your standard library versions of these components rather than the Boost ones.If you would prefer to use the Boost versions of the TR1 conponents rather thanyour standard library, then either: include the Boost headers directly   #include <boost/regex.hpp>      boost::regex e("myregex"); //etc   Or else don't enable TR1 in your standard library: since TR1 is not part ofthe current standard, there should be some option to disable it in yourcompiler or standard library.The configuration macros used by each TR1 component are documented in eachlibrary section (and all together in the [@../../libs/config/index.html Boost.Config] documentation), but defining BOOST_HAS_TR1 will turn on native TR1 supportfor everything (if your standard library has it), which can act as a convenient shortcut.[blurb [*Note for gcc users]\n\nBoost.TR1 does not currently enable gcc's native TR1 implementationas this is currently in an early stage of development.  However, you maychoose to do so by defining BOOST_HAS_GCC_TR1.][endsect][section:subject_list TR1 By Subject][section:ref Reference Wrappers.]      #include <boost/tr1/functional.hpp>or   #include <functional>   The Ref library is a small library that is useful for passingreferences to function templates (algorithms) that would usuallytake copies of their arguments. It defines the class template`reference_wrapper<T>`,and the two functions`ref` and `cref` that returninstances of `reference_wrapper<T>`.[@../../doc/html/ref.html Refer to Boost.Bind for more information.]   namespace std {   namespace tr1 {   template <class T> class reference_wrapper;   template <class T> reference_wrapper<T> ref(T&);   template <class T> reference_wrapper<const T> cref(const T&);   template <class T> reference_wrapper<T> ref(reference_wrapper<T>);   template <class T> reference_wrapper<const T> cref(reference_wrapper<T>);   } // namespace tr1   } // namespace std[*Configuration:] [@../../libs/config/index.html Boost.Config] should (automatically) definethe macro BOOST_HAS_TR1_REFERENCE_WRAPPER if yourstandard library implements this part of TR1.[*Standard Conformity:]The Boost version of this this component does not currently supportfunction call invocation (2.1.2.4), or derivation from std::unary_function or std::binary_function (2.1.2 paragraphs 3 and 4).The Boost version is not implicitly convertible to T& as the TR requires.[endsect][section:ptrs Smart Pointers.]   #include <boost/tr1/memory.hpp>or   #include <memory>The `shared_ptr` class template stores a pointer to a dynamically allocated object, typically with a C++ new-expression. The object pointed to is guaranteed to be deleted when the last `shared_ptr` pointing to it is destroyed or reset. For more information refer to the [@../../libs/smart_ptr/shared_ptr.htm shared_ptr]and [@../../libs/smart_ptr/weak_ptr.htm weak_ptr] documentation.      namespace std {   namespace tr1 {   class bad_weak_ptr;   // [2.2.3] Class template shared_ptr   template<class T> class shared_ptr;   // [2.2.3.6] shared_ptr comparisons   template<class T, class U> bool operator==(shared_ptr<T> const& a, shared_ptr<U> const& b);   template<class T, class U> bool operator!=(shared_ptr<T> const& a, shared_ptr<U> const& b);   template<class T, class U> bool operator<(shared_ptr<T> const& a, shared_ptr<U> const& b);   // [2.2.3.8] shared_ptr specialized algorithms   template<class T> void swap(shared_ptr<T>& a, shared_ptr<T>& b);   // [2.2.3.9] shared_ptr casts   template<class T, class U> shared_ptr<T> static_pointer_cast(shared_ptr<U> const& r);   template<class T, class U> shared_ptr<T> dynamic_pointer_cast(shared_ptr<U> const& r);   template<class T, class U> shared_ptr<T> const_pointer_cast(shared_ptr<U> const& r);   // [2.2.3.7] shared_ptr I/O   template<class E, class T, class Y>   basic_ostream<E, T>& operator<< (basic_ostream<E, T>& os, shared_ptr<Y> const& p);   // [2.2.3.10] shared_ptr get_deleter   template<class D, class T> D * get_deleter(shared_ptr<T> const& p);   // [2.2.4] Class template weak_ptr   template<class T> class weak_ptr;   // [2.2.4.6] weak_ptr comparison   template<class T, class U> bool operator<(weak_ptr<T> const& a, weak_ptr<U> const& b);   // [2.2.4.7] weak_ptr specialized algorithms   template<class T> void swap(weak_ptr<T>& a, weak_ptr<T>& b);   // [2.2.5] Class enable_shared_from_this   template<class T> class enable_shared_from_this;   } // namespace tr1   } // namespace std[*Configuration:] [@../../libs/config/index.html Boost.Config] should (automatically) definethe macro BOOST_HAS_TR1_SHARED_PTR if yourstandard library implements this part of TR1.[*Standard Conformity:] There are no known deviations from the standard when using the Boost version of this component.[endsect][section:result_of Class template result_of.]   #include <boost/tr1/functional.hpp>   or   #include <functional>The class template`result_of` helps determine the type of acall expression. Given an lvalue `f` oftype `F` and lvalues `t1`,`t2, ..., tN` oftypes `T1, T2, ..., TN`, respectively, the type`result_of<F(T1, T2, ..., TN)>::type` defines the result typeof the expression `f(t1, t2, ...,tN)`. The implementation permitsthe type `F` to be a function pointer,function reference, member function pointer, or classtype.  For more information [@../../libs/utility/utility.htm#result_of refer to the Boost.Utility documentation.]   namespace std {   namespace tr1 {   template <class T>   struct result_of   {      typedef unspecified type;   };   } // namespace tr1   } // namespace std[*Configuration:] [@../../libs/config/index.html Boost.Config] should (automatically) define the macro BOOST_HAS_TR1_RESULT_OF if yourstandard library implements this part of TR1.   [*Standard Conformity:] No known problems.[endsect][section:mem_fn Function template mem_fn.]   #include <boost/tr1/functional.hpp>   or   #include <functional>`std::tr1::mem_fn` is a generalization of the standard functions `std::mem_fun`and `std::mem_fun_ref`. It supports member function pointers with more than one argument, and the returned function object can take a pointer, a reference, or a smart pointer to an object instance as its first argument. `mem_fn`also supports pointers to data members by treating them as functions taking no arguments and returning a (const) reference to the member.For more information refer to the [@../../libs/bind/mem_fn.htmlBoost.Mem_fn documentation].   namespace std {   namespace tr1 {   template <class R, class T> unspecified mem_fn(R T::* pm);   } // namespace tr1   } // namespace std[*Configuration:][@../../libs/config/index.html Boost.Config] should (automatically) define the macro BOOST_HAS_TR1_MEM_FN if yourstandard library implements this part of TR1.[*Standard Conformity:]The Boost implementation does not produce functors that inherit from`std::unary_function` or `std::binary_function`, nor does it functioncorrectly with pointers to volatile member functions (these shouldbe extremely rare in practice however).[endsect]