From 0194e3f6b6c043da34640e5e5e3aa9c3c87c030d Mon Sep 17 00:00:00 2001 From: Andrey Date: Thu, 31 Mar 2022 17:49:18 +0300 Subject: [PATCH] PIVector doc --- libs/main/containers/pivector.h | 110 +++++++++++++++++--------------- 1 file changed, 58 insertions(+), 52 deletions(-) diff --git a/libs/main/containers/pivector.h b/libs/main/containers/pivector.h index b68602a2..6833dba2 100644 --- a/libs/main/containers/pivector.h +++ b/libs/main/containers/pivector.h @@ -50,9 +50,12 @@ //! 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. +//! To add elements you can use functions \a append() and \a insert(), +//! to remove elements you can use functions \a remove() and \a clear(). +//! Change size by function \a resize(). //! //! The storage of the vector is handled automatically, -//! being expanded and contracted as needed. +//! being expanded 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, @@ -72,9 +75,12 @@ //! но и с помощью смещений для обычных указателей на элементы. //! Это означает, что указатель на элемент вектора может передаваться в любую функцию, //! ожидающую указатель на элемент массива. +//! Добавить элементы можно с помощью функции \a append() или \a insert(), +//! а удалить с помощью \a remove() или \a clear(). +//! Изменить размер можно функцией \a resize(). //! //! Память вектора обрабатывается автоматически, -//! расширяясь и сжимаясь по мере необходимости. +//! расширяясь по мере необходимости. //! Векторы обычно занимают больше места, чем статические массивы, //! поскольку больше памяти выделяется для обработки будущего роста. //! Таким образом, память для вектора требуется выделять @@ -204,8 +210,8 @@ public: } //! \~\brief - //! \~english Reshape order enum for \a reshape function. - //! \~russian Порядок обхода для функции изменения размерности \a reshape. + //! \~english Reshape order enum for \a reshape() function. + //! \~russian Порядок обхода для функции изменения размерности \a reshape(). enum ReshapeOrder { byRow, byColumn @@ -286,10 +292,10 @@ public: //! \~russian Итератор на первый элемент. //! \~\details ![begin, end](doc/images/pivector_begin.png) //! - //! \~english If the vector is empty, the returned iterator is equal to \a end. - //! \~russian Если массив - пуст, возвращаемый итератор будет равен \a end. + //! \~english If the vector is empty, the returned iterator is equal to \a end(). + //! \~russian Если массив - пуст, возвращаемый итератор будет равен \a end(). //! \~\return \ref stl_iterators - //! \~\sa \a end, \a rbegin, \a rend + //! \~\sa \a end(), \a rbegin(), \a rend() inline iterator begin() {return iterator(this, 0);} //! \~\brief @@ -302,7 +308,7 @@ public: //! \~russian Этот элемент существует лишь условно, //! попытка доступа к нему приведёт к выходу за разрешенную память. //! \~\return \ref stl_iterators - //! \~\sa \a begin, \a rbegin, \a rend + //! \~\sa \a begin(), \a rbegin(), \a rend() inline iterator end() {return iterator(this, piv_size);} inline const_iterator begin() const {return const_iterator(this, 0);} @@ -314,12 +320,12 @@ public: //! \~\details ![rbegin, rend](doc/images/pivector_rbegin.png) //! //! \~english It corresponds to the last element of the non-reversed vector. - //! If the vector is empty, the returned iterator is equal to \a rend. + //! If the vector is empty, the returned iterator is equal to \a rend(). //! \~russian Итератор для прохода массива в обратном порядке. //! Указывает на последний элемент. - //! Если массив пустой, то совпадает с итератором \a rend. + //! Если массив пустой, то совпадает с итератором \a rend(). //! \~\return \ref stl_iterators - //! \~\sa \a rend, \a begin, \a end + //! \~\sa \a rend(), \a begin(), \a end() inline reverse_iterator rbegin() {return reverse_iterator(this, piv_size - 1);} //! \~\brief @@ -335,7 +341,7 @@ public: //! Этот элемент существует лишь условно, //! попытка доступа к нему приведёт к выходу за разрешенную память. //! \~\return \ref stl_iterators - //! \~\sa \a rbegin, \a begin, \a end + //! \~\sa \a rbegin(), \a begin(), \a end() inline reverse_iterator rend() {return reverse_iterator(this, -1);} inline const_reverse_iterator rbegin() const {return const_reverse_iterator(this, piv_size - 1);} @@ -344,19 +350,19 @@ public: //! \~\brief //! \~english Number of elements in the container. //! \~russian Количество элементов массива. - //! \~\sa \a size_s, \a capacity, \a isEmpty, \a isNotEmpty, \a resize, \a reserve + //! \~\sa \a size_s(), \a capacity(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve() inline size_t size() const {return piv_size;} //! \~\brief //! \~english Number of elements in the container as signed value. //! \~russian Количество элементов массива в виде знакового числа. - //! \~\sa \a size, \a capacity, \a isEmpty, \a isNotEmpty, \a resize, \a reserve + //! \~\sa \a size(), \a capacity(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve() inline ssize_t size_s() const {return piv_size;} //! \~\brief - //! \~english Same as \a size. - //! \~russian Синоним \a size. - //! \~\sa \a size \a size_s, \a capacity, \a isEmpty, \a isNotEmpty, \a resize, \a reserve + //! \~english Same as \a size(). + //! \~russian Синоним \a size(). + //! \~\sa \a size(), \a size_s(), \a capacity(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve() inline size_t length() const {return piv_size;} //! \~\brief @@ -365,7 +371,7 @@ public: //! \~\details //! \~english To find out the actual number of items, use the function \a size(). //! \~russian Чтобы узнать фактическое количество элементов используйте функцию \a size(). - //! \~\sa \a reserve, \a size \a size_s + //! \~\sa \a reserve(), \a size(), \a size_s() inline size_t capacity() const {return piv_rsize;} //! \~\brief @@ -374,7 +380,7 @@ public: //! \~\return //! \~english **true** if the container is empty, **false** otherwise //! \~russian **true** если контейнер пуст, **false** иначе. - //! \~\sa \a size \a size_s, \a isEmpty, \a isNotEmpty, \a resize, \a reserve + //! \~\sa \a size(), \a size_s(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve() inline bool isEmpty() const {return (piv_size == 0);} //! \~\brief @@ -383,7 +389,7 @@ public: //! \~\return //! \~english **true** if the container is not empty, **false** otherwise //! \~russian **true** если контейнер не пуст, **false** иначе. - //! \~\sa \a size \a size_s, \a isEmpty, \a isNotEmpty, \a resize, \a reserve + //! \~\sa \a size(), \a size_s(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve() inline bool isNotEmpty() const {return (piv_size > 0);} //! \~\brief @@ -404,7 +410,7 @@ public: //! piCout << v.any([](int e){return e % 2 == 0;}); // true //! piCout << v.any([](int e){return e == 3;}); // false //! \endcode - //! \~\sa \a every, \a contains, \a etries, \a forEach + //! \~\sa \a every(), \a contains(), \a etries(), \a forEach() inline bool any(std::function test) const { for (size_t i = 0; i < piv_size; ++i) { if (test(piv_data[i])) return true; @@ -430,7 +436,7 @@ public: //! piCout << v.every([](int e){return e % 2 == 0;}); // false //! piCout << v.every([](int e){return e > 0;}); // true //! \endcode - //! \~\sa \a any, \a contains, \a entries, \a forEach + //! \~\sa \a any(), \a contains(), \a entries(), \a forEach() inline bool every(std::function test) const { for (size_t i = 0; i < piv_size; ++i) { if (!test(piv_data[i])) return false; @@ -454,7 +460,7 @@ public: //! v[2] = 5; //! piCout << v; // 1, 2, 5, 9 //! \endcode - //! \~\sa \a at + //! \~\sa \a at() inline T & operator [](size_t index) {return piv_data[index];} inline const T & operator [](size_t index) const {return piv_data[index];} @@ -548,7 +554,7 @@ public: //! otherwise it returns **false**. //! \~russian **true** если элемент `e` присутствует в массиве, //! в остальных случаях **false**. - //! \~\sa \a every, \a any, \a etries, \a forEach + //! \~\sa \a every(), \a any(), \a etries(), \a forEach() inline bool contains(const T & e, ssize_t start = 0) const { if (start < 0) { start = piv_size + start; @@ -585,7 +591,7 @@ public: //! piCout << v.entries(2, 2); // 1 //! piCout << v.entries(2, -4); // 2 //! \endcode - //! \~\sa \a every, \a any, \a contains, \a forEach, \a indexOf + //! \~\sa \a every(), \a any(), \a contains(), \a forEach(), \a indexOf() inline int entries(const T & e, ssize_t start = 0) const { int ec = 0; if (start < 0) { @@ -620,7 +626,7 @@ public: //! Если рассчитанный индекс все равно оказывается меньше 0, просматривается весь массив. //! Обратите внимание: если индекс отрицателен, массив всё равно просматривается от начала к концу. //! Значение по умолчанию равно 0, что означает, что просматривается весь массив. - //! \~\sa \a every, \a any, \a contains, \a forEach, \a indexWhere + //! \~\sa \a every(), \a any(), \a contains(), \a forEach(), \a indexWhere() inline int entries(std::function test, ssize_t start = 0) const { int ec = 0; if (start < 0) { @@ -662,7 +668,7 @@ public: //! piCout << v.indexOf(2, -1); // -1 //! piCout << v.indexOf(2, -3); // 0 //! \endcode - //! \~\sa \a indexWhere, \a lastIndexOf, \a lastIndexWhere, \a contains + //! \~\sa \a indexWhere(), \a lastIndexOf(), \a lastIndexWhere(), \a contains() inline ssize_t indexOf(const T & e, ssize_t start = 0) const { if (start < 0) { start = piv_size + start; @@ -702,7 +708,7 @@ public: //! piCout << v.indexWhere([](const PIString & s){return s.startsWith('r');}, 2); // 3 //! piCout << v.indexWhere([](const PIString & s){return s.startsWith('k');}); // -1 //! \endcode - //! \~\sa \a indexOf, \a lastIndexOf, \a lastIndexWhere, \a contains + //! \~\sa \a indexOf(), \a lastIndexOf(), \a lastIndexWhere(), \a contains() inline ssize_t indexWhere(std::function test, ssize_t start = 0) const { if (start < 0) { start = piv_size + start; @@ -748,7 +754,7 @@ public: //! piCout << v.lastIndexOf(2, -300); // -1 //! piCout << v.lastIndexOf(2, 300); // 3 //! \endcode - //! \~\sa \a indexOf, \a indexWhere, \a lastIndexWhere, \a contains + //! \~\sa \a indexOf(), \a indexWhere(), \a lastIndexWhere(), \a contains() inline ssize_t lastIndexOf(const T & e, ssize_t start = -1) const { if (start >= size_s()) start = piv_size - 1; if (start < 0) start = piv_size + start; @@ -783,7 +789,7 @@ public: //! Если рассчитанный индекс оказывается меньше 0, массив даже не просматривается. //! Значение по умолчанию равно `-1`, что равно индексу последнего элемента //! и означает, что просматривается весь массив. - //! \~\sa \a indexOf, \a lastIndexOf, \a indexWhere, \a contains + //! \~\sa \a indexOf(), \a lastIndexOf(), \a indexWhere(), \a contains() inline ssize_t lastIndexWhere(std::function test, ssize_t start = -1) const { if (start >= size_s()) start = piv_size - 1; if (start < 0) start = piv_size + start; @@ -858,7 +864,7 @@ public: //! \~\details //! \~english Note: reserved memory will not be released. //! \~russian Замечание: зарезервированная память не освободится. - //! \~\sa \a resize + //! \~\sa \a resize() template::value , int>::type = 0> @@ -884,7 +890,7 @@ public: //! v.fill(7); //! piCout << v; // 7, 7, 7 //! \endcode - //! \~\sa \a resize + //! \~\sa \a resize() inline PIVector & fill(const T & f = T()) { deleteT(piv_data, piv_size); PIINTROSPECTION_CONTAINER_USED(T, piv_size) @@ -903,7 +909,7 @@ public: //! v.fill([](size_t i){return i*2;}); //! piCout << v; // 0, 2, 4 //! \endcode - //! \~\sa \a resize + //! \~\sa \a resize() inline PIVector & fill(std::function f) { deleteT(piv_data, piv_size); PIINTROSPECTION_CONTAINER_USED(T, piv_size) @@ -914,16 +920,16 @@ public: } //! \~\brief - //! \~english Same as \a fill. - //! \~russian Тоже самое что и \a fill. - //! \~\sa \a fill, \a resize + //! \~english Same as \a fill(). + //! \~russian Тоже самое что и \a fill(). + //! \~\sa \a fill(), \a resize() inline PIVector & assign(const T & f = T()) {return fill(f);} //! \~\brief //! \~english First does `resize(new_size)` then `fill(f)`. //! \~russian Сначала делает `resize(new_size)` затем `fill(f)`. - //! \~\sa \a fill, \a resize + //! \~\sa \a fill(), \a resize() template::value , int>::type = 0> @@ -943,14 +949,14 @@ public: //! \~english Sets size of the array, new elements are copied from `f`. //! \~russian Устанавливает размер массива, новые элементы копируются из `f`. //! \~\details - //! \~english If `new_size` is greater than the current \a size, + //! \~english If `new_size` is greater than the current \a size(), //! elements are added to the end; the new elements are initialized from `f`. - //! If `new_size` is less than the current \a size, elements are removed from the end. - //! \~russian Если `new_size` больше чем текущий размер массива \a size, + //! If `new_size` is less than the current \a size(), elements are removed from the end. + //! \~russian Если `new_size` больше чем текущий размер массива \a size(), //! новые элементы добавляются в конец массива и создаются из `f`. - //! Если `new_size` меньше чем текущий размер массива \a size, + //! Если `new_size` меньше чем текущий размер массива \a size(), //! лишние элементы удаляются с конца массива. - //! \~\sa \a size, \a clear + //! \~\sa \a size(), \a clear() inline PIVector & resize(size_t new_size, const T & f = T()) { if (new_size < piv_size) { T * de = &(piv_data[new_size]); @@ -972,14 +978,14 @@ public: //! \~english Sets size of the array, new elements created by function `f(size_t i)`. //! \~russian Устанавливает размер массива, новые элементы создаются функцией `f(size_t i)`. //! \~\details - //! \~english If `new_size` is greater than the current \a size, + //! \~english If `new_size` is greater than the current \a size(), //! elements are added to the end; the new elements created by function `f(size_t i)`. - //! If `new_size` is less than the current \a size, elements are removed from the end. - //! \~russian Если `new_size` больше чем текущий размер массива \a size, + //! If `new_size` is less than the current \a size(), elements are removed from the end. + //! \~russian Если `new_size` больше чем текущий размер массива \a size(), //! новые элементы добавляются в конец массива и функцией `f(size_t i)`. - //! Если `new_size` меньше чем текущий размер массива \a size, + //! Если `new_size` меньше чем текущий размер массива \a size(), //! лишние элементы удаляются с конца массива. - //! \~\sa \a size, \a clear + //! \~\sa \a size(), \a clear() inline PIVector & resize(size_t new_size, std::function f) { if (new_size < piv_size) { T * de = &(piv_data[new_size]); @@ -1021,15 +1027,15 @@ public: //! \~\details //! \~english If you know in advance how large the array will be, //! you should call this function to prevent reallocations and memory fragmentation. - //! If `new_size` is greater than the current \a capacity, + //! If `new_size` is greater than the current \a capacity(), //! new storage is allocated, otherwise the function does nothing. - //! This function does not change the \a size of the array. + //! This function does not change the \a size() of the array. //! \~russian Если вы заранее знаете, насколько велик будет массив, //! вы можете вызвать эту функцию, чтобы предотвратить перераспределение и фрагментацию памяти. - //! Если размер `new_size` больше чем выделенная память \a capacity, + //! Если размер `new_size` больше чем выделенная память \a capacity(), //! то произойдёт выделение новой памяти и перераспределение массива. - //! Эта функция не изменяет количество элементов в массиве \a size. - //! \~\sa \a size, \a capacity, \a resize + //! Эта функция не изменяет количество элементов в массиве \a size(). + //! \~\sa \a size(), \a capacity(), \a resize() inline PIVector & reserve(size_t new_size) { if (new_size <= piv_rsize) return *this; size_t os = piv_size;