icarus::ns::util::ChangeMonitor< T, Comp > Struct Template Reference

Helper to check if an object has changed. More...

#include <ChangeMonitor.h>

Inheritance diagram for icarus::ns::util::ChangeMonitor< T, Comp >:

Public Types
using	Data_t = T
	Type of the object being monitored. More...
using	Comparison_t = Comp
	Type of object for reference comparison. More...

Public Member Functions
	ChangeMonitor (Comparison_t comp=Comparison_t{})
	Default constructor: starts with no reference value. More...
	ChangeMonitor (Data_t const &ref, Comp comp=Comp{})
	Constructor: starts with ref as the reference value. More...
std::optional< Data_t >	update (Data_t const &currentObj)
	Returns the old object if different from newObj. More...
std::optional< Data_t >	operator() (Data_t const &currentObj)
	As update(). More...
bool	hasReference () const
	Returns whether a reference value is present. More...
Data_t const &	reference () const
	Returns the reference value; undefined if hasReference() is false. More...

Private Member Functions
bool	same (Data_t const &A, Data_t const &B) const
	Returns whether A and B represent the same value. More...

Private Attributes
std::optional< Data_t >	fRefObj
	The last object seen. More...
Comparison_t	fComp
	Comparison used for reference testing. More...

Detailed Description

template<typename T, typename Comp = std::equal_to<T>>
struct icarus::ns::util::ChangeMonitor< T, Comp >

Helper to check if an object has changed.

Template Parameters

T	type of the object
Comp	type of the comparison between T objects

This class can report if a value has changed from a previous check. The usage pattern is:

1. a ChangeMonitor is created
2. the monitor object is given a value, which becomes the new reference
3. arbitrary processing happens
4. the monitor object is given another value, which becomes the new reference; if this value is different from the previous reference, the previous reference is returned
5. steps 2 and 3 can be reiterated

Example of usage:

// starts with no reference by default
icarus::ns::util::ChangeMonitor<int> monitor;

// first check just establishes the reference
int var = 0;
monitor(var); // this is also a `update()`, which returns no value

// reference is 0, new value is 1: a change is detected
if (monitor(1)) {
  std::cout << "Value has changed!" << std::endl;
}

var = 5; // this does not change the monitoring
// reference is now 1, new value is 1: no change is detected
if (monitor(1)) {
  std::cout << "Value has changed again!" << std::endl;
}

// more complex syntax (C++17) allows accessing the old reference value;
// reference is now 1, new value is 2: change is detected
if (auto prevVal = monitor(2); prevVal) {
  std::cout << "Value has changed from " << *prevVal << " to 2!"
    << std::endl;
}

A few observations:

• the object with default construction starts with no reference value; since changes are reported only when a reference value is available, the first update() will not report any change; a constructor is available to establish a reference at construction time;
• the monitor operates on values but it does not monitor a variable the value might be stored in; therefore, even if the value of the variable var which established the reference is later changed, the monitor is oblivious to that change.

A copy of the "current" T object is kept in this object.

Requirements for T:

• must be CopyConstructible
• must be EqualityComparable (if Comp is default)

Note

This implementation is not thread-safe. For a thread-safe change monitor, see icarus::ns::util::ThreadSafeChangeMonitor.

Definition at line 85 of file ChangeMonitor.h.

Member Typedef Documentation

template<typename T, typename Comp = std::equal_to<T>>

using icarus::ns::util::ChangeMonitor< T, Comp >::Comparison_t = Comp

Type of object for reference comparison.

Definition at line 88 of file ChangeMonitor.h.

template<typename T, typename Comp = std::equal_to<T>>

using icarus::ns::util::ChangeMonitor< T, Comp >::Data_t = T

Type of the object being monitored.

Definition at line 87 of file ChangeMonitor.h.

Constructor & Destructor Documentation

template<typename T, typename Comp = std::equal_to<T>>

icarus::ns::util::ChangeMonitor< T, Comp >::ChangeMonitor ( Comparison_t  comp = Comparison_t{} )

inline

Default constructor: starts with no reference value.

Definition at line 91 of file ChangeMonitor.h.

{}): fComp(std::move(comp)) {}

template<typename T, typename Comp = std::equal_to<T>>

icarus::ns::util::ChangeMonitor< T, Comp >::ChangeMonitor ( Data_t const &  ref, Comp  comp = Comp{}  )

inline

Constructor: starts with ref as the reference value.

Definition at line 94 of file ChangeMonitor.h.

                                                     {})
      : fRefObj(ref), fComp(std::move(comp)) {}

Member Function Documentation

template<typename T, typename Comp = std::equal_to<T>>

bool icarus::ns::util::ChangeMonitor< T, Comp >::hasReference ( ) const

inline

Returns whether a reference value is present.

Definition at line 124 of file ChangeMonitor.h.

{ return fRefObj.has_value(); }

template<typename T, typename Comp = std::equal_to<T>>

std::optional<Data_t> icarus::ns::util::ChangeMonitor< T, Comp >::operator() ( Data_t const &  currentObj )

inline

As update().

Definition at line 120 of file ChangeMonitor.h.

      { return update(currentObj); }

template<typename T, typename Comp = std::equal_to<T>>

Data_t const& icarus::ns::util::ChangeMonitor< T, Comp >::reference ( ) const

inline

Returns the reference value; undefined if hasReference() is false.

Definition at line 127 of file ChangeMonitor.h.

{ return fRefObj.value(); }

template<typename T, typename Comp = std::equal_to<T>>

bool icarus::ns::util::ChangeMonitor< T, Comp >::same ( Data_t const &  A, Data_t const &  B  ) const

inlineprivate

Returns whether A and B represent the same value.

Definition at line 137 of file ChangeMonitor.h.

{ return fComp(A, B); }

template<typename T, typename Comp = std::equal_to<T>>

std::optional<Data_t> icarus::ns::util::ChangeMonitor< T, Comp >::update ( Data_t const &  currentObj )

inline

Returns the old object if different from newObj.

Parameters

currentObj

the current object value

Returns

the old reference if different from currentObj, or no value

If there is no reference value, no value is returned. Otherwise, the reference is updated and the value of the old reference is returned. After each call, the reference value will be equivalent to currentObj.

Note

"No value returned" technically means that the std::optional object returned has no value, i.e. has_value() is false.

Definition at line 111 of file ChangeMonitor.h.

      {
        if (fRefObj && same(currentObj, fRefObj.value())) return {};
        auto lastObj = std::move(fRefObj);
        fRefObj.emplace(currentObj);
        return lastObj;
      }

Member Data Documentation

template<typename T, typename Comp = std::equal_to<T>>

Comparison_t icarus::ns::util::ChangeMonitor< T, Comp >::fComp

private

Comparison used for reference testing.

Definition at line 134 of file ChangeMonitor.h.

template<typename T, typename Comp = std::equal_to<T>>

std::optional<Data_t> icarus::ns::util::ChangeMonitor< T, Comp >::fRefObj

private

The last object seen.

Definition at line 132 of file ChangeMonitor.h.

---

The documentation for this struct was generated from the following file:

• ChangeMonitor.h