##CIRCULAR_VECTOR## A STL-Compliant Circular Vector (Container) Data Structure written in C++

Shares similaries to a Circular Buffer Data Structure, except allows access to all elements in the container.

Contains all the same member functions as C++98 std::vector from the STL, except for vector::insert and vector::erase. Newly introduced member functions include: push_front and pop_front which unlike the counterpart operations in std::vector are O(1) time (Constant).

##CONSTRUCTORS:##

circular_vector::circular_vector

explicit circular_vector(size_type capacity = kDefaultCapacity);

@brief

Empty container constructor (default constructor). Constructs an empty container, with no elements. With a specified amount of reserved space.

@param capacity

The starting allocated storage reserve

@throws std::invalid_argument

With negative capacity values

circular_vector::circular_vector

explicit circular_vector(size_type n, const value_type &val, const allocator_type &alloc = allocator_type());

@brief

Fill constructor. Constructs a container with @a n elements. Each element is a copy of @a val.

@param n

The size and capacity of the %circular_vector

@param val

The data value to fill the %circular_vector

@throws std::invalid_argument

With negative size values

circular_vector::circular_vector

template <class InputIterator>; circular_vector(InputIterator first, InputIterator last, const allocator_type& alloc = allocator_type());

@brief

Range constructor. Constructs a container with as many elements as the range [first,last), with each element constructed from its corresponding element in that range, in the same order.

@param first

The initial position to start the copy from

@param last

The final exclusive position of the copy range

circular_vector::circular_vector

circular_vector(const circular_vector &x);

@brief

Copy constructor. Constructs a container with a copy of each of the elements in x, in the same order.

@param x

Another vector object of the same type (with the same class template arguments T and Alloc), whose contents are copied.

@throws std::length_error

Upon catching any exception while assigning memory

circular_vector::operator=

circular_vector &operator = (const self_type &x);;

@brief

Move constructor. Assigns new contents to the container, replacing its current contents, and modifying its size accordingly.

@param x

A vector object of the same type (i.e., with the same template parameters, T and Alloc).

##DESTRUCTORS:##

circular_vector::~circular_vector

@brief

Destroys all container elements, and deallocates all the storage capacity allocated by the vector using its allocator.

##ITERATORS:##

circular_vector::begin

          iterator begin();

`const_iterator begin() const;`

@brief

An iterator pointing to array\_[0], i.e. the first element

@warn

Iterator should be repositioned upon capacity reallocation or after push_front call

circular_vector::end

          iterator end();

`const_iterator end() const;`

@brief

An iterator pointing to array\_[size()], i.e. past-the-end element

@warn

Iterator should be repositioned upon capacity reallocation or after push_back call

circular_vector::rbegin

          reverse_iterator rbegin();

`const_reverse_iterator rbegin() const;`

@brief

Returns a reverse iterator pointing to the last element in the vector (i.e., its reverse beginning). Reverse iterators iterate backwards: increasing them moves them towards the beginning of the container. rbegin points to the element right before the one that would be pointed to by member end. Notice that unlike member vector::back, which returns a reference to this same element, this function returns a reverse random access iterator.

@warn

Iterator should be repositioned upon capacity reallocation or after push_back call

circular_vector::rend

          reverse_iterator rend();

`const_reverse_iterator rend() const;`

@brief

Returns a reverse iterator pointing to the theoretical element preceding the first element in the vector (which is considered its reverse end). The range between vector::rbegin and vector::rend contains all the elements of the vector (in reverse order).

@warn

Iterator should be repositioned upon capacity reallocation or after push_front call

##ALLOCATORS:##

circular_vector::get_allocator

allocator_type get_allocator() const;

@brief

Returns a copy of the allocator object associated with the @circular_vector

@return

Read-only (constant) allocator

##CAPACITIES:##

circular_vector::size

size_type size() const;

@brief

Returns the amount of elements in the %circular_vector

@return

Read-only (constant) circular size

circular_vector::max_size

size_type max_size() const;

@brief

Returns the maximum number of elements that the %circular_vector can hold during dynamic allocation mode

@return

Read-only (constant) maximum size

circular_vector::resize

void resize(size_type n, const value_type &val = value_type());

@brief

Resizes the %circular_vector to specified size

@param n

Number of elements the %circular_vector should contain.

@param val

The value of the element to fill the extra size

@warn

This function changes the actual content of the container by inserting or erasing elements from it (unless @a n = size()). If the number is smaller than the %circular_vector's current size the %circular_vector is truncated, otherwise default (or specified) elements are appended until size reaches @a n size. If capacity needs to increase => capacity becomes @a n. Capacity never shrinks.

