CBitBuffer Class - Data Serialization in MQL5 - библиотека для MetaTrader 5

Класс CBitBuffer - сериализация данных на битовом уровне в MQL5

Класс CBitBuffer представляет собой надежную основу для сериализации данных на битовом уровне в MQL5, обеспечивая тонкий контроль над хранением и извлечением данных. Класс поддерживает различные типы данных, включая целые числа переменной длины (VLQ с кодировкой ZigZag), а также сериализацию строк и структур, которые отлично подходят для оптимизации пространства. Класс использует такие оптимизации, как внутренняя буферизация и экспоненциальный рост массива, для повышения производительности и предоставляет комплексную систему обработки ошибок. Он особенно полезен для сетевого взаимодействия или хранения файлов, где минимизация размера данных имеет решающее значение (например, сжатие тиковых данных).

Ключевые особенности:

• Операции на уровне битов: Позволяют записывать и считывать данные побитно или с заданной длиной до 64 бит.
• Поддержка типов данных: Включает методы для bool, char, uchar, short, ushort, int, uint, long, ulong, datetime, float, double, string и struct.
• Целые числа переменной длины (VLQ): Реализует кодировку VLQ для значений int, uint, long и ulong, что позволяет значительно экономить место для часто используемых небольших целых значений.
• Обработка ошибок: Предоставляет перечисление ENUM_BIT_BUFFER_ERROR и методы GetLastError()/GetLastErrorString() для надежной обработки ошибок.
• Управление буфером: Предлагает функции для очистки, финализации, установки содержимого необработанного буфера, сохранения в файл и загрузки из файла.
• Внутренняя буферизация: Использует внутренние 64-битные буферы (m_writeBufferInternal, m_readBufferInternal) для оптимизации операций на битовом уровне, накапливая биты перед записью в основной массив ulong[] или чтением из него.

//+------------------------------------------------------------------+
//| Класс CBitBuffer|
//| Считывает/записывает отдельные биты или последовательности битов в буфер ulong[]. |
//| Поддерживает эффективное манипулирование битами и смешанные операции чтения/записи.|
//+------------------------------------------------------------------+
class CBitBuffer
  {
public: // Основные битовые операции
   bool              WriteBit(bool bit);                   // Записывает один бит
   bool              WriteBits(ulong value, int numberOfBits); // Записывает N битов из улонга
   bool              ReadBit();                            // Считывает один бит
   ulong             ReadBits(int numberOfBits);           // Считывает N битов как улонг
   ulong             PeekBits(int numberOfBits);           // Считывает N битов без продвижения позиции

public: // Управление положением и размерами
   bool              SetReadPosition(long bitPosition);    // Устанавливает позицию чтения в битах
   long              GetReadPosition();
   bool              ResetReadPosition();                  // Сброс позиции чтения в 0
   bool              SkipBits(long bitsToSkip);            // Пропускает N битов из текущей позиции чтения
   long              GetTotalWrittenBits();                // Всего записано бит
   long              GetTotalBytesWritten();               // Всего записано байт
   long              GetTotalBytesAllocated();             // Всего выделено байт
   long              GetRemainingReadBits();               // Оставшиеся биты для чтения

public: // Операции чтения/записи, специфичные для типа данных
   bool              WriteBool(bool value);
   bool              WriteChar(char value);
   bool              WriteUChar(uchar value);
   bool              WriteShort(short value);
   bool              WriteUShort(ushort value);
   bool              WriteInt(int value);
   bool              WriteUInt(uint value);
   bool              WriteLong(long value);
   bool              WriteULong(ulong value);
   bool              WriteDatetime(datetime value);
   bool              WriteFloat(float value);              // Записывает 32-битный float
   bool              WriteDouble(double value);            // Записывает 64-битное двойное значение
   bool              WriteString(string value);            // Записывает строку с префиксом длины
   template<typename T>
   bool              WriteStruct(T &struct_object);        // Запись структуры с префиксом длины

   bool              ReadBool();
   char              ReadChar();
   uchar             ReadUChar();
   short             ReadShort();
   ushort            ReadUShort();
   int               ReadInt();
   uint              ReadUInt();
   long              ReadLong();
   ulong             ReadULong();
   datetime          ReadDatetime();
   float             ReadFloat();                          // Считывает 32-битное значение float
   double            ReadDouble();                         // Считывание 64-битного двойного числа
   string            ReadString();                         // Считывает строку с префиксом длины
   template<typename T>
   T                 ReadStruct();                         // Считывание структуры с префиксом длины

public: // Кодировка переменной длины для целых чисел (VLQ)
   bool              WriteVarInt(int value);               // Записывает подписанный int с помощью ZigZag + VLQ
   bool              WriteVarUInt(uint value);             // Запись беззнакового int с помощью VLQ
   bool              WriteVarLong(long value);             // Записывает подписанный long с помощью ZigZag + VLQ
   bool              WriteVarULong(ulong value);           // Запись беззнаковой длины с помощью VLQ
   int               ReadVarInt();                         // Чтение знакового инта с помощью ZigZag + VLQ
   uint              ReadVarUInt();                        // Считывание беззнаковых значений int с помощью VLQ
   long              ReadVarLong();                        // Чтение подписанных длинных с помощью ZigZag + VLQ
   ulong             ReadVarULong();                       // Чтение беззнаковой длины с помощью VLQ

public: // Управление буфером
   void              Clear();                              // Очищает содержимое буфера и сбрасывает состояние
   bool              GetFinalizedBuffer(ulong &destinationArray[]); // Копирует содержимое буфера в массив
   bool              SetRawBuffer(const ulong &sourceBuffer[]);     // Устанавливает содержимое буфера из массива
   bool              Save(string filename);                // Сохраняет буфер в файл
   bool              Load(string filename);                // Загрузка буфера из файла

public: // Обработка ошибок
   ENUM_BIT_BUFFER_ERROR GetLastError();                   // Возвращает последний код ошибки
   string            GetLastErrorString();                 // Возвращает строку описания ошибки
   void              ClearLastError() ;                    // Удаление последней ошибки

   void              PrintHex();                           // Печатает основной буфер в шестнадцатеричном формате (отладка)
  };

Полный тестовый пример " CBitBuffer_Test.mq5", приведенный выше, - лучший способ выявить ошибки и проверить возможности класса.

Обновления:

2025.07.21 - v.1.01 :

• Класс CBitBuffer активно предотвращает незаконные попытки записи после начала операции чтения, что помогает сохранить целостность данных.
• При попытке смешивания операций пользователи получают специфическую ошибку (BIT_BUFFER_MIXED_OPERATION_ERROR).

2025.07.22 - v.1.02 :

• Изменен дизайн класса, чтобы разрешить смешанные операции чтения/записи, за счет корректной обработки частичных сливов/заполнений, что помогает сохранить целостность данных при переключении между режимами чтения и записи.
• Удалена переменная (m_operationMode) и код ошибки (BIT_BUFFER_MIXED_OPERATION_ERROR).
• Очищены комментарии к коду для большей ясности смысла.
• Обновлены примеры в файле "CBitBuffer_Test.mq5", чтобы охватить больше тестовых случаев.