KiCad PCB EDA Suite
LIB_ID Class Reference

Class LIB_ID. More...

#include <lib_id.h>

Public Member Functions

 LIB_ID ()
 
 LIB_ID (const std::string &aId) throw ( PARSE_ERROR )
 Constructor LIB_ID. More...
 
 LIB_ID (const wxString &aId) throw ( PARSE_ERROR )
 
 LIB_ID (const wxString &aLibName, const wxString &aLibItemName, const wxString &aRevision=wxEmptyString)
 This LIB_ID ctor is a special version which ignores the parsing due to symbol names allowing '/' as a valid character. More...
 
int Parse (const UTF8 &aId)
 Function Parse. More...
 
const UTF8GetLibNickname () const
 Function GetLibNickname. More...
 
int SetLibNickname (const UTF8 &aNickname)
 Function SetLibNickname. More...
 
const UTF8GetLibItemName () const
 Function GetLibItemName. More...
 
int SetLibItemName (const UTF8 &aLibItemName, bool aTestForRev=true)
 Function SetLibItemName. More...
 
int SetRevision (const UTF8 &aRevision)
 
const UTF8GetRevision () const
 
UTF8 GetLibItemNameAndRev () const
 
UTF8 Format () const
 Function Format. More...
 
bool IsValid () const
 Function IsValid. More...
 
bool IsLegacy () const
 Function IsLegacy. More...
 
void clear ()
 Function clear. More...
 
bool empty () const
 Function empty. More...
 
int compare (const LIB_ID &aLIB_ID) const
 Function Compare. More...
 
bool operator< (const LIB_ID &aLibId) const
 
bool operator> (const LIB_ID &aLibId) const
 
bool operator== (const LIB_ID &aLibId) const
 
bool operator!= (const LIB_ID &aLibId) const
 

Static Public Member Functions

static UTF8 Format (const UTF8 &aLibNickname, const UTF8 &aLibItemName, const UTF8 &aRevision="") throw ( PARSE_ERROR )
 Function Format. More...
 

Protected Attributes

UTF8 nickname
 The nickname of the library or empty. More...
 
UTF8 item_name
 The name of the entry in the logical library. More...
 
UTF8 revision
 The revision of the entry. More...
 

Detailed Description

Class LIB_ID.

is a logical library item identifier and consists of various portions much like a URI. It consists of of triad of the library nickname, the name of the item in the library, and an optional revision of the item. This is a generic library identifier that can be used for any type of library that contains multiple named items such as footprint or symbol libraries.

Example LIB_ID string: "smt:R_0805/rev0".

  • "smt" is the logical library name used to look up library information saved in the LIB_TABLE.
  • "R" is the name of the item within the library.
  • "rev0" is the revision, which is optional. If missing then its / delimiter should also not be present. A revision must begin with "rev" and be followed by at least one or more decimal digits.
Author
Dick Hollenbeck

Definition at line 56 of file lib_id.h.

Constructor & Destructor Documentation

LIB_ID::LIB_ID ( )
inline

Definition at line 60 of file lib_id.h.

60 {}
LIB_ID::LIB_ID ( const std::string &  aId)
throw (PARSE_ERROR
)

Constructor LIB_ID.

takes aId string and parses it. A typical LIB_ID string consists of a library nickname followed by a library item name. e.g.: "smt:R_0805", or e.g.: "mylib:R_0805", or e.g.: "ttl:7400"

Parameters
aIdis a string to be parsed into the LIB_ID object.

Definition at line 178 of file lib_id.cpp.

References THROW_PARSE_ERROR.

179 {
180  int offset = Parse( aId );
181 
182  if( offset != -1 )
183  {
184  THROW_PARSE_ERROR( _( "Illegal character found in LIB_ID string" ),
185  wxString::FromUTF8( aId.c_str() ),
186  aId.c_str(),
187  0,
188  offset );
189  }
190 }
int Parse(const UTF8 &aId)
Function Parse.
Definition: lib_id.cpp:122
#define THROW_PARSE_ERROR(aProblem, aSource, aInputLine, aLineNumber, aByteIndex)
Definition: ki_exception.h:133
LIB_ID::LIB_ID ( const wxString &  aId)
throw (PARSE_ERROR
)

