Low-level binary reader for DipTrace file formats. More...

#include <diptrace_binary_reader.h>

Public Member Functions
	BINARY_READER (const wxString &aFileName)
	Construct a reader by loading the given file into memory.

	~BINARY_READER ()

size_t	GetOffset () const
	Return the current byte offset within the file.

void	SetOffset (size_t aOffset)
	Set the read position to an absolute byte offset.

void	Skip (size_t aBytes)
	Advance the read position by the given number of bytes.

size_t	GetFileSize () const
	Return the total size of the loaded file in bytes.

bool	IsEOF () const
	Return true if the read position has reached or passed the end of file.

const uint8_t *	GetData () const
	Return a pointer to the raw file data buffer.

void	SetVersion (int aVersion)
	Set the DipTrace format version.

int	GetVersion () const
	Return the currently configured format version.

void	SetStringEncoding (STRING_ENCODING aEncoding)
	Override DipTrace string decoding when a file family has a deterministic string-encoding cutover that differs from the shared version threshold.

void	DetectStringEncoding (size_t aProbeOffset)
	Detect the string encoding from the bytes at `aProbeOffset`, which must sit at the start of a non-empty DipTrace string, and pin the encoding override accordingly.

uint8_t	ReadByte ()
	Read a single unsigned byte and advance the position by 1.

int	ReadInt3 ()
	Read a 3-byte big-endian biased integer (bias 1,000,000) and advance the position by 3.

int	ReadInt4 ()
	Read a 4-byte big-endian biased integer (bias 1,000,000,000) and advance the position by 4.

wxString	ReadString ()
	Read a string using the configured encoding.

void	ReadColor (uint8_t &r, uint8_t &g, uint8_t &b)
	Read a 3-byte RGB color value.

void	ReadBytes (uint8_t *aDst, size_t aCount)
	Read a block of raw bytes into the caller's buffer.

int	PeekInt3 () const
	Peek at the next 3-byte biased integer without advancing the position.

int	PeekInt4 () const
	Peek at the next 4-byte biased integer without advancing the position.

uint8_t	PeekByte () const
	Peek at the next byte without advancing the position.

size_t	FindPattern (const uint8_t *aPattern, size_t aPatternLen, size_t aStart, size_t aEnd) const
	Search for a byte pattern in the file data.

size_t	FindString (const wxString &aStr, size_t aStart, size_t aEnd) const
	Search for a UTF-16-BE encoded string in the file data, including its two-byte length prefix.

bool	TryReadString (wxString &aResult)
	Attempt to read a string at the current position.

Static Public Member Functions
static int	DipTraceToKiCadNm (int aDipTraceCoord)
	Convert a DipTrace coordinate value (10 nm units) to KiCad nanometers.

static double	DipTraceToMM (int aDipTraceCoord)
	Convert a DipTrace coordinate value (10 nm units) to millimeters.

Private Member Functions
wxString	ReadStringUTF16 ()
	Read a v39+ UTF-16-BE string: uint16-BE char count + UTF-16-BE data.

wxString	ReadStringASCII ()
	Read a v37 legacy ASCII string: int3(byte_count) + raw ASCII bytes.

bool	TryReadStringUTF16 (wxString &aResult)
	Attempt to read a UTF-16-BE string with validation.

bool	TryReadStringASCII (wxString &aResult)
	Attempt to read a legacy ASCII string with validation.

void	ThrowEOFError (size_t aBytesNeeded) const
	Throw IO_ERROR with a message indicating a read past end of file.

Static Private Member Functions
static bool	IsPrintableString (const wxString &aStr)
	Verify that all characters in aStr are printable or common whitespace (space, tab, CR, LF).

Private Attributes
std::vector< uint8_t >	m_data
	Entire file contents loaded into memory.

size_t	m_offset
	Current read position (byte offset).

int	m_version
	DipTrace format version.

STRING_ENCODING	m_stringEncoding
	Explicit string encoding override.

Detailed Description

Low-level binary reader for DipTrace file formats.

DipTrace files (.dip for PCB, .dch for schematic) use a proprietary big-endian binary encoding with biased integers. This reader loads the entire file into memory and provides methods to decode each primitive type.

