Little-endian byte cursor over one OrCAD Capture DSN stream. More...

#include <orcad_stream.h>

Public Member Functions
	ORCAD_STREAM (const void *aData, size_t aLength)

	ORCAD_STREAM (const std::vector< char > &aData)

uint8_t	ReadU8 ()

int8_t	ReadI8 ()

uint16_t	ReadU16 ()

int16_t	ReadI16 ()

uint32_t	ReadU32 ()

int32_t	ReadI32 ()

std::string	ReadLzt ()
	Read a length-prefixed zero-terminated string: u16 length, `length` content bytes, then a mandatory 0x00 terminator.

std::string	ReadZt ()
	Read a bare zero-terminated string (no length prefix); consumes the NUL.

std::vector< uint8_t >	ReadBytes (size_t aCount)
	Read exactly aCount bytes; throws IO_ERROR on overrun.

void	Skip (size_t aCount)
	Advance the cursor; throws IO_ERROR when aCount exceeds the remaining bytes.

void	Seek (size_t aOffset)
	Set the absolute cursor position.

size_t	GetOffset () const

size_t	Size () const

size_t	Remaining () const
	Bytes left; 0 when the cursor is at or past the end.

bool	AtEnd () const

const uint8_t *	Data () const
	Raw buffer access for scan-and-backtrack parsers (cache/hierarchy walkers).

int	PeekU8 (size_t aAhead=0) const
	Peek one byte at cursor + aAhead without advancing.

bool	PeekMatches (const uint8_t *aBytes, size_t aCount, size_t aAhead=0) const
	Compare aCount bytes at cursor + aAhead against aBytes without advancing.

bool	AtPreamble (size_t aAhead=0) const
	True when the 4 preamble bytes FF E4 5C 39 sit at cursor + aAhead.

bool	HasPreambleAt (size_t aAbsoluteOffset) const
	True when the preamble sits at the given absolute offset (false if out of range).

size_t	FindPreamble (size_t aFrom) const
	Find the next preamble at or after the given absolute offset.

void	Expect (const uint8_t *aBytes, size_t aCount, const wxString &aWhat)
	Consume aCount bytes and require them to equal aBytes; throws IO_ERROR naming aWhat and showing expected/actual hex on mismatch.

void	ExpectByte (uint8_t aValue, const wxString &aWhat)
	Consume one byte and require the given value.

void	ExpectPreamble (const wxString &aWhat)
	Consume the 4 preamble bytes; throws IO_ERROR naming aWhat when absent.

void	SkipOptionalPreambleBlock ()
	If the preamble sits at the cursor, consume it plus its u32 trailLen and the trailLen trailing bytes; otherwise do nothing.

Static Public Attributes
static constexpr uint8_t	PREAMBLE [4] = { 0xFF, 0xE4, 0x5C, 0x39 }
	Magic preceding every framed structure body: FF E4 5C 39.

static constexpr size_t	npos = static_cast<size_t>( -1 )
	Returned by FindPreamble() when no further preamble exists.

Private Member Functions
void	requireBytes (size_t aCount) const
	Throw IO_ERROR unless aCount bytes remain at the cursor.

Private Attributes
const uint8_t *	m_data

size_t	m_size

size_t	m_offset

Detailed Description

Little-endian byte cursor over one OrCAD Capture DSN stream.

String encoding inside the streams: u16 length + content bytes + NUL terminator ("length + zero-terminated", ReadLzt), or bare NUL-terminated (ReadZt). Text is Windows-1252 encoded; readers return the raw bytes as std::string and conversion to Unicode happens once at the UI boundary (see FromOrcadString()).

The recurring structure framing in Page/Cache/Schematic/Hierarchy streams:

N x long prefix : u8 typeId, u32 bodyLen, u32 zero 1 x short prefix: u8 typeId, i16 count, count x ( u32 nameIdx, u32 valueIdx ) preamble : FF E4 5C 39, u32 trailLen, trailLen bytes

