cfl_indexset.h
Go to the documentation of this file.
1 /** @file cfl_indexset.h @brief Classes IndexSet, TaIndexSet */
2 
3 
4 /* FAU Discrete Event Systems Library (libfaudes)
5 
6  Copyright (C) 2006 Bernd Opitz
7  Copyright (C) 2007 Thomas Moor
8  Exclusive copyright is granted to Klaus Schmidt
9 
10  This library is free software; you can redistribute it and/or
11  modify it under the terms of the GNU Lesser General Public
12  License as published by the Free Software Foundation; either
13  version 2.1 of the License, or (at your option) any later version.
14 
15  This library is distributed in the hope that it will be useful,
16  but WITHOUT ANY WARRANTY; without even the implied warranty of
17  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18  Lesser General Public License for more details.
19 
20  You should have received a copy of the GNU Lesser General Public
21  License along with this library; if not, write to the Free Software
22  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23 
24 
25 
26 #ifndef FAUDES_INDEXSET_H
27 #define FAUDES_INDEXSET_H
28 
29 #include "cfl_definitions.h"
30 #include "cfl_exception.h"
31 #include "cfl_abaseset.h"
32 #include "cfl_symboltable.h"
33 #include "cfl_registry.h"
34 #include "cfl_basevector.h"
35 #include <algorithm>
36 
37 
38 namespace faudes {
39 
40 
41 
42 /** @addtogroup ContainerClasses */
43 /** @{*/
44 
45 // Forward declaration for the attributed version of indexset
46 template<class Attr> class TaIndexSet;
47 
48 /**
49  * Set of indices. This class is built on top of the faudes version
50  * TBaseSet of STL sets. It provides the essentials of the STL interface
51  * and inherits the standard token IO interface from Type, so you may
52  * use Read and Write for file/string/console IO.
53  *
54  * IndexSet is used as common base for TaIndexSet (indices with attributes),
55  * NameSet (indices with symbolic names) and TaNameSet (indices with
56  * attributes and symbolic names).
57  *
58  * The index of value 0 is reserved to indicate the invalid index. If the macro FAUDES_CHECKED
59  * is defined, the attempt to insert an index 0 triggers an exception (id 61). Invalid
60  * iterators throw an exception (id 62) when used as an argument to a IndexSet function.
61  *
62  * Technically, file IO is done by TaIndexSet functions. This requires a copy and for
63  * that reason may be reimplemented in a future versions.
64  * The format is demonstrated by the following example
65  * of a set with name "MySet" consisting of indices 17, 25, 26, 27, 28, 40:
66  * \code
67  * <Myset>
68  * 17
69  * <Consecutive> 25 4 </Consecutive>
70  * 40
71  * </MySet>
72  * \endcode
73  * Theere is a minimum number of consecutive indices for the use of the consecutive
74  * section defined in definitions.h.
75  *
76  */
77 
78 class IndexSet : public virtual TBaseSet<Idx> {
79 
81 
82 public:
83 
84  /**
85  * We implement "protected privacy for template classes" by friendship.
86  * This is used for the pragmatic implemention conversion constructors.
87  */
88  template<class Attr> friend class TaIndexSet;
89 
90 
91  /**
92  * Constructor.
93  */
94  IndexSet(void);
95 
96  /**
97  * Copy-constructor.
98  */
99  IndexSet(const IndexSet& rOtherSet);
100 
101  /**
102  * Copy-constructor.
103  */
104  IndexSet(const TBaseSet<Idx>& rOtherSet);
105 
106  /**
107  * Construct from file. Uses the Read(TokenReader&, const std::string&) function to read.
108  * a IndexSet from section rLabel in file rFilename.
109  *
110  * @param rFilename
111  * Name of file to read
112  * @param rLabel
113  * Section to read
114  *
115  * @exception Exception
116  * - IO Errors (id 1)
117  * - Token mismatch (id 50, 51, 52)
118  */
119  IndexSet(const std::string& rFilename, const std::string& rLabel = "");
120 
121  /**
122  * Virtual destructor
123  */
124  virtual ~IndexSet(void) {};
125 
126  /**
127  * Get maximum index used in this set (0 for emptyset)
128  *
129  * @return
130  * max indices
131  */
132  Idx MaxIndex(void) const;
133 
134  /**
135  * Test whether index is not 0
136  * @param rIndex
137  * Index to test
138  * @return
139  * True if idx!=0
140  */
141  bool Valid(const Idx& rIndex) const;
142 
143  /**
144  * Iterators on indexset.
145  */
147 
148  /**
149  * Insert new index to set
150  *
151  * @return
152  * New index
153  */
154  Idx Insert(void);
155 
156  /**
157  * Insert specified index
158  *
159  * @param rIndex
160  * Index to insert
161  * @return
162  * True if index was new to set
163  */
164  bool Insert(const Idx& rIndex);
165 
166  /**
167  * Compute an Idx type signature for a Set. The value is computed by
168  * summing up the product of every index with an integer starting at
169  * 1 (for the first index) and ending at Size() (for the last index).
170  *
171  * @return
172  * Idx type set signature
173  */
174  Idx Signature(void) const;
175 
176  /**
177  * Return pretty printable index.
178  *
179  * @param rIndex
180  * Index to print
181  *
182  * @return
183  * String
184  */
185  std::string Str(const Idx& rIndex) const {return ToStringInteger(rIndex); };
186 
187  protected:
188 
189  /**
190  * Assign my members. This method maintains attributes
191  * provided that the type can be appropriately casted.
192  *
193  * @param rSource
194  * Source to copy from
195  * @return
196  * Ref to this set
197  */
198  virtual void DoAssign(const IndexSet& rSource);
199 
200  /**
201  * Write to TokenWriter, see Type::Write for public wrappers.
202  * Appends the IndexSet to
203  * TokenWriter. This will write a section with label as specified that holds
204  * integer tokens to represent the IndexSet. For non-default attribute values,
205  * the respective index is followed by the attribute value. The latter may
206  * consist of sections (or tokens different from integer or string) to allow
207  * for transparent reading; see AttributeVoid and AttributeFlags. Example for
208  * a set with name "MySet" consisting of indices 17, 25, 40, where index 25 has a
209  * nontrivial attribute attached:
210  * \code
211  * <Myset>
212  * 17
213  * 25 <AValue> "Some Value" </AValue>
214  * 40
215  * </MySet>
216  * \endcode
217  *
218  * @param tw
219  * Reference to TokenWriter
220  * @param rLabel
221  * Label of section to write, defaults to name of set or "IndexSet"
222  * @param pContext
223  * Write context to provide contextual information
224  *
225  * @exception Exception
226  * - IO errors (id 2)
227  */
228  virtual void DoWrite(TokenWriter& tw, const std::string& rLabel="", const Type* pContext=0) const;
229 
230  /**
231  * Write to TokenWriter, see Type::Write for public wrappers. Appends the IndexSet to
232  * TokenWriter using XML format.
233  *
234  * @param tw
235  * Reference to TokenWriter
236  * @param rLabel
237  * Label of section to write, defaults to name of set or "IndexSet"
238  * @param pContext
239  * Write context to provide contextual information
240  *
241  * @exception Exception
242  * - IO errors (id 2)
243  */
244  virtual void DoXWrite(TokenWriter& tw, const std::string& rLabel="", const Type* pContext=0) const;
245 
246  /**
247  * Read from TokenReader, see Type::Read for public wrappers.
248  * This method invokes TokenReader::ReadBegin() to seek the specified
249  * section, reads subsequent integer tokens as indexes, and calls matching TokenReader::ReadEnd().
250  * If no section is specified, the section is assumed to start at the current position
251  * of the token stream. If the current position is no begin token,
252  * the section "IndexSet" is read.
253  * When used by a derived class with attributes, attributes are read, too.
254  *
255  * @param rTr
256  * Reference to tokenreader
257  * @param rLabel
258  * Section to read, defaults to current begin label or else "IndexSet"
259  * @param pContext
260  * Read context to provide contextual information
261  *
262  * @exception Exception
263  * - IO errors (id 1)
264  * - token mismatch (id 50, 51, 52)
265  */
266  virtual void DoRead(TokenReader& rTr, const std::string& rLabel="", const Type* pContext=0);
267 
268 };
269 
270 /* convenience typedef for stateset */
272 
273 
274 /**
275  * Convenience typedef for vectors og generators
276  * \ingroup GeneratorClasses
277  */
279 
280 
281 /**
282  * Set of indices with attributes. A TaIndexSet<Attr> is a template derived from IndexSet,
283  * such that each set element has an Attribute of class Attr.
284  * The template parameter Attr must provide basic functions for file IO and must define a default
285  * value, see AttributeVoid and AttributeFlags for an examples.
286  * Attributes are maintained by an STL map to associate indices
287  * with attributes different from the default value. Thus, attributes with default value
288  * do not take up any memeory.
289  *
290  * @param mAttributeMap
291  * STL map of type std::map<Idx,Attr> to hold attributes
292  *
293  * The copy constructor copies attributes; the methods InsertSet(), EraseSet() and
294  * RestrictSet() maintain attributes; all other set operations derived from IndexSet
295  * either return a IndexSet (no attributes) or set all attributes to the dafault value.
296  * To set or get an attribute of an index that does not exist in the set is considered
297  * as an error and triggers an exception (id 60) when the macro FAUDES_CHECKED is defined.
298  *
299  * The format for token IO is demonstrated by the following example
300  * of a set with name "MySet" consisting of indices 17, 25, 40, where index 25 has a
301  * nontrivial attribute attached:
302  * \code
303  * <Myset>
304  * 17
305  * 25 <AValue> "Some Value" </AValue>
306  * 40
307  * </MySet>
308  * \endcode
309  * Note that attributes may be either subsections or tokens of type different from integer and string.
310  * This is to allow reading a token stream to a class with incompatible (or no) attributes.
311  */
312 
313 
314 
315 template<class Attr>
316 class TaIndexSet : public IndexSet, public TaBaseSet<Idx,Attr> {
317 
319 
320 public:
321 
322  /**
323  * We implement "protected privacy for template classes" by friendship.
324  * This is used for the pragmatic implemention conversion constructors.
325  */
326  friend class IndexSet;
327 
328 
329  /**
330  * Constructor.
331  */
332  TaIndexSet(void);
333 
334  /**
335  * Copy-constructor (from TaIndexSet, incl attributes)
336  */
337  TaIndexSet(const TaIndexSet& rOtherSet);
338 
339  /**
340  * Copy-constructor (from IndexSet, sets attributes to default)
341  */
342  TaIndexSet(const IndexSet& rOtherSet);
343 
344  /**
345  * Construct from file.
346  * This constructor uses the Read(TokenReader&, const std::string&) function to read.
347  *
348  * @param rFilename
349  * Name of file
350  * @param rLabel
351  * Section for the set in file
352  *
353  * @exception Exception
354  * - IO errors (id 1)
355  * - token mismatch (id 50, 51, 52)
356  */
357  TaIndexSet(const std::string& rFilename, const std::string& rLabel = "");
358 
359  /**
360  * Virtual destructor
361  */
362  virtual ~TaIndexSet(void) {};
363 
364  /** Relaxed assignment method. Maintain attributes provided they can be casted.
365  *
366  * @param rSrc
367  * Source from which to assign
368  * @return
369  * Ref to this set
370  */
371  virtual TaIndexSet& Assign(const IndexSet& rSrc);
372 
373  /** Relaxed assignment operator. Maintain attributes provided they can be casted.
374  *
375  * @param rSrc
376  * Source from which to assign
377  * @return
378  * Ref to this set
379  */
380  virtual TaIndexSet& operator=(const IndexSet& rSrc);
381 
382  /**
383  * Set attributes. Provided that rOtherSet has attributes that can be
384  * casted to the appropriate type, attributes are copied per element from rOtherSet.
385  * Elements of this set which are not in rOtherSet maintain their attribute.
386  *
387  * @param rOtherSet
388  * Other IndexSet
389  * @exception Exception
390  * - Element does not exist (63)
391  * - Cannot cast attribute type (63)
392  */
393  virtual void Attributes(const IndexSet& rOtherSet);
394 
395  /**
396  * Set attributes. Attributes are copied per element from rOtherSet.
397  * Elements of this set which are not in rOtherSet maintain their attribute.
398  *
399  * @param rOtherSet
400  * Other IndexSet
401  */
402  virtual void Attributes(const TaIndexSet& rOtherSet);
403 
404  /**
405  * Iterators on indexset.
406  */
407  using IndexSet::Iterator;
408 
409  /**
410  * Erase Element (incl its attribute)
411  *
412  * @param rIndex
413  * Index to specify element
414  * @return
415  * True if element used to exist
416  */
417  bool Erase(const Idx& rIndex);
418 
419 
420  /**
421  * Erase element by iterator (incl attribute)
422  *
423  * @param pos
424  * Iterator to specify element
425  * @return
426  * Iterator to next element or End()
427  */
428  IndexSet::Iterator Erase(const Iterator& pos);
429 
430 
431  /**
432  * Erase elements given by other set. This function
433  * ignores the attributes of the other set and maintains the attributes
434  * of the remaining elements in this set.
435  *
436  * @param rOtherSet
437  * Elements to erase
438  */
439  void EraseSet(const IndexSet& rOtherSet);
440 
441  /**
442  * Restrict to specified subset. Erases any elements no in
443  * the specified set. This function
444  * ignores the attributes of the other set and maintains the attributes
445  * of the remaining elements in this set.
446  *
447  * @param rOtherSet
448  * Elements to erase
449  */
450  void RestrictSet(const IndexSet& rOtherSet);
451 
452 
453  /**
454  * Insert new index to set using default attribute.
455  *
456  * @return
457  * New index
458  */
459  Idx Insert(void);
460 
461  /**
462  * Insert new index with attribute.
463  * If the index allready exists, the
464  * attribute is overwritten by rAttr.
465  *
466  * @param rAttr
467  * Specify attribute of new element
468  * @return
469  * new index
470  */
471  Idx Insert(const Attr& rAttr);
472 
473  /**
474  * Insert element. If the element exists, the attribute is maintained.
475  * If the element does not exist, it is inserted with default attribute.
476  *
477  * @param rIndex
478  * Index to specify element
479  * @return
480  * True if element was new to set
481  */
482  bool Insert(const Idx& rIndex);
483 
484  /**
485  * Insert element with attribute.
486  *
487  * @param rIndex
488  * Index to specify element
489  * @param attr
490  * Specify attribute of (new) element
491  * @return
492  * True if element was new to set
493  */
494  bool Insert(const Idx& rIndex, const Attr& attr);
495 
496  /**
497  * Inserts elements of rOtherSet.
498  * Attributes of this set are maintained, newly inserted elements have default attribute.
499  *
500  *
501  * @param rOtherSet
502  * Other IndexSet
503  */
504  virtual void InsertSet(const IndexSet& rOtherSet);
505 
506  /**
507  * Inserts elements of rOtherSet.
508  * Attributes of this set are maintained, new elements are inserted with attribute.
509  *
510  * @param rOtherSet
511  * Other IndexSet
512  */
513  virtual void InsertSet(const TaIndexSet& rOtherSet);
514 
515  /**
516  * Clear all set.
517  */
518  virtual void Clear(void);
519 
520 
521 
522  protected:
523 
524  /**
525  * Assign my members. This method maintains attributes.
526  *
527  * @param rSource
528  * Source to copy from
529  * @return
530  * Ref to this set
531  */
532  virtual void DoAssign(const TaIndexSet& rSource);
533 
534 
535 };
536 
537 /** Convenience Macro */
538 //template<class Attr> typedef TaStateSet<class Attr> TaIndexSet<class Attr>
539 #define TaStateSet TaIndexSet
540 
541 
542 
543 
544 /** @} doxygen group */
545 
546 
547 /*
548 *************************************************************************************
549 *************************************************************************************
550  Implementation
551 *************************************************************************************
552 *************************************************************************************
553 */
554 
555 
556 // std faudes type
557 FAUDES_TYPE_TIMPLEMENTATION(Void,TaIndexSet<Attr>,IndexSet,template<class Attr>)
558 
559 
560 // TaIndexSet()
561 template<class Attr>
562 TaIndexSet<Attr>::TaIndexSet(void) :
563  TBaseSet<Idx>(),
564  IndexSet(),
565  TaBaseSet<Idx,Attr>()
566 {
567  FD_DC("TaIndexSet(" << this << ")::TaIndexSet()");
568 }
569 
570 // TaIndexSet(rOtherSet)
571 template<class Attr>
573  TBaseSet<Idx>(),
574  IndexSet(),
575  TaBaseSet<Idx,Attr>()
576 {
577  FD_DC("TaIndexSet(" << this << ")::TaIndexSet(rOtherSet " << &rOtherSet << ")");
578  // copy my members
579  DoAssign(rOtherSet);
580 }
581 
582 // TaIndexSet(rOtherSet)
583 template<class Attr>
585  TBaseSet<Idx>(),
586  IndexSet(),
587  TaBaseSet<Idx,Attr>()
588 {
589  FD_DC("TaIndexSet(" << this << ")::TaIndexSet(rOtherSet " << &rOtherSet << ")");
590  // copy my members
591  Assign(rOtherSet);
592 }
593 
594 
595 // File constructor
596 template<class Attr>
597  TaIndexSet<Attr>::TaIndexSet(const std::string& rFilename, const std::string& rLabel) :
598  TBaseSet<Idx>(),
599  IndexSet(),
600  TaBaseSet<Idx,Attr>()
601 {
602  FD_DC("TaIndexSet(" << this << ")::TaIndexSet(" << rFilename << ")");
603  Read(rFilename, rLabel);
604 }
605 
606 
607 // DoAssign (attributes known and match)
608 template<class Attr>
610  FD_DC("TaIndexSet(" << this << ")::DoAssign( [a] " << &rSourceSet<<")");
611  // call base incl attributes
612  TaBaseSet<Idx,Attr>::DoAssign(rSourceSet);
613 }
614 
615 // Relaxed Assign()
616 template<class Attr>
618  FD_DC("TaIndexSet(" << this << ")::Assign([v] " << &rSourceSet<<")");
619  FD_DC("TaIndexSet(" << this << ")::Assign(): src type " << typeid(rSourceSet).name());
620  FD_DC("TaIndexSet(" << this << ")::Assign(): dst type " << typeid(*this).name());
621  // call attribute smart base
622  TaBaseSet<Idx,Attr>::Assign(rSourceSet);
623  // done
624  return *this;
625 }
626 
627 // Relaxed Assignment Operator(rSet)
628 template<class Attr>
630  return Assign(rSourceSet);
631 }
632 
633 
634 // Attributes(set)
635 template<class Attr>
636 void TaIndexSet<Attr>::Attributes(const TaIndexSet& rOtherSet) {
637  FD_DC("TaIndexSet(" << this << ")::Attributes(set) with type " << typeid(rOtherSet.Attribute()).name());
639 }
640 
641 // Attributes(set)
642 template<class Attr>
643 void TaIndexSet<Attr>::Attributes(const IndexSet& rOtherSet) {
644  FD_DC("TaIndexSet(" << this << ")::Attributes(set) with type " << typeid(rOtherSet.Attribute()).name());
646 }
647 
648 
649 //Clear
650 template<class Attr>
652  FD_DC("TaIndexSet(" << this << ")::Clear()");
654 }
655 
656 // Insert()
657 template<class Attr>
659  FD_DC("TaIndexSet(" << this << ")::Insert()");
660  Idx index=MaxIndex()+1;
662  return index;
663 }
664 
665 //Insert(idx)
666 template<class Attr>
667 bool TaIndexSet<Attr>::Insert(const Idx& rIndex) {
668  FD_DC("TaIndexSet(" << this << ")::Insert("<< rIndex <<")");
669  bool ret=IndexSet::Insert(rIndex); // automatic: keep attribute if exists
670  return ret;
671 }
672 
673 // Insert(attr)
674 template<class Attr>
675 Idx TaIndexSet<Attr>::Insert(const Attr& attr) {
676  FD_DC("TaIndexSet(" << this << ")::Insert(" << attr.ToString() << ")");
677  Idx index = Insert();
678  if(!attr.IsDefault()) {
679  TaBaseSet<Idx,Attr>::Attribute(index,attr);
680  }
681  return index;
682 }
683 
684 //Insert(idx,attr)
685 template<class Attr>
686 bool TaIndexSet<Attr>::Insert(const Idx& rIndex, const Attr& attr) {
687  FD_DC("TaIndexSet(" << this << ")::Insert("<< rIndex <<",attr)");
688  return TaBaseSet<Idx,Attr>::Insert(rIndex,attr);
689 }
690 
691 
692 // InsertSet(set)
693 template<class Attr>
694 void TaIndexSet<Attr>::InsertSet(const TaIndexSet& rOtherSet) {
695  FD_DC("TaIndexSet(" << this << ")::InsertSet( T " << &rOtherSet << ")");
697 }
698 
699 // InsertSet(set)
700 template<class Attr>
701 void TaIndexSet<Attr>::InsertSet(const IndexSet& rOtherSet) {
702  FD_DC("TaIndexSet(" << this << ")::InsertSet(" << &rOtherSet << ")");
703  IndexSet::InsertSet(rOtherSet);
704 }
705 
706 //Erase(idx)
707 template<class Attr>
708 bool TaIndexSet<Attr>::Erase(const Idx& rIndex) {
709  return TaBaseSet<Idx,Attr>::Erase(rIndex);
710 }
711 
712 //Erase(pos)
713 template<class Attr>
714 typename IndexSet::Iterator TaIndexSet<Attr>::Erase(const Iterator& pos) {
715  return TaBaseSet<Idx,Attr>::Erase(pos);
716 }
717 
718 
719 //EraseSet(set)
720 template<class Attr>
721 void TaIndexSet<Attr>::EraseSet(const IndexSet& rOtherSet) {
722  FD_DC("TaIndexSet(" << this << ")::EraseSet(" << rOtherSet.ToString() << ")");
724 }
725 
726 //RestrictSet(set)
727 template<class Attr>
728 void TaIndexSet<Attr>::RestrictSet(const IndexSet& rOtherSet) {
729  FD_DC("TaIndexSet(" << this << ")::RestrictSet(" << rOtherSet.ToString() << ")");
731 }
732 
733 
734 
735 
736 } // namespace faudes
737 
738 
739 
740 #endif
741 

libFAUDES 2.26g --- 2015.08.17 --- c++ api documentaion by doxygen