Definition at line 193 of file lib_id.cpp.

References THROW_PARSE_ERROR, and TO_UTF8.

194 {
195  UTF8 id = TO_UTF8( aId );
196 
197  int offset = Parse( id );
198 
199  if( offset != -1 )
200  {
201  THROW_PARSE_ERROR( _( "Illegal character found in LIB_ID string" ),
202  aId,
203  id.c_str(),
204  0,
205  offset );
206  }
207 }
Class UTF8 is an 8 bit std::string that is assuredly encoded in UTF8, and supplies special conversion...
Definition: utf8.h:53
int Parse(const UTF8 &aId)
Function Parse.
Definition: lib_id.cpp:122
#define TO_UTF8(wxstring)
Macro TO_UTF8 converts a wxString to a UTF8 encoded C string for all wxWidgets build modes...
Definition: macros.h:47
#define THROW_PARSE_ERROR(aProblem, aSource, aInputLine, aLineNumber, aByteIndex)
Definition: ki_exception.h:133
LIB_ID::LIB_ID ( const wxString &  aLibName,
const wxString &  aLibItemName,
const wxString &  aRevision = wxEmptyString 
)

This LIB_ID ctor is a special version which ignores the parsing due to symbol names allowing '/' as a valid character.

This was causing the symbol names to be truncated at the first occurrence of '/' in the symbol name.

Parameters
aLibNameis the library nickname used to look up the library item in the LIB_TABLE.
aLibItemNameis the name of the library item which is not parsed by the standard LIB_ID::Parse() function.
aRevisionis the revision of the library item.

Definition at line 210 of file lib_id.cpp.

211  :
212  nickname( TO_UTF8( aLibName ) ),
213  item_name( TO_UTF8( aLibItemName ) ),
214  revision( TO_UTF8( aRevision ) )
215 {
216 }
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
#define TO_UTF8(wxstring)
Macro TO_UTF8 converts a wxString to a UTF8 encoded C string for all wxWidgets build modes...
Definition: macros.h:47
UTF8 item_name
The name of the entry in the logical library.
Definition: lib_id.h:224
UTF8 nickname
The nickname of the library or empty.
Definition: lib_id.h:223

Member Function Documentation

void LIB_ID::clear ( )

Function clear.

clears the contents of the library nickname, library entry name, and revision strings.

Definition at line 114 of file lib_id.cpp.

References item_name, nickname, and revision.

Referenced by SCH_COMPONENT::Load(), and Parse().

115 {
116  nickname.clear();
117  item_name.clear();
118  revision.clear();
119 }
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
UTF8 item_name
The name of the entry in the logical library.
Definition: lib_id.h:224
UTF8 nickname
The nickname of the library or empty.
Definition: lib_id.h:223
int LIB_ID::compare ( const LIB_ID aLIB_ID) const

Function Compare.

compares the contents of LIB_ID objects by performing a std::string comparison of the library nickname, library entry name, and revision strings respectively.

Parameters
aLibIdis the LIB_ID to compare against.
Returns
-1 if less than aLibId, 1 if greater than aLibId, and 0 if equal to aLibId.

Definition at line 343 of file lib_id.cpp.

References item_name, nickname, and revision.

Referenced by operator<(), operator==(), and operator>().

344 {
345  // Don't bother comparing the same object.
346  if( this == &aLibId )
347  return 0;
348 
349  int retv = nickname.compare( aLibId.nickname );
350 
351  if( retv != 0 )
352  return retv;
353 
354  retv = item_name.compare( aLibId.item_name );
355 
356  if( retv != 0 )
357  return retv;
358 
359  return revision.compare( aLibId.revision );
360 }
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
UTF8 item_name
The name of the entry in the logical library.
Definition: lib_id.h:224
UTF8 nickname
The nickname of the library or empty.
Definition: lib_id.h:223
bool LIB_ID::empty ( ) const
inline

