[mrpt-core]

Overview

Core components for MRPT.

Library mrpt-core

This library is part of MRPT and can be installed in Debian-based systems with:

sudo apt install libmrpt-core-dev

Read also how to import MRPT into your CMake scripts.

Library contents

// typedefs

typedef std::optional<std::reference_wrapper<T>> mrpt::optional_ref;

// enums

enum mrpt::cpu::feature;

// structs

struct mrpt::TCallStackBackTrace;
struct mrpt::TCallStackEntry;

template <class T>
struct mrpt::copiable_NULL_ptr;

template <class T>
struct mrpt::copiable_NULL_ptr_basic;

template <class T>
struct mrpt::ignored_copy_ptr;

template <class T>
struct mrpt::non_copiable_ptr;

template <class T>
struct mrpt::non_copiable_ptr_basic;

template <class T>
struct mrpt::safe_ptr;

template <class T>
struct mrpt::safe_ptr_basic;

// classes

class mrpt::cpu::internal::CPU_analyzer;
class mrpt::Clock;

template <class T>
class mrpt::LockHelper;

class mrpt::Stringifyable;
class mrpt::WorkerThreadsPool;

// global functions

void mrpt::callStackBackTrace(
    TCallStackBackTrace& out_bt,
    const unsigned int framesToSkip = 1,
    const unsigned int framesToCapture = 64
    );

TCallStackBackTrace mrpt::callStackBackTrace(const unsigned int framesToSkip = 1, const unsigned int framesToCapture = 64);

template <class VECTOR_T>
void mrpt::vector_strong_clear(VECTOR_T& v);

template <std::size_t N, typename F>
void mrpt::for_(F func);

std::string mrpt::demangle(const std::string& symbolName);
std::string mrpt::exception_to_str(const std::exception& e);
std::string mrpt::format(const char* fmt, ...);

template <typename T>
std::string std::string mrpt::to_string(T v);

template <typename T>
T mrpt::from_string(
    const std::string& s,
    const T& defValue = T{},
    bool throw_on_error = true
    );

template <class T>
T mrpt::get_env(const std::string_view& varname, const T& defValue = T());

template <class T>
LockHelper<T> mrpt::lockHelper(T& t);

void mrpt::reverseBytesInPlace(bool& v_in_out);
void mrpt::reverseBytesInPlace(uint8_t& v_in_out);
void mrpt::reverseBytesInPlace(int8_t& v_in_out);
void mrpt::reverseBytesInPlace(uint16_t& v_in_out);
void mrpt::reverseBytesInPlace(int16_t& v_in_out);
void mrpt::reverseBytesInPlace(uint32_t& v_in_out);
void mrpt::reverseBytesInPlace(int32_t& v_in_out);
void mrpt::reverseBytesInPlace(uint64_t& v_in_out);
void mrpt::reverseBytesInPlace(int64_t& v_in_out);
void mrpt::reverseBytesInPlace(float& v_in_out);
void mrpt::reverseBytesInPlace(double& v_in_out);
void mrpt::reverseBytesInPlace(std::chrono::time_point<mrpt::Clock>& v_in_out);

template <class T>
void mrpt::reverseBytes(const T& v_in, T& v_out);

template <class T>
T mrpt::reverseBytes(const T& v_in);

template <class T>
T mrpt::toNativeEndianness(const T& v_in);

template <
    typename enum_t,
    typename underlying_t = typename std::underlying_type<enum_t>::type
    >
void mrpt::reverseBytesInPlace_enum(enum_t& v);

std::string mrpt::winerror2str(const char* caller = nullptr, const char* errorPrefix = " Error: ");
void mrpt::registerAllClasses_mrpt_core();
bool mrpt::cpu::supports(feature f);
void mrpt::cpu::overrideDetectedFeature(feature f, bool newValue);
std::string mrpt::cpu::features_as_string();

Typedefs

typedef std::optional<std::reference_wrapper<T>> mrpt::optional_ref

Shorter name for std::optional<std::reference_wrapper<T>>

Global Functions