The long-prefix bodyLen values record how many bytes of structure body follow the end of the prefix's own 9-byte record (outermost first), which yields reliable skip offsets for structures whose body cannot be parsed.

The stream does not own the buffer; the caller must keep it alive.

All reads are bounds-checked and throw IO_ERROR (via THROW_IO_ERROR) on overrun. The cursor itself may legally point past the end of the buffer (structure skip offsets computed from file data can do that); any subsequent read then throws.

Definition at line 57 of file orcad_stream.h.

Constructor & Destructor Documentation

◆ ORCAD_STREAM() [1/2]

ORCAD_STREAM::ORCAD_STREAM	(	const void *	aData,
		size_t	aLength )

Definition at line 42 of file orcad_stream.cpp.

References m_data, m_offset, and m_size.

Referenced by ORCAD_STREAM().

◆ ORCAD_STREAM() [2/2]

ORCAD_STREAM::ORCAD_STREAM ( const std::vector< char > & aData )

explicit

Definition at line 50 of file orcad_stream.cpp.

References ORCAD_STREAM().

Member Function Documentation

◆ AtEnd()

bool ORCAD_STREAM::AtEnd ( ) const

inline

Definition at line 114 of file orcad_stream.h.

References m_offset, and m_size.

◆ AtPreamble()

bool ORCAD_STREAM::AtPreamble ( size_t aAhead = 0 ) const

True when the 4 preamble bytes FF E4 5C 39 sit at cursor + aAhead.

Definition at line 205 of file orcad_stream.cpp.

References PeekMatches(), and PREAMBLE.

Referenced by readOccScope(), and SkipOptionalPreambleBlock().

◆ Data()

const uint8_t * ORCAD_STREAM::Data ( ) const

inline

Raw buffer access for scan-and-backtrack parsers (cache/hierarchy walkers).

Definition at line 117 of file orcad_stream.h.

References m_data.

Referenced by OrcadFindStructureStart(), and OrcadReadHierarchyLinks().

◆ Expect()

void ORCAD_STREAM::Expect	(	const uint8_t *	aBytes,
		size_t	aCount,
		const wxString &	aWhat )

Consume aCount bytes and require them to equal aBytes; throws IO_ERROR naming aWhat and showing expected/actual hex on mismatch.

The bytes are consumed even when the check fails (callers recover by seeking).

Definition at line 235 of file orcad_stream.cpp.

References hexOf(), m_offset, ReadBytes(), and THROW_IO_ERROR.

Referenced by ExpectByte(), and ExpectPreamble().

◆ ExpectByte()

void ORCAD_STREAM::ExpectByte	(	uint8_t	aValue,
		const wxString &	aWhat )

Consume one byte and require the given value.

Definition at line 249 of file orcad_stream.cpp.

References Expect().

Referenced by OrcadReadDisplayProp(), OrcadReadHierarchyLinks(), readOccurrence(), v2DisplayProp(), v2PrimBody(), and v2SymbolPin().

◆ ExpectPreamble()

void ORCAD_STREAM::ExpectPreamble ( const wxString & aWhat )

Consume the 4 preamble bytes; throws IO_ERROR naming aWhat when absent.

Definition at line 255 of file orcad_stream.cpp.

References Expect(), and PREAMBLE.

Referenced by readOccHeader().

◆ FindPreamble()

size_t ORCAD_STREAM::FindPreamble ( size_t aFrom ) const

Find the next preamble at or after the given absolute offset.

Returns: the absolute offset of the magic, or ORCAD_STREAM::npos.

Definition at line 220 of file orcad_stream.cpp.

References m_data, m_size, npos, and PREAMBLE.

Referenced by OrcadParseCache(), and OrcadReadHierarchyLinks().

◆ GetOffset()

size_t ORCAD_STREAM::GetOffset ( ) const

inline

