Class to efficiently track reference designators and provide next available designators. More...

#include <refdes_tracker.h>

Classes
struct	PREFIX_DATA
	Data structure for tracking used numbers and caching next available values. More...

Public Member Functions
	REFDES_TRACKER (bool aThreadSafe=false)
	Constructor.

bool	Insert (const std::string &aRefDes)
	Insert a reference designator into the tracker.

bool	Contains (const std::string &aRefDes) const
	Check if a reference designator exists in the tracker.

int	GetNextRefDes (const std::string &aPrefix, int aMinValue=1)
	Get the next available reference designator for a given prefix and reserve it.

int	GetNextRefDesForUnits (const SCH_REFERENCE &aRef, const std::map< int, std::vector< SCH_REFERENCE > > &aRefNumberMap, const std::vector< int > &aRequiredUnits, int aMinValue)
	Get the next available reference designator number for multi-unit symbols.

void	SetUnitsChecker (const UNITS_CHECKER_FUNC< SCH_REFERENCE > &aChecker)
	Set an external units checker function for SCH_REFERENCE objects.

void	ClearUnitsChecker ()
	Clear the external units checker, reverting to default behavior.

std::string	Serialize () const
	Serialize the tracker data to a compact string representation.

bool	Deserialize (const std::string &aData)
	Deserialize tracker data from string representation.

void	Clear ()
	Clear all stored reference designators.

size_t	Size () const
	Get the total count of stored reference designators.

bool	GetReuseRefDes () const

void	SetReuseRefDes (bool aReuse)

Private Member Functions
bool	insertImpl (const std::string &aRefDes)
	Internal implementation of Insert without locking.

void	clearImpl ()
	Clear all internal data structures without locking.

bool	containsImpl (const std::string &aRefDes) const
	Check if a reference designator exists in the tracker without locking.

std::pair< std::string, int >	parseRefDes (const std::string &aRefDes) const
	Parse a reference designator into prefix and numerical suffix.

void	updateCacheOnInsert (PREFIX_DATA &aData, int aInsertedNumber) const
	Update cached next available values when a number is inserted.

int	findNextAvailable (const PREFIX_DATA &aData, int aMinValue) const
	Find next available number for a prefix starting from a minimum value.

bool	areUnitsAvailable (const SCH_REFERENCE &aRef, const std::vector< SCH_REFERENCE > &aRefVector, const std::vector< int > &aRequiredUnits) const
	Check if all required units are available for a given reference number.

bool	insertNumber (const std::string &aPrefix, int aNumber)
	Insert a number for a specific prefix, updating internal structures.

std::string	escapeForSerialization (const std::string &aStr) const
	Escape special characters for serialization.

std::string	unescapeFromSerialization (const std::string &aStr) const
	Unescape special characters from serialization.

std::vector< std::string >	splitString (const std::string &aStr, char aDelimiter) const
	Split string by delimiter, handling escaped characters.

void	updateBaseNext (PREFIX_DATA &aData) const

Private Attributes
std::mutex	m_mutex
	Mutex for thread safety.

bool	m_threadSafe
	True if thread safety is enabled.

std::unordered_map< std::string, PREFIX_DATA >	m_prefixData
	Map from prefix to its tracking data.

std::unordered_set< std::string >	m_allRefDes

bool	m_reuseRefDes
	If true, allows reusing existing reference designators.

UNITS_CHECKER_FUNC< SCH_REFERENCE >	m_externalUnitsChecker
	External units checker function (optional)

Detailed Description

Class to efficiently track reference designators and provide next available designators.

Maintains internal data structures for O(1) lookup of existing designators and efficient retrieval of next available numerical suffixes for any given prefix.

Definition at line 58 of file refdes_tracker.h.

Constructor & Destructor Documentation

◆ REFDES_TRACKER()

REFDES_TRACKER::REFDES_TRACKER ( bool aThreadSafe = false )

explicit

Constructor.

Parameters

aThreadSafe if true, enables mutex locking for thread-safe operation

Definition at line 28 of file refdes_tracker.cpp.

Member Function Documentation

◆ areUnitsAvailable()

bool REFDES_TRACKER::areUnitsAvailable	(	const SCH_REFERENCE &	aRef,
		const std::vector< SCH_REFERENCE > &	aRefVector,
		const std::vector< int > &	aRequiredUnits
	)		const

private

Check if all required units are available for a given reference number.

Parameters

aRef	the SCH_REFERENCE object to check against
aRefVector	vector of SCH_REFERENCE objects for a specific reference number
aRequiredUnits	vector of unit numbers needed (negative values ignored)

Returns: true if all required units are available (not conflicting)

