# Storage

## Unbounded Array

#### Description

The templated class `unbounded_array<T, ALLOC>` implements a unbounded storage array using an allocator. The unbounded array is similar to a `std::vector` in that in can grow in size beyond any fixed bound.

When resized `unbounded_array` will reallocate it's storage even if the new size requirement is smaller. It is therefore inefficient to resize a `unbounded_array`

#### Example

    #include <boost/numeric/ublas/storage.hpp>

    int main () {
        using namespace boost::numeric::ublas;
        unbounded_array<double> a (3);
        for (unsigned i = 0; i < a.size (); ++ i) {
            a [i] = i;
            std::cout << a [i] << std::endl;
        }
    }

#### Definition

Defined in the header storage.hpp.

#### Template parameters

Parameter | Description | Default
--- | --- | ---
`T` | The type of object stored in the array. |
`ALLOC` | An STL Allocator | std::allocator

#### Model of

Random Access Container.

#### Type requirements

None, except for those imposed by the requirements of Random Access Container.

#### Public base classes

None.

#### Members

Member | Description
--- | ---
`explicit unbounded_array (ALLOC &a = ALLOC())` | Allocates an initialized `unbounded_array` that holds at most zero elements, using a specified allocator.
`explicit unbounded_array (size_type size, ALLOC &a = ALLOC())` | Allocates an initialized `unbounded_array` that holds at most `size` elements. using a specified allocator.
`explicit unbounded_array (size_type size, no_init, ALLOC &a = ALLOC())` | Allocates an uninitialized `unbounded_array` that holds at most `size` elements, using a specified allocator.
`unbounded_array (const unbounded_array &a)` | The copy constructor.
`~unbounded_array ()` | Deallocates the `unbounded_array` itself.
`void resize (size_type size, value_type init)` | Resizes an `unbounded_array` to hold at most `size` elements. The `unbounded_array` is reallocated only if the size changes. Element values are preserved, additional elements are assigned the value of init.
`void resize (size_type size)` | Resizes an `unbounded_array` to hold at most `size` elements. The `unbounded_array` is reallocated only if the size changes. The elements values are undefined.
`size_type size () const` | Returns the size of the `unbounded_array`.
`const_reference operator [] (size_type i) const` | Returns a `const` reference of the `i` -th element.
`reference operator [] (size_type i)` | Returns a reference of the `i`-th element.
`unbounded_array &operator = (const unbounded_array &a)` | The assignment operator.
`unbounded_array &assign_temporary (unbounded_array &a)` | Assigns a temporary. May change the array `a`.
`void swap (unbounded_array &a)` | Swaps the contents of the arrays.
`const_iterator begin () const` | Returns a `const_iterator` pointing to the beginning of the `unbounded_array`.
`const_iterator end () const` | Returns a `const_iterator` pointing to the end of the `unbounded_array`.
`iterator begin ()` | Returns a `iterator` pointing to the beginning of the `unbounded_array`.
`iterator end ()` | Returns a `iterator` pointing to the end of the `unbounded_array`.
`const_reverse_iterator rbegin () const` | Returns a `const_reverse_iterator` pointing to the beginning of the reversed `unbounded_array`.
`const_reverse_iterator rend () const` | Returns a `const_reverse_iterator` pointing to the end of the reversed `unbounded_array`.
`reverse_iterator rbegin ()` | Returns a `reverse_iterator` pointing to the beginning of the reversed `unbounded_array`.
`reverse_iterator rend ()` | Returns a `reverse_iterator` pointing to the end of the reversed `unbounded_array`.

## Bounded Array

#### Description

The templated class `bounded_array<T, N, ALLOC>` implements a bounded storage array. The bounded array is similar to a C++ array type in that its maximum size is bounded by N. Similarly a `bounded_array` requires no secondary storage and ALLOC is only used to specify`size_type` and `difference_type`.

When resized `bounded_array` uses the same storage with the same bound!. It is therefore efficient to resize a `bounded_array`

#### Example

    #include <boost/numeric/ublas/storage.hpp>

    int main () {
        using namespace boost::numeric::ublas;
        bounded_array<double, 3> a (3);
        for (unsigned i = 0; i < a.size (); ++ i) {
            a [i] = i;
            std::cout << a [i] << std::endl;
        }
    }

#### Definition

Defined in the header storage.hpp.

#### Template parameters

Parameter | Description | Default
--- | --- | ---
`T` | The type of object stored in the array. |
`N` | The allocation size of the array. |
`ALLOC` | An STL Allocator | std::allocator

#### Model of

Random Access Container.

#### Type requirements

None, except for those imposed by the requirements of Random Access Container.

#### Public base classes

None.

#### Members

