PIVector doc

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;

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).
+	//! \~english Contructs vector from
-	//! \~russian Создает массив из [списка инициализации C++11](https://ru.cppreference.com/w/cpp/utility/initializer_list).
+	//! [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 <int> 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.
+	//! \~english Can use
-	//! \~russian Позволяет передавать [Лямбда-выражения](https://ru.cppreference.com/w/cpp/language/lambda) для создания элементов в конструкторе.
+	//! [Lambda expressions](https://en.cppreference.com/w/cpp/language/lambda)
+	//! as constructor argument.
+	//! \~russian Позволяет передавать
+	//! [Лямбда-выражения](https://ru.cppreference.com/w/cpp/language/lambda)
+	//! для создания элементов в конструкторе.
 	//! \~\code
 	//! PIVector <int> 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`.
+	//! \~english Tests whether at least one element in the array
-	//! \~russian Проверяет, удовлетворяет ли какой-либо элемент массива условию, заданному в передаваемой функции `test`.
+	//! 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**,
+	//! \~russian **true** если хотя бы для одного элемента
-	//! в остальных случаях **false**.
+	//! передаваемая функция возвращает **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`.
+	//! \~english Tests whether all elements in the array passes the test
-	//! \~russian Проверяет, удовлетворяют ли все элементы массива условию, заданному в передаваемой функции `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<bool(const T & e)> 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<int> 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<PIString> 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<bool(const T & e)> 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<int> 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;
+		if (start >= size_s()) start = piv_size - 1;
-		else start = piMin<ssize_t>(piv_size - 1, start);
+		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<bool(const T & e)> test, ssize_t start = -1) const {
-		if (start < 0) start = piv_size - 1;
+		if (start >= size_s()) start = piv_size - 1;
-		else start = piMin<ssize_t>(piv_size - 1, start);
+		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<int> 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<int> 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<T> getRange(size_t index, size_t count) const {