diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index d2dd9bc3..04697f7f 100644 --- a/doc/Doxyfile.in +++ b/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. diff --git a/libs/main/containers/picontainers.h b/libs/main/containers/picontainers.h index c3d26743..fb364e94 100644 --- a/libs/main/containers/picontainers.h +++ b/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 -#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 class _PIReverseWrapper { public: @@ -97,6 +60,11 @@ private: C & c_; }; + +/*! \brief + * \~english Template reverse wrapper over any container + * \~russian Шаблонная функция обертки любого контейнера для обратного доступа через итераторы + */ template _PIReverseWrapper PIReverseWrap(C & c) {return _PIReverseWrapper(c);} template _PIReverseWrapper PIReverseWrap(const C & c) {return _PIReverseWrapper(c);} diff --git a/libs/main/containers/picontainersmodule.h b/libs/main/containers/picontainersmodule.h index b1682e2f..e69e5d62 100644 --- a/libs/main/containers/picontainersmodule.h +++ b/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 diff --git a/libs/main/containers/pivector.cpp b/libs/main/containers/pivector.cpp deleted file mode 100644 index 3c7a96fd..00000000 --- a/libs/main/containers/pivector.cpp +++ /dev/null @@ -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 "resize(0)" - - * \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" - - * */ diff --git a/libs/main/containers/pivector.h b/libs/main/containers/pivector.h index 52ca2e49..e8314dd8 100644 --- a/libs/main/containers/pivector.h +++ b/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 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 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 & 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> reshape(size_t rows, size_t cols, int order = byRow) const { + inline PIVector> reshape(size_t rows, size_t cols, ReshapeOrder order = byRow) const { PIVector> ret; if (isEmpty()) return ret; assert(rows*cols == piv_size); @@ -610,7 +679,7 @@ public: template>::value , int>::type = 0> - inline PIVector reshape(int order = byRow) const { + inline PIVector reshape(ReshapeOrder order = byRow) const { PIVector ret; if (isEmpty()) return ret; size_t rows = size();