Dune Core Modules (unstable)

C++ utilities and backports

Standard library features backported from newer C++ versions or technical specifications and DUNE-specific utilities. More...

Files

file  keywords.hh
 Definitions of several macros that conditionally make C++ syntax available.
 
file  proxymemberaccess.hh
 infrastructure for supporting operator->() on both references and proxies
 

Namespaces

namespace  Dune::Std
 Namespace for features backported from new C++ standards.
 

Classes

class  Dune::IteratorRange< Iterator >
 Simple range between a begin and an end iterator. More...
 
class  Dune::Std::default_accessor< Element >
 A type for indexed access to elements of mdspan. More...
 
class  Dune::Std::extents< IndexType, exts >
 Multidimensional index space with dynamic and static extents. More...
 
struct  Dune::Std::layout_left
 A layout where the leftmost extent has stride 1. More...
 
struct  Dune::Std::layout_right
 A layout where the rightmost extent has stride 1, and strides increase right-to-left as the product of extents. More...
 
struct  Dune::Std::layout_stride
 A layout mapping where the strides are user-defined. More...
 
class  Dune::Std::mdarray< Element, Extents, LayoutPolicy, Container >
 An owning multi-dimensional array analog of mdspan. More...
 
class  Dune::Std::mdspan< Element, Extents, LayoutPolicy, AccessorPolicy >
 A multi-dimensional non-owning array view. More...
 
class  Dune::Std::span< Element, Extent >
 A contiguous sequence of elements with static or dynamic extent. More...
 
struct  Dune::Std::nonesuch
 Type representing a lookup failure by std::detected_or and friends. More...
 
struct  Dune::Empty
 Just an empty class. More...
 
struct  Dune::IsInteroperable< T1, T2 >
 Checks whether two types are interoperable. More...
 
struct  Dune::EnableIfInterOperable< T1, T2, Type >
 Enable typedef if two types are interoperable. More...
 
struct  Dune::AlwaysFalse< T >
 template which always yields a false value More...
 
struct  Dune::AlwaysTrue< T >
 template which always yields a true value More...
 
struct  Dune::IsCallable< D, R >
 Check if a type is callable with ()-operator and given arguments. More...
 
struct  Dune::IsCallable< F(Args...), R >
 Check if a type is callable with ()-operator and given arguments. More...
 
struct  Dune::IsNumber< T >
 Whether this type acts as a scalar in the context of (hierarchically blocked) containers. More...
 
struct  Dune::HasNaN< T >
 Whether this type has a value of NaN. More...
 
struct  Dune::IsIndexable< T, I >
 Type trait to determine whether an instance of T has an operator[](I), i.e. whether it can be indexed with an index of type I. More...
 
struct  Dune::IsIterable< T, typename >
 typetrait to check that a class has begin() and end() members More...
 
struct  Dune::IsTuple< T >
 Check if T is a std::tuple<...> More...
 
struct  Dune::IsTupleOrDerived< T >
 Check if T derived from a std::tuple<...> More...
 
struct  Dune::IsIntegralConstant< T >
 Check if T is an std::integral_constant<I, i> More...
 
struct  Dune::IsCompileTimeConstant< T >
 Check if T is an integral constant or any type derived from std::integral_constant. More...
 
struct  Dune::SizeOf< T >
 Compute size of variadic type list. More...
 
struct  Dune::IntegerSequenceEntry< IntegerSequence, index >
 Get entry of std::integer_sequence. More...
 
struct  Dune::AutonomousValueType< T >
 Type free of internal references that T can be converted to. More...
 
struct  Dune::AutonomousValueType< T & >
 Specialization to remove lvalue references. More...
 
struct  Dune::AutonomousValueType< T && >
 Specialization to remove rvalue references. More...
 
struct  Dune::AutonomousValueType< const T >
 Specialization to remove const qualifiers. More...
 
struct  Dune::AutonomousValueType< volatile T >
 Specialization to remove volatile qualifiers. More...
 
struct  Dune::AutonomousValueType< std::vector< bool >::reference >
 Specialization for the proxies of vector<bool> More...
 
struct  Dune::AutonomousValueType< volatile const T >
 Specialization to remove both const and volatile qualifiers. More...
 

Macros

#define DUNE_ASSERT_AND_RETURN(C, X)   (!(C) ? throw [&](){assert(!#C);return 0;}() : 0), X
 Asserts a condition and return on success in constexpr context. More...
 
