KiCad PCB EDA Suite
KIID Class Reference

#include <kiid.h>

Public Member Functions

 KIID ()
 
 KIID (int null)
 
 KIID (const std::string &aString)
 
 KIID (const char *aString)
 
 KIID (const wxString &aString)
 
 KIID (timestamp_t aTimestamp)
 
void Clone (const KIID &aUUID)
 
size_t Hash () const
 
bool IsLegacyTimestamp () const
 
timestamp_t AsLegacyTimestamp () const
 
wxString AsString () const
 
wxString AsLegacyTimestampString () const
 
void ConvertTimestampToUuid ()
 Change an existing time stamp based UUID into a true UUID. More...
 
void Increment ()
 Generates a deterministic replacement for a given ID. More...
 
bool operator== (KIID const &rhs) const
 
bool operator!= (KIID const &rhs) const
 
bool operator< (KIID const &rhs) const
 
bool operator> (KIID const &rhs) const
 

Static Public Member Functions

static bool SniffTest (const wxString &aCandidate)
 Returns true if a string has the correct formatting to be a KIID. More...
 
static void CreateNilUuids (bool aNil=true)
 A performance optimization which disables/enables the generation of pseudo-random UUIDs. More...
 
static void SeedGenerator (unsigned int aSeed)
 Re-initialize the UUID generator with a given seed (for testing or QA purposes) More...
 

Private Attributes

boost::uuids::uuid m_uuid
 
timestamp_t m_cached_timestamp
 

Detailed Description

Definition at line 47 of file kiid.h.

Constructor & Destructor Documentation

◆ KIID() [1/6]

KIID::KIID ( )

Definition at line 74 of file kiid.cpp.

75{
77
78#if BOOST_VERSION >= 106700
79 try
80 {
81#endif
82
84 {
86 }
87 else
88 {
89 std::lock_guard<std::mutex> lock( rng_mutex );
91 }
92
93#if BOOST_VERSION >= 106700
94 }
95 catch( const boost::uuids::entropy_error& )
96 {
97 wxLogFatalError( "A Boost UUID entropy exception was thrown in %s:%s.",
98 __FILE__, __FUNCTION__ );
99 }
100#endif
101}
timestamp_t m_cached_timestamp
Definition: kiid.h:128
boost::uuids::uuid m_uuid
Definition: kiid.h:126
static boost::uuids::nil_generator nilGenerator
Definition: kiid.cpp:55
static bool g_createNilUuids
Definition: kiid.cpp:63
static std::mutex rng_mutex
Definition: kiid.cpp:44
static boost::uuids::basic_random_generator< boost::mt19937 > randomGenerator
Definition: kiid.cpp:51

References g_createNilUuids, m_cached_timestamp, m_uuid, nilGenerator, randomGenerator, and rng_mutex.

◆ KIID() [2/6]

KIID::KIID ( int  null)

Definition at line 104 of file kiid.cpp.

104 :
105 m_uuid( nilGenerator() ),
107{
108 wxASSERT( null == 0 );
109}

◆ KIID() [3/6]

KIID::KIID ( const std::string &  aString)

Definition at line 112 of file kiid.cpp.

112 :
113 m_uuid(),
115{
116 if( aString.length() == 8
117 && std::all_of( aString.begin(), aString.end(),
118 []( unsigned char c )
119 {
120 return std::isxdigit( c );
121 } ) )
122 {
123 // A legacy-timestamp-based UUID has only the last 4 octets filled in.
124 // Convert them individually to avoid stepping in the little-endian/big-endian
125 // doo-doo.
126 for( int i = 0; i < 4; ++i )
127 {
128 std::string octet = aString.substr( i * 2, 2 );
129 m_uuid.data[i + 12] = strtol( octet.data(), nullptr, 16 );
130 }
131
132 m_cached_timestamp = strtol( aString.c_str(), nullptr, 16 );
133 }
134 else
135 {
136 try
137 {
138 m_uuid = stringGenerator( aString );
139
140 if( IsLegacyTimestamp() )
141 m_cached_timestamp = strtol( aString.substr( 28 ).c_str(), nullptr, 16 );
142 }
143 catch( ... )
144 {
145 // Failed to parse string representation; best we can do is assign a new
146 // random one.
147#if BOOST_VERSION >= 106700
148 try
149 {
150#endif
151
153
154#if BOOST_VERSION >= 106700
155 }
156 catch( const boost::uuids::entropy_error& )
157 {
158 wxLogFatalError( "A Boost UUID entropy exception was thrown in %s:%s.",
159 __FILE__, __FUNCTION__ );
160 }
161#endif
162 }
163 }
164}
bool IsLegacyTimestamp() const
Definition: kiid.cpp:224
static boost::uuids::string_generator stringGenerator
Definition: kiid.cpp:54