Definition at line 108 of file orcad_stream.h.

References m_offset.

Referenced by OrcadParseCache(), OrcadParseLibrary(), OrcadReadDevice(), OrcadReadDrawnInstance(), OrcadReadHierarchyLinks(), OrcadReadPackage(), OrcadReadPinInst(), OrcadReadPrimitive(), OrcadReadSymbolDef(), and OrcadReadSymbolPin().

◆ HasPreambleAt()

bool ORCAD_STREAM::HasPreambleAt ( size_t aAbsoluteOffset ) const

True when the preamble sits at the given absolute offset (false if out of range).

Definition at line 211 of file orcad_stream.cpp.

References m_data, m_size, and PREAMBLE.

◆ PeekMatches()

bool ORCAD_STREAM::PeekMatches	(	const uint8_t *	aBytes,
		size_t	aCount,
		size_t	aAhead = 0 ) const

Compare aCount bytes at cursor + aAhead against aBytes without advancing.

Returns: false (never throws) when fewer than aCount bytes remain.

Definition at line 194 of file orcad_stream.cpp.

References m_data, m_offset, and m_size.

Referenced by AtPreamble(), OrcadReadDevice(), and v2Device().

◆ PeekU8()

int ORCAD_STREAM::PeekU8 ( size_t aAhead = 0 ) const

Peek one byte at cursor + aAhead without advancing.

Returns: the byte value 0..255, or -1 when the position is out of range.

Definition at line 183 of file orcad_stream.cpp.

References m_data, m_offset, and m_size.

Referenced by OrcadReadSymbolDef(), OrcadReadSymbolPin(), v2Structure(), and v2SymbolPin().

◆ ReadBytes()

std::vector< uint8_t > ORCAD_STREAM::ReadBytes ( size_t aCount )

Read exactly aCount bytes; throws IO_ERROR on overrun.

Definition at line 161 of file orcad_stream.cpp.

References m_data, m_offset, and requireBytes().

Referenced by Expect(), and OrcadParseLibrary().

◆ ReadI16()

int16_t ORCAD_STREAM::ReadI16 ( )

Definition at line 90 of file orcad_stream.cpp.

References ReadU16().

Referenced by OrcadReadDisplayProp(), OrcadReadDrawnInstance(), OrcadReadGraphicInst(), OrcadReadPinInst(), OrcadReadPlacedInstance(), OrcadReadSymbolDef(), readOccHeader(), v2DisplayProp(), v2GraphicInst(), v2LibSymbolDef(), v2PinInst(), v2PlacedInstance(), v2Prefix(), v2PrimBody(), and v2SymbolDef().

◆ ReadI32()

int32_t ORCAD_STREAM::ReadI32 ( )

Definition at line 108 of file orcad_stream.cpp.

References ReadU32().

Referenced by OrcadParsePageV2(), OrcadReadAlias(), OrcadReadBusEntry(), OrcadReadSymbolPin(), OrcadReadWire(), v2Alias(), v2PrimBody(), v2SymbolPin(), and v2Wire().

◆ ReadI8()

int8_t ORCAD_STREAM::ReadI8 ( )

Definition at line 74 of file orcad_stream.cpp.

References ReadU8().

◆ ReadLzt()

std::string ORCAD_STREAM::ReadLzt ( )

Read a length-prefixed zero-terminated string: u16 length, length content bytes, then a mandatory 0x00 terminator.

Throws IO_ERROR when the string exceeds the stream or the terminator is missing. Returns raw CP-1252 bytes.

Definition at line 114 of file orcad_stream.cpp.

References m_data, m_offset, m_size, ReadU16(), and THROW_IO_ERROR.

