Some random utilities needed by other siplasplas modules. More...

Modules
	Assert
	Assertion utilities.

	Dynamic-library
	Cross platform API to load symbols from shared librarties at runtime.

	Error-handling
	Error handling tools.

	Hash
	Hashing utilities based on `std::hash`.

	Memory-manip
	Tools related to raw memory manipulation.

Classes
class	cpp::Identity
	A functor class implementing the identity function. More...

class	cpp::UniversalReference< T, IsLvalueReference, IsConst >
	Implements a copyable wrapper of an universal reference. More...

class	cpp::UniversalReference< T, true, false >
	UniversalReference spacialization for non-const lvalues. More...

class	cpp::UniversalReference< T, false, false >
	UniversalReference spacialization for rvalues. More...

Functions
template<typename T >
void	cpp::destroy (T &object)
	Invokes the destructor of an object. More...

template<typename T >
void	cpp::destroy (T *objectPtr)
	Invokes the destructor of an object. More...

template<typename T , typename... Args>
void	cpp::construct (void *where, Args &&...args)
	constructs an object of type T on the specified address More...

template<typename T , typename... Args>
void	cpp::construct (T *where, Args &&...args)
	constructs an object of type T on the specified address More...

template<typename Callable , typename... Args>
decltype(auto)	cpp::invoke (Callable &&callable, Args &&...args)
	Invokes the `Callable` object with the given arguments. See `std::invoke()`

template<typename T >
std::string	cpp::lexical_cast (const T &value)
	Returns an string representation of a value. More...

template<typename T >
T	cpp::lexical_cast (const std::string &value)
	Returns an string representation of a value. More...

template<bool Condition, typename ThenBody , typename... Args>
auto	cpp::staticIf (const ThenBody &thenBody, Args &&...args)
	Implements an static conditional. More...

template<typename T >
auto	cpp::universalReference (T &&value) -> UniversalReference< std::decay_t< T >, std::is_lvalue_reference< T >::value, std::is_const< std::remove_reference_t< T >>::value >
	Creates an universal reference to the given value. More...

Detailed Description

Some random utilities needed by other siplasplas modules.

The siplaspals-utility module implements various utilities used in the implementation of other siplasplas modules. These utilities are not grouped in any special way, but we encourage the policy of rising utilities into full-fledged modules if these became too complex.

Todo:

Move meta.hpp, function_traits.hpp, tuple.hpp, and fusion.hpp to a siplasplas-meta module.

Move error_logger.hpp and exception.hpp to a siplasplas-exception module?

Move cpp::Overload<> to function_traits.hpp

siplasplas-utility includes the following features:

Assertion macros: A set of assertion macros based in Google Test syntax. See assert.hpp.
Clonable pointer: A smart pointer implementing clone semantics. See cloning_ptr.hpp.
Dynamic library loading: Cross platform classes to load symbols from shared libraries at runtime. See cpp::DynamicLibrary.
Exceptions hierarchy: An exception hierarchy with fmt syntax for error messages and automatic logging of exception stack traces. See exception.hpp.
Function type introspection utilities: Metafunctions to check function types and signatures. See function_traits.hpp.
One header metaprogramming library: A header full of metaprogramming tools. See meta.hpp.
Overloaded functor factory: See function.hpp.
Heterogeneous operations on type and parameter packs: See fusion.hpp.
Hash utilities: A cpp::hash() function and equivalent functors that give default hashing for enum types, tuples, function pointer types, etc. See hash.hpp.
Preprocessor utilities: See preprocessor.hpp.
String utilities: See string.hpp.
Raw memory manipulation: Tools for raw memory manipulation such as functions to compute aligned addresses, functions to read/write values directly into raw memory, etc. See memory_manip.hpp.
Tuple manipulation tools: See tuple.hpp.

Function Documentation

template<typename T , typename... Args>

void cpp::construct	(	void *	where,
		Args &&...	args
	)

constructs an object of type T on the specified address

This function performs an in-place construction of an object of type T in the given address. Arguments are passed as-is to the object constructor. The behavior is undefined if alignment(pointer) != alignof(T).

Parameters

where	Location of the object
args	Constructor arguments

std::aligned_storage<std::string> storage;

cpp::construct<std::string>(&storage, "hello, world!");

template<typename T , typename... Args>

void cpp::construct	(	T *	where,
		Args &&...	args
	)

constructs an object of type T on the specified address

This function performs an in-place construction of an object of type T in the given address. Arguments are passed as-is to the object constructor. The behavior is undefined if alignment(pointer) != alignof(T).

Parameters

where	Location of the object
args	Constructor arguments