Shared by both the PCB and schematic importers.

Definition at line 85 of file diptrace_binary_reader.h.

Constructor & Destructor Documentation

◆ BINARY_READER()

BINARY_READER::BINARY_READER ( const wxString & aFileName )

Construct a reader by loading the given file into memory.

Parameters

aFileName path to the DipTrace binary file.

Exceptions

IO_ERROR if the file cannot be opened or read.

Definition at line 38 of file diptrace_binary_reader.cpp.

References _, DIPTRACE::BY_VERSION, m_data, m_offset, m_stringEncoding, m_version, and THROW_IO_ERROR.

◆ ~BINARY_READER()

BINARY_READER::~BINARY_READER ( )

Definition at line 74 of file diptrace_binary_reader.cpp.

Member Function Documentation

◆ DetectStringEncoding()

void BINARY_READER::DetectStringEncoding ( size_t aProbeOffset )

Detect the string encoding from the bytes at aProbeOffset, which must sit at the start of a non-empty DipTrace string, and pin the encoding override accordingly.

DipTrace ships files of the same format version in both encodings (e.g. v37 schematics exist as legacy ASCII and as UTF-16-BE), so the version threshold alone is not reliable. The two framings are mutually exclusive on real string bytes – the ASCII length is the int3 bias 0x0F42xx while a small UTF-16 char count starts 0x00xx – so exactly one parses as a printable string. The encoding is left unchanged when the probe is inconclusive.

Parameters

aProbeOffset file offset of a known non-empty string field.

Definition at line 323 of file diptrace_binary_reader.cpp.

References DIPTRACE::LEGACY_ASCII, m_offset, m_stringEncoding, TryReadStringASCII(), TryReadStringUTF16(), and DIPTRACE::UTF16_BE.

◆ DipTraceToKiCadNm()

int BINARY_READER::DipTraceToKiCadNm ( int aDipTraceCoord )

static

Convert a DipTrace coordinate value (10 nm units) to KiCad nanometers.

Parameters

aDipTraceCoord coordinate in DipTrace units.

Returns: coordinate in nanometers.

Definition at line 234 of file diptrace_binary_reader.cpp.

◆ DipTraceToMM()

double BINARY_READER::DipTraceToMM ( int aDipTraceCoord )

static

Convert a DipTrace coordinate value (10 nm units) to millimeters.

Parameters

aDipTraceCoord coordinate in DipTrace units.

Returns: coordinate in millimeters.

Definition at line 240 of file diptrace_binary_reader.cpp.

References DIPTRACE::DIPTRACE_COORD_TO_MM.

◆ FindPattern()

size_t BINARY_READER::FindPattern	(	const uint8_t *	aPattern,
		size_t	aPatternLen,
		size_t	aStart,
		size_t	aEnd ) const

Search for a byte pattern in the file data.

Parameters

aPattern	pointer to the pattern bytes.
aPatternLen	length of the pattern in bytes.
aStart	byte offset to begin searching (inclusive).
aEnd	byte offset to stop searching (exclusive). Use 0 to search to end of file.

Returns: byte offset of the first match, or std::string::npos if not found.

Definition at line 249 of file diptrace_binary_reader.cpp.

References m_data.

Referenced by FindString().

◆ FindString()

size_t BINARY_READER::FindString	(	const wxString &	aStr,
		size_t	aStart,
		size_t	aEnd ) const

Search for a UTF-16-BE encoded string in the file data, including its two-byte length prefix.

Parameters

aStr	the string to search for.
aStart	byte offset to begin searching.
aEnd	byte offset to stop searching. Use 0 to search to end of file.

Returns: byte offset of the length prefix of the first match, or std::string::npos if not found.

Definition at line 270 of file diptrace_binary_reader.cpp.

References FindPattern().

◆ GetData()

const uint8_t * DIPTRACE::BINARY_READER::GetData ( ) const

inline

Return a pointer to the raw file data buffer.

Definition at line 126 of file diptrace_binary_reader.h.

References m_data.

◆ GetFileSize()

size_t DIPTRACE::BINARY_READER::GetFileSize ( ) const

inline

Return the total size of the loaded file in bytes.

Definition at line 120 of file diptrace_binary_reader.h.

