KiCad PCB EDA Suite
KIID Class Reference

#include <kiid.h>

Public Member Functions

 KIID ()
 
 KIID (int null)
 
 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 44 of file kiid.h.

Constructor & Destructor Documentation

◆ KIID() [1/4]

KIID::KIID ( )

Definition at line 74 of file kiid.cpp.

75 {
77 
78 #if BOOST_VERSION >= 106700
79  try
80  {
81 #endif
82 
83  if( g_createNilUuids )
84  {
85  m_uuid = nilGenerator();
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( wxT( "A Boost UUID entropy exception was thrown in %s:%s." ),
98  __FILE__, __FUNCTION__ );
99  }
100 #endif
101 }
boost::uuids::uuid m_uuid
Definition: kiid.h:121
static boost::uuids::basic_random_generator< boost::mt19937 > randomGenerator(rng)
timestamp_t m_cached_timestamp
Definition: kiid.h:123
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:41

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

◆ KIID() [2/4]

KIID::KIID ( int  null)

Definition at line 104 of file kiid.cpp.

105 {
106  wxASSERT( null == 0 );
107 }
boost::uuids::uuid m_uuid
Definition: kiid.h:121
timestamp_t m_cached_timestamp
Definition: kiid.h:123
static boost::uuids::nil_generator nilGenerator
Definition: kiid.cpp:55

◆ KIID() [3/4]

KIID::KIID ( const wxString &  aString)

Definition at line 110 of file kiid.cpp.

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

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

◆ KIID() [4/4]

KIID::KIID ( timestamp_t  aTimestamp)

Definition at line 186 of file kiid.cpp.

187 {
188  m_cached_timestamp = aTimestamp;
189 
190  // A legacy-timestamp-based UUID has only the last 4 octets filled in.
191  // Convert them individually to avoid stepping in the little-endian/big-endian
192  // doo-doo.
193  wxString str = AsLegacyTimestampString();
194 
195  for( int i = 0; i < 4; ++i )
196  {
197  wxString octet = str.substr( i * 2, 2 );
198  m_uuid.data[i + 12] = strtol( octet.data(), nullptr, 16 );
199  }
200 }
boost::uuids::uuid m_uuid
Definition: kiid.h:121
timestamp_t m_cached_timestamp
Definition: kiid.h:123
wxString AsLegacyTimestampString() const
Definition: kiid.cpp:242

References AsLegacyTimestampString(), m_cached_timestamp, and m_uuid.

Member Function Documentation

◆ AsLegacyTimestamp()

timestamp_t KIID::AsLegacyTimestamp ( ) const

Definition at line 209 of file kiid.cpp.

210 {
211  return m_cached_timestamp;
212 }
timestamp_t m_cached_timestamp
Definition: kiid.h:123

References m_cached_timestamp.

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

◆ AsLegacyTimestampString()

wxString KIID::AsLegacyTimestampString ( ) const

Definition at line 242 of file kiid.cpp.

243 {
244  return wxString::Format( "%8.8lX", (unsigned long) AsLegacyTimestamp() );
245 }
timestamp_t AsLegacyTimestamp() const
Definition: kiid.cpp:209
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 229 of file kiid.cpp.

230 {
231  m_uuid = aUUID.m_uuid;
233 }
boost::uuids::uuid m_uuid
Definition: kiid.h:121
timestamp_t m_cached_timestamp
Definition: kiid.h:123

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 248 of file kiid.cpp.

249 {
250  if( !IsLegacyTimestamp() )
251  return;
252 
253  m_cached_timestamp = 0;
255 }
boost::uuids::uuid m_uuid
Definition: kiid.h:121
static boost::uuids::basic_random_generator< boost::mt19937 > randomGenerator(rng)
bool IsLegacyTimestamp() const
Definition: kiid.cpp:203
timestamp_t m_cached_timestamp
Definition: kiid.h:123

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 273 of file kiid.cpp.

274 {
275  g_createNilUuids = aNil;
276 }
static bool g_createNilUuids
Definition: kiid.cpp:63

References g_createNilUuids.

Referenced by FOOTPRINT_ASYNC_LOADER::Abort(), SYMBOL_TREE_MODEL_ADAPTER::AddLibraries(), and FOOTPRINT_ASYNC_LOADER::Start().

◆ Hash()

size_t KIID::Hash ( ) const

Definition at line 215 of file kiid.cpp.

216 {
217  size_t hash = 0;
218 
219  // Note: this is NOT little-endian/big-endian safe, but as long as it's just used
220  // at runtime it won't matter.
221 
222  for( int i = 0; i < 4; ++i )
223  boost::hash_combine( hash, reinterpret_cast<const uint32_t*>( m_uuid.data )[i] );
224 
225  return hash;
226 }
boost::uuids::uuid m_uuid
Definition: kiid.h:121
static void hash_combine(std::size_t &seed)
This is a dummy function to take the final case of hash_combine below.
Definition: hash_eda.h:67

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 258 of file kiid.cpp.

259 {
260  // This obviously destroys uniform distribution, but it can be useful when a
261  // deterministic replacement for a duplicate ID is required.
262 
263  for( int i = 15; i >= 0; --i )
264  {
265  m_uuid.data[i]++;
266 
267  if( m_uuid.data[i] != 0 )
268  break;
269  }
270 }
boost::uuids::uuid m_uuid
Definition: kiid.h:121

References m_uuid.

◆ IsLegacyTimestamp()

bool KIID::IsLegacyTimestamp ( ) const

Definition at line 203 of file kiid.cpp.

204 {
205  return !m_uuid.data[8] && !m_uuid.data[9] && !m_uuid.data[10] && !m_uuid.data[11];
206 }
boost::uuids::uuid m_uuid
Definition: kiid.h:121

References m_uuid.

Referenced by ConvertTimestampToUuid(), and KIID().

◆ 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  }
boost::uuids::uuid m_uuid
Definition: kiid.h:121

References m_uuid.

◆ 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  }
boost::uuids::uuid m_uuid
Definition: kiid.h:121

References m_uuid.

◆ operator==()

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

Definition at line 100 of file kiid.h.

101  {
102  return m_uuid == rhs.m_uuid;
103  }
boost::uuids::uuid m_uuid
Definition: kiid.h:121

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  }
boost::uuids::uuid m_uuid
Definition: kiid.h:121

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 279 of file kiid.cpp.

280 {
281  rng.seed( aSeed );
282 }
static boost::mt19937 rng(seeder)

References 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 158 of file kiid.cpp.

159 {
160  static wxString niluuidStr = niluuid.AsString();
161 
162  if( aCandidate.Length() != niluuidStr.Length() )
163  return false;
164 
165  for( wxChar c : aCandidate )
166  {
167  if( c >= '0' && c <= '9' )
168  continue;
169 
170  if( c >= 'a' && c <= 'f' )
171  continue;
172 
173  if( c >= 'A' && c <= 'F' )
174  continue;
175 
176  if( c == '-' )
177  continue;
178 
179  return false;
180  }
181 
182  return true;
183 }
KIID niluuid(0)
wxString AsString() const
Definition: kiid.cpp:236

References AsString(), and niluuid.

Referenced by insideArea().

Member Data Documentation

◆ m_cached_timestamp

timestamp_t KIID::m_cached_timestamp
private

Definition at line 123 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: