Add --benchmark_human_readable flag

Allows used to add a command line flag called
`--benchmark_human_readable`. By adding this flag the arguments passed
to benchmarks are formated in a human friendly format. This means that
numbers that are the power of 2 are formatted as `2^x` (e.g., 64 will be
`2^6`). For numbers that are the power of 10 a different formatting
style is used. Numbers 0-999 no formatting is used. For numbers
1000-999999 the format `k` is used (e.g., `32000` -> `32k`). This also
works for millions and billions. For numbers greater than 999 billion no
special formatting is used.
The design is rather simple allowing to by easily extendable.

Closes: google#1006

Author: DiegoKrupitza

docs/user_guide.md

@@ -185,6 +185,57 @@ BM_memcpy/32          12 ns         12 ns   54687500
 BM_memcpy/32k       1834 ns       1837 ns     357143
 ```
 
+<a name="running-with-human-readable-format" />
+
+## Human Readable Format
+
+The `--benchmark_human_readable={true|false}` option can be used to display 
+args in a more human friendly format. Meaning numbers that are power of 2
+will be formatted as `2^x`. Furthermore, for numbers that are the power of 
+10 special formatting abbreviations are used. For instance, `1000` will be
+formatted to `1k`, `32000` to `32k`, `1000000` to `1m` and so on. 
+
+By default `benchmark_human_readable` is disabled. 
+
+
+```bash
+$ ./run_benchmarks.x
+Run on (1 X 2300 MHz CPU )
+2016-06-25 19:34:24
+BM_base_two_args/1                2.22 ns         2.22 ns      6280843
+BM_base_two_args/2                2.20 ns         2.20 ns      6278027
+BM_base_two_args/64               2.14 ns         2.14 ns      6263982
+BM_base_two_args/128              2.22 ns         2.22 ns      6286484
+BM_base_ten_args/1                2.25 ns         2.25 ns      6349206
+BM_base_ten_args/10               2.18 ns         2.18 ns      6241641
+BM_base_ten_args/100              2.24 ns         2.24 ns      6167401
+BM_base_ten_args/1000             2.25 ns         2.25 ns      6137659
+BM_base_ten_args/10000            2.24 ns         2.24 ns      6068487
+BM_base_ten_args/32000            2.26 ns         2.26 ns      6063231
+BM_base_ten_args/100000           2.25 ns         2.25 ns      6105539
+BM_base_ten_args/1000000          2.21 ns         2.21 ns      6766554
+BM_base_ten_args/1000000000       2.23 ns         2.23 ns      6233304
+```
+
+```bash
+$ ./run_benchmarks.x --benchmark_human_readable
+Run on (1 X 2300 MHz CPU )
+2016-06-25 19:34:24
+BM_base_two_args/1              2.18 ns         2.18 ns      6222222
+BM_base_two_args/2^1            2.24 ns         2.24 ns      6208426
+BM_base_two_args/2^6            2.24 ns         2.24 ns      6159261
+BM_base_two_args/2^7            2.25 ns         2.25 ns      6337709
+BM_base_ten_args/1              2.27 ns         2.27 ns      6071119
+BM_base_ten_args/10             2.32 ns         2.32 ns      6278027
+BM_base_ten_args/100            2.28 ns         2.27 ns      6029285
+BM_base_ten_args/1k             2.27 ns         2.26 ns      5845511
+BM_base_ten_args/10k            2.27 ns         2.26 ns      6252791
+BM_base_ten_args/32k            2.27 ns         2.26 ns      6208426
+BM_base_ten_args/100k           2.27 ns         2.26 ns      6129597
+BM_base_ten_args/1m             2.28 ns         2.28 ns      5988024
+BM_base_ten_args/1bn            2.25 ns         2.25 ns      6211180
+```
+
 ## Disabling Benchmarks
 
 It is possible to temporarily disable benchmarks by renaming the benchmark

src/benchmark.cc

@@ -144,6 +144,9 @@ BM_DEFINE_string(benchmark_time_unit, "");
 // The level of verbose logging to output
 BM_DEFINE_int32(v, 0);
 
+// defines whether to use human-readable format or not
+BM_DEFINE_bool(benchmark_human_readable, false);
+
 namespace internal {
 
 std::map<std::string, std::string>* global_context = nullptr;
@@ -691,7 +694,9 @@ void ParseCommandLineFlags(int* argc, char** argv) {
                           &FLAGS_benchmark_context) ||
         ParseStringFlag(argv[i], "benchmark_time_unit",
                         &FLAGS_benchmark_time_unit) ||
-        ParseInt32Flag(argv[i], "v", &FLAGS_v)) {
+        ParseInt32Flag(argv[i], "v", &FLAGS_v) ||
+        ParseBoolFlag(argv[i], "benchmark_human_readable",
+                      &FLAGS_benchmark_human_readable)) {
       for (int j = i; j != *argc - 1; ++j) argv[j] = argv[j + 1];
 
       --(*argc);
@@ -743,6 +748,7 @@ void PrintDefaultHelp() {
 #endif
           "          [--benchmark_context=<key>=<value>,...]\n"
           "          [--benchmark_time_unit={ns|us|ms|s}]\n"
+          "          [--benchmark_human_readable={true|false}]\n"
           "          [--v=<verbosity>]\n");
 }
 

src/benchmark_api_internal.cc

@@ -5,6 +5,9 @@
 #include "string_util.h"
 
 namespace benchmark {
+
+BM_DECLARE_bool(benchmark_human_readable);
+
 namespace internal {
 
 BenchmarkInstance::BenchmarkInstance(Benchmark* benchmark, int family_idx,
@@ -43,7 +46,20 @@ BenchmarkInstance::BenchmarkInstance(Benchmark* benchmark, int family_idx,
       }
     }
 
-    name_.args += StrFormat("%" PRId64, arg);
+    // formatting args either in default mode or in human-readable
+    auto formattedArgument = StrFormat("%" PRId64, arg);
+
+    if (FLAGS_benchmark_human_readable) {
+      if ((arg & (arg - 1)) == 0 && (arg > 1)) {
+        // power of two human format
+        formattedArgument = StrFormat("2^%.0f", std::log2(arg));
+      } else if (arg % 10 == 0 && (arg > 0)) {
+        // base 10 human format
+        formattedArgument = Base10HumanReadableFormat::get(arg);
+      }
+    }
+
+    name_.args += formattedArgument;
     ++arg_i;
   }
 
@@ -114,5 +130,55 @@ void BenchmarkInstance::Teardown() const {
     teardown_(st);
   }
 }
+
+const std::array<Base10HumanReadableFormat, 5>
+    Base10HumanReadableFormat::ranges = {
+        Base10HumanReadableFormat{1, ""},             // from 0 to 10^3-1
+        Base10HumanReadableFormat{1000, "k"},         // from 10^3 to 10^6-1
+        Base10HumanReadableFormat{1000000, "m"},      // from 10^6 to 10^9-1
+        Base10HumanReadableFormat{1000000000, "bn"},  // from 10^9 to 10^12-1
+        Base10HumanReadableFormat{1000000000000, ""}  // above show as full
+};
+
+std::string Base10HumanReadableFormat::get(const int64_t& arg) {
+  // binary search for the best match
+  std::size_t left = 0;
+  std::size_t right = ranges.size() - 1;
+
+  while (left <= right) {
+    const std::size_t middle = left + std::floor((right - left) / 2);
+    const auto& middle_val = ranges[middle].entry_val_;
+
+    if (middle_val == arg) {
+      left = middle;
+      break;
+    }
+
+    if (arg < middle_val) {
+      right = middle - 1;
+    } else {
+      left = middle + 1;
+    }
+  }
+
+  const auto min_index = std::min(left, right);
+
+  // in case we get the "above" we return the '1' just for simplicity.
+  // because we use the "entry_val_" in later stages for division.
+  const auto& readable_format =
+      ranges[(min_index == ranges.size() - 1 ? 0 : min_index)];
+
+  // if it is not a perfect match we return the value
+  // e.g. 1030 we do not want 10k we want 1030
+  if (arg % readable_format.entry_val_ != 0) {
+    return StrFormat("%" PRId64, arg);
+  }
+
+  // for everything else we want the abbreviation
+  const auto reduced_val = arg / readable_format.entry_val_;
+  return StrFormat("%" PRId64 "%s", reduced_val,
+                   readable_format.abbreviation_.c_str());
+}
+
 }  // namespace internal
 }  // namespace benchmark

src/benchmark_api_internal.h

@@ -1,6 +1,8 @@
 #ifndef BENCHMARK_API_INTERNAL_H
 #define BENCHMARK_API_INTERNAL_H
 
+#include <array>
+#include <cinttypes>
 #include <cmath>
 #include <iosfwd>
 #include <limits>
@@ -10,10 +12,29 @@
 
 #include "benchmark/benchmark.h"
 #include "commandlineflags.h"
+#include "string_util.h"
 
 namespace benchmark {
 namespace internal {
 
+struct Base10HumanReadableFormat {
+  const int64_t entry_val_;
+  const std::string abbreviation_;
+
+  // holds all the possible abbreviation limits, easily expandable by adding a
+  // new line. Keep in mind they need to be in ascending order such that binary
+  // search works.
+  const static std::array<Base10HumanReadableFormat, 5> ranges;
+
+  /**
+   * Gets the human readable format for a given base10 value.
+   * In other words converts 1_000 to 1k, 40_000_000 to 40m etc
+   * @param arg the positive value to convert
+   * @return human readable formatted string
+   */
+  static std::string get(const int64_t& arg);
+};
+
 // Information kept per benchmark we may want to run
 class BenchmarkInstance {
  public:

test/CMakeLists.txt

@@ -177,6 +177,12 @@ add_test(NAME user_counters_thousands_test COMMAND user_counters_thousands_test
 compile_output_test(memory_manager_test)
 add_test(NAME memory_manager_test COMMAND memory_manager_test --benchmark_min_time=0.01s)
 
+compile_benchmark_test(human_readable_formatting_test)
+add_test(NAME human_readable_formatting_test COMMAND human_readable_formatting_test --benchmark_min_time=0.01s --benchmark_human_readable)
+
+compile_benchmark_test(non_human_readable_formatting_test)
+add_test(NAME non_human_readable_formatting_test COMMAND non_human_readable_formatting_test --benchmark_min_time=0.01s --benchmark_human_readable=false)
+
 # MSVC does not allow to set the language standard to C++98/03.
 if(NOT CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
   compile_benchmark_test(cxx03_test)
@@ -237,6 +243,7 @@ if (BENCHMARK_ENABLE_GTEST_TESTS)
   add_gtest(perf_counters_gtest)
   add_gtest(time_unit_gtest)
   add_gtest(min_time_parse_gtest)
+  add_gtest(human_readable_gtest)
 endif(BENCHMARK_ENABLE_GTEST_TESTS)
 
 ###############################################################################

test/human_readable_formatting_test.cc

@@ -0,0 +1,113 @@
+#undef NDEBUG
+
+#include <cassert>
+#include <vector>
+
+#include "../src/check.h"  // NOTE: check.h is for internal use only!
+#include "benchmark/benchmark.h"
+
+namespace {
+
+class TestReporter : public benchmark::ConsoleReporter {
+ public:
+  bool ReportContext(const Context& context) override {
+    return ConsoleReporter::ReportContext(context);
+  };
+
+  void ReportRuns(const std::vector<Run>& report) override {
+    all_runs_.insert(all_runs_.end(), begin(report), end(report));
+    ConsoleReporter::ReportRuns(report);
+  }
+
+  TestReporter() {}
+  ~TestReporter() override {}
+
+  mutable std::vector<Run> all_runs_;
+};
+
+struct TestCase {
+  std::string name;
+
+  typedef benchmark::BenchmarkReporter::Run Run;
+
+  void CheckRun(Run const& run) const {
+    BM_CHECK(name == run.benchmark_name())
+        << "expected " << name << " got " << run.benchmark_name();
+  }
+};
+
+std::vector<TestCase> ExpectedResults;
+
+int AddCases(const std::string& base_name,
+             std::initializer_list<TestCase> const& v) {
+  for (auto TC : v) {
+    TC.name = base_name + TC.name;
+    ExpectedResults.push_back(std::move(TC));
+  }
+  return 0;
+}
+
+#define CONCAT(x, y) CONCAT2(x, y)
+#define CONCAT2(x, y) x##y
+#define ADD_CASES(...) int CONCAT(dummy, __LINE__) = AddCases(__VA_ARGS__)
+
+}  // end namespace
+
+// ============== test case we non base 2 args ============== //
+void BM_non_base_two_args(benchmark::State& state) {
+  for (auto _ : state) {
+  }
+}
+BENCHMARK(BM_non_base_two_args)->Arg(9)->Arg(19)->Arg(24)->Arg(1023);
+ADD_CASES("BM_non_base_two_args", {{"/9"}, {"/19"}, {"/24"}, {"/1023"}});
+
+// ============== test case we base 2 args ============== //
+void BM_base_two_args(benchmark::State& state) {
+  for (auto _ : state) {
+  }
+}
+BENCHMARK(BM_base_two_args)->RangeMultiplier(2)->Range(1, 2 << 7 - 1);
+ADD_CASES("BM_base_two_args", {{"/1"},
+                               {"/2^1"},
+                               {"/2^2"},
+                               {"/2^3"},
+                               {"/2^4"},
+                               {"/2^5"},
+                               {"/2^6"},
+                               {"/2^7"}});
+
+// ============== test case we base 10 args ============== //
+void BM_base_ten_args(benchmark::State& state) {
+  for (auto _ : state) {
+  }
+}
+BENCHMARK(BM_base_ten_args)->Arg(1)->Arg(10)->Arg(100)->Arg(1000)->Arg(10000)->Arg(32000)->Arg(100000)->Arg(1000000)->Arg(1000000000);
+ADD_CASES("BM_base_ten_args", {{"/1"},
+                               {"/10"},
+                               {"/100"},
+                               {"/1k"},
+                               {"/10k"},
+                               {"/32k"},
+                               {"/100k"},
+                               {"/1m"},
+                               {"/1bn"}});
+
+int main(int argc, char* argv[]) {
+  benchmark::Initialize(&argc, argv);
+
+  TestReporter test_reporter;
+  benchmark::RunSpecifiedBenchmarks(&test_reporter);
+
+  typedef benchmark::BenchmarkReporter::Run Run;
+
+  auto EB = ExpectedResults.begin();
+
+  for (Run const& run : test_reporter.all_runs_) {
+    assert(EB != ExpectedResults.end());
+    EB->CheckRun(run);
+    ++EB;
+  }
+  assert(EB == ExpectedResults.end());
+
+  return 0;
+}

test/human_readable_gtest.cc

@@ -0,0 +1,49 @@
+//===---------------------------------------------------------------------===//
+// human_readable_test - Unit tests for human readable converters
+//===---------------------------------------------------------------------===//
+
+#include "../src/benchmark_api_internal.h"
+#include "gtest/gtest.h"
+
+namespace {
+TEST(HumanReadableTest, base10) {
+  using Base10Human = benchmark::internal::Base10HumanReadableFormat;
+  {
+    const auto res = Base10Human::get(10000);
+    EXPECT_STREQ(res.c_str(), "10k");
+  }
+  {
+    const auto res = Base10Human::get(20000);
+    EXPECT_STREQ(res.c_str(), "20k");
+  }
+  {
+    const auto res = Base10Human::get(32000);
+    EXPECT_STREQ(res.c_str(), "32k");
+  }
+  {
+    const auto res = Base10Human::get(100);
+    EXPECT_STREQ(res.c_str(), "100");
+  }
+  {
+    const auto res = Base10Human::get(1000000);
+    EXPECT_STREQ(res.c_str(), "1m");
+  }
+  {
+    const auto res = Base10Human::get(42000000);
+    EXPECT_STREQ(res.c_str(), "42m");
+  }
+  {
+    const auto res = Base10Human::get(4000000000);
+    EXPECT_STREQ(res.c_str(), "4bn");
+  }
+  {
+    const auto res = Base10Human::get(4200000000);
+    EXPECT_STREQ(res.c_str(), "4200000000");
+  }
+  {
+    const auto res = Base10Human::get(40200000);
+    EXPECT_STREQ(res.c_str(), "40200000");
+  }
+}
+
+}  // end namespace