CBitBuffer Class - Data Serialization in MQL5 - MetaTrader 5용 라이브러리

CBitBuffer 클래스 - MQL5의 비트 수준 데이터 직렬화

CBitBuffer 클래스는 MQL5에서 비트 수준 데이터 직렬화를 위한 강력한 기반을 제공하여 데이터 저장 및 검색을 세밀하게 제어할 수 있습니다. 이 클래스에는 가변 길이 정수(지그재그 인코딩이 포함된 VLQ), 공간 최적화에 탁월한 문자열 및 구조체 직렬화 등 다양한 데이터 유형에 대한 지원이 포함되어 있습니다. 이 클래스는 내부 버퍼링 및 지수 배열 증가와 같은 최적화를 사용하여 성능을 향상시키고 포괄적인 오류 처리 시스템을 제공합니다. 데이터 크기를 최소화하는 것이 중요한 네트워크 통신이나 파일 저장(예: 틱 데이터 압축)에 특히 유용합니다.

주요 기능:

• 비트 수준 작업: 데이터를 비트 단위로, 또는 최대 64비트까지 지정된 비트 길이로 쓰고 읽을 수 있습니다.
• 데이터 유형 지원: bool, char, uchar, short, ushort, int, uint, long, ulong, datetime, float, double, string 및 struct 메서드가 포함됩니다.
• 가변 길이 정수(VLQ): 자주 작은 정수 값에 대한 공간을 크게 절약할 수 있는 int, uint, long 및 ulong 값에 대한 VLQ 인코딩을 구현합니다.
• 오류 처리: 강력한 오류 관리를 위해 ENUM_BIT_BUFFER_ERROR 열거형과 GetLastError()/GetLastErrorString() 메서드를 제공합니다.
• 버퍼 관리: 버퍼 지우기, 마무리, 원시 버퍼 콘텐츠 설정, 파일에 저장, 파일에서 로드하는 함수를 제공합니다.
• 내부 버퍼링: 내부 64비트 버퍼(m_writeBufferInternal, m_readBufferInternal)를 사용하여 기본 ulong[] 배열에 쓰거나 읽기 전에 비트를 누적하여 비트 수준 연산을 최적화합니다.

//+------------------------------------------------------------------+
//| CBitBuffer 클래스|
//| 개별 비트 또는 비트 시퀀스를 ulong[] 버퍼에 읽기/쓰기합니다. |
//| 효율적인 비트 조작과 읽기/쓰기 혼합 작업을 지원합니다.
//+------------------------------------------------------------------+
class CBitBuffer
  {
public: // 핵심 비트 연산
   bool              WriteBit(bool bit);                   // 단일 비트를 씁니다.
   bool              WriteBits(ulong value, int numberOfBits); // 울롱에서 N 비트를 씁니다.
   bool              ReadBit();                            // 단일 비트를 읽습니다.
   ulong             ReadBits(int numberOfBits);           // N 비트를 울롱으로 읽습니다.
   ulong             PeekBits(int numberOfBits);           // 전진 위치 없이 N비트를 읽습니다.

public: // 위치 및 크기 관리
   bool              SetReadPosition(long bitPosition);    // 읽기 위치를 비트 단위로 설정합니다.
   long              GetReadPosition();
   bool              ResetReadPosition();                  // 읽기 위치를 0으로 초기화
   bool              SkipBits(long bitsToSkip);            // 현재 읽기 위치에서 N비트를 건너뜁니다.
   long              GetTotalWrittenBits();                // 총 기록된 비트 수
   long              GetTotalBytesWritten();               // 총 기록된 바이트 수
   long              GetTotalBytesAllocated();             // 할당된 총 바이트 수
   long              GetRemainingReadBits();               // 읽을 남은 비트

public: // 데이터 유형별 읽기/쓰기 작업
   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);              // 32비트 실수를 씁니다.
   bool              WriteDouble(double value);            // 64비트 더블을 씁니다.
   bool              WriteString(string value);            // 길이 접두사가 있는 문자열을 씁니다.
   template<typename T>
   bool              WriteStruct(T &struct_object);        // 길이 접두사를 사용하여 구조체를 작성합니다.

   bool              ReadBool();
   char              ReadChar();
   uchar             ReadUChar();
   short             ReadShort();
   ushort            ReadUShort();
   int               ReadInt();
   uint              ReadUInt();
   long              ReadLong();
   ulong             ReadULong();
   datetime          ReadDatetime();
   float             ReadFloat();                          // 32비트 실수를 읽습니다.
   double            ReadDouble();                         // 64비트 더블을 읽습니다.
   string            ReadString();                         // 길이 접두사가 있는 문자열을 읽습니다.
   template<typename T>
   T                 ReadStruct();                         // 길이 접두사가 있는 구조체를 읽습니다.