Referenced by OrcadParseLibrary(), OrcadParsePage(), OrcadParsePageOrder(), OrcadParsePageV2(), OrcadReadAlias(), OrcadReadDevice(), OrcadReadDrawnInstance(), OrcadReadErcObject(), OrcadReadGraphicInst(), OrcadReadHierarchyLinks(), OrcadReadOccurrenceTree(), OrcadReadPackage(), OrcadReadPlacedInstance(), OrcadReadSymbolDef(), OrcadReadSymbolPin(), OrcadReadT0x34Raw(), readOccScope(), readOccurrence(), v2Alias(), v2Device(), v2GraphicInst(), v2LibSymbolDef(), v2Package(), v2PartCell(), v2PlacedInstance(), v2PrimBody(), v2SymbolDef(), and v2SymbolPin().

◆ ReadU16()

uint16_t ORCAD_STREAM::ReadU16 ( )

◆ ReadU32()

uint32_t ORCAD_STREAM::ReadU32 ( )

◆ ReadU8()

uint8_t ORCAD_STREAM::ReadU8 ( )

Definition at line 67 of file orcad_stream.cpp.

References m_data, m_offset, and requireBytes().

Referenced by OrcadReadDevice(), OrcadReadDisplayProp(), OrcadReadDrawnInstance(), OrcadReadGraphicInst(), OrcadReadOccurrenceTree(), OrcadReadPlacedInstance(), OrcadReadPrimitive(), ReadI8(), readOccHeader(), v2Device(), v2DisplayProp(), v2GraphicInst(), v2PlacedInstance(), v2Prefix(), v2PrimBody(), and v2Primitive().

◆ ReadZt()

std::string ORCAD_STREAM::ReadZt ( )

Read a bare zero-terminated string (no length prefix); consumes the NUL.

Throws IO_ERROR if no terminator exists before the end of the stream.

Definition at line 141 of file orcad_stream.cpp.

References end, m_data, m_offset, m_size, and THROW_IO_ERROR.

Referenced by OrcadParseLibrary().

◆ Remaining()

size_t ORCAD_STREAM::Remaining ( ) const

inline

Bytes left; 0 when the cursor is at or past the end.

Definition at line 112 of file orcad_stream.h.

References m_offset, and m_size.

Referenced by OrcadParseLibrary(), OrcadParseOlbPackageStreamV2(), OrcadParseOlbSymbolStreamV2(), and v2CheckCount().

◆ requireBytes()

void ORCAD_STREAM::requireBytes ( size_t aCount ) const

private

Throw IO_ERROR unless aCount bytes remain at the cursor.

Definition at line 56 of file orcad_stream.cpp.

References m_offset, m_size, and THROW_IO_ERROR.

Referenced by ReadBytes(), ReadU16(), ReadU32(), and ReadU8().

◆ Seek()

void ORCAD_STREAM::Seek ( size_t aOffset )

inline

Set the absolute cursor position.

Positions beyond Size() are permitted (skip offsets recorded in the file may point past a truncated stream); any read attempted from such a position throws.

Definition at line 106 of file orcad_stream.h.

References m_offset.

Referenced by OrcadFindStructureStart(), OrcadParseCache(), OrcadParseLibrary(), OrcadReadDevice(), OrcadReadDrawnInstance(), OrcadReadHierarchyLinks(), OrcadReadPackage(), OrcadReadPinInst(), OrcadReadSymbolDef(), and OrcadReadSymbolPin().

◆ Size()

size_t ORCAD_STREAM::Size ( ) const

inline

Definition at line 109 of file orcad_stream.h.

References m_size.

Referenced by OrcadFindStructureStart().

◆ Skip()

void ORCAD_STREAM::Skip ( size_t aCount )

Advance the cursor; throws IO_ERROR when aCount exceeds the remaining bytes.

Definition at line 170 of file orcad_stream.cpp.

References m_offset, m_size, and THROW_IO_ERROR.

