jaulib v1.3.0
Jau Support Library (C++, Java, ..)
Namespaces | Classes | Enumerations | Functions
Function Wrapper

A general-purpose static-polymorphic function wrapper via jau::function<R(A...)>. More...

Namespaces

namespace  jau::func
 

Classes

class  jau::func::capref_target_t< R, I, A >
 func::capref_target_t implementation for functions using a reference to a captured value, identifiable as func::target_type::capref via jau::function<R(A...)>::type(). More...
 
class  jau::func::capval_target_t< R, I, A >
 func::capval_target_t implementation for functions using a copy of a captured value, identifiable as func::target_type::capval via jau::function<R(A...)>::type(). More...
 
class  jau::func::delegate_t< R, A >
 Delegated target function object, providing a fast path target function invocation. More...
 
class  jau::func::free_target_t< R, A >
 func::free_target_t implementation for free functions, identifiable as func::target_type::free via jau::function<R(A...)>::type(). More...
 
class  jau::function< Signature >
 Class template jau::function is a general-purpose static-polymorphic function wrapper. More...
 
class  jau::function< R(A...)>
 Class template jau::function is a general-purpose static-polymorphic function wrapper. More...
 
class  jau::func::lambda_target_t< R, L, A >
 func::lambda_target_t implementation for lambda closures, identifiable as func::target_type::lambda via jau::function<R(A...)>::type(). More...
 
class  jau::func::member_target_t< R, C0, C1, A >
 func::member_target_t implementation for class member functions, identifiable as func::target_type::member via jau::function<R(A...)>::type(). More...
 
class  jau::func::null_target_t< R, A >
 func::null_target_t implementation for no function. More...
 
class  jau::func::std_target_t< R, A >
 func::std_target_t implementation for std::function instances, identifiable as func::target_type::std via jau::function<R(A...)>::type(). More...
 
class  jau::func::ylambda_target_t< R, L, A >
 func::ylambda_target_t is a Y combinator and deducing this implementation for lambda closures usable for recursive algorithms. More...
 

Enumerations

enum class  jau::func::target_type : uint32_t {
  jau::func::target_type::null = 0 , jau::func::target_type::member = 1 , jau::func::target_type::free = 2 , jau::func::target_type::lambda = 3 ,
  jau::func::target_type::ylambda = 4 , jau::func::target_type::capval = 5 , jau::func::target_type::capref = 6 , jau::func::target_type::std = 7
}
 func::target_type identifier for the target function delegate_t<R, A...> object, exposed by jau::function<R(A...)>::type(). More...
 

Functions

template<typename R , typename I , typename... A>
jau::function< R(A...)> jau::bind_capref (I *data_ptr, R(*func)(I *, A...)) noexcept
 Bind given data by passing the captured reference (pointer) to the value and non-void function to an anonymous function using func::capref_target_t. More...
 
template<typename I , typename... A>
jau::function< void(A...)> jau::bind_capref (I *data_ptr, void(*func)(I *, A...)) noexcept
 Bind given data by passing the captured reference (pointer) to the value and void function to an anonymous function using func::capref_target_t. More...
 
template<typename R , typename I , typename... A>
jau::function< R(A...)> jau::bind_capval (const I &data, R(*func)(I &, A...)) noexcept
 Bind given data by copying the captured value and the given non-void function to an anonymous function using func::capval_target_t. More...
 
template<typename I , typename... A>
jau::function< void(A...)> jau::bind_capval (const I &data, void(*func)(I &, A...)) noexcept
 Bind given data by copying the captured value and the given void function to an anonymous function using func::capval_target_t. More...
 
template<typename R , typename I , typename... A>
jau::function< R(A...)> jau::bind_capval (I &&data, R(*func)(I &, A...)) noexcept
 Bind given data by moving the captured value and copying the given non-void function to an anonymous function using func::capval_target_t. More...
 
template<typename I , typename... A>
jau::function< void(A...)> jau::bind_capval (I &&data, void(*func)(I &, A...)) noexcept
 Bind given data by moving the captured value and copying the given void function to an anonymous function using func::capval_target_t. More...
 
template<typename R , typename... A>
jau::function< R(A...)> jau::bind_free (R(*func)(A...)) noexcept
 Bind given non-void free-function to an anonymous function using func::free_target_t. More...
 
