From 7ab16b641d574e3e66b591ac361984cdf073a9a2 Mon Sep 17 00:00:00 2001 From: Andrey Date: Thu, 31 Mar 2022 13:28:18 +0300 Subject: [PATCH] PIVector doc --- libs/main/containers/picontainersmodule.h | 2 + libs/main/containers/pivector.h | 204 +++++++++++++++++++--- 2 files changed, 185 insertions(+), 21 deletions(-) diff --git a/libs/main/containers/picontainersmodule.h b/libs/main/containers/picontainersmodule.h index aaf1e446..a0a93487 100644 --- a/libs/main/containers/picontainersmodule.h +++ b/libs/main/containers/picontainersmodule.h @@ -31,6 +31,7 @@ //! \~ \a PIVector, \a PIDeque, \a PIMap, \a PISet, //! \a PIStack, \a PIQueue, \a PIPair, \a PIVector2D. //! +//! //! \~english \section stl_iterators STL-Style Iterators //! \~russian \section stl_iterators Итераторы в стиле STL //! \~\addindex stl_iterators @@ -141,6 +142,7 @@ //! Для неконстантных итераторов, возвращаемое значение унарного оператора `*` //! может быть использовано с левой стороны от оператора присваивания. //! +//! //! \authors //! \~english //! Ivan Pelipenko peri4ko@yandex.ru; diff --git a/libs/main/containers/pivector.h b/libs/main/containers/pivector.h index 2b44ea67..00e83815 100644 --- a/libs/main/containers/pivector.h +++ b/libs/main/containers/pivector.h @@ -125,8 +125,10 @@ public: } //! \~\brief - //! \~english Contructs vector from [C++11 initializer list](https://en.cppreference.com/w/cpp/utility/initializer_list). - //! \~russian Создает массив из [списка инициализации C++11](https://ru.cppreference.com/w/cpp/utility/initializer_list). + //! \~english Contructs vector from + //! [C++11 initializer list](https://en.cppreference.com/w/cpp/utility/initializer_list). + //! \~russian Создает массив из + //! [списка инициализации C++11](https://ru.cppreference.com/w/cpp/utility/initializer_list). //! \~\details //! \~\code //! PIVector v{1,2,3}; @@ -150,8 +152,12 @@ public: //! \~english Contructs vector with size `size` and elements created by function `f(size_t i)`. //! \~russian Создает массив из `size` элементов созданных функцией `f(size_t i)`. //! \~\details - //! \~english Can use [Lambda expressions](https://en.cppreference.com/w/cpp/language/lambda) as constructor argument. - //! \~russian Позволяет передавать [Лямбда-выражения](https://ru.cppreference.com/w/cpp/language/lambda) для создания элементов в конструкторе. + //! \~english Can use + //! [Lambda expressions](https://en.cppreference.com/w/cpp/language/lambda) + //! as constructor argument. + //! \~russian Позволяет передавать + //! [Лямбда-выражения](https://ru.cppreference.com/w/cpp/language/lambda) + //! для создания элементов в конструкторе. //! \~\code //! PIVector v(5, [](size_t i){return i*2;}); //! piCout << v; // {0, 2, 4, 6, 8} @@ -317,7 +323,8 @@ public: inline reverse_iterator rbegin() {return reverse_iterator(this, piv_size - 1);} //! \~\brief - //! \~english Returns a reverse iterator to the element following the last element of the reversed vector. + //! \~english Returns a reverse iterator to the element + //! following the last element of the reversed vector. //! \~russian Обратный итератор на элемент, следующий за последним элементом. //! \~\details ![rbegin, rend](doc/images/pivector_rbegin.png) //! @@ -377,13 +384,16 @@ public: inline bool isNotEmpty() const {return (piv_size > 0);} //! \~\brief - //! \~english Tests whether at least one element in the array passes the test implemented by the provided function `test`. - //! \~russian Проверяет, удовлетворяет ли какой-либо элемент массива условию, заданному в передаваемой функции `test`. + //! \~english Tests whether at least one element in the array + //! passes the test implemented by the provided function `test`. + //! \~russian Проверяет, удовлетворяет ли какой-либо элемент массива условию, + //! заданному в передаваемой функции `test`. //! \~\return - //! \~english **true** if, in the array, it finds an element for which the provided function returns **true**; + //! \~english **true** if, in the array, + //! it finds an element for which the provided function returns **true**; //! otherwise it returns **false**. Always returns **false** if is empty. - //! \~russian **true** если хотя бы для одного элемента передаваемая функция возвращает **true**, - //! в остальных случаях **false**. + //! \~russian **true** если хотя бы для одного элемента + //! передаваемая функция возвращает **true**, в остальных случаях **false**. //! Метод возвращает **false** при любом условии для пустого массива. //! \~\details //! \~\code @@ -400,10 +410,13 @@ public: } //! \~\brief - //! \~english Tests whether all elements in the array passes the test implemented by the provided function `test`. - //! \~russian Проверяет, удовлетворяют ли все элементы массива условию, заданному в передаваемой функции `test`. + //! \~english Tests whether all elements in the array passes the test + //! implemented by the provided function `test`. + //! \~russian Проверяет, удовлетворяют ли все элементы массива условию, + //! заданному в передаваемой функции `test`. //! \~\return - //! \~english **true** if, in the array, it finds an element for which the provided function returns **true**; + //! \~english **true** if, in the array, + //! it finds an element for which the provided function returns **true**; //! otherwise it returns **false**. Always returns **true** if is empty. //! \~russian **true** если для всех элементов передаваемая функция возвращает **true**, //! в остальных случаях **false**. @@ -569,7 +582,7 @@ public: //! piCout << v.entries(2, 2); // 1 //! piCout << v.entries(2, -4); // 2 //! \endcode - //! \~\sa \a every, \a any, \a contains, \a forEach + //! \~\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) { @@ -584,7 +597,8 @@ public: //! \~\brief //! \~english Count elements in the array passes the test implemented by the provided function `test`. - //! \~russian Подсчитывает количество элементов в массиве, проходящих по условию, заданному в передаваемой функции `test`. + //! \~russian Подсчитывает количество элементов в массиве, + //! проходящих по условию, заданному в передаваемой функции `test`. //! \~\details //! \~english Overloaded function. //! Optional argument `start` - the position in this array at which to begin searching. @@ -603,7 +617,7 @@ public: //! Если рассчитанный индекс все равно оказывается меньше 0, просматривается весь массив. //! Обратите внимание: если индекс отрицателен, массив всё равно просматривается от начала к концу. //! Значение по умолчанию равно 0, что означает, что просматривается весь массив. - //! \~\sa \a every, \a any, \a contains, \a forEach + //! \~\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) { @@ -616,7 +630,36 @@ public: return ec; } - + //! \~\brief + //! \~english Returns the first index at which a given element `e` + //! can be found in the array, or `-1` if it is not present. + //! \~russian Возвращает первый индекс, по которому данный элемент `e` + //! может быть найден в массиве или `-1`, если такого индекса нет. + //! \~\details + //! \~english Optional argument `start` - the position in this array at which to begin searching. + //! If the index is greater than or equal to the array's size, + //! `-1` is returned, which means the array will not be searched. + //! If the provided index value is a negative number, + //! it is taken as the offset from the end of the array. + //! Note: if the provided index is negative, + //! the array is still searched from front to back. + //! Default: 0 (entire array is searched). + //! \~russian Опциональный аргумент `start` указывает на индекс в массиве, откуда будет начинаться поиск. + //! Если индекс больше или равен длине массива, + //! возвращается `-1`, что означает, что массив даже не просматривается. + //! Если индекс является отрицательным числом, он трактуется как смещение с конца массива. + //! Если рассчитанный индекс все равно оказывается меньше 0, просматривается весь массив. + //! Обратите внимание: если индекс отрицателен, массив всё равно просматривается от начала к концу. + //! Значение по умолчанию равно 0, что означает, что просматривается весь массив. + //! \~\code + //! PIVector v{2, 5, 9}; + //! piCout << v.indexOf(2); // 0 + //! piCout << v.indexOf(7); // -1 + //! piCout << v.indexOf(9, 2); // 2 + //! piCout << v.indexOf(2, -1); // -1 + //! piCout << v.indexOf(2, -3); // 0 + //! \endcode + //! \~\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; @@ -628,6 +671,35 @@ public: return -1; } + //! \~\brief + //! \~english Returns the first index passes the test implemented by the provided function `test`, + //! or `-1` if it is not present. + //! can be found in the array, or `-1` if it is not present. + //! \~russian Возвращает первый индекс элемента проходящего по условию, + //! заданному в передаваемой функции `test`, или `-1`, если таких элементов нет. + //! \~\details + //! \~english Optional argument `start` - the position in this array at which to begin searching. + //! If the index is greater than or equal to the array's size, + //! `-1` is returned, which means the array will not be searched. + //! If the provided index value is a negative number, + //! it is taken as the offset from the end of the array. + //! Note: if the provided index is negative, + //! the array is still searched from front to back. + //! Default: 0 (entire array is searched). + //! \~russian Опциональный аргумент `start` указывает на индекс в массиве, откуда будет начинаться поиск. + //! Если индекс больше или равен длине массива, + //! возвращается `-1`, что означает, что массив даже не просматривается. + //! Если индекс является отрицательным числом, он трактуется как смещение с конца массива. + //! Если рассчитанный индекс все равно оказывается меньше 0, просматривается весь массив. + //! Обратите внимание: если индекс отрицателен, массив всё равно просматривается от начала к концу. + //! Значение по умолчанию равно 0, что означает, что просматривается весь массив. + //! \~\code + //! PIVector v{"do", "re", "mi", "re"}; + //! piCout << v.indexWhere([](const PIString & s){return s.startsWith('r');}); // 1 + //! 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 inline ssize_t indexWhere(std::function test, ssize_t start = 0) const { if (start < 0) { start = piv_size + start; @@ -639,25 +711,115 @@ public: return -1; } + //! \~\brief + //! \~english Returns the last index at which a given element `e` + //! can be found in the array, or `-1` if it is not present. + //! \~russian Возвращает последний индекс, по которому данный элемент `e` + //! может быть найден в массиве или `-1`, если такого индекса нет. + //! \~\details + //! \~english Optional argument `start` - the position in this array + //! at which to start searching backwards. + //! If the index is greater than or equal to the array's size, + //! causes the whole array to be searched. + //! If the provided index value is a negative number, + //! it is taken as the offset from the end of the array. + //! Therefore, if calculated index less than 0, + //! the array is not searched, and the method returns `-1`. + //! Note: if the provided index is negative, + //! the array is still searched from back to front. + //! Default: -1 (entire array is searched). + //! \~russian Опциональный аргумент `start` указывает на индекс + //! c которого начинать поиск в обратном направлении. + //! Если индекс больше или равен длине массива, просматривается весь массив. + //! Если индекс является отрицательным числом, он трактуется как смещение с конца массива. + //! Обратите внимание: если индекс отрицателен, массив всё равно просматривается от конца к началу. + //! Если рассчитанный индекс оказывается меньше 0, массив даже не просматривается. + //! Значение по умолчанию равно `-1`, что равно индексу последнего элемента + //! и означает, что просматривается весь массив. + //! \~\code + //! PIVector v{2, 5, 9, 2}; + //! piCout << v.lastIndexOf(2); // 3 + //! piCout << v.lastIndexOf(7); // -1 + //! piCout << v.lastIndexOf(2, 2); // 0 + //! piCout << v.lastIndexOf(2, -3); // 0 + //! piCout << v.lastIndexOf(2, -300); // -1 + //! piCout << v.lastIndexOf(2, 300); // 3 + //! \endcode + //! \~\sa \a indexOf, \a indexWhere, \a lastIndexWhere, \a contains inline ssize_t lastIndexOf(const T & e, ssize_t start = -1) const { - if (start < 0) start = piv_size - 1; - else start = piMin(piv_size - 1, start); + if (start >= size_s()) start = piv_size - 1; + if (start < 0) start = piv_size + start; for (ssize_t i = start; i >= 0; --i) { if (e == piv_data[i]) return i; } return -1; } + //! \~\brief + //! \~english Returns the last index passes the test implemented by the provided function `test`, + //! or `-1` if it is not present. + //! \~russian Возвращает последний индекс элемента проходящего по условию, + //! заданному в передаваемой функции `test`, или `-1`, если таких элементов нет. + //! \~\details + //! \~english Optional argument `start` - the position in this array + //! at which to start searching backwards. + //! If the index is greater than or equal to the array's size, + //! causes the whole array to be searched. + //! If the provided index value is a negative number, + //! it is taken as the offset from the end of the array. + //! Therefore, if calculated index less than 0, + //! the array is not searched, and the method returns `-1`. + //! Note: if the provided index is negative, + //! the array is still searched from back to front. + //! Default: -1 (entire array is searched). + //! \~russian Опциональный аргумент `start` указывает на индекс + //! c которого начинать поиск в обратном направлении. + //! Если индекс больше или равен длине массива, просматривается весь массив. + //! Если индекс является отрицательным числом, он трактуется как смещение с конца массива. + //! Обратите внимание: если индекс отрицателен, массив всё равно просматривается от конца к началу. + //! Если рассчитанный индекс оказывается меньше 0, массив даже не просматривается. + //! Значение по умолчанию равно `-1`, что равно индексу последнего элемента + //! и означает, что просматривается весь массив. + //! \~\sa \a indexOf, \a lastIndexOf, \a indexWhere, \a contains inline ssize_t lastIndexWhere(std::function test, ssize_t start = -1) const { - if (start < 0) start = piv_size - 1; - else start = piMin(piv_size - 1, start); + if (start >= size_s()) start = piv_size - 1; + if (start < 0) start = piv_size + start; for (ssize_t i = start; i >= 0; --i) { if (test(piv_data[i])) return i; } return -1; } + //! \~\brief + //! \~english Pointer to array + //! \~russian Указатель на память массива + //! \~\details + //! \~english Optional argument `index` the position in this array, + //! where is pointer. Default: start of array. + //! \~russian Опциональный аргумент `index` указывает на индекс c которого брать указатель. + //! По умолчанию указывает на начало массива. + //! \~\code + //! PIVector v{2, 5, 9, 2}; + //! int a[2] = {12, 13}; + //! memcpy(vec.data(1), carr, 2 * sizeof(int)); + //! piCout << v; // 2, 12, 13, 2 + //! \endcode inline T * data(size_t index = 0) {return &(piv_data[index]);} + + //! \~\brief + //! \~english Read only pointer to array + //! \~russian Указатель на память массива только для чтения. + //! \~\details + //! \~english Optional argument `index` the position in this array, + //! where is pointer. Default: start of array. + //! \~russian Опциональный аргумент `index` указывает на индекс c которого брать указатель. + //! По умолчанию указывает на начало массива. + //! \~\code + //! PIVector v{1, 3, 5}; + //! int a[3]; + //! memcpy(a, v.data(), a.size() * sizeof(int)); + //! piCout << a[0] << a[1] << a[2]; // 1 3 5 + //! \endcode inline const T * data(size_t index = 0) const {return &(piv_data[index]);} PIVector getRange(size_t index, size_t count) const {