picontainers doc, PIVector doc
This commit is contained in:
Andrey
@@ -16,30 +16,139 @@
|
||||
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
|
||||
* \~\brief
|
||||
* \~english This module contains various standart containers realization.
|
||||
* \~russian Модуль содержит основные классы контейнеров.
|
||||
*
|
||||
* \~\details
|
||||
* Scope | Use
|
||||
* ----- | -------
|
||||
* C++ | #include <picontainersmodule.h>
|
||||
* CMake | PIP
|
||||
*
|
||||
* \~english This includes
|
||||
* \~russian В него входят
|
||||
* \~ \a PIVector, \a PIDeque, \a PIMap, \a PISet,
|
||||
* \a PIStack, \a PIQueue, \a PIPair, \a PIVector2D.
|
||||
*
|
||||
* \authors
|
||||
* \~english
|
||||
* Ivan Pelipenko peri4ko@yandex.ru;
|
||||
* Andrey Bychkov work.a.b@yandex.ru;
|
||||
* \~russian
|
||||
* Иван Пелипенко peri4ko@yandex.ru;
|
||||
* Андрей Бычков work.a.b@yandex.ru;
|
||||
*/
|
||||
//! \defgroup Containers
|
||||
//! \~\brief
|
||||
//! \~english This module contains various standart containers realization.
|
||||
//! \~russian Модуль содержит основные классы контейнеров.
|
||||
//! \~\details
|
||||
//! Scope | Use
|
||||
//! ----- | -------
|
||||
//! C++ | `#include <picontainersmodule.h>`
|
||||
//! CMake | PIP
|
||||
//!
|
||||
//! \~english This includes
|
||||
//! \~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
|
||||
//! \~\addindex stl_iterators
|
||||
//! \~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
|
||||
@@ -52,4 +161,5 @@
|
||||
#include "pistack.h"
|
||||
#include "pivector2d.h"
|
||||
|
||||
|
||||
#endif // PICONTAINERSMODULE_H
|
||||
|
||||
Reference in New Issue
Block a user