The auto_ptr class provides a simple class for smart pointers; it stores a pointer to an object obtained by way of the new operator and deletes that object when the auto_ptr object is destroyed. The auto_ptr class provides semantics of strict ownership. After construction an auto_ptr object owns the object whose pointer it holds. When an instantiation of auto_ptr is copied, ownership of the object is transferred to the destination auto_ptr. The behavior is undefined if more than one instantiation of auto_ptr owns the same object at the same time.

The ANSI C++ September 1996 auto_ptr class makes use of member templates for its copy constructor and assignment operator. Because the current DEC C++ compiler does not support member templates, auto_ptr does not make use of them for copy construction or assignment operations.

6.7.1 The auto_ptr Member Functions

explicit auto_ptr(T* p=0) throw();

Constructs an object of class auto_ptr<T>. The pointer held by the auto_ptr class is initialized to p. The p variable points to an object of type T or a class derived from T for which delete p is defined and accessible, or p is a null pointer.

auto_ptr(const auto_ptr<T>& a) throw();

Constructs an object of class auto_ptr<T>. The argument a is copied to *this. If a owns the held pointer, ownership is transferred to *this.

auto_ptr<T>& operator=(const auto_ptr<T>& rhs) throw();

The argument rhs is copied to *this. If rhs owns the held pointer, ownership is transferred to *this. If *this already owns a pointer (not equal to the pointer owned by rhs), that held pointer is deleted first.

~auto_ptr();

If *this owns the held pointer, the pointer is deleted.

T& operator*() const throw();

Returns a reference to the object to which the underlying held pointer points.

T* operator->() const throw();

Returns the underlying held pointer.

T* get() const throw();

Returns the underlying held pointer.

T* release() throw();

Returns the underlying held pointer after releasing ownership of it.

The standard exception classes are all classes derived from the exception class and are used in the standard library to report errors detected during program execution. A simple example of using this class follows:

#include <stdexcept> #include <string> int main() { try { string s("abc"); if (s.at(4)=='d') ; // out of range } catch(const exception& e) { cout << e.what() << endl; } catch(...) { cout << "unknown exception" << endl; } }

The output from this example is as follows:

position beyond end of string

Users may also use the standard exception hierarchy to report errors in their own classes.

6.8.1 Types of Standard Exceptions

All standard exceptions are rooted at the base class exception. No standard library errors throw an object of type exception (they are always of a more specific or derived type). This class is simply used as a base class when a user wants to catch all standard exceptions, as in the previous example.

Six classes are derived from exception:

• logic_error
• runtime_error
• bad_exception
• bad_alloc
• bad_cast
• bad_typeid

• The logic_error exceptions are used to report errors detectable before the program executes, such as violations of logical preconditions or class invariants.
• The runtime_error exceptions are used to report errors detectable only when the program executes, such as mathematical overflow or underflow.
• The bad_alloc, bad_exception, bad_cast, and bad_typeid exceptions are currently not implemented in the DEC C++ compiler.

The logic_error class has four derived classes:

• domain_error (used to report domain errors)
• invalid_argument (used to report invalid arguments)
• length_error (used to report an attempt to produce an object whose length exceeds it maximum allowable size)
• out_of_range (used to report an argument value not in its expected range)

The runtime_error class has three derived classes:

• range_error (used to report errors in internal computations)
• overflow_error (used to report an arithmetic overflow error)
• underflow_error (used to report an arithmetic underflow error)

exception() throw();

Constructs an object of class exception.

exception(const exception&) throw();

Copies an exception object.

exception& operator=(const exception&) throw();

Assigns an exception object.

virtual ~exception() throw();

Destroys the exception object.

virtual const char* what() const throw();

Returns a null-terminated byte string that contains information about the type of error. The contents of the string are implementation dependent. In the DEC C++ library the string contains an indication of the problem---that is, string index out of range or invalid string size parameter.

All of the standard exception classes are derived from class exception; thus, they inherit all of the exception class member functions. The only difference is in the constructor---all have an overridden constructor that takes a string argument; that is:

class logic_error: public exception { public: logic_error(const string& what_arg); }; class domain_error: public logic_error { public: domain_error(const string& what_arg); }; class invalid_argument: public logic_error { public: invalid_argument(const string& what_arg); }; class length_error: public logic_error { public: length_error(const string& what_arg); }; class out_of_range: public logic_error { public: out_of_range(const string& what_arg); }; class runtime_error: public exception { public: runtime_error(const string& what_arg); }; class range_error: public runtime_error { public: range_error(const string& what_arg); }; class overflow_error: public runtime_error { public: overflow_error(const string& what_arg); }; class underflow_error: public runtime_error { public: underflow_error(const string& what_arg); };

6.9 The Complex Math Library

A complex number has a real part and an imaginary part. The standard complex library utilizes templates, so that any underlying type can be used to represent these parts. Template specializations are provided for float, double, and long double.

6.9.1 Example of Use

A simple example of use is:

