CBitBuffer Class - Data Serialization in MQL5 - librería para MetaTrader 5

Clase CBitBuffer - Serialización de Datos a Nivel de Bit en MQL5

La clase CBitBuffer proporciona una base robusta para la serialización de datos a nivel de bits en MQL5, ofreciendo un control detallado sobre el almacenamiento y recuperación de datos. La clase incluye soporte para varios tipos de datos, incluyendo enteros de longitud variable (VLQ con codificación ZigZag), y serialización de cadenas y estructuras, que son excelentes para optimizar el espacio. La clase emplea optimizaciones como el almacenamiento interno en búfer y el crecimiento exponencial de matrices para mejorar el rendimiento y proporciona un completo sistema de gestión de errores. Es especialmente útil para la comunicación en red o el almacenamiento de archivos en los que minimizar el tamaño de los datos es crucial (por ejemplo, la compresión de datos de tick).

Características principales:

• Operaciones a nivel de bit: Permite escribir y leer datos bit a bit, o en longitudes de bit especificadas de hasta 64 bits.
• Soporte de tipos de datos: Incluye métodos para bool, char, uchar, short, ushort, int, uint, long, ulong, datetime, float, double, string y struct.
• Enteros de longitud variable (VLQ): Implementa la codificación VLQ para valores int, uint, long y ulong, lo que puede ahorrar mucho espacio para valores enteros frecuentemente pequeños.
• Gestión de errores: Proporciona un enum ENUM_BIT_BUFFER_ERROR y métodos GetLastError()/GetLastErrorString() para una sólida gestión de errores.
• Gestión de búferes: Ofrece funciones para borrar, finalizar, establecer el contenido del búfer sin procesar, guardar en un archivo y cargar desde un archivo.
• Almacenamiento interno: Utiliza búferes internos de 64 bits (m_writeBufferInternal, m_readBufferInternal) para optimizar las operaciones a nivel de bits mediante la acumulación de bits antes de escribir o leer de la matriz principal ulong[].

//+------------------------------------------------------------------+
//| Clase CBitBuffer|
//| Lee/escribe bits individuales o secuencias de bits en el buffer ulong[]. |
//| Soporta manipulación eficiente de bits y operaciones mixtas de lectura/escritura. ||
//+------------------------------------------------------------------+
class CBitBuffer
  {
public: // Operaciones básicas con bits
   bool              WriteBit(bool bit);                   // Escribe un solo bit
   bool              WriteBits(ulong value, int numberOfBits); // Escribe N bits de un ulong
   bool              ReadBit();                            // Lee un solo bit
   ulong             ReadBits(int numberOfBits);           // Lee N bits como un ulong
   ulong             PeekBits(int numberOfBits);           // Lee N bits sin avanzar posición

public: // Gestión de la posición y el tamaño
   bool              SetReadPosition(long bitPosition);    // Establece la posición de lectura en bits
   long              GetReadPosition();
   bool              ResetReadPosition();                  // Restablece la posición de lectura a 0
   bool              SkipBits(long bitsToSkip);            // Salta N bits desde la posición de lectura actual
   long              GetTotalWrittenBits();                // Total de bits escritos
   long              GetTotalBytesWritten();               // Total bytes escritos
   long              GetTotalBytesAllocated();             // Total bytes asignados
   long              GetRemainingReadBits();               // Bits restantes a leer

public: // Operaciones de lectura/escritura específicas del tipo de datos
   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);              // Escribe un float de 32 bits
   bool              WriteDouble(double value);            // Escribe un doble de 64 bits
   bool              WriteString(string value);            // Escribe cadena con prefijo de longitud
   template<typename T>
   bool              WriteStruct(T &struct_object);        // Escribe struct con prefijo de longitud

   bool              ReadBool();
   char              ReadChar();
   uchar             ReadUChar();
   short             ReadShort();
   ushort            ReadUShort();
   int               ReadInt();
   uint              ReadUInt();
   long              ReadLong();
   ulong             ReadULong();
   datetime          ReadDatetime();
   float             ReadFloat();                          // Lee un float de 32 bits
   double            ReadDouble();                         // Lee un doble de 64 bits
   string            ReadString();                         // Lee cadena con prefijo de longitud
   template<typename T>
   T                 ReadStruct();                         // Lee estructura con prefijo de longitud

public: // Codificación de longitud variable para enteros (VLQ)
   bool              WriteVarInt(int value);               // Escribe int con signo usando ZigZag + VLQ
   bool              WriteVarUInt(uint value);             // Escribe unsigned int usando VLQ
   bool              WriteVarLong(long value);             // Escribe signed long usando ZigZag + VLQ
   bool              WriteVarULong(ulong value);           // Escribe unsigned long usando VLQ
   int               ReadVarInt();                         // Lee int con signo usando ZigZag + VLQ
   uint              ReadVarUInt();                        // Lee unsigned int usando VLQ
   long              ReadVarLong();                        // Lee long con signo usando ZigZag + VLQ
   ulong             ReadVarULong();                       // Lee unsigned long usando VLQ

public: // Gestión del búfer
   void              Clear();                              // Borra el contenido del buffer y reinicia el estado
   bool              GetFinalizedBuffer(ulong &destinationArray[]); // Copia el contenido del buffer al array
   bool              SetRawBuffer(const ulong &sourceBuffer[]);     // Establece el contenido del buffer desde el array
   bool              Save(string filename);                // Guarda la memoria intermedia en un archivo
   bool              Load(string filename);                // Carga el buffer desde el fichero

public: // Tratamiento de errores
   ENUM_BIT_BUFFER_ERROR GetLastError();                   // Devuelve el último código de error
   string            GetLastErrorString();                 // Devuelve la cadena de descripción del error
   void              ClearLastError() ;                    // Borra el último error

   void              PrintHex();                           // Imprime el búfer principal en hexadecimal (depuración)
  };

El ejemplo de prueba completo " CBitBuffer_Test.mq5" proporcionado anteriormente es la mejor manera de detectar errores y verificar las capacidades de la clase.

Actualizaciones:

2025.07.21 - v.1.01 :

• La clase CBitBuffer previene activamente intentos ilegales de escritura después de que una operación de lectura haya comenzado, lo que ayuda a mantener la integridad de los datos.
• Los usuarios reciben un error específico (BIT_BUFFER_MIXED_OPERATION_ERROR) cuando intentan mezclar operaciones.

2025.07.22 - v.1.02 :

• Cambiado el diseño de la clase para permitir las operaciones mixtas de lectura/escritura, mediante la correcta gestión de los vaciados/rellenadosparciales , lo que ayuda a mantener la integridad de los datos al cambiar entre los modos de lectura y escritura.
• Eliminada la variable (m_operationMode) y el código de error (BIT_BUFFER_MIXED_OPERATION_ERROR).
• Se han limpiado los comentarios del código para mayor claridad.
• Actualizados los ejemplos en "CBitBuffer_Test.mq5" para cubrir más casos de prueba.