SHS/pip
4
3
Fork 0
Code Issues 67 Pull Requests 1 Actions Releases Wiki Activity

PIVector doc

Browse Source
This commit is contained in:
Andrey
2022-03-31 17:49:18 +03:00
parent 1edd9e4c55
commit 0194e3f6b6
1 changed files with 58 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
libs/main/containers/pivector.h
View File

@@ -50,9 +50,12 @@
//! 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
//! 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().
//!
//! The storage of the vector is handled automatically,
//! being expanded and contracted as needed.
//! being expanded as needed.
//! Vectors 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,
@@ -72,9 +75,12 @@
//! но и с помощью смещений для обычных указателей на элементы.
//! Это означает, что указатель на элемент вектора может передаваться в любую функцию,
//! ожидающую указатель на элемент массива.
//! Добавить элементы можно с помощью функции \a append() или \a insert(),
//! а удалить с помощью \a remove() или \a clear().
//! Изменить размер можно функцией \a resize().
//!
//! Память вектора обрабатывается автоматически,
//! расширяясь и сжимаясь по мере необходимости.
//! расширяясь по мере необходимости.
//! Векторы обычно занимают больше места, чем статические массивы,
//! поскольку больше памяти выделяется для обработки будущего роста.
//! Таким образом, память для вектора требуется выделять
@@ -204,8 +210,8 @@ public:
}
//! \~\brief
//! \~english Reshape order enum for \a reshape function.
//! \~russian Порядок обхода для функции изменения размерности \a reshape.
//! \~english Reshape order enum for \a reshape() function.
//! \~russian Порядок обхода для функции изменения размерности \a reshape().
enum ReshapeOrder {
byRow,
byColumn
@@ -286,10 +292,10 @@ public:
//! \~russian Итератор на первый элемент.
//! \~\details ![begin, end](doc/images/pivector_begin.png)
//!
//! \~english If the vector is empty, the returned iterator is equal to \a end.
//! \~russian Если массив - пуст, возвращаемый итератор будет равен \a end.
//! \~english If the vector is empty, the returned iterator is equal to \a end().
//! \~russian Если массив - пуст, возвращаемый итератор будет равен \a end().
//! \~\return \ref stl_iterators
//! \~\sa \a end, \a rbegin, \a rend
//! \~\sa \a end(), \a rbegin(), \a rend()
inline iterator begin() {return iterator(this, 0);}
//! \~\brief
@@ -302,7 +308,7 @@ public:
//! \~russian Этот элемент существует лишь условно,
//! попытка доступа к нему приведёт к выходу за разрешенную память.
//! \~\return \ref stl_iterators
//! \~\sa \a begin, \a rbegin, \a rend
//! \~\sa \a begin(), \a rbegin(), \a rend()
inline iterator end() {return iterator(this, piv_size);}
inline const_iterator begin() const {return const_iterator(this, 0);}
@@ -314,12 +320,12 @@ public:
//! \~\details ![rbegin, rend](doc/images/pivector_rbegin.png)
//!
//! \~english It corresponds to the last element of the non-reversed vector.
//! If the vector is empty, the returned iterator is equal to \a rend.
//! If the vector is empty, the returned iterator is equal to \a rend().
//! \~russian Итератор для прохода массива в обратном порядке.
//! Указывает на последний элемент.
//! Если массив пустой, то совпадает с итератором \a rend.
//! Если массив пустой, то совпадает с итератором \a rend().
//! \~\return \ref stl_iterators
//! \~\sa \a rend, \a begin, \a end
//! \~\sa \a rend(), \a begin(), \a end()
inline reverse_iterator rbegin() {return reverse_iterator(this, piv_size - 1);}
//! \~\brief
@@ -335,7 +341,7 @@ public:
//! Этот элемент существует лишь условно,
//! попытка доступа к нему приведёт к выходу за разрешенную память.
//! \~\return \ref stl_iterators
//! \~\sa \a rbegin, \a begin, \a end
//! \~\sa \a rbegin(), \a begin(), \a end()
inline reverse_iterator rend() {return reverse_iterator(this, -1);}
inline const_reverse_iterator rbegin() const {return const_reverse_iterator(this, piv_size - 1);}
@@ -344,19 +350,19 @@ public:
//! \~\brief
//! \~english Number of elements in the container.
//! \~russian Количество элементов массива.
//! \~\sa \a size_s, \a capacity, \a isEmpty, \a isNotEmpty, \a resize, \a reserve
//! \~\sa \a size_s(), \a capacity(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve()
inline size_t size() const {return piv_size;}
//! \~\brief
//! \~english Number of elements in the container as signed value.
//! \~russian Количество элементов массива в виде знакового числа.
//! \~\sa \a size, \a capacity, \a isEmpty, \a isNotEmpty, \a resize, \a reserve
//! \~\sa \a size(), \a capacity(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve()
inline ssize_t size_s() const {return piv_size;}
//! \~\brief
//! \~english Same as \a size.
//! \~russian Синоним \a size.
//! \~\sa \a size \a size_s, \a capacity, \a isEmpty, \a isNotEmpty, \a resize, \a reserve
//! \~english Same as \a size().
//! \~russian Синоним \a size().
//! \~\sa \a size(), \a size_s(), \a capacity(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve()
inline size_t length() const {return piv_size;}
//! \~\brief
@@ -365,7 +371,7 @@ public:
//! \~\details
//! \~english To find out the actual number of items, use the function \a size().
//! \~russian Чтобы узнать фактическое количество элементов используйте функцию \a size().
//! \~\sa \a reserve, \a size \a size_s
//! \~\sa \a reserve(), \a size(), \a size_s()
inline size_t capacity() const {return piv_rsize;}
//! \~\brief
@@ -374,7 +380,7 @@ public:
//! \~\return
//! \~english **true** if the container is empty, **false** otherwise
//! \~russian **true** если контейнер пуст, **false** иначе.
//! \~\sa \a size \a size_s, \a isEmpty, \a isNotEmpty, \a resize, \a reserve
//! \~\sa \a size(), \a size_s(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve()
inline bool isEmpty() const {return (piv_size == 0);}
//! \~\brief
@@ -383,7 +389,7 @@ public:
//! \~\return
//! \~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
//! \~\sa \a size(), \a size_s(), \a isEmpty(), \a isNotEmpty(), \a resize(), \a reserve()
inline bool isNotEmpty() const {return (piv_size > 0);}
//! \~\brief
@@ -404,7 +410,7 @@ public:
//! 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
//! \~\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;
@@ -430,7 +436,7 @@ public:
//! 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
//! \~\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;
@@ -454,7 +460,7 @@ public:
//! v[2] = 5;
//! piCout << v; // 1, 2, 5, 9
//! \endcode
//! \~\sa \a at
//! \~\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];}
@@ -548,7 +554,7 @@ public:
//! otherwise it returns **false**.
//! \~russian **true** если элемент `e` присутствует в массиве,
//! в остальных случаях **false**.
//! \~\sa \a every, \a any, \a etries, \a forEach
//! \~\sa \a every(), \a any(), \a etries(), \a forEach()
inline bool contains(const T & e, ssize_t start = 0) const {
if (start < 0) {
start = piv_size + start;
@@ -585,7 +591,7 @@ public:
//! piCout << v.entries(2, 2); // 1
//! piCout << v.entries(2, -4); // 2
//! \endcode
//! \~\sa \a every, \a any, \a contains, \a forEach, \a indexOf
//! \~\sa \a every(), \a any(), \a contains(), \a forEach(), \a indexOf()
inline int entries(const T & e, ssize_t start = 0) const {
int ec = 0;
if (start < 0) {
@@ -620,7 +626,7 @@ public:
//! Если рассчитанный индекс все равно оказывается меньше 0, просматривается весь массив.
//! Обратите внимание: если индекс отрицателен, массив всё равно просматривается от начала к концу.
//! Значение по умолчанию равно 0, что означает, что просматривается весь массив.
//! \~\sa \a every, \a any, \a contains, \a forEach, \a indexWhere
//! \~\sa \a every(), \a any(), \a contains(), \a forEach(), \a indexWhere()
inline int entries(std::function<bool(const T & e)> test, ssize_t start = 0) const {
int ec = 0;
if (start < 0) {
@@ -662,7 +668,7 @@ public:
//! piCout << v.indexOf(2, -1); // -1
//! piCout << v.indexOf(2, -3); // 0
//! \endcode
//! \~\sa \a indexWhere, \a lastIndexOf, \a lastIndexWhere, \a contains
//! \~\sa \a indexWhere(), \a lastIndexOf(), \a lastIndexWhere(), \a contains()
inline ssize_t indexOf(const T & e, ssize_t start = 0) const {
if (start < 0) {
start = piv_size + start;
@@ -702,7 +708,7 @@ public:
//! piCout << v.indexWhere([](const PIString & s){return s.startsWith('r');}, 2); // 3
//! piCout << v.indexWhere([](const PIString & s){return s.startsWith('k');}); // -1
//! \endcode
//! \~\sa \a indexOf, \a lastIndexOf, \a lastIndexWhere, \a contains
//! \~\sa \a indexOf(), \a lastIndexOf(), \a lastIndexWhere(), \a contains()
inline ssize_t indexWhere(std::function<bool(const T & e)> test, ssize_t start = 0) const {
if (start < 0) {
start = piv_size + start;
@@ -748,7 +754,7 @@ public:
//! piCout << v.lastIndexOf(2, -300); // -1
//! piCout << v.lastIndexOf(2, 300); // 3
//! \endcode
//! \~\sa \a indexOf, \a indexWhere, \a lastIndexWhere, \a contains
//! \~\sa \a indexOf(), \a indexWhere(), \a lastIndexWhere(), \a contains()
inline ssize_t lastIndexOf(const T & e, ssize_t start = -1) const {
if (start >= size_s()) start = piv_size - 1;
if (start < 0) start = piv_size + start;
@@ -783,7 +789,7 @@ public:
//! Если рассчитанный индекс оказывается меньше 0, массив даже не просматривается.
//! Значение по умолчанию равно `-1`, что равно индексу последнего элемента
//! и означает, что просматривается весь массив.
//! \~\sa \a indexOf, \a lastIndexOf, \a indexWhere, \a contains
//! \~\sa \a indexOf(), \a lastIndexOf(), \a indexWhere(), \a contains()
inline ssize_t lastIndexWhere(std::function<bool(const T & e)> test, ssize_t start = -1) const {
if (start >= size_s()) start = piv_size - 1;
if (start < 0) start = piv_size + start;
@@ -858,7 +864,7 @@ public:
//! \~\details
//! \~english Note: reserved memory will not be released.
//! \~russian Замечание: зарезервированная память не освободится.
//! \~\sa \a resize
//! \~\sa \a resize()
template<typename T1 = T, typename std::enable_if<
!std::is_trivially_copyable<T1>::value
, int>::type = 0>
@@ -884,7 +890,7 @@ public:
//! v.fill(7);
//! piCout << v; // 7, 7, 7
//! \endcode
//! \~\sa \a resize
//! \~\sa \a resize()
inline PIVector<T> & fill(const T & f = T()) {
deleteT(piv_data, piv_size);
PIINTROSPECTION_CONTAINER_USED(T, piv_size)
@@ -903,7 +909,7 @@ public:
//! v.fill([](size_t i){return i*2;});
//! piCout << v; // 0, 2, 4
//! \endcode
//! \~\sa \a resize
//! \~\sa \a resize()
inline PIVector<T> & fill(std::function<T(size_t i)> f) {
deleteT(piv_data, piv_size);
PIINTROSPECTION_CONTAINER_USED(T, piv_size)
@@ -914,16 +920,16 @@ public:
}
//! \~\brief
//! \~english Same as \a fill.
//! \~russian Тоже самое что и \a fill.
//! \~\sa \a fill, \a resize
//! \~english Same as \a fill().
//! \~russian Тоже самое что и \a fill().
//! \~\sa \a fill(), \a resize()
inline PIVector<T> & assign(const T & f = T()) {return fill(f);}
//! \~\brief
//! \~english First does `resize(new_size)` then `fill(f)`.
//! \~russian Сначала делает `resize(new_size)` затем `fill(f)`.
//! \~\sa \a fill, \a resize
//! \~\sa \a fill(), \a resize()
template<typename T1 = T, typename std::enable_if<
!std::is_trivially_copyable<T1>::value
, int>::type = 0>
@@ -943,14 +949,14 @@ public:
//! \~english Sets size of the array, new elements are copied from `f`.
//! \~russian Устанавливает размер массива, новые элементы копируются из `f`.
//! \~\details
//! \~english If `new_size` is greater than the current \a size,
//! \~english If `new_size` is greater than the current \a size(),
//! elements are added to the end; the new elements are initialized from `f`.
//! If `new_size` is less than the current \a size, elements are removed from the end.
//! \~russian Если `new_size` больше чем текущий размер массива \a size,
//! If `new_size` is less than the current \a size(), elements are removed from the end.
//! \~russian Если `new_size` больше чем текущий размер массива \a size(),
//! новые элементы добавляются в конец массива и создаются из `f`.
//! Если `new_size` меньше чем текущий размер массива \a size,
//! Если `new_size` меньше чем текущий размер массива \a size(),
//! лишние элементы удаляются с конца массива.
//! \~\sa \a size, \a clear
//! \~\sa \a size(), \a clear()
inline PIVector<T> & resize(size_t new_size, const T & f = T()) {
if (new_size < piv_size) {
T * de = &(piv_data[new_size]);
@@ -972,14 +978,14 @@ public:
//! \~english Sets size of the array, new elements created by function `f(size_t i)`.
//! \~russian Устанавливает размер массива, новые элементы создаются функцией `f(size_t i)`.
//! \~\details
//! \~english If `new_size` is greater than the current \a size,
//! \~english If `new_size` is greater than the current \a size(),
//! elements are added to the end; the new elements created by function `f(size_t i)`.
//! If `new_size` is less than the current \a size, elements are removed from the end.
//! \~russian Если `new_size` больше чем текущий размер массива \a size,
//! If `new_size` is less than the current \a size(), elements are removed from the end.
//! \~russian Если `new_size` больше чем текущий размер массива \a size(),
//! новые элементы добавляются в конец массива и функцией `f(size_t i)`.
//! Если `new_size` меньше чем текущий размер массива \a size,
//! Если `new_size` меньше чем текущий размер массива \a size(),
//! лишние элементы удаляются с конца массива.
//! \~\sa \a size, \a clear
//! \~\sa \a size(), \a clear()
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]);
@@ -1021,15 +1027,15 @@ public:
//! \~\details
//! \~english If you know in advance how large the array will be,
//! you should call this function to prevent reallocations and memory fragmentation.
//! If `new_size` is greater than the current \a capacity,
//! If `new_size` is greater than the current \a capacity(),
//! new storage is allocated, otherwise the function does nothing.
//! This function does not change the \a size of the array.
//! This function does not change the \a size() of the array.
//! \~russian Если вы заранее знаете, насколько велик будет массив,
//! вы можете вызвать эту функцию, чтобы предотвратить перераспределение и фрагментацию памяти.
//! Если размер `new_size` больше чем выделенная память \a capacity,
//! Если размер `new_size` больше чем выделенная память \a capacity(),
//! то произойдёт выделение новой памяти и перераспределение массива.
//! Эта функция не изменяет количество элементов в массиве \a size.
//! \~\sa \a size, \a capacity, \a resize
//! Эта функция не изменяет количество элементов в массиве \a size().
//! \~\sa \a size(), \a capacity(), \a resize()
inline PIVector<T> & reserve(size_t new_size) {
if (new_size <= piv_rsize) return *this;
size_t os = piv_size;