Definition at line 170 of file refdes_tracker.cpp.

Referenced by GetNextRefDesForUnits().

◆ Clear()

void REFDES_TRACKER::Clear ( )

Clear all stored reference designators.

Definition at line 453 of file refdes_tracker.cpp.

References clearImpl(), m_mutex, and m_threadSafe.

◆ clearImpl()

void REFDES_TRACKER::clearImpl ( )

private

Clear all internal data structures without locking.

This is used internally to reset the tracker state.

Definition at line 464 of file refdes_tracker.cpp.

References m_allRefDes, and m_prefixData.

Referenced by Clear(), and Deserialize().

◆ ClearUnitsChecker()

void REFDES_TRACKER::ClearUnitsChecker ( )

Clear the external units checker, reverting to default behavior.

Definition at line 566 of file refdes_tracker.cpp.

References m_externalUnitsChecker, m_mutex, and m_threadSafe.

◆ Contains()

bool REFDES_TRACKER::Contains ( const std::string & aRefDes ) const

Check if a reference designator exists in the tracker.

Parameters

aRefDes the reference designator to check

Returns: true if the reference designator exists

Definition at line 77 of file refdes_tracker.cpp.

References containsImpl(), m_mutex, and m_threadSafe.

Referenced by BOOST_AUTO_TEST_CASE(), and TEST_REFDES_TRACKER_UNITS::runTestCase().

◆ containsImpl()

bool REFDES_TRACKER::containsImpl ( const std::string & aRefDes ) const

private

Check if a reference designator exists in the tracker without locking.

Parameters

aRefDes reference designator to check

Returns: true if the reference designator exists

Definition at line 72 of file refdes_tracker.cpp.

References m_allRefDes.

Referenced by Contains(), and GetNextRefDesForUnits().

◆ Deserialize()

bool REFDES_TRACKER::Deserialize ( const std::string & aData )

Deserialize tracker data from string representation.

Parameters

aData the serialized data string

Returns: true if deserialization was successful

Definition at line 395 of file refdes_tracker.cpp.

References clearImpl(), end, insertImpl(), m_mutex, m_threadSafe, splitString(), and unescapeFromSerialization().

Referenced by BOOST_AUTO_TEST_CASE().

◆ escapeForSerialization()

std::string REFDES_TRACKER::escapeForSerialization ( const std::string & aStr ) const

private

Escape special characters for serialization.

Parameters

aStr	string to escape

Returns: escaped string

Definition at line 480 of file refdes_tracker.cpp.

Referenced by Serialize().

◆ findNextAvailable()

int REFDES_TRACKER::findNextAvailable	(	const PREFIX_DATA &	aData,
		int	aMinValue
	)		const

private

Find next available number for a prefix starting from a minimum value.

Parameters

aData	the prefix data
aMinValue	minimum value to start search from

Returns: next available number >= aMinValue

Definition at line 282 of file refdes_tracker.cpp.

References REFDES_TRACKER::PREFIX_DATA::m_baseNext, REFDES_TRACKER::PREFIX_DATA::m_nextCache, REFDES_TRACKER::PREFIX_DATA::m_usedNumbers, and updateBaseNext().

◆ GetNextRefDes()

int REFDES_TRACKER::GetNextRefDes	(	const std::string &	aPrefix,
		int	aMinValue = `1`
	)

Get the next available reference designator for a given prefix and reserve it.

The returned designator is automatically inserted into the tracker.

Parameters

aPrefix	the alphabetic prefix (e.g., "R", "C", "IC")
aMinValue	the minimum numerical value to use (default 1)

Returns: the next available number for the given prefix (now reserved)

◆ GetNextRefDesForUnits()

int REFDES_TRACKER::GetNextRefDesForUnits	(	const SCH_REFERENCE &	aRef,
		const std::map< int, std::vector< SCH_REFERENCE > > &	aRefNumberMap,
		const std::vector< int > &	aRequiredUnits,
		int	aMinValue
	)

Get the next available reference designator number for multi-unit symbols.

Finds the smallest unused reference number for the given prefix, or the smallest number where all required units are available. The returned number is automatically inserted into the tracker as a base reference designator.

Parameters

aRef	the schematic reference to use for prefix and unit filtering
aRefNumberMap	map from reference numbers to vectors of SCH_REFERENCE for currently used references
aRequiredUnits	vector of unit numbers needed (negative values are ignored)
aMinValue	the minimum value to start searching from

Returns: the next available reference number

Definition at line 88 of file refdes_tracker.cpp.