template<typename... A>
jau::function< void(A...)> jau::bind_free (void(*func)(A...)) noexcept
 Bind given void free-function to an anonymous function using func::free_target_t. More...
 
template<typename R , typename C , typename... A>
jau::function< R(A...)> jau::bind_member (C *base, R(C::*mfunc)(A...)) noexcept
 Bind given class instance and non-void member function to an anonymous function using func_member_targer_t. More...
 
template<typename C , typename... A>
jau::function< void(A...)> jau::bind_member (C *base, void(C::*mfunc)(A...)) noexcept
 Bind given class instance and void member function to an anonymous function using func_member_targer_t. More...
 
template<typename R , typename C0 , typename C1 , typename... A>
jau::function< R(A...)> jau::bind_member (C1 *base, R(C0::*mfunc)(A...)) noexcept
 Bind given class instance and non-void member function to an anonymous function using func_member_targer_t. More...
 
template<typename C0 , typename C1 , typename... A>
jau::function< void(A...)> jau::bind_member (C1 *base, void(C0::*mfunc)(A...)) noexcept
 Bind given class instance and void member function to an anonymous function using func_member_targer_t. More...
 
template<typename R , typename... A>
jau::function< R(A...)> jau::bind_std (uint64_t id, std::function< R(A...)> func) noexcept
 Bind given non-void std::function to an anonymous function using func::std_target_t. More...
 
template<typename... A>
jau::function< void(A...)> jau::bind_std (uint64_t id, std::function< void(A...)> func) noexcept
 Bind given void std::function to an anonymous function using func::std_target_t. More...
 
constexpr uint32_t jau::number (const func::target_type rhs) noexcept
 
template<class R , class... A>
bool jau::operator!= (const function< R(A...)> &lhs, std::nullptr_t) noexcept
 Unequal operator of jau::function<R(A...)> with a right-hand-side nullptr. More...
 
template<typename Rl , typename... Al, template< typename... > typename Fl = function, typename Rr , typename... Ar, template< typename... > typename Fr = function>
bool jau::operator!= (const function< Rl(Al...)> &lhs, const function< Rr(Ar...)> &rhs) noexcept
 Unequal operator using two jau::function<R(A...)> types for both arguments. More...
 
template<class R , class... A>
bool jau::operator!= (std::nullptr_t, const function< R(A...)> &rhs) noexcept
 Unequal operator of jau::function<R(A...)> with a left-hand-side nullptr. More...
 
template<class R , class... A>
bool jau::operator== (const function< R(A...)> &lhs, std::nullptr_t) noexcept
 Equal operator of jau::function<R(A...)> with a right-hand-side nullptr. More...
 
template<typename Rl , typename... Al, template< typename... > class Fl = function, typename Rr , typename... Ar, template< typename... > class Fr = function, std::enable_if_t< !std::is_same_v< Fl< Rl(Al...)>, Fr< Rr(Ar...)> >, bool > = true>
bool jau::operator== (const function< Rl(Al...)> &lhs, const function< Rr(Ar...)> &rhs) noexcept
 Equal operator using different jau::function<R(A...)> return and argument types for both arguments, always returns false. More...
 
template<class R , class... A>
bool jau::operator== (std::nullptr_t, const function< R(A...)> &rhs) noexcept
 Equal operator of jau::function<R(A...)> with a left-hand-side nullptr. More...
 
std::string jau::to_string (const func::target_type v) noexcept
 

Detailed Description

A general-purpose static-polymorphic function wrapper via jau::function<R(A...)>.

Function Overview

Similar to std::function, jau::function<R(A...)> stores any callable target function solely described by its return type R and arguments types A... from any source, e.g. free functions, capturing and non-capturing lambda function, member functions.

jau::function<R(A...)> supports equality operations for all func::target_type source types, allowing to manage container of jau::functions, see limitations below.

If a jau::function contains no target, see jau::function<R(A...)>::is_null(), it is empty. Invoking the target of an empty jau::function is a no-operation and has no side effects.

jau::function satisfies the requirements of CopyConstructible, CopyAssignable, MoveConstructible and MoveAssignable.

Compared to std::function<R(A...)>, jau::function<R(A...)>

Instances of jau::function can store, copy, move and invoke any of its callable targets

Implementation Details

