# cPar Class Reference
[Simulation core classes]

`#include <cpar.h>`

Inheritance diagram for cPar:

List of all members.

## Detailed Description

Parameter class.

cPar is used for module parameters, and its instances can also be attached to cMessage objects.

cPar supports several data types. Data types are identified by type characters. The current data type is returned by type().

- basic types: S string, B bool, L long, D double
- F math function (MathFuncNoArgs,MathFunc1Args,etc),
- X reverse Polish expression (array of ExprElem objects),
- C compiled expression (subclassed from cDoubleExpression),
- T distribution from a cStatistic,
- P pointer to cObject,
- I indirection (refers to another cPar)
- M XML element (pointer to a cXMLElement)

For all types, an input flag can be set. In this case, the user will be asked to enter the value when the object's value is first used. The prompt string can also be specified for cPar. If no prompt string is given, the object's name will be displayed as prompt text.

NOTE: forEachChild() ignores objects stored here such as cPars in ExprElem structs (type X), cObject pointed to (type P), cStatistic (type T)

See also:
  ExprElem

## Public Member Functions

Constructors, destructor, assignment.
| cPar (const cPar &other)
| cPar (const char *name=NULL)
| cPar (const char *name, cPar &other)
virtual | ~cPar ()
cPar & | operator= (const cPar &otherpar)
Redefined cObject member functions
virtual cPolymorphic * | dup () const
virtual std::string | info () const
virtual void | writeContents (std::ostream &os)
virtual void | forEachChild (cVisitor *v)
virtual void | netPack (cCommBuffer *buffer)
virtual void | netUnpack (cCommBuffer *buffer)
Setter functions. Note that overloaded assignment operators also exist.
cPar & | setBoolValue (bool b)
cPar & | setLongValue (long l)
cPar & | setStringValue (const char *s)
cPar & | setDoubleValue (double d)
cPar & | setDoubleValue (cStatistic *res)
cPar & | setDoubleValue (ExprElem *x, int n)
cPar & | setDoubleValue (cDoubleExpression *expr)
cPar & | setDoubleValue (MathFuncNoArg f)
cPar & | setDoubleValue (MathFunc1Arg f, double p1)
cPar & | setDoubleValue (MathFunc2Args f, double p1, double p2)
cPar & | setDoubleValue (MathFunc3Args f, double p1, double p2, double p3)
cPar & | setDoubleValue (MathFunc4Args f, double p1, double p2, double p3, double p4)
cPar & | setPointerValue (void *ptr)
cPar & | setObjectValue (cObject *obj)
cPar & | setXMLValue (cXMLElement *node)
void | configPointer (VoidDelFunc delfunc, VoidDupFunc dupfunc, size_t itemsize=0)
void | takeOwnership (bool tk)
bool | takeOwnership () const
Getter functions. Note that overloaded conversion operators also exist.
bool | boolValue ()
long | longValue ()
const char * | stringValue ()
double | doubleValue ()
void * | pointerValue ()
cObject * | objectValue ()
cXMLElement * | xmlValue ()
Redirection
cPar & | setRedirection (cPar *par)
bool | isRedirected () const
cPar * | redirection ()
void | cancelRedirection ()
Type, prompt text, input flag, change flag.
char | type () const
bool | isNumeric () const
bool | isConstant () const
const char * | prompt ()
void | setPrompt (const char *s)
void | setInput (bool ip)
bool | isInput () const
bool | changed ()
Utility functions.
cPar & | read ()
void | convertToConst ()
bool | equalsTo (cPar *par)
Convert to/from text representation.
virtual std::string | getAsText () const
virtual bool | setFromText (const char *text, char type='?')
Overloaded assignment and conversion operators.
cPar & | operator= (bool b)
cPar & | operator= (const char *s)
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 l)
cPar & | operator= (unsigned long l)
cPar & | operator= (double d)
cPar & | operator= (long double d)
cPar & | operator= (void *ptr)
cPar & | operator= (cObject *obj)
cPar & | operator= (cXMLElement *node)
| operator bool ()
| operator const char * ()
| operator char ()
| operator unsigned char ()
| operator int ()
| operator unsigned int ()
| operator short ()
| operator unsigned short ()
| operator long ()
| operator unsigned long ()
| operator double ()
| operator long double ()
| operator void * ()
| operator cObject * ()
| operator cXMLElement * ()

## Static Public Member Functions

Compare function
static int | cmpbyvalue (cObject *one, cObject *other)

## Protected Member Functions

Event hooks
virtual void | beforeChange ()
virtual void | afterChange ()

## Classes

struct | ExprElem
| One component in a (reversed Polish) expression in a cPar; see cPar::setDoubleValue(ExprElem *,int). More...

## Constructor & Destructor Documentation