References m_data.

◆ GetOffset()

size_t DIPTRACE::BINARY_READER::GetOffset ( ) const

inline

Return the current byte offset within the file.

Definition at line 101 of file diptrace_binary_reader.h.

References m_offset.

◆ GetVersion()

int DIPTRACE::BINARY_READER::GetVersion ( ) const

inline

Return the currently configured format version.

Definition at line 142 of file diptrace_binary_reader.h.

References m_version.

◆ IsEOF()

bool DIPTRACE::BINARY_READER::IsEOF ( ) const

inline

Return true if the read position has reached or passed the end of file.

Definition at line 123 of file diptrace_binary_reader.h.

References m_data, and m_offset.

◆ IsPrintableString()

bool BINARY_READER::IsPrintableString ( const wxString & aStr )

staticprivate

Verify that all characters in aStr are printable or common whitespace (space, tab, CR, LF).

Definition at line 510 of file diptrace_binary_reader.cpp.

Referenced by TryReadStringASCII(), and TryReadStringUTF16().

◆ PeekByte()

uint8_t BINARY_READER::PeekByte ( ) const

Peek at the next byte without advancing the position.

Exceptions

IO_ERROR if at end of file.

Definition at line 219 of file diptrace_binary_reader.cpp.

References _, m_data, m_offset, and THROW_IO_ERROR.

◆ PeekInt3()

int BINARY_READER::PeekInt3 ( ) const

Peek at the next 3-byte biased integer without advancing the position.

Exceptions

IO_ERROR if there are fewer than 3 bytes remaining.

Definition at line 182 of file diptrace_binary_reader.cpp.

References _, DIPTRACE::INT3_BIAS, m_data, m_offset, and THROW_IO_ERROR.

◆ PeekInt4()

int BINARY_READER::PeekInt4 ( ) const

Peek at the next 4-byte biased integer without advancing the position.

Exceptions

IO_ERROR if there are fewer than 4 bytes remaining.

Definition at line 200 of file diptrace_binary_reader.cpp.

References _, DIPTRACE::INT4_BIAS, m_data, m_offset, and THROW_IO_ERROR.

◆ ReadByte()

uint8_t BINARY_READER::ReadByte ( )

Read a single unsigned byte and advance the position by 1.

Exceptions

IO_ERROR on read past end of file.

Definition at line 106 of file diptrace_binary_reader.cpp.

References m_data, m_offset, and ThrowEOFError().

Referenced by ReadColor().

◆ ReadBytes()

void BINARY_READER::ReadBytes	(	uint8_t *	aDst,
		size_t	aCount )

Read a block of raw bytes into the caller's buffer.

Parameters

aDst	destination buffer (must hold at least aCount bytes).
aCount	number of bytes to read.

Exceptions

IO_ERROR on read past end of file.

Definition at line 169 of file diptrace_binary_reader.cpp.

References m_data, m_offset, and ThrowEOFError().

◆ ReadColor()

void BINARY_READER::ReadColor	(	uint8_t &	r,
		uint8_t &	g,
		uint8_t &	b )

Read a 3-byte RGB color value.

Parameters

[out]	r	red component (0-255).
[out]	g	green component (0-255).
[out]	b	blue component (0-255).

Exceptions

IO_ERROR on read past end of file.

Definition at line 161 of file diptrace_binary_reader.cpp.

References ReadByte().

Referenced by ReadColorPacked().

◆ ReadInt3()

int BINARY_READER::ReadInt3 ( )

Read a 3-byte big-endian biased integer (bias 1,000,000) and advance the position by 3.

Decoding: value = (byte[0]<<16 | byte[1]<<8 | byte[2]) - 1,000,000

Returns: the decoded signed integer value.

Exceptions

IO_ERROR on read past end of file.

Definition at line 117 of file diptrace_binary_reader.cpp.

References DIPTRACE::INT3_BIAS, m_data, m_offset, and ThrowEOFError().

Referenced by ReadStringASCII().

◆ ReadInt4()

int BINARY_READER::ReadInt4 ( )

Read a 4-byte big-endian biased integer (bias 1,000,000,000) and advance the position by 4.