Function empty.

Returns
a boolean true value if the LIB_ID is empty. Otherwise return false.

Definition at line 199 of file lib_id.h.

References item_name, nickname, and revision.

Referenced by CVPCB_MAINFRAME::AutomaticFootprintMatching(), CMP_READER::Load(), PCB_EDIT_FRAME::LoadFootprints(), CVPCB_MAINFRAME::ReadNetListAndLinkFiles(), BOARD_NETLIST_UPDATER::replaceComponent(), BOARD::ReplaceNetlist(), COMPONENT::SetFPID(), CVPCB_MAINFRAME::SetNewPkg(), CVPCB_MAINFRAME::ToFirstNA(), and CVPCB_MAINFRAME::ToPreviousNA().

199 { return nickname.empty() && item_name.empty() && revision.empty(); }
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
UTF8 item_name
The name of the entry in the logical library.
Definition: lib_id.h:224
UTF8 nickname
The nickname of the library or empty.
Definition: lib_id.h:223
UTF8 LIB_ID::Format ( ) const

Function Format.

Returns
the fully formatted text of the LIB_ID.

Definition at line 263 of file lib_id.cpp.

References item_name, nickname, and revision.

Referenced by BOARD_NETLIST_UPDATER::addNewComponent(), CVPCB_MAINFRAME::BuildCmpListBox(), DIALOG_EXCHANGE_MODULE::change_1_Module(), DIALOG_EXCHANGE_MODULE::changeSameFootprints(), DIALOG_EDIT_COMPONENT_IN_SCHEMATIC::copyOptionsToPanel(), CreateDevicesSection(), DIALOG_SCH_EDIT_ONE_FIELD::DIALOG_SCH_EDIT_ONE_FIELD(), FOOTPRINT_VIEWER_FRAME::ExportSelectedFootprint(), COMPONENT::Format(), MODULE::GetMsgPanelInfo(), DIALOG_EXCHANGE_MODULE::init(), PCB_BASE_FRAME::LoadFootprint(), PCB_EDIT_FRAME::LoadFootprints(), PCB_BASE_FRAME::LoadModuleFromLibrary(), DSN::SPECCTRA_DB::makeIMAGE(), CVPCB_MAINFRAME::ReadNetListAndLinkFiles(), RecreateCmpFile(), CVPCB_MAINFRAME::refreshAfterComponentSearch(), BOARD_NETLIST_UPDATER::replaceComponent(), BOARD::ReplaceNetlist(), CVPCB_MAINFRAME::SetNewPkg(), BOARD_NETLIST_UPDATER::testConnectivity(), and BOARD_NETLIST_UPDATER::UpdateNetlist().

264 {
265  UTF8 ret;
266 
267  if( nickname.size() )
268  {
269  ret += nickname;
270  ret += ':';
271  }
272 
273  ret += item_name;
274 
275  if( revision.size() )
276  {
277  ret += '/';
278  ret += revision;
279  }
280 
281  return ret;
282 }
Class UTF8 is an 8 bit std::string that is assuredly encoded in UTF8, and supplies special conversion...
Definition: utf8.h:53
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
UTF8 item_name
The name of the entry in the logical library.
Definition: lib_id.h:224
UTF8 nickname
The nickname of the library or empty.
Definition: lib_id.h:223
UTF8 LIB_ID::Format ( const UTF8 aLibNickname,
const UTF8 aLibItemName,
const UTF8 aRevision = "" 
)
throw (PARSE_ERROR
)
static

Function Format.

Returns
a string in the proper format as an LIB_ID for a combination of aLibNickname, aLibItemName, and aRevision.
Exceptions
PARSE_ERRORif any of the pieces are illegal.

