__vic/doc/ru/fixed_vector.h.xml

<chapter xml:id="fixed_vector.h">
<title><tt>__vic/fixed_vector.h</tt></title>

<chapter xml:id="fixed_vector">
<title><tt>fixed_vector</tt></title>
<code-block lang="C++"><![CDATA[
template<class T>
class fixed_vector : private non_copyable
{
public:
    using value_type     = T;
    using iterator       = ]]><nt>&lt;implementation-defined></nt><![CDATA[;
    using const_iterator = ]]><nt>&lt;implementation-defined></nt><![CDATA[;

    fixed_vector();
    explicit fixed_vector(size_t max_size);
    ~fixed_vector();

    // BEGIN C++11
    fixed_vector(fixed_vector &&o) noexcept;
    fixed_vector &operator=(fixed_vector &&o) noexcept;
    template<class... Args> T &emplace_back(Args &&... args)
    // END C++11

    // size in objects
    size_t size() const;
    size_t capacity() const;
    bool full() const;
    bool empty() const;

    void recreate(size_t new_max_size, bool size_exact = false);
    void *alloc(); // returns pointer to memory for object allocation
    void push_allocated(); // adds last allocated object to the container
    void pop_back();
    void clear();
    void swap(fixed_vector &o) noexcept;

    // element access
    T &operator[](size_t i);
    iterator begin();
    iterator end();
    T &front();
    T &back();

    const T &operator[](size_t i) const;
    const_iterator begin() const;
    const_iterator end() const;
    const_iterator cbegin() const;
    const_iterator cend() const;
    const T &front() const;
    const T &back() const;
};
template<class T>
void swap(fixed_vector<T> &o1, fixed_vector<T> &o2) noexcept;
]]></code-block>

<p>Стандартные контейнеры в C++98 не позволяют хранить в себе объекты, которые
нельзя копировать (недоступны копирующий конструктор и копирующее присваивание).
Даже в C++11 элементы контейнера, вроде <tt>std::vector</tt>, должны быть как
минимум noexcept-перемещаемыми. Данный класс решает эту проблему и представляет
собой массив некопируемых объектов, или <tt>std::vector</tt>,
<tt>capacity()</tt> которого не растёт автоматически.</p>

<p>Без использования <tt>emplace_back()</tt> невозможно создать произвольный
новый объект непосредственно в памяти контейнера. В C++98 forwarding ссылки
вообще отсутствуют, делая почти невозможным передачу произвольных параметров в
конструктор элемента. В <tt>fixed_vector</tt> это ограничение обходится с
использованием следующего механизма. Создание элемента происходит в несколько
фаз:</p>
<list style="numbered">
    <item>Запрос в контейнере блока памяти, достаточного для размешения
        объекта - <tt>alloc()</tt>,</item>
    <item>Создание объекта в полученной памяти с помощью placement new -
        <tt>new(ptr) type(...)</tt>,</item>
    <item>Фиксация успешно созданного объекта в контейнере -
        <tt>push_allocated()</tt>.</item>
</list>
<p>Пример кода смотрите в конце статьи.</p>

<p>При создании задаётся максимальная ёмкость контейнера. Изменить в будущем
её можно, но только разрушив содержащиеся в нём объекты, то есть пересоздав
контейнер (функция <tt>recreate()</tt>).</p>

<p>Всегда следует использовать функцию <tt>emplace_back()</tt> для создания
элементов, когда она доступна. Если же нет, то использовать небезопасный
интерфейс, описанный выше, с большой осторожностью. Он достаточно страшный и
подверженный ошибкам, но выполняет свою функцию. После того, как элемент
размещён в контейнере, работать с ним также удобно, как и с любым другим
копируемым объектом в стандартных контейнерах. В любом случае, в целом это
гораздо удобнее и эффективнее использования альтернатив, таких как создание
объектов в куче с последующим хранением в контейнере указателей на них, даже
если нам доступен <tt>std::unique_ptr</tt> для управления временем жизни
объектов.</p>

<p>Принципиальные отличия от <tt>std::vector</tt>:</p>
<list style="numbered">
    <item>Элементы могут быть некопируемыми и неперемещаемыми
        (<tt>std::vector</tt> требует как минимум noexcept-перемещаемости);</item>
    <item>Адреса элементов стабильны при добавлении новых;</item>
    <item><tt>emplace_back()</tt> имеет предусловие (<tt>!full()</tt>).</item>
</list>

<section><title>Члены класса</title>

<synopsis>
<prototype>typename value_type</prototype>
<p>Тип элементов.</p>
</synopsis>

<synopsis>
<prototype>typename iterator</prototype>
<prototype>typename const_iterator</prototype>
<p>Итераторы.</p>
</synopsis>

<synopsis>
<prototype>fixed_vector()</prototype>
<p>Создаёт объект без выделения памяти под элементы.</p>
<postcondition><tt>capacity() == 0</tt></postcondition>
</synopsis>

<synopsis>
<prototype>explicit fixed_vector(size_t max_size)</prototype>
<p>Создаёт контейнер ёмкости <tt>max_size</tt> элементов.</p>
<postcondition><tt>capacity() == max_size</tt></postcondition>
</synopsis>

