utilFunctions.h

Go to the documentation of this file.

/*********************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*********************************************************************************/
 
//! \file utilFunctions.h
//! \ingroup vreUtil
//! \brief Provides common utility functions for the VREngage system
//!
//! This file contains various utility functions for timing, string manipulation,
//! mathematical operations, and type conversions that are used throughout the
//! VREngage codebase.
 
#pragma once
 
#include "vreUtil/export.h"
 
#include <matrix/vlVector.h>
#include <matrix/vlTaitBryan.h>
 
#include <vlutil/vlString.h>
 
#include <string>
#include <vector>
 
// Signals helpers
#include <boost/signals2/signal.hpp>
#include <boost/signals2/connection.hpp>
 
namespace makVre
{
 
//! \brief Unsigned 16-bit integer type
using UInt16 = unsigned short;
//! \brief Signed 16-bit integer type
using Int16 = short;
//! \brief Unsigned 32-bit integer type
using UInt32 = unsigned long;
//! \brief Signed 32-bit integer type
using Int32 = long;
//! \brief Unsigned 64-bit integer type
using UInt64 = unsigned long long;
//! \brief Signed 64-bit integer type
using Int64 = long long;
 
//! \brief Inverse of CPU frequency for time calculations
extern double invFreq;
//! \brief Number of CPU ticks per second
extern UInt64 ticksPerSecond;
//! \brief Flag indicating if the high-resolution timer is initialized
extern bool timerIsInitialized;
 
//! \brief Initializes the high-resolution timer
//!
//! This function can be safely called multiple times, but only the first call has any effect.
//! It is automatically called when the library is loaded and by the profiler, so users
//! typically do not need to call it directly.
//!
//! \return True if initialization succeeded, false otherwise
bool UTIL_DLL DtInitializeTimer();
 
//! \brief Gets a high-resolution CPU timestamp
//!
//! Returns a high-resolution 64-bit timestamp from the CPU, typically used for profiling.
//! If the CPU doesn't support high-resolution counter instructions, uses QueryPerformanceCounter()
//! as a fallback on Windows. On Linux, this function uses gettime().
//!
//! \return 64-bit timestamp value
UInt64 UTIL_DLL DtVreTimestamp();
 
//! \brief Gets a high-resolution time in seconds
//!
//! Returns the elapsed time in seconds since the system was started.
//! Uses DtTimestamp() internally and converts the result to seconds.
//!
//! \return Time in seconds (double precision)
double UTIL_DLL DtWallClockTime();
 
//! \brief Gets the current thread ID
//!
//! Returns a platform-independent identifier for the current thread.
//!
//! \return Thread identifier as an unsigned integer
unsigned int UTIL_DLL DtGetThreadId();
 
//! \brief Checks if an environment variable is set
//!
//! Tests if the specified environment variable exists and optionally compares its
//! value against a test value (case-insensitive comparison).
//!
//! \param env Name of the environment variable to check
//! \param testValue Optional value to compare against (empty string to just check existence)
//! \return True if the variable exists and equals testValue (if provided), false otherwise
bool UTIL_DLL DtIsEnvironmentVariableSet(const std::string& env, const std::string& testValue = "");
 
//! \brief Finds a command-line argument and its parameter
//!
//! Searches for a specific argument in an argv array and retrieves the parameter
//! that follows it if requested.
//!
//! \param arg The argument to search for
//! \param argc Number of arguments in the argv array
//! \param argv Array of command-line arguments
//! \param param Optional output parameter to store the value following the argument
//! \return True if the argument was found, false otherwise
bool UTIL_DLL findArg(const char* arg, int argc, char** argv, const char* param[]);
 
//! \brief Finds a command-line argument
//!
//! Searches for a specific argument in an argv array without retrieving its parameter.
//!
//! \param arg The argument to search for
//! \param argc Number of arguments in the argv array
//! \param argv Array of command-line arguments
//! \return True if the argument was found, false otherwise
bool UTIL_DLL findArg(const char* arg, int argc, char** argv);
 
//! \brief Converts a floating-point value to a string (radians to angle string)
//!
//! Converts a floating-point value (typically an angle in radians) to a string representation.
//!
//! \param r The floating-point value to convert
//! \return String representation of the value
std::string UTIL_DLL rtoa(float r);
 
//! \brief Splits a string into tokens
//!
//! Divides a string into substrings (tokens) based on a delimiter.
//!
//! \param string The string to tokenize
//! \param delimiter The delimiter string (defaults to space)
//! \return Vector of tokens
std::vector<std::string> UTIL_DLL tokenize(const std::string& string, const std::string& delimiter = " ");
 
//! \brief Removes leading and trailing whitespace from a string
//!
//! Trims whitespace characters from the beginning and end of a string.
//!
//! \param str The string to trim
//! \return Trimmed string
std::string UTIL_DLL trim(const std::string& str);
 
//! \brief Creates a new string with a substring range replaced
//!
//! Returns a new string with the range starting from 'start' and ending with 'end'
//! replaced with the replacement string.
//!
//! \param string The original string
//! \param start The starting substring
//! \param end The ending substring
//! \param replacement The replacement string
//! \return New string with the substring range replaced
std::string UTIL_DLL subStrRangeReplaced(
   const std::string& string, const std::string& start, const std::string& end, const std::string& replacement);
 
//! \brief Replaces a substring range in-place
//!
//! Modifies the original string, replacing the range starting from 'start' and
//! ending with 'end' with the replacement string.
//!
//! \param string The string to modify
//! \param start The starting substring
//! \param end The ending substring
//! \param replacement The replacement string
void UTIL_DLL replaceSubStrRange(
   std::string& string, const std::string& start, const std::string& end, const std::string& replacement);
 
//! \brief Creates a new string with all occurrences of a substring replaced
//!
//! Returns a new string with all occurrences of the target substring replaced
//! with the replacement string.
//!
//! \param string The original string
//! \param target The substring to replace
//! \param replacement The replacement string
//! \return New string with all occurrences replaced
std::string UTIL_DLL subStrReplaced(
   const std::string& string, const std::string& target, const std::string& replacement);
 
//! \brief Replaces all occurrences of a substring in-place
//!
//! Modifies the original string, replacing all occurrences of the target substring
//! with the replacement string.
//!
//! \param string The string to modify
//! \param target The substring to replace
//! \param replacement The replacement string
void UTIL_DLL replaceSubStr(std::string& string, const std::string& target, const std::string& replacement);
 
//! \brief Creates a new string clamped to a maximum length
//!
//! Returns a new string clamped to the specified maximum length,
//! appending a tail string (default "...") if truncated.
//!
//! \param string The original string
//! \param length Maximum length of the resulting string
//! \param tail String to append if truncation occurs (typically "...")
//! \return New string clamped to the maximum length
std::string UTIL_DLL lengthClamped(const std::string& string, size_t length, const std::string& tail = "...");
 
//! \brief Clamps a string to a maximum length in-place
//!
//! Modifies the original string, clamping it to the specified maximum length
//! and appending a tail string (default "...") if truncated.
//!
//! \param string The string to modify
//! \param length Maximum length of the resulting string
//! \param tail String to append if truncation occurs (typically "...")
void UTIL_DLL clampLength(std::string& string, size_t length, const std::string& tail = "...");
 
//! \brief Converts a string to lowercase in-place
//!
//! Modifies the original string, converting all characters to lowercase.
//!
//! \param str The string to modify
void UTIL_DLL makeLower(std::string& str);
 
//! \brief Creates a new string with all characters converted to lowercase
//!
//! Returns a new string with all characters converted to lowercase.
//!
//! \param in The original string
//! \return New string in lowercase
std::string UTIL_DLL lowerCase(const std::string& in);
 
//! \brief Clamps a value to a specified precision
//!
//! Rounds a double value to the nearest multiple of the specified precision value.
//! For example, with precision=0.001, the value 1.23456 would be clamped to 1.235.
//!
//! \param val The value to clamp
//! \param precision The precision to clamp to (e.g., 0.001 for three decimal places)
//! \return The clamped value
double UTIL_DLL clampToPrecision(double val, double precision);
 
//! \brief Clamps a vector to a specified precision
//!
//! Applies precision clamping to each component of a 3D vector.
//!
//! \param val The vector to clamp
//! \param precision The precision to clamp to
//! \return The clamped vector
DtVector UTIL_DLL clampToPrecision(DtVector val, double precision);
 
//! \brief Clamps Tait-Bryan angles to a specified precision
//!
//! Applies precision clamping to each angle in a Tait-Bryan representation.
//!
//! \param val The Tait-Bryan angles to clamp
//! \param precision The precision to clamp to
//! \return The clamped Tait-Bryan angles
DtTaitBryan UTIL_DLL clampToPrecision(DtTaitBryan val, double precision);
 
//! \brief Clamps a value between a minimum and maximum range
//! \tparam T Type of the value and range bounds
//! \param value The value to clamp
//! \param min The minimum allowed value
//! \param max The maximum allowed value
//! \return The clamped value
template <class T>
T clampValue(T value, T min, T max)
{
   if (value < min)
   {
      return min;
   }
   else if (value > max)
   {
      return max;
   }
   return value;
}
 
//! \brief Explicit instantiation for int clampValue
template int UTIL_DLL clampValue<int>(int, int, int);
//! \brief Explicit instantiation for float clampValue
template float UTIL_DLL clampValue<float>(float, float, float);
//! \brief Explicit instantiation for double clampValue
template double UTIL_DLL clampValue<double>(double, double, double);
 
//! \brief Generates a random integer within a specified range
//!
//! Returns a random integer between min and max (inclusive).
//!
//! \param min The minimum value (inclusive)
//! \param max The maximum value (inclusive)
//! \return A random integer within the specified range
int UTIL_DLL randomInt(int min, int max);
 
//! \brief Generates a random number within a specified range
//!
//! Returns a double-precision random number between min and max (inclusive).
//!
//! \param min The minimum value (inclusive)
//! \param max The maximum value (inclusive)
//! \return A random integer within the specified range
double UTIL_DLL randReal(double min, double max);
 
//! \brief Converts a string to a boolean value
//!
//! Converts strings like "true", "1", "yes" to true, and "false", "0", "no" to false.
//! Case-insensitive.
//!
//! \param in The string to convert
//! \return The boolean value
bool UTIL_DLL stob(const std::string& in);
 
//! \brief Converts a string to an integer
//!
//! \param in The string to convert
//! \return The integer value
int UTIL_DLL stoi(const std::string& in);
 
//! \brief Converts a string to a long integer
//!
//! \param in The string to convert
//! \return The long integer value
long UTIL_DLL stol(const std::string& in);
 
//! \brief Converts a string to an unsigned long integer
//!
//! \param in The string to convert
//! \return The unsigned long integer value
unsigned long UTIL_DLL stoul(const std::string& in);
 
//! \brief Converts a string to a long long integer
//!
//! \param in The string to convert
//! \return The long long integer value
long long UTIL_DLL stoll(const std::string& in);
 
//! \brief Converts a string to an unsigned long long integer
//!
//! \param in The string to convert
//! \return The unsigned long long integer value
unsigned long long UTIL_DLL stoull(const std::string& in);
 
//! \brief Converts a string to a float
//!
//! \param in The string to convert
//! \return The float value
float UTIL_DLL stof(const std::string& in);
 
//! \brief Converts a string to a double
//!
//! \param in The string to convert
//! \return The double value
double UTIL_DLL stod(const std::string& in);
 
 
class UTIL_DLL DtFileString : public DtString
{
public:
   bool read(const DtFilename& filename);
   bool write(const DtFilename& filename);
};
 
void UTIL_DLL fixMissingBoostClosingTag(DtString& xml);
 
//! \brief Helper: connect a slot to a Boost.Signals2 signal to run only once (back).
//!
//! This helper connects a lambda or callable to a Boost.Signals2 signal such that the
//! callable is invoked the next time the signal is emitted and then automatically
//! disconnected. This avoids using boost::bind/std::bind and favors modern lambdas.
//!
//! Ordering: attaches at the back (default) to preserve existing emission order.
//!
//! Usage example:
//!   connectOnce(de.signal_postInitialize, [&de]{ postInit(&de); });
//!
//! \tparam Signal  A boost::signals2::signal type
//! \tparam F       Callable type; signature should match the signal's arguments
//! \param sig      The signal instance to connect to
//! \param f        The callable to invoke on the next emission
//! \return boost::signals2::connection for the installed slot
template <class Signal, class F>
inline boost::signals2::connection connectOnce(Signal& sig, F&& f)
{
   return sig.connect_extended(
      [func = std::forward<F>(f)](const boost::signals2::connection& c, auto&&... args) mutable {
         func(std::forward<decltype(args)>(args)...);
         c.disconnect();
      },
      boost::signals2::at_back);
}
 
//! \brief Helper: connect a slot to a Boost.Signals2 signal to run only once (front).
//!
//! Same behavior as connectOnce(), but attaches the slot at the front so it runs before
//! other slots. This is useful when initialization must occur first.
//!
//! Usage example:
//!   connectOnceFront(de.signal_postInitialize, [&de]{ postInit(&de); });
//!
//! \tparam Signal  A boost::signals2::signal type
//! \tparam F       Callable type; signature should match the signal's arguments
//! \param sig      The signal instance to connect to
//! \param f        The callable to invoke on the next emission
//! \return boost::signals2::connection for the installed slot
template <class Signal, class F>
inline boost::signals2::connection connectOnceFront(Signal& sig, F&& f)
{
   return sig.connect_extended(
      [func = std::forward<F>(f)](const boost::signals2::connection& c, auto&&... args) mutable {
         func(std::forward<decltype(args)>(args)...);
         c.disconnect();
      },
      boost::signals2::at_front);
}
 
} // namespace makVre