PIP_DEBUG, PIVector sort and doc

libs/main/containers/pivector.h

@@ -36,6 +36,7 @@
 
 #include "picontainers.h"
 
+
 //! \addtogroup Containers
 //! \{
 //! \class PIVector
@@ -1199,7 +1200,7 @@ public:
 	//! \~\sa \a append(), \a prepend(), \a remove()
 	inline PIVector<T> & insert(size_t index, const PIVector<T> & v) {
 		if (v.isEmpty()) return *this;
-#ifdef USE_DEBUG
+#ifdef PIP_DEBUG
 		if (&v == this) {
 			printf("error with PIVector<%s>::insert\n", __PIP_TYPENAME__(T));
 		}
@@ -1249,10 +1250,61 @@ public:
 		piSwap<size_t>(piv_rsize, v.piv_rsize);
 	}
 
-	typedef int (*CompareFunc)(const T * , const T * );
-	static int compare_func(const T * t0, const T * t1) {return (*t0) < (*t1) ? -1 : ((*t0) == (*t1) ? 0 : 1);}
-	inline PIVector<T> & sort(CompareFunc compare = compare_func) {
-		piqsort(piv_data, piv_size, sizeof(T), (int(*)(const void * , const void * ))compare);
+	//! \~\brief
+	//! \~english Sorts the elements in non-descending order.
+	//! \~russian Сортировка элементов в порядке возрастания.
+	//! \~\details
+	//! \~english The order of equal elements is not guaranteed to be preserved.
+	//! Elements are compared using operator<.
+	//! Sorting provided by [std::sort](https://en.cppreference.com/w/cpp/algorithm/sort).
+	//! Complexity `O(N·log(N))`.
+	//! \~russian Сохранность порядка элементов, имеющих одинаковое значение, не гарантируется.
+	//! Для сравнения элементов используется оператор `operator<`.
+	//! Для сортировки используется функция [std::sort](https://ru.cppreference.com/w/cpp/algorithm/sort).
+	//! Сложность сортировки `O(N·log(N))`.
+	//! \~\code
+	//! PIVector<int> v{5, 7, 4, 2, 8, 6, 1, 9, 0, 3};
+	//! v.sort();
+	//! piCout << v; // 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
+	//! \endcode
+	//! \~\sa \a sort(std::function<bool(const T &a, const T &b)> comp)
+	inline PIVector<T> & sort() {
+		std::sort(begin(), end());
+		return *this;
+	}
+
+	//! \~\brief
+	//! \~english Sorts the elements in non-descending order.
+	//! \~russian Сортировка элементов в порядке возрастания.
+	//! \~\details
+	//! \~english The order of equal elements is not guaranteed to be preserved.
+	//! Elements are compared using the given binary comparison function `comp`.
+	//! which returns `​true` if the first argument is less than (i.e. is ordered before) the second.
+	//! The signature of the comparison function should be equivalent to the following:
+	//! \code
+	//! 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.
+	//! Sorting provided by [std::sort](https://en.cppreference.com/w/cpp/algorithm/sort).
+	//! Complexity `O(N·log(N))`.
+	//! \~russian Сохранность порядка элементов, имеющих одинаковое значение, не гарантируется.
+	//! Для сравнения элементов используется функция сравнения `comp`.
+	//! Функция сравнения, возвращает ​`true` если первый аргумент меньше второго.
+	//! Сигнатура функции сравнения должна быть эквивалентна следующей:
+	//! \code
+	//! bool comp(const T &a, const T &b);
+	//! \endcode
+	//! Сигнатура не обязана содержать const &, однако, функция не может изменять переданные объекты.
+	//! Для сортировки используется функция [std::sort](https://ru.cppreference.com/w/cpp/algorithm/sort).
+	//! Сложность сортировки `O(N·log(N))`.
+	//! \~\code
+	//! PIVector<int> v{5, 7, 4, 2, 8, 6, 1, 9, 0, 3};
+	//! v.sort([](const int & a, const int & b){return a > b;});
+	//! piCout << v; // 9, 8, 7, 6, 5, 4, 3, 2, 1, 0
+	//! \endcode
+	//! \~\sa \a sort()
+	inline PIVector<T> & sort(std::function<bool(const T &a, const T &b)> comp) {
+		std::sort(begin(), end(), comp);
 		return *this;
 	}
 
@@ -1390,7 +1442,7 @@ public:
 	}
 
 	inline PIVector<T> & push_back(const PIVector<T> & v) {
-#ifdef USE_DEBUG
+#ifdef PIP_DEBUG
 		if (&v == this) {
 			printf("error with PIVector<%s>::push_back\n", __PIP_TYPENAME__(T));
 		}
@@ -1495,7 +1547,7 @@ public:
 	inline PIVector<PIVector<T>> reshape(size_t rows, size_t cols, ReshapeOrder order = byRow) const {
 		PIVector<PIVector<T>> ret;
 		if (isEmpty()) return ret;
-#ifdef USE_DEBUG
+#ifdef PIP_DEBUG
 		if (rows*cols != piv_size) {
 			printf("error with PIVector<%s>::reshape\n", __PIP_TYPENAME__(T));
 		}
@@ -1624,7 +1676,7 @@ private:
 		if (as == piv_rsize) return;
 		PIINTROSPECTION_CONTAINER_ALLOC(T, (as-piv_rsize))
 		T * p_d = (T*)(realloc((void*)(piv_data), as*sizeof(T)));
-#ifdef USE_DEBUG
+#ifdef PIP_DEBUG
 		if (!p_d) {
 			printf("error with PIVector<%s>::alloc\n", __PIP_TYPENAME__(T));
 		}