cPar::cPar | ( | const cPar & | other | ) |

| Copy constructor, creates an exact copy of the argument.

cPar::cPar | ( | const char * | name = `NULL` | ) | `[explicit]`

| Constructor, creates a cPar with the given name and long ('L') as default type.

cPar::cPar | ( | const char * | name,
|  | cPar & | other
| ) | `[explicit]`

| Constructor, creates a copy of the second argument with another name.

virtual cPar::~cPar | ( |  | ) | `[virtual]`

| Destructor.

## Member Function Documentation

virtual void cPar::afterChange | ( |  | ) | `[protected, virtual]`

| Called each time after the value of this object changed. It can be used for tracking parameter changes. This default implementation does nothing. Reimplemented in cModulePar.

virtual void cPar::beforeChange | ( |  | ) | `[protected, virtual]`

| Called each time before the value of this object changes. It can be used for tracking parameter changes. This default implementation does nothing.

bool cPar::boolValue | ( |  | ) |

| Returns value as a boolean. The cPar type must be bool (B) or a numeric type.

void cPar::cancelRedirection | ( |  | ) |

| Break the redirection. The new type will be long ('L').

bool cPar::changed | ( |  | ) |

| Returns true if the value has changed since the last changed() call. Side effect: clears the 'changed' flag, so a next call will return false.

static int cPar::cmpbyvalue | ( | cObject * | one,
|  | cObject * | other
| ) | `[static]`

| Compares two cPars by their value if they are numeric. This function can be used to sort cPar objects in a priority queue.

void cPar::configPointer | ( | VoidDelFunc | delfunc,
|  | VoidDupFunc | dupfunc,
|  | size_t | itemsize = `0`
| ) |

Configures memory management for the void* pointer ('P') type.

Similar to cLinkedList::configPointer().

delfunc | dupfunc. | itemsize | behavior
NULL | NULL | 0 | Pointer is treated as mere pointer - no memory management. Duplication copies the pointer, and deletion does nothing.
NULL | NULL | !=0 | Plain memory management. Duplication is done with new char[size]+memcpy(), and deletion is done via delete.
NULL or user's delete func. | user's dupfunc. | indifferent | Sophisticated memory management. Duplication is done by calling the user-supplied duplication function, which should do the allocation and the appropriate copying. Deletion is done by calling the user-supplied delete function, or the delete operator if it is not supplied.

void cPar::convertToConst | ( |  | ) |

| Replaces the object value with its evaluation (a double). Equivalent to `setValue('D', this->doubleValue())`.

double cPar::doubleValue | ( |  | ) |

| Returns value as double. The cPar type must be types long (L), double (D), function (F), Boolean (B), distribution (T), compiled expression (C) or expression (X).

virtual cPolymorphic* cPar::dup | ( |  | ) | const`[inline, virtual]`

| Creates and returns an exact copy of this object. See cObject for more details. Reimplemented from cObject. Reimplemented in cModulePar.

bool cPar::equalsTo | ( | cPar * | par | ) |

| Compares the stored values. The two objects must have the same type character and the same value to be equal.

virtual void cPar::forEachChild | ( | cVisitor * | v | ) | `[virtual]`

| Calls v->visit(this) for the contained object, if there's any. See cObject for more details. Reimplemented from cObject.

virtual std::string cPar::getAsText | ( |  | ) | const`[virtual]`

| Returns the value in text format.

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

| Produces a one-line description of object contents into the buffer passed as argument. See cObject for more details. Reimplemented from cPolymorphic.

bool cPar::isConstant | ( |  | ) | const

| Returns true if the value is constant. It returns true if the type is 'L', 'D', 'B', or 'S', that is, the object stores a long, double, boolean or string constant.

bool cPar::isInput | ( |  | ) | const

| Returns true if the parameter is of input type (the input flag is set).

bool cPar::isNumeric | ( |  | ) | const

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

bool cPar::isRedirected | ( |  | ) | const`[inline]`

| Returns true if this object is redirected to another cPar.

long cPar::longValue | ( |  | ) |

| Returns value as long. The cPar type must be types long (L), double (D), Boolean (B), function (F), distribution (T), compiled expression (C) or expression (X).

virtual void cPar::netPack | ( | cCommBuffer * | buffer | ) | `[virtual]`

| Serializes the object into a PVM or MPI send buffer. Used by the simulation kernel for parallel execution. See cObject for more details. Reimplemented from cObject.

virtual void cPar::netUnpack | ( | cCommBuffer * | buffer | ) | `[virtual]`

| Deserializes the object from a PVM or MPI receive buffer Used by the simulation kernel for parallel execution. See cObject for more details. Reimplemented from cObject.

cObject* cPar::objectValue | ( |  | ) |

