helpers.h File Reference

Go to the source code of this file.

Data Structures
class	esphome::ConstVector< T >
	Lightweight read-only view over a const array stored in RODATA (will typically be in flash memory) Avoids copying data from flash to RAM by keeping a pointer to the flash data. More...
class	esphome::StaticVector< T, N >
	Minimal static vector - saves memory by avoiding std::vector overhead. More...
class	esphome::FixedVector< T >
	Fixed-capacity vector - allocates once at runtime, never reallocates This avoids std::vector template overhead (_M_realloc_insert, _M_default_append) when size is known at initialization but not at compile time. More...
class	esphome::CallbackManager< void(Ts...)>
	Helper class to allow having multiple subscribers to a callback. More...
class	esphome::LazyCallbackManager< void(Ts...)>
	Lazy-allocating callback manager that only allocates memory when callbacks are registered. More...
class	esphome::Deduplicator< T >
	Helper class to deduplicate items in a series of values. More...
class	esphome::Parented< T >
	Helper class to easily give an object a parent of type T. More...
class	esphome::Mutex
	Mutex implementation, with API based on the unavailable std::mutex. More...
class	esphome::LockGuard
	Helper class that wraps a mutex with a RAII-style API. More...
class	esphome::InterruptLock
	Helper class to disable interrupts. More...
class	esphome::LwIPLock
	Helper class to lock the lwIP TCPIP core when making lwIP API calls from non-TCPIP threads. More...
class	esphome::HighFrequencyLoopRequester
	Helper class to request loop() to be called as fast as possible. More...
class	esphome::RAMAllocator< T >
	An STL allocator that uses SPI or internal RAM. More...

Namespaces
namespace	esphome
	Providing packet encoding functions for exchanging data with a remote host.

Concepts
concept	esphome::comparable_with
	Functions to constrain the range of arithmetic values.

Functions
STL backports
template<typename To , typename From , enable_if_t< sizeof(To)==sizeof(From) &&is_trivially_copyable< From >::value &&is_trivially_copyable< To >::value, int > = 0>
To	esphome::bit_cast (const From &src)
	Convert data between types, without aliasing issues or undefined behaviour.
float	esphome::lerp (float completion, float start, float end)=delete
template<typename T >
constexpr T	esphome::byteswap (T n)
template<>
constexpr uint8_t	esphome::byteswap (uint8_t n)
template<>
uint16_t	esphome::byteswap (uint16_t n)
template<>
uint32_t	esphome::byteswap (uint32_t n)
template<>
uint64_t	esphome::byteswap (uint64_t n)
template<>
int8_t	esphome::byteswap (int8_t n)
template<>
int16_t	esphome::byteswap (int16_t n)
template<>
int32_t	esphome::byteswap (int32_t n)
template<>
int64_t	esphome::byteswap (int64_t n)
template<>
constexpr uint16_t	esphome::byteswap (uint16_t n)
template<>
constexpr uint32_t	esphome::byteswap (uint32_t n)
template<>
constexpr uint64_t	esphome::byteswap (uint64_t n)
template<>
constexpr int8_t	esphome::byteswap (int8_t n)
template<>
constexpr int16_t	esphome::byteswap (int16_t n)
template<>
constexpr int32_t	esphome::byteswap (int32_t n)
template<>
constexpr int64_t	esphome::byteswap (int64_t n)
Bit manipulation
constexpr uint16_t	esphome::encode_uint16 (uint8_t msb, uint8_t lsb)
	Encode a 16-bit value given the most and least significant byte.
constexpr uint32_t	esphome::encode_uint24 (uint8_t byte1, uint8_t byte2, uint8_t byte3)
	Encode a 24-bit value given three bytes in most to least significant byte order.
constexpr uint32_t	esphome::encode_uint32 (uint8_t byte1, uint8_t byte2, uint8_t byte3, uint8_t byte4)
	Encode a 32-bit value given four bytes in most to least significant byte order.
template<typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
constexpr T	esphome::encode_value (const uint8_t *bytes)
	Encode a value from its constituent bytes (from most to least significant) in an array with length sizeof(T).
