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

Inheritance diagram for cPar:

Public Member Functions
Redefined cObject methods
void	operator= (const cPar &other)

virtual const char *	getName () const override

virtual std::string	str () const override

virtual cObject *	getOwner () const override

virtual void	forEachChild (cVisitor *v) override

Setter functions. Note that overloaded assignment operators also exist.
cPar &	setBoolValue (bool b)

cPar &	setIntValue (intpar_t l)

_OPPDEPRECATED cPar &	setLongValue (intpar_t l)

cPar &	setDoubleValue (double d)

cPar &	setStringValue (const char *s)

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

cPar &	setXMLValue (cXMLElement *node)

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

void	setEvaluationContext (cComponent *ctx)

Getter functions. Note that overloaded conversion operators also exist.
bool	boolValue () const

intpar_t	intValue () const

_OPPDEPRECATED intpar_t	longValue () 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

cXMLElement *	xmlValue () const

cExpression *	getExpression () const

cComponent *	getEvaluationContext () const

Miscellaneous utility functions.
void	convertToConst ()

void	parse (const char *text)

Overloaded assignment and conversion operators.
cPar &	operator= (bool b)

cPar &	operator= (char c)

cPar &	operator= (unsigned char c)

cPar &	operator= (int i)

cPar &	operator= (unsigned int i)

cPar &	operator= (short i)

cPar &	operator= (unsigned short i)

cPar &	operator= (long i)

cPar &	operator= (unsigned long i)

cPar &	operator= (long long i)

cPar &	operator= (unsigned long long i)

cPar &	operator= (double d)

cPar &	operator= (long double d)

cPar &	operator= (const char *s)

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

cPar &	operator= (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 cXMLElement * () const

Public Member Functions inherited from cObject
	cObject ()

	cObject (const cObject &other)

virtual	~cObject ()

virtual const char *	getClassName () const

bool	isName (const char *s) const

virtual const char *	getFullName () const

virtual std::string	getFullPath () const

const cObject *	getThisPtr () const

virtual _OPPDEPRECATED std::string	info () const

virtual _OPPDEPRECATED std::string	detailedInfo () const

virtual cObject *	dup () const

virtual void	parsimPack (cCommBuffer *buffer) const

virtual void	parsimUnpack (cCommBuffer *buffer)

virtual bool	isOwnedObject () const

cObject *	findObject (const char *name, bool deep=true)

void	copyNotSupported () const

Type, flags.
Type	getType () const

bool	isNumeric () const

bool	isVolatile () const

bool	isExpression () const

bool	isShared () const

bool	isSet () const

bool	containsValue () const

cProperties *	getProperties () 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/17]

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

◆ 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 ( intpar_t l )

Sets the value to the given integer value.

◆ setLongValue()

_OPPDEPRECATED cPar& setLongValue ( intpar_t l )

inline

Compatibility method, delegates to setIntValue().

◆ 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().

◆ setXMLValue()

cPar& setXMLValue ( cXMLElement * node )

Sets the value to the given cXMLElement.

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

intpar_t intValue ( ) const

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

◆ longValue()

_OPPDEPRECATED intpar_t longValue ( ) const

inline

Compatibility method, delegates to intValue().

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

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

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

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

◆ parse()

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

◆ operator=() [2/17]

cPar& operator= ( bool b )

inline

Equivalent to setBoolValue().

◆ operator=() [3/17]

cPar& operator= ( char c )

inline

Delegates to setIntValue().

◆ operator=() [4/17]

cPar& operator= ( unsigned char c )

inline

Delegates to setIntValue().

◆ operator=() [5/17]

cPar& operator= ( int i )

inline

Delegates to setIntValue().

◆ operator=() [6/17]

cPar& operator= ( unsigned int i )

inline

Delegates to setIntValue().

◆ operator=() [7/17]

cPar& operator= ( short i )

inline

Delegates to setIntValue().

◆ operator=() [8/17]

cPar& operator= ( unsigned short i )

inline

Delegates to setIntValue().

◆ operator=() [9/17]

cPar& operator= ( long i )

inline

Equivalent to setIntValue().

◆ operator=() [10/17]

cPar& operator= ( unsigned long i )

inline

Delegates to setIntValue().

◆ operator=() [11/17]

cPar& operator= ( long long i )

inline

Delegates to setIntValue().

◆ operator=() [12/17]

cPar& operator= ( unsigned long long i )

inline

Delegates to setIntValue().

◆ operator=() [13/17]

cPar& operator= ( double d )

inline

Equivalent to setDoubleValue().

◆ operator=() [14/17]

cPar& operator= ( long double d )

inline

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

◆ operator=() [15/17]

cPar& operator= ( const char * s )

inline

Equivalent to setStringValue().

◆ operator=() [16/17]

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

inline

Equivalent to setStringValue().

◆ operator=() [17/17]

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,

References omnetpp::checked_int_cast().

◆ 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,

References omnetpp::checked_int_cast().

◆ 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,

References omnetpp::checked_int_cast().

◆ 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,

References omnetpp::checked_int_cast().

◆ 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,

References omnetpp::checked_int_cast().

◆ 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,

References omnetpp::checked_int_cast().

◆ 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,

References omnetpp::checked_int_cast().

◆ 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,

References omnetpp::checked_int_cast().

◆ 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,

References omnetpp::checked_int_cast().

◆ 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,

References omnetpp::checked_int_cast().

◆ 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 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:

cpar.h

Description

Public Member Functions

Type, flags.

Additional Inherited Members

Member Function Documentation

◆ operator=() [1/17]

◆ getName()

◆ str()

◆ getOwner()

◆ forEachChild()

◆ getType()

◆ getTypeName()

◆ isNumeric()

◆ isVolatile()

◆ isExpression()

◆ isShared()

◆ isSet()

◆ containsValue()

◆ getProperties()

◆ setBoolValue()

◆ setIntValue()

◆ setLongValue()

◆ setDoubleValue()

◆ setStringValue() [1/2]

◆ setStringValue() [2/2]

◆ setXMLValue()

◆ setExpression()

◆ setEvaluationContext()

◆ boolValue()

◆ intValue()

◆ longValue()

◆ doubleValue()

◆ doubleValueInUnit()

◆ getUnit()

◆ stringValue()

◆ stdstringValue()

◆ isEmptyString()

◆ xmlValue()

◆ getExpression()

◆ getEvaluationContext()

◆ convertToConst()

◆ parse()

◆ operator=() [2/17]

◆ operator=() [3/17]

◆ operator=() [4/17]

◆ operator=() [5/17]

◆ operator=() [6/17]

◆ operator=() [7/17]

◆ operator=() [8/17]

◆ operator=() [9/17]

◆ operator=() [10/17]

◆ operator=() [11/17]

◆ operator=() [12/17]

◆ operator=() [13/17]

◆ operator=() [14/17]

◆ operator=() [15/17]

◆ operator=() [16/17]

◆ operator=() [17/17]

◆ operator bool()

◆ operator char()

◆ operator unsigned char()

◆ operator int()

◆ operator unsigned int()

◆ operator short()

◆ operator unsigned short()

◆ operator long()

◆ operator unsigned long()

◆ operator long long()

◆ operator unsigned long long()

◆ operator double()

◆ operator long double()

◆ operator const char *()

◆ operator std::string()

◆ operator cXMLElement *()