Appendix: NED Functions¶

The functions that can be used in NED expressions and ini files are as follows. The question mark (as in “rng?”) denotes optional arguments.

Category “conversion”:¶

bool: : bool bool(any x)

Converts x to bool, and returns the result. For numeric values, 0 and nan become false and other values become true; for strings, “true” becomes true and everything else becomes false.
double: : quantity double(any x)

Converts x to double, and returns the result. A boolean argument becomes 0 or 1; a string is interpreted as number; an object argument causes an error. Units are preserved.
int: : intquantity int(any x)

Converts x to int, and returns the result. A boolean argument becomes 0 or 1; a double is converted using floor(); a string is interpreted as number; an object argument causes an error. Units are preserved.
string: : string string(any x)

Converts x to string, and returns the result.

Category “i/o”:¶

absFilePath: : string absFilePath(string filename)

Converts filename to an absolute filesystem path. Absolute paths are returned unchanged; relative paths are understood as relative to the location of the ini or NED file where the call occurs (see baseDir()).
baseDir: : string baseDir()

Returns the absolute filesystem path to the directory of the ini or NED file where the baseDir() call occurs.
parseCSV: : any parseCSV(string str)

Parses the given string as a comma-separated CSV, and returns it as an array of arrays. Elements can be boolean (true/false), numeric (integer or double, with or without measurement unit), quoted string, or unquoted string. Items that cannot be parsed as any of the more specific types are interpreted as unquoted strings. See readCSV() for details of the accepted CSV flavor.
parseExtendedCSV: : any parseExtendedCSV(string str)

Parses the given string as a comma-separated CSV, and returns it as an array of arrays. Elements are parsed as NED expressions, and are evaluated in the caller’s context. See readCSV() for details of the accepted CSV flavor.
parseExtendedJSON: : any parseExtendedJSON(string str)

Parses the given string as Extended JSON, and returns its contents. Extended JSON allows any value to be a valid NED expression (instead of just constants allowed by strict JSON), and some extensions to the object syntax. Actually, as the NED expression syntax includes JSON-like arrays and objects, “parsing” is done simply by evaluating the string as a NED expression in the caller’s context.
parseJSON: : any parseJSON(string str)

Parses the given string as JSON, and returns its contents. The syntax is more permissive than standard JSON: it additionally allows the special numeric values ‘nan‘, ‘inf‘ and ‘-inf‘, the use of measurement units, and object keys are also accepted without quotation marks if it doesn’t interfere with parsing.
parseXML: : xml parseXML(string xmlstring, string xpath?)

Parses the given XML string into a cXMLElement tree, and returns the root element. When called with two arguments, it returns the first element from the tree that matches the expression given in simplified XPath syntax.
readCSV: : any readCSV(string filename)

Parses the content of the given text file as comma-separated CSV, and returns it as an array of arrays. Elements can be boolean (‘true‘ or ‘false‘), numeric (integer or double, with or without measurement unit), quoted string, or unquoted string. Items that cannot be parsed as any of the more specific types are interpreted as unquoted strings. CSV parsing rules: separator is comma; blank (whitespace-only) lines are ignored; lines that contain hash mark ‘#‘ on column 1 are considered comments and are ignored; items are trimmed of leading and trailing whitespace before processing; no line continuation with backslash; quoted strings may be delimited with single or double quotes; quoted strings may contain C-like backslash escapes; no support for splitting strings over multiple lines; no special treatment for the first (possibly header) line.
readExtendedCSV: : any readExtendedCSV(string filename)

Parses the content of the given text file as comma-separated CSV, and returns it as an array of arrays. Elements are parsed as NED expressions, and are evaluated in the caller’s context. See readCSV() for details of the accepted CSV flavor.
readExtendedJSON: : any readExtendedJSON(string filename)

Parses the given text file as Extended JSON, and returns its contents. Extended JSON allows any value to be a valid NED expression (instead of just constants allowed by strict JSON), and some extensions to the object syntax. Actually, as the NED expression syntax includes JSON-like arrays and objects, “parsing” is done simply by evaluating the content as a NED expression in the caller’s context.
readFile: : string readFile(string filename)