public: // 정수를 위한 가변 길이 인코딩(VLQ)
   bool              WriteVarInt(int value);               // ZigZag + VLQ를 사용하여 서명된 int를 씁니다.
   bool              WriteVarUInt(uint value);             // VLQ를 사용하여 부호 없는 int를 씁니다.
   bool              WriteVarLong(long value);             // 지그재그 + VLQ를 사용하여 길게 서명된 쓰기
   bool              WriteVarULong(ulong value);           // VLQ를 사용하여 서명되지 않은 길게 쓰기
   int               ReadVarInt();                         // ZigZag + VLQ를 사용하여 부호화된 int를 읽습니다.
   uint              ReadVarUInt();                        // VLQ를 사용하여 부호 없는 정수를 읽습니다.
   long              ReadVarLong();                        // 지그재그 + VLQ를 사용하여 길게 서명된 읽기
   ulong             ReadVarULong();                       // VLQ를 사용하여 서명되지 않은 긴 읽기

public: // 버퍼 관리
   void              Clear();                              // 버퍼 콘텐츠를 지우고 상태를 초기화합니다.
   bool              GetFinalizedBuffer(ulong &destinationArray[]); // 버퍼 콘텐츠를 배열에 복사합니다.
   bool              SetRawBuffer(const ulong &sourceBuffer[]);     // 배열에서 버퍼 콘텐츠를 설정합니다.
   bool              Save(string filename);                // 버퍼를 파일에 저장합니다.
   bool              Load(string filename);                // 파일에서 버퍼를 로드합니다.

public: // 오류 처리
   ENUM_BIT_BUFFER_ERROR GetLastError();                   // 마지막 오류 코드를 반환합니다.
   string            GetLastErrorString();                 // 오류 설명 문자열을 반환합니다.
   void              ClearLastError() ;                    // 마지막 오류를 지웁니다.

   void              PrintHex();                           // 메인 버퍼를 헥스로 출력합니다(디버깅).
  };

위에제공된 전체 테스트 예제 " CBitBuffer_Test.mq5 " 는 오류를 감지하고 클래스의 기능을 검증하는 가장 좋은 방법입니다.

업데이트

2025.07.21 - v.1.01 :

• CBitBuffer 클래스는 읽기 작업이 시작된 후 불법적인 쓰기 시도를 적극적으로 방지하여 데이터 무결성을 유지하는 데 도움이 됩니다.
• 사용자가 혼합 연산을 시도하면 특정 오류(BIT_BUFFER_MIXED_OPERATION_ERROR)가 발생합니다.

2025.07.22 - v.1.02 :

• 읽기/쓰기 모드 간 전환 시 데이터 무결성을 유지하는 데 도움이 되는부분 플러시/리필을올바르게 처리하여 혼합 읽기/쓰기 작업을 허용하도록 클래스 설계를 변경했습니다 .
• 변수(m_operationMode)와 오류 코드(BIT_BUFFER_MIXED_OPERATION_ERROR)를 제거했습니다.
• 의도를 더 명확하게 파악할 수 있도록 코드 주석을 정리했습니다.
• 더 많은 테스트 사례를 다루기 위해 "CBitBuffer_Test.mq5"의 예제를 업데이트했습니다.