Technical Report 1

From Wikipedia, the free encyclopedia

Technical Report 1 (TR1) is a draft document specifying additions to the C++ Standard Library such as regular expressions, smart pointers, hash tables, and random number generators. TR1 is not yet standardized, but likely will be part of the next official standard mostly as it stands now. In the meantime, vendors can use this document as a guide to create extensions. The report's goal is "to build more widespread existing practice for an expanded C++ standard library."[1]

[edit] Overview

Compilers need not include the TR1 components to be conforming, as TR1 is not yet officially part of the standard. Much of it is available from Boost, and several compiler/library distributors currently implement all or part of the components.

TR1 is not a complete list of additions to the library that will appear in the next standard; for example, the next standard, C++0x, may include support for threading. There is also a second technical report, TR2, planned for publishing after C++0x [2].

The new components are in the std::tr1 namespace to distinguish them from the current standard library.

[edit] Components

TR1 includes the following components:

[edit] General Utilities

[edit] Reference Wrapper

lifted from Boost.Ref ^[3]
additions to the <functional> header file - cref, ref, reference_wrapper
enables passing references, rather than copies, into algorithms or function objects

[edit] Smart Pointers

based on Boost Smart Pointer library ^[4]
additions to the <memory> header file - shared_ptr, weak_ptr, etc
utility for memory management and exception safety using the Resource Acquisition Is Initialization (RAII) idiom

[edit] Function Objects

These four modules are added to the <functional> header file:

[edit] Polymorphic Function Wrapper

function
based on Boost.Function ^[5]
stores all callables (function pointers, member function pointers, and function objects) that use a specified function call signature. The specific type of callable object is not required.

[edit] Function Object Binders

bind
taken from Boost Bind library ^[6]
generalized version of the standard std::bind1st and std::bind2nd
binds parameters to function objects, and allows for function composition.

[edit] Function Return Types

result_of
taken from Boost
determines the type of a call expression

[edit] mem_fn

mem_fn
based on Boost Mem Fn library ^[7]
enhancement to the standard std::mem_fun and std::mem_fun_ref
allows pointers to member functions to be treated as function objects

[edit] Metaprogramming and Type Traits

new <type_traits> header file - is_pod, has_virtual_destructor, remove_extent, etc
based on Boost Type Traits library ^[8]
facilitates metaprogramming by enabling queries on and transformation between different types

[edit] Numerical Facilities

[edit] Random Number Generation

new <random> header file - variate_generator, mersenne twister, poisson distribution, etc
utilities for generating random numbers using various engines and probability distributions

[edit] Mathematical Functions

Some features of TR1, such as the mathematical functions and certain C99 additions, are not included in the Visual C++ implementation of TR1.

additions to the <cmath>/<math.h> header files - beta, legendre, etc

These functions will be of principal interest to programmers in the engineering and scientific disciplines.

The following table shows all 23 functions described in TR1.