jau::function<R(A...)> holds the static polymorphic target function delegate_t<R, A...>,
which itself completely holds up to 24 bytes sized TriviallyCopyable target function objects to avoiding cache misses.

The following table shows the full memory footprint of the target function delegate_t<R, A...> storage,
which equals to jau::function<R(A...)> memory size as it only contains the instance of delegate_t<R, A...>.

Type Signature Target Function Size delegate_t<R, A...> Size Heap Size Total Size TriviallyCopyable
free function<free, void ()> 8 48 0 48 true
member function<member, int (int)> 16 48 0 48 true
lambda_plain function<lambda, int (int)> 24 48 0 48 true
lambda_ref function<lambda, int (int)> 24 48 0 48 true
lambda_copy function<lambda, int (int)> 24 48 0 48 true
ylambda_plain function<ylambda, int (int)> 24 48 0 48 true
capval (small) function<capval, int (int)> 16 48 0 48 true
capval (big) function<capval, int (int)> 48 48 48 96 true
capref function<capref, int (int)> 16 48 0 48 true

Memory sizes are in bytes, data collected on a GNU/Linux arm64 system.

The detailed memory footprint can queried at runtime, see implementation of jau::function<R(A...)>::function::toString().

Static polymorphism is achieved by constructing the delegate_t<R, A...> instance via their func::target_type specific factories, see mapping at func::target_type.

For example the static func::member_target_t::delegate constructs its specific delegate_t<R, A...> by passing its data and required functions to func::delegate_t<R, A...>::make.
The latter is an overloaded template for trivial and non-trivial types and decides which memory is being used, e.g. the internal 24 bytes memory cache or heap if not fitting.

To support lambda identity for the equality operator, jau::type_info is being used either with Runtime Type Information (RTTI) if enabled or using Compile time type information (CTTI), see limitations below.

Function Usage

A detailed API usage is covered within test_functional.hpp and test_functional_perf.hpp, see function test00_usage().

Let's assume we like to bind to the following function prototype bool func(int), which results to jau::function<bool(int)>:

Function Limitations

Non unique lambda type names without RTTI using gcc or non clang compiler

Due to limitations of jau::make_ctti<R, L, A...>(), not using RTTI on gcc or non clang compiler will erroneously mistake different lambda functions defined within one function and using same function prototype R<A...> to be the same.

jau::type_info::limited_lambda_id will expose the potential limitation.

See CTTI lambda name limitations and limitations of jau::type_info.

Enumeration Type Documentation

◆ target_type

enum class jau::func::target_type : uint32_t
strong

func::target_type identifier for the target function delegate_t<R, A...> object, exposed by jau::function<R(A...)>::type().

See also
Function Overview
Enumerator
null 

Denotes a func::null_target_t.

member 

Denotes a func::member_target_t.

free 

Denotes a func::free_target_t.

lambda 

Denotes a func::lambda_target_t.

ylambda 

Denotes a func::ylambda_target_t.

capval 

Denotes a func::capval_target_t.

capref 

Denotes a func::capref_target_t.

std 

Denotes a func::std_target_t.

Definition at line 341 of file functional.hpp.

Function Documentation

◆ number()

constexpr uint32_t jau::number ( const func::target_type  rhs)
constexprnoexcept

Definition at line 1196 of file functional.hpp.

Here is the caller graph for this function:

◆ to_string()

std::string jau::to_string ( const func::target_type  v)
noexcept

Definition at line 535 of file basic_types.cpp.

Here is the caller graph for this function:

◆ operator==() [1/3]

template<typename Rl , typename... Al, template< typename... > class Fl = function, typename Rr , typename... Ar, template< typename... > class Fr = function, std::enable_if_t< !std::is_same_v< Fl< Rl(Al...)>, Fr< Rr(Ar...)> >, bool > = true>
bool jau::operator== ( const function< Rl(Al...)> &  lhs,
const function< Rr(Ar...)> &  rhs 
)
noexcept

Equal operator using different jau::function<R(A...)> return and argument types for both arguments, always returns false.

Equal operator using same jau::function<R(A...)> return and argument types for both arguments, returning actual result of equality operation.

