PIDeque optimization

libs/main/containers/pivector.h

@@ -1287,6 +1287,8 @@ public:
 	//! bool comp(const T &a, const T &b);
 	//! \endcode
 	//! While the signature does not need to have const &, the function must not modify the objects passed to it.
+	//! The function must return `false` for identical elements,
+	//! otherwise, it will lead to undefined program behavior and memory errors.
 	//! Sorting provided by [std::sort](https://en.cppreference.com/w/cpp/algorithm/sort).
 	//! Complexity `O(N·log(N))`.
 	//! \~russian Сохранность порядка элементов, имеющих одинаковое значение, не гарантируется.
@@ -1297,6 +1299,8 @@ public:
 	//! bool comp(const T &a, const T &b);
 	//! \endcode
 	//! Сигнатура не обязана содержать const &, однако, функция не может изменять переданные объекты.
+	//! Функция обязана возвращать `false` для одинаковых элементов,
+	//! иначе это приведёт к неопределённому поведению программы и ошибкам памяти.
 	//! Для сортировки используется функция [std::sort](https://ru.cppreference.com/w/cpp/algorithm/sort).
 	//! Сложность сортировки `O(N·log(N))`.
 	//! \~\code
@@ -1795,6 +1799,18 @@ public:
 		return ret;
 	}
 
+	//! \brief
+	//! \~english Returns a new array with all elements
+	//! that pass the test implemented by the provided function `test`.
+	//! \~russian Возвращает новый массив со всеми элементами,
+	//! прошедшими проверку, задаваемую в передаваемой функции `test`.
+	//! \~\details
+	//! \~\code
+	//! PIVector<int> v{3, 2, 5, 2, 7};
+	//! PIVector<int> v2 = v.filter([](const int & i){return i > 2;});
+	//! piCout << v2; // {3, 5, 7}
+	//! \endcode
+	//! \~\sa \a take_front(), \a pop_back(), \a pop_front()
 	inline PIVector<T> filter(std::function<bool(const T & e)> test) const {
 		PIVector<T> ret;
 		for (size_t i = 0; i < piv_size; ++i) {