193 lines
9.9 KiB
C++
193 lines
9.9 KiB
C++
/*
|
||
PIP - Platform Independent Primitives
|
||
Containers
|
||
Ivan Pelipenko peri4ko@yandex.ru, Andrey Bychkov work.a.b@yandex.ru
|
||
|
||
This program is free software: you can redistribute it and/or modify
|
||
it under the terms of the GNU Lesser General Public License as published by
|
||
the Free Software Foundation, either version 3 of the License, or
|
||
(at your option) any later version.
|
||
|
||
This program is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
GNU Lesser General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Lesser General Public License
|
||
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||
*/
|
||
//! \defgroup Containers Containers
|
||
//! \~\brief
|
||
//! \~english Various standart containers realization
|
||
//! \~russian Различные классы контейнеров
|
||
//!
|
||
//! \~\details
|
||
//! \~english \section cmake_module_Containers Building with CMake
|
||
//! \~russian \section cmake_module_Containers Сборка с использованием CMake
|
||
//!
|
||
//! \~\code
|
||
//! find_package(PIP REQUIRED)
|
||
//! target_link_libraries([target] PIP)
|
||
//! \endcode
|
||
//!
|
||
//! \~english \section containers_module_list Content
|
||
//! \~russian \section containers_module_list Состав
|
||
//!
|
||
//! \~english
|
||
//! Class | Description
|
||
//! ------------- | -----------
|
||
//! \a PIVector | Linear array, fast back insert
|
||
//! \a PIDeque | Linear array, fast back and front insert
|
||
//! \a PIMap | Dictionary container, key/value array
|
||
//! \a PISet | Set container
|
||
//! \a PIStack | Stack
|
||
//! \a PIQueue | Queue
|
||
//! \a PIPair | Pair
|
||
//! \a PIVector2D | Linear 2D rectangle array
|
||
//!
|
||
//! \~russian
|
||
//! Класс | Описание
|
||
//! ------------- | -----------
|
||
//! \a PIVector | Линейный массив, быстрое добавление в конец
|
||
//! \a PIDeque | Линейный массив, быстрое добавление вначало и конец
|
||
//! \a PIMap | Массив ключ/значение, словарь
|
||
//! \a PISet | Множество
|
||
//! \a PIStack | Стек
|
||
//! \a PIQueue | Очередь
|
||
//! \a PIPair | Пара
|
||
//! \a PIVector2D | Линейный двумерный прямоугольный массив
|
||
//!
|
||
//!
|
||
//! \~english \section stl_iterators STL-Style Iterators
|
||
//! \~russian \section stl_iterators Итераторы в стиле STL
|
||
//! \~english
|
||
//! \brief They are compatible with Qt's and STL's generic algorithms and are optimized for speed.
|
||
//! \details
|
||
//! For each container class, there are two STL-style iterator types:
|
||
//! one that provides read-only access and one that provides read-write access.
|
||
//! Read-only iterators should be used wherever possible
|
||
//! because they are faster than read-write iterators.
|
||
//! Read-only iterator - `const_iterator.`
|
||
//! Read-write iterator - `iterator.`
|
||
//!
|
||
//! The API of the STL iterators is modelled on pointers in an array.
|
||
//! For example, the `++` operator advances the iterator to the next item,
|
||
//! and the `*` operator returns the item that the iterator points to.
|
||
//! The `iterator` type is just a `typedef` for `T *`,
|
||
//! and the `const_iterator` type is just a `typedef` for `const T *`.
|
||
//! STL-style iterators point directly at items.
|
||
//! The `begin()` function of a container
|
||
//! returns an iterator that points to the first item in the container.
|
||
//! The `end()` function of a container returns an iterator to the imaginary item
|
||
//! one position past the last item in the container.
|
||
//! `end()` marks an invalid position; it must never be dereferenced.
|
||
//! It is typically used in a loop's break condition.
|
||
//!
|
||
//! Example:
|
||
//! \code
|
||
//! for (PIVector<int>::const_iterator i = v.begin(); i != v.end(); ++i) piCout << *i;
|
||
//! std::for_each(v.begin(), v.end(), [](int n){std::cout << n << ' ';});
|
||
//! \endcode
|
||
//!
|
||
//! If the list is empty, `begin()` equals `end()`, so we never execute the loop.
|
||
//!
|
||
//! 
|
||
//!
|
||
//! The following table summarizes the STL-style iterators' API:
|
||
//! Expression | Behavior
|
||
//! ---------- | --------------------
|
||
//! `*i` | Returns the current item
|
||
//! `++i` | Advances the iterator to the next item
|
||
//! `i += n` | Advances the iterator by `n` items
|
||
//! `--i` | Moves the iterator back by one item
|
||
//! `i -= n` | Moves the iterator back by `n` items
|
||
//! `i - j` | Returns the number of items between iterators `i` and `j`
|
||
//!
|
||
//! The `++` and `--` operators are available both as prefix `(++i, --i)`
|
||
//! and postfix `(i++, i--)` operators.
|
||
//! The prefix versions modify the iterators
|
||
//! and return a reference to the modified iterator;
|
||
//! the postfix versions take a copy of the iterator before they modify it, and return that copy.
|
||
//! In expressions where the return value is ignored,
|
||
//! we recommend that you use the prefix operators `(++i, --i)`, as these are slightly faster.
|
||
//! For non-const iterator types, the return value of the unary `*` operator
|
||
//! can be used on the left side of the assignment operator.
|
||
//!
|
||
//! \~russian
|
||
//! \brief Они совместимы с базовыми алгоритмами Qt и STL и оптимизированы по скорости.
|
||
//! \details
|
||
//! Для каждого контейнерного класса есть два типа итераторов в стиле STL:
|
||
//! один из них предоставляет доступ только для чтения, а другой - доступ для чтения-записи.
|
||
//! Итераторы только для чтения должны использоваться везде, где это только возможно,
|
||
//! так как они быстрее, чем итераторы для чтения-записи.
|
||
//! Итератор только для чтения - `const_iterator.`
|
||
//! Итератор для чтения-записи - `iterator.`
|
||
//!
|
||
//! API итераторов в стиле STL сделан по образцу указателей в массиве.
|
||
//! Например, оператор `++` перемещает итератор к следующему элементу,
|
||
//! а оператор `*` возвращает элемент, на который позиционирован итератор.
|
||
//! Тип `iterator` - это как `typedef` для `T *`,
|
||
//! а тип `const_iterator` - как `typedef` для `const T *`.
|
||
//! Итераторы в стиле STL указывают непосредственно на элемент.
|
||
//! Функция контейнера `begin()` возвращает итератор, указывающий на первый элемент контейнера.
|
||
//! Функция контейнера `end()` возвращает итератор, указывающий на воображаемый элемент,
|
||
//! находящийся в позиции, следующей за последним элементом контейнера.
|
||
//! `end()` обозначает несуществующую позицию;
|
||
//! он никогда не должен разыменовываться.
|
||
//! Обычно, он используется, как условие выхода из цикла.
|
||
//!
|
||
//! Например:
|
||
//! \code
|
||
//! for (PIVector<int>::const_iterator i = v.begin(); i != v.end(); ++i) piCout << *i;
|
||
//! std::for_each(v.begin(), v.end(), [](int n){std::cout << n << ' ';});
|
||
//! \endcode
|
||
//!
|
||
//! Если список пуст, то begin() равен end(), поэтому цикл никогда не выполнится.
|
||
//!
|
||
//! 
|
||
//!
|
||
//! В следующей таблице подводится итог API итераторов в стиле STL:
|
||
//! Выражение | Поведение
|
||
//! --------- | --------------------
|
||
//! `*i` | Возвращает текущий элемент
|
||
//! `++i` | Перемещает итератор к следующему элементу
|
||
//! `i += n` | Перемещает итератор вперед на `n` элементов
|
||
//! `--i` | Перемещает итератор на один элемент назад
|
||
//! `i -= n` | Перемещает итератор назад на `n` элементов
|
||
//! `i - j` | Возвращает количество элементов, находящихся между итераторами `i` и `j`
|
||
//!
|
||
//! Оба оператора `++` и `--` могут использоваться и как префиксные `(++i, --i)`
|
||
//! и как постфиксные `(i++, i--)` операторы.
|
||
//! Префиксная версия изменяет итератор, и возвращает ссылку на измененный итератор;
|
||
//! постфиксная версия, берет копию итератора перед его изменением, и возвращает эту копию.
|
||
//! В выражениях, в которых возвращаемое значение игнорируется,
|
||
//! мы рекомендуем использовать префиксную версию `(++i, --i)`,
|
||
//! так как она несколько быстрее.
|
||
//!
|
||
//! Для неконстантных итераторов, возвращаемое значение унарного оператора `*`
|
||
//! может быть использовано с левой стороны от оператора присваивания.
|
||
//!
|
||
//!
|
||
//! \authors
|
||
//! \~english
|
||
//! Ivan Pelipenko peri4ko@yandex.ru;
|
||
//! Andrey Bychkov work.a.b@yandex.ru;
|
||
//! \~russian
|
||
//! Иван Пелипенко peri4ko@yandex.ru;
|
||
//! Андрей Бычков work.a.b@yandex.ru;
|
||
|
||
|
||
#ifndef PICONTAINERSMODULE_H
|
||
#define PICONTAINERSMODULE_H
|
||
|
||
#include "pivector.h"
|
||
#include "pideque.h"
|
||
#include "pimap.h"
|
||
#include "piqueue.h"
|
||
#include "piset.h"
|
||
#include "pistack.h"
|
||
#include "pivector2d.h"
|
||
|
||
|
||
#endif // PICONTAINERSMODULE_H
|