CBitBuffer Class - Data Serialization in MQL5 - libreria per MetaTrader 5

Classe CBitBuffer - Serializzazione dei dati a livello di bit in MQL5

La classe CBitBuffer fornisce una solida base per la serializzazione dei dati a livello di bit in MQL5, offrendo un controllo a grana fine sulla memorizzazione e sul recupero dei dati. La classe include il supporto per vari tipi di dati, tra cui gli interi a lunghezza variabile (VLQ con codifica ZigZag), e la serializzazione di stringhe e strutture, che sono eccellenti per ottimizzare lo spazio. La classe impiega ottimizzazioni come il buffering interno e la crescita esponenziale degli array per migliorare le prestazioni e fornisce un sistema completo di gestione degli errori. È particolarmente utile per le comunicazioni di rete o per l'archiviazione di file in cui è fondamentale ridurre al minimo le dimensioni dei dati (ad esempio, la compressione dei dati di tick).

Caratteristiche principali:

• Operazioni a livello di bit: Consente di scrivere e leggere i dati bit per bit, o in lunghezze di bit specifiche fino a 64 bit.
• Supporto dei tipi di dati: Include metodi per bool, char, uchar, short, ushort, int, uint, long, ulong, datetime, float, double, string e struct.
• Interi di lunghezza variabile (VLQ): Implementa la codifica VLQ per i valori int, uint, long e ulong, che consente di risparmiare spazio per i valori interi più piccoli.
• Gestione degli errori: Fornisce un enum ENUM_BIT_BUFFER_ERROR e i metodi GetLastError()/GetLastErrorString() per una solida gestione degli errori.
• Gestione del buffer: Offre funzioni per cancellare, finalizzare, impostare il contenuto del buffer grezzo, salvare su file e caricare da file.
• Buffering interno: Utilizza buffer interni a 64 bit (m_writeBufferInternal, m_readBufferInternal) per ottimizzare le operazioni a livello di bit, accumulando i bit prima di scrivere o leggere dall'array principale ulong[].

//+------------------------------------------------------------------+
//| Classe CBitBuffer|
//| Legge/scrive singoli bit o sequenze di bit nel buffer ulong[]. |
//| Supporta la manipolazione efficiente dei bit e le operazioni miste di lettura e scrittura.
//+------------------------------------------------------------------+
class CBitBuffer
  {
public: // Operazioni con i bit del nucleo
   bool              WriteBit(bool bit);                   // Scrive un singolo bit
   bool              WriteBits(ulong value, int numberOfBits); // Scrive N bit da un ulong
   bool              ReadBit();                            // Legge un singolo bit
   ulong             ReadBits(int numberOfBits);           // Legge N bit come ulong
   ulong             PeekBits(int numberOfBits);           // Legge N bit senza avanzare di posizione

public: // Gestione della posizione e delle dimensioni
   bool              SetReadPosition(long bitPosition);    // Imposta la posizione di lettura in bit
   long              GetReadPosition();
   bool              ResetReadPosition();                  // Riporta la posizione di lettura a 0
   bool              SkipBits(long bitsToSkip);            // Salta N bit dalla posizione di lettura attuale
   long              GetTotalWrittenBits();                // Totale dei bit scritti
   long              GetTotalBytesWritten();               // Totale byte scritti
   long              GetTotalBytesAllocated();             // Totale dei byte allocati
   long              GetRemainingReadBits();               // Bit rimanenti da leggere

public: // Operazioni di lettura/scrittura specifiche del tipo di dati
   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);              // Scrive un float a 32 bit
   bool              WriteDouble(double value);            // Scrive un doppio a 64 bit
   bool              WriteString(string value);            // Scrive una stringa con un prefisso di lunghezza
   template<typename T>
   bool              WriteStruct(T &struct_object);        // Scrive la struct con il prefisso di lunghezza

   bool              ReadBool();
   char              ReadChar();
   uchar             ReadUChar();
   short             ReadShort();
   ushort            ReadUShort();
   int               ReadInt();
   uint              ReadUInt();
   long              ReadLong();
   ulong             ReadULong();
   datetime          ReadDatetime();
   float             ReadFloat();                          // Legge un float a 32 bit
   double            ReadDouble();                         // Legge un doppio a 64 bit
   string            ReadString();                         // Legge la stringa con il prefisso di lunghezza
   template<typename T>
   T                 ReadStruct();                         // Legge la struttura con il prefisso di lunghezza

public: // Codifica a lunghezza variabile per numeri interi (VLQ)
   bool              WriteVarInt(int value);               // Scrive un int firmato usando ZigZag + VLQ
   bool              WriteVarUInt(uint value);             // Scrive un int senza segno utilizzando VLQ
   bool              WriteVarLong(long value);             // Scrive un lungo firmato usando ZigZag + VLQ
   bool              WriteVarULong(ulong value);           // Scrive un lungo senza segno usando VLQ
   int               ReadVarInt();                         // Legge gli int firmati utilizzando ZigZag + VLQ
   uint              ReadVarUInt();                        // Legge gli int senza segno utilizzando VLQ
   long              ReadVarLong();                        // Legge un lungo firmato usando ZigZag + VLQ
   ulong             ReadVarULong();                       // Legge i lunghi senza segno usando VLQ

public: // Gestione del buffer
   void              Clear();                              // Cancella il contenuto del buffer e ripristina lo stato
   bool              GetFinalizedBuffer(ulong &destinationArray[]); // Copia il contenuto del buffer nell'array
   bool              SetRawBuffer(const ulong &sourceBuffer[]);     // Imposta il contenuto del buffer dall'array
   bool              Save(string filename);                // Salva il buffer su file
   bool              Load(string filename);                // Carica il buffer dal file

public: // Gestione degli errori
   ENUM_BIT_BUFFER_ERROR GetLastError();                   // Restituisce l'ultimo codice di errore
   string            GetLastErrorString();                 // Restituisce la stringa di descrizione dell'errore
   void              ClearLastError() ;                    // Cancella l'ultimo errore

   void              PrintHex();                           // Stampa il buffer principale in esadecimale (debug)
  };

L'esempio di test completo " CBitBuffer_Test.mq5" fornito sopra è il modo migliore per individuare gli errori e verificare le capacità della classe.

Aggiornamenti:

2025.07.21 - v.1.01 :

• La classe CBitBuffer impedisce attivamente i tentativi di scrittura illegali dopo l'inizio di un'operazione di lettura, contribuendo così a mantenere l'integrità dei dati.
• Gli utenti ricevono un errore specifico (BIT_BUFFER_MIXED_OPERATION_ERROR) quando tentano di mescolare le operazioni.

2025.07.22 - v.1.02 :

• Modificato il design della classe per consentire le operazioni miste di lettura/scrittura, grazie alla corretta gestione dei flush/riempimentiparziali , che aiuta a mantenere l'integrità dei dati quando si passa dalla modalità di lettura a quella di scrittura.
• Rimossa la variabile (m_operationMode) e il codice di errore (BIT_BUFFER_MIXED_OPERATION_ERROR).
• Puliti i commenti al codice per una maggiore chiarezza di intenti.
• Aggiornati gli esempi in "CBitBuffer_Test.mq5" per coprire più casi di test.