OMNeT++ API 6.1
Discrete Event Simulation Library
List of all members
cDisplayString Class Reference
Model Components

Description

Represents a display string.

Display strings are used to control the graphical presentation of network elements when a graphical runtime environment is used.

A display string consist of several named tags, where each tag may have several arguments (parameters). The syntax: "tag1=value1,val2,val3;tag2=val4,val5".

The special characters ",", ";", and "=" may be included in tag argument values by preceding (escaping) them with a "\". A literal backslash may be written as "\\".

Tag values may also contain expressions in the following form: "${expression}". The three special characters mentioned above lose their meaning within these expressions even without escaping. A literal dollar sign may be written as "$$".

This class facilitates tasks such as adding new tags, adding arguments to existing tags, removing tags or replacing arguments. The internal storage method allows very fast operation; it will generally be faster than direct string manipulation.

The this class does not know about the meaning or semantics of various display string tags, nor does it care about what is written in the embedded expressions, it merely parses the string as data elements separated by semicolons, equal signs and commas.

An example: 

  cDisplayString dispstr("a=1,2;p=alpha,,3");
  dispstr.insertTag("x");
  dispstr.setTagArg("x",0,"joe");
  dispstr.setTagArg("x",2,"jim");
  dispstr.setTagArg("p",0,"beta");
  EV << dispstr.str();  // result: "x=joe,,jim;a=1,2;p=beta,,3"

Limitation: a tag may have at most 16 arguments.

Public Member Functions

Constructors, destructor.
 cDisplayString ()
 
 cDisplayString (const char *dispstr)
 
 cDisplayString (const cDisplayString &ds)
 
 ~cDisplayString ()
 
Assignment, conversions.
cDisplayString & operator= (const cDisplayString &ds)
 
cDisplayString & operator= (const char *s)
 
 operator const char * () const
 
Getting and setting the stored display string.
const char * str () const
 
void set (const char *displaystr)
 
void parse (const char *displaystr)
 
void updateWith (const cDisplayString &ds)
 
void updateWith (const char *s)
 
Manipulating tags by name.
bool containsTag (const char *tagname) const
 
int getNumArgs (const char *tagname) const
 
const char * getTagArg (const char *tagname, int index) const
 
bool setTagArg (const char *tagname, int index, const char *value)
 
bool setTagArg (const char *tagname, int index, long value)
 
bool removeTag (const char *tagname)
 
Manipulating tags by index.
int getNumTags () const
 
const char * getTagName (int tagindex) const
 
int getTagIndex (const char *tagname) const
 
int getNumArgs (int tagindex) const
 
const char * getTagArg (int tagindex, int index) const
 
bool setTagArg (int tagindex, int index, const char *value)
 
int insertTag (const char *tagname, int atindex=0)
 
bool removeTag (int tagindex)
 

Constructor & Destructor Documentation

◆ cDisplayString() [1/3]

cDisplayString ( )
inline

Constructor.

◆ cDisplayString() [2/3]

cDisplayString ( const char *  dispstr)

Constructor that initializes the object with the given string. See parse() for details. Throws an error if there was an error parsing the string.

◆ cDisplayString() [3/3]

cDisplayString ( const cDisplayString &  ds)

Copy constructor.

◆ ~cDisplayString()

~cDisplayString ( )

Destructor.

Member Function Documentation

◆ operator=() [1/2]

cDisplayString& operator= ( const cDisplayString &  ds)

Assignment operator.

◆ operator=() [2/2]

cDisplayString& operator= ( const char *  s)
inline

Conversion from string.

◆ operator const char *()

operator const char * ( ) const
inline

Conversion to string.

◆ str()

const char* str ( ) const

Returns the display string.

◆ set()

void set ( const char *  displaystr)
inline

Same as parse().

◆ parse()

void parse ( const char *  displaystr)

Sets the display string to the given value. Throws an error if there was an error parsing the string.