| Returns value as pointer to cObject. The cPar type must be pointer (O).

cPar::operator bool | ( |  | ) | `[inline]`

| Equivalent to boolValue().

cPar::operator char | ( |  | ) | `[inline]`

| Calls longValue() and converts the result to char.

cPar::operator cObject * | ( |  | ) | `[inline]`

| Equivalent to objectValue().

cPar::operator const char * | ( |  | ) | `[inline]`

| Equivalent to stringValue().

cPar::operator cXMLElement * | ( |  | ) | `[inline]`

| Equivalent to xmlValue().

cPar::operator double | ( |  | ) | `[inline]`

| Equivalent to doubleValue().

cPar::operator int | ( |  | ) | `[inline]`

| Calls longValue() and converts the result to int.

cPar::operator long | ( |  | ) | `[inline]`

| Equivalent to longValue().

cPar::operator long double | ( |  | ) | `[inline]`

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

cPar::operator short | ( |  | ) | `[inline]`

| Calls longValue() and converts the result to short.

cPar::operator unsigned char | ( |  | ) | `[inline]`

| Calls longValue() and converts the result to unsigned char.

cPar::operator unsigned int | ( |  | ) | `[inline]`

| Calls longValue() and converts the result to unsigned int.

cPar::operator unsigned long | ( |  | ) | `[inline]`

| Calls longValue() and converts the result to unsigned long.

cPar::operator unsigned short | ( |  | ) | `[inline]`

| Calls longValue() and converts the result to unsigned short.

cPar::operator void * | ( |  | ) | `[inline]`

| Equivalent to pointerValue().

cPar& cPar::operator= | ( | cXMLElement * | node | ) | `[inline]`

| Equivalent to setXMLValue().

cPar& cPar::operator= | ( | cObject * | obj | ) | `[inline]`

| Equivalent to setObjectValue().

cPar& cPar::operator= | ( | void * | ptr | ) | `[inline]`

| Equivalent to setPointerValue().

cPar& cPar::operator= | ( | long double | d | ) | `[inline]`

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

cPar& cPar::operator= | ( | double | d | ) | `[inline]`

| Equivalent to setDoubleValue().

cPar& cPar::operator= | ( | unsigned long | l | ) | `[inline]`

| Converts the argument to long, and calls setLongValue().

cPar& cPar::operator= | ( | long | l | ) | `[inline]`

| Equivalent to setLongValue().

cPar& cPar::operator= | ( | unsigned short | i | ) | `[inline]`

| Converts the argument to long, and calls setLongValue().

cPar& cPar::operator= | ( | short | i | ) | `[inline]`

| Converts the argument to long, and calls setLongValue().

cPar& cPar::operator= | ( | unsigned int | i | ) | `[inline]`

| Converts the argument to long, and calls setLongValue().

cPar& cPar::operator= | ( | int | i | ) | `[inline]`

| Converts the argument to long, and calls setLongValue().

cPar& cPar::operator= | ( | unsigned char | c | ) | `[inline]`

| Converts the argument to long, and calls setLongValue().

cPar& cPar::operator= | ( | char | c | ) | `[inline]`

| Converts the argument to long, and calls setLongValue().

cPar& cPar::operator= | ( | const char * | s | ) | `[inline]`

| Equivalent to setStringValue().

cPar& cPar::operator= | ( | bool | b | ) | `[inline]`

| Equivalent to setBoolValue().

cPar& cPar::operator= | ( | const cPar & | otherpar | ) |

Assignment operator.

The name member doesn't get copied; see cObject's operator=() for more details.

The behavior with redirected cPar objects is the following. This function copies the contents of the other object (whether it is redirected or not) into this object, or, if this object is redirected, into the object this object refers to. This means that if you want to overwrite this very object (and not the one it points to), you have to use cancelRedirection() first.

void* cPar::pointerValue | ( |  | ) |

| Returns value as a void * pointer. The cPar type must be pointer (P).

const char* cPar::prompt | ( |  | ) |

| Returns the prompt text or NULL.

cPar& cPar::read | ( |  | ) |

| Reads the object value from the ini file or from the user.

cPar* cPar::redirection | ( |  | ) |

| Returns NULL if the cPar's value is not redirected to another cPar; otherwise it returns the pointer of that cPar. This function and isRedirected() are the only ways to determine if an object is redirected or not (type() returns the type of the other cPar: 'D', 'L' etc).

cPar& cPar::setBoolValue | ( | bool | b | ) |

| Sets the value to the given bool value.

cPar& cPar::setDoubleValue | ( | MathFunc4Args | f,
|  | double | p1,
|  | double | p2,
|  | double | p3,
|  | double | p4
| ) |