void mrpt::callStackBackTrace(
    TCallStackBackTrace& out_bt,
    const unsigned int framesToSkip = 1,
    const unsigned int framesToCapture = 64
    )

Returns a list of strings representing the current call stack backtrace.

If possible, human-readable names are used for functions. Source code line numbers will be also recovered if code has symbols (-g or -g1 in GCC).

See environment variables that can modify the behavior of this function.

(Moved from mrpt-system to mrpt-core in MRPT 2.1.5)

TCallStackBackTrace mrpt::callStackBackTrace(
    const unsigned int framesToSkip = 1,
    const unsigned int framesToCapture = 64
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template <class VECTOR_T>
void mrpt::vector_strong_clear(VECTOR_T& v)

Like calling a std::vector<>’s clear() method, but really forcing deallocating the memory.

template <std::size_t N, typename F>
void mrpt::for_(F func)

constexpr for loop.

Example:

mrpt::for_<10>( [&](auto i) { std::cout << i.value << " "; } );

(New in MRPT 2.1.0)

Credits to SO.

std::string mrpt::demangle(const std::string& symbolName)

Demangle a C++ symbol name (works on both Windows and Unices)

std::string mrpt::exception_to_str(const std::exception& e)

Builds a nice textual representation of an exception, which if generated using MRPT macros (THROW_EXCEPTION,…) in between MRPT_START/MRPT_END macros, will contain function names and line numbers across the call stack at the original throw point.

Since MRPT 2.1.5 this will also print line numbers of any other exception (even if generated in non-mrpt code, like inside STL headers) as long as MRPT was built with BFD support and sources built with, at least, -g1 debug symbols.

See examples of use in [mrpt-core]

std::string mrpt::format(const char* fmt, ...)

A std::string version of C sprintf.

You can call this to obtain a std::string using printf-like syntax.

template <typename T>
std::string std::string mrpt::to_string(T v)

Just like std::to_string(), but with an overloaded version for std::string arguments.

template <typename T>
T mrpt::from_string(
    const std::string& s,
    const T& defValue = T{},
    bool throw_on_error = true
    )

Converts from string to any data type that supports reading (>>) from a text stream.

In case of error, the given default value is returned, or an exception raised.

template <class T>
T mrpt::get_env(
    const std::string_view& varname,
    const T& defValue = T()
    )

Reads an environment variable, with a default value if not present.

template <class T>
LockHelper<T> mrpt::lockHelper(T& t)

Syntactic sugar to easily create a locker to any kind of std::mutex.

void mrpt::reverseBytesInPlace(bool& v_in_out)

Reverse the order of the bytes of a given type (useful for transforming btw little/big endian)

template <class T>
void mrpt::reverseBytes(const T& v_in, T& v_out)

Reverse the order of the bytes of a given type (useful for transforming btw little/big endian)

std::string mrpt::winerror2str(
    const char* caller = nullptr,
    const char* errorPrefix = " Error: "
    )

[Windows only] Returns an error string “[<caller>] Error: <error msg>” with “<caller>” the given user-provided string, and “<error msg>” the combination of calling GetLastError() + FormatMessageA().

If no “<caller>” string is provided (nullptr), it just returns the “<error msg>” part.

Returns an empty string in non Windows OSes, or if GetLastError() gives no error. (New in MRPT 2.1.5)

void mrpt::registerAllClasses_mrpt_core()

Forces manual RTTI registration of all serializable classes in this namespace.

Should never be required to be explicitly called by users, except if building MRPT as a static library.

bool mrpt::cpu::supports(feature f)

Returns true if the current CPU (and OS) supports the given CPU feature.

void mrpt::cpu::overrideDetectedFeature(feature f, bool newValue)

Blindly enables/disables a CPU feature flag in the list of detected features to be reported in subsequent calls to mrpt::cpu::supports().

Could be used to disable a given CPU feature for benchmarking dynamically-dispatched functions.

Enabling a feature that is not actually supported by the current CPU would probably lead to program crashes.

std::string mrpt::cpu::features_as_string()

Returns a string with detected features: “MMX:1 SSE2:0 etc.”.