CBitBuffer Class - Data Serialization in MQL5 - Bibliothek für den MetaTrader 5

CBitBuffer Klasse - Serialisierung von Daten auf Bit-Ebene in MQL5

Die Klasse CBitBuffer bietet eine robuste Grundlage für die Serialisierung von Daten auf Bitebene in MQL5 und bietet eine feinkörnige Kontrolle über die Speicherung und den Abruf von Daten. Die Klasse unterstützt verschiedene Datentypen, einschließlich Ganzzahlen variabler Länge (VLQ mit ZigZag-Kodierung), sowie die Serialisierung von Strings und Strukturen, die sich hervorragend für die Optimierung des Speicherplatzes eignen. Die Klasse nutzt Optimierungen wie interne Pufferung und exponentielles Array-Wachstum, um die Leistung zu verbessern, und bietet ein umfassendes Fehlerbehandlungssystem. Sie ist besonders nützlich für die Netzwerkkommunikation oder die Speicherung von Dateien, bei denen die Minimierung der Datengröße von entscheidender Bedeutung ist (z. B. Komprimierung von Tickdaten).

Hauptmerkmale:

• Operationen auf Bitebene: Ermöglicht das Schreiben und Lesen von Daten Bit für Bit oder in bestimmten Bitlängen bis zu 64 Bit.
• Unterstützung von Datentypen: Enthält Methoden für bool, char, uchar, short, ushort, int, uint, long, ulong, datetime, float, double, string und struct.
• Ganzzahlen mit variabler Länge (VLQ): Implementiert VLQ-Kodierung für int-, uint-, long- und ulong-Werte, wodurch bei häufig kleinen Integer-Werten erheblich Platz gespart werden kann.
• Fehlerbehandlung: Bietet ein ENUM_BIT_BUFFER_ERROR-Enum und GetLastError()/GetLastErrorString()-Methoden für robustes Fehlermanagement.
• Puffer-Verwaltung: Bietet Funktionen zum Löschen, Finalisieren, Einstellen des Rohpufferinhalts, Speichern in eine Datei und Laden aus einer Datei.
• Interne Pufferung: Verwendet interne 64-Bit-Puffer (m_writeBufferInternal, m_readBufferInternal) zur Optimierung von Operationen auf Bit-Ebene durch Akkumulieren von Bits vor dem Schreiben in oder Lesen aus dem Haupt-Ulong[]-Array.

//+------------------------------------------------------------------+
//| CBitBuffer Klasse|
//| Liest/schreibt einzelne Bits oder Bitfolgen in ulong[]-Puffer. |
//| Unterstützt effiziente Bitmanipulation und gemischte Lese-/Schreiboperationen.
//+------------------------------------------------------------------+
class CBitBuffer
  {
public: // Kern-Bit-Operationen
   bool              WriteBit(bool bit);                   // Schreibt ein einzelnes Bit
   bool              WriteBits(ulong value, int numberOfBits); // Schreibt N Bits aus einem ulong
   bool              ReadBit();                            // Liest ein einzelnes Bit
   ulong             ReadBits(int numberOfBits);           // Liest N Bits als ulong
   ulong             PeekBits(int numberOfBits);           // Liest N Bits ohne Positionsverschiebung

public: // Positions- und Größenmanagement
   bool              SetReadPosition(long bitPosition);    // Setzt die Leseposition in Bits
   long              GetReadPosition();
   bool              ResetReadPosition();                  // Setzt Leseposition auf 0 zurück
   bool              SkipBits(long bitsToSkip);            // Überspringt N Bits ab der aktuellen Leseposition
   long              GetTotalWrittenBits();                // Insgesamt geschriebene Bits
   long              GetTotalBytesWritten();               // Insgesamt geschriebene Bytes
   long              GetTotalBytesAllocated();             // Insgesamt zugewiesene Bytes
   long              GetRemainingReadBits();               // Verbleibende zu lesende Bits

public: // Datentypspezifische Lese-/Schreiboperationen
   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);              // Schreibt eine 32-Bit-Fließkommazahl
   bool              WriteDouble(double value);            // Schreibt ein 64-Bit-Double
   bool              WriteString(string value);            // Schreibt Zeichenkette mit Längenpräfix
   template<typename T>
   bool              WriteStruct(T &struct_object);        // Schreibt struct mit Längenpräfix

   bool              ReadBool();
   char              ReadChar();
   uchar             ReadUChar();
   short             ReadShort();
   ushort            ReadUShort();
   int               ReadInt();
   uint              ReadUInt();
   long              ReadLong();
   ulong             ReadULong();
   datetime          ReadDatetime();
   float             ReadFloat();                          // Liest eine 32-Bit-Fließkommazahl
   double            ReadDouble();                         // Liest ein 64-Bit-Double
   string            ReadString();                         // Liest Zeichenkette mit Längenpräfix
   template<typename T>
   T                 ReadStruct();                         // Liest struct mit Längenpräfix

