Expression Language¶
PHPBench has a domain-specific expression language which is used when writing assertions.
Comparators¶
| comparator | description |
|---|---|
| < | Less than |
| <= | Less than or equal |
| = | Equal |
| > | Greater than |
| >= | Greater than or equal |
Examples:
10 microseconds < 20 microseconds
Logical Operators¶
| comparator | description |
|---|---|
| and | Logical and |
| or | Logical or |
Examples:
1 < 2 and 3 < 4
(1 < 2 and 3 < 4) or true
String Operators¶
| comparator | description |
|---|---|
~ |
Concatenate |
Examples:
"mode: " ~ mode([12, 12, 12]) ~ " \o/"
Null Safe Operator¶
Use the null-safe operator to evaluate absence as null rather than throwing a runtime exception.
Examples:
data?["bar"] = null
Arithmetic¶
| comparator | description |
|---|---|
+ |
Addition |
- |
Subtraction |
/ |
Divide |
* |
Multiply |
Examples:
1 + 1 = 2
2 + 3 * 4 + 5 = 19
2 + (3 * 4) + 5 = 19
(2 + 3) * 4 + 5 = 25
Time Units¶
The base unit for time in PHPBench is microseconds. By specifying a timeunit you can represent other units - internally the unit will be converted to microseconds:
| unit | description |
|---|---|
| microsecond | 1,000,000th of a second |
| millisecond | 1,000th of a second |
| second | 1 second |
| minute | 60 seconds |
| hour | 3,600 seconds |
| day | 86,400 seconds |
| time | Automatic |
Examples:
20 milliseconds
20 seconds < 20 days
360 days = (3600 seconds * 24) * 360
Memory Units:¶
| unit | description |
|---|---|
| byte | 1 byte |
| kilobyte | 1,000 bytes |
| kibibyte | 1,024 bytes |
| megabyte | 1,000,000 bytes |
| mibibyte | 1,048,576 bytes |
| gigabyte | 1,000,000,000 bytes |
| gibibyte | 1,073,741,824 bytes |
| memory | Automatic |
For example:
1 megabytes < 2 megabytes
1 bytes + 2 megabytes
Display As¶
Parameterized values (e.g. variant.time.avg) are always provided the base
unit. You can use as to display these values in a specified unit:
1000000 as seconds = 1 second
This will force the unit conversion to happen only when displaying the evaluated expression.
You can also specify the precision:
1000000 as seconds precision 4 = 1 second
Will ensure that the result is displayed with the given number of digits after the decimal point.
Tolerance¶
In practice two runs will rarely return exactly the same result. To allow a tolerable variance you can specify a tolerance as follows:
9 milliseconds <= 10 milliseconds +/- 10%
With the above values within 8 to 12 milliseconds will be tolerated.
You can also specify a percentage value:
9 milliseconds <= 10 milliseconds +/- 2 milliseconds
Filtering¶
Enter an expression within square brackets to filter the dataset on a data frame:
data[column1 = "value1"] = frame(["column1", "column2"], [["value1", "value2"]])
data[column1 = "value1"]["column1"] = ["value1"]
first(data[column1 = "value1"]["column1"]) = "value1"
Note that this will only work when the underlying variable is a data frame, if it is not you will encounter an exception such as:
Expression provided but container is not a data frame, it is "array"
Functions¶
max¶
Return the max value in a set of values, if values are empty it will return NULL:
max([10, 12, 4, 20]) = 20
max([]) = null
min¶
Return the min value in a set of values, if values are empty it will return NULL:
min([10, 12, 4, 20]) = 4
min([]) = null
mode¶
Return the KDE mode value in a set of values:
mode([1, 2, 1, 2]) = 1.5 +/- 0.00000000001
In PHPBench the mode is generally the best predictor.
rstdev¶
Return the relative standard deviation for a set of values:
rstdev([1,2]) = 33.3333 +/- 0.0001
rstdev([1,2], true) = 47.1405 +/- 0.0001
format("%2.4f%%", rstdev([1,2])) = "33.3333%"
format¶
Format values as a string - uses sprintf:
format("hello %s", "daniel") = "hello daniel"
format("%2.4f%%", rstdev([1,2])) = "33.3333%"
first¶
Return the first element in an array, if values are empty it will return NULL.
first(["one", "two"]) = "one"
first([]) = null
display_as_time¶
Similar to Display As but also allows specification of the “mode”
display_as_time(100000, "seconds", 2, "throughput") = 100000