#define DUNE_NO_DEPRECATED_BEGIN   ...
 Ignore deprecation warnings (start) More...
 
#define DUNE_NO_DEPRECATED_END   ...
 Ignore deprecation warnings (end) More...
 
#define DUNE_INLINE_VARIABLE
 Preprocessor macro used for marking variables inline on supported compilers.
 
#define DUNE_GENERALIZED_CONSTEXPR
 Preprocessor macro used for marking code as constexpr under the relaxed rules of C++14 if supported by the compiler.
 
#define DUNE_UNUSED_PARAMETER(param)   static_cast<void>(param)
 

Typedefs

template<class IndexType , std::size_t R>
using Dune::Std::dextents = typename Impl::DExtentsImpl< IndexType, std::make_integer_sequence< std::size_t, R > >::type
 Alias of extents of given rank R and purely dynamic extents. See [mdspan.extents.dextents].
 
template<typename Default , template< typename... > class Op, typename... Args>
using Dune::Std::detected_or = Impl::detector< Default, void, Op, Args... >
 Detects whether Op<Args...> is valid and makes the result available. More...
 
template<template< typename... > class Op, typename... Args>
using Dune::Std::is_detected = typename detected_or< nonesuch, Op, Args... >::value_t
 Detects whether Op<Args...> is valid. More...
 
template<template< typename... > class Op, typename... Args>
using Dune::Std::detected_t = typename detected_or< nonesuch, Op, Args... >::type
 Returns Op<Args...> if that is valid; otherwise returns nonesuch. More...
 
template<typename Default , template< typename... > class Op, typename... Args>
using Dune::Std::detected_or_t = typename detected_or< Default, Op, Args... >::type
 Returns Op<Args...> if that is valid; otherwise returns the fallback type Default. More...
 
template<typename Expected , template< typename... > class Op, typename... Args>
using Dune::Std::is_detected_exact = std::is_same< Expected, detected_t< Op, Args... > >
 Checks whether Op<Args...> is Expected without causing an error if Op<Args...> is invalid. More...
 
template<typename Target , template< typename... > class Op, typename... Args>
using Dune::Std::is_detected_convertible = std::is_convertible< Target, detected_t< Op, Args... > >
 Checks whether Op<Args...> is convertible to Target without causing an error if Op<Args...> is invalid. More...
 
template<class... Types>
using Dune::void_t = typename Impl::voider< Types... >::type
 Is void for all valid input types. The workhorse for C++11 SFINAE-techniques. More...
 
template<class Type >
using Dune::field_t = typename FieldTraits< Type >::field_type
 Convenient access to FieldTraits<Type>::field_type.
 
template<class Type >
using Dune::real_t = typename FieldTraits< Type >::real_type
 Convenient access to FieldTraits<Type>::real_type.
 
template<class T >
using Dune::AutonomousValue = typename AutonomousValueType< T >::type
 Type free of internal references that T can be converted to. More...
 

Functions

template<class... F>
auto Dune::overload (F &&... f)
 Create an overload set. More...
 
template<class... F>
auto Dune::orderedOverload (F &&... f)
 Create an ordered overload set. More...
 
template<typename T >
pointer_or_proxy_holder Dune::handle_proxy_member_access (T &&t)
 Transparent support for providing member access to both lvalues and rvalues (temporary proxies). More...
 
template<class T >
constexpr T & Dune::resolveRef (T &gf) noexcept
 Helper function to resolve std::reference_wrapper. More...
 
template<class T >
constexpr T & Dune::resolveRef (std::reference_wrapper< T > gf) noexcept
 Helper function to resolve std::reference_wrapper. More...
 
template<class T , T... t, std::size_t index>
constexpr auto Dune::integerSequenceEntry (std::integer_sequence< T, t... >, std::integral_constant< std::size_t, index > i)
 Get entry of std::integer_sequence. More...
 
template<class T >
constexpr AutonomousValue< T > Dune::autoCopy (T &&v)
 Autonomous copy of an expression's value for use in auto type deduction. More...
 

Variables

template<class T >
constexpr bool Dune::IsReferenceWrapper_v = Impl::IsReferenceWrapper<T>::value
 Helper to detect if given type is a std::reference_wrapper.
 

Detailed Description

Standard library features backported from newer C++ versions or technical specifications and DUNE-specific utilities.

Macro Definition Documentation

◆ DUNE_ASSERT_AND_RETURN

