cPar Class Reference
[Simulation core classes]

Represents a module or channel parameter. More...

#include <cpar.h>

Inheritance diagram for cPar:

List of all members.

Public Member Functions

virtual ~cPar ()
virtual const char * getName () const
virtual std::string info () const
virtual std::string detailedInfo () const
virtual cObjectgetOwner () const
void operator= (const cPar &other)
Setter functions. Note that overloaded assignment operators also exist.

cParsetBoolValue (bool b)
cParsetLongValue (long l)
cParsetDoubleValue (double d)
cParsetStringValue (const char *s)
cParsetStringValue (const std::string &s)
cParsetXMLValue (cXMLElement *node)
cParsetExpression (cExpression *e, cComponent *evalcontext=NULL)
void setEvaluationContext (cComponent *ctx)
Getter functions. Note that overloaded conversion operators also exist.

bool boolValue () const
long longValue () const
double doubleValue () const
const char * getUnit () const
const char * stringValue () const
std::string stdstringValue () const
cXMLElementxmlValue () const
cExpressiongetExpression () const
cComponentgetEvaluationContext () const
Miscellaneous utility functions.

void read ()
void convertToConst ()
std::string str () const
void parse (const char *text)
Overloaded assignment and conversion operators.

cParoperator= (bool b)
cParoperator= (char c)
cParoperator= (unsigned char c)
cParoperator= (int i)
cParoperator= (unsigned int i)
cParoperator= (short i)
cParoperator= (unsigned short i)
cParoperator= (long l)
cParoperator= (unsigned long l)
cParoperator= (double d)
cParoperator= (long double d)
cParoperator= (const char *s)
cParoperator= (const std::string &s)
cParoperator= (cXMLElement *node)
 operator bool () const
 operator char () const
 operator unsigned char () const
 operator int () const
 operator unsigned int () const
 operator short () const
 operator unsigned short () const
 operator long () const
 operator unsigned long () const
 operator double () const
 operator long double () const
 operator const char * () const
 operator std::string () const
 operator cXMLElement * () const


class cComponent

Type, flags.

Type getType () const
bool isNumeric () const
bool isVolatile () const
bool isExpression () const
bool isShared () const
bool isSet () const
bool containsValue () const
cPropertiesgetProperties () const
static const char * getTypeName (Type t)

Detailed Description

Represents a module or channel parameter.

When a module or channel is created, parameter objects are added automatically, based on the NED declaration of the module/channel. It is not possible to create further parameters (or to remove parameters) at runtime. This is enforced by the cPar constructor being private.