References areUnitsAvailable(), containsImpl(), SCH_REFERENCE::GetRef(), SCH_REFERENCE::GetRefStr(), insertNumber(), m_allRefDes, m_externalUnitsChecker, m_mutex, m_reuseRefDes, and m_threadSafe.

Referenced by BOOST_AUTO_TEST_CASE(), and TEST_REFDES_TRACKER_UNITS::runTestCase().

◆ GetReuseRefDes()

bool REFDES_TRACKER::GetReuseRefDes ( ) const

inline

Definition at line 157 of file refdes_tracker.h.

References m_reuseRefDes.

◆ Insert()

bool REFDES_TRACKER::Insert ( const std::string & aRefDes )

Insert a reference designator into the tracker.

Parameters

aRefDes the reference designator to insert

Returns: true if inserted successfully, false if already exists

Definition at line 33 of file refdes_tracker.cpp.

References insertImpl(), m_mutex, and m_threadSafe.

Referenced by BOOST_AUTO_TEST_CASE(), and TEST_REFDES_TRACKER_UNITS::runTestCase().

◆ insertImpl()

bool REFDES_TRACKER::insertImpl ( const std::string & aRefDes )

private

Internal implementation of Insert without locking.

Parameters

aRefDes reference designator to insert

Returns: true if inserted, false if already exists

Definition at line 43 of file refdes_tracker.cpp.

References insertNumber(), m_allRefDes, and parseRefDes().

Referenced by Deserialize(), and Insert().

◆ insertNumber()

bool REFDES_TRACKER::insertNumber	(	const std::string &	aPrefix,
		int	aNumber
	)

private

Insert a number for a specific prefix, updating internal structures.

Parameters

aPrefix	the prefix
aNumber	the number to insert (0 for prefix-only)

Returns: true if inserted, false if already exists

Definition at line 56 of file refdes_tracker.cpp.

References m_prefixData, REFDES_TRACKER::PREFIX_DATA::m_usedNumbers, and updateCacheOnInsert().

Referenced by GetNextRefDesForUnits(), and insertImpl().

◆ parseRefDes()

std::pair< std::string, int > REFDES_TRACKER::parseRefDes ( const std::string & aRefDes ) const

private

Parse a reference designator into prefix and numerical suffix.

Parameters

aRefDes the reference designator to parse

Returns: pair of (prefix, number) where number is 0 if no numerical suffix

Definition at line 194 of file refdes_tracker.cpp.

Referenced by insertImpl().

◆ Serialize()

std::string REFDES_TRACKER::Serialize ( ) const

Serialize the tracker data to a compact string representation.

Uses range notation for consecutive numbers (e.g., "R1-3,R5-7,R10").

Returns: serialized string representation

Definition at line 310 of file refdes_tracker.cpp.

References end, escapeForSerialization(), m_mutex, m_prefixData, and m_threadSafe.

Referenced by BOOST_AUTO_TEST_CASE().

◆ SetReuseRefDes()

void REFDES_TRACKER::SetReuseRefDes ( bool aReuse )

inline

Definition at line 158 of file refdes_tracker.h.

References m_reuseRefDes.

Referenced by TEST_REFDES_TRACKER_UNITS::setupRefDesTracker(), TEST_ANNOTATION_UNITS_CONFLICTS::setupRefDesTracker(), and TEST_ANNOTATION_UNITS_INTEGRATION::setupRefDesTracker().

◆ SetUnitsChecker()

void REFDES_TRACKER::SetUnitsChecker ( const UNITS_CHECKER_FUNC< SCH_REFERENCE > & aChecker )

Set an external units checker function for SCH_REFERENCE objects.

This allows overriding the default units availability logic without requiring LIB_SYMBOL dependencies.

Parameters

aChecker function to use for checking unit availability

Definition at line 555 of file refdes_tracker.cpp.

References m_externalUnitsChecker, m_mutex, and m_threadSafe.

Referenced by TEST_REFDES_TRACKER_UNITS::setupRefDesTracker(), TEST_ANNOTATION_UNITS_CONFLICTS::setupRefDesTracker(), TEST_ANNOTATION_UNITS_INTEGRATION::setupRefDesTracker(), and TEST_SCH_REFERENCE_LIST_UNITS_FIXTURE::setupRefDesTracker().

◆ Size()

size_t REFDES_TRACKER::Size ( ) const

Get the total count of stored reference designators.

Returns: number of reference designators stored

Definition at line 470 of file refdes_tracker.cpp.

References m_allRefDes, m_mutex, and m_threadSafe.

Referenced by BOOST_AUTO_TEST_CASE().

◆ splitString()

std::vector< std::string > REFDES_TRACKER::splitString	(	const std::string &	aStr,
		char	aDelimiter
	)		const