References IsLegacyTimestamp(), m_cached_timestamp, m_uuid, randomGenerator, and stringGenerator.

◆ KIID() [4/6]

KIID::KIID ( const char *  aString)

Definition at line 167 of file kiid.cpp.

167 :
168 KIID( std::string( aString ) )
169{
170}
KIID()
Definition: kiid.cpp:74

◆ KIID() [5/6]

KIID::KIID ( const wxString &  aString)

Definition at line 173 of file kiid.cpp.

173 :
174 KIID( std::string( aString.ToUTF8() ) )
175{
176}

◆ KIID() [6/6]

KIID::KIID ( timestamp_t  aTimestamp)

Definition at line 207 of file kiid.cpp.

208{
209 m_cached_timestamp = aTimestamp;
210
211 // A legacy-timestamp-based UUID has only the last 4 octets filled in.
212 // Convert them individually to avoid stepping in the little-endian/big-endian
213 // doo-doo.
214 wxString str = AsLegacyTimestampString();
215
216 for( int i = 0; i < 4; ++i )
217 {
218 wxString octet = str.substr( i * 2, 2 );
219 m_uuid.data[i + 12] = strtol( octet.data(), nullptr, 16 );
220 }
221}
wxString AsLegacyTimestampString() const
Definition: kiid.cpp:263

References AsLegacyTimestampString(), m_cached_timestamp, and m_uuid.

Member Function Documentation

◆ AsLegacyTimestamp()

timestamp_t KIID::AsLegacyTimestamp ( ) const

Definition at line 230 of file kiid.cpp.

231{
232 return m_cached_timestamp;
233}

References m_cached_timestamp.

Referenced by AsLegacyTimestampString(), SCH_LEGACY_PLUGIN::saveSheet(), and SCH_LEGACY_PLUGIN::saveSymbol().

◆ AsLegacyTimestampString()

wxString KIID::AsLegacyTimestampString ( ) const

Definition at line 263 of file kiid.cpp.

264{
265 return wxString::Format( "%8.8lX", (unsigned long) AsLegacyTimestamp() );
266}
timestamp_t AsLegacyTimestamp() const
Definition: kiid.cpp:230
void Format(OUTPUTFORMATTER *out, int aNestLevel, int aCtl, const CPTREE &aTree)
Output a PTREE into s-expression format via an OUTPUTFORMATTER derivative.
Definition: ptree.cpp:200

References AsLegacyTimestamp(), and Format().

Referenced by KIID(), and SCH_LEGACY_PLUGIN::saveSymbol().

◆ AsString()

◆ Clone()

void KIID::Clone ( const KIID aUUID)

Definition at line 250 of file kiid.cpp.

251{
252 m_uuid = aUUID.m_uuid;
254}

References m_cached_timestamp, and m_uuid.

◆ ConvertTimestampToUuid()

void KIID::ConvertTimestampToUuid ( )

Change an existing time stamp based UUID into a true UUID.

If this is not a time stamp based UUID, then no change is made.

Definition at line 269 of file kiid.cpp.

270{
271 if( !IsLegacyTimestamp() )
272 return;
273
276}

References IsLegacyTimestamp(), m_cached_timestamp, m_uuid, and randomGenerator.

◆ CreateNilUuids()

void KIID::CreateNilUuids ( bool  aNil = true)
static

A performance optimization which disables/enables the generation of pseudo-random UUIDs.

NB: uses a global. Not thread safe!

Definition at line 294 of file kiid.cpp.

295{
296 g_createNilUuids = aNil;
297}

References g_createNilUuids.

Referenced by SYMBOL_TREE_MODEL_ADAPTER::AddLibraries(), KIID_NIL_SET_RESET::KIID_NIL_SET_RESET(), SYMBOL_VIEWER_FRAME::loadAllLibraries(), and KIID_NIL_SET_RESET::~KIID_NIL_SET_RESET().

◆ Hash()

size_t KIID::Hash ( ) const

Definition at line 236 of file kiid.cpp.

