cfl_basevector.h
Go to the documentation of this file.
1 /** @file cfl_basevector.h @brief Class TBaseVector */
2 
3 
4 /* FAU Discrete Event Systems Library (libfaudes)
5 
6  Copyright (C) 2009 Thomas Moor
7 
8  This library is free software; you can redistribute it and/or
9  modify it under the terms of the GNU Lesser General Public
10  License as published by the Free Software Foundation; either
11  version 2.1 of the License, or (at your option) any later version.
12 
13  This library is distributed in the hope that it will be useful,
14  but WITHOUT ANY WARRANTY; without even the implied warranty of
15  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  Lesser General Public License for more details.
17 
18  You should have received a copy of the GNU Lesser General Public
19  License along with this library; if not, write to the Free Software
20  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
21 */
22 
23 
24 
25 #ifndef FAUDES_BASEVECTOR_H
26 #define FAUDES_BASEVECTOR_H
27 
28 #include "cfl_definitions.h"
29 #include "cfl_tokenwriter.h"
30 #include "cfl_tokenreader.h"
31 #include "cfl_types.h"
32 #include "cfl_attributes.h"
33 #include <vector>
34 #include <algorithm>
35 
36 // fix mingw toochain
37 #ifdef THIS
38 #undef THIS
39 #endif
40 
41 namespace faudes {
42 
43 /** @addtogroup ContainerClasses */
44 /** @{*/
45 
46 /**
47  * Vector bass class.
48  *
49  * This class is designed as a random access container for a small number of
50  * comperatively large objects, eg a vector of generators to model a decentralized DES.
51  * The API is restricted to simple positional access and there are no explicit
52  * iterators nor is there a deferred copy mechanism. As with other faudes containers,
53  * vBaseVector is the universal base class for all faudes vector data types. The latter
54  * explicitely refer to the element data type and are implemented as templates.
55  *
56  * Internally, the vBaseVector template uses STL vector of pointers to the individual entries.
57  * When adding an entry, you may either do so be refernce or by pointer. When setting
58  * by reference, the vector takes a copy and owns the new entry. When setting by a pointer,
59  * the vector only records the reference. The vector tracks ownership of each entry in order
60  * to properly destruct entries.
61  *
62  * vBaseVector serves as a base class for all libFaudes vectors:
63  * - GeneratorVector (vector or generators)
64  * - EventSetVector (vector of event sets)
65  *
66  * Token io assumes that the type parameter is a faudes type, ie. entries of the vector
67  * provide token io themselfs. To derive a vector class with non-faudes-type entries,
68  * you will need to reimplement token io. As a convenience feature, the vector keeps a record
69  * of filenames associated with individual entries. You can inspect and edit this record via
70  * the FilenameAt members. When writing the vector to a file and all entries have an associated filename,
71  * output will be to the individual files.
72  *
73  */
74 
75 class FAUDES_API vBaseVector : public Type {
76 
78 
79 public:
80 
81  using Type::operator=;
82  using Type::operator==;
83  using Type::operator!=;
84 
85  /**
86  * Constructor.
87  */
88  vBaseVector(void);
89 
90  /**
91  * Copy-constructor.
92  *
93  * @param rOtherVector
94  * Source to copy from
95  */
96  vBaseVector(const vBaseVector& rOtherVector);
97 
98  /**
99  * Constructor from file.
100  *
101  * @param rFilename
102  * Name of File
103  * @param rLabel
104  * Section for the set in the file;
105  */
106  vBaseVector(const std::string& rFilename, const std::string& rLabel = "BaseVector");
107 
108  /**
109  * Virtual destructor
110  */
111  virtual ~vBaseVector(void);
112 
113  /**
114  * Prototype for vector entries.
115  * The virtual base vBaseVector will provide a plain Type object.
116  * Derived vector classes are meant to reimplement this function.
117  *
118  * @return
119  * Element protoype
120  */
121  virtual const Type* Elementp(void) const;
122 
123 
124  /**
125  * Prototype for vector entries.
126  * This is a convenience wrapper for Elementp.
127  *
128  * @return
129  * Element protoype
130  */
131  virtual const Type& Element(void) const;
132 
133 
134  /**
135  * Factory method for vector entries.
136  * This is a convenience wrapper using Elementp.
137  *
138  * @return
139  * New element allocated on heap
140  */
141  virtual Type* NewElement(void);
142 
143  /**
144  * Test whether the specified element is acceptebla for this vector.
145  * This is a convenience wrapper for Elementp.
146  *
147  * @param rElement
148  * Element to type check.
149  * @return
150  * True, if provided element is accepted by this vector.
151  */
152  virtual bool ElementTry(const Type& rElement) const;
153 
154 
155  /**
156  * Return name of vBaseVector
157  *
158  * @return
159  * Name of vBaseVector
160  */
161  const std::string& Name(void) const;
162 
163  /**
164  * Set name of vBaseVector
165  *
166  * @param rName
167  * Name to set
168  */
169  void Name(const std::string& rName);
170 
171  /**
172  * Clear all vector
173  */
174  virtual void Clear(void);
175 
176  /**
177  * Get size of vector.
178  *
179  * @return
180  * Number of entries.
181  */
182  Idx Size(void) const;
183 
184  /**
185  * Set size of vector.
186  * If the new size is smaller than the current size,
187  * the vector is truncated. If it is larger, default members
188  * are inserted at the end.
189  *
190  * @param len
191  * Number of entries in vector
192  */
193  void Size(Idx len);
194 
195  /**
196  * Check if the vBaseVector ist Empty
197  *
198  * @return
199  * True if empty
200  */
201  bool Empty(void) const;
202 
203  /**
204  * convenience typedef for positions (must be unsigned)
205  */
206  typedef size_t Position;
207 
208  /**
209  * Access element.
210  *
211  * @param pos
212  * Specify entry to access
213  * @exception Exception
214  * - Position out of range (id 69)
215  */
216  virtual const Type& At(const Position& pos) const;
217 
218  /**
219  * Access element.
220  *
221  * @param pos
222  * Specify entry to access
223  * @exception Exception
224  * - Position out of range (id 69)
225  */
226  virtual Type& At(const Position& pos);
227 
228 
229  /**
230  * Replace specified entry.
231  * This method takes a copy of the entry to replace and the
232  * vector becomes the owner of the copy.
233  *
234  * @param pos
235  * Position to replace
236  * @param rElem
237  * New entry
238  * @exception Exception
239  * - Position out of range (id 69)
240  * - Cannot cast element type (63)
241  */
242  virtual void Replace(const Position& pos, const Type& rElem);
243 
244  /**
245  * Replace specified entry.
246  * This method avoids to copy the entry to replace and only records the reference.
247  * The vector does not take ownership of the new entry. I.e., when the vector is destroyed, or the
248  * entry is deleted from the vector, the entry itself remains allocated.
249  *
250  * @param pos
251  * Position to replace
252  * @param pElem
253  * New entry
254  * @exception Exception
255  * - Position out of range (id 69)
256  * - Cannot cast element type (63)
257  */
258  virtual void Replace(const Position& pos, Type* pElem);
259 
260  /**
261  * Replace specified entry.
262  * This method reads the sepcified entry from file and the
263  * vector becomes the owner of the new entry.
264  *
265  * @param pos
266  * Position to replace
267  * @param rFileName
268  * New entry to be read from file
269  * @exception Exception
270  * - Position out of range (id 69)
271  */
272  virtual void Replace(const Position& pos, const std::string& rFileName);
273 
274 
275  /**
276  * Erase entry by position.
277  * If the vector owns the entry, it will be destructed.
278  *
279  * @param pos
280  * Specify entry to erase
281  * @exception Exception
282  * - Position out of range (id 69)
283  */
284  virtual void Erase(const Position& pos);
285 
286  /**
287  * Insert specified entry.
288  * This method takes a copy of the entry to replace and the
289  * vector becomes the owner of the copy.
290  *
291  * @param pos
292  * Position at which to insert
293  * @param rElem
294  * Element to insert
295  * @exception Exception
296  * - Position out of range (id 69)
297  * - Cannot cast element type (63)
298  */
299  virtual void Insert(const Position& pos, const Type& rElem);
300 
301  /**
302  * Insert specified entry.
303  * This method avoids to copy the entry to replace and only records the reference.
304  * The vector does not take ownership of the new entry. I.e., when the vector is destroyed, or the
305  * entry is deleted from the vector, the entry itself remains allocated.
306  *
307  *
308  * @param pos
309  * Position at which to insert
310  * @param rElem
311  * Element to insert
312  * @exception Exception
313  * - Position out of range (id 69)
314  * - Cannot cast element type (63)
315  */
316  virtual void Insert(const Position& pos, Type* rElem);
317 
318  /**
319  * Insert specified entry.
320  * This method reads the sepcified entry from file and the
321  * vector becomes the owner of the new entry.
322  *
323  * @param pos
324  * Position at which to insert
325  * @param rFileName
326  * Element to insert
327  * @exception Exception
328  * - Position out of range (id 69)
329  */
330  virtual void Insert(const Position& pos, const std::string& rFileName);
331 
332  /**
333  * Append specified entry.
334  * This method takes a copy of the entry to replace and the
335  * vector becomes the owner of the copy.
336  *
337  * @param rElem
338  * Element to append
339  * @exception Exception
340  * - Cannot cast element type (63)
341  */
342  virtual void PushBack(const Type& rElem);
343 
344  /**
345  * Append specified entry.
346  * This method avoids to copy the entry to replace and only records the reference.
347  * The vector does not take ownership of the new entry. I.e., when the vector is destroyed, or the
348  * entry is deleted from the vector, the entry itself remains allocated.
349  *
350  *
351  * @param rElem
352  * Element to insert
353  * @exception Exception
354  * - Cannot cast element type (63)
355  */
356  virtual void PushBack(Type* rElem);
357 
358  /**
359  * Append specified entry.
360  * This method reads the sepcified entry from file and the
361  * vector becomes the owner of the new entry.
362  *
363  * @param rFileName
364  * Element to insert
365  */
366  virtual void PushBack(const std::string& rFileName);
367 
368  /**
369  * Append specified entry.
370  * Synonymous for PushBack.
371  * This method takes a copy of the entry to replace and the
372  * vector becomes the owner of the copy.
373  *
374  * @param rElem
375  * Element to append
376  * @exception Exception
377  * - Cannot cast element type (63)
378  */
379  virtual void Append(const Type& rElem);
380 
381  /**
382  * Append specified entry.
383  * Synonymous for PushBack.
384  * This method avoids to copy the entry to replace and only records the reference.
385  * The vector does not take ownership of the new entry. I.e., when the vector is destroyed, or the
386  * entry is deleted from the vector, the entry itself remains allocated.
387  *
388  *
389  * @param rElem
390  * Element to insert
391  * @exception Exception
392  * - Cannot cast element type (63)
393  */
394  virtual void Append(Type* rElem);
395 
396  /**
397  * Append specified entry.
398  * Synonymous for PushBack.
399  * This method reads the sepcified entry from file and the
400  * vector becomes the owner of the new entry.
401  *
402  * @param rFileName
403  * Element to insert
404  */
405  virtual void Append(const std::string& rFileName);
406 
407  /**
408  * Find element.
409  * This method iterates through the vector to find a matching element. This is generally inefficient,
410  * consider to use an STL set instead.
411  *
412  * @param rElem
413  * Element to serach for
414  * @return
415  * Position on success (or >= Size() for not found)
416  * @exception Exception
417  * - Cannot cast element type (63)
418  */
419  virtual Position Find(const Type& rElem);
420 
421  /**
422  * Specify a filename.
423  * When each entry has a filename specified,
424  * file io of the vector will be to indiviudual files.
425  *
426  * @param pos
427  * Position of entry
428  * @param rFileName
429  * Filename relative to vector file
430  * @exception Exception
431  * - Position out of range (id 69)
432  */
433  void FilenameAt(const Position& pos, const std::string& rFileName);
434 
435  /**
436  * Get filename of entry.
437  *
438  * @param pos
439  * Position of entry
440  * @return
441  * Filename assoiated with entry
442  * @exception Exception
443  * - Position out of range (id 69)
444  */
445  const std::string& FilenameAt(const Position& pos) const;
446 
447  /**
448  * Take ownership of all entries.
449  * This method will take ownership of all entries, including those, that
450  * have been set by pointer reference. When the vector is destructed, all
451  * entries will be destructed, too. However, write access may invalidate
452  * element pointers.
453  *
454  */
455  void TakeOwnership(void);
456 
457  /**
458  * Take local copies of all entries.
459  * This method will construct local copies of all entries not previously
460  * owned.
461  */
462  void TakeCopies(void);
463 
464 protected:
465 
466 
467  /**
468  * Token output, debugging see Type::DWrite for public wrappers.
469  * The method assumes that the type parameter is a faudes type and uses
470  * the provide write method per entry. Reimplement this function in derived
471  * classes for non-faudes type vectors.
472  * @param rTw
473  * Reference to TokenWriter
474  * @param rLabel
475  * Label of section to write, defaults to name of set
476  * @param pContext
477  * Write context to provide contextual information
478  */
479  virtual void DoDWrite(TokenWriter& rTw,const std::string& rLabel="", const Type* pContext=0) const;
480 
481  /**
482  * Token output, see Type::SWrite for public wrappers.
483  * The method assumes that the type parameter is a faudes type and uses
484  * the provide write method per entry. Reimplement this function in derived
485  * classes for non-faudes type vectors.
486  *
487  * @param rTw
488  * Reference to TokenWriter
489  *
490  * @exception Exception
491  * - IO errors (id 2)
492  */
493  virtual void DoSWrite(TokenWriter& rTw) const;
494 
495  /**
496  * Token output, see Type::Write for public wrappers.
497  * The method assumes that the type parameter is a faudes type and uses
498  * the provide write method per entry. Reimplement this function in derived
499  * classes for non-faudes type vectors.
500  *
501  * @param rTw
502  * Reference to TokenWriter
503  * @param rLabel
504  * Label of section to write, defaults to name of set
505  * @param pContext
506  * Write context to provide contextual information
507  */
508  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="", const Type* pContext=0) const;
509 
510  /**
511  * Token input, see Type::Read for public wrappers.
512  * The method assumes that the type parameter is a faudes type and uses
513  * the provide read method per entry. Reimplement this function in derived
514  * classes for non-faudes type vectors.
515  * By convention, the default label "" should be translated to some meaningful default,
516  * eg "GeneratorVector" for a vector of generators. The pContext pointer can be type-checked
517  * and interpreted, ie as a symboltable to provide symbolic names. It is also
518  * passed on to vector entries.
519  *
520  * @param rTr
521  * Reference to TokenReader
522  * @param rLabel
523  * Label of section to read, defaults to name of set
524  * @param pContext
525  * Read context to provide contextual information
526  */
527  virtual void DoRead(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
528 
529  /** Assignment method */
530  void DoAssign(const vBaseVector& rSourceVector);
531 
532  /** Internal entry data type */
534  public:
536  std::string mFileName;
537  bool mMine;
538  };
539 
540  /** STL vector of element */
541  std::vector<ElementRecord> mVector;
542 
543  /** convenience typedef */
544  typedef std::vector<ElementRecord>::iterator iterator;
545 
546 private:
547 
548  /** Name of TBaseVector */
549  std::string mMyName;
550 
551 };
552 
553 
554 /** @} doxygen group */
555 
556 
557 /** @addtogroup ContainerClasses */
558 /** @{*/
559 
560 /**
561  * Vector template.
562  *
563  * The vector templates specializes the bass vBaseVector in that it uses the template
564  * parameter to specify the type of its entries. See vBaseVector for element access
565  * methods.
566  *
567  * TVectorSet serves is used to implement the libFaudes vectors
568  * - GeneratorVector (vector or generators)
569  * - SytemVector (vector or generators)
570  * - EventSetVector (vector of event sets)
571  * - AlphabetVector (vector of event sets)
572  *
573  *
574  */
575 
576 template<class T>
578 
580 
581 public:
582 
583  using vBaseVector::operator=;
584  using vBaseVector::operator==;
585  using vBaseVector::operator!=;
586 
587  /**
588  * Constructor.
589  */
590  TBaseVector(void);
591 
592  /**
593  * Copy-constructor.
594  *
595  * @param rOtherSet
596  * Source to copy from
597  */
598  TBaseVector(const TBaseVector& rOtherSet);
599 
600  /**
601  * Copy-constructor. This version takes any vector as source,
602  * but throughs an exception, if element types dont match.
603  *
604  * @param rOtherSet
605  * Source to copy from
606  * @exception Exception
607  * - Cannot cast elements (63)
608  */
609  TBaseVector(const vBaseVector& rOtherSet);
610 
611  /**
612  * Constructor from file.
613  *
614  * @param rFilename
615  * Name of File
616  * @param rLabel
617  * Section for the set in the file;
618  */
619  TBaseVector(const std::string& rFilename, const std::string& rLabel = "BaseVector");
620 
621  /**
622  * Virtual destructor
623  */
624  virtual ~TBaseVector(void);
625 
626 
627  /**
628  * Prototype for vector entries.
629  * This template class uses the virtual function to know its element type.
630  *
631  * @return
632  * Element protoype
633  */
634  virtual const T* Elementp(void) const;
635 
636  /**
637  * Test whether the specified element is acceptebla for this vector.
638  * This is a convenience wrapper for Elementp.
639  *
640  * @param rElement
641  * Element to type check.
642  * @return
643  * True, if provided element is accepted by this vector.
644  */
645  virtual bool ElementTry(const Type& rElement) const;
646 
647  /**
648  * convenience typedef for positions
649  */
650  typedef std::vector<int>::size_type Position;
651 
652  /**
653  * Access element.
654  *
655  * @param pos
656  * Specify entry to access
657  * @exception Exception
658  * - Position out of range (id 69)
659  */
660  virtual const T& At(const Position& pos) const;
661 
662  /**
663  * Access element.
664  *
665  * @param pos
666  * Specify entry to access
667  * @exception Exception
668  * - Position out of range (id 69)
669  */
670  virtual T& At(const Position& pos);
671 
672 protected:
673 
674  /** Assignment method */
675  void DoAssign(const TBaseVector<T>& rSourceVector);
676 
677 
678 };
679 
680 
681 /** @} doxygen group */
682 
683 
684 
685 /*
686 ******************************************************************************************
687 ******************************************************************************************
688 ******************************************************************************************
689 
690 Implementation of TBaseVector
691 
692 ******************************************************************************************
693 ******************************************************************************************
694 ******************************************************************************************
695 */
696 
697 /* convenience access to relevant scopes */
698 #define THIS TBaseVector<T>
699 #define TEMP template<class T>
700 #define BASE vBaseVector
701 
702 
703 // faudes type std
704 FAUDES_TYPE_TIMPLEMENTATION(Void,THIS,vBaseVector,TEMP)
705 
706 // TBaseVector()
708  vBaseVector()
709 {
710  FD_DC("TBaseVector(" << this << ")::TBaseVector()");
711 }
712 
713 
714 // TBaseVector(filename)
715 TEMP THIS::TBaseVector(const std::string& rFileName, const std::string& rLabel) :
716  vBaseVector()
717 {
718  FD_DC("TBaseVector(" << this << ")::TBaseVector()");
719  // do read;
720  Read(rFileName,rLabel);
721 }
722 
723 
724 // TBaseVector(rOtherSet)
725 TEMP THIS::TBaseVector(const TBaseVector& rOtherVector) :
726  vBaseVector()
727 {
728  FD_DC("TBaseVector(" << this << ")::TBaseVector(rOtherVector " << &rOtherVector << "): copy construct");
729  DoAssign(rOtherVector);
730 }
731 
732 // TBaseVector(rOtherSet)
733 TEMP THIS::TBaseVector(const vBaseVector& rOtherVector) :
734  vBaseVector()
735 {
736  FD_DC("TBaseVector(" << this << ")::TBaseVector([v] rOtherVector " << &rOtherVector << "): copy construct");
737  Assign(rOtherVector);
738 }
739 
740 // destructor
741 TEMP THIS::~TBaseVector(void) {
742  FD_DC("TBaseVector(" << this << ")::~TBaseVector()");
743 }
744 
745 
746 // element prototype
747 TEMP const T* THIS::Elementp(void) const {
748  static T tproto;
749  return &tproto;
750 }
751 
752 // test element type
753 TEMP bool THIS::ElementTry(const Type& rElement) const {
754  FD_DC("TBaseVector::ElementTry(): casting from " << typeid(rElement).name() << " to " << typeid(*Elementp()).name());
755  return Elementp()->Cast(&rElement)!=NULL;
756 }
757 
758 
759 // assignment
760 TEMP void THIS::DoAssign(const THIS& rSourceVector) {
761  FD_DC("TBaseVector(" << this << ")::DoAssign(rOtherVector " << &rSourceVector << ")");
762  // base can do it
763  BASE::DoAssign(rSourceVector);
764  // done
765  FD_DC("TBaseVector(" << this << ")::DoAssign(rOtherVector " << &rSourceVector << "): done");
766 }
767 
768 // At()
769 TEMP const T& THIS::At(const Position& pos) const {
770 #ifdef FAUDES_CHECKED
771  if(pos >= mVector.size()) {
772  std::stringstream errstr;
773  errstr << "index out of range" << std::endl;
774  throw Exception("TBaseVector::At", errstr.str(), 62);
775  }
776 #endif
777 #ifdef FAUDES_DEBUG_CODE
778  if(!dynamic_cast<T*>(mVector[pos].pElement)){
779  std::stringstream errstr;
780  errstr << "internal type error" << std::endl;
781  throw Exception("TBaseVector::At", errstr.str(), 63);
782  }
783 #endif
784  return *dynamic_cast<T*>(mVector[pos].pElement);
785 }
786 
787 // At()
788 TEMP T& THIS::At(const Position& pos) {
789 #ifdef FAUDES_CHECKED
790  if(pos >= mVector.size()) {
791  std::stringstream errstr;
792  errstr << "index out of range" << std::endl;
793  throw Exception("TBaseVector::At", errstr.str(), 62);
794  }
795 #endif
796 #ifdef FAUDES_DEBUG_CODE
797  if(!dynamic_cast<T*>(mVector[pos].pElement)){
798  std::stringstream errstr;
799  errstr << "internal type error" << std::endl;
800  throw Exception("TBaseVector::At", errstr.str(), 63);
801  }
802 #endif
803  return *dynamic_cast<T*>(mVector[pos].pElement);
804 }
805 
806 
807 
808 
809 
810 /* undefine local shortcuts */
811 #undef THIS
812 #undef TEMP
813 #undef BASE
814 
815 
816 } // namespace faudes
817 
818 #endif
#define TEMP
#define THIS
#define FD_DC(message)
#define FAUDES_API
Definition: cfl_platform.h:80
#define FAUDES_TAPI
Definition: cfl_platform.h:83
Class TokenReader.
Class TokenWriter.
#define FAUDES_TYPE_TDECLARATION(ftype, ctype, cbase)
Definition: cfl_types.h:883
#define FAUDES_TYPE_DECLARATION(ftype, ctype, cbase)
Definition: cfl_types.h:872
#define FAUDES_TYPE_TIMPLEMENTATION(ftype, ctype, cbase, ctemp)
Definition: cfl_types.h:977
std::vector< int >::size_type Position
TBaseVector(const std::string &rFilename, const std::string &rLabel="BaseVector")
virtual const T * Elementp(void) const
virtual bool ElementTry(const Type &rElement) const
virtual const T & At(const Position &pos) const
virtual ~TBaseVector(void)
TBaseVector(const vBaseVector &rOtherSet)
TBaseVector(const TBaseVector &rOtherSet)
void DoAssign(const TBaseVector< T > &rSourceVector)
virtual T & At(const Position &pos)
void Read(const std::string &rFileName, const std::string &rLabel="", const Type *pContext=0)
Definition: cfl_types.cpp:262
virtual Type & Assign(const Type &rSrc)
Definition: cfl_types.cpp:77
std::vector< ElementRecord >::iterator iterator
std::vector< ElementRecord > mVector
uint32_t Idx

libFAUDES 2.33b --- 2025.05.07 --- c++ api documentaion by doxygen