PIVector doc

libs/main/containers/pivector.h

@@ -1368,11 +1368,9 @@ public:
 	}
 
 	//! \brief
-	//! \~english Remove no more than one element equal "v" and return reference to vector
-	//! \~russian
-	//! \details
-	//! \~english
-	//! \~russian
+	//! \~english Remove no more than one element equal `e`.
+	//! \~russian Удаляет первый элемент, который равен элементу `e`.
+	//! \~\details
 	//! \~\code
 	//! PIVector<int> v{3, 2, 5, 2, 7};
 	//! v.removeOne(2);
@@ -1390,11 +1388,9 @@ public:
 	}
 
 	//! \brief
-	//! \~english Remove no more than one element equal "v" and return reference to vector
-	//! \~russian
-	//! \details
-	//! \~english
-	//! \~russian
+	//! \~english Remove all elements equal `e`.
+	//! \~russian Удаляет все элементы, равные элементу `e`.
+	//! \~\details
 	//! \~\code
 	//! PIVector<int> v{3, 2, 5, 2, 7};
 	//! v.removeAll(2);
@@ -1411,6 +1407,18 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Remove all elements in the array
+	//! passes the test implemented by the provided function `test`.
+	//! \~russian Удаляет все элементы, удовлетворяющие условию,
+	//! заданному в передаваемой функции `test`.
+	//! \~\details
+	//! \~\code
+	//! PIVector<int> v{3, 2, 5, 2, 7};
+	//! v.removeWhere([](const int & i){return i > 2;});
+	//! piCout << v; // 2, 2
+	//! \endcode
+	//! \~\sa \a remove(), \a removeOne(), \a removeWhere()
 	inline PIVector<T> & removeWhere(std::function<bool(const T & e)> test) {
 		for (ssize_t i = 0; i < size_s(); ++i) {
 			if (test(piv_data[i])) {
@@ -1421,6 +1429,29 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~english If size() is less than capacity(), which is most often
+	//! then the addition will be very fast, and does not depend on the size of the array.
+	//! If the new size() is greater than capacity()
+	//! then all iterators and references
+	//! (including the past-the-end iterator) are invalidated.
+	//! Otherwise only the past-the-end iterator is invalidated.
+	//! \~russian Если size() меньше capacity(), что чаше всего,
+	//! то добавление будет очень быстрым, и не зависит от размера массива.
+	//! Если новый size() больше, чем capacity(),
+	//! то все итераторы и указатели становятся нерабочими.
+	//! В противном случае, все, кроме итераторов указывающих на конец массива,
+	//! остаются в рабочем состоянии.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v.push_back(4);
+	//! v.push_back(5);
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a push_front(), \a append(), \a prepend(), \a insert()
 	inline PIVector<T> & push_back(const T & e) {
 		alloc(piv_size + 1);
 		PIINTROSPECTION_CONTAINER_USED(T, 1);
@@ -1428,6 +1459,13 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\sa \a push_back()
 	inline PIVector<T> & push_back(T && e) {
 		alloc(piv_size + 1);
 		PIINTROSPECTION_CONTAINER_USED(T, 1);
@@ -1435,6 +1473,17 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given elements to the end of the array.
+	//! \~russian Добавляет элементы в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! Appends the given elements from
+	//! [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).
+	//! \~\sa \a push_back()
 	inline PIVector<T> & push_back(std::initializer_list<T> init_list) {
 		size_t ps = piv_size;
 		alloc(piv_size + init_list.size());
@@ -1442,6 +1491,13 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given array `v` to the end of the array.
+	//! \~russian Добавляет массив `v` в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\sa \a push_back()
 	inline PIVector<T> & push_back(const PIVector<T> & v) {
 #ifndef NDEBUG
 		if (&v == this) {
@@ -1455,20 +1511,194 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~english If size() is less than capacity(), which is most often
+	//! then the addition will be very fast, and does not depend on the size of the array.
+	//! If the new size() is greater than capacity()
+	//! then all iterators and references
+	//! (including the past-the-end iterator) are invalidated.
+	//! Otherwise only the past-the-end iterator is invalidated.
+	//! \~russian Если size() меньше capacity(), что чаше всего,
+	//! то добавление будет очень быстрым, и не зависит от размера массива.
+	//! Если новый size() больше, чем capacity(),
+	//! то все итераторы и указатели становятся нерабочими.
+	//! В противном случае, все, кроме итераторов указывающих на конец массива,
+	//! остаются в рабочем состоянии.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v.append(4);
+	//! v.append(5);
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a prepend(), \a push_front(), \a push_back(), \a insert()
 	inline PIVector<T> & append(const T & e) {return push_back(e);}
+
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\sa \a append()
 	inline PIVector<T> & append(T && e) {return push_back(std::move(e));}
+
+	//! \brief
+	//! \~english Appends the given elements to the end of the array.
+	//! \~russian Добавляет элементы в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! Appends the given elements from
+	//! [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).
+	//! \~\sa \a append()
 	inline PIVector<T> & append(std::initializer_list<T> init_list) {return push_back(init_list);}
+
+	//! \brief
+	//! \~english Appends the given array `v` to the end of the array.
+	//! \~russian Добавляет массив `v` в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v.append(PIVector<int>{4, 5});
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a append()
 	inline PIVector<T> & append(const PIVector<T> & v) {return push_back(v);}
 
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v << 4 << 5;
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a append()
 	inline PIVector<T> & operator <<(const T & e) {return push_back(e);}
+
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v << 4 << 5;
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a append()
 	inline PIVector<T> & operator <<(T && e) {return push_back(std::move(e));}
+
+	//! \brief
+	//! \~english Appends the given array `v` to the end of the array.
+	//! \~russian Добавляет массив `v` в конец массива.
+	//! \~\details
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v << PIVector<int>{4, 5};
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a append()
 	inline PIVector<T> & operator <<(const PIVector<T> & v) {return push_back(v);}
 
-	inline PIVector<T> & push_front(const T & e) {insert(0, e); return *this;}
-	inline PIVector<T> & push_front(T && e) {insert(0, std::move(e)); return *this;}
-	inline PIVector<T> & push_front(const PIVector<T> & v) {insert(0, v); return *this;}
+	//! \brief
+	//! \~english Appends the given element `e` to the begin of the array.
+	//! \~russian Добавляет элемент `e` в начало массива.
+	//! \~\details
+	//! \~english Adding an element to the beginning takes longer than to the end.
+	//! This time is directly proportional to the size of the array.
+	//! All iterators and references are invalidated.
+	//! \~russian Добавление элемента в начало выполняется дольше чем в конец.
+	//! Это время прямопропорционально размеру массива.
+	//! При добавлении элемента все итераторы и указатели становятся нерабочими.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v.push_front(4);
+	//! v.push_front(5);
+	//! piCout << v; // 5, 4, 1, 2, 3
+	//! \endcode
+	//! \~\sa \a push_back(), \a append(), \a prepend(), \a insert()
+	inline PIVector<T> & push_front(const T & e) {
+		insert(0, e);
+		return *this;
+	}
+
+	//! \brief
+	//! \~english Appends the given element `e` to the begin of the array.
+	//! \~russian Добавляет элемент `e` в начало массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\sa \a push_front()
+	inline PIVector<T> & push_front(T && e) {
+		insert(0, std::move(e));
+		return *this;
+	}
+
+	//! \brief
+	//! \~english Appends the given array `v` to the begin of the array.
+	//! \~russian Добавляет массив `v` в начало массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v.push_front(PIVector<int>{4, 5});
+	//! piCout << v; // 4, 5, 1, 2, 3
+	//! \endcode
+	//! \~\sa \a push_front()
+	inline PIVector<T> & push_front(const PIVector<T> & v) {
+		insert(0, v);
+		return *this;
+	}
+
+	//! \brief
+	//! \~english Appends the given element `e` to the begin of the array.
+	//! \~russian Добавляет элемент `e` в начало массива.
+	//! \~\details
+	//! \~english Adding an element to the beginning takes longer than to the end.
+	//! This time is directly proportional to the size of the array.
+	//! All iterators and references are invalidated.
+	//! \~russian Добавление элемента в начало выполняется дольше чем в конец.
+	//! Это время прямопропорционально размеру массива.
+	//! При добавлении элемента все итераторы и указатели становятся нерабочими.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v.prepend(4);
+	//! v.prepend(5);
+	//! piCout << v; // 5, 4, 1, 2, 3
+	//! \endcode
+	//! \~\sa \a append(), \a push_back(), \a push_front(), \a insert()
 	inline PIVector<T> & prepend(const T & e) {return push_front(e);}
+
+	//! \brief
+	//! \~english Appends the given element `e` to the begin of the array.
+	//! \~russian Добавляет элемент `e` в начало массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\sa \a prepend()
 	inline PIVector<T> & prepend(T && e) {return push_front(std::move(e));}
+
+	//! \brief
+	//! \~english Appends the given array `v` to the begin of the array.
+	//! \~russian Добавляет массив `v` в начало массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v.prepend(PIVector<int>{4, 5});
+	//! piCout << v; // 4, 5, 1, 2, 3
+	//! \endcode
+	//! \~\sa \a prepend()
 	inline PIVector<T> & prepend(const PIVector<T> & v) {return push_front(v);}
 
 	inline PIVector<T> & pop_back() {
@@ -1482,8 +1712,16 @@ public:
 		return *this;
 	}
 
-	inline T take_back() {T e(back()); pop_back(); return e;}
-	inline T take_front() {T e(front()); pop_front(); return e;}
+	inline T take_back() {
+		T e(back());
+		pop_back();
+		return e;
+	}
+	inline T take_front() {
+		T e(front());
+		pop_front();
+		return e;
+	}
 
 	template <typename ST>
 	inline PIVector<ST> toType() const {
@@ -1694,6 +1932,8 @@ private:
 
 
 #ifdef PIP_STD_IOSTREAM
+//! \~english Output operator to [std::ostream](https://en.cppreference.com/w/cpp/io/basic_ostream).
+//! \~russian Оператор вывода в [std::ostream](https://ru.cppreference.com/w/cpp/io/basic_ostream).
 template<typename T>
 inline std::ostream & operator <<(std::ostream & s, const PIVector<T> & v) {
 	s << "{";
@@ -1706,6 +1946,9 @@ inline std::ostream & operator <<(std::ostream & s, const PIVector<T> & v) {
 }
 #endif
 
+//! \relatesalso PICout
+//! \~english Output operator to \a PICout
+//! \~russian Оператор вывода в \a PICout
 template<typename T>
 inline PICout operator <<(PICout s, const PIVector<T> & v) {
 	s.space();
@@ -1722,7 +1965,8 @@ inline PICout operator <<(PICout s, const PIVector<T> & v) {
 	return s;
 }
 
-template<typename T> inline void piSwap(PIVector<T> & f, PIVector<T> & s) {f.swap(s);}
+template<typename T>
+inline void piSwap(PIVector<T> & f, PIVector<T> & s) {f.swap(s);}
 
 
 #endif // PIVECTOR_H