#define DUNE_ASSERT_AND_RETURN (   C,
 
)    (!(C) ? throw [&](){assert(!#C);return 0;}() : 0), X

Asserts a condition and return on success in constexpr context.

The macro DUNE_ASSERT_AND_RETURN can be used as expression in the return statement of a constexpr function to have assert() and constexpr at the same time. It first uses assert for the condition given by the first argument and then returns the value of the second argument.

Deprecated:
Will be removed after Dune 2.10 release

◆ DUNE_NO_DEPRECATED_BEGIN

#define DUNE_NO_DEPRECATED_BEGIN   ...

Ignore deprecation warnings (start)

This macro can be used together with DUNE_NO_DEPRECATED_END to mark a block in which deprecation warnings are ignored. This can be useful for implementations of deprecated methods that call other deprecated methods or for testing deprecated methods in the testsuite.

some_deprecated_function();
another_deprecated_function();
#define DUNE_NO_DEPRECATED_END
Ignore deprecation warnings (end)
Definition: deprecated.hh:38
#define DUNE_NO_DEPRECATED_BEGIN
Ignore deprecation warnings (start)
Definition: deprecated.hh:32
Warning
This macro must always be used together with DUNE_NO_DEPRECATED_END

◆ DUNE_NO_DEPRECATED_END

#define DUNE_NO_DEPRECATED_END   ...

Ignore deprecation warnings (end)

Warning
This macro must always be used together with DUNE_NO_DEPRECATED_BEGIN

◆ DUNE_UNUSED_PARAMETER

#define DUNE_UNUSED_PARAMETER (   param)    static_cast<void>(param)

A macro to mark intentionally unused function parameters with.

If possible use C++17's

[[maybe_unused]]

instead. Due to a bug prior to GCC 9.3 it cannot be used for the first argument of a constructor (bug 81429).

Typedef Documentation

◆ AutonomousValue

template<class T >
using Dune::AutonomousValue = typedef typename AutonomousValueType<T>::type

Type free of internal references that T can be converted to.

Specialize AutonomousValueType to add your own mapping. Use autoCopy() to convert an expression of type T to AutonomousValue<T>.

This type alias determines a type that T can be converted to, but that will be free of references to other objects that it does not manage. In practice it will act like std::decay_t, but in addition to removing references it will also determine the types that proxies stand in for, and the types that expression templates will evaluate to.

"Free of references" means that the converted object will always be valid and does not alias any other objects directly or indirectly. The "other objects that it does not manage" restriction means that the converted object may still contain internal references, but they must be to resources that it manages itself. So, an std::vector would be an autonomous value even though it contains internal references to the storage for the elements since it manages that storage itself.

Note
For pointers, iterators, and the like the "value" for the purpose of AutonomousValue is considered to be the identity of the pointed-to object, so that object should not be cloned. But then you should hopefully never need an autonomous value for those anyway...

◆ detected_or

template<typename Default , template< typename... > class Op, typename... Args>
using Dune::Std::detected_or = typedef Impl::detector<Default,void,Op,Args...>

Detects whether Op<Args...> is valid and makes the result available.

This alias template is an alias for an unspecified class type with two nested typedefs value_t and type. It can be used to detect whether the meta function call Op<Args...> is valid and access the result of the call by inspecting the returned type, which is defined as follows:

  • If Op<Args...> can be instantiated, value_t is an alias for std::true_type and type is an alias for Op<Args...>.
  • If Op<Args...> is invalid, value_t is an alias for std::false_type and type is an alias for Default.

This can be used to safely extract a nested typedef from a type T that might not define the typedef:

struct A { using size_type = int ; };
struct B;
template<typename T>
using SizeType = typename T::size_type;
// this extracts the nested typedef for int
using st_a = typename detected_or<std::size_t,SizeType,A>::type;
// as there is no nested typedef in B, this yields std::size_t
using st_b = typename detected_or<std::size_t,SizeType,B>::type;

Do not directly use the nested typedefs value_t and type as they are implementation details.

Note
This functionality is part of the C++ library fundamentals TS v3 and might or might not became part of C++2c / C++26.

◆ detected_or_t

template<typename Default , template< typename... > class Op, typename... Args>
using Dune::Std::detected_or_t = typedef typename detected_or<Default,Op,Args...>::type

Returns Op<Args...> if that is valid; otherwise returns the fallback type Default.

This alias template can be used to instantiate Op<Args...> in a context that is not SFINAE-safe by appropriately wrapping the instantiation and automatically falling back to Default if instantiation fails.

Note
This functionality is part of the C++ library fundamentals TS v3 and might or might not became part of C++2c / C++26.

◆ detected_t

template<template< typename... > class Op, typename... Args>
using Dune::Std::detected_t = typedef typename detected_or<nonesuch,Op,Args...>::type

Returns Op<Args...> if that is valid; otherwise returns nonesuch.

This alias template can be used to instantiate Op<Args...> in a context that is not SFINAE-safe by appropriately wrapping the instantiation. If instantiation fails, the marker type nonesuch is returned instead.

Note
This functionality is part of the C++ library fundamentals TS v3 and might or might not became part of C++2c / C++26.

◆ is_detected

template<template< typename... > class Op, typename... Args>
using Dune::Std::is_detected = typedef typename detected_or<nonesuch,Op,Args...>::value_t

Detects whether Op<Args...> is valid.

This alias template checks whether Op<Args...> can be instantiated. It is equivalent to typename detected_or<nonesuch,Op,Args...>::value_t.

Note
This functionality is part of the C++ library fundamentals TS v3 and might or might not became part of C++2c / C++26.

◆ is_detected_convertible

template<typename Target , template< typename... > class Op, typename... Args>
using Dune::Std::is_detected_convertible = typedef std::is_convertible<Target,detected_t<Op,Args...> >

Checks whether Op<Args...> is convertible to Target without causing an error if Op<Args...> is invalid.

Note
This functionality is part of the C++ library fundamentals TS v3 and might or might not became part of C++2c / C++26.

◆ is_detected_exact

template<typename Expected , template< typename... > class Op, typename... Args>
using Dune::Std::is_detected_exact = typedef std::is_same<Expected,detected_t<Op,Args...> >

Checks whether Op<Args...> is Expected without causing an error if Op<Args...> is invalid.

Note
This functionality is part of the C++ library fundamentals TS v3 and might or might not became part of C++2c / C++26.

◆ void_t

template<class... Types>
using Dune::void_t = typedef typename Impl::voider<Types...>::type

Is void for all valid input types. The workhorse for C++11 SFINAE-techniques.

Note, since c++17 there is also std::void_t that should be preferred. But, due to an issue in the c++ standard, see CWG issue #1980. "Equivalent but not functionally-equivalent redeclarations", and a corresponding failure in some clang compilers, this tool is left here as a workaround. Use it if you want to specialize multiple classes using void_t.

Function Documentation

◆ autoCopy()

template<class T >
constexpr AutonomousValue< T > Dune::autoCopy ( T &&  v)
constexpr

Autonomous copy of an expression's value for use in auto type deduction.

This function is an unproxyfier or an expression evaluator or a fancy cast to ensure an expression can be used in auto type deduction. It ensures two things:

  1. The return value is a prvalue,
  2. the returned value is self-sufficient, or "autonomous".

The latter means that there will be no references into other objects (like containers) which are not guaranteed to be kept alive during the lifetime of the returned value.

An example usage would be

{c++}
std::vector<bool> bitvector{24};
auto value = autoCopy(bitvector[23]);
bitvector.resize(42);
// value still valid

Since vector<bool> may use proxies, auto value = bitvector[23]; would mean that the type of value is such a proxy. The proxy keeps internal references into the vector, and thus can be invalidated by anything that modifies the vector – such as a later call to resize(). autoCopy() lets you work around that problem by copying the value referenced by the proxy and converting it to a bool.

Another example would be an automatic differentiation library that lets you track the operations in a computation, and later ask for derivatives. Imagine that your operation involves a parameter function, and you want to use that function both with plain types and with automatic differentiation types. You might write the parameter function as follows:

{c++}
template<class NumberType>
auto param(NumberType v)
{
return 2*v;
}

If the automatic differentiation library is Adept, this would lead to use-after-end-of-life-bugs. The reason is that for efficiency reasons Adept does not immediately evaluate the expression, but instead it constructs an expression object that records the kind of expression and references to the operands. The expression object is only evaluated when it is assigned to an object of some number type – which will only happen after the operands (v and the temporary object representing 2) have gone out of scope and been destroyed. Basically, Adept was invented before auto and rvalue-references were a thing.

This can be handled with autoCopy():

{c++}
template<class NumberType>
auto param(NumberType v)
{
return autoCopy(2*v);
}

Of course, autoCopy() needs to be taught about the expression objects of Adept for this to work.

autoCopy() will by default simply return the argument as a prvalue of the same type with cv-qualifiers removed. This involves one or more copy/move operation, so it will only work with types that are in fact copyable. And it will incur one copy if the compiler cannot use a move, such as when the type of the expression is a std::array or a FieldMatrix. (Any second copy that may semantically be necessary will be elided.)

To teach autoCopy() about a particular proxy type, specialize Dune::AutonomousValueType.

Note
Do not overload Dune::autoCopy() directly. It is meant to be found by unqualified or qualified lookup, not by ADL. There is little guarantee that your overload will be declared before the definition of internal Dune functions that use autoCopy(). They would need the lazy binding provided by ADL to find your overload, but they will probably use unqualified lookup.

◆ handle_proxy_member_access()

template<typename T >
pointer_or_proxy_holder Dune::handle_proxy_member_access ( T &&  t)

Transparent support for providing member access to both lvalues and rvalues (temporary proxies).

If an iterator facade (like entity iterators) wants to allow the embedded implementation to return either an (internally stored) reference or a temporary object and expose these two behaviors to enable performance optimizations, operator->() needs special handling: If the implementation returns a reference, operator->() in the facade can simply return the address of the referenced object, but if the returned object is a temporary, we need to capture and store it in a helper object to make sure it outlives the member access. This function transparently supports both variants. It should be used like this:

class iterator
{
...
decltype(handle_proxy_member_access(implementation.dereference()))
operator->() const
{
return handle_proxy_member_access(implementation.dereference());
}
...
};
pointer_or_proxy_holder handle_proxy_member_access(T &&t)
Transparent support for providing member access to both lvalues and rvalues (temporary proxies).
Note
This function exploits the special type deduction rules for unqualified rvalue references to distinguish between lvalues and rvalues and thus needs to be passed the object returned by the implementation.

◆ integerSequenceEntry()

template<class T , T... t, std::size_t index>
constexpr auto Dune::integerSequenceEntry ( std::integer_sequence< T, t... >  ,
std::integral_constant< std::size_t, index >  i 
)
constexpr

Get entry of std::integer_sequence.

Parameters
iIndex
Returns
The i-th entry of the integer_sequence encoded as std::integral_constant<std::size_t, entry>.

◆ orderedOverload()

template<class... F>
auto Dune::orderedOverload ( F &&...  f)

Create an ordered overload set.

Template Parameters
FList of function object types
Parameters
fList of function objects

This returns an object that contains all operator() implementations of the passed functions. All those are available when calling operator() of the returned object.

In contrast to overload() these overloads are ordered in the sense that the first matching overload for the given arguments is selected and later ones are ignored. Hence such a call is never ambiguous.

Notice that the passed function objects are stored by value and must be copy-constructible.

◆ overload()

template<class... F>
auto Dune::overload ( F &&...  f)

Create an overload set.

Template Parameters
FList of function object types
Parameters
fList of function objects

This returns an object that contains all operator() implementations of the passed functions. All those are available when calling operator() of the returned object.

The returned object derives from those implementations such that it contains all operator() implementations in its overload set. When calling operator() this will select the best overload. If multiple overload are equally good this will lead to ambiguity.

Notice that the passed function objects are stored by value and must be copy-constructible.

◆ resolveRef() [1/2]

template<class T >
constexpr T & Dune::resolveRef ( std::reference_wrapper< T >  gf)
constexprnoexcept

Helper function to resolve std::reference_wrapper.

This is the overload for std::reference_wrapper<T>. It resolves the reference by returning the stored (mutable or const) l-value reference. It is safe to call this with mutable or cost l-values as well as r-values of std::reference_wrapper, because the life time of the wrapped l-value reference is independent of the wrapping std::reference_wrapper<T> object.

Notice that the copy created by calling this function is easily elided by the compiler, since std::reference_wrapper is trivially copyable.

◆ resolveRef() [2/2]

template<class T >
constexpr T & Dune::resolveRef ( T &  gf)
constexprnoexcept

Helper function to resolve std::reference_wrapper.

This is the overload for plain (mutable or const) l-value reference types. It simply forwards the passed l-value reference.

Creative Commons License   |  Legal Statements / Impressum  |  Hosted by TU Dresden  |  generated with Hugo v0.111.3 (Jun 16, 22:32, 2024)