Store parameter usage metadata in benchmark results

Add colors to --help/-h

README.md

@@ -88,6 +88,22 @@ option:
 hyperfine -L compiler g++,clang++ '{compiler} -O2 main.cpp'
 ```
 
+A common use case is comparing the same command across multiple Git branches. Use `--setup`
+to switch branches once before each set of timing runs, so the branch switch is not part of
+the measured command:
+```sh
+hyperfine \
+    --parameter-list branch main,performance-improvements \
+    --setup 'git switch {branch}' \
+    'python main.py'
+```
+
+If you need a unique value for each individual run of a benchmark command, hyperfine also exposes
+the zero-based `$HYPERFINE_ITERATION` environment variable inside the benchmarked command itself:
+```sh
+hyperfine 'my-command > output-${HYPERFINE_ITERATION}.log'
+```
+
 ### Intermediate shell
 
 By default, commands are executed using `sh` on Unix (resolved through `PATH`) or `cmd.exe` on Windows.

doc/hyperfine.1

@@ -180,7 +180,7 @@ The exact syntax may vary depending on your shell and OS.
 \fB\-D\fR, \fB\-\-parameter\-step\-size\fR \fIDELTA\fP
 .IP
 This argument requires \fB\-\-parameter\-scan\fR to be specified as well. Traverse the
-range \fIMIN..MAX\fP in steps of \fIDELTA\fP.
+range \fIMIN..MAX\fP in steps of \fIDELTA\fP, which must be positive.
 .IP
 .RS
 Example:

src/benchmark/benchmark_result.rs

@@ -2,6 +2,15 @@ use std::collections::BTreeMap;
 
 use serde::Serialize;
 
+/// Parameter value and whether it was used in the command line template
+#[derive(Debug, Default, Clone, Serialize, PartialEq)]
+#[serde(transparent)]
+pub struct Parameter {
+    pub value: String,
+    #[serde(skip)]
+    pub is_unused: bool,
+}
+
 /// Set of values that will be exported.
 // NOTE: `serde` is used for JSON serialization, but not for CSV serialization due to the
 // `parameters` map. Update `src/hyperfine/export/csv.rs` with new fields, as appropriate.
@@ -49,5 +58,5 @@ pub struct BenchmarkResult {
 
     /// Parameter values for this benchmark
     #[serde(skip_serializing_if = "BTreeMap::is_empty")]
-    pub parameters: BTreeMap<String, String>,
+    pub parameters: BTreeMap<String, Parameter>,
 }

src/benchmark/executor.rs

@@ -266,7 +266,7 @@ impl Executor for ShellExecutor<'_> {
             time_wall_clock: measurements.time_wall_clock_mean(),
             time_user: measurements.time_user_mean(),
             time_system: measurements.time_system_mean(),
-            peak_memory_usage: Information::zero(),
+            peak_memory_usage: measurements.peak_memory_usage_mean(),
             exit_status: ExitStatus::default(),
         });
 

src/benchmark/measurement.rs

@@ -1,7 +1,7 @@
 use std::process::ExitStatus;
 
 use crate::quantity::statistics::{max, mean, median, min, modified_zscores, standard_deviation};
-use crate::quantity::{second, Information, Time};
+use crate::quantity::{Information, Time};
 
 /// Performance measurements and exit status from running a single command
 #[derive(Debug, Default, Copy, Clone)]
@@ -77,12 +77,7 @@ impl Measurements {
 
     /// Compute modified Z-scores for the wall clock times.
     pub fn modified_zscores(&self) -> Vec<f64> {
-        modified_zscores(
-            &self
-                .wall_clock_times()
-                .map(|t| t.get::<second>())
-                .collect::<Vec<_>>(),
-        )
+        modified_zscores(&self.wall_clock_times().collect::<Vec<_>>())
     }
 
     /// The average user time.
@@ -94,4 +89,8 @@ impl Measurements {
     pub fn time_system_mean(&self) -> Time {
         mean(self.measurements.iter().map(|m| m.time_system))
     }
+
+    pub fn peak_memory_usage_mean(&self) -> Information {
+        mean(self.measurements.iter().map(|m| m.peak_memory_usage))
+    }
 }

src/benchmark/mod.rs

@@ -17,11 +17,9 @@ use crate::output::console_writeln;
 use crate::output::progress_bar::get_progress_bar;
 use crate::output::warnings::{OutlierWarningOptions, Warnings};
 use crate::parameter::ParameterNameAndValue;
-use crate::quantity::{
-    byte, const_time_from_seconds, format_duration, format_duration_unit, ratio, second, Time, Zero,
-};
+use crate::quantity::{byte, const_time_from_seconds, ratio, second, FormatQuantity, Time, Zero};
 use crate::util::exit_code::extract_exit_code;
-use benchmark_result::BenchmarkResult;
+use benchmark_result::{BenchmarkResult, Parameter};
 use measurement::{Measurement, Measurements};
 
 use anyhow::{anyhow, Result};
@@ -294,10 +292,12 @@ impl<'a> Benchmark<'a> {
             run_preparation_command()?;
 
             let msg = {
-                let mean = format_duration(
-                    measurements.time_wall_clock_mean().get::<second>(),
-                    self.options.time_unit,
-                );
+                let t_wall_clock_mean = measurements.time_wall_clock_mean();
+                let time_unit = self
+                    .options
+                    .time_unit
+                    .unwrap_or(t_wall_clock_mean.suitable_unit());
+                let mean = t_wall_clock_mean.format(time_unit);
                 format!("Current estimate: {}", mean.to_string().green())
             };
 
@@ -340,14 +340,14 @@ impl<'a> Benchmark<'a> {
         let system_mean = measurements.time_system_mean();
 
         // Formatting and console output
-        let (mean_str, time_unit) =
-            format_duration_unit(t_mean.get::<second>(), self.options.time_unit);
-        let min_str = format_duration(t_min.get::<second>(), Some(time_unit));
-        let max_str = format_duration(t_max.get::<second>(), Some(time_unit));
+        let time_unit = self.options.time_unit.unwrap_or(t_mean.suitable_unit());
+        let mean_str = t_mean.format(time_unit);
+        let min_str = t_min.format(time_unit);
+        let max_str = t_max.format(time_unit);
         let num_str = format!("{t_num} runs");
 
-        let user_str = format_duration(user_mean.get::<second>(), Some(time_unit));
-        let system_str = format_duration(system_mean.get::<second>(), Some(time_unit));
+        let user_str = user_mean.format(time_unit);
+        let system_str = system_mean.format(time_unit);
 
         if self.options.output_style != OutputStyleOption::Disabled {
             let mut stdout = io::stdout().lock();
@@ -362,8 +362,7 @@ impl<'a> Benchmark<'a> {
                     system_str.blue()
                 )?;
             } else {
-                let stddev_str =
-                    format_duration(t_stddev.unwrap().get::<second>(), Some(time_unit));
+                let stddev_str = t_stddev.unwrap().format(time_unit);
 
                 console_writeln!(
                     stdout,
@@ -475,7 +474,15 @@ impl<'a> Benchmark<'a> {
                 .command
                 .get_parameters()
                 .iter()
-                .map(|(name, value)| (name.to_string(), value.to_string()))
+                .map(|(name, value)| {
+                    (
+                        name.to_string(),
+                        Parameter {
+                            value: value.to_string(),
+                            is_unused: self.command.is_parameter_unused(name),
+                        },
+                    )
+                })
                 .collect(),
         })
     }

src/cli.rs

@@ -1,8 +1,10 @@
 use std::ffi::OsString;
 
 use clap::{
-    builder::NonEmptyStringValueParser, crate_version, Arg, ArgAction, ArgMatches, Command,
-    ValueHint,
+    builder::styling::{AnsiColor, Effects},
+    builder::NonEmptyStringValueParser,
+    builder::Styles,
+    crate_version, Arg, ArgAction, ArgMatches, Command, ValueHint,
 };
 
 pub fn get_cli_arguments<'a, I, T>(args: I) -> ArgMatches
@@ -14,10 +16,17 @@ where
     command.get_matches_from(args)
 }
 
+const STYLES: Styles = Styles::styled()
+    .header(AnsiColor::Green.on_default().effects(Effects::BOLD))
+    .usage(AnsiColor::Green.on_default().effects(Effects::BOLD))
+    .literal(AnsiColor::Cyan.on_default().effects(Effects::BOLD))
+    .placeholder(AnsiColor::Cyan.on_default());
+
 /// Build the clap command for parsing command line arguments
 fn build_command() -> Command {
     Command::new("hyperfine")
         .version(crate_version!())
+        .styles(STYLES)
         .next_line_help(true)
         .hide_possible_values(true)
         .about("A command-line benchmarking tool.")
@@ -182,7 +191,7 @@ fn build_command() -> Command {
                 .requires("parameter-scan")
                 .help(
                     "This argument requires --parameter-scan to be specified as well. \
-                     Traverse the range MIN..MAX in steps of DELTA.\n\n  \
+                     Traverse the range MIN..MAX in steps of DELTA, which must be positive.\n\n  \
                      Example:  hyperfine -P delay 0.3 0.7 -D 0.2 'sleep {delay}'\n\n\
                      This performs benchmarks for 'sleep 0.3', 'sleep 0.5' and 'sleep 0.7'.",
                 ),

src/command.rs

@@ -97,10 +97,14 @@ impl<'a> Command<'a> {
         &self.parameters
     }
 
+    pub fn is_parameter_unused(&self, parameter: &str) -> bool {
+        !self.expression.contains(&format!("{{{parameter}}}"))
+    }
+
     pub fn get_unused_parameters(&self) -> impl Iterator<Item = &(&'a str, ParameterValue)> {
         self.parameters
             .iter()
-            .filter(move |(parameter, _)| !self.expression.contains(&format!("{{{parameter}}}")))
+            .filter(move |(parameter, _)| self.is_parameter_unused(parameter))
     }
 
     fn replace_parameters_in(&self, original: &str) -> String {

src/error.rs

@@ -19,6 +19,8 @@ pub enum ParameterScanError {
     TooLarge,
     #[error("Zero is not a valid parameter step")]
     ZeroStep,
+    #[error("Parameter step size must be positive")]
+    NegativeStep,
     #[error("A step size is required when the range bounds are floating point numbers. The step size can be specified with the '-D/--parameter-step-size <DELTA>' parameter")]
     StepRequired,
     #[error("'--command-name' has been specified {0} times. It has to appear exactly once, or exactly {1} times (number of benchmarks)")]

src/export/csv.rs

@@ -19,6 +19,8 @@ impl Exporter for CsvExporter {
         _unit: Option<TimeUnit>,
         _sort_order: SortOrder,
     ) -> Result<Vec<u8>> {
+        const CSV_PRECISION: usize = 6;
+
         let mut writer = WriterBuilder::new().from_writer(vec![]);
 
         {
@@ -48,10 +50,10 @@ impl Exporter for CsvExporter {
                 res.min,
                 res.max,
             ] {
-                fields.push(Cow::Owned(f.to_string().into_bytes()))
+                fields.push(Cow::Owned(format!("{f:.CSV_PRECISION$}").into_bytes()))
             }
             for v in res.parameters.values() {
-                fields.push(Cow::Borrowed(v.as_bytes()))
+                fields.push(Cow::Borrowed(v.value.as_bytes()))
             }
             writer.write_record(fields)?;
         }
@@ -62,6 +64,7 @@ impl Exporter for CsvExporter {
 
 #[test]
 fn test_csv() {
+    use crate::benchmark::benchmark_result::Parameter;
     use std::collections::BTreeMap;
     let exporter = CsvExporter::default();
 
@@ -81,8 +84,20 @@ fn test_csv() {
             exit_codes: vec![Some(0), Some(0), Some(0)],
             parameters: {
                 let mut params = BTreeMap::new();
-                params.insert("foo".into(), "one".into());
-                params.insert("bar".into(), "two".into());
+                params.insert(
+                    "foo".into(),
+                    Parameter {
+                        value: "one".into(),
+                        is_unused: false,
+                    },
+                );
+                params.insert(
+                    "bar".into(),
+                    Parameter {
+                        value: "two".into(),
+                        is_unused: false,
+                    },
+                );
                 params
             },
         },
@@ -101,8 +116,20 @@ fn test_csv() {
             exit_codes: vec![Some(0), Some(0), Some(0)],
             parameters: {
                 let mut params = BTreeMap::new();
-                params.insert("foo".into(), "one".into());
-                params.insert("bar".into(), "seven".into());
+                params.insert(
+                    "foo".into(),
+                    Parameter {
+                        value: "one".into(),
+                        is_unused: false,
+                    },
+                );
+                params.insert(
+                    "bar".into(),
+                    Parameter {
+                        value: "seven".into(),
+                        is_unused: false,
+                    },
+                );
                 params
             },
         },
@@ -117,7 +144,7 @@ fn test_csv() {
 
     insta::assert_snapshot!(actual, @r#"
     command,mean,stddev,median,user,system,min,max,parameter_bar,parameter_foo
-    command_a,1,2,1,3,4,5,6,two,one
-    command_b,11,12,11,13,14,15,16.5,seven,one
+    command_a,1.000000,2.000000,1.000000,3.000000,4.000000,5.000000,6.000000,two,one
+    command_b,11.000000,12.000000,11.000000,13.000000,14.000000,15.000000,16.500000,seven,one
     "#);
 }

src/export/markdown.rs

@@ -24,7 +24,19 @@ impl MarkupExporter for MarkdownExporter {
     }
 
     fn command(&self, cmd: &str) -> String {
-        format!("`{cmd}`")
+        let longest_backtick_run = cmd
+            .split(|character| character != '`')
+            .map(str::len)
+            .max()
+            .unwrap_or(0);
+
+        if longest_backtick_run == 0 {
+            format!("`{cmd}`")
+        } else {
+            // Use a longer delimiter and keep command backticks separate from it.
+            let delimiter = "`".repeat(longest_backtick_run + 1);
+            format!("{delimiter} {cmd} {delimiter}")
+        }
     }
 }
 
