Statistics
| Branch: | Revision:

root / include / cdisplaystring.h @ master

History | View | Annotate | Download (9.35 KB)

1 01873262 Georg Kunz
//==========================================================================
2
//   CDISPLAYSTRING.H  - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//
7
//  Declaration of the following classes:
8
//    cDisplayString : utility class for display string manipulation
9
//
10
//==========================================================================
11
12
/*--------------------------------------------------------------*
13
  Copyright (C) 1992-2008 Andras Varga
14
  Copyright (C) 2006-2008 OpenSim Ltd.
15

16
  This file is distributed WITHOUT ANY WARRANTY. See the file
17
  `license' for details on this and other legal matters.
18
*--------------------------------------------------------------*/
19
20
#ifndef __CDISPLAYSTRING_H
21
#define __CDISPLAYSTRING_H
22
23
#include "cobject.h"
24
#include "cgate.h"
25
#include "cmodule.h"
26
27
NAMESPACE_BEGIN
28
29
30
/**
31
 * Class for storage and easy manipulation of display strings. Display strings
32
 * are used to control the graphical presentation of network elements
33
 * when a GUI execution environment is used (Tkenv).
34
 *
35
 * A display string consist of several named tags, where each tag may have
36
 * several arguments (parameters). The syntax: "tag1=value1,val2,val3;tag2=val4,val5".
37
 *
38
 * This class facilitates tasks such as adding new tags, adding arguments to
39
 * existing tags, removing tags or replacing arguments. The internal storage
40
 * method allows very fast operation; it will generally be faster than
41
 * direct string manipulation.
42
 *
43
 * The object doesn't try to interpret the display string in any way,
44
 * nor does it know the meaning of the different tags; it merely
45
 * parses the string as data elements separated by semicolons, equal
46
 * signs and commas.
47
 *
48
 * An example:
49
 * <pre>
50
 *   cDisplayString dispstr("a=1,2;p=alpha,,3");
51
 *   dispstr.insertTag("x");
52
 *   dispstr.setTagArg("x",0,"joe");
53
 *   dispstr.setTagArg("x",2,"jim");
54
 *   dispstr.setTagArg("p",0,"beta");
55
 *   ev << dispstr.str();  // result: "x=joe,,jim;a=1,2;p=beta,,3"
56
 * </pre>
57
 *
58
 * Limitation: a tag may have at most 16 arguments.
59
 *
60
 * @ingroup SimSupport
61
 */
