Expressions allow to use mathematical formulas to be used in d3web knowledge bases. In every formula you may access existing questions and their values, as well as predefined constants. The results of those formulas may be used to assign it to an existing question (e.g. in a rule action) or as a condition in a rule.
This tutorial is built in three chapters:
The expressions are integrated in a bunch of existing markups, as well as defining some additional markups.
Expression can be used in %%Rule markup in both conditions and actions. In both, it must be surrounded by eval(...) containing the expression. When using the expression as a condition, the expression must result to a boolean value, otherwise an error is signaled and the rule will not be created. The rule will fire if the condition evaluates to "true". In the following example the rule will fire of the gradient of question "measurement" is above 1 during the last 10 seconds.
%%Rule IF eval(gradient(measurement[-10s, 0s]) > 1) THEN ... %
For rule actions the expression can be used to assign the resulting value to an abstract question. The expression is also surrounded by eval(...), preceded by the question to be assigned. Please note that the questions type must be compatible to the result of the expression, otherwise an error is signaled and the rule will not be created. In the following example the question myGradient will be assigned to the gradient, the question "measurement" had during the last 10 seconds:
%%Rule IF measurement = known THEN myGradient = eval(gradient(measurement[-10s, 0s]) ) %
Using the markup %%Variable you can directly assign the result of an expression to an existing question. Please note that the questions type must be compatible to the result of the expression, otherwise an error is signaled and the assignment will not be created. Unlike using the expressions in rules, no eval(...) is required. The assignment is always kept up-to-date, so the value of the assigned question is never outdated.
%%Variable myGradient = gradient( measurement[-10s,0s] )
Constants are helpful to define values that have a special meaning and therefore naming it. Those constants can be of any type (e.g. number, date, boolean) and can be used in any expression instead the direct value. This gives you the possibility to also alter the constant's value in the wiki without altering all the usages of the value.
Defining a constant is identical to defining a direct question assignment, but instead of a predefined question the constant name is to be written left to the expression. The type of the constant is automatically derived by the result of the expression. Note that defining a constant, neither questions nor other constants are allowed to be used in the defining expression. See some examples:
// define a numeric constant %%Constant pi = 3.14159265358979323846 // define a date constant (see special date notation) %%Constant bostonTeaParty = #1773-12-16# // you may also use operators and functions %%Constant silvesterParty = #1999-12-31# + 19h + 30min %%Constant pi_of_Archimedes = 3 + 9552/67441 // using other constants is NOT ALLOWED!!! --> error signaled %%Constant invalidDeclaration = 2*pi
Expressions can also be used in the flowchart graphical editor. Similar to rules the expressions can be used as both assignments in nodes and conditions on arrows.
You can write expression in a natural operator infix-notation. For mathematical calculations you can use the common operators "+", "-", "*", "/" to addition, subtraction, multiplication and division. In addition the infix operator "^" for power is also defined. The operators have their priority as usual in algebra (1: "^"; 2: "*", "/"; 3: "+", "-"). Brackets can be used to change priority of evaluation.
// examples of valid expressions 1 + 3 // result is 4 2 ^ 16 - 1 // result is 65635 2 ^ (16 - 1) // result is 32768
Each element in an expression has a defined result type. The following types are defined: numbers, booleans, durations, time-points and strings. In the examples above, only numbers are used. By typing a number in an expression you have defined a literal constant. But also the other types have their literal constants to be used in expressions:
Type | Syntax | Description / Example |
---|---|---|
Number | <DD> <DD>.<DD> <DD>.<DD>e+-<DD> | <DD> is any number character sequence. Defines a number literal constant, either an integer number or an rational number or a floating point number in exponent notation. Examples are "12" or "125.17" or "1.1e-23". |
Boolean | "true" "false" | Defines a boolean literal constant either being true or false. |
Duration | <NUMBER>"ms" <NUMBER>"s" or "sec" <NUMBER>"min" <NUMBER>"h" <NUMBER>"d" | <NUMBER> is a number literal constant as described above. It is appended by a duration unit which may be "ms" for milliseconds, "s" or "sec" for seconds, "min" for minutes, "h" for "hours" or "d" for days. Examples are "1.5d" for 36 hours of time or "1s" for one second. |
Time-Point | #YYYY-MM-DD# | Defines a date as a time-point, where "YYYY" is the year, "MM" is the month (1-12) and "DD" is the day of the month. The time-point literal is always at 0:00 o'clock of the specified date. If a special time is meant, simply add a duration to the date. Examples are "#2000-01-01#" for the millenium sylvester and "#1999-12-31# + 19h" for the party starting at 7pm the day before. |
String | '<any_characters_here>' | Defines a string literal constant. Please note the single quotes to be used for string literals. If the string shall contain a single quote character use "\'" inside the string literal. Examples are "'my string'" or "'quote means \' here'". |
For each type there is also a history of that type available. A history is the evolution of a single value over a certain range in time. A history consists of a sequence of past values. Each value is associated with a time-point when the value has been set. For a history, each value is assumed to be valid from its time-point until the next value of the history has been set.
For comparing values the operators "=" (or "==", which is identical), "<", "<=", ">", ">=" and "!=" are defined. The result of these compare operators are a boolean value, "true" or "false" to be more precise. For booleans there are also some additional infix operators defined: "&" for "logical and" and "|" for "logical or", as well as "&&" and "||" which are identical to "&" and "|". You can also use "!" for logical negation.
// example comparators 1 >= 3 // true 2^16-1 == 65535 // true // example boolean operators true & false // false true | false // true true & !false // true
There are a lot of functions provided, that can be applied to a set of arguments. See function reference table for a complete set of all available functions. Each function has a number of signatures describing the arguments allowed to be used for the function.
A function is called by writing the function name followed by brackets. Inside the brackets the arguments of the function can be listed, separated by ",". Examples of functions are:
floor( 3.23 ) // results to 3 average( 1, 2, 3, 4 ) // results to 2.5
Each of the infix operators available have also a corresponding function. By looking in the function reference table you can see to what argument types the operators can be applied to.
Operator | Function | Desciption |
---|---|---|
^ | pow | Returns the value of the first argument raised to the power of the second argument. |
* | mult | Returns the product of the two arguments. |
/ | div | Returns the ratio of the two arguments. |
+ | plus | Returns the sum of the two arguments. |
- | minus | Returns the difference of the two arguments. |
! | not | Returns true, if the argument is false, and vica verse. |
&, && | and | Returns false, if one argument is false. |
|, || | or | Returns true, if one argument is true. |
=, == | equal | Returns true, if both argument are equal, false otherwise. |
!= | unequal | Returns true, if both argument are not equal, false otherwise. |
< | lt | Returns true, if the first argument is less than the second one, false otherwise. |
<= | le | Returns true, if the first argument is less or equal than the second one, false otherwise. |
> | gt | Returns true, if the first argument is greater than the second one, false otherwise. |
>= | ge | Returns true, if the first argument is greater or equal than the second one, false otherwise. |
[] | -- | Access the full history to a certain question. This operator has no functional equivalent. |
[...] | valueAt | Access a value of a history to a certain time. |
[..., ...] | subHistory | Access a sub-history in a certain time range. If there is not value directly at the start of the subhistory, the next earlier value will be included. |
![..., ...] | strictSubHistory | Access a sub-history in a certain time range. The sub-history will not contain values that were set before the given start. |
You can access the current value of a question by simply writing the question's or solution's name in a formula. If the name contains any non-alphanumeric characters, you can use double quotes on the name. Referring to a question or solution, the current (most recent) value is used when the expression is evaluated.
// access question values floor(myQuestion + 1) // using the current value of myQuestion floor("My special question" + 1) // using the current value of the question "My special question"
Using questions or solutions, you can also use the special []-operator, that allows you to access a past value of the object or it's whole history. Please note that this is only allowed for questions and solutions that are recorded in the time database. This is the default behaviour, but may be altered setting the object's property "history" to "false". The []-operator has different possible usages:
// access question values myQuestion[now - 10min] // using the value of myQuestion 10 minutes ago // access question histories average(myQuestion[]) // average of all values myQuestion had before (incl. current one) average(myQuestion[now-10min, now]) // average of the last 10 minutes average(myQuestion![now-10min, now]) // average of all values that were set between 10 minutes ago and now
Instead of using time-points, the operator also allows to use durations (e.g. "10min"). Using a duration means that you refer to the time the specified duration ago. Regardless to whether the duration is positive or negative, the operator always goes into the past starting at the "recent time". This "recent time" is the latest time the object has been set, but not from the global variable 'now'. Especially for rarely set objects this can make a big difference.
// using durations instead of time-points myQuestion[10min] // using the value of myQuestion 10 minutes before its latest value average(myQuestion[-10min, 0min]) // average of the last 10 minutes since the latest value average(myQuestion[10min, 0min]) // identical to the line above
Using questions in formulas, the questions will be interpreted as following:
Using solutions in formulas the solution's value is a numeric integer value as following:
You can also access the choices of the questions as constant symbols. The choices have their value defined by "1" for the first choice of a question, "2" for the second one, and so on. Since the name of choices are not unique, but identical named choices may have different values for different question, it is necessary to link the choice to the correct question.
Usually in expression you can simply write the choice, after you have used the question before. To have this simple rule, there is complex identification behind, you usually not get noticed of. Here it is how the choices are matched to their choice-questions (both, [oc] and [yn]):
As mentioned you usually not in charge to be aware of this rule. Simply use choices natural to after their questions:
myQuestion[-10s] = myChoice myQuestion = myChoice && myOtherQuestion = myOtherChoice average( myQuestion[] ) > myChoice
You can also directly refer to any choice of any question, under ignorance of all the rules above. To do that simply use the question name, append "#" and the choice name. If the question or choice contains any special characters or white-spaces use double quotes around the whole literal:
// direct access to choices myQuestion#myChoice "My special question#my special choice"
You can also access the states of a solution as constant symbols, similar to question choices. The states have their value defined by "0" if the solution is excluded, "1" for neutral, "2" for suggested and "3" for established solutions. Usually the rating states for a certain solution can be accessed by their name (e.g. "ESTABLISHED"). The behavior is identical to choice questions, thus refer to the section above for more details.
mySolution[-10s] = ESTABLISHED median( mySolution[] ) >= SUGGESTED
There is also a number of special literal tokens defined when using expression. Those tokens are:
When using questions in expressions, their values may be undefined, e.g. no value has been set to the question. In addition also functions may return undefined, e.g. calculating the average of an empty history. Most functions will return undefined if any of it's arguments is undefined. Otherwise, function's behavior on undefined values is denoted by the individual functions.
Below you see all functions that come with the TimeDB plugin by default. If you need additional functionality that is not covered by the provided functions, you might consider defining your own specialized function using Javascript. See Doc Javascript Functions for more info.
Function | Documentation |
---|---|
[] | Internal function. |
abs | Returns the absolute value of a double value. |
acos | Returns the arc cosine of a value; the returned angle is in therange 0. |
and | Returns false, if one argument is false. |
asin | Returns the arc sine of a value; the returned angle is in therange -pi/2 through pi/2. |
atan | Returns the arc tangent of a value; the returned angle is in therange -pi/2 through pi/2. |
average | Returns the average (mean) value of the one argument history or the set of the argument values. |
cbrt | Returns the cube root of a double value. |
ceil | Returns the smallest (closest to negative infinity) double value that is greater than or equal to the argument and is equal to a mathematical integer. |
cos | Returns the trigonometric cosine of an angle. |
cosh | Returns the hyperbolic cosine of a double value. |
count | Returns the number of entries of the argument history. |
date | Creates a new date with the specified YEAR, MONTH and DAY. |
dayOfMonth | Returns the day within the month specified by the given date, a value between 1 to 31 (or 30, 28, 29 respectively). |
dayOfWeek | Returns the day of week of the specified date as integer representation. |
daysOfMonth | Returns the last day of the month that contains the specified date, so it is either 28 or 29 for february or 30 or 31 for all other months. |
delta | Returns the difference between the maximum value and the minimum value of the one argument history or the set of the argument values. |
div | Returns the ratio of the two arguments. |
duration | Returns the total duration of all entries of the argument history. |
equal | Returns true, if both argument are equal, false otherwise. |
exp | Returns Euler's number e raised to the power of adouble value. |
expm1 | Returns e x -1. |
filter | Returns a new history with all the values of the given history that do not satisfy the given value or condition (combination of operator and value) being removed. |
firstChange | Returns the date when the first value of the specified history has been set. |
floor | Returns the largest (closest to positive infinity) double value that is less than or equal to the argument and is equal to a mathematical integer. |
ge | Returns true, if the first argument is greater or equal than the second one, false otherwise. |
gradient | Returns the total increase of a linear fitted line within the given (sub-)history. |
gt | Returns true, if the first argument is greater than the second one, false otherwise. |
hour | Returns the hour of a given date. |
if | Checks the first argument as the condition and returns one of the following arguments as the result of the if-function. |
invalidCount | Returns the number of invalid entries of the argument history. |
invalidDuration | Returns the total duration of the invalid entries of the argument history. |
invalidDurationRatio | Returns the ratio of invalid entrys' durations of the argument history compared to the total duration of all its entries. |
invalidRatio | Returns the ratio of invalid entries of the argument history compared to the number of its total entries. |
isNewer | Returns 'lastChange' of the first history is newer as the 'lastChange' time of the second history. |
known | Checks if the specified value is valid (known). |
latestChange | Returns the date when the most recent value of the specified history has been set. |
latestValue | Returns the most recent value stored in the specified history or histories. |
le | Returns true, if the first argument is less or equal than the second one, false otherwise. |
log | Returns the natural logarithm (base e) of a double value. |
log10 | Returns the base 10 logarithm of a double value. |
log1p | Returns the natural logarithm of the sum of the argument and 1. |
lt | Returns true, if the first argument is less than the second one, false otherwise. |
max | Returns the maximum value of the one argument history or the set of the argument values. |
median | This is an implementation of the median function. |
min | Returns the minimum value of the one argument history or the set of the argument values. |
minus | Returns the difference of the two arguments. |
minute | Returns the minute of a given date, from 0 to 59. |
mod | Returns the remainder of the of the two arguments. |
month | Returns the month as a number for a given date, i. |
mult | Returns the product of the two arguments. |
neg | Returns the negated value of the argument. |
not | Returns true, if the argument is false, and vica verse. |
or | Returns true, if one argument is true. |
percentEqual | Returns the percentage (between 0 - 1) of the time the specified history has been equal to the specified value. |
percentGe | Returns the percentage (between 0 - 1) of the time the specified history has been greater or equal than the specified value. |
percentGt | Returns the percentage (between 0 - 1) of the time the specified history has been less than the specified value. |
percentIn | Returns the percentage (between 0 - 1) of the time the specified history has been in between the specified min and max value (limits included). |
percentLe | Returns the percentage (between 0 - 1) of the time the specified history has been less or equal than the specified value. |
percentLt | Returns the percentage (between 0 - 1) of the time the specified history has been greater than the specified value. |
percentUnequal | Returns the percentage (between 0 - 1) of the time the specified history has been different to the specified value. |
plus | Returns the sum of the two arguments. |
pow | Returns the value of the first argument raised to the power of the second argument. |
rint | Returns the double value that is closest in value to the argument and is equal to a mathematical integer. |
round | Returns the closest int to the argument. |
second | Returns the second of a given date, from 0 to 59. |
signum | Returns the signum function of the argument; zero if the argument is zero, 1. |
sin | Returns the trigonometric sine of an angle. |
since | Returns the date since the value of the specified history remains unchanged. |
sinh | Returns the hyperbolic sine of a double value. |
sqrt | Returns the correctly rounded positive square root of a double value. |
strictSubHistory | Access a sub-history in a certain time range. |
subHistory | Access a sub-history in a certain time range. |
tan | Returns the trigonometric tangent of an angle. |
tanh | Returns the hyperbolic tangent of a double value. |
toDegrees | Converts an angle measured in radians to an approximatelyequivalent angle measured in degrees. |
toRadians | Converts an angle measured in degrees to an approximatelyequivalent angle measured in radians. |
unequal | Returns true, if both argument are not equal, false otherwise. |
validCount | Returns the number of valid entries of the argument history. |
validDuration | Returns the total duration of the valid entries of the argument history. |
validDurationRatio | Returns the ratio of valid entrys' durations of the argument history compared to the total duration of all its entries. |
validRatio | Returns the ratio of valid entries of the argument history compared to the number of its total entries. |
valids | Removes all invalid values from the history. |
valueAt | Access a value of a history to a certain time. |
year | Returns the year of a given date. |
(Implemented in cc.d3web.expression.eval.FullHistoryFunction)
HISTORY_BOOLEAN -> HISTORY_BOOLEAN HISTORY_DATE -> HISTORY_DATE HISTORY_DURATION -> HISTORY_DURATION HISTORY_NUMBER -> HISTORY_NUMBER HISTORY_STRING -> HISTORY_STRING
Internal function. Returns the specified history as it is.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER DURATION -> DURATION
Returns the absolute value of a double value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. Special cases:
Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the arc cosine of a value; the returned angle is in therange 0.0 through pi. Special case:
The computed result must be within 1 ulp of the exact result.Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.LogicalOperator)
BOOLEAN x BOOLEAN -> BOOLEAN
Returns false, if one argument is false. Returns true, if both arguments are true. Otherwise it returns undefined. Instead of the function you can also use the inline operator '&'.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the arc sine of a value; the returned angle is in therange -pi/2 through pi/2. Special cases:
The computed result must be within 1 ulp of the exact result.Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the arc tangent of a value; the returned angle is in therange -pi/2 through pi/2. Special cases:
The computed result must be within 1 ulp of the exact result.Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.MinMaxFunction)
HISTORY_NUMBER -> NUMBER HISTORY_DURATION -> DURATION HISTORY_DATE -> DATE HISTORY_BOOLEAN -> BOOLEAN
NUMBER x NUMBER -> NUMBER DURATION x DURATION -> DURATION DATE x DATE -> DATE BOOLEAN x BOOLEAN -> BOOLEAN
NUMBER x NUMBER x NUMBER -> NUMBER DURATION x DURATION x DURATION -> DURATION DATE x DATE x DATE -> DATE BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN
NUMBER x NUMBER x NUMBER x NUMBER -> NUMBER DURATION x DURATION x DURATION x DURATION -> DURATION DATE x DATE x DATE x DATE -> DATE BOOLEAN x BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN
Returns the average (mean) value of the one argument history or the set of the argument values. Invalid values in history or arguments are ignored. A minimum is returned as long as there is at least one valid value in history or arguments.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the cube root of a double value. For positive finite x, cbrt(-x) == -cbrt(x); that is, the cube root of a negative value is the negative of the cube root of that value's magnitude. Special cases:
The computed result must be within 1 ulp of the exact result.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the smallest (closest to negative infinity) double value that is greater than or equal to the argument and is equal to a mathematical integer. Special cases:
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the trigonometric cosine of an angle. Special cases:
The computed result must be within 1 ulp of the exact result.Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the hyperbolic cosine of a double value. The hyperbolic cosine of x is defined to be (e x + e -x )/2 where e is Euler's number.
Special cases:
The computed result must be within 2.5 ulps of the exact result.
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> NUMBER HISTORY_DATE -> NUMBER HISTORY_DURATION -> NUMBER HISTORY_NUMBER -> NUMBER HISTORY_STRING -> NUMBER
Returns the number of entries of the argument history. It is not taken into consideration whether the entry's values are valid or not.
(Implemented in cc.d3web.expression.eval.DateFunction)
NUMBER x NUMBER x NUMBER -> DATE
Creates a new date with the specified YEAR, MONTH and DAY. The argument MONTH must be between 1 and 12, and the DAY between 1 and the total days of the specific month. If any of the arguments is undefined, the function also returns undefined.
(Implemented in cc.d3web.expression.eval.DateFunction)
DATE -> NUMBER
Returns the day within the month specified by the given date, a value between 1 to 31 (or 30, 28, 29 respectively).
(Implemented in cc.d3web.expression.eval.DateFunction)
DATE -> NUMBER
Returns the day of week of the specified date as integer representation. That is, Sunday = 1, Monday = 2... Saturday = 7.
(Implemented in cc.d3web.expression.eval.DateFunction)
DATE -> NUMBER
Returns the last day of the month that contains the specified date, so it is either 28 or 29 for february or 30 or 31 for all other months. Be careful not to mix it up with 'dayOfMonth' which returns the day of the specified date, instead of the month's last day.
(Implemented in cc.d3web.expression.eval.MinMaxFunction)
HISTORY_NUMBER -> NUMBER HISTORY_DURATION -> DURATION HISTORY_DATE -> DATE HISTORY_BOOLEAN -> BOOLEAN
NUMBER x NUMBER -> NUMBER DURATION x DURATION -> DURATION DATE x DATE -> DATE BOOLEAN x BOOLEAN -> BOOLEAN
NUMBER x NUMBER x NUMBER -> NUMBER DURATION x DURATION x DURATION -> DURATION DATE x DATE x DATE -> DATE BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN
NUMBER x NUMBER x NUMBER x NUMBER -> NUMBER DURATION x DURATION x DURATION x DURATION -> DURATION DATE x DATE x DATE x DATE -> DATE BOOLEAN x BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN
Returns the difference between the maximum value and the minimum value of the one argument history or the set of the argument values. Invalid values in history or arguments are ignored. A delta is returned as long as there are at least two valid values in history or arguments.
(Implemented in cc.d3web.expression.eval.NumberOperator)
NUMBER x NUMBER -> NUMBER DURATION x NUMBER -> DURATION DURATION x DURATION -> NUMBER
Returns the ratio of the two arguments. The result is always a floating pointed value.You may also use the inline operator '/'
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> DURATION HISTORY_DATE -> DURATION HISTORY_DURATION -> DURATION HISTORY_NUMBER -> DURATION HISTORY_STRING -> DURATION
Returns the total duration of all entries of the argument history. It is not taken into consideration whether the entry's values are valid or not. If the time span of a history entry exceeds the time span of the history only the time span within the history's time span is considered.
(Implemented in cc.d3web.expression.eval.LogicalOperator)
BOOLEAN x BOOLEAN -> BOOLEAN HISTORY_BOOLEAN x BOOLEAN -> BOOLEAN BOOLEAN x HISTORY_BOOLEAN -> BOOLEAN STRING x STRING -> BOOLEAN HISTORY_STRING x STRING -> BOOLEAN STRING x HISTORY_STRING -> BOOLEAN DURATION x DURATION -> BOOLEAN HISTORY_DURATION x DURATION -> BOOLEAN DURATION x HISTORY_DURATION -> BOOLEAN DATE x DATE -> BOOLEAN HISTORY_DATE x DATE -> BOOLEAN DATE x HISTORY_DATE -> BOOLEAN NUMBER x NUMBER -> BOOLEAN HISTORY_NUMBER x NUMBER -> BOOLEAN NUMBER x HISTORY_NUMBER -> BOOLEAN
Returns true, if both argument are equal, false otherwise. Instead of the function you can also use the inline operator '='. If one of the specified arguments is a history, it returns true if all defined values of the history holds the condition. Undefined values of the history will be ignored. If the history is empty or only contains undefined values, the method returns undefined.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns Euler's number e raised to the power of adouble value. Special cases:
The computed result must be within 1 ulp of the exact result.Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns e x -1. Note that for values ofx near 0, the exact sum of expm1(x) + 1 is much closer to the true result of e x than exp(x).
Special cases:
The computed result must be within 1 ulp of the exact result. Results must be semi-monotonic. The result of expm1 for any finite input must be greater than or equal to -1.0. Note that once the exact result of e x - 1 is within 1/2 ulp of the limit value -1, -1.0 should be returned.
(Implemented in cc.d3web.expression.eval.FilterFunction)
HISTORY_BOOLEAN x BOOLEAN -> HISTORY_BOOLEAN HISTORY_DATE x DATE -> HISTORY_DATE HISTORY_DURATION x DURATION -> HISTORY_DURATION HISTORY_NUMBER x NUMBER -> HISTORY_NUMBER HISTORY_STRING x STRING -> HISTORY_STRING
HISTORY_BOOLEAN x STRING x BOOLEAN -> HISTORY_BOOLEAN HISTORY_DATE x STRING x DATE -> HISTORY_DATE HISTORY_DURATION x STRING x DURATION -> HISTORY_DURATION HISTORY_NUMBER x STRING x NUMBER -> HISTORY_NUMBER HISTORY_STRING x STRING x STRING -> HISTORY_STRING
Returns a new history with all the values of the given history that do not satisfy the given value or condition (combination of operator and value) being removed. In this resulting history there might be time gaps in between the history entries. When accessing values for time stamps in these gaps, undefined is returned as the value. (See also function valueAt).
The type of the specified value must match the type specified history. You may optionally specify a compare operator as a string parameter. If a compare operator is specified it must be one of the following: '<', '<=', '=', '==', '!=', '>=', '>' or alternatively 'lt', 'le', 'eq', 'unequal', 'ge', 'gt'. If an other string is specified as the operator it defaults to '='.
(Implemented in cc.d3web.expression.eval.ChangeFunction)
HISTORY_ANY -> DATE
Returns the date when the first value of the specified history has been set. Please note that for sub-histories the time may be before the start time of the sub-history, because the first value has been set before that time (and is still valid at the sub-histories start time). If the specified history is empty, undefined is returned.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the largest (closest to positive infinity) double value that is less than or equal to the argument and is equal to a mathematical integer. Special cases:
(Implemented in cc.d3web.expression.eval.LogicalOperator)
STRING x STRING -> BOOLEAN HISTORY_STRING x STRING -> BOOLEAN STRING x HISTORY_STRING -> BOOLEAN DURATION x DURATION -> BOOLEAN HISTORY_DURATION x DURATION -> BOOLEAN DURATION x HISTORY_DURATION -> BOOLEAN DATE x DATE -> BOOLEAN HISTORY_DATE x DATE -> BOOLEAN DATE x HISTORY_DATE -> BOOLEAN NUMBER x NUMBER -> BOOLEAN HISTORY_NUMBER x NUMBER -> BOOLEAN NUMBER x HISTORY_NUMBER -> BOOLEAN
Returns true, if the first argument is greater or equal than the second one, false otherwise. Instead of the function you can also use the inline operator '>='. If one of the specified arguments is a history, it returns true if all defined values of the history holds the condition. Undefined values of the history will be ignored. If the history is empty or only contains undefined values, the method returns undefined.
(Implemented in cc.d3web.expression.eval.analysis.GradientFunction)
HISTORY_NUMBER -> NUMBER
HISTORY_NUMBER x DURATION -> NUMBER
Returns the total increase of a linear fitted line within the given (sub-)history.
Computes the best fit (least squares) line y = ax + b through the set of points given by the argument history. The slope a is multiplied by the duration between the timestaps of the first and the last element within the specified history. The multiplication result is returned.
As a special case, the gradient is defined as 0.0, if the argument history contains only one element.
If the history has any undefined values, these values are ignored and the gradient of the other values is calculated.
As an optional argument a duration can be specified that is used instead of the the duration between the first and the last history entry (also undefined entries are considered!), to be used for multiplication. Then the result will be the average increase of the histories values per this duration. Note that if the duration is longer than the history, the increase will be forecasted by assuming to remain constant (in average).
(Implemented in cc.d3web.expression.eval.LogicalOperator)
STRING x STRING -> BOOLEAN HISTORY_STRING x STRING -> BOOLEAN STRING x HISTORY_STRING -> BOOLEAN DURATION x DURATION -> BOOLEAN HISTORY_DURATION x DURATION -> BOOLEAN DURATION x HISTORY_DURATION -> BOOLEAN DATE x DATE -> BOOLEAN HISTORY_DATE x DATE -> BOOLEAN DATE x HISTORY_DATE -> BOOLEAN NUMBER x NUMBER -> BOOLEAN HISTORY_NUMBER x NUMBER -> BOOLEAN NUMBER x HISTORY_NUMBER -> BOOLEAN
Returns true, if the first argument is greater than the second one, false otherwise. Instead of the function you can also use the inline operator '>'. If one of the specified arguments is a history, it returns true if all defined values of the history holds the condition. Undefined values of the history will be ignored. If the history is empty or only contains undefined values, the method returns undefined.
(Implemented in cc.d3web.expression.eval.DateFunction)
DATE -> NUMBER
Returns the hour of a given date. Here, the 24-hour clock is assumed, i.e. midnight returns 0, noon returns 12, 10 am returns 10, 10pm returns 22, and so on. The returned value is between 0 and 23.
(Implemented in cc.d3web.expression.eval.IfFunction)
BOOLEAN x BOOLEAN -> BOOLEAN BOOLEAN x DATE -> DATE BOOLEAN x DURATION -> DURATION BOOLEAN x NUMBER -> NUMBER BOOLEAN x STRING -> STRING
BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN BOOLEAN x DATE x DATE -> DATE BOOLEAN x DURATION x DURATION -> DURATION BOOLEAN x NUMBER x NUMBER -> NUMBER BOOLEAN x STRING x STRING -> STRING
BOOLEAN x BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN BOOLEAN x DATE x DATE x DATE -> DATE BOOLEAN x DURATION x DURATION x DURATION -> DURATION BOOLEAN x NUMBER x NUMBER x NUMBER -> NUMBER BOOLEAN x STRING x STRING x STRING -> STRING
Checks the first argument as the condition and returns one of the following arguments as the result of the if-function.
If the first argument is 'true', the function call will result to the value of the second argument. If the first argument evaluates to 'false', the function call will result to the value of the third argument. If the first argument cannot be evaluated to a definite value ('unknown'), the function call will result to the value of the fourth argument.
If the condition if false or unknown and there is no third or fourth argument, the if-function evaluates to unknown.
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> NUMBER HISTORY_DATE -> NUMBER HISTORY_DURATION -> NUMBER HISTORY_NUMBER -> NUMBER HISTORY_STRING -> NUMBER
Returns the number of invalid entries of the argument history. Invalid entries are those entries which do not have a defined value.
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> DURATION HISTORY_DATE -> DURATION HISTORY_DURATION -> DURATION HISTORY_NUMBER -> DURATION HISTORY_STRING -> DURATION
Returns the total duration of the invalid entries of the argument history. Invalid entries are those entries which do not have a defined value. If the time span of a history entry exceeds the time spand of the history only the time span within the history's time span is considered.
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> NUMBER HISTORY_DATE -> NUMBER HISTORY_DURATION -> NUMBER HISTORY_NUMBER -> NUMBER HISTORY_STRING -> NUMBER
Returns the ratio of invalid entrys' durations of the argument history compared to the total duration of all its entries. If the history has no entires at all, '0' is returned to reflect that there are no invalid entries within the history. If the time span of a history entry exceeds the time spand of the history only the time span within the history's time span is considered.
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> NUMBER HISTORY_DATE -> NUMBER HISTORY_DURATION -> NUMBER HISTORY_NUMBER -> NUMBER HISTORY_STRING -> NUMBER
Returns the ratio of invalid entries of the argument history compared to the number of its total entries. If the history has no entires at all, '0' is returned to reflect that there are no invalid entries within the history.
(Implemented in cc.d3web.expression.eval.ChangeFunction)
HISTORY_ANY x HISTORY_ANY -> BOOLEAN
Returns 'lastChange' of the first history is newer as the 'lastChange' time of the second history. It returns false if both have been updated at the same time. If any of the specified histories are empty, undefined is returned.
(Implemented in cc.d3web.expression.eval.KnownFunction)
BOOLEAN -> BOOLEAN DATE -> BOOLEAN DURATION -> BOOLEAN NUMBER -> BOOLEAN STRING -> BOOLEAN
Checks if the specified value is valid (known). It is usually used when accessing question values to check if the value has a known and defined value. If a question is not answered or answered by 'unknown' false is returned, true otherwise.
(Implemented in cc.d3web.expression.eval.ChangeFunction)
HISTORY_ANY -> DATE
Returns the date when the most recent value of the specified history has been set. If the specified history is empty, undefined is returned.
(Implemented in cc.d3web.expression.eval.ChangeFunction)
HISTORY_BOOLEAN -> BOOLEAN HISTORY_DATE -> DATE HISTORY_DURATION -> DURATION HISTORY_NUMBER -> NUMBER HISTORY_STRING -> STRING
HISTORY_BOOLEAN x HISTORY_BOOLEAN -> BOOLEAN HISTORY_DATE x HISTORY_DATE -> DATE HISTORY_DURATION x HISTORY_DURATION -> DURATION HISTORY_NUMBER x HISTORY_NUMBER -> NUMBER HISTORY_STRING x HISTORY_STRING -> STRING
HISTORY_BOOLEAN x HISTORY_BOOLEAN x HISTORY_BOOLEAN -> BOOLEAN HISTORY_DATE x HISTORY_DATE x HISTORY_DATE -> DATE HISTORY_DURATION x HISTORY_DURATION x HISTORY_DURATION -> DURATION HISTORY_NUMBER x HISTORY_NUMBER x HISTORY_NUMBER -> NUMBER HISTORY_STRING x HISTORY_STRING x HISTORY_STRING -> STRING
Returns the most recent value stored in the specified history or histories. If two histories have values with the same most recent start timestamp, the value of the first specified history is returned. If any of the specified histories is empty, it is ignored. If all specified histories are empty, undefined is returned.
(Implemented in cc.d3web.expression.eval.LogicalOperator)
STRING x STRING -> BOOLEAN HISTORY_STRING x STRING -> BOOLEAN STRING x HISTORY_STRING -> BOOLEAN DURATION x DURATION -> BOOLEAN HISTORY_DURATION x DURATION -> BOOLEAN DURATION x HISTORY_DURATION -> BOOLEAN DATE x DATE -> BOOLEAN HISTORY_DATE x DATE -> BOOLEAN DATE x HISTORY_DATE -> BOOLEAN NUMBER x NUMBER -> BOOLEAN HISTORY_NUMBER x NUMBER -> BOOLEAN NUMBER x HISTORY_NUMBER -> BOOLEAN
Returns true, if the first argument is less or equal than the second one, false otherwise. Instead of the function you can also use the inline operator '<='. If one of the specified arguments is a history, it returns true if all defined values of the history holds the condition. Undefined values of the history will be ignored. If the history is empty or only contains undefined values, the method returns undefined.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the natural logarithm (base e) of a double value. Special cases:
The computed result must be within 1 ulp of the exact result. Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the base 10 logarithm of a double value. Special cases:
The computed result must be within 1 ulp of the exact result. Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the natural logarithm of the sum of the argument and 1. Note that for small values x, the result of log1p(x) is much closer to the true result of ln(1 + x) than the floating-point evaluation of log(1.0+x).
Special cases:
The computed result must be within 1 ulp of the exact result. Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.LogicalOperator)
STRING x STRING -> BOOLEAN HISTORY_STRING x STRING -> BOOLEAN STRING x HISTORY_STRING -> BOOLEAN DURATION x DURATION -> BOOLEAN HISTORY_DURATION x DURATION -> BOOLEAN DURATION x HISTORY_DURATION -> BOOLEAN DATE x DATE -> BOOLEAN HISTORY_DATE x DATE -> BOOLEAN DATE x HISTORY_DATE -> BOOLEAN NUMBER x NUMBER -> BOOLEAN HISTORY_NUMBER x NUMBER -> BOOLEAN NUMBER x HISTORY_NUMBER -> BOOLEAN
Returns true, if the first argument is less than the second one, false otherwise. Instead of the function you can also use the inline operator '<'. If one of the specified arguments is a history, it returns true if all defined values of the history holds the condition. Undefined values of the history will be ignored. If the history is empty or only contains undefined values, the method returns undefined.
(Implemented in cc.d3web.expression.eval.MinMaxFunction)
HISTORY_NUMBER -> NUMBER HISTORY_DURATION -> DURATION HISTORY_DATE -> DATE HISTORY_BOOLEAN -> BOOLEAN HISTORY_STRING -> STRING
NUMBER x NUMBER -> NUMBER DURATION x DURATION -> DURATION DATE x DATE -> DATE BOOLEAN x BOOLEAN -> BOOLEAN STRING x STRING -> STRING
NUMBER x NUMBER x NUMBER -> NUMBER DURATION x DURATION x DURATION -> DURATION DATE x DATE x DATE -> DATE BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN STRING x STRING x STRING -> STRING
NUMBER x NUMBER x NUMBER x NUMBER -> NUMBER DURATION x DURATION x DURATION x DURATION -> DURATION DATE x DATE x DATE x DATE -> DATE BOOLEAN x BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN STRING x STRING x STRING x STRING -> STRING
Returns the maximum value of the one argument history or the set of the argument values. Invalid values in history or arguments are ignored. A maximum is returned as long as there is at least one valid value in history or arguments.
(Implemented in cc.d3web.expression.eval.analysis.MedianFunction)
HISTORY_NUMBER -> NUMBER
This is an implementation of the median function. It searches the median of the {@link HistoryEntry}s within the specified numeric history (HISTORY_NUMBER).
If the number of entries to the history is even, the lower median is returned. It is guaranteed that the returned median is always an existing entry of the history. This allows the function also to be used e.g. for choice values. The duration of the history entries is not taken into consideration. Therefore the values are not 'weighted' by the time they has been valid. If the history has any undefined values, these values are ignored and the median of the other values is calculated.
The function returns either the non-null median element of the history or null if (and only if) there are no non-null values within the history.
(Implemented in cc.d3web.expression.eval.MinMaxFunction)
HISTORY_NUMBER -> NUMBER HISTORY_DURATION -> DURATION HISTORY_DATE -> DATE HISTORY_BOOLEAN -> BOOLEAN HISTORY_STRING -> STRING
NUMBER x NUMBER -> NUMBER DURATION x DURATION -> DURATION DATE x DATE -> DATE BOOLEAN x BOOLEAN -> BOOLEAN STRING x STRING -> STRING
NUMBER x NUMBER x NUMBER -> NUMBER DURATION x DURATION x DURATION -> DURATION DATE x DATE x DATE -> DATE BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN STRING x STRING x STRING -> STRING
NUMBER x NUMBER x NUMBER x NUMBER -> NUMBER DURATION x DURATION x DURATION x DURATION -> DURATION DATE x DATE x DATE x DATE -> DATE BOOLEAN x BOOLEAN x BOOLEAN x BOOLEAN -> BOOLEAN STRING x STRING x STRING x STRING -> STRING
Returns the minimum value of the one argument history or the set of the argument values. Invalid values in history or arguments are ignored. A minimum is returned as long as there is at least one valid value in history or arguments.
(Implemented in cc.d3web.expression.eval.NumberOperator)
NUMBER x NUMBER -> NUMBER DATE x DURATION -> DATE DATE x DATE -> DURATION DURATION x DURATION -> DURATION
Returns the difference of the two arguments. You may also use the inline operator '-'
(Implemented in cc.d3web.expression.eval.DateFunction)
DATE -> NUMBER
Returns the minute of a given date, from 0 to 59.
(Implemented in cc.d3web.expression.eval.NumberOperator)
NUMBER x NUMBER -> NUMBER DURATION x DURATION -> DURATION
Returns the remainder of the of the two arguments. The remainder is the rest when calculating the integer-ratio of both. You may also use the inline operator '%'
(Implemented in cc.d3web.expression.eval.DateFunction)
DATE -> NUMBER
Returns the month as a number for a given date, i.e. 1 for January, 2 for February, and so on.
(Implemented in cc.d3web.expression.eval.NumberOperator)
NUMBER x NUMBER -> NUMBER DURATION x NUMBER -> DURATION NUMBER x DURATION -> DURATION
Returns the product of the two arguments. You may also use the inline operator '*'
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER DURATION -> DURATION
Returns the negated value of the argument.
(Implemented in cc.d3web.expression.eval.LogicalOperator)
BOOLEAN -> BOOLEAN
Returns true, if the argument is false, and vica verse. Instead of the function you can also use the inline operator '!'.
(Implemented in cc.d3web.expression.eval.LogicalOperator)
BOOLEAN x BOOLEAN -> BOOLEAN
Returns true, if one argument is true. Returns false, if both arguments are false. Otherwise it returns undefined. Instead of the function you can also use the inline operator '|'.
(Implemented in cc.d3web.expression.eval.CorridorFunction)
HISTORY_BOOLEAN x BOOLEAN -> NUMBER HISTORY_STRING x STRING -> NUMBER HISTORY_DURATION x DURATION -> NUMBER HISTORY_DATE x DATE -> NUMBER HISTORY_NUMBER x NUMBER -> NUMBER
Returns the percentage (between 0 - 1) of the time the specified history has been equal to the specified value. Time periods of undefined values are ignored. If there is no valid value in the history undefined is returned.
(Implemented in cc.d3web.expression.eval.CorridorFunction)
HISTORY_STRING x STRING -> NUMBER HISTORY_DURATION x DURATION -> NUMBER HISTORY_DATE x DATE -> NUMBER HISTORY_NUMBER x NUMBER -> NUMBER
Returns the percentage (between 0 - 1) of the time the specified history has been greater or equal than the specified value. Time periods of undefined values are ignored. If there is no valid value in the history undefined is returned.
(Implemented in cc.d3web.expression.eval.CorridorFunction)
HISTORY_STRING x STRING -> NUMBER HISTORY_DURATION x DURATION -> NUMBER HISTORY_DATE x DATE -> NUMBER HISTORY_NUMBER x NUMBER -> NUMBER
Returns the percentage (between 0 - 1) of the time the specified history has been less than the specified value. Time periods of undefined values are ignored. If there is no valid value in the history undefined is returned.
(Implemented in cc.d3web.expression.eval.CorridorFunction)
HISTORY_STRING x STRING x STRING -> NUMBER HISTORY_DURATION x DURATION x DURATION -> NUMBER HISTORY_DATE x DATE x DATE -> NUMBER HISTORY_NUMBER x NUMBER x NUMBER -> NUMBER
Returns the percentage (between 0 - 1) of the time the specified history has been in between the specified min and max value (limits included). Time periods of undefined values are ignored. If there is no valid value in the history undefined is returned.
(Implemented in cc.d3web.expression.eval.CorridorFunction)
HISTORY_STRING x STRING -> NUMBER HISTORY_DURATION x DURATION -> NUMBER HISTORY_DATE x DATE -> NUMBER HISTORY_NUMBER x NUMBER -> NUMBER
Returns the percentage (between 0 - 1) of the time the specified history has been less or equal than the specified value. Time periods of undefined values are ignored. If there is no valid value in the history undefined is returned.
(Implemented in cc.d3web.expression.eval.CorridorFunction)
HISTORY_STRING x STRING -> NUMBER HISTORY_DURATION x DURATION -> NUMBER HISTORY_DATE x DATE -> NUMBER HISTORY_NUMBER x NUMBER -> NUMBER
Returns the percentage (between 0 - 1) of the time the specified history has been greater than the specified value. Time periods of undefined values are ignored. If there is no valid value in the history undefined is returned.
(Implemented in cc.d3web.expression.eval.CorridorFunction)
HISTORY_BOOLEAN x BOOLEAN -> NUMBER HISTORY_STRING x STRING -> NUMBER HISTORY_DURATION x DURATION -> NUMBER HISTORY_DATE x DATE -> NUMBER HISTORY_NUMBER x NUMBER -> NUMBER
Returns the percentage (between 0 - 1) of the time the specified history has been different to the specified value. Time periods of undefined values are ignored. If there is no valid value in the history undefined is returned.
(Implemented in cc.d3web.expression.eval.NumberOperator)
NUMBER x NUMBER -> NUMBER DURATION x DURATION -> DURATION DATE x DURATION -> DATE DURATION x DATE -> DATE STRING x ANY -> STRING ANY x STRING -> STRING
Returns the sum of the two arguments. You may also use the inline operator '+'
(Implemented in cc.d3web.expression.eval.NumberOperator)
NUMBER x NUMBER -> NUMBER
Returns the value of the first argument raised to the power of the second argument. You may also use the inline operator '^'.
Special cases:
(In the foregoing descriptions, a floating-point value is considered to be an integer if and only if it is finite and a fixed point of the method {@link #ceil <tt>ceil</tt>} or, equivalently, a fixed point of the method {@link #floor <tt>floor</tt>}. A value is a fixed point of a one-argument method if and only if the result of applying the method to the value is equal to the value.)
The computed result must be within 1 ulp of the exact result. Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the double value that is closest in value to the argument and is equal to a mathematical integer. If two double values that are mathematical integers are equally close, the result is the integer value that is even. Special cases:
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the closest int to the argument. The result is rounded to an integer by adding 1/2, taking the floor of the result, and casting the result to type int. In other words, the result is equal to the value of the expression:
(int)Math.floor(a + 0.5f)
Special cases:
(Implemented in cc.d3web.expression.eval.DateFunction)
DATE -> NUMBER
Returns the second of a given date, from 0 to 59.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the signum function of the argument; zero if the argument is zero, 1.0 if the argument is greater than zero, -1.0 if the argument is less than zero.
Special Cases:
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the trigonometric sine of an angle. Special cases:
The computed result must be within 1 ulp of the exact result.Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.ChangeFunction)
HISTORY_ANY -> DATE
Returns the date since the value of the specified history remains unchanged. The function therefore ignores any value entries in the history that has not altered the value. If the specified history is empty, undefined is returned.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the hyperbolic sine of a double value. The hyperbolic sine of x is defined to be (e x - e -x )/2 where e is Euler's number.
Special cases:
The computed result must be within 2.5 ulps of the exact result.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the correctly rounded positive square root of a double value. Special cases:
(Implemented in cc.d3web.expression.eval.StrictSubHistoryFunction)
HISTORY_BOOLEAN x DATE x DATE -> HISTORY_BOOLEAN HISTORY_DATE x DATE x DATE -> HISTORY_DATE HISTORY_DURATION x DATE x DATE -> HISTORY_DURATION HISTORY_NUMBER x DATE x DATE -> HISTORY_NUMBER HISTORY_STRING x DATE x DATE -> HISTORY_STRING HISTORY_BOOLEAN x DURATION x DURATION -> HISTORY_BOOLEAN HISTORY_DATE x DURATION x DURATION -> HISTORY_DATE HISTORY_DURATION x DURATION x DURATION -> HISTORY_DURATION HISTORY_NUMBER x DURATION x DURATION -> HISTORY_NUMBER HISTORY_STRING x DURATION x DURATION -> HISTORY_STRING
Access a sub-history in a certain time range. There is no special order of the 'START' or 'END' parameters required, the sub-history starts at the earlier time point an lasts to the later one. If the history has no values within the specified time range, an empty history is returned. If the requested sub-history starts before the history it is taken from, the start time is the latter one. Please note that only history entries at or after the requested start time will be used as the result of the strict-sub-history. This is the difference to the 'subHistory' function.
If you specify a duration instead of a time for the 'START' or 'END' parameter, the time to be used is calculated relatively to the history's last entry. Regardless whether the value is positive or negative, the used date is the specified time before the history's end. Due to avoid confusion, it is not allowed to mix date and duration as arguments.
Examples:
You may also use the inline operator «HISTORY»![«START» , «END»].
(Implemented in cc.d3web.expression.eval.SubHistoryFunction)
HISTORY_BOOLEAN x DATE x DATE -> HISTORY_BOOLEAN HISTORY_DATE x DATE x DATE -> HISTORY_DATE HISTORY_DURATION x DATE x DATE -> HISTORY_DURATION HISTORY_NUMBER x DATE x DATE -> HISTORY_NUMBER HISTORY_STRING x DATE x DATE -> HISTORY_STRING HISTORY_BOOLEAN x DURATION x DURATION -> HISTORY_BOOLEAN HISTORY_DATE x DURATION x DURATION -> HISTORY_DATE HISTORY_DURATION x DURATION x DURATION -> HISTORY_DURATION HISTORY_NUMBER x DURATION x DURATION -> HISTORY_NUMBER HISTORY_STRING x DURATION x DURATION -> HISTORY_STRING
Access a sub-history in a certain time range. There is no special order of the 'START' or 'END' parameters required, the sub-history starts at the earlier time point an lasts to the later one. If the history has no values within the specified time range, an empty history is returned. If the requested sub-history starts before the history it is taken from, the start time is the latter one. If the earlier time does not match exactly an existing entry within the history the latest entry before the requested time is used as the first entry of the strict-sub-history.
If you specify a duration instead of a time for the 'START' or 'END' parameter, the time to be used is calculated relatively to the history's last entry. Regardless whether the value is positive or negative, the used date is the specified time before the history's end. Due to avoid confusion, it is not allowed to mix date and duration as arguments.
Examples:
You may also use the inline operator «HISTORY»[«START» , «END»].
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the trigonometric tangent of an angle. Special cases:
The computed result must be within 1 ulp of the exact result.Results must be semi-monotonic.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Returns the hyperbolic tangent of a double value. The hyperbolic tangent of x is defined to be (e x - e -x )/(e x + e -x ), in other words, sinh(x)/cosh(x). Note that the absolute value of the exact tanh is always less than 1.
Special cases:
The computed result must be within 2.5 ulps of the exact result. The result of tanh for any finite input must have an absolute value less than or equal to 1. Note that once the exact result of tanh is within 1/2 of an ulp of the limit value of ±1, correctly signed ±1.0 should be returned.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Converts an angle measured in radians to an approximatelyequivalent angle measured in degrees. The conversion fromradians to degrees is generally inexact; users shouldnot expect cos(toRadians(90.0)) to exactlyequal 0.0.
(Implemented in cc.d3web.expression.eval.UnaryMathFunction)
NUMBER -> NUMBER
Converts an angle measured in degrees to an approximatelyequivalent angle measured in radians. The conversion fromdegrees to radians is generally inexact.
(Implemented in cc.d3web.expression.eval.LogicalOperator)
BOOLEAN x BOOLEAN -> BOOLEAN HISTORY_BOOLEAN x BOOLEAN -> BOOLEAN BOOLEAN x HISTORY_BOOLEAN -> BOOLEAN STRING x STRING -> BOOLEAN HISTORY_STRING x STRING -> BOOLEAN STRING x HISTORY_STRING -> BOOLEAN DURATION x DURATION -> BOOLEAN HISTORY_DURATION x DURATION -> BOOLEAN DURATION x HISTORY_DURATION -> BOOLEAN DATE x DATE -> BOOLEAN HISTORY_DATE x DATE -> BOOLEAN DATE x HISTORY_DATE -> BOOLEAN NUMBER x NUMBER -> BOOLEAN HISTORY_NUMBER x NUMBER -> BOOLEAN NUMBER x HISTORY_NUMBER -> BOOLEAN
Returns true, if both argument are not equal, false otherwise. Instead of the function you can also use the inline operator '!='. If one of the specified arguments is a history, it returns true if all defined values of the history holds the condition. Undefined values of the history will be ignored. If the history is empty or only contains undefined values, the method returns undefined.
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> NUMBER HISTORY_DATE -> NUMBER HISTORY_DURATION -> NUMBER HISTORY_NUMBER -> NUMBER HISTORY_STRING -> NUMBER
Returns the number of valid entries of the argument history. Valid entries are those entries which have a defined value.
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> DURATION HISTORY_DATE -> DURATION HISTORY_DURATION -> DURATION HISTORY_NUMBER -> DURATION HISTORY_STRING -> DURATION
Returns the total duration of the valid entries of the argument history. Valid entries are those entries which have a defined value. If the time span of a history entry exceeds the time spand of the history only the time span within the history's time span is considered.
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> NUMBER HISTORY_DATE -> NUMBER HISTORY_DURATION -> NUMBER HISTORY_NUMBER -> NUMBER HISTORY_STRING -> NUMBER
Returns the ratio of valid entrys' durations of the argument history compared to the total duration of all its entries. If the history has no entires at all, '0' is returned to reflect that there are no valid entries within the history. If the time span of a history entry exceeds the time spand of the history only the time span within the history's time span is considered.
(Implemented in cc.d3web.expression.eval.CountFunction)
HISTORY_BOOLEAN -> NUMBER HISTORY_DATE -> NUMBER HISTORY_DURATION -> NUMBER HISTORY_NUMBER -> NUMBER HISTORY_STRING -> NUMBER
Returns the ratio of valid entries of the argument history compared to the number of its total entries. If the history has no entires at all, '0' is returned to reflect that there are no valid entries within the history.
(Implemented in cc.d3web.expression.eval.ValidsFunction)
HISTORY_BOOLEAN -> HISTORY_BOOLEAN HISTORY_DATE -> HISTORY_DATE HISTORY_DURATION -> HISTORY_DURATION HISTORY_NUMBER -> HISTORY_NUMBER HISTORY_STRING -> HISTORY_STRING
Removes all invalid values from the history. This results in a history which only contains the valid values. In this resulting history there might be time gaps in between the history entries. When accessing values for time stamps in these gaps, undefined is returned as the value. (See also function valueAt).
(Implemented in cc.d3web.expression.eval.ValueAtFunction)
HISTORY_BOOLEAN x DATE -> BOOLEAN HISTORY_DATE x DATE -> DATE HISTORY_DURATION x DATE -> DURATION HISTORY_NUMBER x DATE -> NUMBER HISTORY_STRING x DATE -> STRING HISTORY_BOOLEAN x DURATION -> BOOLEAN HISTORY_DATE x DURATION -> DATE HISTORY_DURATION x DURATION -> DURATION HISTORY_NUMBER x DURATION -> NUMBER HISTORY_STRING x DURATION -> STRING
Access a value of a history to a certain time.If you specify a duration instead of a time for the 'TIME' parameter, the time to be used is calculated relatively to the history's last entry. Regardless whether the duration is positive or negative, the used date is the specified time before the history's end.
Examples:
If you access a value for a specific time of a history, and there is no value available at the exact time, usually the latest value that has been set before the speified time is returned. Only if you create a history with time gaps (e.g. using the functions 'valids' or 'filter'), and ask for values within these time gaps, undefined is returned as the value. To access the latest available value before these gaps, use 'latestChange(«HISTORY»[start, «TIME»])'instead of 'valueAt(«HISTORY», «TIME»)'.
You may also use the inline operator «HISTORY»[«TIME»].
(Implemented in cc.d3web.expression.eval.DateFunction)
DATE -> NUMBER
Returns the year of a given date.