Opens the specified text file, and returns its content as a string. If filename is a relative path, it is understood as relative to the location of the ini or NED file where the readFile() call occurs.
readJSON: : any readJSON(string filename)

Parses the given text file as JSON, and returns its contents. The syntax is more permissive than standard JSON: it additionally allows the special numeric values ‘nan‘, ‘inf‘ and ‘-inf‘, the use of measurement units, and object keys are also accepted without quotation marks if it doesn’t interfere with parsing.
readXML: : xml readXML(string filename, string xpath?)

Parses the given XML file into a cXMLElement tree, and returns the root element. When called with two arguments, it returns the first element from the tree that matches the expression given in simplified XPath syntax.
resolveFile: : string resolveFile(string directory, string filename)

Joins that arguments as file paths, except that when the second argument is an absolute filesystem path, it is returned unchanged. This is purely a string operation; neither directory nor filename needs to exist in the file system.
workingDir: : string workingDir()

Returns the current working directory.

Category “math”:¶

acos: : double acos(double)

Trigonometric function; see the standard C function of the same name.
asin: : double asin(double)

Trigonometric function; see the standard C function of the same name.
atan: : double atan(double)

Trigonometric function; see the standard C function of the same name.
atan2: : double atan2(double, double)

Trigonometric function; see the standard C function of the same name.
ceil: : double ceil(double)

Rounds up; see the standard C function of the same name.
cos: : double cos(double)

Trigonometric function; see the standard C function of the same name.
exp: : double exp(double)

Exponential; see the standard C function of the same name.
fabs: : quantity fabs(quantity x)

Returns the absolute value of the quantity.
floor: : double floor(double)

Rounds down; see the standard C function of the same name.
fmod: : quantity fmod(quantity x, quantity y)

Returns the floating-point remainder of x/y; unit conversion takes place if needed.
hypot: : double hypot(double, double)

Length of the hypotenuse; see the standard C function of the same name.
log: : double log(double)

Natural logarithm; see the standard C function of the same name.
log10: : double log10(double)

Base-10 logarithm; see the standard C function of the same name.
max: : quantity max(quantity a, quantity b)

Returns the greater one of the two quantities; unit conversion takes place if needed.
min: : quantity min(quantity a, quantity b)

Returns the smaller one of the two quantities; unit conversion takes place if needed.
pow: : double pow(double, double)

Power; see the standard C function of the same name.
sin: : double sin(double)

Trigonometric function; see the standard C function of the same name.
sqrt: : double sqrt(double)

Square root; see the standard C function of the same name.
tan: : double tan(double)

Trigonometric function; see the standard C function of the same name.

Category “misc”:¶

dup: : object dup(object obj)

Clones the given object by invoking its dup() C++ method.
eval: : any eval(string expr)

Evaluates the NED expression within the calling context.
firstAvailable: : string firstAvailable(...)

Accepts any number of strings, interprets them as NED type names (qualified or unqualified), and returns the first one that exists and its C++ implementation class is also available. Throws an error if none of the types are available.
get: : any get(object arrayOrMap, any keyOrIndex)

Retrieves a value from a NED map or array. Examples: get([10,20,30], 1) returns 20; get(foo:10,bar:20, ’foo’) returns 10. Note that get(x,i) may also be written as x.get(i), with the two being completely equivalent.
select: : any select(int index, ...)

Returns the <index>th item from the rest of the argument list; numbering starts from 0.
simTime: : quantity simTime()

Returns the current simulation time.
size: : int size(object arrayOrMap)

Returns the length of an array, or the number of elements in a map.

Category “ned”:¶

ancestorIndex: : int ancestorIndex(int numLevels)

Returns the index of the ancestor module numLevels levels above the module or channel in context.
componentId: : int componentId()

Returns the ID of the module or channel in context.
fullName: : string fullName()

Returns the full name of the module or channel in context.
fullPath: : string fullPath()

Returns the full path of the module or channel in context.
parentIndex: : int parentIndex()

Returns the index of the parent module, which has to be part of module vector.

Category “python”:¶

pycode: : any pycode(string s, ...)

evaluates the string as if it was a Python function body
pyeval: : any pyeval(string s, ...)

evaluates the string as a Python expression; or as if it was a Python lambda, then calls it

Category “random/continuous”:¶

beta: : double beta(double alpha1, double alpha2, int rng?)

