fix doc

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<typename T>
 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<T> & 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<void(const T &)> 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.
+		//! \~english Returns the first index of element `e` in the row, starting from `start`.
-		//! \~russian Возвращает первый индекс (строку), в которой элемент `e` появляется в столбце.
+		//! \~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<bool(const T & e)> 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<bool(const T & e)> 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<void(T &)> 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<void(const T &)> 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<bool(const T & e)> 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<bool(const T & e)> 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<bool(const T & e)> 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<T> toVector() const { return PIVector<T>(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<bool(const T & e)> 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<bool(const T & e)> 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<void(const T &)> 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<bool(const T & e)> 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<bool(const T & e)> 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<bool(const T & e)> 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<bool(const T & e)> 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<bool(const T & e)> 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<void(const T &)> 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<bool(const T & e)> 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<bool(const T & e)> 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<bool(const T & e)> 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<T> & v, ssize_t start = 0) const { return mat.contains(v, start); }