CBitBuffer Class - Data Serialization in MQL5 - bibliothèque pour MetaTrader 5

Classe CBitBuffer - Sérialisation des données au niveau des bits en MQL5

La classe CBitBuffer fournit une base solide pour la sérialisation des données au niveau des bits dans MQL5, offrant un contrôle fin sur le stockage et l'extraction des données. La classe prend en charge différents types de données, notamment les entiers de longueur variable (VLQ avec encodage ZigZag), ainsi que la sérialisation des chaînes et des structures, qui sont excellentes pour l'optimisation de l'espace. La classe utilise des optimisations telles que la mise en mémoire tampon interne et la croissance exponentielle des tableaux pour améliorer les performances et fournit un système complet de gestion des erreurs. Elle est particulièrement utile pour la communication réseau ou le stockage de fichiers où la minimisation de la taille des données est cruciale (par exemple, la compression des données de tic-tac).

Caractéristiques principales :

• Opérations au niveau du bit: Permet d'écrire et de lire des données bit par bit, ou dans des longueurs de bits spécifiées jusqu'à 64 bits.
• Prise en charge des types de données: Inclut des méthodes pour bool, char, uchar, short, ushort, int, uint, long, ulong, datetime, float, double, string et struct.
• Entiers de longueur variable (VLQ): implémente le codage VLQ pour les valeurs int, uint, long et ulong, ce qui permet d'économiser de l'espace de manière significative pour les valeurs entières fréquemment petites.
• Gestion des erreurs: Fournit un enum ENUM_BIT_BUFFER_ERROR et les méthodes GetLastError()/GetLastErrorString() pour une gestion robuste des erreurs.
• Gestion des tampons: Fonctions permettant d'effacer, de finaliser, de définir le contenu de la mémoire tampon brute, d'enregistrer dans un fichier et de charger à partir d'un fichier.
• Tampon interne: Utilise des tampons 64 bits internes (m_writeBufferInternal, m_readBufferInternal) pour optimiser les opérations au niveau des bits en accumulant les bits avant d'écrire ou de lire dans le tableau principal ulong[].

//+------------------------------------------------------------------+
//| Classe CBitBuffer|
//| Lit/écrit des bits individuels ou des séquences de bits dans un tampon ulong[]. |
//| Prend en charge la manipulation efficace des bits et les opérations mixtes de lecture et d'écriture.
//+------------------------------------------------------------------+
class CBitBuffer
  {
public: // Opérations sur les bits de base
   bool              WriteBit(bool bit);                   // Écriture d'un seul bit
   bool              WriteBits(ulong value, int numberOfBits); // Écriture de N bits dans un ulong
   bool              ReadBit();                            // Lecture d'un seul bit
   ulong             ReadBits(int numberOfBits);           // Lit N bits sous la forme d'un ulong
   ulong             PeekBits(int numberOfBits);           // Lit N bits sans avancer la position

public: // Gestion de la position et de la taille
   bool              SetReadPosition(long bitPosition);    // Définit la position de lecture en bits
   long              GetReadPosition();
   bool              ResetReadPosition();                  // Remet la position de lecture à 0
   bool              SkipBits(long bitsToSkip);            // Sauter N bits à partir de la position de lecture actuelle
   long              GetTotalWrittenBits();                // Total des bits écrits
   long              GetTotalBytesWritten();               // Total des octets écrits
   long              GetTotalBytesAllocated();             // Total des octets alloués
   long              GetRemainingReadBits();               // Bits restants à lire

public: // Opérations de lecture/écriture spécifiques au type de données
   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);              // Écriture d'un flottant de 32 bits
   bool              WriteDouble(double value);            // Écrit un double de 64 bits
   bool              WriteString(string value);            // Écrit une chaîne de caractères avec un préfixe de longueur
   template<typename T>
   bool              WriteStruct(T &struct_object);        // Écrit la structure avec le préfixe de longueur

   bool              ReadBool();
   char              ReadChar();
   uchar             ReadUChar();
   short             ReadShort();
   ushort            ReadUShort();
   int               ReadInt();
   uint              ReadUInt();
   long              ReadLong();
   ulong             ReadULong();
   datetime          ReadDatetime();
   float             ReadFloat();                          // Lit un flottant de 32 bits
   double            ReadDouble();                         // Lit un double de 64 bits
   string            ReadString();                         // Lit la chaîne de caractères avec le préfixe de longueur
   template<typename T>
   T                 ReadStruct();                         // Lit la structure avec le préfixe de longueur

public: // Codage de longueur variable pour les entiers (VLQ)
   bool              WriteVarInt(int value);               // Écriture d'un int signé en utilisant ZigZag + VLQ
   bool              WriteVarUInt(uint value);             // Écriture d'un int non signé à l'aide de VLQ
   bool              WriteVarLong(long value);             // Écriture d'un long signé en utilisant ZigZag + VLQ
   bool              WriteVarULong(ulong value);           // Écriture d'un long non signé à l'aide de VLQ
   int               ReadVarInt();                         // Lecture d'un int signé en utilisant ZigZag + VLQ
   uint              ReadVarUInt();                        // Lecture d'un int non signé à l'aide de VLQ
   long              ReadVarLong();                        // Lecture d'un fichier long signé à l'aide de ZigZag + VLQ
   ulong             ReadVarULong();                       // Lecture d'un long non signé à l'aide de VLQ

public: // Gestion de la mémoire tampon
   void              Clear();                              // Efface le contenu de la mémoire tampon et réinitialise l'état
   bool              GetFinalizedBuffer(ulong &destinationArray[]); // Copie le contenu du tampon dans un tableau
   bool              SetRawBuffer(const ulong &sourceBuffer[]);     // Définit le contenu de la mémoire tampon à partir d'un tableau
   bool              Save(string filename);                // Sauvegarde du tampon dans le fichier
   bool              Load(string filename);                // Chargement de la mémoire tampon à partir du fichier

public: // Gestion des erreurs
   ENUM_BIT_BUFFER_ERROR GetLastError();                   // Renvoie le dernier code d'erreur
   string            GetLastErrorString();                 // Retourne la chaîne de description de l'erreur
   void              ClearLastError() ;                    // Efface la dernière erreur

   void              PrintHex();                           // Imprime le tampon principal en hexadécimal (débogage)
  };

L'exemple de test complet " CBitBuffer_Test.mq5" fourni ci-dessus est le meilleur moyen de détecter les erreurs et de vérifier les capacités de la classe.

Mises à jour :

2025.07.21 - v.1.01 :

• La classe CBitBuffer empêche activement les tentatives illégales d'écriture après le début d'une opération de lecture, ce qui contribue à maintenir l'intégrité des données.
• Les utilisateurs reçoivent une erreur spécifique (BIT_BUFFER_MIXED_OPERATION_ERROR) lorsqu'ils tentent de mélanger des opérations.

2025.07.22 - v.1.02 :

• Modification de la conception de la classe pour permettre les opérations mixtes lecture/écriture, en gérant correctement les remplissagespartiels , ce qui aide à maintenir l'intégrité des données lors de la commutation entre les modes lecture et écriture.
• Suppression de la variable (m_operationMode) et du code d'erreur (BIT_BUFFER_MIXED_OPERATION_ERROR).
• Nettoyage des commentaires du code pour une meilleure clarté d'intention.
• Mise à jour des exemples dans "CBitBuffer_Test.mq5" pour couvrir plus de cas de test.