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
megabyte 1,000,000 bytes
gigabyte 1,000,000,000 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

mean

Return the mean (i.e. average) value in a set of values:

mean([1, 2, 1, 2]) = 1.5

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.

percent_diff

Return the percentage difference between two values

percent_diff(1, 2) = 100

stdev

Return the standard deviation for a set of values:

stdev([1,2]) = 0.5

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%"

variance

Return the variance for a set of values:

variance([1,2]) = 0.25

format

Format values as a string - uses sprintf:

format("hello %s", "daniel") = "hello daniel"
format("%2.4f%%", rstdev([1,2])) = "33.3333%"

join

Join values with a delimiter

join(",", ["one", "two"]) = "one,two"

first

Return the first element in an array, if values are empty it will return NULL.

first(["one", "two"]) = "one"
first([]) = null

coalesce

Return the first non-null element from the given arguments:

coalesce(null, null, 10) = 10

display_as_time

Similar to Display As but also allows specification of the “mode”

display_as_time(100000, "seconds", 2, "throughput") = 100000

sum

Evaluate sum of given numbers

sum([1, 2, 3]) = 6

count

Evaluate count of given numbers

count([1, 2, 3]) = 3

frame

Create a new data frame with the given column names and row lists.

frame(["column1"], [["value1"],["value2"]])[column1 = "value1"] = frame(["column1"], [["value1"]])