private

Split string by delimiter, handling escaped characters.

Parameters

aStr	string to split
aDelimiter	delimiter character

Returns: vector of split parts

Definition at line 519 of file refdes_tracker.cpp.

Referenced by Deserialize().

◆ unescapeFromSerialization()

std::string REFDES_TRACKER::unescapeFromSerialization ( const std::string & aStr ) const

private

Unescape special characters from serialization.

Parameters

aStr	escaped string

Returns: unescaped string

Definition at line 494 of file refdes_tracker.cpp.

Referenced by Deserialize().

◆ updateBaseNext()

void REFDES_TRACKER::updateBaseNext ( PREFIX_DATA & aData ) const

private

Definition at line 221 of file refdes_tracker.cpp.

References REFDES_TRACKER::PREFIX_DATA::m_baseNext, REFDES_TRACKER::PREFIX_DATA::m_cacheValid, and REFDES_TRACKER::PREFIX_DATA::m_usedNumbers.

Referenced by findNextAvailable().

◆ updateCacheOnInsert()

void REFDES_TRACKER::updateCacheOnInsert	(	PREFIX_DATA &	aData,
		int	aInsertedNumber
	)		const

private

Update cached next available values when a number is inserted.

Parameters

aData	the prefix data to update
aInsertedNumber	the number that was just inserted

Definition at line 246 of file refdes_tracker.cpp.

References REFDES_TRACKER::PREFIX_DATA::m_baseNext, REFDES_TRACKER::PREFIX_DATA::m_cacheValid, REFDES_TRACKER::PREFIX_DATA::m_nextCache, and REFDES_TRACKER::PREFIX_DATA::m_usedNumbers.

Referenced by insertNumber().

Member Data Documentation

◆ m_allRefDes

std::unordered_set<std::string> REFDES_TRACKER::m_allRefDes

private

Definition at line 179 of file refdes_tracker.h.

Referenced by clearImpl(), containsImpl(), GetNextRefDesForUnits(), insertImpl(), and Size().

◆ m_externalUnitsChecker

UNITS_CHECKER_FUNC<SCH_REFERENCE> REFDES_TRACKER::m_externalUnitsChecker

private

External units checker function (optional)

Definition at line 184 of file refdes_tracker.h.

Referenced by ClearUnitsChecker(), GetNextRefDesForUnits(), and SetUnitsChecker().

◆ m_mutex

std::mutex REFDES_TRACKER::m_mutex

mutableprivate

Mutex for thread safety.

Definition at line 174 of file refdes_tracker.h.

Referenced by Clear(), ClearUnitsChecker(), Contains(), Deserialize(), GetNextRefDesForUnits(), Insert(), Serialize(), SetUnitsChecker(), and Size().

◆ m_prefixData

std::unordered_map<std::string, PREFIX_DATA> REFDES_TRACKER::m_prefixData

private

Map from prefix to its tracking data.

Definition at line 178 of file refdes_tracker.h.

Referenced by clearImpl(), insertNumber(), and Serialize().

◆ m_reuseRefDes

bool REFDES_TRACKER::m_reuseRefDes

private

If true, allows reusing existing reference designators.

Definition at line 181 of file refdes_tracker.h.

Referenced by GetNextRefDesForUnits(), GetReuseRefDes(), and SetReuseRefDes().

◆ m_threadSafe

bool REFDES_TRACKER::m_threadSafe

private

True if thread safety is enabled.

Definition at line 175 of file refdes_tracker.h.

Referenced by Clear(), ClearUnitsChecker(), Contains(), Deserialize(), GetNextRefDesForUnits(), Insert(), Serialize(), SetUnitsChecker(), and Size().

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

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ REFDES_TRACKER()

Member Function Documentation

◆ areUnitsAvailable()

◆ Clear()

◆ clearImpl()

◆ ClearUnitsChecker()

◆ Contains()

◆ containsImpl()

◆ Deserialize()

◆ escapeForSerialization()

◆ findNextAvailable()

◆ GetNextRefDes()

◆ GetNextRefDesForUnits()

◆ GetReuseRefDes()

◆ Insert()

◆ insertImpl()

◆ insertNumber()

◆ parseRefDes()

◆ Serialize()

◆ SetReuseRefDes()

◆ SetUnitsChecker()

◆ Size()

◆ splitString()

◆ unescapeFromSerialization()

◆ updateBaseNext()

◆ updateCacheOnInsert()

Member Data Documentation

◆ m_allRefDes

◆ m_externalUnitsChecker

◆ m_mutex

◆ m_prefixData

◆ m_reuseRefDes

◆ m_threadSafe