PIVector doc

2022-03-29 17:30:58 +03:00
parent 288062cfd6
commit c2ceb710c5
1 changed files with 128 additions and 6 deletions
--- a/libs/main/containers/pivector.h
+++ b/libs/main/containers/pivector.h
@@ -38,7 +38,7 @@

 //! \addtogroup Containers
 //! \{
-//! \class PIVector pivector.h
+//! \class PIVector
 //! \brief
 //! \~english Sequence linear container - dynamic size array of any type.
 //! \~russian Последовательный контейнер с линейной памятью - динамический массив любого типа.
@@ -91,6 +91,8 @@
 //! - Произвольный доступ — постоянная 𝓞(1)
 //! - Вставка и удаление элементов в конце — амортизированная постоянная 𝓞(1)
 //! - Вставка и удаление элементов — линейная по расстоянию до конца вектора 𝓞(n)
+//!
+//! \~\sa \a PIDeueue, \a PIMap
 template <typename T>
 class PIVector {
 public:
@@ -364,19 +366,54 @@ public:

 	//! \~\brief
 	//! \~english Checks if the container has elements.
-	//! \~russian Проверяет пуст ли контейнер.
+	//! \~russian Проверяет не пуст ли контейнер.
 	//! \~\return
-	//! \~english **true** if the container is empty, **false** otherwise
-	//! \~russian **true** если контейнер пуст, **false** иначе.
+	//! \~english **true** if the container is not empty, **false** otherwise
+	//! \~russian **true** если контейнер не пуст, **false** иначе.
 	//! \~\sa \a size \a size_s, \a isEmpty, \a isNotEmpty, \a resize, \a reserve
 	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`.
+	//! \~russian Проверяет, удовлетворяет ли какой-либо элемент массива условию, заданному в передаваемой функции `test`.
+	//! \~\return
+	//! \~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**,
+	//! в остальных случаях **false**.
+	//! Метод возвращает **false** при любом условии для пустого массива.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 8, 9};
+	//! piCout << v.any([](int e){return e % 2 == 0;});
+	//! // true
+	//! piCout << v.any([](int e){return e == 3;});
+	//! // false
+	//! \endcode
+	//! \~\sa \a every, \a contains, \a etries, \a forEach
 	inline bool any(std::function<bool(const T & e)> test) const {
 		for (size_t i = 0; i < piv_size; ++i) {
 			if (test(piv_data[i])) return true;
 		}
 		return false;
 	}
+
+	//! \~\brief
+	//! \~english Tests whether all elements in the array 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**;
+	//!  otherwise it returns **false**. Always returns **true** if is empty.
+	//! \~russian **true** если для всех элементов передаваемая функция возвращает **true**,
+	//! в остальных случаях **false**.
+	//! Метод возвращает **true** при любом условии для пустого массива.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 8, 9};
+	//! piCout << v.every([](int e){return e % 2 == 0;});
+	//! // false
+	//! piCout << v.every([](int e){return e > 0;});
+	//! // true
+	//! \endcode
+	//! \~\sa \a any, \a contains, \a entries, \a forEach
 	inline bool every(std::function<bool(const T & e)> test) const {
 		for (size_t i = 0; i < piv_size; ++i) {
 			if (!test(piv_data[i])) return false;
@@ -384,13 +421,69 @@ public:
 		return true;
 	}

+	//! \brief
+	//! \~english Full access to element by `index`.
+	//! \~russian Полный доступ к элементу по индексу `index`.
+	//! \~\details
+	//! \~english Element index starts from `0`.
+	//! Element index must be in range from `0` to `size()-1`.
+	//! Otherwise will be undefined behavior.
+	//! \~russian Индекс элемента считается от `0`.
+	//! Индекс элемента должен лежать в пределах от `0` до `size()-1`.
+	//! Иначе это приведёт к неопределённому поведению программы и ошибкам памяти.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 8, 9};
+	//! piCout << v[2];
+	//! // 8
+	//! v[2] = 5;
+	//! piCout << v;
+	//! // 1, 2, 5, 9
+	//! \endcode
+	//! \~\sa \a at
 	inline T & operator [](size_t index) {return piv_data[index];}
 	inline const T & operator [](size_t index) const {return piv_data[index];}
+
+	//! \brief
+	//! \~english Read only access to element by `index`.
+	//! \~russian Доступ исключительно на чтение к элементу по индексу `index`.
+	//! \~\details
+	//! \~english Element index starts from `0`.
+	//! Element index must be in range from `0` to `size()-1`.
+	//! Otherwise will be undefined behavior.
+	//! \~russian Индекс элемента считается от `0`.
+	//! Индекс элемента должен лежать в пределах от `0` до `size()-1`.
+	//! Иначе это приведёт к неопределённому поведению программы и ошибкам памяти.
 	inline const T & at(size_t index) const {return piv_data[index];}
+
+	//! \brief
+	//! \~english Last element.
+	//! \~russian Последний элемент массива.
+	//! \~\details
+	//! \~english Returns a reference to the last item in the vector.
+	//! This function assumes that the vector isn't empty.
+	//! Otherwise will be undefined behavior.
+	//! \~russian Возвращает ссылку на последний элемент в массиве.
+	//! Эта функция предполагает, что массив не пустой.
+	//! Иначе это приведёт к неопределённому поведению программы и ошибкам памяти.
 	inline T & back() {return piv_data[piv_size - 1];}
 	inline const T & back() const {return piv_data[piv_size - 1];}
+
+	//! \brief
+	//! \~english Last element.
+	//! \~russian Первый элемент массива.
+	//! \~\details
+	//! \~english Returns a reference to the last item in the vector.
+	//! This function assumes that the vector isn't empty.
+	//! Otherwise will be undefined behavior.
+	//! \~russian Возвращает ссылку на пенрвый элемент в массиве.
+	//! Эта функция предполагает, что массив не пустой.
+	//! Иначе это приведёт к неопределённому поведению программы и ошибкам памяти.
 	inline T & front() {return piv_data[0];}
 	inline const T & front() const {return piv_data[0];}
+
+	//! \brief
+	//! \~english Compare operator with vector `t`.
+	//! \~russian Оператор сравнения с массивом `t`.
 	inline bool operator ==(const PIVector<T> & t) const {
 		if (piv_size != t.piv_size) {
 			return false;
@@ -402,7 +495,12 @@ public:
 		}
 		return true;
 	}
+
+	//! \brief
+	//! \~english Compare operator with vector `t`.
+	//! \~russian Оператор сравнения с массивом `t`.
 	inline bool operator !=(const PIVector<T> & t) const {return !(*this == t);}
+
 	inline bool operator <(const PIVector<T> & t) const {
 		if (piv_size != t.piv_size) return piv_size < t.piv_size;
 		for (size_t i = 0; i < piv_size; ++i) {
@@ -417,6 +515,21 @@ public:
 		}
 		return false;
 	}
+
+	//! \~\brief
+	//! \~english Tests if element `e` exists in the array.
+	//! \~russian Проверяет наличие элемента `e` в массиве.
+	//! \~\return
+	//! \~english **true** if the array contains an occurrence of element `e`,
+	//! otherwise it returns **false**.
+	//! \~russian **true** если элемент `e` присутствует в массиве,
+	//! в остальных случаях **false**.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3, 4};
+	//! piCout << v.contains(3);
+	//! // true
+	//! \endcode
+	//! \~\sa \a every, \a any, \a etries, \a forEach
 	inline bool contains(const T & e) const {
 		for (size_t i = 0; i < piv_size; ++i) {
 			if (e == piv_data[i]) {
@@ -425,7 +538,8 @@ public:
 		}
 		return false;
 	}
-	inline int etries(const T & e, size_t start = 0) const {
+
+	inline int entries(const T & e, size_t start = 0) const {
 		int ec = 0;
 		if (start >= piv_size) return ec;
 		for (size_t i = start; i < piv_size; ++i) {
@@ -433,7 +547,8 @@ public:
 		}
 		return ec;
 	}
-	inline int etries(std::function<bool(const T & e)> test, size_t start = 0) const {
+
+	inline int entries(std::function<bool(const T & e)> test, size_t start = 0) const {
 		int ec = 0;
 		if (start >= piv_size) return ec;
 		for (size_t i = start; i < piv_size; ++i) {
@@ -441,6 +556,7 @@ public:
 		}
 		return ec;
 	}
+
 	inline ssize_t indexOf(const T & e, size_t start = 0) const {
 		if (start >= piv_size) return -1;
 		for (size_t i = start; i < piv_size; ++i) {
@@ -450,6 +566,7 @@ public:
 		}
 		return -1;
 	}
+
 	inline ssize_t indexWhere(std::function<bool(const T & e)> test, size_t start = 0) const {
 		if (start >= piv_size) return -1;
 		for (size_t i = start; i < piv_size; ++i) {
@@ -459,6 +576,7 @@ public:
 		}
 		return -1;
 	}
+
 	inline ssize_t lastIndexOf(const T & e, ssize_t start = -1) const {
 		if (start < 0) start = piv_size - 1;
 		else start = piMin<ssize_t>(piv_size - 1, start);
@@ -469,6 +587,7 @@ public:
 		}
 		return -1;
 	}
+
 	inline ssize_t lastIndexWhere(std::function<bool(const T & e)> test, ssize_t start = -1) const {
 		if (start < 0) start = piv_size - 1;
 		else start = piMin<ssize_t>(piv_size - 1, start);
@@ -521,6 +640,7 @@ public:
 		}
 		return *this;
 	}
+
 	inline PIVector<T> & assign(const T & f = T()) {return fill(f);}
 	template<typename T1 = T, typename std::enable_if<
 				 !std::is_trivially_copyable<T1>::value
@@ -553,6 +673,7 @@ public:
 		}
 		return *this;
 	}
+
 	inline PIVector<T> & resize(size_t new_size, std::function<T(size_t i)> f) {
 		if (new_size < piv_size) {
 			T * de = &(piv_data[new_size]);
@@ -569,6 +690,7 @@ public:
 		}
 		return *this;
 	}
+
 	template<typename T1 = T, typename std::enable_if<
 				 std::is_trivially_copyable<T1>::value
 				 , int>::type = 0>