<synopsis>
<prototype>~fixed_vector()</prototype>
<p>Вызывает <tt>clear()</tt>.</p>
</synopsis>

<synopsis>
<prototype>fixed_vector(fixed_vector &amp;&amp;o) noexcept <sign>C++11</sign></prototype>
<prototype>fixed_vector &amp;operator=(fixed_vector &amp;&amp;o) noexcept <sign>C++11</sign></prototype>
<p>Операции перемещения для режима C++11.</p>
</synopsis>

<synopsis>
<prototype>size_t size() const</prototype>
<prototype>size_t capacity() const</prototype>
<p>Текущее и максимальное количество элементов в данном экземпляре контейнера.
</p>
</synopsis>

<synopsis>
<prototype>bool empty() const</prototype>
<p>Возвращает <tt>size() == 0</tt>.</p>
</synopsis>

<synopsis>
<prototype>bool full() const</prototype>
<p>Возвращает <tt>size() == capacity()</tt>.</p>
</synopsis>

<synopsis>
<prototype>void recreate(size_t new_max_size, bool size_exact = false)</prototype>
<p>Пересоздаёт контейнер. Сначала вызывается <tt>clear()</tt>, затем
перевыделяется буфер, если <tt>new_max_size > capacity()</tt> или <tt>size_exact
== true</tt> и <tt>new_max_size != capacity()</tt>.</p>
<postcondition><tt>capacity() >= new_max_size &amp;&amp; empty() == true</tt>
(если <tt>size_exact == true</tt>, то <tt>capacity() == new_max_size &amp;&amp;
empty() == true</tt>)</postcondition>
</synopsis>

<synopsis>
<prototype>void *alloc()</prototype>
<p>Возвращает указатель на блок памяти, достаточный для размещения экземпляра
<tt>value_type</tt>.</p>
<precondition><tt>!full()</tt></precondition>
<note>Используйте <tt>emplace_back()</tt> в режиме C++11.</note>
</synopsis>

<synopsis>
<prototype>void push_allocated()</prototype>
<p>Фиксирует успешно созданный объект в контейнере, увеличивая <tt>size()</tt>
на единицу.</p>
</synopsis>

<synopsis>
<prototype>template&lt;class... Args> T &amp;emplace_back(Args &amp;&amp;... args) <sign>C++11</sign></prototype>
<p>Конструирует новый объект в контейнере с помощью переданных аргументов и
увеличивает <tt>size()</tt> на единицу (<tt>alloc()</tt> + <tt>new</tt> +
<tt>push_allocated()</tt> одним вызовом). Возвращает ссылку на новый элемент.
</p>
<precondition><tt>!full()</tt></precondition>
</synopsis>

<synopsis>
<prototype>void pop_back()</prototype>
<p>Удаляет из контейнера последний элемент.</p>
<precondition><tt>!empty()</tt></precondition>
</synopsis>

<synopsis>
<prototype>void clear()</prototype>
<p>Разрушает все элементы контейнера в порядке обратном порядку создания.</p>
<postcondition><tt>size() == 0</tt> (<tt>empty() == true</tt>)</postcondition>
</synopsis>

<synopsis>
<prototype>void swap(fixed_vector &amp;o)</prototype>
<prototype><![CDATA[template<class T> void swap(fixed_vector<T> &o1, fixed_vector<T> &o2) noexcept]]></prototype>
<p>Обменивается значением с <tt>o</tt>.</p>
</synopsis>

<synopsis>
<prototype>T &amp;operator[](size_t i)</prototype>
<prototype>const T &amp;operator[](size_t i) const</prototype>
<p>Доступ к элементам контейнера по индексу.</p>
<precondition><tt>i &lt; size()</tt></precondition>
</synopsis>

<synopsis>
<prototype>T &amp;front()</prototype>
<prototype>const T &amp;front() const</prototype>
<prototype>T &amp;back()</prototype>
<prototype>const T &amp;back() const</prototype>
<p>Доступ к первому и последнему элементу контейнера.</p>
<precondition><tt>!empty()</tt></precondition>
</synopsis>

<synopsis>
<prototype>iterator begin()</prototype>
<prototype>const_iterator begin() const</prototype>
<prototype>const_iterator cbegin() const</prototype>
<prototype>iterator end()</prototype>
<prototype>const_iterator end() const</prototype>
<prototype>const_iterator cend() const</prototype>
<p>Доступ к элементам через итераторы.</p>
</synopsis>

</section>

<section><title>Пример</title>
<code-block lang="C++"><![CDATA[
// Создаём вектор на два объекта класса C
__vic::fixed_vector<C> v(2);

// Создание элемента в режиме C++98:
new(v.alloc()) C(...); // Запрашиваем блок памяти и создаём в нём объект
v.push_allocated();    // Фиксируем в контейнере успешно созданный объект

// Создание элемента в режиме C++11:
v.emplace_back(...);
]]></code-block>
</section>

</chapter>

</chapter>