Loading...
Searching...
No Matches
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:

topic_matcher<int> tm{
{"some/random/topic", 42},
{"some/#", 99},
{"some/+/topic", 33}
};
mqtt::topic_matcher
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

  lst | The 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

  val | The 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

  key | The topic/filter entry
  val | The 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

  filter | The 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

inline noexcept

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

inline noexcept

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

  filter | The 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

  filter | The 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

  topic | The 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

  topic | The 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

inline noexcept

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

inline noexcept

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

  topic | The 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:

- topic_matcher.h