@@ -44,3 +56,19 @@ fn test_markdown_formatter_table_divider() {
     let divider = formatter.table_divider(&[Alignment::Left, Alignment::Right, Alignment::Left]);
     assert_eq!(divider, "|:---|---:|:---|\n");
 }
+
+#[test]
+fn test_markdown_formatter_command_with_backticks() {
+    let formatter = MarkdownExporter::default();
+
+    for (command, expected) in [
+        ("echo `uname`", "`` echo `uname` ``"),
+        ("echo ``quoted``", "``` echo ``quoted`` ```"),
+        ("`` `quoted` ``", "``` `` `quoted` `` ```"),
+        ("`", "`` ` ``"),
+        ("echo ```", "```` echo ``` ````"),
+        (" echo `uname` ", "``  echo `uname`  ``"),
+    ] {
+        assert_eq!(formatter.command(command), expected, "{command:?}");
+    }
+}

src/export/markup.rs

@@ -1,7 +1,7 @@
 use crate::benchmark::relative_speed::BenchmarkResultWithRelativeSpeed;
 use crate::benchmark::{benchmark_result::BenchmarkResult, relative_speed};
 use crate::options::SortOrder;
-use crate::quantity::{format_duration_value, TimeUnit};
+use crate::quantity::{second, FormatQuantity, IsUnit, Time, TimeUnit};
 
 use super::Exporter;
 use anyhow::Result;
