Core utilities

The axom::utilities namespace contains basic commonly-used functions. Often these started out in another Axom component and were “promoted” to Axom Core when they were useful in other Axom libraries. In some cases, axom::utilities brings functionality from recent C++ standards to platforms restricted to older compilers.

Axom can print a self-explanatory message and provide a version string.

  std::cout << "Here is a message telling you about Axom." << std::endl;
  axom::about();

  std::cout << "The version string '" << axom::getVersion()
            << "' is part of the previous message, " << std::endl
            << " and is also available separately." << std::endl;

Here a function showing the usage of string and filesystem facilities available in Axom Core.

void demoFileSystemAndString(const char* argv0)
{
  using namespace axom::utilities;

  // Get the current directory
  std::string cwd = filesystem::getCWD();

  // Split it on file separator.
#if WIN32
  const char pathsep = '\\';
#else
  const char pathsep = '/';
#endif
  std::vector<std::string> cmp = string::split(cwd, pathsep);

  // Count how many start with "ax" or end with "exe"
  // (we could also use std::count_if)
  int matchcount = 0;
  std::string prefix {"ax"};
  std::string suffix {"exe"};
  const int N = static_cast<int>(cmp.size());
  for(int i = 0; i < N; ++i)
  {
    if(string::startsWith(cmp[i], prefix) || string::endsWith(cmp[i], suffix))
    {
      matchcount += 1;
    }
  }
  std::cout << "Found " << matchcount << " path components starting with "
            << prefix << " or ending with " << suffix << "." << std::endl;

  // Append "hello.txt"
  std::string hellofile =
    filesystem::joinPath(cwd, "hello.txt", std::string {pathsep});

  // Does this exist?
  std::cout << "The file \"hello.txt\" ";
  if(filesystem::pathExists(hellofile))
  {
    std::cout << "exists ";
  }
  else
  {
    std::cout << "DOES NOT exist ";
  }
  std::cout << "in the current working directory." << std::endl;

  // Does argv0 exist?
  if(filesystem::pathExists(argv0))
  {
    std::cout << argv0 << " exists ";
  }
  else
  {
    std::cout << argv0 << " DOES NOT exist ";
  }
  std::cout << "in the current working directory." << std::endl;

  // sleep for a second
  sleep(1);
}

Axom Core also includes a Timer class. Here, we time the preceding filesystem example snippet.

  axom::utilities::Timer t;

  t.start();

  if(argc == 1)
  {
    std::cerr << "Error: no path given on command line" << std::endl;
    return 1;
  }
  else
  {
    demoFileSystemAndString(argv[0]);
  }

  t.stop();

  std::cout << "The tests took " << t.elapsedTimeInMilliSec() << " ms."
            << std::endl;

There are several other utility functions. Some are numerical functions such as variations on clamp (ensure a variable is restricted to a given range) and swap (exchange the values of two variables). There are also functions for testing values with tolerances, such as isNearlyEqual and isNearlyEqualRelative. These are provided since they work in device (GPU) kernel code, wheras C++ standard library routines do not. There is also processAbort, to gracefully exit an application. For details, please see the Axom Core API Documentation.