Decoding: value = (byte[0]<<24 | byte[1]<<16 | byte[2]<<8 | byte[3])

1,000,000,000

Returns: the decoded signed integer value.

Exceptions

IO_ERROR on read past end of file.

Definition at line 131 of file diptrace_binary_reader.cpp.

References DIPTRACE::INT4_BIAS, m_data, m_offset, and ThrowEOFError().

◆ ReadString()

wxString BINARY_READER::ReadString ( )

Read a string using the configured encoding.

legacy ASCII: int3(byte_count) + ASCII bytes
UTF-16-BE: uint16-BE(char_count) + UTF-16-BE data

Returns: the decoded wxString.

Exceptions

IO_ERROR on read past end of file or corrupt string data.

Definition at line 146 of file diptrace_binary_reader.cpp.

References DIPTRACE::LEGACY_ASCII, DIPTRACE::LEGACY_STRING_VERSION, m_stringEncoding, m_version, ReadStringASCII(), ReadStringUTF16(), and DIPTRACE::UTF16_BE.

◆ ReadStringASCII()

wxString BINARY_READER::ReadStringASCII ( )

private

Read a v37 legacy ASCII string: int3(byte_count) + raw ASCII bytes.

Definition at line 388 of file diptrace_binary_reader.cpp.

References _, m_data, m_offset, DIPTRACE::MAX_STRING_CHARS, ReadInt3(), result, THROW_IO_ERROR, and ThrowEOFError().

Referenced by ReadString().

◆ ReadStringUTF16()

wxString BINARY_READER::ReadStringUTF16 ( )

private

Read a v39+ UTF-16-BE string: uint16-BE char count + UTF-16-BE data.

Definition at line 354 of file diptrace_binary_reader.cpp.

References _, m_data, m_offset, DIPTRACE::MAX_STRING_CHARS, result, THROW_IO_ERROR, and ThrowEOFError().

Referenced by ReadString().

◆ SetOffset()

void BINARY_READER::SetOffset ( size_t aOffset )

Set the read position to an absolute byte offset.

Parameters

aOffset byte offset from the start of the file.

Exceptions

IO_ERROR if aOffset is beyond the end of the file.

Definition at line 82 of file diptrace_binary_reader.cpp.

References _, m_data, m_offset, and THROW_IO_ERROR.

◆ SetStringEncoding()

void DIPTRACE::BINARY_READER::SetStringEncoding ( STRING_ENCODING aEncoding )

inline

Override DipTrace string decoding when a file family has a deterministic string-encoding cutover that differs from the shared version threshold.

Definition at line 148 of file diptrace_binary_reader.h.

References m_stringEncoding.

◆ SetVersion()

void DIPTRACE::BINARY_READER::SetVersion ( int aVersion )

inline

Set the DipTrace format version.

The version affects default string decoding: versions <= 37 use the legacy int3+ASCII encoding while versions >= 39 use uint16+UTF-16-BE. File-family parsers can override this with SetStringEncoding().

Parameters

aVersion DipTrace format version number.

Definition at line 139 of file diptrace_binary_reader.h.

References m_version.

◆ Skip()

void BINARY_READER::Skip ( size_t aBytes )

Advance the read position by the given number of bytes.

Parameters

aBytes number of bytes to skip.

Exceptions

IO_ERROR if skipping would read past the end of the file.

Definition at line 94 of file diptrace_binary_reader.cpp.

References m_data, m_offset, and ThrowEOFError().

◆ ThrowEOFError()

void BINARY_READER::ThrowEOFError ( size_t aBytesNeeded ) const

private

Throw IO_ERROR with a message indicating a read past end of file.

Parameters

aBytesNeeded number of bytes the caller tried to read.

Definition at line 527 of file diptrace_binary_reader.cpp.

References _, m_data, m_offset, and THROW_IO_ERROR.

Referenced by ReadByte(), ReadBytes(), ReadInt3(), ReadInt4(), ReadStringASCII(), ReadStringUTF16(), and Skip().

◆ TryReadString()

bool BINARY_READER::TryReadString ( wxString & aResult )

Attempt to read a string at the current position.

On success, the position is advanced past the string and aResult is populated. On failure the position is restored and false is returned.