Function name	Function prototype	Mathematical expression
Associated Laguerre polynomials	double assoc_laguerre( unsigned n, unsigned m, double x ) ;	${L_n}^m(x) = (-1)^m \frac{d^m}{dx^m} L_{n+m}(x), \text{ for } x \ge 0$
Associated Legendre polynomials	double assoc_legendre( unsigned l, unsigned m, double x ) ;	${P_l}^m(x) = (1-x^2)^{m/2} \frac{d^m}{dx^m} P_l(x), \text{ for } x \ge 0$
Beta function	double beta( double x, double y ) ;	$\Beta(x,y)=\frac{\Gamma(x) \Gamma(y)}{\Gamma(x+y)}$
Complete elliptic integral of the first kind	double comp_ellint_1( double k ) ;	$K(k) = F\left(k, \textstyle \frac{\pi}{2}\right) = \int_0^{\frac{\pi}{2}} \frac{d\theta}{\sqrt{1 - k^2 \sin^2 \theta}}$
Complete elliptic integral of the second kind	double comp_ellint_2( double k ) ;	$E\left(k, \textstyle \frac{\pi}{2}\right) = \int_0^{\frac{\pi}{2}} \sqrt{1 - k^2 \sin^2 \theta}\; d\theta$
Complete elliptic integral of the third kind	double comp_ellint_3( double k , double nu ) ;	$\Pi\left(\nu, k, \textstyle \frac{\pi}{2}\right) = \int_0^{\frac{\pi}{2}} \frac{d\theta}{(1 - \nu \sin^2 \theta)\sqrt{1 - k^2 \sin^2 \theta}}$
Confluent hypergeometric functions	double conf_hyperg( double a, double c, double x ) ;	$F(a, c, x) = \frac{\Gamma(c)}{\Gamma(a)} \sum_{n = 0}^\infty \frac{\Gamma(a + n) x^n}{\Gamma(c + n) n!}$
Regular modified cylindrical Bessel functions	double cyl_bessel_i( double nu, double x ) ;	$I_\nu(x) = i^{-\nu} J_\nu(ix) = \sum_{k = 0}^\infty \frac{(x/2)^{\nu + 2k}}{k! \; \Gamma(\nu + k + 1)}, \text{ for } x \ge 0$
Cylindrical Bessel functions of the first kind	double cyl_bessel_j( double nu, double x ) ;	$J_\nu(x) = \sum_{k = 0}^\infty \frac{(-1)^k \; (x/2)^{\nu + 2k}}{k! \; \Gamma(\nu + k + 1)}, \text{ for } x \ge 0$
Irregular modified cylindrical Bessel functions	double cyl_bessel_k( double nu, double x ) ;	$\begin{align} K_\nu(x) & = \textstyle\frac{\pi}{2} i^{\nu+1} \big(J_\nu(ix) + i N_\nu(ix)\big) \\ & = \begin{cases} \displaystyle \frac{I_{-\nu}(x) - I_\nu(x)}{\sin \nu\pi}, & \text{for } x \ge 0 \text{ and } \nu \notin \mathbb{Z} \\[10pt] \displaystyle \frac{\pi}{2} \lim_{\mu \to \nu} \frac{I_{-\mu}(x) - I_\mu(x)}{\sin \mu\pi}, & \text{for } x < 0 \text{ and } \nu \in \mathbb{Z} \\ \end{cases} \end{align}$
Cylindrical Neumann functions Cylindrical Bessel functions of the second kind	double cyl_neumann( double nu, double x ) ;	$N_\nu(x) = \begin{cases} \displaystyle \frac{J_\nu(x)\cos \nu\pi - J_{-\nu}(x)}{\sin \nu\pi}, & \text{for } x \ge 0 \text{ and } \nu \notin \mathbb{Z} \\[10pt] \displaystyle \lim_{\mu \to \nu} \frac{J_\mu(x)\cos \mu\pi - J_{-\mu}(x)}{\sin \mu\pi}, & \text{for } x < 0 \text{ and } \nu \in \mathbb{Z} \\ \end{cases}$
Incomplete elliptic integral of the first kind	double ellint_1( double k, double phi ) ;	$F(k,\phi)=\int_0^\phi\frac{d\theta}{\sqrt{1-k^2\sin^2\theta}}, \text{ for } \left\|k\right\| \le 1$
Incomplete elliptic integral of the second kind	double ellint_2( double k, double phi ) ;	$\displaystyle E(k,\phi)=\int_0^\phi\sqrt{1-k^2\sin^2\theta}d\theta, \text{ for } \left\|k\right\| \le 1$
Incomplete elliptic integral of the third kind	double ellint_3( double k, double nu, double phi ) ;	$\Pi(k,\nu,\phi)=\int_0^\phi\frac{d\theta}{\left(1-\nu\sin^2\theta\right)\sqrt{1-k^2\sin^2\theta}}, \text{ per } \left\|k\right\| \le 1$
Exponential integral	double expint( double x ) ;	$\mbox{E}i(x)=-\int_{-x}^{\infty} \frac{e^{-t}}{t}\, dt$
Hermite polynomials	double hermite( unsigned n, double x ) ;	$H_n(x)=(-1)^n e^{x^2}\frac{d^n}{dx^n}e^{-x^2}\,\!$
Hypergeometric series	double hyperg( double a, double b, double c, double x ) ;	$F(a,b,c,x)=\frac{\Gamma(c)}{\Gamma(a)\Gamma(b)}\sum_{n = 0}^\infty\frac{\Gamma(a+n)\Gamma(b+n)}{\Gamma(c+n)}\frac{x^n}{n!}$
Laguerre polynomials	double laguerre( unsigned n, double x ) ;	$L_n(x)=\frac{e^x}{n!}\frac{d^n}{dx^n}\left(x^n e^{-x}\right), \text{ for } x \ge 0$
Legendre polynomials	double legendre( unsigned l, double x ) ;	$P_l(x) = {1 \over 2^l l!} {d^l \over dx^l } (x^2 -1)^l, \text{ for } \left\|x\right\| \le 1$
Riemann zeta function	double riemann_zeta( double x ) ;	$\Zeta(x) = \begin{cases} \displaystyle \sum_{k = 1}^\infty k^{-x}, & \text{for } x > 1 \\[10pt] \displaystyle 2^x\pi^{x-1}\sin\left(\frac{x\pi}{2}\right)\Gamma(1-x)\zeta(1-x), & \text{for } x < 1 \\ \end{cases}$
Spherical Bessel functions of the first kind	double sph_bessel( unsigned n, double x ) ;	$j_n(x) = \sqrt{\frac{\pi}{2x}} J_{n+1/2}(x), \text{ for } x \ge 0$
Spherical associated Legendre functions	double sph_legendre( unsigned l, unsigned m, double theta ) ;	$Y_{l}^{m}(\theta, 0) \text{ where } Y_{l}^{m}(\theta, \phi) = (-1)^{m}\left[\frac{(2l+1)}{4\pi}\frac{(l-m)!}{(l+m)!}\right]^{1 \over 2} P_{l}^{m}(cos \theta)e^{im\phi}, \text{ for } \|m\| \leq l$
Spherical Neumann functions Spherical Bessel functions of the second kind	double sph_neumann( unsigned n, double x ) ;	$n_n(x) = \left(\frac{\pi}{2x}\right)^{\frac{1}{2}}N_{n+\frac{1}{2}}(x), \text{ for } x \ge 0$

