esphome::text_sensor::MapFilter< N > Class Template Reference

A filter that maps values from one set to another. More...

#include <filter.h>

Inheritance diagram for esphome::text_sensor::MapFilter< N >:

Public Member Functions
	MapFilter (const std::initializer_list< Substitution > &mappings)
bool	new_value (std::string &value) override
Public Member Functions inherited from esphome::text_sensor::Filter
virtual void	initialize (TextSensor *parent, Filter *next)
	Initialize this filter, please note this can be called more than once.
void	input (std::string value)
void	output (std::string &value)

Protected Attributes
std::array< Substitution, N >	mappings_ {}
Protected Attributes inherited from esphome::text_sensor::Filter
friend	TextSensor
Filter *	next_ {nullptr}
TextSensor *	parent_ {nullptr}

Detailed Description

template<size_t N>
class esphome::text_sensor::MapFilter< N >

A filter that maps values from one set to another.

Uses linear search instead of std::map for typical small datasets (2-20 mappings). Linear search on contiguous memory is faster than red-black tree lookups when:

• Dataset is small (< ~30 items)
• Memory is contiguous (cache-friendly, better CPU cache utilization)
• No pointer chasing overhead (tree node traversal)
• String comparison cost dominates lookup time

Benchmark results (see benchmark_map_filter.cpp):

• 2 mappings: Linear 1.26x faster than std::map
• 5 mappings: Linear 2.25x faster than std::map
• 10 mappings: Linear 1.83x faster than std::map
• 20 mappings: Linear 1.59x faster than std::map
• 30 mappings: Linear 1.09x faster than std::map
• 40 mappings: std::map 1.27x faster than Linear (break-even)

Benefits over std::map:

• ~2KB smaller flash (no red-black tree code)
• ~24-32 bytes less RAM per mapping (no tree node overhead)
• Faster for typical ESPHome usage (2-10 mappings common, 20+ rare)

Break-even point: ~35-40 mappings, but ESPHome configs rarely exceed 20

N is set by code generation to match the exact number of mappings configured in YAML.

Definition at line 171 of file filter.h.

Constructor & Destructor Documentation

MapFilter()

template<size_t N>

esphome::text_sensor::MapFilter< N >::MapFilter ( const std::initializer_list< Substitution > & mappings )

inlineexplicit

Definition at line 173 of file filter.h.

Member Function Documentation

new_value()

template<size_t N>

bool esphome::text_sensor::MapFilter< N >::new_value ( std::string & value )

inlineoverridevirtual

Implements esphome::text_sensor::Filter.

Definition at line 176 of file filter.h.

Field Documentation

mappings_

template<size_t N>

std::array<Substitution, N> esphome::text_sensor::MapFilter< N >::mappings_ {}

protected

Definition at line 179 of file filter.h.

---

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

• esphome/components/text_sensor/filter.h