OMNeT++ Simulation Library  6.0.3
cPar Class Reference

#include <cpar.h>

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, int, 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 delegate 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 be regarded as internal data structures, and should not be directly accessed from model code.

Inheritance diagram for cPar:
cObject

Public Member Functions

Redefined cObject methods
void operator= (const cPar &other)
 
virtual const char * getName () const override
 
virtual std::string str () const override
 
virtual cObjectgetOwner () const override
 
virtual void forEachChild (cVisitor *v) override
 
Setter functions. Note that overloaded assignment operators also exist.
cParsetBoolValue (bool b)
 
cParsetIntValue (intval_t l)
 
cParsetDoubleValue (double d)
 
cParsetStringValue (const char *s)
 
cParsetStringValue (const std::string &s)
 
cParsetObjectValue (cObject *object)
 
cParsetXMLValue (cXMLElement *node)
 
cParsetValue (const cValue &value)
 
cParsetExpression (cExpression *e, cComponent *evalcontext=nullptr)
 
void setEvaluationContext (cComponent *ctx)
 
Getter functions. Note that overloaded conversion operators also exist.
bool boolValue () const
 
intval_t intValue () const
 
double doubleValue () const
 
double doubleValueInUnit (const char *targetUnit) const
 
const char * getUnit () const
 
const char * stringValue () const
 
std::string stdstringValue () const
 
bool isEmptyString () const
 
cObjectobjectValue () const
 
cXMLElementxmlValue () const
 
cValue getValue () const
 
cExpressiongetExpression () const
 
cComponentgetEvaluationContext () const
 
Miscellaneous utility functions.
void convertToConst ()
 
void parse (const char *text, const char *baseDirectory=nullptr, FileLine loc=FileLine())
 
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 i)
 
cParoperator= (unsigned long i)
 
cParoperator= (long long i)
 
cParoperator= (unsigned long long i)
 
cParoperator= (double d)
 
cParoperator= (long double d)
 
cParoperator= (const char *s)
 
cParoperator= (const std::string &s)
 
cParoperator= (cObject *object)
 
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 long long () const
 
 operator unsigned long long () const
 
 operator double () const
 
 operator long double () const
 
 operator const char * () const
 
 operator std::string () const
 
 operator cObject * () const
 
 operator cXMLElement * () const
 
- Public Member Functions inherited from cObject
 cObject ()
 
 cObject (const cObject &other)=default
 
virtual ~cObject ()
 
virtual const char * getClassName () const
 
bool isName (const char *s) const
 
virtual const char * getFullName () const
 
virtual std::string getFullPath () const
 
virtual std::string getClassAndFullName () const
 
virtual std::string getClassAndFullPath () const
 
const cObjectgetThisPtr () const
 
virtual std::ostream & printOn (std::ostream &os) const
 
virtual cObjectdup () const
 
virtual void parsimPack (cCommBuffer *buffer) const
 
virtual void parsimUnpack (cCommBuffer *buffer)
 
virtual bool isOwnedObject () const
 
virtual bool isSoftOwner () const
 
cObjectfindObject (const char *name, bool deep=true)
 
virtual cClassDescriptorgetDescriptor () const
 
void copyNotSupported () const
 

Type, flags.

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

Additional Inherited Members

- Protected Member Functions inherited from cObject
virtual void take (cOwnedObject *obj)
 
virtual void drop (cOwnedObject *obj)
 
void dropAndDelete (cOwnedObject *obj)
 

Member Function Documentation

◆ operator=() [1/18]

void operator= ( const cPar other)

Assignment operator.

◆ getName()

virtual const char* getName ( ) const
overridevirtual

Returns the parameter name.

Reimplemented from cObject.

◆ str()

virtual std::string str ( ) const
overridevirtual

Returns the value in text form.

Reimplemented from cObject.

◆ getOwner()

virtual cObject* getOwner ( ) const
overridevirtual

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.

◆ forEachChild()

virtual void forEachChild ( cVisitor v)
overridevirtual

Calls v->visit(this) for contained objects. See cObject for more details.

Reimplemented from cObject.

◆ getType()

Type getType ( ) const

Returns the parameter type

◆ getTypeName()

static const char* getTypeName ( Type  t)
static

Returns the given type as a string.

◆ isNumeric()

bool isNumeric ( ) const

Returns true if the stored value is of a numeric type.

◆ isVolatile()

bool isVolatile ( ) const

Returns true if this parameter is marked in the NED file as "volatile". This flag affects the operation of setExpression().