Referenced by OrcadParseLibrary(), OrcadParsePage(), OrcadParsePageOrder(), OrcadParsePageSettings(), OrcadParsePageV2(), OrcadReadBusEntry(), OrcadReadDevice(), OrcadReadDrawnInstance(), OrcadReadGraphicInst(), OrcadReadOccurrenceTree(), OrcadReadPlacedInstance(), OrcadReadPort(), OrcadReadSymbolDef(), OrcadReadSymbolPin(), OrcadReadT0x34Raw(), OrcadReadT0x35Raw(), OrcadReadTitleBlock(), OrcadReadWire(), readOccHeader(), readOccScope(), SkipOptionalPreambleBlock(), v2Device(), v2GraphicInst(), v2PlacedInstance(), v2PrimBody(), v2SymbolPin(), and v2Wire().

◆ SkipOptionalPreambleBlock()

void ORCAD_STREAM::SkipOptionalPreambleBlock ( )

If the preamble sits at the cursor, consume it plus its u32 trailLen and the trailLen trailing bytes; otherwise do nothing.

Legacy primitive records have no trailing preamble, modern ones do.

Definition at line 261 of file orcad_stream.cpp.

References AtPreamble(), ReadU32(), and Skip().

Member Data Documentation

◆ m_data

const uint8_t* ORCAD_STREAM::m_data

private

Definition at line 171 of file orcad_stream.h.

Referenced by Data(), FindPreamble(), HasPreambleAt(), ORCAD_STREAM(), PeekMatches(), PeekU8(), ReadBytes(), ReadLzt(), ReadU16(), ReadU32(), ReadU8(), and ReadZt().

◆ m_offset

size_t ORCAD_STREAM::m_offset

private

Definition at line 173 of file orcad_stream.h.

Referenced by AtEnd(), Expect(), GetOffset(), ORCAD_STREAM(), PeekMatches(), PeekU8(), ReadBytes(), ReadLzt(), ReadU16(), ReadU32(), ReadU8(), ReadZt(), Remaining(), requireBytes(), Seek(), and Skip().

◆ m_size

size_t ORCAD_STREAM::m_size

private

Definition at line 172 of file orcad_stream.h.

Referenced by AtEnd(), FindPreamble(), HasPreambleAt(), ORCAD_STREAM(), PeekMatches(), PeekU8(), ReadLzt(), ReadZt(), Remaining(), requireBytes(), Size(), and Skip().

◆ npos

size_t ORCAD_STREAM::npos = static_cast<size_t>( -1 )

staticconstexpr

Returned by FindPreamble() when no further preamble exists.

Definition at line 64 of file orcad_stream.h.

Referenced by FindPreamble(), OrcadParseCache(), and OrcadReadHierarchyLinks().

◆ PREAMBLE

uint8_t ORCAD_STREAM::PREAMBLE[4] = { 0xFF, 0xE4, 0x5C, 0x39 }

staticconstexpr

Magic preceding every framed structure body: FF E4 5C 39.

Definition at line 61 of file orcad_stream.h.

Referenced by AtPreamble(), BOOST_AUTO_TEST_CASE(), ExpectPreamble(), FindPreamble(), and HasPreambleAt().

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

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ORCAD_STREAM() [1/2]

◆ ORCAD_STREAM() [2/2]

Member Function Documentation

◆ AtEnd()

◆ AtPreamble()

◆ Data()

◆ Expect()

◆ ExpectByte()

◆ ExpectPreamble()

◆ FindPreamble()

◆ GetOffset()

◆ HasPreambleAt()

◆ PeekMatches()

◆ PeekU8()

◆ ReadBytes()

◆ ReadI16()

◆ ReadI32()

◆ ReadI8()

◆ ReadLzt()

◆ ReadU16()

◆ ReadU32()

◆ ReadU8()

◆ ReadZt()

◆ Remaining()

◆ requireBytes()

◆ Seek()

◆ Size()

◆ Skip()

◆ SkipOptionalPreambleBlock()

Member Data Documentation

◆ m_data

◆ m_offset

◆ m_size

◆ npos

◆ PREAMBLE