Each function has two additional variants. Appending the suffix ‘f’ or ‘l’ to a function name gives a function that operates on float or long double values respectively. For example:

float sph_neumannf( unsigned n, float x ) ;
long double sph_neumannl( unsigned n, long double x ) ;

[edit] Wrapper reference

A wrapper reference is obtained from an instance of the template class reference_wrapper. Wrapper references are similar to normal references (‘&’) of the C++ language. To obtain a wrapper reference from any object the template class ref is used (for a constant reference cref is used).

Wrapper references are useful above all for template functions, when we need to obtain references to parameters rather than copies:

// This function will obtain a reference to the parameter 'r' and increase it.
void f( int &r )  { r++ ; }
 
// Template function.
template< class F, class P > void g( F f, P t )  { f(t) ; }
 
int main()
{
  int i = 0 ;
  g( f, i ) ;  // 'g<void ( int &r ), int>' is instantiated
               // then 'i' will not be modified.
  cout << i << endl ;  // Output -> 0
 
  g( f, ref(i) ) ;  // 'g<void(int &r),reference_wrapper<int>>' is instanced
                    // then 'i' will be modified.
  cout << i << endl ;  // Output -> 1
}

[edit] Containers

[edit] Tuple Types

new <tuple> header file - tuple
based on Boost Tuple library ^[9]
vaguely an extension of the standard std::pair
fixed size collection of elements, which may be of different types

[edit] Fixed Size Array

new <array> header file - array
lifted from Boost Array library ^[10]
as opposed to dynamic array types such as the standard std::vector

[edit] Hash Tables

new <unordered_set>, <unordered_map> header files
new implementation, not derived from an existing library, not fully API compatible with existing libraries
like all hash tables, often provide constant time lookup of elements but the worst case can be linear in the size of the container

[edit] Regular Expressions

new <regex> header file - regex, regex_match, regex_search, regex_replace, etc
based on Boost RegEx library ^[11]
pattern matching library

[edit] C Compatibility

C++ is designed to be compatible with the C programming language, but is not a strict superset of C due to diverging standards. TR1 attempts to reconcile some of these differences through additions to various headers in the C++ library, such as <complex>, <locale>, <cmath>, etc. These changes help to bring C++ more in line with the C99 version of the C standard (not all parts of C99 are included in TR1).

[edit] See also

Boost library, a large collection of portable C++ libraries, several of which were included in TR1
Standard Template Library, part of the current C++ Standard Library
C++0x, the planned new standard for the C++ programming language
Dinkumware, the only commercial vendor to fully implement TR1

[edit] Literature

Peter Becker: "The C++ Standard Library Extensions: A Tutorial and Reference", 2006, ISBN 0-321-41299-0. Covers also the TR1 extensions.

[edit] External links

http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf - pdf of the Proposed Draft
http://aristeia.com/EC3E/TR1_info_frames.html - Scott Meyers' TR1 page, links to documents and articles

Categories: C++ standard library