ещё правки документации для PIVector и PIDeque

libs/main/containers/pivector.h

@@ -49,24 +49,31 @@
 //! The elements are stored contiguously,
 //! which means that elements can be accessed not only through iterators,
 //! but also using offsets to regular pointers to elements.
-//! This means that a pointer to an element of a vector may be passed to any function
+//! This means that a pointer to an element of a PIVector may be passed to any function
 //! that expects a pointer to an element of an array.
 //! To add elements you can use functions \a append() and \a insert(),
-//! to remove elements you can use functions \a remove() and \a clear().
-//! Change size by function \a resize().
+//! to remove elements you can use functions \a remove() and \a removeOne(), \a removeWhere().
+//! Change size by function \a resize() and \a assign().
+//! Items in an array are numbered, starting from zero.
+//! This number is called the item's index.
+//! So the first item has index 0, the last has index `size() - 1`.
+//! A set of various convenient functions is also available for the array,
+//! for example: \a indexOf, \a contains(), \a entries(), \a isEmpty(), \a isNotEmpty(),
+//! \a every(), \a any(), \a forEach(), \a indexWhere(), \a getRange(), \a sort(),
+//! \a map(), \a reduce(), \a filter(), \a flatten(), \a reshape() and others.
 //!
-//! The storage of the vector is handled automatically,
+//! The storage of the PIVector is handled automatically,
 //! being expanded as needed.
-//! Vectors usually occupy more space than static arrays,
+//! PIVector usually occupy more space than static arrays,
 //! because more memory is allocated to handle future growth.
-//! This way a vector does not need to reallocate each time an element is inserted,
+//! This way a PIVector does not need to reallocate each time an element is inserted,
 //! but only when the additional memory is exhausted.
 //! The total amount of allocated memory can be queried using \a capacity() function.
 //! Reallocations are usually costly operations in terms of performance.
 //! The \a reserve() function can be used to eliminate reallocations
 //! if the number of elements is known beforehand.
 //!
-//! The complexity (efficiency) of common operations on vectors is as follows:
+//! The complexity (efficiency) of common operations on PIVector is as follows:
 //! - Random access - constant 𝓞(1)
 //! - Insertion or removal of elements at the end - amortized constant 𝓞(1)
 //! - Insertion or removal of elements - linear in the distance to the end of the array 𝓞(n)
@@ -74,17 +81,24 @@
 //! \~russian
 //! Элементы хранятся непрерывно, а значит доступны не только через итераторы,
 //! но и с помощью смещений для обычных указателей на элементы.
-//! Это означает, что указатель на элемент вектора может передаваться в любую функцию,
+//! Это означает, что указатель на элемент PIVector может передаваться в любую функцию,
 //! ожидающую указатель на элемент массива.
 //! Добавить элементы можно с помощью функции \a append() или \a insert(),
-//! а удалить с помощью \a remove() или \a clear().
-//! Изменить размер можно функцией \a resize().
+//! а удалить с помощью \a remove() или \a removeOne(), \a removeWhere().
+//! Изменить размер можно функцией \a resize() или \a assign().
+//! Массив индексируется с нуля:
+//! первый элемент массива имеет индекс, равный `0`,
+//! а индекс последнего элемента равен `size() - 1`.
+//! Также для массива доступен набор различных удобных функций,
+//! например: \a indexOf, \a contains(), \a entries(), \a isEmpty(), \a isNotEmpty(),
+//! \a every(), \a any(), \a forEach(), \a indexWhere(), \a getRange(), \a sort(),
+//! \a map(), \a reduce(), \a filter(), \a flatten(), \a reshape() и другие.
 //!
-//! Память вектора обрабатывается автоматически,
+//! Память PIVector обрабатывается автоматически,
 //! расширяясь по мере необходимости.
 //! Векторы обычно занимают больше места, чем статические массивы,
 //! поскольку больше памяти выделяется для обработки будущего роста.
-//! Таким образом, память для вектора требуется выделять
+//! Таким образом, память для PIVector требуется выделять
 //! не при каждой вставке элемента,
 //! а только после исчерпания дополнительной памяти.
 //! Общий объём выделенной памяти можно получить с помощью функции \a capacity().
@@ -94,7 +108,7 @@
 //! Функцию \a reserve() можно использовать для исключения выделения памяти,
 //! если количество элементов известно заранее.
 //!
-//! Сложность (эффективность) обычных операций над векторами следующая:
+//! Сложность (эффективность) обычных операций над PIVector следующая:
 //! - Произвольный доступ — постоянная 𝓞(1)
 //! - Вставка и удаление элементов в конце — амортизированная постоянная 𝓞(1)
 //! - Вставка и удаление элементов — линейная по расстоянию до конца массива 𝓞(n)