public: // Kodierung mit variabler Länge für ganze Zahlen (VLQ)
   bool              WriteVarInt(int value);               // Schreibt einen vorzeichenbehafteten int mit ZigZag + VLQ
   bool              WriteVarUInt(uint value);             // Schreibt unsigned int mit VLQ
   bool              WriteVarLong(long value);             // Schreibt vorzeichenbehafteten Long mit ZigZag + VLQ
   bool              WriteVarULong(ulong value);           // Schreibt unsigned long mit VLQ
   int               ReadVarInt();                         // Liest vorzeichenbehafteten int mit ZigZag + VLQ
   uint              ReadVarUInt();                        // Liest unsigned int mit VLQ
   long              ReadVarLong();                        // Liest vorzeichenbehafteten Long mit ZigZag + VLQ
   ulong             ReadVarULong();                       // Liest unsigned long mit VLQ

public: // Pufferverwaltung
   void              Clear();                              // Löscht den Pufferinhalt und setzt den Status zurück
   bool              GetFinalizedBuffer(ulong &destinationArray[]); // Kopiert Pufferinhalt in Array
   bool              SetRawBuffer(const ulong &sourceBuffer[]);     // Setzt Pufferinhalt aus Array
   bool              Save(string filename);                // Speichert Puffer in Datei
   bool              Load(string filename);                // Lädt Puffer aus Datei

public: // Fehlerbehandlung
   ENUM_BIT_BUFFER_ERROR GetLastError();                   // Gibt den letzten Fehlercode zurück
   string            GetLastErrorString();                 // Gibt eine Zeichenfolge zur Fehlerbeschreibung zurück
   void              ClearLastError() ;                    // Löscht den letzten Fehler

   void              PrintHex();                           // Druckt den Hauptpuffer in Hexadezimalzeichen (Debugging)
  };

Das vollständige Testbeispiel " CBitBuffer_Test.mq5" (siehe oben) ist der beste Weg, um Fehler zu erkennen und die Fähigkeiten der Klasse zu überprüfen.

Aktualisierungen:

2025.07.21 - v.1.01 :

• Die Klasse CBitBuffer verhindert aktiv illegale Schreibversuche, nachdem ein Lesevorgang begonnen hat, was zur Wahrung der Datenintegrität beiträgt.
• Benutzer erhalten einen spezifischen Fehler (BIT_BUFFER_MIXED_OPERATION_ERROR), wenn sie versuchen, Operationen zu mischen.

2025.07.22 - v.1.02 :

• Das Design der Klasse wurde geändert, um gemischte Lese-/Schreiboperationen zu ermöglichen, indem partielle Flushes/Nachfüllungenkorrekt gehandhabt werden , was zur Aufrechterhaltung der Datenintegrität beim Wechsel zwischen Lese- und Schreibmodus beiträgt.
• Die Variable (m_operationMode) und der Fehlercode (BIT_BUFFER_MIXED_OPERATION_ERROR) wurden entfernt.
• Die Code-Kommentare wurden bereinigt, um die Absicht besser zu verdeutlichen.
• Aktualisierte Beispiele in "CBitBuffer_Test.mq5", um mehr Testfälle abzudecken.