Definition at line 299 of file lib_id.cpp.

References okLogical(), okRevision(), and THROW_PARSE_ERROR.

301 {
302  UTF8 ret;
303  int offset;
304 
305  if( aLogicalLib.size() )
306  {
307  offset = okLogical( aLogicalLib );
308 
309  if( offset != -1 )
310  {
311  THROW_PARSE_ERROR( _( "Illegal character found in logical library name" ),
312  wxString::FromUTF8( aLogicalLib.c_str() ),
313  aLogicalLib.c_str(), 0, offset );
314  }
315 
316  ret += aLogicalLib;
317  ret += ':';
318  }
319 
320  ret += aLibItemName; // TODO: Add validity test.
321 
322  if( aRevision.size() )
323  {
324  offset = okRevision( aRevision );
325 
326  if( offset != -1 )
327  {
328  THROW_PARSE_ERROR( _( "Illegal character found in revision" ),
329  wxString::FromUTF8( aRevision.c_str() ),
330  aRevision.c_str(),
331  0,
332  offset );
333  }
334 
335  ret += '/';
336  ret += aRevision;
337  }
338 
339  return ret;
340 }
Class UTF8 is an 8 bit std::string that is assuredly encoded in UTF8, and supplies special conversion...
Definition: utf8.h:53
static int okLogical(const std::string &aField)
Definition: lib_id.cpp:86
static int okRevision(const std::string &aField)
Definition: lib_id.cpp:94
#define THROW_PARSE_ERROR(aProblem, aSource, aInputLine, aLineNumber, aByteIndex)
Definition: ki_exception.h:133
const UTF8& LIB_ID::GetLibItemName ( ) const
inline
UTF8 LIB_ID::GetLibItemNameAndRev ( ) const

Definition at line 285 of file lib_id.cpp.

References revision.

286 {
287  UTF8 ret;
288 
289  if( revision.size() )
290  {
291  ret += '/';
292  ret += revision;
293  }
294 
295  return ret;
296 }
Class UTF8 is an 8 bit std::string that is assuredly encoded in UTF8, and supplies special conversion...
Definition: utf8.h:53
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
const UTF8& LIB_ID::GetLibNickname ( ) const
inline
const UTF8& LIB_ID::GetRevision ( ) const
inline

Definition at line 144 of file lib_id.h.

References revision.

144 { return revision; }
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
bool LIB_ID::IsLegacy ( ) const
inline

Function IsLegacy.

Returns
true if the LIB_ID only has the item_name name defined.

Definition at line 185 of file lib_id.h.

References item_name, nickname, and revision.

Referenced by CVPCB_MAINFRAME::ReadNetListAndLinkFiles().

185 { return nickname.empty() && !item_name.empty() && revision.empty(); }
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
UTF8 item_name
The name of the entry in the logical library.
Definition: lib_id.h:224
UTF8 nickname
The nickname of the library or empty.
Definition: lib_id.h:223
bool LIB_ID::IsValid ( ) const
inline

Function IsValid.

Returns
true is the LIB_ID is valid.

A valid LIB_ID must have both the library nickname and the library item name defined. The revision field is optional.

Note
A return value of true does not indicated that the LIB_ID is a valid LIB_TABLE entry.

Definition at line 178 of file lib_id.h.

References item_name, and nickname.

Referenced by PCB_EDIT_FRAME::LoadFootprints().

178 { return !nickname.empty() && !item_name.empty(); }
UTF8 item_name
The name of the entry in the logical library.
Definition: lib_id.h:224
UTF8 nickname
The nickname of the library or empty.
Definition: lib_id.h:223
bool LIB_ID::operator!= ( const LIB_ID aLibId) const
inline

Definition at line 216 of file lib_id.h.

216 { return !(*this == aLibId); }
bool LIB_ID::operator< ( const LIB_ID aLibId) const
inline

Definition at line 213 of file lib_id.h.

References compare().