Parameters get their initial values automatically, from the NED declarations and the configuration. It is possible to change the parameter value during runtime (see various setter methods and operator='s), but not the type of the parameter (see getType()). The type correspond to NED types (bool, double, long, string, xml), and cannot be changed at runtime.

The module or channel object can get notified when a parameter is changed; one has to override cComponent::handleParameterChange() for that.

Note: In earlier versions of OMNeT++, cPar could be used as a general value storage object, and attached to cMessages as well. From the 4.0 version, simulation models should use cMsgPar for that.

Implementation note: from the 4.0 version, almost all methods of cPar delegates to an internal cParImpl object, which actually stores the value, and generally does the real job. This was done to allow sharing parameter objects which have the same name, same value, etc. among module/channel instances. This significantly reduces memory consumption of most simulation models. Because cPar is just a thin wrapper around cParImpl, cPar is not meant for subclassing, and none if its methods are virtual. cParImpl and subclasses should also be regarded as internal data structures, and they should not be directly accessed or manipulated from model code.

Member Function Documentation

bool cPar::boolValue (  )  const

Returns value as a boolean.

The cPar type must be BOOL.

bool cPar::containsValue (  )  const

Returns true if the parameter is set (see isSet()) or contains a default value, and false otherwise.

Parameters of an already initialized module or channel are guaranteed to be assigned, so this method will return true for them.

double cPar::doubleValue (  )  const

Returns value as double.

The cPar type must be LONG or DOUBLE.

cComponent* cPar::getEvaluationContext (  )  const [inline]

If the parameter contains an expression, this method returns the module or channel in the context of which the expression will be evaluated.

(The context affects the resolution of parameter references, and NED operators like index or sizeof().) If the parameter does not contain an expression, the return value is undefined.

See also:
isExpression(), setEvaluationContext()
virtual cObject* cPar::getOwner (  )  const [virtual]

Returns the component (module/channel) this parameter belongs to.

Note: return type is cObject only for technical reasons, it can be safely cast to cComponent.

Reimplemented from cObject.

cProperties* cPar::getProperties (  )  const

Return the properties for this parameter.

Properties cannot be changed at runtime.

const char* cPar::getUnit (  )  const

Returns the parameter's unit ("s", "mW", "Hz", "bps", etc), as declared with the @unit property of the parameter in NED, or NULL if no unit was specified.

Unit is only valid for LONG and DOUBLE types.

virtual std::string cPar::info (  )  const [virtual]

Returns a one-line description of the object.

See also:

Reimplemented from cObject.

bool cPar::isExpression (  )  const

Returns false if the stored value is a constant, and true if it is an expression.

(It is not examined whether the expression yields a constant value.)

bool cPar::isSet (  )  const

Returns true if the parameter is assigned a value, and false otherwise.

Parameters of an already initialized module or channel are guaranteed to assigned, so this method will return true for them.

bool cPar::isShared (  )  const

Returns true if the parameter value expression is shared among several modules to save memory.

This flag is purely informational, and whether a parameter is shared or not does not affect operation at all.

bool cPar::isVolatile (  )  const

Returns true if this parameter is marked in the NED file as "volatile".

This flag affects the operation of setExpression().

long cPar::longValue (  )  const

Returns value as long.

The cPar type must be LONG or DOUBLE.

cPar::operator cXMLElement * (  )  const [inline]

Equivalent to xmlValue().

NOTE: The lifetime of the returned object tree is limited; see xmlValue() for details.

void cPar::parse ( const char *  text  ) 

Converts the value from string, and stores the result.

If the text cannot be parsed, an exception is thrown, which can be caught as std::runtime_error& if necessary.

Note: this method understands expressions too, but does NOT handle the special values "default" and "ask".

void cPar::read (  ) 

This method does the final touches on the parameter.

It is invoked at some point on all parameter objects before we start the simulation.

  • if the parameter is not set, gets the value from omnetpp.ini or interactively from the user, or sets the default value.
  • if the parameter is volatile but contains "const" subexpressions, these parts are converted to a constant value.
void cPar::setEvaluationContext ( cComponent ctx  )  [inline]

If the parameter contains an expression (see isExpression()), this method sets the evaluation context for the expression.

See also:
getEvaluationContext(), isExpression(), setExpression()
cPar& cPar::setExpression ( cExpression e,
cComponent evalcontext = NULL 

Sets the value to the given expression.

This object will assume the responsibility to delete the expression object.

The evalcontext parameter determines the module or channel in the context of which the expression will be evaluated. If evalcontext is NULL, the owner of this parameter will be used.

Note: if the parameter is marked as non-volatile (isVolatile()==false), one should not set an expression as value. This is not enforced by cPar though.

See also:
getOwner(), getEvaluationContext(), setEvaluationContext()
cPar& cPar::setStringValue ( const char *  s  ) 

Sets the value to the given string value.

The cPar will make its own copy of the string. NULL is also accepted and treated as an empty string.

std::string cPar::stdstringValue (  )  const

Returns value as string.

The cPar type must be STRING.

Referenced by operator std::string().

const char* cPar::stringValue (  )  const

Returns value as const char *.

The cPar type must be STRING. This method may only be invoked when the parameter's value is a string constant and not the result of expression evaluation, otherwise an error is thrown. This practically means this method cannot be used on parameters declared as "volatile string" in NED; they can only be accessed using stdstringValue().

cXMLElement* cPar::xmlValue (  )  const

Returns value as pointer to cXMLElement.

The cPar type must be XML.

The lifetime of the returned object tree is undefined, but it is valid at least until the end of the current simulation event or initialize() call. Modules are expected to process their XML configurations at once (within one event or within initialize()), and not hang on to pointers returned from this method. The reason for the limited lifetime is that this method may return pointers to objects stored in an internal XML document cache, and the simulation kernel reserves the right to discard cached XML documents at any time to free up memory, and re-load them on demand (i.e. when xmlValue() is called again).

The documentation for this class was generated from the following file:
Generated on Fri Mar 7 17:19:41 2014 for OMNeT++ Simulation Library by  doxygen 1.6.3