docs: Add an example on adding a diff column

dantleech · dantleech · commit e1fcce2f8072 · 2026-04-04T15:54:05.000+01:00
diff --git a/docs/report-generators/expression.rst b/docs/report-generators/expression.rst
@@ -61,6 +61,18 @@ Which yields:
   :language: bash
   :section: 2
 
+For example you add a **diff** column:
+
+.. approved:: ../../examples/Command/report-generators-column-diff
+  :language: javascript
+  :section: 0
+
+Which yields:
+
+.. approved:: ../../examples/Command/report-generators-column-diff
+  :language: bash
+  :section: 2
+
 .. _generator_expression_aggregate:
 
 Aggregate
diff --git a/examples/Command/report-generators-column-diff b/examples/Command/report-generators-column-diff
@@ -0,0 +1,34 @@
+{
+    "runner.executor": "debug-example",
+    "runner.iterations": 5,
+    "runner.executors": {
+        "debug-example": {
+            "executor": "debug",
+            "times":[10, 20, 30, 40, 50]
+        }
+    },
+    "report.generators": {
+         "my-report": {
+             "generator": "expression",
+             "aggregate": ["iteration_index"],
+             "cols": {
+                 "subject": null,
+                 "mode": null,
+                 "diff": "format('%.2fx', mean(result_time_avg) / min(suite['result_time_avg']))"
+             }
+         }
+    }
+}
+---
+phpbench run --report=my-report --executor=debug NothingBench.php --progress=none
+---
++--------------+----------+-------+
+| subject      | mode     | diff  |
++--------------+----------+-------+
+| benchNothing | 10.000μs | 1.00x |
+| benchNothing | 20.000μs | 2.00x |
+| benchNothing | 30.000μs | 3.00x |
+| benchNothing | 40.000μs | 4.00x |
+| benchNothing | 50.000μs | 5.00x |
++--------------+----------+-------+
+