213 { return this->compare( aLibId ) < 0; }
int compare(const LIB_ID &aLIB_ID) const
Function Compare.
Definition: lib_id.cpp:343
bool LIB_ID::operator== ( const LIB_ID aLibId) const
inline

Definition at line 215 of file lib_id.h.

References compare().

215 { return this->compare( aLibId ) == 0; }
int compare(const LIB_ID &aLIB_ID) const
Function Compare.
Definition: lib_id.cpp:343
bool LIB_ID::operator> ( const LIB_ID aLibId) const
inline

Definition at line 214 of file lib_id.h.

References compare().

214 { return this->compare( aLibId ) > 0; }
int compare(const LIB_ID &aLIB_ID) const
Function Compare.
Definition: lib_id.cpp:343
int LIB_ID::Parse ( const UTF8 aId)

Function Parse.

[re-]stuffs this LIB_ID with the information from aId.

Parameters
aIdis the string to populate the LIB_ID object.
Returns
int - minus 1 (i.e. -1) means success, >= 0 indicates the character offset into aId at which an error was detected.

Definition at line 122 of file lib_id.cpp.

References clear(), EndsWithRev(), ReplaceIllegalFileNameChars(), revision, SetLibItemName(), SetLibNickname(), and UTF8::substr().

Referenced by DISPLAY_FOOTPRINTS_FRAME::Get_Module(), FOOTPRINT_LIST::GetModuleInfo(), CMP_READER::Load(), PCB_BASE_FRAME::LoadModuleFromLibrary(), KICAD_NETLIST_PARSER::parseComponent(), PCB_PARSER::parseMODULE_unchecked(), and CVPCB_MAINFRAME::SetNewPkg().

123 {
124  clear();
125 
126  const char* buffer = aId.c_str();
127  const char* rev = EndsWithRev( buffer, buffer+aId.length(), '/' );
128  size_t revNdx;
129  size_t partNdx;
130  int offset;
131 
132  //=====<revision>=========================================
133  // in a LIB_ID like discret:R3/rev4
134  if( rev )
135  {
136  revNdx = rev - buffer;
137 
138  // no need to check revision, EndsWithRev did that.
139  revision = aId.substr( revNdx );
140  --revNdx; // back up to omit the '/' which precedes the rev
141  }
142  else
143  {
144  revNdx = aId.size();
145  }
146 
147  //=====<nickname>==========================================
148  if( ( partNdx = aId.find( ':' ) ) != aId.npos )
149  {
150  offset = SetLibNickname( aId.substr( 0, partNdx ) );
151 
152  if( offset > -1 )
153  {
154  return offset;
155  }
156 
157  ++partNdx; // skip ':'
158  }
159  else
160  {
161  partNdx = 0;
162  }
163 
164  //=====<item name>====================================
165  if( partNdx >= revNdx )
166  return partNdx; // Error: no library item name.
167 
168  // Be sure the item name is valid.
169  // Some chars can be found in legacy files converted files from an other EDA tools.
170  std::string fpname = aId.substr( partNdx, revNdx-partNdx );
171  ReplaceIllegalFileNameChars( &fpname, '_' );
172  SetLibItemName( fpname );
173 
174  return -1;
175 }
const char * EndsWithRev(const char *start, const char *tail, char separator)
Definition: lib_id.cpp:41
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
bool ReplaceIllegalFileNameChars(std::string *aName, int aReplaceChar)
Function ReplaceIllegalFileNameChars checks aName for illegal file name characters.
Definition: string.cpp:483
UTF8 substr(size_t pos=0, size_t len=npos) const
Definition: utf8.h:104
void clear()
Function clear.
Definition: lib_id.cpp:114
int SetLibItemName(const UTF8 &aLibItemName, bool aTestForRev=true)
Function SetLibItemName.
Definition: lib_id.cpp:232
int SetLibNickname(const UTF8 &aNickname)
Function SetLibNickname.
Definition: lib_id.cpp:219
int LIB_ID::SetLibItemName ( const UTF8 aLibItemName,
bool  aTestForRev = true 
)

