start PIVector doc

libs/main/containers/pivector.h

@@ -1,11 +1,20 @@
-/*! \file pivector.h
- * \brief Dynamic array of any type
- *
- * This file declares PIVector
-*/
+/*! \addtogroup Containers
+ * \{
+ * \file pivector.h
+ * \brief
+ * \~english Declares \a PIVector
+ * \~russian Объявление \a PIVector
+ * \~\authors
+ * \~english
+ * Ivan Pelipenko peri4ko@yandex.ru;
+ * Andrey Bychkov work.a.b@yandex.ru;
+ * \~russian
+ * Иван Пелипенко peri4ko@yandex.ru;
+ * Андрей Бычков work.a.b@yandex.ru;
+ * \~\} */
 /*
 	PIP - Platform Independent Primitives
-	Dynamic array of any type
+	Sequence linear container aka dynamic size array of any type
 	Ivan Pelipenko peri4ko@yandex.ru, Andrey Bychkov work.a.b@yandex.ru
 
 	This program is free software: you can redistribute it and/or modify
@@ -27,13 +36,70 @@
 
 #include "picontainers.h"
 
-
+/*! \addtogroup Containers
+ * \{
+ * \class PIVector pivector.h
+ * \brief
+ * \~english Sequence linear container - dynamic size array of any type
+ * \~russian Последовательный контейнер с линейной памятью - динамический массив любого типа
+ * \~\}
+ * \details
+ * \~english
+ * The elements are stored contiguously,
+ * which means that elements can be accessed not only through iterators,
+ * but also using offsets to regular pointers to elements.
+ * This means that a pointer to an element of a vector may be passed to any function
+ * that expects a pointer to an element of an array.
+ *
+ * The storage of the vector is handled automatically,
+ * being expanded and contracted as needed.
+ * Vectors usually occupy more space than static arrays,
+ * because more memory is allocated to handle future growth.
+ * This way a vector does not need to reallocate each time an element is inserted,
+ * but only when the additional memory is exhausted.
+ * The total amount of allocated memory can be queried using \a capacity() function.
+ * Reallocations are usually costly operations in terms of performance.
+ * The \a reserve() function can be used to eliminate reallocations
+ * if the number of elements is known beforehand.
+ *
+ * The complexity (efficiency) of common operations on vectors is as follows:
+ * - Random access - constant 𝓞(1)
+ * - Insertion or removal of elements at the end - amortized constant 𝓞(1)
+ * - Insertion or removal of elements - linear in the distance to the end of the vector 𝓞(n)
+ *
+ * \~russian
+ * Элементы хранятся непрерывно, а значит доступны не только через итераторы,
+ * но и с помощью смещений для обычных указателей на элементы.
+ * Это означает, что указатель на элемент вектора может передаваться в любую функцию,
+ * ожидающую указатель на элемент массива.
+ *
+ * Память вектора обрабатывается автоматически,
+ * расширяясь и сжимаясь по мере необходимости.
+ * Векторы обычно занимают больше места, чем статические массивы,
+ * поскольку больше памяти выделяется для обработки будущего роста.
+ * Таким образом, память для вектора требуется выделять
+ * не при каждой вставке элемента,
+ * а только после исчерпания дополнительной памяти.
+ * Общий объём выделенной памяти можно получить с помощью функции \a capacity().
+ *
+ * Выделение памяти обычно является дорогостоящей операцией
+ * с точки зрения производительности.
+ * Функцию \a reserve() можно использовать для исключения выделения памяти,
+ * если количество элементов известно заранее.
+ *
+ * Сложность (эффективность) обычных операций над векторами следующая:
+ * - Произвольный доступ — постоянная 𝓞(1)
+ * - Вставка и удаление элементов в конце — амортизированная постоянная 𝓞(1)
+ * - Вставка и удаление элементов — линейная по расстоянию до конца вектора 𝓞(n)
+ */
 template <typename T>
 class PIVector {
 public:
+	//! Contructs an empty vector
 	inline PIVector(): piv_data(0), piv_size(0), piv_rsize(0) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
 	}
+	//! \brief Contructs vector with size "size" filled elements "value"
 	inline PIVector(const T * data, size_t size): piv_data(0), piv_size(0), piv_rsize(0) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
 		alloc(size);
@@ -44,6 +110,7 @@ public:
 		alloc(v.piv_size);
 		newT(piv_data, v.piv_data, piv_size);
 	}
+	//! \brief Contructs vector from C++11 initializer list
 	inline PIVector(std::initializer_list<T> init_list): piv_data(0), piv_size(0), piv_rsize(0) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
 		alloc(init_list.size());
@@ -83,8 +150,6 @@ public:
 		return *this;
 	}
 
-	typedef T value_type;
-
 	enum ReshapeOrder {
 		byRow,
 		byColumn
@@ -463,6 +528,10 @@ public:
 		return *this;
 	}
 
+/*! \brief Remove no more than one element equal "v" and return reference to vector
+* \details Example: \snippet picontainers.cpp PIVector::removeOne
+* \sa \a remove(), \a removeAll()
+*/
 	inline PIVector<T> & removeOne(const T & e) {
 		for (size_t i = 0; i < piv_size; ++i) {
 			if (piv_data[i] == e) {
@@ -586,7 +655,7 @@ public:
 		return ret;
 	}
 
-	inline PIVector<PIVector<T>> reshape(size_t rows, size_t cols, int order = byRow) const {
+	inline PIVector<PIVector<T>> reshape(size_t rows, size_t cols, ReshapeOrder order = byRow) const {
 		PIVector<PIVector<T>> ret;
 		if (isEmpty()) return ret;
 		assert(rows*cols == piv_size);
@@ -610,7 +679,7 @@ public:
 	template<typename C, typename std::enable_if<
 				 std::is_same<T, PIVector<C>>::value
 				 , int>::type = 0>
-	inline PIVector<C> reshape(int order = byRow) const {
+	inline PIVector<C> reshape(ReshapeOrder order = byRow) const {
 		PIVector<C> ret;
 		if (isEmpty()) return ret;
 		size_t rows = size();