Utilities.h File Reference

Miscellaneous utility functions, including logging. More...

Go to the source code of this file.

Namespaces
	XPMP2

Macros
#define	ERR_ASSERT   "ASSERT FAILED: %s"
#define	ERR_EXCEPTION   "EXCEPTION CAUGHT: %s"
#define	PATH_DELIM_STD   '/'
#define	WHITESPACE   " \t\f\v\r\n"
#define	XPMP2_FMTARGS(FMT)
	To apply printf-style warnings to our functions. More...
#define	LOG_MSG(lvl, ...)
	Log a message if lvl is greater or equal currently defined log level. More...
#define	LOG_MATCHING(lvl, ...)
	Log a message about matching if logging of model matching is enabled. More...
#define	THROW_ERROR(...)   throw XPMP2Error(__FILE__, __LINE__, __func__, __VA_ARGS__);
	Throws an exception using XPMP2Error. More...
#define	LOG_ASSERT(cond)
	Throw in an assert-style (logging takes place in XPMP2Error constructor) More...
#define	CATCH_AC(ac)
	Standard catch clauses for dealing with aircraft: logs message, sets aircraft invalid. More...
#define	STRCPY_S(dest, src)   strncpy_s(dest,sizeof(dest),src,sizeof(dest)-1)
	Simpler access to strncpy_s if dest is a char array (not a pointer!) More...
#define	STRCPY_ATMOST(dest, src)   strncpy_s(dest,sizeof(dest),strAtMost(src,sizeof(dest)-1).c_str(),sizeof(dest)-1)
#define	SET_THREAD_NAME(sName)

Enumerations
enum	XPMP2::logLevelTy {   XPMP2::logDEBUG = 0 , XPMP2::logINFO , XPMP2::logWARN , XPMP2::logERR ,   XPMP2::logFATAL , XPMP2::logMSG }
	Logging level. More...

Functions
int	XPMP2::PrefsFuncIntDefault (const char *, const char *, int _default)
	Default config function just always returns the provided default value. More...
bool	XPMP2::ExistsFile (const std::string &filename)
	Does a file path exist? More...
bool	XPMP2::IsDir (const std::string &path)
	Is path a directory? More...
bool	XPMP2::CreateDir (const std::string &path)
	Create directory if it does not exist. More...
bool	XPMP2::CopyFileIfNewer (const std::string &source, const std::string &destDir)
	Copy file if source is newer or destination missing. More...
std::list< std::string >	XPMP2::GetDirContents (const std::string &path)
	List of files in a directory (wrapper around XPLMGetDirectoryContents) More...
std::istream &	XPMP2::safeGetline (std::istream &is, std::string &t)
	Read a line from a text file, no matter if ending on CRLF or LF. More...
const std::string &	XPMP2::GetXPSystemPath ()
	Returns XP's system directory, including a trailing slash. More...
std::string	XPMP2::StripXPSysDir (const std::string &path)
	If a path starts with X-Plane's system directory it is stripped. More...
void	XPMP2::RemoveExtension (std::string &path)
	Removes everything after the last dot, the dot including. More...
std::string &	XPMP2::str_tolower (std::string &s)
	change a std::string to uppercase More...
std::string &	XPMP2::rtrim (std::string &s, const char *t=WHITESPACE)
	trimming of string (from right) More...
std::string &	XPMP2::ltrim (std::string &s, const char *t=WHITESPACE)
	trimming of string (from left) More...
std::string &	XPMP2::trim (std::string &s, const char *t=WHITESPACE)
	trimming of string (from both ends) More...
std::string	XPMP2::leftOf (const std::string &s, const std::string &terminators)
	Returns everything left of any of terminators. More...
std::vector< std::string >	XPMP2::str_tokenize (const std::string s, const std::string tokens, bool bSkipEmpty=true)
	separates string into tokens More...
bool	XPMP2::fequal (float a, float b)
	Are these two float near-equal? (to avoid trying something like a == b) More...
template<class T >
T	XPMP2::rad2deg (const T _rad)
	Convert radians to degrees, normalized to [0..360) More...
template<class T >
T	XPMP2::deg2rad (const T _deg)
	Convert degree to radians. More...
template<class T >
T	XPMP2::sqr (const T a)
	Square. More...
template<class T >
T	XPMP2::dist (const T x1, const T y1, const T z1, const T x2, const T y2, const T z2)
	Pythagorean distance between two points in a 3-D world. More...
float	XPMP2::atan2deg (float x, float y)
	atan2 converted to degrees: the angle between (0|0) and the given point More...
float	XPMP2::angleLocCoord (float x1, float z1, float x2, float z2)
	Angle of line from point (x1|z1) to point (x2|z2) More...
float	XPMP2::headDiff (float head1, float head2)
	(Shortest) difference between 2 angles: How much to turn to go from h1 to h2? More...
template<class numT >
numT	XPMP2::headNormalize (numT _head)
	Normalize a heading value to [0..360), works for both float and double values. More...
std::valarray< float >	XPMP2::HeadPitch2Vec (const float head, const float pitch)
	Convert heading/pitch to normalized x/y/z vector. More...
std::valarray< float >	XPMP2::HeadPitchRoll2Normal (const float head, const float pitch, const float roll)
	Convert heading/pitch/roll to unit and normal vector, ie. returns 6 values, first 3 like HeadPitch2Vec, second three the normal vector (pointing "up") More...
float	XPMP2::GetMiscNetwTime ()
	Get synched network time from X-Plane (sim/network/misc/network_time_sec) as used in Log.txt. More...