Uses the version-appropriate encoding, with additional sanity checks: character count must be <= 500, and all decoded characters must be printable or whitespace.

Parameters

[out] aResult receives the decoded string on success.

Returns: true if a valid string was read.

Definition at line 308 of file diptrace_binary_reader.cpp.

References DIPTRACE::LEGACY_ASCII, DIPTRACE::LEGACY_STRING_VERSION, m_stringEncoding, m_version, TryReadStringASCII(), TryReadStringUTF16(), and DIPTRACE::UTF16_BE.

◆ TryReadStringASCII()

bool BINARY_READER::TryReadStringASCII ( wxString & aResult )

private

Attempt to read a legacy ASCII string with validation.

Returns false and restores the position on failure.

Definition at line 461 of file diptrace_binary_reader.cpp.

References DIPTRACE::INT3_BIAS, IsPrintableString(), m_data, and m_offset.

Referenced by DetectStringEncoding(), and TryReadString().

◆ TryReadStringUTF16()

bool BINARY_READER::TryReadStringUTF16 ( wxString & aResult )

private

Attempt to read a UTF-16-BE string with validation.

Returns false and restores the position on failure.

Definition at line 414 of file diptrace_binary_reader.cpp.

References IsPrintableString(), m_data, and m_offset.

Referenced by DetectStringEncoding(), and TryReadString().

Member Data Documentation

◆ m_data

std::vector<uint8_t> DIPTRACE::BINARY_READER::m_data

private

Entire file contents loaded into memory.

Definition at line 349 of file diptrace_binary_reader.h.

Referenced by BINARY_READER(), FindPattern(), GetData(), GetFileSize(), IsEOF(), PeekByte(), PeekInt3(), PeekInt4(), ReadByte(), ReadBytes(), ReadInt3(), ReadInt4(), ReadStringASCII(), ReadStringUTF16(), SetOffset(), Skip(), ThrowEOFError(), TryReadStringASCII(), and TryReadStringUTF16().

◆ m_offset

size_t DIPTRACE::BINARY_READER::m_offset

private

Current read position (byte offset).

Definition at line 350 of file diptrace_binary_reader.h.

Referenced by BINARY_READER(), DetectStringEncoding(), GetOffset(), IsEOF(), PeekByte(), PeekInt3(), PeekInt4(), ReadByte(), ReadBytes(), ReadInt3(), ReadInt4(), ReadStringASCII(), ReadStringUTF16(), SetOffset(), Skip(), ThrowEOFError(), TryReadStringASCII(), and TryReadStringUTF16().

◆ m_stringEncoding

STRING_ENCODING DIPTRACE::BINARY_READER::m_stringEncoding

private

Explicit string encoding override.

Definition at line 352 of file diptrace_binary_reader.h.

Referenced by BINARY_READER(), DetectStringEncoding(), ReadString(), SetStringEncoding(), and TryReadString().

◆ m_version

int DIPTRACE::BINARY_READER::m_version

private

DipTrace format version.

Definition at line 351 of file diptrace_binary_reader.h.

Referenced by BINARY_READER(), GetVersion(), ReadString(), SetVersion(), and TryReadString().

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BINARY_READER()

◆ ~BINARY_READER()

Member Function Documentation

◆ DetectStringEncoding()

◆ DipTraceToKiCadNm()

◆ DipTraceToMM()

◆ FindPattern()

◆ FindString()

◆ GetData()

◆ GetFileSize()

◆ GetOffset()

◆ GetVersion()

◆ IsEOF()

◆ IsPrintableString()

◆ PeekByte()

◆ PeekInt3()

◆ PeekInt4()

◆ ReadByte()

◆ ReadBytes()

◆ ReadColor()

◆ ReadInt3()

◆ ReadInt4()

◆ ReadString()

◆ ReadStringASCII()

◆ ReadStringUTF16()

◆ SetOffset()

◆ SetStringEncoding()

◆ SetVersion()

◆ Skip()

◆ ThrowEOFError()

◆ TryReadString()

◆ TryReadStringASCII()

◆ TryReadStringUTF16()

Member Data Documentation

◆ m_data

◆ m_offset

◆ m_stringEncoding

◆ m_version