Member | Description
--- | ---
`bounded_array ()` | Allocates an initialized `bounded_array` that holds at most ZERO elements.
`explicit bounded_array (size_type size)` | Allocates an initialized `bounded_array` that holds at most `size` elements.
`bounded_array (size_type size, no_init)` | Allocates an uninitialized `bounded_array` that holds at most `size` elements.
`bounded_array (const bounded_array &c)` | The copy constructor.
`~bounded_array ()` | Deallocates the `bounded_array` itself.
`void resize (size_type size, value_type init)` | Resizes a `bounded_array` to hold at most `size` elements. Element values are preserved, additional elements are assigned the value of init. Throws a `bad_size` exception if the size exeeds the bound.
`void resize (size_type size)` | Resizes a `bounded_array` to hold at most `size` elements. The elements values are undefined. Throws a `bad_size` exception if the size exeeds the bound.
`size_type size () const` | Returns the size of the `bounded_array`.
`const_reference operator [] (size_type i) const` | Returns a `const` reference of the `i` -th element.
`reference operator [] (size_type i)` | Returns a reference of the `i`-th element.
`bounded_array &operator = (const bounded_array &a)` | The assignment operator.
`bounded_array &assign_temporary (bounded_array &a)` | Assigns a temporary. May change the array `a`.
`const_iterator begin () const` | Returns a `const_iterator` pointing to the beginning of the `bounded_array`.
`const_iterator end () const` | Returns a `const_iterator` pointing to the end of the `bounded_array`.
`iterator begin ()` | Returns a `iterator` pointing to the beginning of the `bounded_array`.
`iterator end ()` | Returns a `iterator` pointing to the end of the `bounded_array`.
`const_reverse_iterator rbegin () const` | Returns a `const_reverse_iterator` pointing to the beginning of the reversed `bounded_array`.
`const_reverse_iterator rend () const` | Returns a `const_reverse_iterator` pointing to the end of the reversed `bounded_array`.
`reverse_iterator rbegin ()` | Returns a `reverse_iterator` pointing to the beginning of the reversed `bounded_array`.
`reverse_iterator rend ()` | Returns a `reverse_iterator` pointing to the end of the reversed `bounded_array`.

## Range

#### Description

The class `range` specifies a range of indicies. It can therefore be specify ranges for vectors and matrices.

#### Example

    #include <boost/numeric/ublas/storage.hpp>

    int main () {
        using namespace boost::numeric::ublas;
        range r (0, 3);
        for (unsigned i = 0; i < r.size (); ++ i) {
            std::cout << r (i) << std::endl;
        }
    }

#### Definition

Defined in the header storage.hpp.

#### Model of

Reversible Container.

#### Type requirements

None, except for those imposed by the requirements of Reversible Container.

#### Public base classes

None.

#### Members

Member | Description
--- | ---
`range (size_type start, size_type stop)` | Constructs a range of indicies from `start` to `stop (excluded)` .
`size_type start () const` | Returns the beginning of the `range`.
`size_type size () const` | Returns the size of the `range`.
`const_reference operator [] (size_type i) const` | Returns the value `start + i` of the `i` -th element.
`range compose (const range &r) const` | Returns the composite range from `start + r.start ()` to `start + r.start () + r.size ()`.
`bool operator == (const range &r) const` | Tests two ranges for equality.
`bool operator != (const range &r) const` | Tests two ranges for inequality.
`const_iterator begin () const` | Returns a `const_iterator` pointing to the beginning of the `range`.
`const_iterator end () const` | Returns a `const_iterator` pointing to the end of the `range`.
`const_reverse_iterator rbegin () const` | Returns a `const_reverse_iterator` pointing to the beginning of the reversed `range`.
`const_reverse_iterator rend () const` | Returns a `const_reverse_iterator` pointing to the end of the reversed `range`.

#### Preconditions

- `start () <= stop ()`

## Slice

#### Description

The class `range` specifies a 'slice' of indicies. It can therefore be specify slices for vectors and matrices.

#### Example

    #include <boost/numeric/ublas/storage.hpp>

    int main () {
        using namespace boost::numeric::ublas;
        slice s (0, 1, 3);
        for (unsigned i = 0; i < s.size (); ++ i) {
            std::cout << s (i) << std::endl;
        }
    }

#### Definition

Defined in the header storage.hpp.

#### Model of

Reversible Container.

#### Type requirements

None, except for those imposed by the requirements of Reversible Container.

#### Public base classes

None.

#### Members

Member | Description
--- | ---
`slice (size_type start, size_type stride, size_type size)` | Constructs a slice `start,start+stride,start+2*stride...` with `size` elements.
`size_type start () const` | Returns the beginning of the `slice`.
`size_type stride () const` | Returns the stride of the `slice`.
`size_type size () const` | Returns the size of the `slice`.
`const_reference operator [] (size_type i) const` | Returns the value `start + i * stride` of the `i`-th element.
`slice compose (const range &r) const` | Returns the composite slice from `start + stride * r.start ()` to `start + stride * (r.start () + r.size ())` with stride `stride`.
`slice compose (const slice &s) const` | Returns the composite slice from `start + stride * s.start ()` to `start + stride * s.stride () * (s.start () + s.size ())` with stride `stride * s.stride ()` .
`bool operator == (const slice &s) const` | Tests two slices for equality.
`bool operator != (const slice &s) const` | Tests two slices for inequality.
`const_iterator begin () const` | Returns a `const_iterator` pointing to the beginning of the `slice`.
`const_iterator end () const` | Returns a `const_iterator` pointing to the end of the `slice`.
`const_reverse_iterator rbegin () const` | Returns a `const_reverse_iterator` pointing to the beginning of the reversed `slice`.
`const_reverse_iterator rend () const` | Returns a `const_reverse_iterator` pointing to the end of the reversed `slice`.

#### Preconditions

- None all strides are vaild. However when an index is returned or an iterator is dereferenced its value must be representable as the size_type.

Copyright (©) 2000-2002 Joerg Walter, Mathias Koch
Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided ``as is'' without express or implied warranty, and with no claim as to its suitability for any purpose.

Last revised: 24/06/2004