Utilities.h File Reference

Miscellaneous utility functions, including logging. More...

Go to the source code of this file.

Classes
class	StrTokens
	Class to extract tokens from a string. More...

Macros
#define	ERR_ASSERT   "ASSERT FAILED: %s"
#define	ERR_EXCEPTION   "EXCEPTION CAUGHT: %s"
#define	STR_N(s)   str_n(s,sizeof(s))
	Simplify using str_n() with char arrays. More...
#define	XPPLANES_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	THROW_ERROR(...)   throw XPMP2::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	SET_THREAD_NAME(sName)

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

Functions
float	GetMiscNetwTime ()
	Get synched network time from X-Plane (sim/network/misc/network_time_sec) as used in Log.txt. More...
bool	CheckEverySoOften (float &_lastCheck, float _interval, float _now)
	Convenience function to check on something at most every x seconds. More...
bool	CheckEverySoOften (float &_lastCheck, float _interval)
	Convenience function to check on something at most every x seconds. More...
std::string	GetPluginName (XPLMPluginID who)
	Return a plugin's name. More...
std::istream &	safeGetline (std::istream &is, std::string &t)
	Read a text line, handling both Windows (CRLF) and Unix (LF) ending. More...
double	WeatherAltCorr_ft (double pressureAlt_ft, double hPa)
	Compute geometric altitude [ft] from pressure altitude and current weather in a very simplistic manner good enough for the first 3,000ft. More...
float	HeadDiff (float from, float to)
	Return shortest turn from one heading to the other. More...
float	RpmToAngle (float angle, float rpm, float s)
	Rotation: Computes new rotation angle based on current + revolution in a (small) amount of time. More...
template<typename T >
T	NZ (T v)
	Replace NAN with 0.0. More...
std::string	str_n (const char *s, size_t max)
	Copy at most n chars from location, or less if zero-terminated. More...
std::vector< std::string >	str_tokenize (const std::string &s, const std::string &tokens, bool bSkipEmpty=true)
	separates string into tokens More...
std::pair< std::string, std::string >	str_split (const std::string &s, const std::string &tokens)
	Split the string at the first of the tokens and return the two pieces. More...
const char *	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	LogMsg (const char *szFile, int ln, const char *szFunc, logLevelTy lvl, const char *szMsg,...) XPPLANES_FMTARGS(5)
	Log Text to log file. 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

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_MSG

#define LOG_MSG	(		lvl,
			...
	)

Value:

    {                                         \
    if (lvl >= 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

SET_THREAD_NAME

#define SET_THREAD_NAME

(

sName

)

STR_N

#define STR_N

(

s

)

str_n(s,sizeof(s))

Simplify using str_n() with char arrays.

THROW_ERROR

#define THROW_ERROR

(

...

)

throw XPMP2::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

XPPLANES_FMTARGS

#define XPPLANES_FMTARGS

(

FMT

)

To apply printf-style warnings to our functions.

See also

Taken from imgui.h's definition of IM_FMTARGS

Enumeration Type Documentation

logLevelTy

enum logLevelTy : int

Logging level.

Enumerator
logDEBUG	Debug, highest level of detail.
logINFO	regular info messages
logWARN	warnings, i.e. unexpected, but uncritical events, maybe leading to unwanted display, but still: display of aircraft
logERR	errors mean, aircraft can potentially not be displayed
logFATAL	fatal is shortly before a crash
logMSG	will always be output, no matter what has been configured, cannot be suppressed

Function Documentation

CheckEverySoOften() [1/2]

bool CheckEverySoOften ( float &  _lastCheck, float  _interval  )

inline

Convenience function to check on something at most every x seconds.

Parameters

_lastCheck	Provide a float which holds the time of last check (init with 0.0f)
_interval	[seconds] How often to perform the check?

Returns

true if more than _interval time has passed since _lastCheck

CheckEverySoOften() [2/2]

bool CheckEverySoOften	(	float &	_lastCheck,
		float	_interval,
		float	_now
	)

Convenience function to check on something at most every x seconds.

Parameters

_lastCheck	Provide a float which holds the time of last check (init with 0.0f)
_interval	[seconds] How often to perform the check?
_now	Current time, possibly from a call to GetTotalRunningTime()

Returns

true if more than _interval time has passed since _lastCheck

GetMiscNetwTime()

float GetMiscNetwTime

(

)

Get synched network time from X-Plane (sim/network/misc/network_time_sec) as used in Log.txt.

GetPluginName()

std::string GetPluginName

(

XPLMPluginID

who

)

Return a plugin's name.

HeadDiff()

float HeadDiff	(	float	from,
		float	to
	)

Return shortest turn from one heading to the other.

LogGetString()

const char* 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.

LogMsg()

void LogMsg	(	const char *	szFile,
		int	ln,
		const char *	szFunc,
		logLevelTy	lvl,
		const char *	szMsg,
			...
	)

Log Text to log file.

NZ()

template<typename T >

T NZ ( T  v )

inline

Replace NAN with 0.0.

RpmToAngle()

float RpmToAngle	(	float	angle,
		float	rpm,
		float	s
	)

Rotation: Computes new rotation angle based on current + revolution in a (small) amount of time.

Parameters

angle	Last rotation angle as basis
rpm	Rotation speed in revolutions per minute
s	Timeframe to consider in seconds

Returns

new rotation angle, normalized to [0.0; 360.0)

safeGetline()

std::istream& safeGetline	(	std::istream &	is,
		std::string &	t
	)

Read a text line, handling both Windows (CRLF) and Unix (LF) ending.

Code makes use of the fact that in both cases LF is the terminal character. So we read from file until LF (without widening!). In case of CRLF files there then is a trailing CR, which we just remove.

str_n()

std::string str_n	(	const char *	s,
		size_t	max
	)

Copy at most n chars from location, or less if zero-terminated.

Unlike std::string(char*, n) this will not copy null chars

str_split()

std::pair<std::string,std::string> str_split	(	const std::string &	s,
		const std::string &	tokens
	)

Split the string at the first of the tokens and return the two pieces.

str_tokenize()

std::vector<std::string> str_tokenize	(	const std::string &	s,
		const std::string &	tokens,
		bool	bSkipEmpty = true
	)

separates string into tokens

WeatherAltCorr_ft()

double WeatherAltCorr_ft ( double  pressureAlt_ft, double  hPa  )

inline

Compute geometric altitude [ft] from pressure altitude and current weather in a very simplistic manner good enough for the first 3,000ft.