Built-In Functions

Device Monitoring Studio provides a number of built-in functions:

Function Name Description

bool(exp)

Convert a given parameter exp to a boolean value. The following conversion rules apply:

Value's type	Behavior
`bool`	`exp` returned
`int`	`false` if exp equals to zero, `true` otherwise
`double`	`false` if exp equals to zero, `true` otherwise
`string`	`false` if exp is an empty string, `true` otherwise
`reference`	`false` if reference is not initialized, `true` otherwise

Note that when a statement expects a boolean, it converts the passed value to boolean automatically. The same rules are used during this implicit conversion.

int(exp) Convert a given parameter exp to an integer value. Floating-point numbers are truncated to nearest integer, strings are parsed as containing an integer. If parsing error occurs, the result of the conversion is zero. If passed string starts with 0, it is considered as containing octal number. If passed string starts with 0x or 0X, it is considered as containing hexadecimal number. References are first dereferenced and then converted to integer.

double(exp) Convert a given parameter exp to a floating-point value. If used on string, a string is parsed as containing a floating-point number. If parsing error occurs, the result of the conversion is zero. References are first dereferenced and then converted to floating-point.

string(exp) Convert a given parameter exp to a string value. References are dereferenced.

decimal(exp) Convert a given parameter exp to an integer value. Always treats a passed string as containing decimal number (regardless of any prefixes). References are dereferenced.

hex(exp) Convert a given parameter exp to an integer value. Always treats a passed string as containing hexadecimal number (regardless of any prefixes). References are dereferenced.

octal(exp) Convert a given parameter exp to an integer value. Always treats a passed string as containing octal number (regardless of any prefixes). References are dereferenced.

binary(exp) Convert a given parameter exp to an integer value. Always treats a passed string as containing binary number (regardless of any prefixes). References are dereferenced.

convert_integer(exp, radix) Convert a given parameter exp to an integer value. An integer's base is passed as second argument to the function. It is automatically converted to integer. References are dereferenced.

format(fmt_string, ...) This function takes a format string fmt_string and arbitrary number of arguments. It returns a string after placing each passed parameter to corresponding placeholder in a format string.

visualize(ref-expr[, flags[, encoding]])

This function requires a reference to a field and invokes a standard visualization algorithm for the referenced field. Use this function to take effect of display attribute, automatic enumeration parsing and so on. Use optional flags value to specify rendering options:

Value	Type of Expression
0	Decimal (default)
1	Hexadecimal

substring(string, pos, [count]) This function extracts a substring from a given string. pos is zero-based index of the first character of the substring and count is an optional number of characters in a substring. If omitted, substring continues until the end of the string. If pos is greater than the string length, an exception occurs. Count can be any positive integer or -1, which is equivalent to omitting the parameter.

subarray(array, start_offset[, length]) This function extracts a sub-array of a byte array. First and second arguments are required. array is an array from which you are extracting a sub-array and start_offset is a zero-based offset of the beginning of sub-array. Optional length parameter specifies the length of the resulting sub-array in bytes.

element(array, position) Returns the byte at a given offset in an array byte array.

length(exp) Return a length of a string if exp is a string expression, or byte array (in bytes), if exp is a byte array.

find(find_where, find_what[, start_pos) Find a substring in a string (if both find_where and find_what expressions are strings) or one array within another, if both expressions are byte arrays. Optional start_pos parameter specifies the location from which to start searching. It defaults to 0. The function returns integer specifying the found location or -1 if no occurrence is found.

type(exp)

Determine the type of the expression exp. Returns one of the following values (symbolic names are predefined in stddefs.h):

Symbolic Constant	Value	Type of Expression
BooleanType	0	`bool`
IntegerType	1	`int`
FloatingPointType	2	`double`
StringType	3	`string`
ReferenceType	4	`reference`

ref(exp)

Take the reference of expression. Expression must be a Field Access or Array Indexing Operator. The result of this function may not be used on the left of . operator or [] operator.

A special construct ref(this) is used to get a reference to the current object.

array(exp) Convert an expression to a byte array. Little-endian representation of boolean, integer and floating-point values are returned. If exp is a reference, a copy of referenced value is returned as byte array. All other conversions are prohibited.

is_valid(exp) This function evaluates the expression and returns false if any exception occurs during evaluation, otherwise, it returns true. Expression's result is never used and is silently discarded.

evaluate_if(exp1, exp2)

This function evaluates expression exp1 and returns its result. If any exception occurs during evaluation, it returns the value of expression exp2. Note that if another exception occurs during evaluation of exp2, it is handled as usual (propagated to user interface). This function is equivalent to

is_valid(exp1) ? exp1 : exp2

but evaluates exp1 only once.

Examples

int(2.5)           // results to 2 (integer)
int("89")          // results to 89 (integer)
double("7.8")      // results to 7.8 (floating-point)
double("string")   // results to 0.0 (floating-point)