From 52c400915dab1ed2a46a47c4c08149b0d0248102 Mon Sep 17 00:00:00 2001 From: "andrey.bychkov" Date: Wed, 18 Feb 2026 17:09:26 +0300 Subject: [PATCH] fix doc --- libs/main/containers/pivector2d.h | 180 +++++++++++++++++++++++++++--- 1 file changed, 164 insertions(+), 16 deletions(-) diff --git a/libs/main/containers/pivector2d.h b/libs/main/containers/pivector2d.h index a0abede9..895f7293 100644 --- a/libs/main/containers/pivector2d.h +++ b/libs/main/containers/pivector2d.h @@ -43,11 +43,11 @@ //! (use \a resize(), \a addRow(), \a removeRow(), \a removeColumn() instead), but you can modify the values of existing elements. //! \~russian //! Этот класс используется для хранения двумерного массива элементов любого типа в виде единого непрерывного блока памяти (обычного -//! PIVector). Доступ к элементам осуществляется с помощью операторов `[][]`, где первый индекс — это строка, а второй — столбец. Со +//! \a PIVector). Доступ к элементам осуществляется с помощью операторов `[][]`, где первый индекс — это строка, а второй — столбец. Со //! строками можно работать как с объектами \a PIVector, что позволяет изменять отдельные элементы или присваивать целые строки. Нельзя //! напрямую добавлять или удалять элементы, чтобы изменить размеры массива после создания (используйте \a resize(), \a addRow(), \a //! removeRow(), \a removeColumn() для этого), но можно изменять значения существующих элементов. -//! \sa PIVector + template class PIVector2D { @@ -85,10 +85,10 @@ public: //! \details //! \~english The constructor copies the data from `v` into the internal flat vector. //! If `v` is larger than `rows * cols`, the excess elements are ignored (the vector is truncated). - //! If `v` is smaller, the behaviour is undefined (an assertion may fail in debug mode). + //! If `v` is smaller, other values filled whith default cunstructor T() //! \~russian Конструктор копирует данные из `v` во внутренний плоский вектор. //! Если `v` больше, чем `rows * cols`, лишние элементы игнорируются (вектор обрезается). - //! Если `v` меньше, поведение не определено (в отладочном режиме может сработать assertion). + //! Если `v` меньше, остальные значения будут заполнены из конструктора по умолчанию T() //! \sa PIVector::PIVector(const PIVector&), reshape() inline PIVector2D(size_t rows, size_t cols, const PIVector & v): rows_(rows), cols_(cols), mat(v) { mat.resize(rows * cols); } @@ -361,6 +361,9 @@ public: //! \~english Applies a function to each element of the row (read-only). //! \~russian Применяет функцию к каждому элементу строки (только чтение). //! \param func Function that takes a const reference to T. + //! \details + //! \~english The function can't modify the elements. + //! \~russian Функция не может изменять элементы. //! \sa forEach (modifiable) inline void forEach(std::function func) const { for (size_t i = 0; i < sz_; ++i) { @@ -526,8 +529,15 @@ public: return ret; } - //! \~english Returns the first index (row) where element `e` appears in the column. - //! \~russian Возвращает первый индекс (строку), в которой элемент `e` появляется в столбце. + //! \~english Returns the first index of element `e` in the row, starting from `start`. + //! \~russian Возвращает первый индекс элемента `e` в строке, начиная с позиции `start`. + //! \param e Element to search for. + //! \param start Starting index (negative values count from the end). Default 0. + //! \return Index if found, -1 otherwise. + //! \details + //! \~english See \a PIVector::indexOf() for details on negative start handling. + //! \~russian Подробнее об обработке отрицательного `start` см. \a PIVector::indexOf(). + //! \sa PIVector::indexOf() inline ssize_t indexOf(const T & e, ssize_t start = 0) const { if (start < 0) start = 0; for (size_t i = (size_t)start; i < sz_; ++i) { @@ -536,7 +546,12 @@ public: return -1; } - //! \~english Returns the last index (row) where element `e` appears in the column. + //! \~english Returns the last index of element `e` in the row, searching backwards from `start`. + //! \~russian Возвращает последний индекс элемента `e` в строке, выполняя поиск в обратном направлении от `start`. + //! \param e Element to search for. + //! \param start Starting index (negative values count from the end). Default -1 (last element). + //! \return Index if found, -1 otherwise. + //! \sa PIVector::lastIndexOf() inline ssize_t lastIndexOf(const T & e, ssize_t start = -1) const { ssize_t from = (start < 0 || (size_t)start >= sz_) ? (ssize_t)sz_ - 1 : start; for (ssize_t i = from; i >= 0; --i) { @@ -545,7 +560,12 @@ public: return -1; } - //! \~english Returns the first row index where the predicate `test` returns true. + //! \~english Returns the first index where the predicate `test` returns true, starting from `start`. + //! \~russian Возвращает первый индекс, для которого предикат `test` возвращает true, начиная с `start`. + //! \param test Predicate function: `bool(const T&)`. + //! \param start Starting index (negative values count from the end). Default 0. + //! \return Index if found, -1 otherwise. + //! \sa PIVector::indexWhere() inline ssize_t indexWhere(std::function test, ssize_t start = 0) const { if (start < 0) start = 0; for (size_t i = (size_t)start; i < sz_; ++i) { @@ -554,7 +574,10 @@ public: return -1; } - //! \~english Returns the last row index where the predicate `test` returns true. + //! \~english Returns the last index where the predicate `test` returns true, searching backwards from `start`. + //! \~russian Возвращает последний индекс, для которого предикат `test` возвращает true, выполняя поиск в обратном направлении от + //! `start`. \param test Predicate function: `bool(const T&)`. \param start Starting index (negative values count from the end). + //! Default -1. \return Index if found, -1 otherwise. \sa PIVector::lastIndexWhere() inline ssize_t lastIndexWhere(std::function test, ssize_t start = -1) const { ssize_t from = (start < 0 || (size_t)start >= sz_) ? (ssize_t)sz_ - 1 : start; for (ssize_t i = from; i >= 0; --i) { @@ -565,6 +588,11 @@ public: //! \~english Applies a function to each element of the column (modifiable). //! \~russian Применяет функцию к каждому элементу столбца (с возможностью изменения). + //! \param func Function that takes a reference to T. + //! \details + //! \~english The function can modify the elements. + //! \~russian Функция может изменять элементы. + //! \sa PIVector::forEach() inline void forEach(std::function func) { for (size_t i = 0; i < sz_; ++i) { func((*p_)[i * step_ + col_]); @@ -573,6 +601,11 @@ public: //! \~english Applies a function to each element of the column (read-only). //! \~russian Применяет функцию к каждому элементу столбца (только чтение). + //! \param func Function that takes a const reference to T. + //! \details + //! \~english The function can't modify the elements. + //! \~russian Функция не может изменять элементы. + //! \sa forEach (modifiable) inline void forEach(std::function func) const { for (size_t i = 0; i < sz_; ++i) { func((*p_)[i * step_ + col_]); @@ -581,6 +614,8 @@ public: //! \~english Fills the column with copies of `value`. //! \~russian Заполняет столбец копиями `value`. + //! \param value Value to fill with. + //! \sa PIVector::fill() inline void fill(const T & value) { for (size_t i = 0; i < sz_; ++i) { (*p_)[i * step_ + col_] = value; @@ -589,10 +624,18 @@ public: //! \~english Checks if the column contains the element `e`. //! \~russian Проверяет, содержит ли столбец элемент `e`. + //! \param e Element to check. + //! \param start Starting index (negative allowed). Default 0. + //! \return \c true if found, \c false otherwise. + //! \sa PIVector::contains() inline bool contains(const T & e, ssize_t start = 0) const { return indexOf(e, start) != -1; } //! \~english Counts occurrences of `e` in the column. //! \~russian Подсчитывает количество вхождений `e` в столбце. + //! \param e Element to count. + //! \param start Starting index (negative allowed). Default 0. + //! \return Number of occurrences. + //! \sa PIVector::entries() inline int entries(const T & e, ssize_t start = 0) const { if (start < 0) start = 0; int count = 0; @@ -604,6 +647,10 @@ public: //! \~english Counts elements in the column that pass the `test`. //! \~russian Подсчитывает элементы в столбце, проходящие `test`. + //! \param test Predicate function. + //! \param start Starting index (negative allowed). Default 0. + //! \return Count of matching elements. + //! \sa PIVector::entries(std::function) inline int entries(std::function test, ssize_t start = 0) const { if (start < 0) start = 0; int count = 0; @@ -615,6 +662,9 @@ public: //! \~english Tests if any element in the column passes the `test`. //! \~russian Проверяет, проходит ли какой-либо элемент в столбце `test`. + //! \param test Predicate function. + //! \return \c true if at least one element satisfies the predicate. + //! \sa PIVector::any() inline bool any(std::function test) const { for (size_t i = 0; i < sz_; ++i) { if (test((*p_)[i * step_ + col_])) return true; @@ -624,6 +674,9 @@ public: //! \~english Tests if all elements in the column pass the `test`. //! \~russian Проверяет, проходят ли все элементы в столбце `test`. + //! \param test Predicate function. + //! \return \c true if all elements satisfy the predicate. + //! \sa PIVector::every() inline bool every(std::function test) const { for (size_t i = 0; i < sz_; ++i) { if (!test((*p_)[i * step_ + col_])) return false; @@ -668,6 +721,15 @@ public: //! \~russian Преобразует строку в \a PIVector. inline PIVector toVector() const { return PIVector(p_->data(st_), sz_); } + //! \~english Returns the first index of element `e` in the row, starting from `start`. + //! \~russian Возвращает первый индекс элемента `e` в строке, начиная с позиции `start`. + //! \param e Element to search for. + //! \param start Starting index (negative values count from the end). Default 0. + //! \return Index if found, -1 otherwise. + //! \details + //! \~english See \a PIVector::indexOf() for details on negative start handling. + //! \~russian Подробнее об обработке отрицательного `start` см. \a PIVector::indexOf(). + //! \sa PIVector::indexOf() inline ssize_t indexOf(const T & e, ssize_t start = 0) const { if (start < 0) start = 0; for (size_t i = (size_t)start; i < sz_; ++i) { @@ -676,7 +738,12 @@ public: return -1; } - //! \~english Searches for element `e` backwards (see Row::lastIndexOf). + //! \~english Returns the last index of element `e` in the row, searching backwards from `start`. + //! \~russian Возвращает последний индекс элемента `e` в строке, выполняя поиск в обратном направлении от `start`. + //! \param e Element to search for. + //! \param start Starting index (negative values count from the end). Default -1 (last element). + //! \return Index if found, -1 otherwise. + //! \sa PIVector::lastIndexOf() inline ssize_t lastIndexOf(const T & e, ssize_t start = -1) const { ssize_t from = (start < 0 || (size_t)start >= sz_) ? (ssize_t)sz_ - 1 : start; for (ssize_t i = from; i >= 0; --i) { @@ -685,7 +752,12 @@ public: return -1; } - //! \~english Searches with predicate (see Row::indexWhere). + //! \~english Returns the first index where the predicate `test` returns true, starting from `start`. + //! \~russian Возвращает первый индекс, для которого предикат `test` возвращает true, начиная с `start`. + //! \param test Predicate function: `bool(const T&)`. + //! \param start Starting index (negative values count from the end). Default 0. + //! \return Index if found, -1 otherwise. + //! \sa PIVector::indexWhere() inline ssize_t indexWhere(std::function test, ssize_t start = 0) const { if (start < 0) start = 0; for (size_t i = (size_t)start; i < sz_; ++i) { @@ -694,7 +766,10 @@ public: return -1; } - //! \~english Searches with predicate backwards (see Row::lastIndexWhere). + //! \~english Returns the last index where the predicate `test` returns true, searching backwards from `start`. + //! \~russian Возвращает последний индекс, для которого предикат `test` возвращает true, выполняя поиск в обратном направлении от + //! `start`. \param test Predicate function: `bool(const T&)`. \param start Starting index (negative values count from the end). + //! Default -1. \return Index if found, -1 otherwise. \sa PIVector::lastIndexWhere() inline ssize_t lastIndexWhere(std::function test, ssize_t start = -1) const { ssize_t from = (start < 0 || (size_t)start >= sz_) ? (ssize_t)sz_ - 1 : start; for (ssize_t i = from; i >= 0; --i) { @@ -705,6 +780,11 @@ public: //! \~english Applies a function to each element of the row (read-only). //! \~russian Применяет функцию к каждому элементу строки (только чтение). + //! \param func Function that takes a const reference to T. + //! \details + //! \~english The function can't modify the elements. + //! \~russian Функция не может изменять элементы. + //! \sa forEach (modifiable) inline void forEach(std::function func) const { for (size_t i = 0; i < sz_; ++i) { func((*p_)[st_ + i]); @@ -713,10 +793,18 @@ public: //! \~english Checks if the row contains the element `e`. //! \~russian Проверяет, содержит ли строка элемент `e`. + //! \param e Element to check. + //! \param start Starting index (negative allowed). Default 0. + //! \return \c true if found, \c false otherwise. + //! \sa PIVector::contains() inline bool contains(const T & e, ssize_t start = 0) const { return indexOf(e, start) != -1; } //! \~english Counts occurrences of `e` in the row. //! \~russian Подсчитывает количество вхождений `e` в строке. + //! \param e Element to count. + //! \param start Starting index (negative allowed). Default 0. + //! \return Number of occurrences. + //! \sa PIVector::entries() inline int entries(const T & e, ssize_t start = 0) const { if (start < 0) start = 0; int count = 0; @@ -728,6 +816,10 @@ public: //! \~english Counts elements in the row that pass the `test`. //! \~russian Подсчитывает элементы в строке, проходящие `test`. + //! \param test Predicate function. + //! \param start Starting index (negative allowed). Default 0. + //! \return Count of matching elements. + //! \sa PIVector::entries(std::function) inline int entries(std::function test, ssize_t start = 0) const { if (start < 0) start = 0; int count = 0; @@ -739,6 +831,9 @@ public: //! \~english Tests if any element in the row passes the `test`. //! \~russian Проверяет, проходит ли какой-либо элемент в строке `test`. + //! \param test Predicate function. + //! \return \c true if at least one element satisfies the predicate. + //! \sa PIVector::any() inline bool any(std::function test) const { for (size_t i = 0; i < sz_; ++i) { if (test((*p_)[st_ + i])) return true; @@ -748,6 +843,9 @@ public: //! \~english Tests if all elements in the row pass the `test`. //! \~russian Проверяет, проходят ли все элементы в строке `test`. + //! \param test Predicate function. + //! \return \c true if all elements satisfy the predicate. + //! \sa PIVector::every() inline bool every(std::function test) const { for (size_t i = 0; i < sz_; ++i) { if (!test((*p_)[st_ + i])) return false; @@ -799,7 +897,15 @@ public: return ret; } - //! \~english Searches for element `e` (see Col::indexOf). + //! \~english Returns the first index of element `e` in the row, starting from `start`. + //! \~russian Возвращает первый индекс элемента `e` в строке, начиная с позиции `start`. + //! \param e Element to search for. + //! \param start Starting index (negative values count from the end). Default 0. + //! \return Index if found, -1 otherwise. + //! \details + //! \~english See \a PIVector::indexOf() for details on negative start handling. + //! \~russian Подробнее об обработке отрицательного `start` см. \a PIVector::indexOf(). + //! \sa PIVector::indexOf() inline ssize_t indexOf(const T & e, ssize_t start = 0) const { if (start < 0) start = 0; for (size_t i = (size_t)start; i < sz_; ++i) { @@ -808,7 +914,12 @@ public: return -1; } - //! \~english Searches for element `e` backwards (see Col::lastIndexOf). + //! \~english Returns the last index of element `e` in the row, searching backwards from `start`. + //! \~russian Возвращает последний индекс элемента `e` в строке, выполняя поиск в обратном направлении от `start`. + //! \param e Element to search for. + //! \param start Starting index (negative values count from the end). Default -1 (last element). + //! \return Index if found, -1 otherwise. + //! \sa PIVector::lastIndexOf() inline ssize_t lastIndexOf(const T & e, ssize_t start = -1) const { ssize_t from = (start < 0 || (size_t)start >= sz_) ? (ssize_t)sz_ - 1 : start; for (ssize_t i = from; i >= 0; --i) { @@ -817,7 +928,12 @@ public: return -1; } - //! \~english Searches with predicate (see Col::indexWhere). + //! \~english Returns the first index where the predicate `test` returns true, starting from `start`. + //! \~russian Возвращает первый индекс, для которого предикат `test` возвращает true, начиная с `start`. + //! \param test Predicate function: `bool(const T&)`. + //! \param start Starting index (negative values count from the end). Default 0. + //! \return Index if found, -1 otherwise. + //! \sa PIVector::indexWhere() inline ssize_t indexWhere(std::function test, ssize_t start = 0) const { if (start < 0) start = 0; for (size_t i = (size_t)start; i < sz_; ++i) { @@ -826,7 +942,10 @@ public: return -1; } - //! \~english Searches with predicate backwards (see Col::lastIndexWhere). + //! \~english Returns the last index where the predicate `test` returns true, searching backwards from `start`. + //! \~russian Возвращает последний индекс, для которого предикат `test` возвращает true, выполняя поиск в обратном направлении от + //! `start`. \param test Predicate function: `bool(const T&)`. \param start Starting index (negative values count from the end). + //! Default -1. \return Index if found, -1 otherwise. \sa PIVector::lastIndexWhere() inline ssize_t lastIndexWhere(std::function test, ssize_t start = -1) const { ssize_t from = (start < 0 || (size_t)start >= sz_) ? (ssize_t)sz_ - 1 : start; for (ssize_t i = from; i >= 0; --i) { @@ -837,6 +956,11 @@ public: //! \~english Applies a function to each element of the column (read-only). //! \~russian Применяет функцию к каждому элементу столбца (только чтение). + //! \param func Function that takes a const reference to T. + //! \details + //! \~english The function can't modify the elements. + //! \~russian Функция не может изменять элементы. + //! \sa forEach (modifiable) inline void forEach(std::function func) const { for (size_t i = 0; i < sz_; ++i) { func((*p_)[i * step_ + col_]); @@ -845,10 +969,18 @@ public: //! \~english Checks if the column contains the element `e`. //! \~russian Проверяет, содержит ли столбец элемент `e`. + //! \param e Element to check. + //! \param start Starting index (negative allowed). Default 0. + //! \return \c true if found, \c false otherwise. + //! \sa PIVector::contains() inline bool contains(const T & e, ssize_t start = 0) const { return indexOf(e, start) != -1; } //! \~english Counts occurrences of `e` in the column. //! \~russian Подсчитывает количество вхождений `e` в столбце. + //! \param e Element to count. + //! \param start Starting index (negative allowed). Default 0. + //! \return Number of occurrences. + //! \sa PIVector::entries() inline int entries(const T & e, ssize_t start = 0) const { if (start < 0) start = 0; int count = 0; @@ -860,6 +992,10 @@ public: //! \~english Counts elements in the column that pass the `test`. //! \~russian Подсчитывает элементы в столбце, проходящие `test`. + //! \param test Predicate function. + //! \param start Starting index (negative allowed). Default 0. + //! \return Count of matching elements. + //! \sa PIVector::entries(std::function) inline int entries(std::function test, ssize_t start = 0) const { if (start < 0) start = 0; int count = 0; @@ -871,6 +1007,9 @@ public: //! \~english Tests if any element in the column passes the `test`. //! \~russian Проверяет, проходит ли какой-либо элемент в столбце `test`. + //! \param test Predicate function. + //! \return \c true if at least one element satisfies the predicate. + //! \sa PIVector::any() inline bool any(std::function test) const { for (size_t i = 0; i < sz_; ++i) { if (test((*p_)[i * step_ + col_])) return true; @@ -880,6 +1019,9 @@ public: //! \~english Tests if all elements in the column pass the `test`. //! \~russian Проверяет, проходят ли все элементы в столбце `test`. + //! \param test Predicate function. + //! \return \c true if all elements satisfy the predicate. + //! \sa PIVector::every() inline bool every(std::function test) const { for (size_t i = 0; i < sz_; ++i) { if (!test((*p_)[i * step_ + col_])) return false; @@ -1129,11 +1271,17 @@ public: //! \~english Checks if the underlying flat vector contains the element `e`. //! \~russian Проверяет, содержит ли внутренний плоский вектор элемент `e`. + //! \param e Element to check. + //! \param start Starting index (negative allowed). Default 0. + //! \return \c true if found, \c false otherwise. //! \sa PIVector::contains() inline bool contains(const T & e, ssize_t start = 0) const { return mat.contains(e, start); } //! \~english Checks if the underlying flat vector contains all elements of `v`. //! \~russian Проверяет, содержит ли внутренний плоский вектор все элементы `v`. + //! \param e Element to check. + //! \param start Starting index (negative allowed). Default 0. + //! \return \c true if found, \c false otherwise. //! \sa PIVector::contains(const PIVector&) inline bool contains(const PIVector & v, ssize_t start = 0) const { return mat.contains(v, start); }