Core utilities

The axom::utilities namespace contains basic useful functions. Often these have started out in another, higher-level library and proven so useful they’re “promoted” to Axom Core. In some cases, axom::utilities brings functionality from recent standards of C++ 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(cmp, 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. There is also processAbort, to gracefully end an application. For details on all these, please see the API documentation.