1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<!-- $Id: formulas.htm,v 1.7 2005/01/03 22:40:12 jfontain Exp $ -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Jean-Luc Fontaine">
<meta name="Description" content="user manual for formulas in moodss">
<title>moodss formulas</title>
</head>
<body bgcolor="#FFFFFF" style="font-family: helvetica, verdana, arial">
<center><h2>Formulas in moodss (Modular Object Oriented Dynamic SpreadSheet)</h2></center>
<h3>Contents:</h3>
<!-- beginning of contents -->
<ul>
<li><a href="#about">1. About this document</a>
<li><a href="#expressions">2. Expressions</a><ul>
<li><a href="#expressions.operands">2.1. Operands</a>
<li><a href="#expressions.operators">2.2. Operators</a>
<li><a href="#expressions.functions">2.3. Functions</a>
<li><a href="#expressions.errors">2.4. Error handling</a>
</ul>
<li><a href="#formatting">3. Formatting</a>
<li><a href="#advanced">4. Advanced usage</a>
</ul>
<!-- end of contents -->
<h3><a name="about"></a>1. About this document</h3>
<p>This document contains general and reference information to help the user create formulas from data cells coming from modules loaded in the moodss application. Once created, the formulas are displayed in formulas tables, described in the general moodss documentation.
<br>This document particularly covers the mathematical expressions that can be used in formulas, including their syntax and the various available operators and functions.
<h3><a name="expressions"></a>2. Expressions</h3>
<p>In moodss and moomps, a formula consists of a user defined name, comments and a mathematical expression made of data cells, mathematical operators and functions. The expression is the core of the formula.
<p>An expression consists of a combination of operands (data cells, numbers, mathematical functions, ...), operators (+, -, ...), and parentheses. White space may be used between the operands and operators and parentheses; it is ignored when the result of the formula is internally calculated.
<p>For example, the screen shot below shows the expression used to calculate the memory usage of a computer in percent, obtained by dividing the used memory by the available memory and multiplying the result by 100.
<p><center><img src="formula1.gif" alt="basic memory usage expression"></center>
<p>You may notice that something is wrong with this expression, since its result seems to be <b>0</b>, unexpected since there is some actual memory used. What is happening is that the internal calculation engine (called the <b>calculator</b> in this document), when possible, interprets the operands as integer values.
<br>What we want in this case is to force floating-point numbers calculations, which can be achieved by using a math function to convert one of the memory operands to floating-point, as shown below.
<p><center><img src="formula2.gif" alt="floating-point memory usage expression"></center>
<p>We will now cover in more details all the available features of expressions.
<h4><a name="expressions.operands"></a>2.1. Operands</h4>
<p>Where possible, operands are interpreted as integer values (such as <b>123</b>), else treated as floating-point numbers (such as <b>12.345</b>) if that is possible.
<br>An operand may be directly input as a constant value by the user (such as the <b>100</b> multiplier in the screen shots above), or dropped from any source of data cells (such as <b>used memory</b> and <b>available memory</b>).
<p>Conversion among internal representations for integer and floating-point operands is done automatically as needed. For arithmetic computations, integers are used until some floating-point number is introduced, after which floating-point is used. For example, the result of <i>5/4</i> is <i>1</i>, while <i>5/4.0</i> gives <i>1.25</i>.
<br>Floating-point results are always displayed and used with a <b>.</b> (dot) or an <i>e</i> so that they will not look like integer values. For example, the result of <i>20.0/5.0</i> is <i>4.0</i>, not <i>4</i>.
<p>An operand may also be a mathematical function whose arguments have any of the above forms for operands, such as <b>double(127544)</b> (see the <a href="#expressions.functions">functions</a> section).
<h4><a name="expressions.operators"></a>2.2. Operators</h4>
<p>The valid operators are listed below, grouped in decreasing order of precedence:<ul>
<li><b>- + ~ !</b> Unary minus, unary plus, bit-wise NOT, logical NOT. Bit-wise NOT may be applied only to integers.
<li><b>* / %</b> Multiply, divide, remainder. Remainder may be applied only to integers. The remainder will always have the same sign as the divisor and an absolute value smaller than the divisor.
<li><b>+ -</b> Add and subtract.
<li><b><< >></b> Left and right shift. Valid for integer operands only. A right shift always propagates the sign bit.
<li><b>< > <= >=</b> Boolean less, greater, less than or equal, and greater than or equal. Each operator produces 1 if the condition is true, 0 otherwise.
<li><b>== !=</b> Boolean equal and not equal. Each operator produces a zero/one result.
<li><b>&</b> Bit-wise AND. Valid for integer operands only.
<li><b>^</b> Bit-wise exclusive OR. Valid for integer operands only.
<li><b>|</b> Bit-wise OR. Valid for integer operands only.
<li><b>&&</b> Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. Valid for boolean and numeric (integers or floating-point) operands only.
<li><b>||</b> Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. Valid for boolean and numeric (integers or floating-point) operands only.
</ul>
<h4><a name="expressions.functions"></a>2.3. Functions</h4>
<p>The following specific functions take strictly one data cell (dragged and dropped in moodss formulas interface) as sole argument. They internally use the value of the data cell at the last update of the formula, which means that they return an undefined value the first time they are invoked, since, obviously, there was no previous value for the data cell.<ul>
<li><b>delta(</b><i>cell</i><b>)</b> Returns the difference between the current value of a data cell and its last value, in <b>integer</b> form. For example, it can be used on a 32 bit counter that always grows and wraps around after a while, and, in such a case, always returns a positive difference. Equivalent to: <b>int(</b><i>cell</i><b> - last(</b><i>cell</i><b>))</b>.
<li><b>diff(</b><i>cell</i><b>)</b> Returns the difference between the current value of a data cell and its last value, in <b>floating point</b> form, with maximum precision. Equivalent to: <b>double(</b><i>cell</i><b> - last(</b><i>cell</i><b>))</b>.
<li><b>last(</b><i>cell</i><b>)</b> Returns the value of a data cell at the last update time.
</ul>
<p><i><b>Note</b>: A formula is usually updated by the core (moodss or moomps), at the time the dashboard is refreshed, as defined by its poll time. A formula update means the result of the formula is evaluated, using the values of the embedded data cells at the current time, and possibly the values of some of the cells at the time of the last update of the formula (if <b>diff()</b>, <b>delta()</b> or <b>last()</b> functions are used). If the formula contains any data cell belonging to an asynchronous module instance, then the formula is updated (or evaluated) at any time the value of a composing asynchronous data cell changes, independently of the dashboard refresh rate (poll time). The value of the last update time (see <b>diff(time)</b>) is updated every time the formula is evaluated.</i>
<p>There is also a special specific function which returns the time difference between updates:<ul>
<li><b>diff(time)</b> Returns the difference in seconds between the current time and its value at the last update, in <b>floating point</b> form. For example, the formula "<b>diff(</b><i>cell</i><b>) / diff(time)</b>" gives the growth rate of a data cell.
</ul>
<p>The following mathematical functions are also supported in expressions. They work solely with floating-point numbers unless otherwise noted:<ul>
<li><b>abs(</b><i>number</i><b>)</b> Returns the absolute value of <i>number</i>. <i>Number</i> may be either integer or floating-point, and the result is returned in the same form.
<li><b>acos(</b><i>number</i><b>)</b> Returns the arc cosine of <i>number</i>, in the range [<i>0,PI</i>] radians. <i>Number</i> should be in the range [<i>-1,1</i>].
<li><b>asin(</b><i>number</i><b>)</b> Returns the arc sine of <i>number</i>, in the range [<i>-PI/2,PI/2</i>] radians. <i>Number</i> should be in the range [<i>-1,1</i>].
<li><b>atan(</b><i>number</i><b>)</b> Returns the arc tangent of <i>number</i>, in the range [<i>-PI/2,PI/2</i>] radians.
<li><b>atan2(</b><i>y,x</i><b>)</b> Returns the arc tangent of <i>y/x</i>, in the range [<i>-PI,PI</i>] radians. <i>x</i> and <i>y</i> cannot both be <i>0</i>. If <i>x</i> is greater than <i>0</i>, this is equivalent to <b>atan(</b><i>y/x</i><b>)</b>.
<li><b>ceil(</b><i>number</i><b>)</b> Returns the smallest integral floating-point value (i.e. with a zero fractional part) not less than <i>number</i>.
<li><b>cos(</b><i>number</i><b>)</b> Returns the cosine of <i>number</i>, measured in radians.
<li><b>cosh(</b><i>number</i><b>)</b> Returns the hyperbolic cosine of <i>number</i>. If the result would cause an overflow, an error is returned.
<li><b>double(</b><i>number</i><b>)</b> If <i>number</i> is a floating-point value, returns <i>number</i>, otherwise converts <i>number</i> to floating-point and returns the converted value.
<li><b>exp(</b><i>number</i><b>)</b> Returns the exponential of <i>number</i>, defined as <i>e</i> to the power of <i>number</i>. If the result would cause an overflow, an error is returned.
<li><b>floor(</b><i>number</i><b>)</b> Returns the largest integral floating-point value (i.e. with a zero fractional part) not greater than <i>number</i>.
<li><b>fmod(</b><i>x,y</i><b>)</b> Returns the floating-point remainder of the division of <i>x</i> by <i>y</i>. If <i>y</i> is <i>0</i>, an error is returned.
<li><b>hypot(</b>x,y<b>)</b> Computes the length of the hypotenuse of a right-angled triangle <b>sqrt(</b><i>x*x+y*y</i><b>)</b>.
<li><b>int(</b><i>number</i><b>)</b> If <i>number</i> is an integer value of the same width as the machine word, returns <i>number</i>, otherwise converts <i>number</i> to an integer (of the same size as a machine word, i.e. 32-bits on 32-bit systems, and 64-bits on 64-bit systems) by truncation and returns the converted value.
<li><b>log(</b><i>number</i><b>)</b> Returns the natural logarithm of <i>number</i>. <i>Number</i> must be a positive value.
<li><b>log10(</b><i>number</i><b>)</b> Returns the base <i>10</i> logarithm of <i>number</i>. <i>Number</i> must be a positive value.
<li><b>pow(</b><i>x,y</i><b>)</b> Computes the value of <i>x</i> raised to the power <i>y</i>. If <i>x</i> is negative, <i>y</i> must be an integer value.
<li><b>round(</b><i>number</i><b>)</b> If <i>number</i> is an integer value, returns <i>number</i>, otherwise converts <i>number</i> to integer by rounding and returns the converted value.
<li><b>sin(</b><i>number</i><b>)</b> Returns the sine of <i>number</i>, measured in radians.
<li><b>sinh(</b><i>number</i><b>)</b> Returns the hyperbolic sine of <i>number</i>. If the result would cause an overflow, an error is returned.
<li><b>sqrt(</b><i>number</i><b>)</b> Returns the square root of <i>number</i>. <i>Number</i> must be non-negative.
<li><b>tan(</b><i>number</i><b>)</b> Returns the tangent of <i>number</i>, measured in radians.
<li><b>tanh(</b><i>number</i><b>)</b> Returns the hyperbolic tangent of <i>number</i>.
<li><b>wide(</b><i>number</i><b>)</b> Converts <i>number</i> to an integer value at least 64-bits wide (by sign-extension if <i>number</i> is a 32-bit number) if it is not one already.
</ul>
<h4><a name="expressions.errors"></a>2.4. Error handling</h4>
<p>Error handling is handled by the internal calculator, and most messages are easy to understand, but careful reading and thorough thinking is always useful...
<br><i><b>Note</b>: for experts, it is actually the <b>expr</b> command in a safe Tcl interpreter that reports errors.</i>
<p>Some typical error messaged are explained here (<i>please request new entries as you see fit</i>):<ul>
<li><i>syntax error in expression "...": variable references require preceding $</i>: means that probably some stray alphabet characters or an invalid mathematical function were left in the expression.
<li><i>syntax error in expression "...": premature end of expression</i>: a closing parentheses may be missing.
</ul>
<h3><a name="formatting"></a>3. Formatting</h3>
<p><i>(to be implemented)</i>
<h3><a name="advanced"></a>4. Advanced usage</h3>
<p>Operands integer values may be specified in decimal (the normal case), in octal (if the first character of the operand is <b>0</b>), or in hexadecimal (if the first two characters of the operand are <b>0x</b>).
<p>Floating-point numbers may be specified in any of the ways accepted by an ANSI-compliant C compiler (except that the <b>f</b>, <b>F</b>, <b>l</b>, and <b>L</b> suffixes are not permitted). For example, all of the following are valid floating-point numbers: <b>2.1</b>, <b>3.</b>, <b>6e4</b>, <b>7.91e+16</b>. If no numeric interpretation is possible, then it is an error and the result of the expression is <b>?</b>.
<p>The following operator is also valid:<ul>
<li><b>x?y:z</b> if-then-else, as in C. If <b>x</b> evaluates to non-zero, then the result is the value of <b>y</b>. Otherwise the result is the value of <b>z</b>.
</ul>
<p>The following random functions are also supported in expressions:<ul>
<li><b>rand(</b><b>)</b> Returns a pseudo-random floating-point value in the range [<i>0,1</i>]. Each result from rand completely determines all future results from subsequent calls to rand. The seed of the generator is initialized from the internal clock of the machine or may be set with the <b>srand</b> function.
<li><b>srand(</b><i>number</i><b>)</b> The <i>number</i>, which must be an integer, is used to reset the seed for the random number generator of rand. Returns the first random number (see <b>rand</b>) from that seed.
</ul>
<p>Finally, for users fluent in the <b>Tcl</b> language, you may use all the features of the <i>expr</i> command, including strings as operands, as the formula text is directly passed to the <b>expr</b> command, after filling the values of the data cells of course.
</body>
</html>
|