Template Parameters
Rlleft function return type
Alleft function arguments
Flleft function Fl<Rl(<Al...)>
Rrright function return type
Arright function arguments
Frright function Fr<Rr(<Ar...)>
Parameters
lhsleft function Fl<Rl(<Al...)>
rhsright function Fr<Rr(<Ar...)>
Returns
false
See also
function Overview
function Usage
Template Parameters
Rlleft function return type
Alleft function arguments
Flleft function Fl<Rl(<Al...)>
Rrright function return type
Arright function arguments
Frright function Fr<Rr(<Ar...)>
Parameters
lhsleft function Fl<Rl(<Al...)>
rhsright function Fr<Rr(<Ar...)>
Returns
equality result of same type functions
See also
function Overview
function Usage

Definition at line 1518 of file functional.hpp.

◆ operator!=() [1/3]

template<typename Rl , typename... Al, template< typename... > typename Fl = function, typename Rr , typename... Ar, template< typename... > typename Fr = function>
bool jau::operator!= ( const function< Rl(Al...)> &  lhs,
const function< Rr(Ar...)> &  rhs 
)
noexcept

Unequal operator using two jau::function<R(A...)> types for both arguments.

Template Parameters
Rlleft function return type
Alleft function arguments
Flleft function Fl<Rl(<Al...)>
Rrright function return type
Arright function arguments
Frright function Fr<Rr(<Ar...)>
Parameters
lhsleft function Fl<Rl(<Al...)>
rhsright function Fr<Rr(<Ar...)>
Returns
unequality result of same type functions
See also
function Overview
function Usage

Definition at line 1563 of file functional.hpp.

◆ operator==() [2/3]

template<class R , class... A>
bool jau::operator== ( const function< R(A...)> &  lhs,
std::nullptr_t   
)
noexcept

Equal operator of jau::function<R(A...)> with a right-hand-side nullptr.

Template Parameters
Rleft function return type
Aleft function arguments
Parameters
lhsleft function
Returns
true if function instance contains no function, i.e. !lhs negated function bool operator.

Definition at line 1574 of file functional.hpp.

◆ operator!=() [2/3]

template<class R , class... A>
bool jau::operator!= ( const function< R(A...)> &  lhs,
std::nullptr_t   
)
noexcept

Unequal operator of jau::function<R(A...)> with a right-hand-side nullptr.

Template Parameters
Rleft function return type
Aleft function arguments
Parameters
lhsleft function
Returns
true if function instance contains a function, i.e. lhs function bool operator.

Definition at line 1585 of file functional.hpp.

◆ operator==() [3/3]

template<class R , class... A>
bool jau::operator== ( std::nullptr_t  ,
const function< R(A...)> &  rhs 
)
noexcept

Equal operator of jau::function<R(A...)> with a left-hand-side nullptr.

Template Parameters
Rright function return type
Aright function arguments
Parameters
rhsright function
Returns
true if function instance contains no function, i.e. !lhs negated function bool operator.

Definition at line 1596 of file functional.hpp.

◆ operator!=() [3/3]

template<class R , class... A>
bool jau::operator!= ( std::nullptr_t  ,
const function< R(A...)> &  rhs 
)
noexcept

Unequal operator of jau::function<R(A...)> with a left-hand-side nullptr.

Template Parameters
Rright function return type
Aright function arguments
Parameters
rhsright function
Returns
true if function instance contains a function, i.e. lhs function bool operator.

Definition at line 1607 of file functional.hpp.

◆ bind_member() [1/4]

template<typename R , typename C0 , typename C1 , typename... A>
jau::function< R(A...)> jau::bind_member ( C1 base,
R(C0::*)(A...)  mfunc 
)
inlinenoexcept

Bind given class instance and non-void member function to an anonymous function using func_member_targer_t.

Template Parameters
Rfunction return type
C0class type holding the member-function
C1class derived from C0 or C0 of this base-pointer used to invoke the member-function
Afunction arguments
Parameters
baseclass instance this pointer
mfuncmember-function with R return value and A... arguments.
Returns
anonymous function
See also
function constructor for member function
function Overview
function Usage
Examples
test_functional.hpp, and test_functional_perf.hpp.

Definition at line 1627 of file functional.hpp.

Here is the caller graph for this function:

◆ bind_member() [2/4]

template<typename R , typename C , typename... A>
jau::function< R(A...)> jau::bind_member ( C *  base,
R(C::*)(A...)  mfunc 
)
inlinenoexcept

