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

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 (intval_t l)

cPar &	setDoubleValue (double d)

cPar &	setStringValue (const char *s)

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

cPar &	setObjectValue (cObject *object)

cPar &	setXMLValue (cXMLElement *node)

cPar &	setValue (const cValue &value)

cPar &	setExpression (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

cObject *	objectValue () const

cXMLElement *	xmlValue () const

cValue	getValue () const

cExpression *	getExpression () const

cComponent *	getEvaluationContext () const

Miscellaneous utility functions.
void	convertToConst ()

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

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= (cObject *object)

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 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 cObject *	getThisPtr () const

virtual std::ostream &	printOn (std::ostream &os) const

virtual cObject *	dup () const

virtual void	parsimPack (cCommBuffer *buffer) const

virtual void	parsimUnpack (cCommBuffer *buffer)

virtual bool	isOwnedObject () const

virtual bool	isSoftOwner () const

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

virtual cClassDescriptor *	getDescriptor () 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

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

cpar.h

Description

Public Member Functions

Type, flags.

Additional Inherited Members

Member Function Documentation

◆ operator=() [1/18]

◆ getName()

◆ str()

◆ getOwner()

◆ forEachChild()

◆ getType()

◆ getTypeName()

◆ isNumeric()

◆ isVolatile()

◆ isMutable()

◆ isExpression()

◆ isShared()

◆ isSet()

◆ containsValue()

◆ getProperties()

◆ setBoolValue()

◆ setIntValue()

◆ setDoubleValue()

◆ setStringValue() [1/2]

◆ setStringValue() [2/2]

◆ setObjectValue()

◆ setXMLValue()

◆ setValue()

◆ setExpression()

◆ setEvaluationContext()

◆ boolValue()

◆ intValue()

◆ doubleValue()

◆ doubleValueInUnit()

◆ getUnit()

◆ stringValue()

◆ stdstringValue()

◆ isEmptyString()

◆ objectValue()

◆ xmlValue()

◆ getValue()

◆ getExpression()

◆ getEvaluationContext()

◆ convertToConst()

◆ parse()

◆ operator=() [2/18]

◆ operator=() [3/18]

◆ operator=() [4/18]

◆ operator=() [5/18]

◆ operator=() [6/18]

◆ operator=() [7/18]

◆ operator=() [8/18]

◆ operator=() [9/18]

◆ operator=() [10/18]

◆ operator=() [11/18]

◆ operator=() [12/18]

◆ operator=() [13/18]

◆ operator=() [14/18]

◆ operator=() [15/18]

◆ operator=() [16/18]

◆ operator=() [17/18]

◆ operator=() [18/18]

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

◆ operator cXMLElement *()