62
class SIM_API cDisplayString
63
{
64
  private:
65
    enum { MAXARGS = 16 };  // maximum number of arguments per tag
66
67
    // holds one tag
68
    struct Tag {
69
       char *name;
70
       int numargs;
71
       char *args[MAXARGS];
72
       Tag() {name=NULL; numargs=0;}
73
    };
74
75
    char *buffer;       // holds pieces of display string (sliced with zeroes)
76
    char *bufferend;    // points to last byte of buffer allocated
77
    Tag *tags;          // table of tags
78
    int numtags;        // number of tags
79
80
    mutable char *dispstr; // cached copy of assembled display string
81
    mutable bool needsassemble; // if dispstr is up-to-date
82
83
    // needed for notifications
84
    cComponent *ownercomponent;
85
86
  private:
87
    // helper functions
88
    void doParse(const char *s);
89
    void doUpdateWith(const cDisplayString& ds);
90
    bool doSetTagArg(int tagindex, int index, const char *value);
91
    bool doSetTagArg(const char *tagname, int index, const char *value);
92
    int doInsertTag(const char *tagname, int atindex=0);
93
    bool doRemoveTag(int tagindex);
94
95
    void doParse();
96
    void assemble() const;
97
    void clearTags();
98
    bool pointsIntoBuffer(char *s) const {return s>=buffer && s<=bufferend;}
99
    static void strcatescaped(char *d, const char *s);
100
101
    // internal: called before the stored display string changes
102
    void beforeChange();
103
    // internal: called when the stored display string changes, and notifies Envir in turn.
104
    void afterChange();
105
106
  public:
107
    // internal:
108
    void setHostObject(cComponent *o) {ownercomponent=o;}
109
    void dump() const;
110
111
  public:
112
    /** @name Constructors, destructor. */
113
    //@{
114
115
    /**
116
     * Constructor.
117
     */
118
    cDisplayString();
119
120
    /**
121
     * Constructor. Throws an error if there was an error parsing the string.
122
     */
123
    cDisplayString(const char *dispstr);
124
125
    /**
126
     * Copy constructor.
127
     */
128
    cDisplayString(const cDisplayString& ds);
129
130
    /**
131
     * Destructor.
132
     */
133
    ~cDisplayString();
134
    //@}
135
136
    /** @name Assignment, conversions. */
137
    //@{
138
    /**
139
     * Assignment operator.
140
     */
141
    cDisplayString& operator=(const cDisplayString& ds) {parse(ds.str()); return *this;}
142
143
    /**
144
     * Conversion from string.
145
     */
146
    cDisplayString& operator=(const char *s)  {parse(s); return *this;}
147
148
    /**
149
     * Conversion to string.
150
     */
151
    operator const char *() const  {return str();}
152
    //@}
153
154
    /** @name Getting and setting the stored display string. */
155
    //@{
156
157
    /**
158
     * Returns the display string.
159
     */
160
    const char *str() const;
161
162
    /**
163
     * Same as parse().
164
     */
165
    void set(const char *displaystr)  {parse(displaystr);}
166
167
    /**
168
     * Sets the display string to the given value. Throws an error if there
169
     * was an error parsing the string.
170
     */
171
    void parse(const char *displaystr);
172
173
    /**
174
     * Update with the contents of another display string. Corresponding
175
     * elements from the new display string will overwrite existing values.
176
     */
177
    void updateWith(const cDisplayString& ds);
178
179
    /**
180
     * Update with the contents of another display string. Corresponding
181
     * elements from the new display string will overwrite existing values.
182
     */
183
    void updateWith(const char *s);
184
    //@}
185
186
    /** @name Manipulating tags by name. */
187
    //@{
188
189
    /**
190
     * Returns true if the stored display string contains the given tag.
191
     */
192
    bool containsTag(const char *tagname) const;
193
194
    /**
195
     * Returns the number of arguments a tag actually has in the display
196
     * string. The count includes empty arguments too. For example,
197
     * for the "x=8,,15,2;y=2" display string getNumArgs("x") returns 4,
198
     * and getNumArgs("y") returns 1. If the display string doesn't
199
     * contain the given tag, 0 is returned.
200
     */
201
    int getNumArgs(const char *tagname) const;
202
203
    /**
204
     * Returns pointer to the indexth argument of the given tag.
205
     * If the tag doesn't exist or the index is out of range,
206
     * empty string ("") is returned.
207
     */
208
    const char *getTagArg(const char *tagname, int index) const;
209
210
    /**
211
     * Sets an argument for the given tag. The value may be NULL pointer.
212
     * If index points beyond the last argument, the list of arguments will
213
     * be extended by inserting intervening empty arguments if necessary.
214
     *
215
     * The result is true if the operation was successful. False is returned
216
     * if the given tag doesn't exist, or index is invalid (negative or
217
     * greater than the maximum number of arguments, currently 16).
218
     */
219
    bool setTagArg(const char *tagname, int index, const char *value);
220
221
    /**
222
     * Convenience function to set a tag argument to a numeric value. Converts
223
     * 'value' to string, then calls setTagArg(const char *, int, const char *).
224
     */
225
    bool setTagArg(const char *tagname, int index, long value);
226
227
    /**
228
     * Removes the given tag with all its arguments from the display
229
     * string. The result is true if the tag was actually deleted
230
     * (it existed before), false otherwise.
231
     */
232
    bool removeTag(const char *tagname);
233
    //@}
234
235
    /** @name Manipulating tags by index. */
236
    //@{
237
238
    /**
239
     * Returns the number of tags in the display string. Tags are indexed
240
     * starting from 0.
241
     */
242
    int getNumTags() const;
243
244
    /**
245
     * Returns the name of the tag given with its index.
246
     * If the tag index is out of range, NULL is returned.
247
     */
248
    const char *getTagName(int tagindex) const;
249
250
    /**
251
     * Returns the tag index for the given tag, or -1 if the display string
252
     * does not contain the given tag.
253
     */
254
    int getTagIndex(const char *tagname) const;
255
256
    /**
257
     * Returns the number of arguments a tag actually has in the display
258
     * string. The count includes empty arguments too. For example,
259
     * for the "x=8,,15,2;y=2" display string getNumArgs("x") returns 4,
260
     * and getNumArgs("y") returns 1. If the display string doesn't
261
     * contain the given tag, 0 is returned.
262
     */
263
    int getNumArgs(int tagindex) const;
264
265
    /**
266
     * Returns pointer to the indexth argument of the given tag.
267
     * If the tag doesn't exist or the index is out of range,
268
     * NULL is returned.
269
     */
270
    const char *getTagArg(int tagindex, int index) const;
271
272
    /**
273
     * Sets an argument for the given tag. The value may be NULL pointer.
274
     * If index points beyond the last argument, the list of arguments will
275
     * be extended by inserting intervening empty arguments if necessary.
276
     *
277
     * The result is true if the operation was successful. False is returned
278
     * if the given tag doesn't exist, or index is invalid (negative or
279
     * greater than the maximum numer of arguments, currently 16).
280
     */
281
    bool setTagArg(int tagindex, int index, const char *value);
282
283
    /**
284
     * Inserts a tag into the display string, optionally at the given
285
     * index. If no index is given, the tag is inserted at the beginning
286
     * of the string. Return value is the index of the tag.
287
     * If the display string already contains a tag with the given tagname,
288
     * nothing is changed and the index of the existing tag is returned.
289
     */
290
    int insertTag(const char *tagname, int atindex=0);
291
292
    /**
293
     * Removes the given tag with all its arguments from the display
294
     * string. The result is true if the tag was actually deleted
295
     * (it existed before), false otherwise.
296
     */
297
    bool removeTag(int tagindex);
298
    //@}
299
};
300
301
302
NAMESPACE_END
303
304
305
#endif
306