Bind given class instance and non-void member function to an anonymous function using func_member_targer_t.

Template Parameters
Rfunction return type
Cclass type holding the member-function and of this base pointer
Afunction arguments
Parameters
baseclass instance this pointer
mfuncmember-function with R return value and A... arguments.
Returns
anonymous function
See also
function constructor for member function
function Overview
function Usage

Definition at line 1647 of file functional.hpp.

◆ bind_member() [3/4]

template<typename C0 , typename C1 , typename... A>
jau::function< void(A...)> jau::bind_member ( C1 base,
void(C0::*)(A...)  mfunc 
)
inlinenoexcept

Bind given class instance and void member function to an anonymous function using func_member_targer_t.

Template Parameters
C0class type holding the member-function
C1class derived from C0 or C0 of this base-pointer used to invoke the member-function
Afunction arguments
Parameters
baseclass instance this pointer
mfuncmember-function with A... arguments.
Returns
anonymous function
See also
function constructor for member function
function Overview
function Usage

Definition at line 1667 of file functional.hpp.

◆ bind_member() [4/4]

template<typename C , typename... A>
jau::function< void(A...)> jau::bind_member ( C *  base,
void(C::*)(A...)  mfunc 
)
inlinenoexcept

Bind given class instance and void member function to an anonymous function using func_member_targer_t.

Template Parameters
Cclass type holding the member-function and of this base pointer
Afunction arguments
Parameters
baseclass instance this pointer
mfuncmember-function with A... arguments.
Returns
anonymous function
See also
function constructor for member function
function Overview
function Usage

Definition at line 1686 of file functional.hpp.

◆ bind_free() [1/2]

template<typename R , typename... A>
jau::function< R(A...)> jau::bind_free ( R(*)(A...)  func)
inlinenoexcept

Bind given non-void free-function to an anonymous function using func::free_target_t.

Template Parameters
Rfunction return type
Afunction arguments
Parameters
funcfree-function with R return value and A... arguments.
Returns
anonymous function
See also
function constructor for free function
function Overview
function Usage
Examples
test_functional.hpp, and test_functional_perf.hpp.

Definition at line 1704 of file functional.hpp.

Here is the caller graph for this function:

◆ bind_free() [2/2]

template<typename... A>
jau::function< void(A...)> jau::bind_free ( void(*)(A...)  func)
inlinenoexcept

Bind given void free-function to an anonymous function using func::free_target_t.

Template Parameters
Afunction arguments
Parameters
funcfree-function with A... arguments.
Returns
anonymous function
See also
function constructor for free function
function Overview
function Usage

Definition at line 1721 of file functional.hpp.

◆ bind_capval() [1/4]

template<typename R , typename I , typename... A>
jau::function< R(A...)> jau::bind_capval ( const I &  data,
R(*)(I &, A...)  func 
)
inlinenoexcept

Bind given data by copying the captured value and the given non-void function to an anonymous function using func::capval_target_t.

const I& data will be copied into func::capval_target_t and hence captured by-copy.

The function invocation will have the reference of the copied data being passed to the target function for efficiency.

Template Parameters
Rfunction return type
Itypename holding the captured data used by the function
Afunction arguments
Parameters
datadata type instance holding the captured data
funcfunction with R return value and A... arguments.
Returns
anonymous function
See also
function constructor for copying capturing value
function Overview
function Usage
Examples
test_functional.hpp, and test_functional_perf.hpp.

Definition at line 1745 of file functional.hpp.

Here is the caller graph for this function:

◆ bind_capval() [2/4]

template<typename I , typename... A>
jau::function< void(A...)> jau::bind_capval ( const I &  data,
void(*)(I &, A...)  func 
)
inlinenoexcept

Bind given data by copying the captured value and the given void function to an anonymous function using func::capval_target_t.

const I& data will be copied into func::capval_target_t and hence captured by-copy.

The function invocation will have the reference of the copied data being passed to the target function for efficiency.

Template Parameters
Itypename holding the captured data used by the function
Afunction arguments
Parameters
datadata type instance holding the captured data
funcfunction with A... arguments.
Returns
anonymous function
See also
function constructor for copying capturing value
function Overview
function Usage

Definition at line 1768 of file functional.hpp.

