123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252 |
- <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><implementation-defined></nt><![CDATA[;
- using const_iterator = ]]><nt><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 &&o) noexcept <sign>C++11</sign></prototype>
- <prototype>fixed_vector &operator=(fixed_vector &&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 && empty() == true</tt>
- (если <tt>size_exact == true</tt>, то <tt>capacity() == new_max_size &&
- 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<class... Args> T &emplace_back(Args &&... 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 &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 &operator[](size_t i)</prototype>
- <prototype>const T &operator[](size_t i) const</prototype>
- <p>Доступ к элементам контейнера по индексу.</p>
- <precondition><tt>i < size()</tt></precondition>
- </synopsis>
- <synopsis>
- <prototype>T &front()</prototype>
- <prototype>const T &front() const</prototype>
- <prototype>T &back()</prototype>
- <prototype>const T &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>
|