start PIVector doc

doc/Doxyfile.in

@@ -158,7 +158,7 @@ INLINE_INHERITED_MEMB  = NO
 # shortest path that makes the file name unique will be used
 # The default value is: YES.
 
-FULL_PATH_NAMES        = YES
+FULL_PATH_NAMES        = NO
 
 # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
 # Stripping is only done if one of the specified strings matches the left-hand
@@ -368,7 +368,7 @@ AUTOLINK_SUPPORT       = YES
 # diagrams that involve STL classes more complete and accurate.
 # The default value is: NO.
 
-BUILTIN_STL_SUPPORT    = NO
+BUILTIN_STL_SUPPORT    = YES
 
 # If you use Microsoft's C++/CLI language, you should set this option to YES to
 # enable parsing support.
@@ -624,7 +624,7 @@ SHOW_INCLUDE_FILES     = NO
 # which file to include in order to use the member.
 # The default value is: NO.
 
-SHOW_GROUPED_MEMB_INC  = NO
+SHOW_GROUPED_MEMB_INC  = YES
 
 # If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include
 # files with double quotes in the documentation rather than with sharp brackets.

libs/main/containers/picontainers.h

@@ -1,7 +1,7 @@
 /*! \addtogroup Containers
  * \{
  * \file picontainers.h
- * \~\brief
+ * \brief
  * \~english Base macros for generic containers
  * \~russian Базовые макросы для контейнеров
  * \~\authors
@@ -47,43 +47,6 @@
 #include <new>
 
 
-#if 0
-
-/*!\brief Macro for iterate any container
- * \details Use this macros instead of standard "for"
- * to get read/write access to each element of container.
- * Pass direction is direct \n
- * Example: \snippet picontainers.cpp foreach
- */
-#  define piForeach(i,c)
-
-/*!\brief Macro for iterate any container only for read
- * \details Use this macros instead of standard "for"
- * to get read access to each element of container.
- * Pass direction is direct \n
- * Example: \snippet picontainers.cpp foreachC
- */
-#  define piForeachC(i,c)
-
-/*!\brief Macro for iterate any container with reverse direction
- * \details Use this macros instead of standard "for"
- * to get read/write access to each element of container.
- * Pass direction is reverse \n
- * Example: \snippet picontainers.cpp foreachR
- */
-#  define piForeachR(i,c)
-
-/*!\brief Macro for iterate any container only for read with reverse direction
- * \details Use this macros instead of standard "for"
- * to get read access to each element of container.
- * Pass direction is reverse \n
- * Example: \snippet picontainers.cpp foreachCR
- */
-#  define piForeachCR(i,c)
-
-#endif
-
-
 template <typename C>
 class _PIReverseWrapper {
 public:
@@ -97,6 +60,11 @@ private:
 	C & c_;
 };
 
+
+/*! \brief
+ * \~english Template reverse wrapper over any container
+ * \~russian Шаблонная функция обертки любого контейнера для обратного доступа через итераторы
+ */
 template <typename C> _PIReverseWrapper<C> PIReverseWrap(C & c) {return _PIReverseWrapper<C>(c);}
 template <typename C> _PIReverseWrapper<C> PIReverseWrap(const C & c) {return _PIReverseWrapper<C>(c);}
 

libs/main/containers/picontainersmodule.h

@@ -1,6 +1,6 @@
 /*
 	PIP - Platform Independent Primitives
-	Module includes
+	Containers
 	Ivan Pelipenko peri4ko@yandex.ru, Andrey Bychkov work.a.b@yandex.ru
 
 	This program is free software: you can redistribute it and/or modify
@@ -18,14 +18,20 @@
 */
 /** \defgroup Containers
  * \~\brief
- * This module contains various standart containers realization.
+ * \~english This module contains various standart containers realization.
  * \~russian Модуль содержит основные классы контейнеров.
  * \~\details
  * \~english This includes
  * \~russian В него входят
  * \~ \a PIVector, \a PIDeque, \a PIMap, \a PISet,
- *  \a PIStack, \a PIQueue, \a PIVector2D.
+ *  \a PIStack, \a PIQueue, \a PIPair, \a PIVector2D.
- *
+ * \authors
+ * \~english
+ * Ivan Pelipenko peri4ko@yandex.ru;
+ * Andrey Bychkov work.a.b@yandex.ru;
+ * \~russian
+ * Иван Пелипенко peri4ko@yandex.ru;
+ * Андрей Бычков work.a.b@yandex.ru;
 */
 #ifndef PICONTAINERSMODULE_H
 #define PICONTAINERSMODULE_H