template<typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
constexpr T	esphome::encode_value (const std::array< uint8_t, sizeof(T)> bytes)
	Encode a value from its constituent bytes (from most to least significant) in an std::array with length sizeof(T).
template<typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
constexpr std::array< uint8_t, sizeof(T)>	esphome::decode_value (T val)
	Decode a value into its constituent bytes (from most to least significant).
uint8_t	esphome::reverse_bits (uint8_t x)
	Reverse the order of 8 bits.
uint16_t	esphome::reverse_bits (uint16_t x)
	Reverse the order of 16 bits.
uint32_t	esphome::reverse_bits (uint32_t x)
	Reverse the order of 32 bits.
template<typename T >
constexpr T	esphome::convert_big_endian (T val)
	Convert a value between host byte order and big endian (most significant byte first) order.
template<typename T >
constexpr T	esphome::convert_little_endian (T val)
	Convert a value between host byte order and little endian (least significant byte first) order.
Colors
float	esphome::gamma_correct (float value, float gamma)
	Applies gamma correction of gamma to value.
float	esphome::gamma_uncorrect (float value, float gamma)
	Reverts gamma correction of gamma to value.
void	esphome::rgb_to_hsv (float red, float green, float blue, int &hue, float &saturation, float &value)
	Convert red, green and blue (all 0-1) values to hue (0-360), saturation (0-1) and value (0-1).
void	esphome::hsv_to_rgb (int hue, float saturation, float value, float &red, float &green, float &blue)
	Convert hue (0-360), saturation (0-1) and value (0-1) to red, green and blue (all 0-1).
Units
constexpr float	esphome::celsius_to_fahrenheit (float value)
	Convert degrees Celsius to degrees Fahrenheit.
constexpr float	esphome::fahrenheit_to_celsius (float value)
	Convert degrees Fahrenheit to degrees Celsius.
System APIs
void	esphome::get_mac_address_raw (uint8_t *mac)
	Get the device MAC address as raw bytes, written into the provided byte array (6 bytes).
std::string	esphome::get_mac_address ()
	Get the device MAC address as a string, in lowercase hex notation.
std::string	esphome::get_mac_address_pretty ()
	Get the device MAC address as a string, in colon-separated uppercase hex notation.
void	esphome::get_mac_address_into_buffer (std::span< char, MAC_ADDRESS_BUFFER_SIZE > buf)
	Get the device MAC address into the given buffer, in lowercase hex notation.
const char *	esphome::get_mac_address_pretty_into_buffer (std::span< char, MAC_ADDRESS_PRETTY_BUFFER_SIZE > buf)
	Get the device MAC address into the given buffer, in colon-separated uppercase hex notation.
void	esphome::set_mac_address (uint8_t *mac)
	Set the MAC address to use from the provided byte array (6 bytes).
bool	esphome::has_custom_mac_address ()
	Check if a custom MAC address is set (ESP32 & variants)
bool	esphome::mac_address_is_valid (const uint8_t *mac)
	Check if the MAC address is not all zeros or all ones.
void IRAM_ATTR HOT	esphome::delay_microseconds_safe (uint32_t us)
	Delay for the given amount of microseconds, possibly yielding to other processes during the wait.
Internal functions
template<typename T , enable_if_t<!std::is_pointer< T >::value, int > = 0>
T	esphome::id (T value)
	Helper function to make id(var) known from lambdas work in custom components.
template<typename T , enable_if_t< std::is_pointer< T * >::value, int > = 0>
T &	esphome::id (T *value)
	Helper function to make id(var) known from lambdas work in custom components.

Parsing & formatting
enum	esphome::ParseOnOffState : uint8_t { esphome::PARSE_NONE = 0 , esphome::PARSE_ON , esphome::PARSE_OFF , esphome::PARSE_TOGGLE }
	Return values for parse_on_off(). More...
template<typename T , enable_if_t<(std::is_integral< T >::value &&std::is_unsigned< T >::value), int > = 0>
optional< T >	esphome::parse_number (const char *str)
	Parse an unsigned decimal number from a null-terminated string.
