CBitBuffer Class - Data Serialization in MQL5 - biblioteca para MetaTrader 5

Classe CBitBuffer - serialização de dados em nível de bit em MQL5

A classe CBitBuffer fornece uma base robusta para a serialização de dados em nível de bit em MQL5, oferecendo controle refinado sobre o armazenamento e a recuperação de dados. A classe oferece suporte a vários tipos de dados, incluindo números inteiros de comprimento variável (VLQ com codificação ZigZag) e serialização de strings e estruturas, que são excelentes para otimizar o espaço. A classe emprega otimizações como buffer interno e crescimento exponencial de matriz para melhorar o desempenho e fornece um sistema abrangente de tratamento de erros. É particularmente útil para comunicação de rede ou armazenamento de arquivos em que a minimização do tamanho dos dados é crucial (por exemplo, compactação de dados de ticks).

Principais recursos:

• Operações em nível de bit: Permite gravar e ler dados bit a bit ou em comprimentos de bits especificados de até 64 bits.
• Suporte a tipos de dados: Inclui métodos para bool, char, uchar, short, ushort, int, uint, long, ulong, datetime, float, double, string e struct.
• Inteiros de comprimento variável (VLQ): Implementa a codificação VLQ para valores int, uint, long e ulong, o que pode economizar muito espaço para valores inteiros frequentemente pequenos.
• Tratamento de erros: Fornece um enum ENUM_BIT_BUFFER_ERROR e os métodos GetLastError()/GetLastErrorString() para um gerenciamento robusto de erros.
• Gerenciamento de buffer: Oferece funções para limpar, finalizar, definir o conteúdo do buffer bruto, salvar no arquivo e carregar do arquivo.
• Buffering interno: Usa buffers internos de 64 bits (m_writeBufferInternal, m_readBufferInternal) para otimizar as operações em nível de bit, acumulando bits antes de gravar ou ler a partir da matriz principal ulong[].

//+------------------------------------------------------------------+
//| Classe CBitBuffer|
//| Lê/grava bits individuais ou sequências de bits no buffer ulong[]. |
//| Suporte à manipulação eficiente de bits e operações mistas de leitura/gravação.
//+------------------------------------------------------------------+
class CBitBuffer
  {
public: // Operações de bits principais
   bool              WriteBit(bool bit);                   // Grava um único bit
   bool              WriteBits(ulong value, int numberOfBits); // Grava N bits de um ulong
   bool              ReadBit();                            // Lê um único bit
   ulong             ReadBits(int numberOfBits);           // Lê N bits como um ulongo
   ulong             PeekBits(int numberOfBits);           // Lê N bits sem avançar a posição

public: // Gerenciamento de posição e tamanho
   bool              SetReadPosition(long bitPosition);    // Define a posição de leitura em bits
   long              GetReadPosition();
   bool              ResetReadPosition();                  // Redefine a posição de leitura para 0
   bool              SkipBits(long bitsToSkip);            // Pula N bits da posição de leitura atual
   long              GetTotalWrittenBits();                // Total de bits gravados
   long              GetTotalBytesWritten();               // Total de bytes gravados
   long              GetTotalBytesAllocated();             // Total de bytes alocados
   long              GetRemainingReadBits();               // Bits restantes para ler

public: // Operações de leitura/gravação específicas do tipo de dados
   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);              // Grava um float de 32 bits
   bool              WriteDouble(double value);            // Grava um duplo de 64 bits
   bool              WriteString(string value);            // Grava uma string com prefixo de comprimento
   template<typename T>
   bool              WriteStruct(T &struct_object);        // Grava a estrutura com prefixo de comprimento

   bool              ReadBool();
   char              ReadChar();
   uchar             ReadUChar();
   short             ReadShort();
   ushort            ReadUShort();
   int               ReadInt();
   uint              ReadUInt();
   long              ReadLong();
   ulong             ReadULong();
   datetime          ReadDatetime();
   float             ReadFloat();                          // Lê um float de 32 bits
   double            ReadDouble();                         // Lê um duplo de 64 bits
   string            ReadString();                         // Lê a string com prefixo de comprimento
   template<typename T>
   T                 ReadStruct();                         // Lê a estrutura com prefixo de comprimento

public: // Codificação de comprimento variável para inteiros (VLQ)
   bool              WriteVarInt(int value);               // Grava um int assinado usando ZigZag + VLQ
   bool              WriteVarUInt(uint value);             // Grava um int sem sinal usando VLQ
   bool              WriteVarLong(long value);             // Grava um texto longo assinado usando ZigZag + VLQ
   bool              WriteVarULong(ulong value);           // Grava um longo sem sinal usando VLQ
   int               ReadVarInt();                         // Lê um int com sinal usando ZigZag + VLQ
   uint              ReadVarUInt();                        // Lê um int sem sinal usando VLQ
   long              ReadVarLong();                        // Lê um longo assinado usando ZigZag + VLQ
   ulong             ReadVarULong();                       // Lê um longo sem sinal usando VLQ

public: // Gerenciamento de buffer
   void              Clear();                              // Limpa o conteúdo do buffer e redefine o estado
   bool              GetFinalizedBuffer(ulong &destinationArray[]); // Copia o conteúdo do buffer para a matriz
   bool              SetRawBuffer(const ulong &sourceBuffer[]);     // Define o conteúdo do buffer a partir da matriz
   bool              Save(string filename);                // Salva o buffer no arquivo
   bool              Load(string filename);                // Carrega o buffer do arquivo

public: // Tratamento de erros
   ENUM_BIT_BUFFER_ERROR GetLastError();                   // Retorna o último código de erro
   string            GetLastErrorString();                 // Retorna a string de descrição do erro
   void              ClearLastError() ;                    // Limpa o último erro

   void              PrintHex();                           // Imprime o buffer principal em hexadecimal (depuração)
  };

O exemplo de teste completo " CBitBuffer_Test.mq5" fornecido acima é a melhor maneira de detectar erros e verificar os recursos da classe.

Atualizações:

2025.07.21 - v.1.01 :

• A classe CBitBuffer impede ativamente tentativas ilegais de gravação após o início de uma operação de leitura, o que ajuda a manter a integridade dos dados.
• Os usuários recebem um erro específico (BIT_BUFFER_MIXED_OPERATION_ERROR) quando tentam misturar operações.

2025.07.22 - v.1.02 :

• Alterado o design da classe para permitir operações mistas de leitura/gravação, por meio do tratamento correto de descargas/recargasparciais , o que ajuda a manter a integridade dos dados ao alternar entre os modos de leitura e gravação.
• Removida a variável (m_operationMode) e o código de erro (BIT_BUFFER_MIXED_OPERATION_ERROR).
• Limpos os comentários do código para maior clareza de intenção.
• Atualizados os exemplos em "CBitBuffer_Test.mq5" para abranger mais casos de teste.