libs/main/containers/pivector.cpp

@@ -1,170 +0,0 @@
-/** \class PIVector
- * \brief Dynamic array of any type
- * \details This class used to store dynamic array of any
- * type of data. In memory data stored linear. You can insert
- * item in any place of remove some items from any place.
- * For quick add elements this is stream operator <<.
-
- * \fn PIVector::PIVector();
- * Contructs an empty vector
-
- * \fn PIVector::PIVector(size_t size, const T & value = T());
- * \brief Contructs vector with size "size" filled elements "value"
- * \details Example: \snippet picontainers.cpp PIVector::PIVector
-
- * \fn PIVector::PIVector(std::initializer_list list);
- * \brief Contructs vector from C++11 initializer list
- * \details Example: \snippet picontainers.cpp PIVector::PIVector
-
- * \fn const T & PIVector::at(size_t index) const;
- * \brief Read-only access to element by index "index"
- * \details Example: \snippet picontainers.cpp PIVector::at_c
- * \sa \a operator[]
-
- * \fn T & PIVector::at(size_t index);
- * \brief Full access to element by index "index"
- * \details Example: \snippet picontainers.cpp PIVector::at
- * \sa \a operator[]
-
- * \fn const T * PIVector::data(size_t index = 0) const;
- * \brief Read-only pointer to element by index "index"
- * \details Example: \snippet picontainers.cpp PIVector::data_c
-
- * \fn T * PIVector::data(size_t index = 0);
- * \brief Pointer to element by index "index"
- * \details Example: \snippet picontainers.cpp PIVector::data
-
- * \fn size_t PIVector::size() const;
- * \brief Elements count
-
- * \fn ssize_t PIVector::size_s() const;
- * \brief Elements count
-
- * \fn bool PIVector::isEmpty() const;
- * \brief Return \c "true" if vector is empty, i.e. size = 0
-
- * \fn bool PIVector::has(const T & t) const;
-
- * \fn bool PIVector::contains(const T & v) const;
- * \brief Return \c "true" if vector has at least one element equal "t"
-
- * \fn int PIVector::etries(const T & t) const;
- * \brief Return how many times element "t" appears in vector
-
- * \fn ssize_t PIVector::indexOf(const T & t) const;
- * \brief Return index of first element equal "t" or -1 if there is no such element
-
- * \fn ssize_t PIVector::lastIndexOf(const T & t) const;
- * \brief Return index of last element equal "t" or -1 if there is no such element
-
- * \fn static int PIVector::compare_func(const T * t0, const T * t1);
- * \brief Standard compare function for type "T". Return  0 if t0 = t1,  -1 if t0 < t1  and  1 if t0 > t1.
-
- * \fn void PIVector::resize(size_t size, const T & new_type = T());
- * \brief Resize vector to size "size"
- * \details Elements removed from end of vector if new size < old size, or added new elements = "new_type" if new size > old size.\n
- * Example: \snippet picontainers.cpp PIVector::resize
- * \sa \a size(), \a clear()
-
- * \fn PIVector & PIVector::enlarge(size_t size);
- * \brief Increase vector size with "size" elements
-
- * \fn void PIVector::clear();
- * \brief Clear vector. Equivalent to call <tt>"resize(0)"</tt>
-
- * \fn PIVector & PIVector::sort(CompareFunc compare = compare_func);
- * \brief Sort vector using quick sort algorithm and standard compare function
- * \details Example: \snippet picontainers.cpp PIVector::sort_0
- * With custom compare function: \snippet picontainers.cpp PIVector::sort_1
-
- * \fn PIVector & PIVector::fill(const T & t);
- * \brief Fill vector with elements "t" leave size is unchanged and return reference to vector
- * \details Example: \snippet picontainers.cpp PIVector::fill
-
- * \fn PIVector & PIVector::assign(const T & t = T());
- * \brief Synonym of \a fill(t)
-
- * \fn PIVector & PIVector::assign(size_t new_size, const T & t);
- * \brief Resize to "new_size", then fill with "t"
-
- * \fn T & PIVector::back();
- * \brief Last element of the vector
-
- * \fn const T & PIVector::back() const;
- * \brief Last element of the vector
-
- * \fn T & PIVector::front();
- * \brief First element of the vector
-
- * \fn const T & PIVector::front() const;
- * \brief First element of the vector
-
- * \fn PIVector & PIVector::push_back(const T & t);
- * \brief Add new element "t" at the end of vector and return reference to vector
-
- * \fn PIVector & PIVector::push_front(const T & t);
- * \brief Add new element "t" at the beginning of vector and return reference to vector
-
- * \fn PIVector & PIVector::pop_back();
- * \brief Remove one element from the end of vector and return reference to vector
-
- * \fn PIVector & PIVector::pop_front();
- * \brief Remove one element from the beginning of vector and return reference to vector
-
- * \fn T PIVector::take_back();
- * \brief Remove one element from the end of vector and return it
-
- * \fn T PIVector::take_front();
- * \brief Remove one element from the beginning of vector and return it
-
- * \fn PIVector & PIVector::remove(size_t index);
- * \brief Remove one element by index "index" and return reference to vector
- * \details Example: \snippet picontainers.cpp PIVector::remove_0
- * \sa \a removeOne(), \a removeAll()
-
- * \fn PIVector & PIVector::remove(size_t index, size_t count);
- * \brief Remove "count" elements by first index "index" and return reference to vector
- * \details Example: \snippet picontainers.cpp PIVector::remove_1
- * \sa \a removeOne(), \a removeAll()
-
- * \fn PIVector & PIVector::removeOne(const T & v);
- * \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()
-
- * \fn PIVector & PIVector::removeAll(const T & v);
- * \brief Remove all elements equal "v" and return reference to vector
- * \details Example: \snippet picontainers.cpp PIVector::removeAll
- * \sa \a remove(), \a removeOne()
-
- * \fn PIVector & PIVector::insert(size_t pos, const T & t);
- * \brief Insert element "t" after index "pos" and return reference to vector
- * \details Example: \snippet picontainers.cpp PIVector::insert_0
-
- * \fn PIVector & PIVector::insert(size_t pos, const PIVector & t);
- * \brief Insert other vector "t" after index "pos" and return reference to vector
- * \details Example: \snippet picontainers.cpp PIVector::insert_1
-
- * \fn T & PIVector::operator [](size_t index);
- * \brief Full access to element by index "index"
- * \details Example: \snippet picontainers.cpp PIVector::()
- * \sa \a at()
-
- * \fn const T & PIVector::operator [](size_t index) const;
- * \brief Read-only access to element by index "index"
- * \details Example: \snippet picontainers.cpp PIVector::()_c
- * \sa \a at()
-
- * \fn PIVector & PIVector::operator <<(const T & t);
- * \brief Add new element "t" at the end of vector and return reference to vector
-
- * \fn PIVector & PIVector::operator <<(const PIVector & t);
- * \brief Add vector "t" at the end of vector and return reference to vector
-
- * \fn bool PIVector::operator ==(const PIVector & t);
- * \brief Compare with vector "t"
-
- * \fn bool PIVector::operator !=(const PIVector & t);
- * \brief Compare with vector "t"
-
- * */

libs/main/containers/pivector.h

@@ -1,11 +1,20 @@
-/*! \file pivector.h
+/*! \addtogroup Containers
- * \brief Dynamic array of any type
+ * \{
- *
+ * \file pivector.h
- * This file declares PIVector
+ * \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();