template<typename T , enable_if_t<(std::is_integral< T >::value &&std::is_unsigned< T >::value), int > = 0>
optional< T >	esphome::parse_number (const std::string &str)
	Parse an unsigned decimal number.
size_t	esphome::parse_hex (const char *str, size_t len, uint8_t *data, size_t count)
	Parse bytes from a hex-encoded string into a byte array.
bool	esphome::parse_hex (const char *str, uint8_t *data, size_t count)
	Parse count bytes from the hex-encoded string str of at least 2*count characters into array data.
bool	esphome::parse_hex (const std::string &str, uint8_t *data, size_t count)
	Parse count bytes from the hex-encoded string str of at least 2*count characters into array data.
bool	esphome::parse_hex (const char *str, std::vector< uint8_t > &data, size_t count)
	Parse count bytes from the hex-encoded string str of at least 2*count characters into vector data.
bool	esphome::parse_hex (const std::string &str, std::vector< uint8_t > &data, size_t count)
	Parse count bytes from the hex-encoded string str of at least 2*count characters into vector data.
template<typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
optional< T >	esphome::parse_hex (const char *str, size_t len)
	Parse a hex-encoded string into an unsigned integer.
template<typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
optional< T >	esphome::parse_hex (const char *str)
	Parse a hex-encoded null-terminated string (starting with the most significant byte) into an unsigned integer.
template<typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
optional< T >	esphome::parse_hex (const std::string &str)
	Parse a hex-encoded null-terminated string (starting with the most significant byte) into an unsigned integer.
constexpr uint8_t	esphome::parse_hex_char (char c)
	Parse a hex character to its nibble value (0-15), returns 255 on invalid input.
char	esphome::format_hex_char (uint8_t v, char base)
	Convert a nibble (0-15) to hex char with specified base ('a' for lowercase, 'A' for uppercase)
char	esphome::format_hex_char (uint8_t v)
	Convert a nibble (0-15) to lowercase hex char.
char	esphome::format_hex_pretty_char (uint8_t v)
	Convert a nibble (0-15) to uppercase hex char (used for pretty printing)
char *	esphome::int8_to_str (char *buf, int8_t val)
	Write int8 value to buffer without modulo operations.
char *	esphome::format_hex_to (char *buffer, size_t buffer_size, const uint8_t *data, size_t length)
	Format byte array as lowercase hex to buffer (base implementation).
template<size_t N>
char *	esphome::format_hex_to (char(&buffer)[N], const uint8_t *data, size_t length)
	Format byte array as lowercase hex to buffer.
template<size_t N, typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
char *	esphome::format_hex_to (char(&buffer)[N], T val)
	Format an unsigned integer in lowercased hex to buffer, starting with the most significant byte.
constexpr size_t	esphome::format_hex_size (size_t byte_count)
	Calculate buffer size needed for format_hex_to: "XXXXXXXX...\0" = bytes * 2 + 1.
constexpr size_t	esphome::format_hex_pretty_size (size_t byte_count)
	Calculate buffer size needed for format_hex_pretty_to with separator: "XX:XX:...:XX\0".
char *	esphome::format_hex_pretty_to (char *buffer, size_t buffer_size, const uint8_t *data, size_t length, char separator=':')
	Format byte array as uppercase hex to buffer (base implementation).
template<size_t N>
char *	esphome::format_hex_pretty_to (char(&buffer)[N], const uint8_t *data, size_t length, char separator=':')
	Format byte array as uppercase hex with separator to buffer. Automatically deduces buffer size.
void	esphome::format_mac_addr_upper (const uint8_t *mac, char *output)
	Format MAC address as XX:XX:XX:XX:XX:XX (uppercase, colon separators)
void	esphome::format_mac_addr_lower_no_sep (const uint8_t *mac, char *output)
	Format MAC address as xxxxxxxxxxxxxx (lowercase, no separators)
std::string	esphome::format_mac_address_pretty (const uint8_t mac[6])
	Format the six-byte array mac into a MAC address.
