The CppAD::vector Template Class
Keywords: the cppad::vector template class vector Cppad [] push thread_alloc syntax description include capacity assignment check size return reference move semantics element access push_back push_vector output resize clear data vectorbool memory bit_per_unit type parallel mode example exercise

| Prev | Next |  |  |  |  |  |

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. The 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:

1. `elementType` can be converted to `bool`; e.g. the following syntax is supported: `
   static_cast<bool>( x[i] )
   `
2. `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
   `
3. 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 :

1. The routine parallel_setup must be called before these vectors can be used in parallel .
2. Using these vectors affects the amount of memory in_use and available .
3. Calling clear , makes the corresponding memory available (though `thread_alloc`) to the current thread.
4. 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