| Sets the value to the given math function with four arguments. Every time the cPar's value is asked the function will be called with p1, p2, p3 and p4 as an arguments.

cPar& cPar::setDoubleValue | ( | MathFunc3Args | f,
|  | double | p1,
|  | double | p2,
|  | double | p3
| ) |

| Sets the value to the given math function with three arguments. Every time the cPar's value is asked the function will be called with p1, p2 and p3 as an arguments.

cPar& cPar::setDoubleValue | ( | MathFunc2Args | f,
|  | double | p1,
|  | double | p2
| ) |

| Sets the value to the given math function with two arguments. Every time the cPar's value is asked the function will be called with p1 and p2 as an arguments.

cPar& cPar::setDoubleValue | ( | MathFunc1Arg | f,
|  | double | p1
| ) |

| Sets the value to the given math function with one argument. Every time the cPar's value is asked the function will be called with p1 as an argument.

cPar& cPar::setDoubleValue | ( | MathFuncNoArg | f | ) |

| Sets the value to the given math function with no arguments. Every time the cPar's value is asked the function will be called.

cPar& cPar::setDoubleValue | ( | cDoubleExpression * | expr | ) |

| Sets the value to the given compiled expression, subclassed from cDoubleExpression. Every time the cPar's value is asked, the evaluate() function of cDoubleExpression will be called. The passed object will be deallocated (using operator delete) from the cPar destructor, and also when the cPar object is assigned another value.

cPar& cPar::setDoubleValue | ( | ExprElem * | x,
|  | int | n
| ) |

Sets the value to the given Reverse Polish expression, specified as an array of ExprElem structs.

Every time the cPar's value is asked the expression will be evaluated using a stack machine. The stack machine calculates in doubles.

Example: the NED expression (count+1)/2 would be represented in the following way:

     cPar::ExprElem *expression = new cPar::ExprElem[5];
     expression[0] = &(mod->par("count")); // ptr to module parameter
     expression[1] = 1;
     expression[2] = '+';
     expression[3] = 2;
     expression[4] = '/';
     param.setDoubleValue(expression,5);

cPar& cPar::setDoubleValue | ( | cStatistic * | res | ) |

| Sets the value to the given distribution. Every time the cPar's value is asked a random number produced by res.random() will be returned.

cPar& cPar::setDoubleValue | ( | double | d | ) |

| Sets the value to the given double value.

virtual bool cPar::setFromText | ( | const char * | text,
|  | char | type = `'?'`
| ) | `[virtual]`

| This function tries to interpret the argument text as a type typed value (L=long, S=string, etc). type=='?' (the default) means that the type is to be auto-selected. On success, cPar is updated with the new value and true is returned, otherwise the function returns false. No error message is generated.

void cPar::setInput | ( | bool | ip | ) |

| Sets (ip=true) or clears (ip=false) the input flag.

cPar& cPar::setLongValue | ( | long | l | ) |

| Sets the value to the given long value.

cPar& cPar::setObjectValue | ( | cObject * | obj | ) |

| Sets the value to the given object. Whether cPar will take the ownership of the object depends on the takeOwnership() flag.

cPar& cPar::setPointerValue | ( | void * | ptr | ) |

Sets the value to the given pointer.

The ownership of the block pointer to can be controlled using configPointer().

See also:
  configPointer

void cPar::setPrompt | ( | const char * | s | ) |

| Sets the prompt text.

cPar& cPar::setRedirection | ( | cPar * | par | ) |

| Creates a redirection to another cPar. A cPar object can be set to stand for a value actually stored in another cPar object. This is called indirect or redirected value. When using redirection, every operation on the value (i.e. reading or changing it) will be actually done to the other cPar object.

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.

cPar& cPar::setXMLValue | ( | cXMLElement * | node | ) |

| Sets the value to the given cXMLElement.

const char* cPar::stringValue | ( |  | ) |

| Returns value as const char *. Only for string (S) type.

bool cPar::takeOwnership | ( |  | ) | const`[inline]`

| Returns the takeOwnership flag, see takeOwnership().

void cPar::takeOwnership | ( | bool | tk | ) | `[inline]`

| Sets the flag that determines whether setObjectValue(cObject *) and setDoubleValue(cStatistic *) should automatically take ownership of the objects.

char cPar::type | ( |  | ) | const

| Returns type character. If the "real" type is 'I', it returns the type of the object it is redirected to (for example, 'D', 'L', etc.)

virtual void cPar::writeContents | ( | std::ostream & | os | ) | `[virtual]`

| Writes textual information about this object to the stream. See cObject for more details. Reimplemented from cObject.

cXMLElement* cPar::xmlValue | ( |  | ) |

| Returns value as pointer to cXMLElement. The cPar type must be XML (M).

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

- cpar.h