◆ isMutable()

bool isMutable ( ) const

Returns true if this parameter is marked in the NED file as mutable. A non-mutable parameter cannot have its value changed.

◆ isExpression()

bool 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.)

◆ isShared()

bool 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.

◆ isSet()

bool 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.

◆ containsValue()

bool 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.

◆ getProperties()

cProperties* getProperties ( ) const

Return the properties for this parameter. Properties cannot be changed at runtime.

◆ setBoolValue()

cPar& setBoolValue ( bool  b)

Sets the value to the given bool value.

◆ setIntValue()

cPar& setIntValue ( intval_t  l)

Sets the value to the given integer value.

◆ setDoubleValue()

cPar& setDoubleValue ( double  d)

Sets the value to the given double value.

◆ setStringValue() [1/2]

cPar& setStringValue ( const char *  s)

Sets the value to the given string value. The cPar will make its own copy of the string. nullptr is also accepted and treated as an empty string.

◆ setStringValue() [2/2]

cPar& setStringValue ( const std::string &  s)
inline

Sets the value to the given string value.

References cPar::setStringValue().

Referenced by cPar::setStringValue().

◆ setObjectValue()

cPar& setObjectValue ( cObject object)

Sets the value to the given object.

◆ setXMLValue()

cPar& setXMLValue ( cXMLElement node)

Sets the value to the given cXMLElement.

◆ setValue()

cPar& setValue ( const cValue value)

Sets the parameter's value. This method invokes the value setter method (setBoolValue(), setIntValue(), etc.) that corresponds to the parameter's type with the value in the cValue object. If the value's type doesn't match the parameter's type, an error is raised.

◆ setExpression()

cPar& setExpression ( cExpression e,
cComponent evalcontext = nullptr 
)

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 nullptr, 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()

◆ setEvaluationContext()

void 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()

◆ boolValue()

bool boolValue ( ) const

Returns value as a boolean. The cPar type must be BOOL.

◆ intValue()

intval_t intValue ( ) const

Returns value as intval_t. The cPar type must be INT. Note: Implicit conversion from DOUBLE is intentionally missing.

◆ doubleValue()

double doubleValue ( ) const

Returns value as double. The cPar type must be DOUBLE. Note: Implicit conversion from INT is intentionally missing.

◆ doubleValueInUnit()

double doubleValueInUnit ( const char *  targetUnit) const

Returns the numeric value as a double converted to the given unit. If the current unit cannot be converted to the given one, an error will be thrown. The type must be DOUBLE or INT.

◆ getUnit()

const char* getUnit ( ) const

Returns the parameter's unit ("s", "mW", "Hz", "bps", etc) as declared with the @unit property of the parameter in NED, or nullptr if no unit was specified. Unit is only valid for INT and DOUBLE types.

◆ stringValue()

const char* 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().

◆ stdstringValue()

std::string stdstringValue ( ) const

Returns value as string. The cPar type must be STRING.

◆ isEmptyString()

bool isEmptyString ( ) const
inline

Convenience method: returns true of the parameter contains an empty string. The cPar type must be STRING.

◆ objectValue()

cObject* objectValue ( ) const

Returns the value as object. The cPar type must be OBJECT. The ownership of the object remains with the cPar. It is not possible for the user to take ownership of the object, but creating a copy via dup() is an option.

Lifetime of the returned objects:

The returned object pointer is stored within the parameter. A setObjectValue() call will delete the previous object (given that the parameter owns the object).

Note: If the object parameter refers to an object which it doesn't own, it never deletes the object. If an object doesn't know its owner (it is a cObject but not a cOwnedObject), it is considered owned.

If the parameter is declared volatile (see isVolatile()), the returned object pointer (the pointer of the object which was produced by evaluating the expression) is stored. Upon the next objectValue() call, the previously returned object is deleted (given that the parameter owns the object), and replaced with the new object.

Note that parameters may be shared under the hood. This means that a previously returned object may also be deleted if another module's similar volatile parameter is evaluated using objectValue().

Therefore, the lifetime of returned objects should be considered very limited. In simple terms, the object should either be used only locally and then its pointer forgotten, or be cloned using dup() for long-term use.

◆ xmlValue()

cXMLElement* 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).

◆ getValue()

cValue getValue ( ) const

Generic access to the parameter's value. This method delegates to the value accessor method (boolValue(), intValue(), etc.) that corresponds to the parameter's type, and returns the result.

◆ getExpression()

cExpression* getExpression ( ) const