std::string	esphome::format_hex (const uint8_t *data, size_t length)
	Format the byte array data of length len in lowercased hex.
std::string	esphome::format_hex (const std::vector< uint8_t > &data)
	Format the vector data in lowercased hex.
template<typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
std::string	esphome::format_hex (T val)
	Format an unsigned integer in lowercased hex, starting with the most significant byte.
template<std::size_t N>
std::string	esphome::format_hex (const std::array< uint8_t, N > &data)
std::string	esphome::format_hex_pretty (const uint8_t *data, size_t length, char separator='.', bool show_length=true)
	Format a byte array in pretty-printed, human-readable hex format.
std::string	esphome::format_hex_pretty (const uint16_t *data, size_t length, char separator='.', bool show_length=true)
	Format a 16-bit word array in pretty-printed, human-readable hex format.
std::string	esphome::format_hex_pretty (const std::vector< uint8_t > &data, char separator='.', bool show_length=true)
	Format a byte vector in pretty-printed, human-readable hex format.
std::string	esphome::format_hex_pretty (const std::vector< uint16_t > &data, char separator='.', bool show_length=true)
	Format a 16-bit word vector in pretty-printed, human-readable hex format.
std::string	esphome::format_hex_pretty (const std::string &data, char separator='.', bool show_length=true)
	Format a string's bytes in pretty-printed, human-readable hex format.
template<typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
std::string	esphome::format_hex_pretty (T val, char separator='.', bool show_length=true)
	Format an unsigned integer in pretty-printed, human-readable hex format.
std::string	esphome::format_bin (const uint8_t *data, size_t length)
	Format the byte array data of length len in binary.
template<typename T , enable_if_t< std::is_unsigned< T >::value, int > = 0>
std::string	esphome::format_bin (T val)
	Format an unsigned integer in binary, starting with the most significant byte.
ParseOnOffState	esphome::parse_on_off (const char *str, const char *on=nullptr, const char *off=nullptr)
	Parse a string that contains either on, off or toggle.
std::string	esphome::value_accuracy_to_string (float value, int8_t accuracy_decimals)
	Create a string from a value and an accuracy in decimals.
size_t	esphome::value_accuracy_to_buf (std::span< char, VALUE_ACCURACY_MAX_LEN > buf, float value, int8_t accuracy_decimals)
	Format value with accuracy to buffer, returns chars written (excluding null)
size_t	esphome::value_accuracy_with_uom_to_buf (std::span< char, VALUE_ACCURACY_MAX_LEN > buf, float value, int8_t accuracy_decimals, StringRef unit_of_measurement)
	Format value with accuracy and UOM to buffer, returns chars written (excluding null)
int8_t	esphome::step_to_accuracy_decimals (float step)
	Derive accuracy in decimals from an increment step.
std::string	esphome::base64_encode (const uint8_t *buf, size_t buf_len)
std::string	esphome::base64_encode (const std::vector< uint8_t > &buf)
std::vector< uint8_t >	esphome::base64_decode (const std::string &encoded_string)
size_t	esphome::base64_decode (const std::string &encoded_string, uint8_t *buf, size_t buf_len)
size_t	esphome::base64_decode (const uint8_t *encoded_data, size_t encoded_len, uint8_t *buf, size_t buf_len)

Memory management
template<class T >
using	esphome::ExternalRAMAllocator = RAMAllocator<T>
template<std::totally_ordered T, comparable_with< T > U>
T	esphome::clamp_at_least (T value, U min)
template<std::totally_ordered T, comparable_with< T > U>
T	esphome::clamp_at_most (T value, U max)

Mathematics
constexpr uint32_t	esphome::FNV1_OFFSET_BASIS = 2166136261UL
	FNV-1 32-bit offset basis.
constexpr uint32_t	esphome::FNV1_PRIME = 16777619UL
	FNV-1 32-bit prime.
template<typename T , typename U >
T	esphome::remap (U value, U min, U max, T min_out, T max_out)
	Remap value from the range (min, max) to (min_out, max_out).