Returns a random number from the Beta distribution.
cauchy: : quantity cauchy(quantity a, quantity b, int rng?)

Returns a random number from the Cauchy distribution.
chi_square: : double chi_square(int k, int rng?)

Returns a random number from the Chi-square distribution.
erlang_k: : quantity erlang_k(int k, quantity mean, int rng?)

Returns a random number from the Erlang distribution.
exponential: : quantity exponential(quantity mean, int rng?)

Returns a random number from the Exponential distribution.
gamma_d: : quantity gamma_d(double alpha, quantity theta, int rng?)

Returns a random number from the Gamma distribution.
lognormal: : double lognormal(double m, double w, int rng?)

Returns a random number from the Lognormal distribution.
normal: : quantity normal(quantity mean, quantity stddev, int rng?)

Returns a random number from the Normal distribution.
pareto_shifted: : quantity pareto_shifted(double a, quantity b, quantity c, int rng?)

Returns a random number from the Pareto-shifted distribution.
student_t: : double student_t(int i, int rng?)

Returns a random number from the Student-t distribution.
triang: : quantity triang(quantity a, quantity b, quantity c, int rng?)

Returns a random number from the Triangular distribution.
truncnormal: : quantity truncnormal(quantity mean, quantity stddev, int rng?)

Returns a random number from the truncated Normal distribution.
uniform: : quantity uniform(quantity a, quantity b, int rng?)

Returns a random number from the Uniform distribution.
weibull: : quantity weibull(quantity a, quantity b, int rng?)

Returns a random number from the Weibull distribution.

Category “random/discrete”:¶

bernoulli: : int bernoulli(double p, int rng?)

Returns a random number from the Bernoulli distribution.
binomial: : int binomial(int n, double p, int rng?)

Returns a random number from the Binomial distribution.
geometric: : int geometric(double p, int rng?)

Returns a random number from the Geometric distribution.
intuniform: : int intuniform(intquantity a, intquantity b, int rng?)

Returns a random integer uniformly distributed over [a,b].
intuniformexcl: : int intuniformexcl(intquantity a, intquantity b, int rng?)

Returns a random integer uniformly distributed over [a,b), that is, [a,b-1].
negbinomial: : int negbinomial(int n, double p, int rng?)

Returns a random number from the Negative Binomial distribution.
poisson: : int poisson(double lambda, int rng?)

Returns a random number from the Poisson distribution.

Category “strings”:¶

choose: : string choose(int index, string list)

Interprets list as a space-separated list, and returns the item at the given index. Negative and out-of-bounds indices cause an error.
contains: : bool contains(string s, string substr)

Returns true if string s contains substr as substring
endsWith: : bool endsWith(string s, string substr)

Returns true if s ends with the substring substr.
expand: : string expand(string s)

Expands $ variables ($configname, $runnumber, etc.) in the given string, and returns the result.
indexOf: : int indexOf(string s, string substr)

Returns the position of the first occurrence of the substring substr in s, or -1 if s does not contain substr.
length: : int length(string s)

Returns the length of the string
replace: : string replace(string s, string substr, string repl, int startPos?)

Replaces all occurrences of substr in s with the string repl. If startPos is given, search begins from position startPos in s.
replaceFirst: : string replaceFirst(string s, string substr, string repl, int startPos?)

Replaces the first occurrence of substr in s with the string repl. If startPos is given, search begins from position startPos in s.
startsWith: : bool startsWith(string s, string substr)

Returns true if s begins with the substring substr.
substring: : string substring(string s, int pos, int len?)

Return the substring of s starting at the given position, either to the end of the string or maximum len characters
substringAfter: : string substringAfter(string s, string substr)

Returns the substring of s after the first occurrence of substr, or the empty string if s does not contain substr.
substringAfterLast: : string substringAfterLast(string s, string substr)

Returns the substring of s after the last occurrence of substr, or the empty string if s does not contain substr.
substringBefore: : string substringBefore(string s, string substr)

Returns the substring of s before the first occurrence of substr, or the empty string if s does not contain substr.
substringBeforeLast: : string substringBeforeLast(string s, string substr)

Returns the substring of s before the last occurrence of substr, or the empty string if s does not contain substr.
tail: : string tail(string s, int len)