std::aligned_storage<std::string> storage;
std::string* stringPtr = reinterpret_cast<std::string*>(&storage);
cpp::construct(stringPtr, "hello, world!");

template<typename T >

void cpp::destroy ( T & object )

Invokes the destructor of an object.

Template Parameters

T	Must be Destructible (See std::is_destructible)

template<typename T >

void cpp::destroy ( T * objectPtr )

Invokes the destructor of an object.

Template Parameters

T	Must be Destructible (See std::is_destructible)

template<typename T >

std::string cpp::lexical_cast ( const T & value )

Returns an string representation of a value.

This function invokes operator<<(std::ostream&, const T&) to get an string representation of a given value.

It's a simplified version of the Boost.Lexical_Cast library.

Template Parameters

T	value type. Must have a valid `operator<<(std::ostream&, T)` overload.

Parameters

value Value which is translated to a string.

Returns: A string representation of the given value.

template<typename T >

T cpp::lexical_cast ( const std::string & value )

Returns an string representation of a value.

This function invokes operator>>(std::istream&, T&) to assign a T value from an string representation of it.

It's a simplified version of the Boost.Lexical_Cast library.

Template Parameters

T	Required output value type. Must have a valid `operator>>(std::istream&, T&)` overload.

Parameters

value String representation of the value.

Returns: A value of type T equivalent to the value string representation argument.

template<bool Condition, typename ThenBody , typename... Args>

auto cpp::staticIf	(	const ThenBody &	thenBody,
		Args &&...	args
	)

Implements an static conditional.

An static conditional allows to conditionally evaluate some code depending on the value of a compile time property. The body of the conditional is implemented by user provided functions.

template<typename T>
void f(T value)
{
    cpp::staticIf<std::is_integral<T>::value>([&](auto identity)
    {
        std::cout << "the value is integral\n";
    });
    ...
}

The body of the untaken conditional path shall not be evaluated by the compiler and can contain ill formed code. NOTE: This behavior relies on the two phase template processing scheme, so the statement above is only true for entities that will be evaluated in the instantiation phase only:

template<typename T>
void foo(T value)
{
   int i = 0;
   // The condition is false, so the code
   // inside the if "should" not be evaluated:
   cpp::staticIf<false>([&](auto identity)
   {
       // Ok: value depends on T template parameter.
       value.TheMostBizarreMethodName();
       // ERROR: 'int' type is not class/struct/union.
       i.method();
       // Ok: identity(i) depends on a template parameter.
       identity(i).method();
   });
}

As the example shows, the conditional body takes an identity parameter that can be used to force the evaluation of an expression at the second phase.

The static conditional expression also provides an else sentence in the form of an Else() method:

template<typename T>
void foo(T value)
{
   int i = 0;
   cpp::staticIf<false>([&](auto identity)
   {
       value.TheMostBizarreMethodName();
       i.method();
       identity(i).method();
   }).Else([&](auto identity)
   {
       std::cout << i << std::endl;
   });
}

cpp::staticIf() supports returning values from the conditional body too:

template<typename T>
T twice(const T& value)
{
    return cpp::staticIf<std::is_class<T>::value>([&](auto)
    {
        return value.twice();
    }).Else([&](auto)
    {
        return value * 2;
    });
}

note this has some caveats:

Return types cannot be inferred: Due to technical reasons auto or any other kind of type inference cannot be used with the return value of a static conditional.
Return may not be optimal in some code paths: If the condition is true, the then path is picked. If the then body returns a value, such value is not returned directly (So elligible for RVO) but bypassed through the else internals. This means returning a value from a positive conditional may involve two move operations.

Template Parameters

Condition	Value of the condition. The value should be evaluable at compile time, else compilation fails.
ThenBody	Function type with one template-dependent value parameter.

Parameters

thenBody Body of the then path of the conditional. Evaluated only if the condition is true.

Returns: An unspecified type implementing the else part of the conditional.

template<typename T >

auto cpp::universalReference ( T && value ) -> UniversalReference< std::decay_t<T>, std::is_lvalue_reference<T>::value, std::is_const<std::remove_reference_t<T>>::value >

Creates an universal reference to the given value.

This function checks the value category of the given value and instances the apropiate cpp::UniversalReference specialization. Note the returned type depends on the value category. For an alternative with common a type, see cpp::typeerasure::AnyArg

Returns

A UniversalReference specialization instance as follows:

UniversalReference<std::decay_t<T>, true, true> if value type is deduced to a const reference to an lvalue.
UniversalReference<std::decay_t<T>, true, false> if value type is deduced to a non const reference to an lvalue.
UniversalReference<std::decay_t<T>, false, false> if value type is deduced to an rvalue reference

Modules

Classes

Functions

Detailed Description

Function Documentation