merged AI doc, some new pages

doc/pages/chunk_stream.md

@@ -0,0 +1,56 @@
+\~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.