@@ -50,14 +50,14 @@ pub trait MarkupExporter {
             let cmd_str = measurement
                 .command_with_unused_parameters
                 .replace('|', "\\|");
-            let mean_str = format_duration_value(measurement.mean, Some(unit)).0;
+            let mean_str = Time::new::<second>(measurement.mean).format_value(unit);
             let stddev_str = if let Some(stddev) = measurement.stddev {
-                format!(" ± {}", format_duration_value(stddev, Some(unit)).0)
+                format!(" ± {}", Time::new::<second>(stddev).format_value(unit))
             } else {
                 "".into()
             };
-            let min_str = format_duration_value(measurement.min, Some(unit)).0;
-            let max_str = format_duration_value(measurement.max, Some(unit)).0;
+            let min_str = Time::new::<second>(measurement.min).format_value(unit);
+            let max_str = Time::new::<second>(measurement.max).format_value(unit);
             let rel_str = format!("{:.2}", entry.relative_speed);
             let rel_stddev_str = if entry.is_reference {
                 "".into()
@@ -101,7 +101,7 @@ pub trait MarkupExporter {
 fn determine_unit_from_results(results: &[BenchmarkResult]) -> TimeUnit {
     if let Some(first_result) = results.first() {
         // Use the first BenchmarkResult entry to determine the unit for all entries.
-        format_duration_value(first_result.mean, None).1
+        Time::new::<second>(first_result.mean).suitable_unit()
     } else {
         // Default to `Second`.
         TimeUnit::Second

src/main.rs

@@ -25,7 +25,7 @@ pub mod options;
 pub mod outlier_detection;
 pub mod output;
 pub mod parameter;
-mod quantity;
+pub mod quantity;
 pub mod timer;
 pub mod util;
 
@@ -37,14 +37,14 @@ fn run() -> Result<()> {
     let cli_arguments = get_cli_arguments(env::args_os());
     let mut options = Options::from_cli_arguments(&cli_arguments)?;
     let commands = Commands::from_cli_arguments(&cli_arguments)?;
+    options.validate_against_command_list(&commands)?;
+
     let export_manager = ExportManager::from_cli_arguments(
         &cli_arguments,
         options.time_unit,
         options.sort_order_exports,
     )?;
 
-    options.validate_against_command_list(&commands)?;
-
     let mut scheduler = Scheduler::new(&commands, &options, &export_manager);
     scheduler.run_benchmarks()?;
     scheduler.print_relative_speed_comparison()?;

src/outlier_detection.rs

@@ -14,13 +14,13 @@ pub const OUTLIER_THRESHOLD: f64 = 1.4826 * 10.0;
 /// modified Z-score that is larger than `OUTLIER_THRESHOLD`.
 #[cfg(test)]
 pub fn num_outliers(xs: &[f64]) -> usize {
-    use crate::quantity::statistics::modified_zscores;
+    use crate::quantity::statistics::modified_zscores_f64;
 
     if xs.is_empty() {
         return 0;
     }
 
-    let scores = modified_zscores(xs);
+    let scores = modified_zscores_f64(xs);
     scores
         .iter()
         .filter(|&&s| s.abs() > OUTLIER_THRESHOLD)

src/output/warnings.rs

@@ -1,7 +1,7 @@
 use std::fmt;
 
 use crate::benchmark::MIN_EXECUTION_TIME;
-use crate::quantity::{format_duration, second, Time};
+use crate::quantity::{FormatQuantity, Time, TimeUnit};
 
 pub struct OutlierWarningOptions {
     pub warmup_in_use: bool,
@@ -21,11 +21,11 @@ impl fmt::Display for Warnings {
         match *self {
             Warnings::FastExecutionTime => write!(
                 f,
-                "Command took less than {:.0} ms to complete. Note that the results might be \
+                "Command took less than {} ms to complete. Note that the results might be \
                 inaccurate because hyperfine can not calibrate the shell startup time much \
                 more precise than this limit. You can try to use the `-N`/`--shell=none` \
                 option to disable the shell completely.",
-                MIN_EXECUTION_TIME.get::<second>() * 1e3
+                MIN_EXECUTION_TIME.format_with_precision(TimeUnit::MilliSecond, 0)
             ),
             Warnings::NonZeroExitCode => write!(f, "Ignoring non-zero exit code."),
             Warnings::SlowInitialRun(time_first_run, ref options) => write!(
@@ -33,7 +33,7 @@ impl fmt::Display for Warnings {
                 "The first benchmarking run for this command was significantly slower than the \
                  rest ({time}). This could be caused by (filesystem) caches that were not filled until \
                  after the first run. {hints}",
-                time=format_duration(time_first_run.get::<second>(), None),
+                time=time_first_run.format_auto(),
                 hints=match (options.warmup_in_use, options.prepare_in_use) {
                     (true, true) => "You are already using both the '--warmup' option as well \
                     as the '--prepare' option. Consider re-running the benchmark on a quiet system. \

src/parameter/range_step.rs

@@ -47,6 +47,10 @@ impl<T: Numeric> RangeStep<T> {
             return Err(ParameterScanError::ZeroStep);
         }
 
+        if step < T::from(0) {
+            return Err(ParameterScanError::NegativeStep);
+        }
+
         const MAX_PARAMETERS: usize = 100_000;
         match range_step_size_hint(start, end, step) {
             (_, Some(size)) if size <= MAX_PARAMETERS => Ok(Self {
@@ -120,6 +124,36 @@ mod tests {
         assert_eq!(param_range[10], Decimal::from(1));
     }
 
+    #[test]
+    fn test_negative_integer_step() {
+        for step in [-2, -3, i32::MIN, -1] {
+            for end in [0, 1, 10] {
+                let result = RangeStep::new(0, end, step);
+                assert_eq!(
+                    result.unwrap_err().to_string(),
+                    "Parameter step size must be positive"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn test_negative_decimal_step() {
+        for step in ["-2.0", "-0.1"] {
+            for end in [0, 1, 10] {
+                let result = RangeStep::new(
+                    Decimal::ZERO,
+                    Decimal::from(end),
+                    Decimal::from_str(step).unwrap(),
+                );
+                assert_eq!(
+                    result.unwrap_err().to_string(),
+                    "Parameter step size must be positive"
+                );
+            }
+        }
+    }
+
     #[test]
     fn test_range_step_validate() {
         let result = RangeStep::new(0, 10, 3);

src/quantity/mod.rs

@@ -1,18 +1,64 @@
 use std::marker::PhantomData;
 
-pub use uom::num_traits::Zero;
-pub use uom::si::f64::{Information, Ratio, Time};
-pub use uom::si::information::byte;
-#[cfg(any(not(windows), test))]
-pub use uom::si::information::kibibyte;
-pub use uom::si::ratio::ratio;
-pub use uom::si::time::{microsecond, nanosecond, second};
+use uom::si;
 
-pub use units::TimeUnit;
+pub use si::f64::{Information, Ratio, Time};
+pub use si::information::{byte, gibibyte, kibibyte, mebibyte, tebibyte};
+pub use si::ratio::ratio;
+pub use si::time::{hour, microsecond, millisecond, minute, nanosecond, second};
+pub use uom::num_traits::Zero;
+
+pub use units::{InformationUnit, IsUnit, TimeUnit};
 
 pub mod statistics;
 mod units;
 
+pub trait FormatQuantity {
+    type Unit;
+
+    fn suitable_unit(&self) -> Self::Unit;
+
+    fn format_with_precision(&self, unit: Self::Unit, precision: usize) -> String;
+    fn format(&self, unit: Self::Unit) -> String;
+    fn format_auto(&self) -> String;
+    fn format_value(&self, unit: Self::Unit) -> String;
+}
+
+impl FormatQuantity for Time {
+    type Unit = TimeUnit;
+
+    fn suitable_unit(&self) -> TimeUnit {
+        if *self < Time::new::<millisecond>(1.0) {
+            TimeUnit::MicroSecond
+        } else if *self < Time::new::<second>(1.0) {
+            TimeUnit::MilliSecond
+        } else {
+            TimeUnit::Second
+        }
+    }
+
+    /// Format the time duration in the given unit with the given precision.
+    fn format_with_precision(&self, u: TimeUnit, precision: usize) -> String {
+        u.format(*self, precision)
+    }
+
+    /// Format the time duration in the given unit.
+    fn format(&self, unit: TimeUnit) -> String {
+        let value = self.format_with_precision(unit, unit.preferred_precision());
+        format!("{} {}", value, unit.short_name())
+    }
+
+    /// Format the given time duration. The unit will be determined automatically.
+    fn format_auto(&self) -> String {
+        self.format(self.suitable_unit())
+    }
+
+    /// Like `format`, but without displaying the unit.
+    fn format_value(&self, unit: TimeUnit) -> String {
+        self.format_with_precision(unit, unit.preferred_precision())
+    }
+}
+
 pub const fn const_time_from_seconds(value: f64) -> Time {
     // Quantity::new in uom is not yet const: https://docs.rs/uom/0.36.0/uom/si/struct.Quantity.html
     Time {
@@ -22,41 +68,43 @@ pub const fn const_time_from_seconds(value: f64) -> Time {
     }
 }
 
-/// Format the given duration as a string. The output-unit can be enforced by setting `unit` to
-/// `Some(target_unit)`. If `unit` is `None`, it will be determined automatically.
-pub fn format_duration(duration: f64, unit: Option<TimeUnit>) -> String {
-    let (duration_fmt, _) = format_duration_unit(duration, unit);
-    duration_fmt
-}
+impl FormatQuantity for Information {
+    type Unit = InformationUnit;
 
-/// Like `format_duration`, but returns the target unit as well.
-pub fn format_duration_unit(duration: f64, unit: Option<TimeUnit>) -> (String, TimeUnit) {
-    let (out_str, out_unit) = format_duration_value(duration, unit);
+    fn suitable_unit(&self) -> InformationUnit {
+        if *self < Information::new::<kibibyte>(1.0) {
+            InformationUnit::Byte
+        } else if *self < Information::new::<mebibyte>(1.0) {
+            InformationUnit::KibiByte
+        } else if *self < Information::new::<gibibyte>(1.0) {
+            InformationUnit::MebiByte
+        } else {
+            InformationUnit::GibiByte
+        }
+    }
 
-    (format!("{} {}", out_str, out_unit.short_name()), out_unit)
-}
+    /// Format the information in the given unit with the given precision.
+    fn format_with_precision(&self, u: InformationUnit, precision: usize) -> String {
+        u.format(*self, precision)
+    }
 
-/// Like `format_duration`, but returns the target unit as well.
-pub fn format_duration_value(duration: f64, unit: Option<TimeUnit>) -> (String, TimeUnit) {
-    if (duration < 0.001 && unit.is_none()) || unit == Some(TimeUnit::MicroSecond) {
-        (
-            TimeUnit::MicroSecond.format(duration),
-            TimeUnit::MicroSecond,
-        )
-    } else if (duration < 1.0 && unit.is_none()) || unit == Some(TimeUnit::MilliSecond) {
-        (
-            TimeUnit::MilliSecond.format(duration),
-            TimeUnit::MilliSecond,
-        )
-    } else {
-        let unit = unit.unwrap_or(TimeUnit::Second);
-        (unit.format(duration), unit)
+    /// Format the information in the given unit.
+    fn format(&self, unit: InformationUnit) -> String {
+        let value = self.format_with_precision(unit, unit.preferred_precision());
+        format!("{} {}", value, unit.short_name())
+    }
+
+    /// Format the given information. The unit will be determined automatically.
+    fn format_auto(&self) -> String {
+        self.format(self.suitable_unit())
+    }
+
+    /// Like `format`, but without displaying the unit.
+    fn format_value(&self, unit: InformationUnit) -> String {
+        self.format_with_precision(unit, unit.preferred_precision())
     }
 }
 
-#[cfg(test)]
-use uom::si::time::millisecond;
-
 #[test]
 fn test_time() {
     let time = Time::new::<millisecond>(123.4);
@@ -84,52 +132,72 @@ fn test_information() {
 }
 
 #[test]
-fn test_format_duration_unit_basic() {
-    let (out_str, out_unit) = format_duration_unit(1.3, None);
+fn test_suiteable_unit_time() {
+    assert_eq!(Time::new::<second>(1.3).suitable_unit(), TimeUnit::Second);
+    assert_eq!(Time::new::<second>(1.0).suitable_unit(), TimeUnit::Second);
+    assert_eq!(
+        Time::new::<second>(0.999).suitable_unit(),
+        TimeUnit::MilliSecond
+    );
+    assert_eq!(
+        Time::new::<second>(0.0005).suitable_unit(),
+        TimeUnit::MicroSecond
+    );
+    assert_eq!(
+        Time::new::<second>(0.).suitable_unit(),
+        TimeUnit::MicroSecond
+    );
+    assert_eq!(
+        Time::new::<second>(1000.0).suitable_unit(),
+        TimeUnit::Second
+    );
+}
 
-    assert_eq!("1.300 s", out_str);
-    assert_eq!(TimeUnit::Second, out_unit);
+#[test]
+fn test_suitable_unit_information() {
+    assert_eq!(
+        Information::new::<byte>(512.0).suitable_unit(),
+        InformationUnit::Byte
+    );
+    assert_eq!(
+        Information::new::<byte>(2048.0).suitable_unit(),
+        InformationUnit::KibiByte
+    );
+    assert_eq!(
+        Information::new::<byte>(2_097_152.0).suitable_unit(),
+        InformationUnit::MebiByte
+    );
+    assert_eq!(
+        Information::new::<byte>(2_147_483_648.0).suitable_unit(),
+        InformationUnit::GibiByte
+    );
+}
 
-    let (out_str, out_unit) = format_duration_unit(1.0, None);
+#[test]
+fn test_format() {
+    let time = Time::new::<millisecond>(123.4);
+    assert_eq!(time.format(TimeUnit::Second), "0.123 s");
+    assert_eq!(time.format(TimeUnit::MilliSecond), "123.4 ms");
+    assert_eq!(time.format_auto(), "123.4 ms");
+    assert_eq!(time.format(TimeUnit::MicroSecond), "123400.0 µs");
 
-    assert_eq!("1.000 s", out_str);
-    assert_eq!(TimeUnit::Second, out_unit);
-
-    let (out_str, out_unit) = format_duration_unit(0.999, None);
-
-    assert_eq!("999.0 ms", out_str);
-    assert_eq!(TimeUnit::MilliSecond, out_unit);
-
-    let (out_str, out_unit) = format_duration_unit(0.0005, None);
-
-    assert_eq!("500.0 µs", out_str);
-    assert_eq!(TimeUnit::MicroSecond, out_unit);
-
-    let (out_str, out_unit) = format_duration_unit(0.0, None);
-
-    assert_eq!("0.0 µs", out_str);
-    assert_eq!(TimeUnit::MicroSecond, out_unit);
-
-    let (out_str, out_unit) = format_duration_unit(1000.0, None);
-
-    assert_eq!("1000.000 s", out_str);
-    assert_eq!(TimeUnit::Second, out_unit);
+    let peak_memory_usage = Information::new::<kibibyte>(8.);
+    assert_eq!(peak_memory_usage.format_auto(), "8.0 KiB");
+    assert_eq!(peak_memory_usage.format(InformationUnit::Byte), "8192 B");
+    assert_eq!(
+        peak_memory_usage.format(InformationUnit::KibiByte),
+        "8.0 KiB"
+    );
 }
 
 #[test]
 fn test_format_duration_unit_with_unit() {
-    let (out_str, out_unit) = format_duration_unit(1.3, Some(TimeUnit::Second));
+    let out = Time::new::<second>(1.3).format(TimeUnit::Second);
+    assert_eq!("1.300 s", out);
 
-    assert_eq!("1.300 s", out_str);
-    assert_eq!(TimeUnit::Second, out_unit);
+    let out = Time::new::<second>(1.3).format(TimeUnit::MilliSecond);
+    assert_eq!("1300.0 ms", out);
 
-    let (out_str, out_unit) = format_duration_unit(1.3, Some(TimeUnit::MilliSecond));
-
-    assert_eq!("1300.0 ms", out_str);
-    assert_eq!(TimeUnit::MilliSecond, out_unit);
-
-    let (out_str, out_unit) = format_duration_unit(1.3, Some(TimeUnit::MicroSecond));
-
-    assert_eq!("1300000.0 µs", out_str);
-    assert_eq!(TimeUnit::MicroSecond, out_unit);
+    let out = Time::new::<second>(1.3).format(TimeUnit::MicroSecond);
+    assert_eq!("1300000.0 µs", out);
 }

src/quantity/statistics.rs

@@ -106,13 +106,13 @@ pub fn standard_deviation<Q: UnsafeRawValue>(values: &[Q], mean: Q) -> Q {
     Q::unsafe_from_raw_value((sum / (values.len() as f64 - 1.0)).sqrt())
 }
 
-/// Compute modifized Z-scores for a given sample. A (unmodified) Z-score is defined by
+/// Compute modified Z-scores for a given sample. A (unmodified) Z-score is defined by
 /// `(x_i - x_mean)/x_stddev` whereas the modified Z-score is defined by `(x_i - x_median)/MAD`
 /// where MAD is the median absolute deviation.
 ///
 /// References:
 /// - <https://en.wikipedia.org/wiki/Median_absolute_deviation>
-pub fn modified_zscores(xs: &[f64]) -> Vec<f64> {
+pub fn modified_zscores_f64(xs: &[f64]) -> Vec<f64> {
     assert!(!xs.is_empty());
 
     // Compute sample median:
@@ -131,6 +131,11 @@ pub fn modified_zscores(xs: &[f64]) -> Vec<f64> {
     xs.iter().map(|&x| (x - x_median) / mad).collect()
 }
 
+pub fn modified_zscores<Q: UnsafeRawValue>(values: &[Q]) -> Vec<f64> {
+    let values: Vec<_> = values.iter().map(|q| q.unsafe_raw_value()).collect();
+    modified_zscores_f64(&values)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/quantity/units.rs

@@ -1,41 +1,146 @@
-//! This module contains common units.
+//! This module contains common units for time and information quantities.
+
+use std::marker::PhantomData;
+
+use crate::quantity::{
+    byte, gibibyte, hour, kibibyte, mebibyte, microsecond, millisecond, minute, second, tebibyte,
+    Information, Time,
+};
+
+pub trait IsUnit {
+    type Quantity;
+
+    fn dispatch(&self) -> Box<dyn UnitImpl<Quantity = Self::Quantity>>;
+
+    fn preferred_precision(&self) -> usize;
+
+    fn short_name(&self) -> &'static str {
+        self.dispatch().short_name()
+    }
+
+    fn format(&self, value: Self::Quantity, precision: usize) -> String {
+        self.dispatch().format_value(value, precision)
+    }
+}
 
 /// Supported time units
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TimeUnit {
-    Second,
-    MilliSecond,
     MicroSecond,
+    MilliSecond,
+    Second,
     Minute,
     Hour,
 }
 
-impl TimeUnit {
-    /// The abbreviation of the TimeUnit.
-    pub fn short_name(self) -> String {
+impl IsUnit for TimeUnit {
+    type Quantity = Time;
+
+    fn dispatch(&self) -> Box<dyn UnitImpl<Quantity = Time>> {
         match self {
-            TimeUnit::Second => String::from("s"),
-            TimeUnit::MilliSecond => String::from("ms"),
-            TimeUnit::MicroSecond => String::from("µs"),
-            TimeUnit::Minute => String::from("min"),
-            TimeUnit::Hour => String::from("h"),
+            TimeUnit::MicroSecond => Box::new(TimeUnitDispatcher::<microsecond>::new()),
+            TimeUnit::MilliSecond => Box::new(TimeUnitDispatcher::<millisecond>::new()),
+            TimeUnit::Second => Box::new(TimeUnitDispatcher::<second>::new()),
+            TimeUnit::Minute => Box::new(TimeUnitDispatcher::<minute>::new()),
+            TimeUnit::Hour => Box::new(TimeUnitDispatcher::<hour>::new()),
         }
     }
 
-    /// Returns the value in seconds formatted for the TimeUnit.
-    pub fn format(self, value: f64) -> String {
+    fn preferred_precision(&self) -> usize {
         match self {
-            TimeUnit::Second => format!("{value:.3}"),
-            TimeUnit::MilliSecond => format!("{:.1}", value * 1e3),
-            TimeUnit::MicroSecond => format!("{:.1}", value * 1e6),
-            TimeUnit::Minute => format!("{:.1}", value / 60.0),
-            TimeUnit::Hour => format!("{:.1}", value / 3600.0),
+            TimeUnit::Second => 3,
+            _ => 1,
         }
     }
 }
 
+/// Supported information units
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+
+pub enum InformationUnit {
+    Byte,
+    KibiByte,
+    MebiByte,
+    GibiByte,
+    TebiByte,
+}
+
+impl IsUnit for InformationUnit {
+    type Quantity = Information;
+
+    fn dispatch(&self) -> Box<dyn UnitImpl<Quantity = Information>> {
+        match self {
+            InformationUnit::Byte => Box::new(InformationUnitDispatcher::<byte>::new()),
+            InformationUnit::KibiByte => Box::new(InformationUnitDispatcher::<kibibyte>::new()),
+            InformationUnit::MebiByte => Box::new(InformationUnitDispatcher::<mebibyte>::new()),
+            InformationUnit::GibiByte => Box::new(InformationUnitDispatcher::<gibibyte>::new()),
+            InformationUnit::TebiByte => Box::new(InformationUnitDispatcher::<tebibyte>::new()),
+        }
+    }
+
+    fn preferred_precision(&self) -> usize {
+        match self {
+            InformationUnit::Byte => 0,
+            _ => 1,
+        }
+    }
+}
+
+pub trait UnitImpl {
+    type Quantity;
+
+    fn short_name(&self) -> &'static str;
+    fn format_value(&self, value: Self::Quantity, precision: usize) -> String;
+}
+
+struct TimeUnitDispatcher<U: uom::si::time::Unit + uom::Conversion<f64, T = f64>> {
+    u: PhantomData<U>,
+}
+
+impl<U: uom::si::time::Unit + uom::Conversion<f64, T = f64>> TimeUnitDispatcher<U> {
+    fn new() -> Self {
+        TimeUnitDispatcher { u: PhantomData }
+    }
+}
+
+impl<U: uom::si::time::Unit + uom::Conversion<f64, T = f64>> UnitImpl for TimeUnitDispatcher<U> {
+    type Quantity = Time;
+
+    fn short_name(&self) -> &'static str {
+        U::abbreviation()
+    }
+
+    fn format_value(&self, value: Time, precision: usize) -> String {
+        format!("{value:.precision$}", value = value.get::<U>())
+    }
+}
+
+struct InformationUnitDispatcher<U: uom::si::information::Unit + uom::Conversion<f64, T = f64>> {
+    u: PhantomData<U>,
+}
+
+impl<U: uom::si::information::Unit + uom::Conversion<f64, T = f64>> InformationUnitDispatcher<U> {
+    fn new() -> Self {
+        InformationUnitDispatcher { u: PhantomData }
+    }
+}
+
+impl<U: uom::si::information::Unit + uom::Conversion<f64, T = f64>> UnitImpl
+    for InformationUnitDispatcher<U>
+{
+    type Quantity = Information;
+
+    fn short_name(&self) -> &'static str {
+        U::abbreviation()
+    }
+
+    fn format_value(&self, value: Information, precision: usize) -> String {
+        format!("{value:.precision$}", value = value.get::<U>())
+    }
+}
+
 #[test]
-fn test_unit_short_name() {
+fn test_time_unit_short_name() {
     assert_eq!("s", TimeUnit::Second.short_name());
     assert_eq!("ms", TimeUnit::MilliSecond.short_name());
     assert_eq!("µs", TimeUnit::MicroSecond.short_name());
@@ -46,11 +151,16 @@ fn test_unit_short_name() {
 // Note - the values are rounded when formatted.
 #[test]
 fn test_unit_format() {
-    let value: f64 = 123.456789;
-    assert_eq!("123.457", TimeUnit::Second.format(value));
-    assert_eq!("123456.8", TimeUnit::MilliSecond.format(value));
+    use crate::quantity::FormatQuantity;
 
-    assert_eq!("1234.6", TimeUnit::MicroSecond.format(0.00123456));
-    assert_eq!("2.1", TimeUnit::Minute.format(value));
-    assert_eq!("0.0", TimeUnit::Hour.format(value));
+    let value = Time::new::<second>(123.456789);
+    assert_eq!("123.457", value.format_value(TimeUnit::Second));
+    assert_eq!("123456.8", value.format_value(TimeUnit::MilliSecond));
+
+    assert_eq!(
+        "1234.6",
+        Time::new::<second>(0.00123456).format_value(TimeUnit::MicroSecond)
+    );
+    assert_eq!("2.1", value.format_value(TimeUnit::Minute));
+    assert_eq!("0.0", value.format_value(TimeUnit::Hour));
 }

src/timer/windows_timer.rs

@@ -27,9 +27,7 @@ use windows_sys::{
     },
 };
 
-use crate::quantity::{microsecond, Information, Time, Zero};
-
-const HUNDRED_NS_PER_MS: i64 = 10;
+use crate::quantity::{nanosecond, Information, Time, Zero};
 
 #[cfg(not(feature = "windows_process_extensions_main_thread_handle"))]
 #[allow(non_upper_case_globals)]
@@ -108,17 +106,14 @@ impl CPUTimer {
             // The `TotalUserTime` is "The total amount of user-mode execution time for
             // all active processes associated with the job, as well as all terminated processes no
             // longer associated with the job, in 100-nanosecond ticks."
-            let user: i64 = job_object_info.TotalUserTime / HUNDRED_NS_PER_MS;
+            let user_time = Time::new::<nanosecond>((job_object_info.TotalUserTime as f64) * 100.0);
 
             // The `TotalKernelTime` is "The total amount of kernel-mode execution time
             // for all active processes associated with the job, as well as all terminated
             // processes no longer associated with the job, in 100-nanosecond ticks."
-            let kernel: i64 = job_object_info.TotalKernelTime / HUNDRED_NS_PER_MS;
-            (
-                Time::new::<microsecond>(user as f64),
-                Time::new::<microsecond>(kernel as f64),
-                Information::zero(),
-            )
+            let system_time =
+                Time::new::<nanosecond>((job_object_info.TotalKernelTime as f64) * 100.0);
+            (user_time, system_time, Information::zero())
         } else {
             (Time::zero(), Time::zero(), Information::zero())
         }

tests/integration_tests.rs

@@ -779,6 +779,22 @@ fn performs_all_benchmarks_in_parameter_scan() {
     ");
 }
 
+#[test]
+fn rejects_negative_parameter_steps() {
+    for step in ["-1", "-1.0"] {
+        hyperfine()
+            .args(["--parameter-scan", "n", "0", "1"])
+            .arg(format!("--parameter-step-size={step}"))
+            .arg("echo {n}")
+            .assert()
+            .code(1)
+            .stdout(predicate::str::is_empty())
+            .stderr(predicate::str::contains(
+                "Parameter step size must be positive",
+            ));
+    }
+}
+
 #[test]
 fn performs_reference_and_all_benchmarks_in_parameter_scan() {
     let _settings = snapshot_settings().bind_to_scope();
@@ -870,6 +886,70 @@ fn exports_intermediate_results_to_file() {
     assert!(contents.contains("true"));
 }
 
+#[test]
+fn invalid_command_options_preserve_export_files() {
+    use tempfile::tempdir;
+
+    for (option, values) in [
+        ("--prepare", ["echo first", "echo second"]),
+        ("--conclude", ["echo first", "echo second"]),
+        ("--output", ["null", "pipe"]),
+    ] {
+        let directory = tempdir().unwrap();
+        let existing_export = directory.path().join("previous.json");
+        let new_export = directory.path().join("new.csv");
+        let previous_results =
+            b"{\"results\":[{\"command\":\"previous benchmark\",\"mean\":1.0}]}\n";
+        std::fs::write(&existing_export, previous_results).unwrap();
+
+        hyperfine()
+            .arg("--runs=1")
+            .arg("--export-json")
+            .arg(&existing_export)
+            .arg("--export-csv")
+            .arg(&new_export)
+            .args([option, values[0], option, values[1]])
+            .arg("echo benchmark")
+            .assert()
+            .failure()
+            .stderr(predicate::str::contains(format!(
+                "The '{option}' option has to be provided just once or N times"
+            )));
+
+        assert_eq!(
+            std::fs::read(&existing_export).unwrap(),
+            previous_results,
+            "{option} validation must preserve previous results"
+        );
+        assert!(
+            !new_export.exists(),
+            "{} validation must not create export files",
+            option
+        );
+    }
+}
+
+#[test]
+fn markdown_export_preserves_backticks_and_pipes_in_command_names() {
+    let _settings = snapshot_settings().bind_to_scope();
+    assert_cmd_snapshot!(hyperfine_debug()
+        .arg("--style=none")
+        .arg("--export-markdown=-")
+        .arg("--command-name=echo `uname` | cat")
+        .arg("sleep 1"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    | Command | Mean [s] | Min [s] | Max [s] | Relative |
+    |:---|---:|---:|---:|---:|
+    | `` echo `uname` \| cat `` | 1.000 ± 0.000 | 1.000 | 1.000 | 1.00 |
+
+
+    ----- stderr -----
+    ");
+}
+
 #[test]
 fn unused_parameters_are_shown_in_benchmark_name() {
     hyperfine()