Doc Expressions

The functionalities described on this page are only available using a commercial extension. Please contact info@denkbares.com for more information.

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:

  1. The supported markups and how expression can be used there.
  2. The expression syntax with detailed information on the expression's capabilities.
  3. A function reference table with a list of all available functions and their documentation.

Supported Markups#

The expressions are integrated in a bunch of existing markups, as well as defining some additional markups.

Rules#

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]) )
%

Direct question assignment#

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] )

Defining Constants#

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

Flowcharts#

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.

Using expressions for assignment

Using expressions as conditions

Expression syntax#

Basic calculations#

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

Types and literals#

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.

Boolean expressions#

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

Using functions#

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.

Access question and solution values#

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:

Access question choices#

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]):

  1. If you use a choice-question in a function call, its choices are known in every following argument of that function. Thus in "equal(myQuestion, ...)", the choices of myQuestion are known at the second argument.
  2. If multiple questions are used all choices of all questions are known to the following arguments. Thus in "average(myQuestion1, myQuestion2, ...)" the third argument can refer to choices of both questions.
  3. Choices does not overwrite other literal symbols. Choices of questions will not be overwritten by the following question's choices.
  4. If a question is used in a sub-expression, being a functions argument, the choices of the question are also known at the following arguments of the function, if the sub-expression's result "still refers to the choice-question". This is a complex thing, so see the example "equal(max(myQuestion), myChoice)". Here the function max still refers the to values of myQuestion, thus myChoice can be used to refer to a choice of myQuestion. In contrast, "equal(gradient(myQuestion), myChoice)" will fail, because the gradient has a complete different meaning.
  5. Infix-operators are treated exactly as their functional notation. Thus "question = foo" is identical to "equal(question, foo)".

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"

Access solution states#

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

Special keywords#

There is also a number of special literal tokens defined when using expression. Those tokens are:

Undefined values#

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.

Function Reference#

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.

[]#

Usage: [](«HISTORY»)