std::string	XPMP2::GetMiscNetwTimeStr (float _time=NAN)
	Return the network time as a string like used in the XP's Log.txt. More...
const char *	XPMP2::GetGraphicsDriverTxt ()
	Text string for current graphics driver in use. More...
bool	XPMP2::IsPaused ()
	X-Plane in a Pause state? More...
bool	XPMP2::IsViewExternal ()
	Is current X-Plane view an external view (outside a cockpit)? More...
bool	XPMP2::CheckEverySoOften (float &_lastCheck, float _interval, float _now)
	Convenience function to check on something at most every x seconds. More...
bool	XPMP2::CheckEverySoOften (float &_lastCheck, float _interval)
	Convenience function to check on something at most every x seconds. More...
const char *	XPMP2::LogGetString (const char *szFile, int ln, const char *szFunc, logLevelTy lvl, const char *szMsg, va_list args)
	Returns ptr to static buffer filled with formatted log string. More...
void	XPMP2::LogMsg (const char *szFile, int ln, const char *szFunc, logLevelTy lvl, const char *szMsg,...) XPMP2_FMTARGS(5)
	Log Text to log file. More...
std::string	XPMP2::TOPOSIX (const std::string &p)
	On Lin/Win there is no need for a conversion, but we do treat p now as std::string More...
std::string	XPMP2::FROMPOSIX (const std::string &p)
	On Lin/Win there is no need for a conversion, but we do treat p now as std::string More...

Variables
constexpr const char *	XPMP2::RSRC_RELATED = "related.txt"
constexpr const char *	XPMP2::RSRC_REL_OP = "relOp.txt"
constexpr const char *	XPMP2::RSRC_DOC8643 = "Doc8643.txt"
constexpr const char *	XPMP2::RSRC_MAP_ICONS = "MapIcons.png"
constexpr const char *	XPMP2::RSRC_OBJ8DATAREFS = "Obj8DataRefs.txt"
constexpr double	XPMP2::PI = 3.1415926535897932384626433832795028841971693993751
	Pi. More...
constexpr float	XPMP2::EPSILON_F = 0.00001f
	Epsilon, a small number. More...

Detailed Description

Miscellaneous utility functions, including logging.

Author

Birger Hoppe

Copyright

(c) 2020 Birger Hoppe

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Macro Definition Documentation

CATCH_AC

#define CATCH_AC

(

ac

)

Value:

    catch (const std::exception& e) {                               \
        LOG_MSG(logFATAL, ERR_EXCEPTION, e.what());                 \
        (ac).SetInvalid();                                          \
    }                                                               \
    catch (...) {                                                   \
        LOG_MSG(logFATAL, ERR_EXCEPTION, "<unknown>");              \
        (ac).SetInvalid();                                          \
    }

Standard catch clauses for dealing with aircraft: logs message, sets aircraft invalid.

ERR_ASSERT

#define ERR_ASSERT   "ASSERT FAILED: %s"

ERR_EXCEPTION

#define ERR_EXCEPTION   "EXCEPTION CAUGHT: %s"

LOG_ASSERT

#define LOG_ASSERT

(

cond

)

Value:

    if (!(cond)) {                                                  \
        THROW_ERROR(ERR_ASSERT,#cond);                              \
    }

Throw in an assert-style (logging takes place in XPMP2Error constructor)

Note

This conditional check always takes place, independend of any build or logging settings!

LOG_MATCHING

#define LOG_MATCHING	(		lvl,
			...
	)

Value:

    {                                    \
    if (XPMP2::glob.bLogMdlMatch && lvl >= glob.logLvl)             \
    {LogMsg(__FILE__, __LINE__, __func__, lvl, __VA_ARGS__);}       \
}

Log a message about matching if logging of model matching is enabled.

Note

First parameter after lvl must be the message text, which can be a format string with its parameters following like in sprintf

LOG_MSG

#define LOG_MSG	(		lvl,
			...
	)

Value:

    {                                         \
    if (lvl >= XPMP2::glob.logLvl)                                  \
    {LogMsg(__FILE__, __LINE__, __func__, lvl, __VA_ARGS__);}       \
}

Log a message if lvl is greater or equal currently defined log level.

Note

First parameter after lvl must be the message text, which can be a format string with its parameters following like in sprintf

PATH_DELIM_STD

#define PATH_DELIM_STD   '/'

SET_THREAD_NAME

#define SET_THREAD_NAME

(

sName

)

STRCPY_ATMOST

#define STRCPY_ATMOST	(		dest,
			src
	)		strncpy_s(dest,sizeof(dest),strAtMost(src,sizeof(dest)-1).c_str(),sizeof(dest)-1)

STRCPY_S

#define STRCPY_S	(		dest,
			src
	)		strncpy_s(dest,sizeof(dest),src,sizeof(dest)-1)

Simpler access to strncpy_s if dest is a char array (not a pointer!)

THROW_ERROR

#define THROW_ERROR

(

...

)

throw XPMP2Error(__FILE__, __LINE__, __func__, __VA_ARGS__);

Throws an exception using XPMP2Error.

Note

First parameter after lvl must be the message text, which can be a format string with its parameters following like in sprintf

WHITESPACE

#define WHITESPACE   " \t\f\v\r\n"

XPMP2_FMTARGS

#define XPMP2_FMTARGS

(

FMT

)

To apply printf-style warnings to our functions.

See also

Taken from imgui.h's definition of IM_FMTARGS