Project

General

Profile

Statistics
| Branch: | Revision:

root / src / common / displaystring.h @ 81ad8b66

History | View | Annotate | Download (8.28 KB)

1 01873262 Georg Kunz
//==========================================================================
2
//   DISPLAYSTRING.H  - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//  Author: Andras Varga
7
//
8
//==========================================================================
9
10
/*--------------------------------------------------------------*
11
  Copyright (C) 2006-2008 OpenSim Ltd.
12

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