Function SetLibItemName.

overrides the library item name portion of the LIB_ID to aLibItemName

Returns
int - minus 1 (i.e. -1) means success, >= 0 indicates the character offset into the parameter at which an error was detected, usually because it contained '/'.

Definition at line 232 of file lib_id.cpp.

References item_name, and UTF8::substr().

Referenced by FOOTPRINT_VIEWER_FRAME::ExportSelectedFootprint(), SCH_COMPONENT::Load(), SCH_EDIT_FRAME::Load_Component(), LEGACY_NETLIST_READER::loadComponent(), Parse(), RESCUE_CASE_CANDIDATE::PerformAction(), RESCUE_CACHE_CANDIDATE::PerformAction(), SCH_COMPONENT::SCH_COMPONENT(), DIALOG_MODULE_MODULE_EDITOR::TransferDataFromWindow(), and RESCUER::UndoRescues().

233 {
234  int separation = int( aLibItemName.find_first_of( "/" ) );
235 
236  if( aTestForRev && separation != -1 )
237  {
238  item_name = aLibItemName.substr( 0, separation-1 );
239  return separation;
240  }
241  else
242  {
243  item_name = aLibItemName;
244  }
245 
246  return -1;
247 }
UTF8 substr(size_t pos=0, size_t len=npos) const
Definition: utf8.h:104
UTF8 item_name
The name of the entry in the logical library.
Definition: lib_id.h:224
int LIB_ID::SetLibNickname ( const UTF8 aNickname)

Function SetLibNickname.

overrides the logical library name portion of the LIB_ID to aNickname.

Returns
int - minus 1 (i.e. -1) means success, >= 0 indicates the character offset into the parameter at which an error was detected, usually because it contained '/' or ':'.

Definition at line 219 of file lib_id.cpp.

References nickname, and okLogical().

Referenced by FOOTPRINT_VIEWER_FRAME::ClickOnFootprintList(), EVT_TOOL(), FOOTPRINT_VIEWER_FRAME::ExportSelectedFootprint(), FP_LIB_TABLE::FootprintLoad(), guessNickname(), Parse(), and DIALOG_SYMBOL_REMAP::remapSymbolToLibTable().

220 {
221  int offset = okLogical( aLogical );
222 
223  if( offset == -1 )
224  {
225  nickname = aLogical;
226  }
227 
228  return offset;
229 }
static int okLogical(const std::string &aField)
Definition: lib_id.cpp:86
UTF8 nickname
The nickname of the library or empty.
Definition: lib_id.h:223
int LIB_ID::SetRevision ( const UTF8 aRevision)

Definition at line 250 of file lib_id.cpp.

References okRevision(), and revision.

251 {
252  int offset = okRevision( aRevision );
253 
254  if( offset == -1 )
255  {
256  revision = aRevision;
257  }
258 
259  return offset;
260 }
UTF8 revision
The revision of the entry.
Definition: lib_id.h:225
static int okRevision(const std::string &aField)
Definition: lib_id.cpp:94

Member Data Documentation

UTF8 LIB_ID::item_name
protected

The name of the entry in the logical library.

Definition at line 224 of file lib_id.h.

Referenced by clear(), compare(), empty(), Format(), GetLibItemName(), IsLegacy(), IsValid(), and SetLibItemName().

UTF8 LIB_ID::nickname
protected

The nickname of the library or empty.

Definition at line 223 of file lib_id.h.

Referenced by clear(), compare(), empty(), Format(), GetLibNickname(), IsLegacy(), IsValid(), and SetLibNickname().

UTF8 LIB_ID::revision
protected

The revision of the entry.

Definition at line 225 of file lib_id.h.

Referenced by clear(), compare(), empty(), Format(), GetLibItemNameAndRev(), GetRevision(), IsLegacy(), Parse(), and SetRevision().


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