D++ (DPP)
C++ Discord API Bot Library
dpp::collector< T, C > Class Template Referenceabstract

Collects objects from events during a specified time period. More...

+ Inheritance diagram for dpp::collector< T, C >:
+ Collaboration diagram for dpp::collector< T, C >:

Public Member Functions

 collector (class cluster *cl, uint64_t duration, event_router_t< T > &event)
 Construct a new collector object. More...
 
virtual void completed (const std::vector< C > &list)=0
 You must implement this function to receive the completed list of captured objects. More...
 
virtual const C * filter (const T &element)=0
 Filter the list of elements. More...
 
virtual void cancel ()
 Immediately cancels the collector. More...
 
virtual ~collector ()
 Destroy the collector object. More...
 

Protected Attributes

class clusterowner
 Owning cluster. More...
 

Detailed Description

template<class T, class C>
class dpp::collector< T, C >

Collects objects from events during a specified time period.

This template must be specialised. There are premade specialisations which you can use such as dpp::reaction_collector and dpp::message_collector. For these specialised instances all you need to do is derive a simple class from them which implements collector::completed().

A collector will run for the specified number of seconds, attaching itself to the given event. During this time any events pass through the collector and collector::filter(). This function can return a pointer to an object to allow a copy of that object to be stored to a vector, or it can return nullptr to do nothing with that object. For example a collector attached to on_message_create would receive an event with the type message_create_t, and from this may decide to extract the message_create_t::msg structure, returning a pointer to it, or instead may choose to return a nullptr.

When either the predetermined timeout is reached, or the collector::cancel() method is called, or the collector is destroyed, the collector::completed() method is called, which will be passed a list of collected objects in the order they were collected.

Template Parameters
Tparameter type of the event this collector will monitor
Cobject type this collector will store

Constructor & Destructor Documentation

◆ collector()

template<class T , class C >
dpp::collector< T, C >::collector ( class cluster cl,
uint64_t  duration,
event_router_t< T > &  event 
)
inline

Construct a new collector object.

The timer for the collector begins immediately on construction of the object.

Parameters
clPointer to cluster which manages this collector
durationDuration in seconds to run the collector for
eventEvent to attach to, e.g. cluster::on_message_create

◆ ~collector()

template<class T , class C >
virtual dpp::collector< T, C >::~collector ( )
inlinevirtual

Destroy the collector object.

Note
Causes calling of the completed() method if it has not yet been called.

Member Function Documentation

◆ cancel()

template<class T , class C >
virtual void dpp::collector< T, C >::cancel ( )
inlinevirtual

Immediately cancels the collector.

Use this if you have met the conditions for which you are collecting objects early, e.g. you were watching for a message containing 'yes' or 'no' and have received it before the time is up.

Note
Causes calling of the completed() method if it has not yet been called.

◆ completed()

template<class T , class C >
virtual void dpp::collector< T, C >::completed ( const std::vector< C > &  list)
pure virtual

You must implement this function to receive the completed list of captured objects.

Parameters
listThe list of captured objects in captured order

◆ filter()

template<class T , class C >
virtual const C* dpp::collector< T, C >::filter ( const T &  element)
pure virtual

Filter the list of elements.

Every time an event is fired on the collector, this method wil be called to determine if we should add an object to the list or not. This function can then process the element value, extract the parts which are to be saved to a list (e.g. a dpp::message out of a dpp::message_create_t) and return it as the return value. Returning a value of nullptr causes no object to be stored.

Here is an example of how to filter messages which have specific text in them. This should be used with the specialised type dpp::message_collector

virtual const dpp::message* filter(const dpp::message_create_t& m) {
if (m.msg.content.find("something i want") != std::string::npos) {
return &m.msg;
} else {
return nullptr;
}
}
Parameters
elementThe event data to filter
Returns
const C* Returned object or nullptr

Member Data Documentation

◆ owner

template<class T , class C >
class cluster* dpp::collector< T, C >::owner
protected

Owning cluster.

dpp::message_create_t
Create message.
Definition: dispatcher.h:1655
dpp::collector::filter
virtual const C * filter(const T &element)=0
Filter the list of elements.
dpp::message
Represents messages sent and received on Discord.
Definition: message.h:2035
dpp::unicode_emoji::m
constexpr const char m[]
Definition: unicode_emoji.h:5304
D++ Library version 9.0.13D++ Library version 9.0.12D++ Library version 9.0.11D++ Library version 9.0.10D++ Library version 9.0.9D++ Library version 9.0.8D++ Library version 9.0.7D++ Library version 9.0.6D++ Library version 9.0.5D++ Library version 9.0.4D++ Library version 9.0.3D++ Library version 9.0.2D++ Library version 9.0.1D++ Library version 9.0.0D++ Library version 1.0.2D++ Library version 1.0.1D++ Library version 1.0.0