\~english \page chunk_stream Chunk stream and versioned serialization
\~russian \page chunk_stream Поток чанков и версионная сериализация

\~english

\a PIChunkStream is a binary stream where data is stored as **chunks**: each chunk has an integer \e id and a value. Reading is id-based, so you can add or reorder fields over time and stay backward compatible: old readers ignore unknown ids, new readers can skip optional ids.

Two format versions exist (\a PIChunkStream::Version_1 and \a Version_2); the writer chooses the version, the reader detects it automatically. By default new data is written in Version_2.

# When to use

Use chunk streams when:
* You need to extend structures without breaking existing stored data (add new fields with new ids).
* You want optional or reordered fields in a single stream.
* You use \ref code_model to generate serialization: with default (chunk) mode, \c pip_cmg emits operators that read/write via \a PIChunkStream and field ids (see \ref code_model "code_model" for PIMETA \c id and \c simple-stream / \c no-stream).

For fixed, non-extensible layouts, plain \a PIBinaryStream operators (see \ref iostream) are enough.

# Usage

Build a \a PIChunkStream from a \a PIByteArray (read or read-write). Write with \c cs << cs.chunk(id, value) or \c add(id, value); read with \c read() to get the next id, then \c get(value). Call \c data() to get the byte buffer for storing or sending. Example (conceptually as in code_model output):

\code{.cpp}
PIByteArray buf;
PIChunkStream cs(&buf);
cs << cs.chunk(1, i) << cs.chunk(2, s);
// later:
PIChunkStream reader(buf);
while (!reader.atEnd()) {
	switch (reader.read()) {
	case 1: reader.get(i); break;
	case 2: reader.get(s); break;
	}
}
\endcode

Generated operators for structs use the same pattern; see \ref code_model.

\~russian

\a PIChunkStream — бинарный поток, в котором данные хранятся **чанками**: у каждого чанка целочисленный \e id и значение. Чтение идёт по id, поэтому можно добавлять или менять порядок полей с сохранением обратной совместимости: старые читатели игнорируют неизвестные id, новые могут пропускать необязательные.

Есть две версии формата (\a PIChunkStream::Version_1 и \a Version_2); версию выбирает запись, при чтении она определяется автоматически. По умолчанию запись идёт в Version_2.

# Когда использовать

Имеет смысл использовать поток чанков, когда:
* Нужно расширять структуры без поломки уже сохранённых данных (новые поля — новые id).
* Нужны необязательные или переставляемые поля в одном потоке.
* Используется \ref code_model для генерации сериализации: в режиме по умолчанию (chunk) \c pip_cmg выдаёт операторы через \a PIChunkStream и id полей (см. \ref code_model по PIMETA \c id и \c simple-stream / \c no-stream).

Для фиксированных неизменяемых форматов достаточно обычных операторов \a PIBinaryStream (см. \ref iostream).

# Использование

Создают \a PIChunkStream из \a PIByteArray (чтение или чтение/запись). Запись: \c cs << cs.chunk(id, value) или \c add(id, value); чтение: \c read() — следующий id, затем \c get(value). \c data() возвращает буфер для сохранения или передачи. Примеры генерации операторов — в \ref code_model.