circular_vector::capacity

size_type capacity() const;

@brief

Returns size of allocated storage capacity

circular_vector::empty

bool empty() const;

@brief

Returns true if there are elements in the %circular_vector

@return

Read-only (constant) True iff end index is in default state

circular_vector::reserve

void reserve(size_type n);

@brief

Request that the %circular_vector capacity be at least enough to contain @a n elements. This function has no effect on the %circular_vector size and cannot alter its elements.

@warn

If @a n is greater than the current %circular_vector capacity, the function causes the container to reallocate its storage increasing its capacity to @a n (or greater). O(n) time and space required when this occurs

##MODIFIERS:##

circular_vector::assign

template <typename iter> void assign(iter start, iter last);

@brief

Fills a %circular_vector with copies of the elements in the range \[start, last)

@param start

An input iterator

@param last

An input iterator

@warn

The assignment completely changes the %circular_vector and the resulting %circular_vector's size is the same as the number of elements assigned. Old data will be lost.

circular_vector::assign

@brief

Fills a %circular_vector with the specified value in the range \[0, n)

@param n

Number of elements to be assigned

@param val

Value to be assigned

@warn

The assignment completely changes the %circular_vector and the resulting %circular_vector's size is the same as the number of elements assigned. Old data will be lost.

`void assign(size_type n, const value_type &val);`

circular_vector::pop_front

void pop_front();

@brief

Removes the first indexed element

@warn

Undefined behaviour when calling on an empty %circular_vector

circular_vector::pop_back

void pop_back();

@brief

Removes the last indexed element

@warn

Undefined behaviour when calling on an empty %circular_vector

circular_vector::push_front

void push_front(const value_type &val);

@brief

Adds an element to the head of the %circular_vector and decrements the start index

@param val

Element to be added

@warn

If capacity has been reached, the function causes the container to reallocate its storage increasing its capacity to 1.5 * capacity. O(n) time and space required when this occurs.

circular_vector::push_back

void push_back(const value_type &val);

@brief

Adds an element to the tail of the %circular_vector

@param val

Element to be added

@warn

If capacity has been reached, the function causes the container to reallocate its storage increasing its capacity to 1.5 * capacity. O(n) time and space required when this occurs.

circular_vector::swap

void swap(circular_vector &x);

@brief

Exchanges the content of the container by the content of x, which is another %circular_vector object of the same type. Sizes may differ.

@param x

The %circular_vector of the same type to swap with.

circular_vector::clear

void clear();

@brief

Removes all elements from the @circular_vector (which are destroyed), leaving the container with a size of 0.

@warn

If the elements themselves are pointers, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibility.

##ELEMENT ACCESS:##

circular_vector::operator[]

reference operator [] (size_type n);

@brief

Provides access to the data contained in %circular_vector

@param n

The index of the element for which data should be accessed

@return

Read/write reference to data

@warn

Calling this function with an argument @a n that is out of range causes undefined behaviour.

circular_vector::operator[]

const_reference operator [] (size_type n) const;

@brief

Provides access to the data contained in %circular_vector

@param n

The index of the element for which data should be accessed

@return

Read/write reference to data

@warn

Calling this function with an argument @a n that is out of range causes undefined behaviour

circular_vector::at

reference at(size_type n);

@brief

Provides access to the data contained in %circular_vector

@param n

The index of the element for which data should be accessed

@return

Read/write reference to data

@throw std::out_of_range

If @a n is an invalid index

circular_vector::at

const_reference at(size_type n) const;

@brief

Provides access to the data contained in %circular_vector

@param n

The index of the element for which data should be accessed

@return

Read-only (constant) reference to data

@throw std::out_of_range

If @a n is an invalid index

circular_vector::front

reference front();

@return

Read/Write reference to the first indexed element in %circular_vector

@warn

Calling this function on an empty container causes undefined behaviour

circular_vector::front

const_reference front() const;

@return

Read-only (constant) reference to the first indexed element in %circular_vector

@warn

Calling this function on an empty container causes undefined behaviour

circular_vector::back

reference back();

@return

Read/Write reference to the last indexed element in %circular_vector

@warn

Calling this function on an empty container causes undefined behaviour

circular_vector::back

const_reference back() const;

@return

Read-only (constant) reference to the last indexed element in %circular_vector

@warn

Calling this function on an empty container causes undefined behaviour