Returns pointer to the expression stored by the object, or nullptr.

◆ getEvaluationContext()

cComponent* 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()

◆ convertToConst()

void convertToConst ( )
inline

For non-const values, replaces the stored expression with its evaluation.

◆ parse()

void parse ( const char *  text,
const char *  baseDirectory = nullptr,
FileLine  loc = FileLine() 
)

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".

◆ operator=() [2/18]

cPar& operator= ( bool  b)
inline

Equivalent to setBoolValue().

◆ operator=() [3/18]

cPar& operator= ( char  c)
inline

Delegates to setIntValue().

◆ operator=() [4/18]

cPar& operator= ( unsigned char  c)
inline

Delegates to setIntValue().

◆ operator=() [5/18]

cPar& operator= ( int  i)
inline

Delegates to setIntValue().

◆ operator=() [6/18]

cPar& operator= ( unsigned int  i)
inline

Delegates to setIntValue().

◆ operator=() [7/18]

cPar& operator= ( short  i)
inline

Delegates to setIntValue().

◆ operator=() [8/18]

cPar& operator= ( unsigned short  i)
inline

Delegates to setIntValue().

◆ operator=() [9/18]

cPar& operator= ( long  i)
inline

Equivalent to setIntValue().

◆ operator=() [10/18]

cPar& operator= ( unsigned long  i)
inline

Delegates to setIntValue().

◆ operator=() [11/18]

cPar& operator= ( long long  i)
inline

Delegates to setIntValue().

◆ operator=() [12/18]

cPar& operator= ( unsigned long long  i)
inline

Delegates to setIntValue().

◆ operator=() [13/18]

cPar& operator= ( double  d)
inline

Equivalent to setDoubleValue().

◆ operator=() [14/18]

cPar& operator= ( long double  d)
inline

Converts the argument to double, and calls setDoubleValue().

◆ operator=() [15/18]

cPar& operator= ( const char *  s)
inline

Equivalent to setStringValue().

◆ operator=() [16/18]

cPar& operator= ( const std::string &  s)
inline

Equivalent to setStringValue().

◆ operator=() [17/18]

cPar& operator= ( cObject object)
inline

Equivalent to setObjectValue().

◆ operator=() [18/18]

cPar& operator= ( cXMLElement node)
inline

Equivalent to setXMLValue().

◆ operator bool()

operator bool ( ) const
inline

Equivalent to boolValue().

◆ operator char()

operator char ( ) const
inline

Calls intValue() and converts the result to char. An exception is thrown if the conversion would result in a data loss,

◆ operator unsigned char()

operator unsigned char ( ) const
inline

Calls intValue() and converts the result to unsigned char. An exception is thrown if the conversion would result in a data loss,

◆ operator int()

operator int ( ) const
inline

Calls intValue() and converts the result to int. An exception is thrown if the conversion would result in a data loss,

◆ operator unsigned int()

operator unsigned int ( ) const
inline

Calls intValue() and converts the result to unsigned int. An exception is thrown if the conversion would result in a data loss,

◆ operator short()

operator short ( ) const
inline

Calls intValue() and converts the result to short. An exception is thrown if the conversion would result in a data loss,

◆ operator unsigned short()

operator unsigned short ( ) const
inline

Calls intValue() and converts the result to unsigned short. An exception is thrown if the conversion would result in a data loss,

◆ operator long()

operator long ( ) const
inline

Calls intValue() and converts the result to long. An exception is thrown if the conversion would result in a data loss,

◆ operator unsigned long()

operator unsigned long ( ) const
inline

Calls intValue() and converts the result to unsigned long. An exception is thrown if the conversion would result in a data loss,

◆ operator long long()

operator long long ( ) const
inline

Calls intValue() and converts the result to long long. An exception is thrown if the conversion would result in a data loss,

◆ operator unsigned long long()

operator unsigned long long ( ) const
inline

Calls intValue() and converts the result to unsigned long long. An exception is thrown if the conversion would result in a data loss,

◆ operator double()

operator double ( ) const
inline

Equivalent to doubleValue().

◆ operator long double()

operator long double ( ) const
inline

Calls doubleValue() and converts the result to long double.

◆ operator const char *()

operator const char * ( ) const
inline

Equivalent to stringValue().

◆ operator std::string()

operator std::string ( ) const
inline

Equivalent to stdstringValue().

◆ operator cObject *()

operator cObject * ( ) const
inline

Equivalent to objectValue().

◆ operator cXMLElement *()

operator cXMLElement * ( ) const
inline

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


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