#include <complex> int main() { complex<double> c1(1,1), c2(3.14,3.14); cout << "c2/c1: " << c2/c1 << endl; }

Note that you must explicitly link in the math library when using the complex library on DIGITAL UNIX, that is:

cxx prog.cxx -lm

6.9.2 Complex Math Member Functions

complex(const T& re = T(), const T& im = T());

Constructs an object of type complex with the real part set to re and the imaginary part set to im.

complex(const complex<T>& c);

Constructs a complex number by copying all elements from c.

complex<T>& operator=(const complex<T>& c);

Assigns c to *this and returns *this.

complex<T>& operator=(const T& c);

Assigns c to the real part of *this. Sets the imaginary part of *this to zero and returns *this.

complex<T>& operator+=(const complex<T>& c);

Adds c to *this and then returns the result.

complex<T>& operator-=(const complex<T>& c);

Subtracts c from *this and then returns the result.

complex<T>& operator*=(const complex<T>& c);

Multiplies c and *this and then returns the result.

complex<T>& operator/=(const complex<T>& c);

Divides *this by c and then returns the result.

T real();

Returns the real part of *this.

T imag();

Returns the imaginary part of *this.

6.9.3 Complex Math Nonmember Functions

template <class T>

T real(const complex<T>& c);

Returns the real part of c.

template <class T>

T imag(const complex<T>& c);

Returns the imaginary part of c.

template <class T>

T abs(const complex<T>& c);

Returns the magnitude of c.

template <class T>

T norm(const complex<T>& c);

Returns the squared magnitude of c.

template <class T>

T arg(const complex<T>& c);

Returns the phase angle of c.

template <class T>

complex<T> conj(const complex<T>& c);

Returns the complex conjugate of c.

template <class T>

complex<T> polar(const T& rho, const T& theta = 0);

Returns the complex value corresponding to a complex number whose magnitude is rho and whose phase angle is theta.

template <class T>

complex<T> cos(const complex<T>& c);

Returns the complex cosine of c.

template <class T>

complex<T> cosh(const complex<T>& c);

Returns the complex hyperbolic cosine of c.

template <class T>

complex<T> exp(const complex<T>& c);

Returns the complex base e exponential of c.

template <class T>

complex<T> log(const complex<T>& c);

Returns the complex natural (base e) logarithm of x.

template <class T>

complex<T> log10(const complex<T>& c);

Returns the complex common (base 10) logarithm of x.

template <class T>
complex<T> pow(const complex<T>& x, int y); template <class T> complex<T> pow(const complex<T>& x, int y); template <class T> complex<T> pow(const complex<T>& x, const complex<T>& y);

template <class T>
complex<T> pow(const complex<T>& x, const T& y); template <class T> complex<T> pow(const T& x, const complex<T>& y);

Returns the complex power of base x raised to the y-th power.

template <class T>

complex<T> sin(const complex<T>& c);

Returns the complex sine of c.

template <class T>

complex<T> sinh(const complex<T>& c);

Returns the complex hyperbolic sine of c.

template <class T>

complex<T> sqrt(const complex<T>& c);

Returns the complex square root of c, in the range of the right half-plane.

template <class T>

complex<T> tan(const complex<T>& c);

Returns the complex tangent of c.

template <class T>

complex<T> tanh(const complex<T>& c);

Returns the complex hyperbolic tangent of c.

6.9.4 Complex Math Nonmember Operators

template <class T>
complex<T> operator+(const complex<T>& lhs, const T& rhs);

template <class T>
complex<T> operator+(const T& lhs, const complex<T>& rhs);

Adds rhs to lhs and returns the sum.

template <class T>
complex<T> operator+(const complex<T>& lhs, const T& rhs);

template <class T>
complex<T> operator+(const T& lhs, const complex<T>& rhs);

Subtracts rhs from lhs and returns the difference.

template <class T>
complex<T> operator*(const complex<T>& lhs, const T& rhs);

template <class T>
complex<T> operator*(const T& lhs, const complex<T>& rhs);

Multiplies rhs and lhs and returns the product.

template <class T>
complex<T> operator/(const complex<T>& lhs, const T& rhs);

template <class T>
complex<T> operator/(const T& lhs, const complex<T>& rhs);

Divides rhs into lhs and returns the quotient.

template <class T>
complex<T> operator:=,=(const complex<T>& lhs, const T& rhs);

template <class T>
complex<T> operator:=,=(const T& lhs, const complex<T>& rhs);

Compares lhs to rhs and returns true if they are equal, otherwise returns false. The imaginary parts of the scalars are assumed to be the value T().

template <class T>
complex<T> operator!=(const complex<T>& lhs, const T& rhs);

template <class T>
complex<T> operator!=(const T& lhs, const complex<T>& rhs);

Compares lhs to rhs and returns true if they are not equal, otherwise returns false. The imaginary parts of the scalars are assumed to be T().

template <class T, class charT, class traits>

istream& operator>>(istream& is, complex<T>& c);