If a tag argument contains a "," or ";", it needs to be escaped with a backslash to take away its special meaning. Other backslashes are are ignored (i.e. not stored). To add a backslash into a tag argument, it needs to be duplicated. Example: the 't=foo\,bar\;bs=\' string (i.e. the "t=foo\\,bar\\;bs=\\\\" C++ string constant) will be parsed as a "t" tag having the single argument "foo,bar;bs=\".

◆ updateWith() [1/2]

void updateWith ( const cDisplayString &  ds)

Update with the contents of another display string. Corresponding elements from the new display string will overwrite existing values.

◆ updateWith() [2/2]

void updateWith ( const char *  s)

Update with the contents of another display string. Corresponding elements from the new display string will overwrite existing values.

◆ containsTag()

bool containsTag ( const char *  tagname) const

Returns true if the stored display string contains the given tag.

◆ getNumArgs() [1/2]

int getNumArgs ( const char *  tagname) const

Returns the number of arguments a tag actually has in the display string. The count includes empty arguments too. For example, for the "x=8,,15,2;y=2" display string getNumArgs("x") returns 4, and getNumArgs("y") returns 1. If the display string doesn't contain the given tag, 0 is returned.

◆ getTagArg() [1/2]

const char* getTagArg ( const char *  tagname,
int  index 
) const

Returns pointer to the indexth argument of the given tag. If the tag doesn't exist or the index is out of range, empty string ("") is returned.

◆ setTagArg() [1/3]

bool setTagArg ( const char *  tagname,
int  index,
const char *  value 
)

Sets an argument for the given tag. The value may be nullptr. If index points beyond the last argument, the list of arguments will be extended by inserting intervening empty arguments if necessary.

The result is true if the operation was successful. False is returned if the given tag doesn't exist, or index is invalid (negative or greater than the maximum number of arguments, currently 16).

◆ setTagArg() [2/3]

bool setTagArg ( const char *  tagname,
int  index,
long  value 
)

Convenience function to set a tag argument to a numeric value. Converts 'value' to string, then calls setTagArg(const char *, int, const char *).

◆ removeTag() [1/2]

bool removeTag ( const char *  tagname)

Removes the given tag with all its arguments from the display string. The result is true if the tag was actually deleted (it existed before), false otherwise.

◆ getNumTags()

int getNumTags ( ) const

Returns the number of tags in the display string. Tags are indexed starting from 0.

◆ getTagName()

const char* getTagName ( int  tagindex) const

Returns the name of the tag given with its index. If the tag index is out of range, nullptr is returned.

◆ getTagIndex()

int getTagIndex ( const char *  tagname) const

Returns the tag index for the given tag, or -1 if the display string does not contain the given tag.

◆ getNumArgs() [2/2]

int getNumArgs ( int  tagindex) const

Returns the number of arguments a tag actually has in the display string. The count includes empty arguments too. For example, for the "x=8,,15,2;y=2" display string getNumArgs("x") returns 4, and getNumArgs("y") returns 1. If the display string doesn't contain the given tag, 0 is returned.

◆ getTagArg() [2/2]

const char* getTagArg ( int  tagindex,
int  index 
) const

Returns pointer to the indexth argument of the given tag. If the tag doesn't exist or the index is out of range, nullptr is returned.

◆ setTagArg() [3/3]

bool setTagArg ( int  tagindex,
int  index,
const char *  value 
)

Sets an argument for the given tag. The value may be nullptr. If index points beyond the last argument, the list of arguments will be extended by inserting intervening empty arguments if necessary.

The result is true if the operation was successful. False is returned if the given tag doesn't exist, or index is invalid (negative or greater than the maximum numer of arguments, currently 16).

◆ insertTag()

int insertTag ( const char *  tagname,
int  atindex = 0 
)

Inserts a tag into the display string, optionally at the given index. If no index is given, the tag is inserted at the beginning of the string. Return value is the index of the tag. If the display string already contains a tag with the given tagname, nothing is changed and the index of the existing tag is returned.

◆ removeTag() [2/2]

bool removeTag ( int  tagindex)

Removes the given tag with all its arguments from the display string. The result is true if the tag was actually deleted (it existed before), false otherwise.

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