PahoMqttCpp
MQTT C++ Client for POSIX and Windows
Loading...
Searching...
No Matches
Data Structures | Public Types | Public Member Functions
mqtt::topic_matcher< T > Class Template Reference

#include <topic_matcher.h>

Data Structures

class  const_iterator
 
class  const_match_iterator
 
class  iterator
 
class  match_iterator
 

Public Types

using key_type = string
 
using mapped_type = T
 
using value_type = std::pair< key_type, mapped_type >
 
using reference = value_type
 
using const_reference = const value_type &
 
using value_ptr = std::unique_ptr< value_type >
 
using mapped_ptr = std::unique_ptr< mapped_type >
 

Public Member Functions

 topic_matcher ()
 
 topic_matcher (std::initializer_list< value_type > lst)
 
bool empty () const
 
void insert (value_type &&val)
 
void insert (const value_type &val)
 
mapped_ptr remove (const key_type &filter)
 
void prune ()
 
iterator begin ()
 
iterator end ()
 
const_iterator end () const noexcept
 
const_iterator cbegin () const
 
const_iterator cend () const noexcept
 
iterator find (const key_type &filter)
 
const_iterator find (const key_type &filter) const
 
match_iterator matches (const string &topic)
 
const_match_iterator matches (const string &topic) const
 
const_match_iterator matches_end () const noexcept
 
const_match_iterator matches_cend () const noexcept
 
bool has_match (const string &topic)
 

Detailed Description

template<typename T>
class mqtt::topic_matcher< T >

A collection of MQTT topic filters mapped to arbitrary values.

This can be used to get an iterator to all filters in the collection that match a topic. A typical use case might be to match incoming messages to specific callback functions based on topics, such as

To test against a single filter, see [TopicFilter](crate::TopicFilter). This collection is more commonly used when there are a number of filters and each needs to be associated with a particular action or piece of data. Note, however, that a single incoming topic could match against several items in the collection. For example, the topic:

data/temperature/engine

Could match against the filters:

data/temperature/engine
data/temperature/#
data/+/engine

Thus, the collection gives an iterator for the items matching a topic.

A common use for this would be to store callbacks to process incoming messages based on topics.

This code was adapted from the Eclipse Python MQTTMatcher class:

https://github.com/eclipse/paho.mqtt.python/blob/master/src/paho/mqtt/matcher.py

which use a prefix tree (trie) to store the values.

For example, if you had a topic_mapper<int> and you inserted:

{"some/random/topic", 42},
{"some/#", 99},
{"some/+/topic", 33}
};
Definition topic_matcher.h:109

The collection would be built like:

"some" -> <null>
"random" -> <null>
"topic" -> <42>
"#" -> <99>
"+" -> <null>
"topic" -> <33>

Note that the collection has two types of iterators. The basic iterator is a normal C++ iterator over all the items in the collection. It will visit every node in the collection and produce all items. This is not the typical use case for the collection, but can be used for diagnostics, etc, to show the full contents of the collection.

The more common use case is the match_iterator, returned by the topic_matcher::matches(string) method. This is an optimized search iterator for finding all the filters and values that match the specified topic string.

Member Typedef Documentation

◆ key_type

template<typename T >
using mqtt::topic_matcher< T >::key_type = string

◆ mapped_type

template<typename T >
using mqtt::topic_matcher< T >::mapped_type = T

◆ value_type

template<typename T >
using mqtt::topic_matcher< T >::value_type = std::pair<key_type, mapped_type>

◆ reference

template<typename T >
using mqtt::topic_matcher< T >::reference = value_type

◆ const_reference

template<typename T >
using mqtt::topic_matcher< T >::const_reference = const value_type&

◆ value_ptr

template<typename T >
using mqtt::topic_matcher< T >::value_ptr = std::unique_ptr<value_type>

◆ mapped_ptr

template<typename T >
using mqtt::topic_matcher< T >::mapped_ptr = std::unique_ptr<mapped_type>

Constructor & Destructor Documentation

◆ topic_matcher() [1/2]

template<typename T >
mqtt::topic_matcher< T >::topic_matcher ( )
inline

Creates new, empty collection.

◆ topic_matcher() [2/2]

template<typename T >
mqtt::topic_matcher< T >::topic_matcher ( std::initializer_list< value_type lst)
inline

Creates a new collection with a list of key/value pairs.

This can be used to create a connection from a table of entries, as key/value pairs, like:

topic_matcher<int> matcher {
   { "#", -1 },
   { "some/random/topic", 42 },
   { "some/#", 99 }
}
Parameters
lstThe list of key/value pairs to populate the collection.

Member Function Documentation

◆ empty()

template<typename T >
bool mqtt::topic_matcher< T >::empty ( ) const
inline

Determines if the collection is empty.

Returns
true if the collection is empty, false if it contains any filters.

◆ insert() [1/2]

template<typename T >
void mqtt::topic_matcher< T >::insert ( value_type &&  val)
inline

Inserts a new key/value pair into the collection.

Parameters
valThe value to place in the collection.

◆ insert() [2/2]

template<typename T >
void mqtt::topic_matcher< T >::insert ( const value_type val)
inline

Inserts a new value into the collection.

Parameters
keyThe topic/filter entry
valThe value to associate with that entry.

◆ remove()

template<typename T >
mapped_ptr mqtt::topic_matcher< T >::remove ( const key_type filter)
inline

Removes an entry from the collection.

This removes the value from the internal node, but leaves the node in the collection, even if it is empty.

Parameters
filterThe topic filter to remove.
Returns
A unique pointer to the value, if any.

◆ prune()

template<typename T >
void mqtt::topic_matcher< T >::prune ( )
inline

Removes the empty nodes in the collection.

◆ begin()

template<typename T >
iterator mqtt::topic_matcher< T >::begin ( )
inline

Gets an iterator to the full collection of filters.

Returns
An iterator to the full collection of filters.

◆ end() [1/2]

template<typename T >
iterator mqtt::topic_matcher< T >::end ( )
inline

Gets an iterator to the end of the collection of filters.

Returns
An iterator to the end of collection of filters.

◆ end() [2/2]

template<typename T >
const_iterator mqtt::topic_matcher< T >::end ( ) const
inlinenoexcept

Gets an iterator to the end of the collection of filters.

Returns
An iterator to the end of collection of filters.

◆ cbegin()

template<typename T >
const_iterator mqtt::topic_matcher< T >::cbegin ( ) const
inline

Gets a const iterator to the full collection of filters.

Returns
A const iterator to the full collection of filters.

◆ cend()

template<typename T >
const_iterator mqtt::topic_matcher< T >::cend ( ) const
inlinenoexcept

Gets a const iterator to the end of the collection of filters.

Returns
A const iterator to the end of collection of filters.

◆ find() [1/2]

template<typename T >
iterator mqtt::topic_matcher< T >::find ( const key_type filter)
inline

Gets a pointer to the value at the requested key.

Parameters
filterThe topic filter entry to find.
Returns
An iterator to the value if found, end() if not found.

◆ find() [2/2]

template<typename T >
const_iterator mqtt::topic_matcher< T >::find ( const key_type filter) const
inline

Gets a const pointer to the value at the requested key.

Parameters
filterThe topic filter entry to find.
Returns
A const pointer to the value if found, nullptr if not found.

◆ matches() [1/2]

template<typename T >
match_iterator mqtt::topic_matcher< T >::matches ( const string topic)
inline

Gets an match_iterator that can find the matches to the topic.

Parameters
topicThe topic to search for matches.
Returns
An iterator that can find the matches to the topic.

◆ matches() [2/2]

template<typename T >
const_match_iterator mqtt::topic_matcher< T >::matches ( const string topic) const
inline

Gets a const iterator that can find the matches to the topic.

Parameters
topicThe topic to search for matches.
Returns
A const iterator that can find the matches to the topic.

◆ matches_end()

template<typename T >
const_match_iterator mqtt::topic_matcher< T >::matches_end ( ) const
inlinenoexcept

Gets an iterator for the end of the collection.

This simply returns an empty/null iterator which we can use to signal the end of the collection.

Returns
An empty/null iterator indicating the end of the collection.

◆ matches_cend()

template<typename T >
const_match_iterator mqtt::topic_matcher< T >::matches_cend ( ) const
inlinenoexcept

Gets an iterator for the end of the collection.

This simply returns an empty/null iterator which we can use to signal the end of the collection.

Returns
An empty/null iterator indicating the end of the collection.

◆ has_match()

template<typename T >
bool mqtt::topic_matcher< T >::has_match ( const string topic)
inline

Determines if there are any matches for the specified topic.

Parameters
topicThe topic to search for matches.
Returns
Whether there are any matches for the topic in the collection.

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