Extracts a complex number c from the istream is of the form u, (u), or (u,v), where u is the real part and v is the imaginary part. If bad input is encountered, sets ios::failbit.

template <class T, class charT, class traits>

ostream operator<<(ostream& os, const complex<T>& c);

Returns os << "(" << c.real() << "," << c.imag() << ")".

typedef T value_type;

The type used to represent the real and imaginary parts of the complex number.

Because the DEC C++ compiler does not yet support the explicit keyword (that is, nonconverting constructors), unsafe downcasts will be allowed; that is, users can convert a complex<double> to a complex<float>.

6.9.7 Upgrading from the Nonstandard Complex Math Library

This section explains how to upgrade from the pre-ANSI DEC C++ complex library to the current DEC C++ standard complex library, which is based on the 24 September 1996 ANSI C++ working draft.

In the ANSI library, complex objects are templatized on the type of the real and imaginary parts, the pre-ANSI DEC C++ library, complex objects are not templatized. The pre-ANSI library assumes the type is double, whereas the new library provides specializations for float, double, and long double as well as allowing users to specialize on their own floating point types.

Also note that mathematical error checking is not supported in the ANSI library. Users who rely on detection of underflow, overflow, and divide by zero should continue using the pre-ANSI DEC C++ complex library.

The following is a detailed list of important changes:

• Change #include <complex.h> or #include <complex.hxx> to #include <complex>.
• Change all declarations of complex to complex<double>, for example:

  complex c;

  
  to:

  complex<double> c;

• The polar() function no longer supplies a default value of 0 for the second argument. Users will have to explicitly add it to any calls that have only one argument, for example:

  complex c; c = polar(c); // get polar

  
  to:

  complex<double> c; c = polar(c,0.0);

• If you are calling a mathematical function or mathematical operator that takes scalars as arguments (polar() for example), then you must adjust the arguments you pass in to be the same type as the complex template parameter type. For example, you would have to change:

  complex c = polar(0,0); complex c2 = c+1;

  
  to:

  complex<double> c = polar(0.0,0.0); // 0.0 is double complex<double> c2= c + 1.0; // 1.0 is double

• The complex_zero variable is not declared in the complex header file. If you want to use it, you will have to declare it yourself. For example, add the following to the top of your source file:

  static const complex<double> complex_zero(0.0,0.0);

• The sqr() and arg1() functions are gone. If you want to continue to use them, you should define them in one of your own headers, using the following definitions.

  template <class T> inline complex<T> sqr(const complex<T>& a) { return complex<T>(real(a) * real(a) - imag(a) * imag(a), 2 * real(a) * imag(a)); } template <class T> inline T arg1(const complex<T>& a) { double val = arg(a); if(val > -M_PI && val <= M_PI) return val; if(val > M_PI) return val - (2*M_PI); // val <= -PI return val + (2*M_PI); }

• The pow(complex, int) function is no longer provided. You must use pow(complex<double>, double). This means changing calls such as:

  pow(c,1);

  
  to:

  pow(c,1.0);

  
  This may yield different results if the function previously was underflowing or overflowing, it may not happen anymore.

• The complex output operator (<<) does not insert a space between the comma and the imaginary part. If you want the space, you would need to print the real and imaginary parts separately, adding your own comma and space; that is:

  complex<double> c; cout << "(" << c.real() << ", " << c.imag() << ")"; // add extra space

• The complex input operator (>>) does not raise an Objection if bad input is detected; it instead sets input stream's state to ios::failbit.
• Floating point overflow, underflow, and divide by zero do not set errno and will cause undefined behavior. DIGITAL plans to do complex error checking and error notification in a subsequent release.
• You should no longer need to explicitly link your program with the complex library. It is automatically linked in as part of the standard library. You still have to explicitly link in the C math library, however, as shown in Section 6.9.1.

The Standard C++ Library defines an allocator class that is used to control the memory model containers will use. Every container class in the Standard C++ library takes an allocator as one of its template arguments. In this way each container can manage its own storage requirements. Containers can make use of different memory models by using allocators that implement different types of memory management schemes. A default allocator that makes use of the global new and delete is provided by the Standard library.

The allocator as defined in the 24 September 1996 draft C++ Standard makes use of member function templates and member class templates. The lack of member template support in the current version of DEC C++ mandates the use of an allocator that does not utilize this feature. Therefore the DEC C++ library provides an alternate allocator class. The alternate allocator allocates raw bytes of storage. Its types and functions are provided by an allocator_interface class. Under this scheme the allocator makes use of the allocator_interface class to allocate typed storage rather than allocating itself directly. The implementation is not standard conforming so its use will be documented in this section.

Note that the current version of the DEC C++ library also contains a specialization for void. The specialization for void does not conform to standard either. Refer to the 24 September 1996 ANSI C++ draft for details on the ANSI C++ draft conforming allocator.

The rest of this section defines the allocator class provided with the current version of DEC C++. It also describes how to build custom allocators and containers that make use of this allocator class.