pivector doc

libs/main/containers/pivector.h

@@ -1819,12 +1819,41 @@ public:
 		return ret;
 	}
 
+	//! \brief
+	//! \~english Execute function `void f(const T & e)` for every element in array.
+	//! \~russian Выполняет функцию `void f(const T & e)` для каждого элемента массива.
+	//! \~\details
+	//! \~russian Не позволяет изменять элементы массива.
+	//! Для редактирования элементов используйте функцию вида `void f(T & e)`.
+	//! \~english Does not allow changing array elements.
+	//! To edit elements, use the function like `void f(T & e)`
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3, 4, 5};
+	//! int s = 0;
+	//! v.forEach([&s](const int & e){s += e;});
+	//! piCout << s; // 15
+	//! \endcode
+	//! \~\sa \a map(), \a reduce()
 	inline void forEach(std::function<void(const T & e)> f) const {
 		for (size_t i = 0; i < piv_size; ++i) {
 			f(piv_data[i]);
 		}
 	}
 
+	//! \brief
+	//! \~english Execute function `void f(T & e)` for every element in array.
+	//! \~russian Выполняет функцию `void f(T & e)` для каждого элемента массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! Allows you to change the elements of the array.
+	//! \~russian Перегруженая функция.
+	//! Позволяет изменять элементы массива.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3, 4, 5};
+	//! v.forEach([](int & e){e++;});
+	//! piCout << v; // {2, 3, 4, 5, 6}
+	//! \endcode
+	//! \~\sa \a map(), \a reduce()
 	inline PIVector<T> & forEach(std::function<void(T & e)> f) {
 		for (size_t i = 0; i < piv_size; ++i) {
 			f(piv_data[i]);
@@ -1832,6 +1861,24 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Сreates a new array populated with the results
+	//! of calling a provided function `ST f(const T & e)` on every element in the calling array.
+	//! \~russian Создаёт новый массив с результатом вызова указанной функции
+	//! `ST f(const T & e)` для каждого элемента массива.
+	//! \~\details
+	//! \~english Calls a provided function`ST f(const T & e)`
+	//! once for each element in an array, in order,
+	//! and constructs a new array from the results.
+	//! \~russian Метод `map` вызывает переданную функцию `ST f(const T & e)`
+	//! один раз для каждого элемента, в порядке их появления
+	//! и конструирует новый массив из результатов её вызова.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! PIStringList sl = v.map<PIString>([](const int & i){return PIString::fromNumber(i);});
+	//! piCout << sl; {"1", "2", "3"}
+	//! \endcode
+	//! \~\sa \a forEach(), \a reduce()
 	template <typename ST>
 	inline PIVector<ST> map(std::function<ST(const T & e)> f) const {
 		PIVector<ST> ret; ret.reserve(piv_size);
@@ -1841,6 +1888,48 @@ public:
 		return ret;
 	}
 
+	//! \brief
+	//! \~english Applies the function `ST f(const T & e, const ST & acc)`
+	//! to each element of the array (from left to right), returns one value.
+	//! \~russian Применяет функцию `ST f(const T & e, const ST & acc)`
+	//! к каждому элементу массива (слева-направо), возвращает одно значение.
+	//! \~\details
+	//! \~english The reduce() method performs the `f` function
+	//! once for each element in the array.
+	//! If the `initial` argument is passed when calling reduce(),
+	//! then when the function `f` is called for the first time,
+	//! the value of `acc` will be assigned to `initial`.
+	//! If the array is empty, the value `initial` will be returned.
+	//! \param f is a function like `ST f(const T & e, const ST & acc)`,
+	//! executed for each element of the array. It takes two arguments:
+	//! * **e** - current element of the array
+	//! * **acc** - accumulator accumulating the value
+	//! which this function returns after visiting the next element
+	//!
+	//! \param initial _optional_ Object used as the second argument
+	//! when the `f` function is first called.
+	//! \~russian Метод reduce() выполняет функцию `f`
+	//! один раз для каждого элемента, присутствующего в массиве.
+	//! Если при вызове reduce() передан аргумент `initial`,
+	//! то при первом вызове функции `f` значение `acc`
+	//! будет равным значению `initial`.
+	//! Если массив пустой то будет возвращено значение `initial`.
+	//! \param f Функция, вида `ST f(const T & e, const ST & acc)`,
+	//! выполняющаяся для каждого элемента массива.
+	//! Она принимает два аргумента:
+	//! * **e** - текущий элемент массива
+	//! * **acc** - аккумулятор, аккумулирующий значение
+	//! которое возвращает эта функция после посещения очередного элемента
+	//!
+	//! \param initial _опциональный_ Объект,
+	//! используемый в качестве второго аргумента при первом вызове функции `f`.
+	//!
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3, 4, 5};
+	//! int s = v.reduce<int>([](const int & e, const int & acc){return e + acc;});
+	//! piCout << s; // 15
+	//! \endcode
+	//! \~\sa \a forEach(), \a map()
 	template <typename ST>
 	inline ST reduce(std::function<ST(const T & e, const ST & acc)> f, const ST & initial = ST()) const {
 		ST ret(initial);