237{
238 size_t hash = 0;
239
240 // Note: this is NOT little-endian/big-endian safe, but as long as it's just used
241 // at runtime it won't matter.
242
243 for( int i = 0; i < 4; ++i )
244 boost::hash_combine( hash, reinterpret_cast<const uint32_t*>( m_uuid.data )[i] );
245
246 return hash;
247}
static void hash_combine(std::size_t &seed)
This is a dummy function to take the final case of hash_combine below.
Definition: hash.h:34

References hash_combine(), and m_uuid.

Referenced by BOOST_AUTO_TEST_CASE().

◆ Increment()

void KIID::Increment ( )

Generates a deterministic replacement for a given ID.

NB: destroys uniform distribution! But it's the only thing we have when a deterministic replacement for a duplicate ID is required.

Definition at line 279 of file kiid.cpp.

280{
281 // This obviously destroys uniform distribution, but it can be useful when a
282 // deterministic replacement for a duplicate ID is required.
283
284 for( int i = 15; i >= 0; --i )
285 {
286 m_uuid.data[i]++;
287
288 if( m_uuid.data[i] != 0 )
289 break;
290 }
291}

References m_uuid.

◆ IsLegacyTimestamp()

bool KIID::IsLegacyTimestamp ( ) const

Definition at line 224 of file kiid.cpp.

225{
226 return !m_uuid.data[8] && !m_uuid.data[9] && !m_uuid.data[10] && !m_uuid.data[11];
227}

References m_uuid.

Referenced by ConvertTimestampToUuid(), and KIID().

◆ operator!=()

bool KIID::operator!= ( KIID const &  rhs) const
inline

Definition at line 110 of file kiid.h.

111 {
112 return m_uuid != rhs.m_uuid;
113 }

References m_uuid.

◆ operator<()

bool KIID::operator< ( KIID const &  rhs) const
inline

Definition at line 115 of file kiid.h.

116 {
117 return m_uuid < rhs.m_uuid;
118 }

References m_uuid.

◆ operator==()

bool KIID::operator== ( KIID const &  rhs) const
inline

Definition at line 105 of file kiid.h.

106 {
107 return m_uuid == rhs.m_uuid;
108 }

References m_uuid.

◆ operator>()

bool KIID::operator> ( KIID const &  rhs) const
inline

Definition at line 120 of file kiid.h.

121 {
122 return m_uuid > rhs.m_uuid;
123 }

References m_uuid.

◆ SeedGenerator()

void KIID::SeedGenerator ( unsigned int  aSeed)
static

Re-initialize the UUID generator with a given seed (for testing or QA purposes)

WARNING: Do not call this function from within KiCad or via a Python action plugin. It is only to be used inside QA tests or in external Python scripts. Resetting the UUID generator in the middle of a KiCad GUI run will potentially have harmful effects on file integrity.

Parameters
aSeedis a seed to pass to the boost::mt19937 pseudo-random number generator

Definition at line 300 of file kiid.cpp.

301{
302 rng.seed( aSeed );
303 randomGenerator = boost::uuids::basic_random_generator<boost::mt19937>( rng );
304}
static boost::mt19937 rng
Definition: kiid.cpp:50

References randomGenerator, and rng.

Referenced by BOOST_AUTO_TEST_CASE().

◆ SniffTest()

bool KIID::SniffTest ( const wxString &  aCandidate)
static

Returns true if a string has the correct formatting to be a KIID.

Definition at line 179 of file kiid.cpp.

180{
181 static wxString niluuidStr = niluuid.AsString();
182
183 if( aCandidate.Length() != niluuidStr.Length() )
184 return false;
185
186 for( wxChar c : aCandidate )
187 {
188 if( c >= '0' && c <= '9' )
189 continue;
190
191 if( c >= 'a' && c <= 'f' )
192 continue;
193
194 if( c >= 'A' && c <= 'F' )
195 continue;
196
197 if( c == '-' )
198 continue;
199
200 return false;
201 }
202
203 return true;
204}
wxString AsString() const
Definition: kiid.cpp:257
KIID niluuid(0)

References AsString(), and niluuid.

Referenced by searchAreas().

Member Data Documentation

◆ m_cached_timestamp

timestamp_t KIID::m_cached_timestamp
private

Definition at line 128 of file kiid.h.

Referenced by AsLegacyTimestamp(), Clone(), ConvertTimestampToUuid(), and KIID().

◆ m_uuid

boost::uuids::uuid KIID::m_uuid
private

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