eventpp/doc/conditionalfunctor.md

# Conditional functor reference

## Description

The header file `eventpp/utilities/conditionalfunctor.h` contains utilities that can check certain condition then decide whether to invoke the underlying function.  

For example,  

```c++
eventpp::CallbackList<void(int)> callbackList;

callbackList.append(
    eventpp::conditionalFunctor(
        [](const int value) {
            std::cout << "We should get value 1." << here;
        },
        [](const int value) {
            return value == 1;
        }
    )
);
callbackList(2); // not trigger the callback
callbackList(1); // trigger the callback
```

## Header

eventpp/utilities/conditionalfunctor.h

## API reference

```c++
template <typename Func, typename Condition>
ConditionalFunctor<Func, Condition> conditionalFunctor(Func func, Condition condition);
```

Function `conditionalFunctor` receives a function `func`, and a conditional function `condition`, and return a functor object of `ConditionalFunctor`. `ConditionalFunctor` has a function invoking operator that forwards all arguments to `condition`, if `condition` returns true, `func` will be invoked with same arguments, if `condition` return false, `func` will not be invoked. The return value of `conditionalFunctor` can be passed to CallbackList, EventDispatcher, or EventQueue.  

Below is the example code to demonstrate how to use `conditionalFunctor`, it's grabbed from the unit tests.  

```c++

eventpp::CallbackList<void(int)> callbackList;

std::vector<int> dataList(3);
callbackList.append(
    eventpp::conditionalFunctor(
        [&dataList](const int index) {
            ++dataList[index];
        },
        [](const int index) {
            return index == 0;
        }
    )
);
callbackList.append(
    eventpp::conditionalFunctor(
        [&dataList](const int index) {
            ++dataList[index];
        },
        [](const int index) {
            return index == 1;
        }
    )
);
callbackList.append(
    eventpp::conditionalFunctor(
        [&dataList](const int index) {
            ++dataList[index];
        },
        [](const int index) {
            return index == 2;
        }
    )
);

REQUIRE(dataList == std::vector<int>{ 0, 0, 0 });

callbackList(2);
REQUIRE(dataList == std::vector<int>{ 0, 0, 1 });

callbackList(0);
REQUIRE(dataList == std::vector<int>{ 1, 0, 1 });

callbackList(1);
REQUIRE(dataList == std::vector<int>{ 1, 1, 1 });

```