uint8_t	esphome::crc8 (const uint8_t *data, uint8_t len, uint8_t crc=0x00, uint8_t poly=0x8C, bool msb_first=false)
	Calculate a CRC-8 checksum of data with size len.
uint16_t	esphome::crc16 (const uint8_t *data, uint16_t len, uint16_t crc=0xffff, uint16_t reverse_poly=0xa001, bool refin=false, bool refout=false)
	Calculate a CRC-16 checksum of data with size len.
uint16_t	esphome::crc16be (const uint8_t *data, uint16_t len, uint16_t crc, uint16_t poly, bool refin, bool refout)
uint32_t	esphome::fnv1_hash (const char *str)
	Calculate a FNV-1 hash of str.
uint32_t	esphome::fnv1_hash (const std::string &str)
constexpr uint32_t	esphome::fnv1a_hash_extend (uint32_t hash, const char *str)
	Extend a FNV-1a hash with additional string data.
uint32_t	esphome::fnv1a_hash_extend (uint32_t hash, const std::string &str)
constexpr uint32_t	esphome::fnv1a_hash (const char *str)
	Calculate a FNV-1a hash of str.
uint32_t	esphome::fnv1a_hash (const std::string &str)
uint32_t	esphome::random_uint32 ()
	Return a random 32-bit unsigned integer.
float	esphome::random_float ()
	Return a random float between 0 and 1.
bool	esphome::random_bytes (uint8_t *data, size_t len)
	Generate len number of random bytes.

Strings
std::string size_t	esphome::len
bool	esphome::str_equals_case_insensitive (const std::string &a, const std::string &b)
	Compare strings for equality in case-insensitive manner.
bool	esphome::str_startswith (const std::string &str, const std::string &start)
	Check whether a string starts with a value.
bool	esphome::str_endswith (const std::string &str, const std::string &end)
	Check whether a string ends with a value.
std::string	esphome::str_truncate (const std::string &str, size_t length)
	Truncate a string to a specific length.
std::string	esphome::str_until (const char *str, char ch)
	Extract the part of the string until either the first occurrence of the specified character, or the end (requires str to be null-terminated).
std::string	esphome::str_until (const std::string &str, char ch)
	Extract the part of the string until either the first occurrence of the specified character, or the end.
std::string	esphome::str_lower_case (const std::string &str)
	Convert the string to lower case.
std::string	esphome::str_upper_case (const std::string &str)
	Convert the string to upper case.
constexpr char	esphome::to_snake_case_char (char c)
	Convert a single char to snake_case: lowercase and space to underscore.
std::string	esphome::str_snake_case (const std::string &str)
	Convert the string to snake case (lowercase with underscores).
constexpr char	esphome::to_sanitized_char (char c)
	Sanitize a single char: keep alphanumerics, dashes, underscores; replace others with underscore.
std::string	esphome::str_sanitize (const std::string &str)
	Sanitizes the input string by removing all characters but alphanumerics, dashes and underscores.
std::string	esphome::__attribute__ ((format(printf, 1, 3))) str_snprintf(const char *fmt
	snprintf-like function returning std::string of maximum length len (excluding null terminator).
std::string size_t std::string	esphome::__attribute__ ((format(printf, 1, 2))) str_sprintf(const char *fmt
	sprintf-like function returning std::string.
std::string	esphome::make_name_with_suffix (const std::string &name, char sep, const char *suffix_ptr, size_t suffix_len)
	Concatenate a name with a separator and suffix using an efficient stack-based approach.
std::string	esphome::make_name_with_suffix (const char *name, size_t name_len, char sep, const char *suffix_ptr, size_t suffix_len)
	Optimized string concatenation: name + separator + suffix (const char* overload) Uses a fixed stack buffer to avoid heap allocations.
size_t	esphome::make_name_with_suffix_to (char *buffer, size_t buffer_size, const char *name, size_t name_len, char sep, const char *suffix_ptr, size_t suffix_len)
	Zero-allocation version: format name + separator + suffix directly into buffer.