(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.


abs#

Usage: abs(«NUMBER»)

(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:

In other words, the result is the same as the value of the expression:

Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)


acos#

Usage: acos(«NUMBER»)

(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.


and#

Usage: and(«BOOLEAN», «BOOLEAN»)

(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 '&'.


asin#

Usage: asin(«NUMBER»)

(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.


atan#

Usage: atan(«NUMBER»)

(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.


average#

Usage: average(«HISTORY or PRIMITIVE», «[PRIMITIVE]*»)

(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.


cbrt#

Usage: cbrt(«NUMBER»)

(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.


ceil#

Usage: ceil(«NUMBER»)

(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:


cos#

Usage: cos(«NUMBER»)

(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.


cosh#

Usage: cosh(«NUMBER»)

(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.


count#

Usage: count(«HISTORY»)

(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.


date#

Usage: date(«YEAR», «MONTH», «DAY»)

(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.


dayOfMonth#

Usage: dayOfMonth(«DATE»)

(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).


dayOfWeek#

Usage: dayOfWeek(«DATE»)

(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.


daysOfMonth#

Usage: daysOfMonth(«DATE»)

(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.


delta#

Usage: delta(«HISTORY or PRIMITIVE», «[PRIMITIVE]*»)

(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.


div#

Usage: div(«ARGUMENT», «ARGUMENT»)

(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 '/'


duration#

Usage: duration(«HISTORY»)

(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.


equal#

Usage: equal(«ARGUMENT», «ARGUMENT»)

(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.


exp#

Usage: exp(«NUMBER»)

(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.


expm1#

Usage: expm1(«NUMBER»)

(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.


filter#

Usage: filter(«HISTORY», «[OPERATOR]», «VALUE»)

(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: '<', '<=', '=', '==', '!=', '>=', '&gt' or alternatively 'lt', 'le', 'eq', 'unequal', 'ge', 'gt'. If an other string is specified as the operator it defaults to '='.


firstChange#

Usage: firstChange(«HISTORY»)

(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.


floor#

Usage: floor(«NUMBER»)

(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:


ge#

Usage: ge(«ARGUMENT», «ARGUMENT»)

(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.


gradient#

Usage: gradient(«NUMBER HISTORY», «[BASE_DURATION]»)

(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).


gt#

Usage: gt(«ARGUMENT», «ARGUMENT»)

(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.


hour#

Usage: hour(«DATE»)

(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.


if#

Usage: if(«CONDITION», «THEN», «[ELSE]», «[UNKNOWN]»)

(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.


invalidCount#

Usage: invalidCount(«HISTORY»)

(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.


invalidDuration#

Usage: invalidDuration(«HISTORY»)

(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.


invalidDurationRatio#

Usage: invalidDurationRatio(«HISTORY»)

(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.


invalidRatio#

Usage: invalidRatio(«HISTORY»)

(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.


isNewer#

Usage: isNewer(«HISTORY1», «HISTORY2»)

(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.


known#

Usage: known(«QUESTION»)

(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.


latestChange#

Usage: latestChange(«HISTORY»)

(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.


latestValue#

Usage: latestValue(«HISTORY1», «[HISTORY2]», «[HISTORY3]»)

(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.


le#

Usage: le(«ARGUMENT», «ARGUMENT»)

(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.


log#

Usage: log(«NUMBER»)

(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.


log10#

Usage: log10(«NUMBER»)

(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.


log1p#

Usage: log1p(«NUMBER»)

(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.


lt#

Usage: lt(«ARGUMENT», «ARGUMENT»)

(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.


max#

Usage: max(«HISTORY or PRIMITIVE», «[PRIMITIVE]*»)

(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.


median#

Usage: median(«HISTORY»)

(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.


min#

Usage: min(«HISTORY or PRIMITIVE», «[PRIMITIVE]*»)

(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.


minus#

Usage: minus(«ARGUMENT», «ARGUMENT»)

(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 '-'


minute#

Usage: minute(«DATE»)

(Implemented in cc.d3web.expression.eval.DateFunction)

DATE -> NUMBER

Returns the minute of a given date, from 0 to 59.


mod#

Usage: mod(«ARGUMENT», «ARGUMENT»)

(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 '%'


month#

Usage: month(«DATE»)

(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.


mult#

Usage: mult(«ARGUMENT», «ARGUMENT»)

(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 '*'


neg#

Usage: neg(«NUMBER»)

(Implemented in cc.d3web.expression.eval.UnaryMathFunction)

NUMBER   -> NUMBER
DURATION -> DURATION

Returns the negated value of the argument.


not#

Usage: not(«BOOLEAN»)

(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 '!'.


or#

Usage: or(«BOOLEAN», «BOOLEAN»)

(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 '|'.


percentEqual#

Usage: percentEqual(«HISTORY», «VALUE»)

(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.


percentGe#

Usage: percentGe(«HISTORY», «LIMIT»)

(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.


percentGt#

Usage: percentGt(«HISTORY», «LIMIT»)

(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.


percentIn#

Usage: percentIn(«HISTORY», «MIN», «MAX»)

(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.


percentLe#

Usage: percentLe(«HISTORY», «LIMIT»)

(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.


percentLt#

Usage: percentLt(«HISTORY», «LIMIT»)

(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.


percentUnequal#

Usage: percentUnequal(«HISTORY», «VALUE»)

(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.


plus#

Usage: plus(«ARGUMENT», «ARGUMENT»)

(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 '+'


pow#

Usage: pow(«ARGUMENT», «ARGUMENT»)

(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.


rint#

Usage: rint(«NUMBER»)

(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:


round#

Usage: round(«NUMBER»)

(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:


second#

Usage: second(«DATE»)

(Implemented in cc.d3web.expression.eval.DateFunction)

DATE -> NUMBER

Returns the second of a given date, from 0 to 59.


signum#

Usage: signum(«NUMBER»)

(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:


sin#

Usage: sin(«NUMBER»)

(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.


since#

Usage: since(«HISTORY»)

(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.


sinh#

Usage: sinh(«NUMBER»)

(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.


sqrt#

Usage: sqrt(«NUMBER»)

(Implemented in cc.d3web.expression.eval.UnaryMathFunction)

NUMBER -> NUMBER

Returns the correctly rounded positive square root of a double value. Special cases:

Otherwise, the result is the double value closest to the true mathematical square root of the argument value.

strictSubHistory#

Usage: strictSubHistory(«HISTORY», «START», «END»)

(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:

Note: Relative dates specified by durations are taken back in time, relatively from the last change of the xps session (global variable 'now').

You may also use the inline operator «HISTORY»![«START» , «END»].


subHistory#

Usage: subHistory(«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:

Note: Relative dates specified by durations are taken back in time, relatively from the last change of the xps session (global variable 'now').

You may also use the inline operator «HISTORY»[«START» , «END»].


tan#

Usage: tan(«NUMBER»)

(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.


tanh#

Usage: tanh(«NUMBER»)

(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.


toDegrees#

Usage: toDegrees(«NUMBER»)

(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.


toRadians#

Usage: toRadians(«NUMBER»)

(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.


unequal#

Usage: unequal(«ARGUMENT», «ARGUMENT»)

(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.


validCount#

Usage: validCount(«HISTORY»)

(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.


validDuration#

Usage: validDuration(«HISTORY»)

(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.


validDurationRatio#

Usage: validDurationRatio(«HISTORY»)

(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.


validRatio#

Usage: validRatio(«HISTORY»)

(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.


valids#

Usage: valids(«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).


valueAt#

Usage: valueAt(«HISTORY», «TIME»)

(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:

Note: A relative date specified by a duration is taken back in time, raletively from the the current time of the xps session.

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»].


year#

Usage: year(«DATE»)

(Implemented in cc.d3web.expression.eval.DateFunction)

DATE -> NUMBER

Returns the year of a given date.