The CppAD::vector Template Class

@(@\newcommand{\W}[1]{ \; #1 \; } \newcommand{\R}[1]{ {\rm #1} } \newcommand{\B}[1]{ {\bf #1} } \newcommand{\D}[2]{ \frac{\partial #1}{\partial #2} } \newcommand{\DD}[3]{ \frac{\partial^2 #1}{\partial #2 \partial #3} } \newcommand{\Dpow}[2]{ \frac{\partial^{#1}}{\partial {#2}^{#1}} } \newcommand{\dpow}[2]{ \frac{ {\rm d}^{#1}}{{\rm d}\, {#2}^{#1}} }@)@The CppAD::vector Template Class
Syntax
# include <cppad/utility/vector.hpp>

Description
The include file cppad/vector.hpp defines the vector template class CppAD::vector. This is a SimpleVector template class and in addition it has the features listed below:

Include
The file cppad/vector.hpp is included by cppad/cppad.hpp but it can also be included separately with out the rest of the CppAD include files.

capacity
If x is a CppAD::vector<Scalar> , and cap is a size_t object,



     cap = x.capacity()

set cap to the number of Scalar objects that could fit in the memory currently allocated for x . Note that



     x.size() <= x.capacity()

Assignment
If x and y are CppAD::vector<Scalar> objects,



     y = x

has all the properties listed for a simple vector assignment plus the following:

Check Size
The CppAD::vector template class will check that the size of x is either zero or the size of y before doing the assignment. If this is not the case, CppAD::vector will use ErrorHandler to generate an appropriate error report. Allowing for assignment to a vector with size zero makes the following code work:



     CppAD::vector<Scalar> y;

     y = x;

Return Reference
A reference to the vector y is returned. An example use of this reference is in multiple assignments of the form



     z = y = x

Move Semantics
If the C++ compiler supports move semantic rvalues using the && syntax, then it will be used during the vector assignment statement. This means that return values and other temporaries are not be copied, but rather pointers are transferred.

Element Access
If x is a CppAD::vector<Scalar> object and i has type size_t,



     x[i]

has all the properties listed for a simple vector element access plus the following:

The object x[i] has type Scalar (is not possibly a different type that can be converted to Scalar ).

If i is not less than the size of the x , CppAD::vector will use ErrorHandler to generate an appropriate error report.

push_back
If x is a CppAD::vector<Scalar> object with size equal to n and s has type Scalar ,



     x.push_back(s)

extends the vector x so that its new size is n plus one and x[n] is equal to s (equal in the sense of the Scalar assignment operator).

push_vector
If x is a CppAD::vector<Scalar> object with size equal to n and v is a simple vector with elements of type Scalar and size m ,



     x.push_vector(v)

extends the vector x so that its new size is n+m and x[n + i] is equal to v[i] for i = 1 , ... , m-1 (equal in the sense of the Scalar assignment operator).

Output
If x is a CppAD::vector<Scalar> object and os is an std::ostream, and the operation



     os << x

will output the vector x to the standard output stream os . The elements of x are enclosed at the beginning by a { character, they are separated by , characters, and they are enclosed at the end by } character. It is assumed by this operation that if e is an object with type Scalar ,



     os << e

will output the value e to the standard output stream os .

resize
The call x.resize(n) set the size of x equal to n . If n <= x.capacity() , no memory is freed or allocated, the capacity of x does not change, and the data in x is preserved. If n > x.capacity() , new memory is allocated and the data in x is lost (not copied to the new memory location).

clear
All memory allocated for the vector is freed and both its size and capacity are set to zero. This can be useful when using very large vectors and when checking for memory leaks (and there are global vectors) see the memory discussion.

data
If x is a CppAD::vector<Scalar> object



     x.data()

returns a pointer to a Scalar object such that for 0 <= i < x.size() , x[i] and x.data()[i] are the same Scalar object. If x is const, the pointer is const. If x.capacity() is zero, the value of the pointer is not defined. The pointer may no longer be valid after the following operations on x : its destructor, clear, resize, push_back, push_vector, assignment to another vector when original size of x is zero.

vectorBool
The file <cppad/vector.hpp> also defines the class CppAD::vectorBool. This has the same specifications as CppAD::vector<bool> with the following exceptions:

Memory
The class vectorBool conserves on memory (on the other hand, CppAD::vector<bool> is expected to be faster than vectorBool).

bit_per_unit
The static function call



     s = vectorBool::bit_per_unit()

returns the size_t value s which is equal to the number of boolean values (bits) that are packed into one operational unit. For example, a logical or acts on this many boolean values with one operation.

data
The data function is not supported by vectorBool.

Output
The CppAD::vectorBool output operator prints each boolean value as a 0 for false, a 1 for true, and does not print any other output; i.e., the vector is written a long sequence of zeros and ones with no surrounding {, } and with no separating commas or spaces.

Element Type
If x has type vectorBool and i has type size_t, the element access value x[i] has an unspecified type, referred to here as elementType , that supports the following operations:

elementType can be converted to bool; e.g. the following syntax is supported: static_cast<bool>( x[i] )
elementType supports the assignment operator = where the right hand side is a bool or an elementType object; e.g., if y has type bool, the following syntax is supported: x[i] = y
The result of an assignment to an elementType also has type elementType . Thus, if z has type bool, the following syntax is supported: z = x[i] = y

Memory and Parallel Mode
These vectors use the multi-threaded fast memory allocator thread_alloc :

The routine parallel_setup must be called before these vectors can be used in parallel .
Using these vectors affects the amount of memory in_use and available .
Calling clear , makes the corresponding memory available (though thread_alloc) to the current thread.
Available memory can then be completely freed using free_available .

Example
The files cppad_vector.cpp and vector_bool.cpp each contain an example and test of this template class. They return true if they succeed and false otherwise.

Exercise
Create and run a program that contains the following code:

 
     CppAD::vector<double> x(3);
     size_t i;
     for(i = 0; i < 3; i++)
          x[i] = 4. - i;
     std::cout << "x = " << x << std::endl;

Input File: cppad/utility/vector.hpp