[library Boost.TR1
[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: 2007/05/09 17:20:56 $]
]
[section:intro Introduction]
This documentation is
[@http://boost-consulting.com/vault/index.php?action=downloadfile&filename=boost_tr1-1.34.pdf&directory=PDF%20Documentation&
also available in printer-friendly PDF format].
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 Boost
Library 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 make
use of it, rather than use the Boost equivalents, then you will need to
take some explicit action to enable it: this may be a pre-processor
define, a special compiler switch, or a different include path.
You will need to consult your compilers documentation to find out
which of these
actions you need to take.
Provided Boost is [link boost_tr1.config correctly configured],
everything should
now "just work", and code written to use Boost.TR1 will include
your 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
or:
#include
The first option is the preferred method for other Boost libraries
to use. The second option is standard-conforming, but requires that you
add `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 directory
called "include", doing so will cause them to cease working.
[blurb [*Important Note #1]\n\n
The include path order is very important if you want this library to work
correctly. If you get compiler errors then suspect the include paths. The
correct order is:\n\n
1) boost-root/boost/tr1/tr1\n
2) boost-root\n
3) Any other standard library replacements (STLport for example).\n
4) Your regular standard library.]
[blurb [*Important Note #2: Borland C++ Users]\n\n
Borland's compiler has a particularly broken form of `#include`, that
will actually look for a file named `array.h` if you `#include `.
In order to make this library work with Borland's compiler you will need to
set up the include paths as follows:\n\n
1) boost-root/boost/tr1/tr1/bcc32\n
2) boost-root/boost/tr1/tr1\n
3) boost-root\n
4) Any other standard library replacements (STLport for example).\n
5) Your regular standard library.]
[blurb [*Important Note #3: Sun C++ Users]\n\n
Sun's compiler has a particularly interesting form of `#include`, that
will actually look for a file named `array.SUNWCCh` if you `#include `.
In order to make this library work with Sun's compiler you will need to
set up the include paths as follows:\n\n
1) boost-root/boost/tr1/tr1/sun\n
2) boost-root/boost/tr1/tr1\n
3) boost-root\n
4) Any other standard library replacements (STLport for example).\n
5) Your regular standard library.]
[endsect]
[endsect]
[section:config Configuration]
Configuring Boost.TR1 is no different to configuring any other part of
Boost; 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::tr1
it is more than usually sensitive to an incorrect configuration.
The intention is that
[@../../libs/config/index.html Boost.Config]
will automaticaly define the configuration
macros used by this library, so that if your standard library is set up to
support TR1 (note that few are at present) then this will be detected and Boost.TR1
will 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 than
your standard library, then either: include the Boost headers directly
#include
boost::regex e("myregex"); //etc
Or else don't enable TR1 in your standard library: since TR1 is not part of
the current standard, there should be some option to disable it in your
compiler or standard library.
The configuration macros used by each TR1 component are documented in each
library section (and all together in the
[@../../libs/config/index.html Boost.Config]
documentation), but defining BOOST_HAS_TR1 will turn on native TR1 support
for everything (if your standard library has it), which can act as a
convenient shortcut.
[blurb [*Note for gcc users]\n\n
Boost.TR1 does not currently enable gcc's native TR1 implementation
as this is currently in an early stage of development. However, you may
choose to do so by defining BOOST_HAS_GCC_TR1.]
[endsect]
[section:subject_list TR1 By Subject]
[section:ref Reference Wrappers.]
#include
or
#include
The Ref library is a small library that is useful for passing
references to function templates (algorithms) that would usually
take copies of their arguments. It defines the class template
`reference_wrapper`,
and the two functions
`ref` and `cref` that return
instances of `reference_wrapper`.
[@../../doc/html/ref.html Refer to Boost.Bind for more information.]
namespace std {
namespace tr1 {
template class reference_wrapper;
template reference_wrapper ref(T&);
template reference_wrapper cref(const T&);
template reference_wrapper ref(reference_wrapper);
template reference_wrapper cref(reference_wrapper);
} // namespace tr1
} // namespace std
[*Configuration:]
[@../../libs/config/index.html Boost.Config] should (automatically) define
the macro BOOST_HAS_TR1_REFERENCE_WRAPPER if your
standard library implements this part of TR1.
[*Standard Conformity:]
The Boost version of this this component does not currently support
function 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
or
#include
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 shared_ptr;
// [2.2.3.6] shared_ptr comparisons
template bool operator==(shared_ptr const& a, shared_ptr const& b);
template bool operator!=(shared_ptr const& a, shared_ptr const& b);
template bool operator<(shared_ptr const& a, shared_ptr const& b);
// [2.2.3.8] shared_ptr specialized algorithms
template void swap(shared_ptr& a, shared_ptr& b);
// [2.2.3.9] shared_ptr casts
template shared_ptr static_pointer_cast(shared_ptr const& r);
template shared_ptr dynamic_pointer_cast(shared_ptr const& r);
template shared_ptr const_pointer_cast(shared_ptr const& r);
// [2.2.3.7] shared_ptr I/O
template
basic_ostream& operator<< (basic_ostream& os, shared_ptr const& p);
// [2.2.3.10] shared_ptr get_deleter
template D * get_deleter(shared_ptr const& p);
// [2.2.4] Class template weak_ptr
template class weak_ptr;
// [2.2.4.6] weak_ptr comparison
template bool operator<(weak_ptr const& a, weak_ptr const& b);
// [2.2.4.7] weak_ptr specialized algorithms
template void swap(weak_ptr& a, weak_ptr& b);
// [2.2.5] Class enable_shared_from_this
template class enable_shared_from_this;
} // namespace tr1
} // namespace std
[*Configuration:]
[@../../libs/config/index.html Boost.Config] should (automatically) define
the macro BOOST_HAS_TR1_SHARED_PTR if your
standard 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
or
#include
The class template
`result_of` helps determine the type of a
call expression. Given an lvalue `f` of
type `F` and lvalues `t1`,
`t2, ..., tN` of
types `T1, T2, ..., TN`, respectively, the type
`result_of::type` defines the result type
of the expression `f(t1, t2, ...,tN)`. The implementation permits
the type `F` to be a function pointer,
function reference, member function pointer, or class
type. For more information
[@../../libs/utility/utility.htm#result_of refer to the Boost.Utility documentation.]
namespace std {
namespace tr1 {
template
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 your
standard library implements this part of TR1.
[*Standard Conformity:] No known problems.
[endsect]
[section:mem_fn Function template mem_fn.]
#include
or
#include
`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.html
Boost.Mem_fn documentation].
namespace std {
namespace tr1 {
template 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 your
standard 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 function
correctly with pointers to volatile member functions (these should
be extremely rare in practice however).
[endsect]
[section:bind Function Object Binders.]
#include
or
#include
`std::tr1::bind` is a generalization of the standard functions `std::bind1st`
and `std::bind2nd`. It supports arbitrary function objects, functions,
function pointers, and member function pointers, and is able to bind any
argument to a specific value or route input arguments into arbitrary positions. `bind`
does not place any requirements on the function object; in particular, it does
not need the `result_type`, `first_argument_type` and `second_argument_type`
standard typedefs.
For more information refer to the [@../../libs/bind/bind.html
Boost.Bind documentation].
namespace std {
namespace tr1 {
// [3.6] Function object binders
template struct is_bind_expression;
template struct is_placeholder;
template unspecified bind(F f, T1 t1, ..., Tn tn );
template unspecified bind(F f, T1 t1, ..., Tn tn );
namespace placeholders {
// M is the implementation-defined number of placeholders
extern unspecified _1;
extern unspecified _2;
.
.
.
extern unspecified _M;
}
} // namespace tr1
} // namespace std
[*Configuration:]
[@../../libs/config/index.html Boost.Config] should (automatically) define
the macro BOOST_HAS_TR1_BIND if your
standard library implements this part of TR1.
[*Standard Conformity:]
The traits classes `is_placeholder` and `is_bind_expression` are not supported
by the Boost implementation.
The named return value syntax isn't supported if the object being bound is a
function pointer, for example:
std::tr1::bind(&my_proc, arg1, arg2 /* etc */); // works OK.
std::tr1::bind(&my_proc, arg1, arg2 /* etc */); // causes compiler error.
std::tr1::bind(my_function_object, arg1, arg2 /* etc */); // works OK.
On the other hand, the Boost implementation does work with pointers to overloaded
functions, and optionally with function pointers with non-standard
calling conventions.
[endsect]
[section:function Polymorphic function wrappers.]
#include
or
#include
The polymorphic function wrappers are a family of class templates
that may be used as a generalized callback mechanism.
A polymorphic function wrapper shares features with function pointers, in
that both define a call interface (for example a function taking two integer
arguments and returning a floating-point value) through which some
arbitrary code may be called. However a polymorphic function wrapper can call
any callable object with a compatible call signature, this could be a function
pointer, or it could be a function object produced by std::tr1::bind, or some
other mechanism. For more information see the [@../../doc/html/function.html
Boost.Function documentation].
namespace std {
namespace tr1 {
// [3.7] polymorphic function wrappers
class bad_function_call;
template
class function;
template
void swap(function&, function&);
template
void operator==(const function&, const function&);
template
void operator!=(const function&, const function&);
template
bool operator==(const function&, unspecified-null-pointer-type );
template
bool operator==(unspecified-null-pointer-type , const function&);
template
bool operator!=(const function&, unspecified-null-pointer-type );
template
bool operator!=(unspecified-null-pointer-type , const function&);
} // namespace tr1
} // namespace std
[*Configuration:]
[@../../libs/config/index.html Boost.Config] should (automatically) define
the macro BOOST_HAS_TR1_FUNCTION if your
standard library implements this part of TR1.
[*Standard Conformity:]
The Boost version of `std::tr1::function` lacks the member function
`target_type()` and does not inherit from `std::unary_function`
or `std::binary_function` when applicable. The member function
target() can only access pointer-to-member targets when they
have been wrapped in mem_fn.
[endsect]
[section:type_traits Type Traits.]
#include
or
#include
Type traits enable generic code to access the fundamental properties
of a type, to determine the relationship between two types, or to
transform one type into another related type. For more information
refer to the [@../../libs/type_traits/index.html Boost.Type_traits documentation].
namespace std {
namespace tr1 {
template struct integral_constant;
typedef integral_constant true_type;
typedef integral_constant false_type;
// [4.5.1] primary type categories:
template struct is_void;
template struct is_integral;
template struct is_floating_point;
template struct is_array;
template struct is_pointer;
template struct is_reference;
template struct is_member_object_pointer;
template struct is_member_function_pointer;
template struct is_enum;
template struct is_union;
template struct is_class;
template struct is_function;
// [4.5.2] composite type categories:
template struct is_arithmetic;
template struct is_fundamental;
template struct is_object;
template struct is_scalar;
template struct is_compound;
template struct is_member_pointer;
// [4.5.3] type properties:
template struct is_const;
template struct is_volatile;
template struct is_pod;
template struct is_empty;
template struct is_polymorphic;
template struct is_abstract;
template struct has_trivial_constructor;
template struct has_trivial_copy;
template struct has_trivial_assign;
template struct has_trivial_destructor;
template struct has_nothrow_constructor;
template struct has_nothrow_copy;
template struct has_nothrow_assign;
template struct has_virtual_destructor;
template struct is_signed;
template struct is_unsigned;
template struct alignment_of;
template struct rank;
template struct extent;
// [4.6] type relations:
template struct is_same;
template struct is_base_of;
template struct is_convertible;
// [4.7.1] const-volatile modifications:
template struct remove_const;
template struct remove_volatile;
template struct remove_cv;
template struct add_const;
template struct add_volatile;
template struct add_cv;
// [4.7.2] reference modifications:
template struct remove_reference;
template struct add_reference;
// [4.7.3] array modifications:
template struct remove_extent;
template struct remove_all_extents;
// [4.7.4] pointer modifications:
template struct remove_pointer;
template struct add_pointer;
// [4.8] other transformations:
template struct aligned_storage;
} // namespace tr1
} // namespace std
[*Configuration:]
[@../../libs/config/index.html Boost.Config] should (automatically) define
the macro BOOST_HAS_TR1_TYPE_TRAITS if your
standard library implements this part of TR1.
[*Standard Conformity:]
No known problems.
[endsect]
[section:random Random Number Generators and Distributions.]
#include
or
#include
The random number library is devided into three parts:
[@../../libs/random/random-generators.html generators], which
are nullary functors producing uniform random number distributions.
[@../../libs/random/random-distributions.html Distributions], which are unary
functors that adapt a generator to some
specific kind of distribution. And the class template
[@../../libs/random/random-variate.html variate_generator]
which combines a generator with a distribution, to create a new generator.
For more information see the [@../../libs/random/index.html Boost.Random documentation].
namespace std {
namespace tr1 {
// [5.1.3] Class template variate_generator
template
class variate_generator;
// [5.1.4.1] Class template linear_congruential
template
class linear_congruential;
// [5.1.4.2] Class template mersenne_twister
template
class mersenne_twister;
// [5.1.4.3] Class template substract_with_carry
template
class subtract_with_carry;
// [5.1.4.4] Class template substract_with_carry_01
template
class subtract_with_carry_01;
// [5.1.4.5] Class template discard_block
template
class discard_block;
// [5.1.4.6] Class template xor_combine
template
class xor_combine;
// [5.1.5] Predefined generators
typedef linear_congruential<
implementation-defined ,
16807,
0,
2147483647> minstd_rand0;
typedef linear_congruential<
implementation-defined ,
48271,
0,
2147483647> minstd_rand;
typedef mersenne_twister<
implementation-defined ,
32, 624, 397, 31,
0x9908b0df, 11, 7,
0x9d2c5680, 15,
0xefc60000, 18> mt19937;
typedef subtract_with_carry_01<
float,
24,
10,
24> ranlux_base_01;
typedef subtract_with_carry_01<
double,
48,
10,
24> ranlux64_base_01;
typedef discard_block<
subtract_with_carry<
implementation-defined ,
(1<<24),
10,
24>,
223,
24> ranlux3;
typedef discard_block<
subtract_with_carry<
implementation-defined,
(1<<24),
10,
24>,
389,
24> ranlux4;
typedef discard_block<
subtract_with_carry_01<
float,
24,
10,
24>,
223,
24> ranlux3_01;
typedef discard_block<
subtract_with_carry_01<
float,
24,
10,
24>,
389,
24> ranlux4_01;
// [5.1.6] Class random_device
class random_device;
// [5.1.7.1] Class template uniform_int
template
class uniform_int;
// [5.1.7.2] Class bernoulli_distribution
class bernoulli_distribution;
// [5.1.7.3] Class template geometric_distribution
template
class geometric_distribution;
// [5.1.7.4] Class template poisson_distribution
template
class poisson_distribution;
// [5.1.7.5] Class template binomial_distribution
template
class binomial_distribution;
// [5.1.7.6] Class template uniform_real
template
class uniform_real;
// [5.1.7.7] Class template exponential_distribution
template
class exponential_distribution;
// [5.1.7.8] Class template normal_distribution
template
class normal_distribution;
// [5.1.7.9] Class template gamma_distribution
template
class gamma_distribution;
} // namespace tr1
} // namespace std
[*Configuration:]
[@../../libs/config/index.html Boost.Config] should (automatically) define
the macro BOOST_HAS_TR1_RANDOM if your
standard library implements this part of TR1.
[*Standard Conformity:]
The Boost implementation has the following limitations:
*The linear_congruential generator is fully supported for
signed integer types only (unsigned types probably only work when
the modulus is zero).
*The subtract_with_carry template does not support a modulus of zero.
*Not all of the standard generator types have Boost documentation yet, they are
none the less supported however.
*Class template variate_generator does not have a template unary function call operator(),
only the non-template nullary version.
Note also that most of the Random number generators have been re-implemented
as thin wrappers around the Boost versions in order to
provide a standard conforming interface (the Boost versions all take an additional,
redundant, template parameter, and are initialized by iterators rather than functors).
[endsect]
[section:tuple Tuples.]
#include
or
#include
A tuple is a fixed size collection of elements.
Pairs, triples, quadruples etc. are tuples.
In a programming language, a tuple is a data object containing other objects as elements.
These element objects may be of different types.
Tuples are convenient in many circumstances.
For instance, tuples make it easy to define functions that return more than one value.
Some programming languages, such as ML, Python and Haskell, have built-in tuple constructs.
Unfortunately C++ does not.
To compensate for this "deficiency", the TR1 Tuple Library implements a tuple construct using templates.
For more information see the [@../../libs/tuple/index.html Boost Tuple Library Documentation].
namespace std {
namespace tr1 {
// [6.1.3] Class template tuple
template class tuple;
// [6.1.3.2] Tuple creation functions
const unspecified ignore;
template
tuple make_tuple(const T1&, const T2& , ..., const TN&);
// [6.1] Tuple types Containers
template
tuple tie(T1&, T2& , ..., TN&);
// [6.1.3.3] Tuple helper classes
template class tuple_size;
template class tuple_element;
// [6.1.3.4] Element access
template
RI get(tuple&);
template
PI get(const tuple&);
// [6.1.3.5] relational operators
template
bool operator==(const tuple&, const tuple&);
template
bool operator<(const tuple&, const tuple&);
template
bool operator!=(const tuple&, const tuple&);
template
bool operator>(const tuple&, const tuple&);
template
bool operator<=(const tuple&, const tuple&);
template
bool operator>=(const tuple&, const tuple&);
} // namespace tr1
} // namespace std
[*Configuration:]
[@../../libs/config/index.html Boost.Config] should (automatically) define
the macro BOOST_HAS_TR1_TUPLE if your
standard library implements this part of TR1.
[*Standard Conformity:]
No known issues for conforming compilers.
[endsect]
[section:utility Tuple Interface to std::pair.]
#include
or
#include
The existing class template std::pair, can also be accessed using the
[link boost_tr1.tuple tuple interface].
namespace std {
namespace tr1 {
template class tuple_size; // forward declaration
template class tuple_element; // forward declaration
template struct tuple_size >;
template struct tuple_element<0, std::pair >;
template struct tuple_element<1, std::pair >;
// see below for definition of "P".
template P& get(std::pair&);
template const P& get(const std::pair&);
} // namespace tr1
} // namespace std
[*Configuration:]
[@../../libs/config/index.html Boost.Config] should (automatically) define
the macro BOOST_HAS_TR1_UTILITY if your
standard library implements this part of TR1.
[*Standard Conformity:]
No known problems.
[endsect]
[section:array Fixed Size Array.]
#include
or
#include
Class template array is a fixed size array that is safer than and no
less efficient than a C style array. Class array fulfils almost all of the
requirements of a reversible-container (see Section 23.1,
[lib.container.requirements] of the C++ Standard). For more information refer
to the [@../../libs/array/index.html Boost.Array documentation].
namespace std {
namespace tr1 {
// [6.2.2] Class template array
template struct array;
// Array comparisons
template bool operator== (const array& x, const array& y);
template bool operator< (const array& x, const array& y);
template bool operator!= (const array& x, const array& y);
template bool operator> (const array& x, const array& y);
template bool operator>= (const array& x, const array& y);
template bool operator<= (const array& x, const array& y);
// [6.2.2.2] Specialized algorithms
template void swap(array& x, array& y);
// [6.2.2.5] Tuple interface to class template array
template class tuple_size; // forward declaration
template class tuple_element; // forward declaration
template struct tuple_size >;
template struct tuple_element >;
template T& get( array&);
template const T& get(const array&);
} // namespace tr1
} // namespace std
[*Configuration:]
[@../../libs/config/index.html Boost.Config] should (automatically) define
the macro BOOST_HAS_TR1_ARRAY if your
standard library implements this part of TR1.
[*Standard Conformity:]
No known issues as of Boost-1.34 onwards.
[endsect]
[section:hash Hash Function Objects.]
#include
or
#include
Class template std::hash is a unary-functor that converts some type T
into a hash-value,
specializations of std::hash are provided for integer, character, floating point,
and pointer types, plus the two string types std::string and std::wstring.
See the [@../../libs/functional/hash/index.html Boost.Hash]
documentation for more information.
namespace std {
namespace tr1 {
template
struct hash : public unary_function
{
size_t operator()(T val)const;
};
// Hash function specializations
template <> struct hash;
template <> struct hash;
template <> struct hash