Returns the last len character of s, or the full s if it is shorter than len characters.
toLower: : string toLower(string s)

Converts s to all lowercase, and returns the result.
toUpper: : string toUpper(string s)

Converts s to all uppercase, and returns the result.
trim: : string trim(string s)

Discards whitespace from the start and end of s, and returns the result.

Category “units”:¶

convertUnit: : quantity convertUnit(quantity x, string unit)

Converts x to the given unit.
dropUnit: : double dropUnit(quantity x)

Removes the unit of measurement from quantity x.
replaceUnit: : quantity replaceUnit(quantity x, string unit)

Replaces the unit of x with the given unit.
unitOf: : string unitOf(quantity x)

Returns the unit of the given quantity.

Category “xml”:¶

xml: : xml xml(string xmlstring, string xpath?)

Parses the given XML string into a cXMLElement tree, and returns the root element. When called with two arguments, it returns the first element from the tree that matches the expression given in simplified XPath syntax. Note: This is an alias for the parseXML() function.
xmldoc: : xml xmldoc(string filename, string xpath?)

Parses the given XML file into a cXMLElement tree, and returns the root element. When called with two arguments, it returns the first element from the tree that matches the expression given in simplified XPath syntax. Note: This is an alias for the readXML() function.

Category “units/conversion”:¶

<unit_name>: : quantity <unit_name>(quantity x)

All measurement unit names can be used as one-argument functions that convert from a compatible unit or a dimensionless number. Substitute underscore for any hyphen in the name, and ’_per_’ for any slash: milliampere-hour –> milliampere_hour(), meter/sec –> meter_per_sec().

d(), day(), h(), hour(), min(), minute(), s(), second(), ms(), millisecond(), us(), microsecond(), ns(), nanosecond(), ps(), picosecond(), fs(), femtosecond(), as(), attosecond(), bps(), bit_per_sec(), kbps(), kilobit_per_sec(), Mbps(), megabit_per_sec(), Gbps(), gigabit_per_sec(), Tbps(), terabit_per_sec(), B(), byte(), KiB(), kibibyte(), MiB(), mebibyte(), GiB(), gibibyte(), TiB(), tebibyte(), kB(), kilobyte(), MB(), megabyte(), GB(), gigabyte(), TB(), terabyte(), b(), bit(), Kib(), kibibit(), Mib(), mebibit(), Gib(), gibibit(), Tib(), tebibit(), kb(), kilobit(), Mb(), megabit(), Gb(), gigabit(), Tb(), terabit(), rad(), radian(), deg(), degree(), m(), meter(), dm(), decimeter(), cm(), centimeter(), mm(), millimeter(), um(), micrometer(), nm(), nanometer(), km(), kilometer(), W(), watt(), mW(), milliwatt(), uW(), microwatt(), nW(), nanowatt(), pW(), picowatt(), fW(), femtowatt(), kW(), kilowatt(), MW(), megawatt(), GW(), gigawatt(), Hz(), hertz(), kHz(), kilohertz(), MHz(), megahertz(), GHz(), gigahertz(), THz(), terahertz(), kg(), kilogram(), g(), gram(), t(), tonne(), K(), kelvin(), J(), joule(), kJ(), kilojoule(), MJ(), megajoule(), Ws(), watt_second(), Wh(), watt_hour(), kWh(), kilowatt_hour(), MWh(), megawatt_hour(), V(), volt(), kV(), kilovolt(), mV(), millivolt(), A(), ampere(), mA(), milliampere(), uA(), microampere(), Ohm(), ohm(), mOhm(), milliohm(), kOhm(), kiloohm(), MOhm(), megaohm(), mps(), meter_per_sec(), kmps(), kilometer_per_sec(), kmph(), kilometer_per_hour(), C(), coulomb(), As(), ampere_second(), mAs(), milliampere_second(), Ah(), ampere_hour(), mAh(), milliampere_hour(), x(), times(), dBW(), decibel_watt(), dBm(), decibel_milliwatt(), dBmW(), decibel_milliwatt(), dBV(), decibel_volt(), dBmV(), decibel_millivolt(), dBA(), decibel_ampere(), dBmA(), decibel_milliampere(), dB(), decibel(), etc.