◆ bind_capval() [3/4]

template<typename R , typename I , typename... A>
jau::function< R(A...)> jau::bind_capval ( I &&  data,
R(*)(I &, A...)  func 
)
inlinenoexcept

Bind given data by moving the captured value and copying the given non-void function to an anonymous function using func::capval_target_t.

I&& data will be moved into func::capval_target_t.

The function invocation will have the reference of the moved data being passed to the target function for efficiency.

Template Parameters
Rfunction return type
Itypename holding the captured data used by the function
Afunction arguments
Parameters
datadata type instance holding the captured data
funcfunction with R return value and A... arguments.
Returns
anonymous function
See also
function constructor for moving capturing value
function Overview
function Usage

Definition at line 1792 of file functional.hpp.

◆ bind_capval() [4/4]

template<typename I , typename... A>
jau::function< void(A...)> jau::bind_capval ( I &&  data,
void(*)(I &, A...)  func 
)
inlinenoexcept

Bind given data by moving the captured value and copying the given void function to an anonymous function using func::capval_target_t.

I&& data will be moved into func::capval_target_t.

The function invocation will have the reference of the moved data being passed to the target function for efficiency.

Template Parameters
Itypename holding the captured data used by the function
Afunction arguments
Parameters
datadata type instance holding the captured data
funcfunction with A... arguments.
Returns
anonymous function
See also
function constructor for moving capturing value
function Overview
function Usage

Definition at line 1815 of file functional.hpp.

◆ bind_capref() [1/2]

template<typename R , typename I , typename... A>
jau::function< R(A...)> jau::bind_capref ( I *  data_ptr,
R(*)(I *, A...)  func 
)
inlinenoexcept

Bind given data by passing the captured reference (pointer) to the value and non-void function to an anonymous function using func::capref_target_t.

The function invocation will have the reference of the data being passed to the target function.

Template Parameters
Rfunction return type
Itypename holding the captured data used by the function
Afunction arguments
Parameters
data_ptrdata type reference to instance holding the captured data
funcfunction with R return value and A... arguments.
Returns
anonymous function
See also
function constructor for capturing reference
function Overview
function Usage
Examples
test_functional.hpp, and test_functional_perf.hpp.

Definition at line 1837 of file functional.hpp.

Here is the caller graph for this function:

◆ bind_capref() [2/2]

template<typename I , typename... A>
jau::function< void(A...)> jau::bind_capref ( I *  data_ptr,
void(*)(I *, A...)  func 
)
inlinenoexcept

Bind given data by passing the captured reference (pointer) to the value and void function to an anonymous function using func::capref_target_t.

The function invocation will have the reference of the data being passed to the target function.

Template Parameters
Itypename holding the captured data used by the function
Afunction arguments
Parameters
data_ptrdata type reference to instance holding the captured data
funcfunction with A... arguments.
Returns
anonymous function
See also
function constructor for capturing reference
function Overview
function Usage

Definition at line 1858 of file functional.hpp.

◆ bind_std() [1/2]

template<typename R , typename... A>
jau::function< R(A...)> jau::bind_std ( uint64_t  id,
std::function< R(A...)>  func 
)
inlinenoexcept

Bind given non-void std::function to an anonymous function using func::std_target_t.

Notable, instance is holding the given unique uint64_t identifier to allow implementing the equality operator w/o RTTI, not supported by std::function.

Template Parameters
Rfunction return type
Afunction arguments
Parameters
funcfree-function with R return value and A... arguments.
Returns
anonymous function
See also
function constructor for std::function
function Overview
function Usage
Examples
test_functional.hpp, and test_functional_perf.hpp.

Definition at line 1879 of file functional.hpp.

Here is the caller graph for this function:

◆ bind_std() [2/2]

template<typename... A>
jau::function< void(A...)> jau::bind_std ( uint64_t  id,
std::function< void(A...)>  func 
)
inlinenoexcept

Bind given void std::function to an anonymous function using func::std_target_t.

Notable, instance is holding the given unique uint64_t identifier to allow implementing the equality operator w/o RTTI, not supported by std::function.

Template Parameters
Afunction arguments
Parameters
funcfree-function with A... arguments.
Returns
anonymous function
See also
function constructor for std::function
function Overview
function Usage

Definition at line 1899 of file functional.hpp.