helpers.h

Go to the documentation of this file.

#pragma once
 
#include <array>
#include <cmath>
#include <cstdint>
#include <cstring>
#include <functional>
#include <iterator>
#include <limits>
#include <memory>
#include <span>
#include <string>
#include <type_traits>
#include <vector>
#include <concepts>
 
#include "esphome/core/optional.h"
 
#ifdef USE_ESP8266
#include <Esp.h>
#endif
 
#ifdef USE_RP2040
#include <Arduino.h>
#endif
 
#ifdef USE_ESP32
#include <esp_heap_caps.h>
#endif
 
#if defined(USE_ESP32)
#include <freertos/FreeRTOS.h>
#include <freertos/semphr.h>
#elif defined(USE_LIBRETINY)
#include <FreeRTOS.h>
#include <semphr.h>
#endif
 
#ifdef USE_HOST
#include <mutex>
#endif
 
#define HOT __attribute__((hot))
#define ESPDEPRECATED(msg, when) __attribute__((deprecated(msg)))
#define ESPHOME_ALWAYS_INLINE __attribute__((always_inline))
#define PACKED __attribute__((packed))
 
namespace esphome {
 
// Forward declaration to avoid circular dependency with string_ref.h
class StringRef;
 
 
// Keep "using" even after the removal of our backports, to avoid breaking existing code.
using std::to_string;
using std::is_trivially_copyable;
using std::make_unique;
using std::enable_if_t;
using std::clamp;
using std::is_invocable;
#if __cpp_lib_bit_cast >= 201806
using std::bit_cast;
#else
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 bit_cast(const From &src) {
  To dst;
  memcpy(&dst, &src, sizeof(To));
  return dst;
}
#endif
 
// clang-format off
inline float lerp(float completion, float start, float end) = delete;  // Please use std::lerp. Notice that it has different order on arguments!
// clang-format on
 
// std::byteswap from C++23
template<typename T> constexpr T byteswap(T n) {
  T m;
  for (size_t i = 0; i < sizeof(T); i++)
    reinterpret_cast<uint8_t *>(&m)[i] = reinterpret_cast<uint8_t *>(&n)[sizeof(T) - 1 - i];
  return m;
}
template<> constexpr uint8_t byteswap(uint8_t n) { return n; }
#ifdef USE_LIBRETINY
// LibreTiny's Beken framework redefines __builtin_bswap functions as non-constexpr
template<> inline uint16_t byteswap(uint16_t n) { return __builtin_bswap16(n); }
template<> inline uint32_t byteswap(uint32_t n) { return __builtin_bswap32(n); }
template<> inline uint64_t byteswap(uint64_t n) { return __builtin_bswap64(n); }
template<> inline int8_t byteswap(int8_t n) { return n; }
template<> inline int16_t byteswap(int16_t n) { return __builtin_bswap16(n); }
template<> inline int32_t byteswap(int32_t n) { return __builtin_bswap32(n); }
template<> inline int64_t byteswap(int64_t n) { return __builtin_bswap64(n); }
#else
template<> constexpr uint16_t byteswap(uint16_t n) { return __builtin_bswap16(n); }
template<> constexpr uint32_t byteswap(uint32_t n) { return __builtin_bswap32(n); }
template<> constexpr uint64_t byteswap(uint64_t n) { return __builtin_bswap64(n); }
template<> constexpr int8_t byteswap(int8_t n) { return n; }
template<> constexpr int16_t byteswap(int16_t n) { return __builtin_bswap16(n); }
template<> constexpr int32_t byteswap(int32_t n) { return __builtin_bswap32(n); }
template<> constexpr int64_t byteswap(int64_t n) { return __builtin_bswap64(n); }
#endif
 
 
 
 
template<typename T> class ConstVector {
 public:
  constexpr ConstVector(const T *data, size_t size) : data_(data), size_(size) {}
 
  const constexpr T &operator[](size_t i) const { return data_[i]; }
  constexpr size_t size() const { return size_; }
  constexpr bool empty() const { return size_ == 0; }
 
 protected:
  const T *data_;
  size_t size_;
};
 
template<typename T, size_t N> class StaticVector {
 public:
  using value_type = T;
  using iterator = typename std::array<T, N>::iterator;
  using const_iterator = typename std::array<T, N>::const_iterator;
  using reverse_iterator = std::reverse_iterator<iterator>;
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
 
 private:
  std::array<T, N> data_{};
  size_t count_{0};
 
 public:
  // Minimal vector-compatible interface - only what we actually use
  void push_back(const T &value) {
    if (count_ < N) {
      data_[count_++] = value;
    }
  }
 
  // Return reference to next element and increment count (with bounds checking)
  T &emplace_next() {
    if (count_ >= N) {
      // Should never happen with proper size calculation
      // Return reference to last element to avoid crash
      return data_[N - 1];
    }
    return data_[count_++];
  }
 
  size_t size() const { return count_; }
  bool empty() const { return count_ == 0; }
 
  // Direct access to underlying data
  T *data() { return data_.data(); }
  const T *data() const { return data_.data(); }
 
  T &operator[](size_t i) { return data_[i]; }
  const T &operator[](size_t i) const { return data_[i]; }
 
  // For range-based for loops
  iterator begin() { return data_.begin(); }
  iterator end() { return data_.begin() + count_; }
  const_iterator begin() const { return data_.begin(); }
  const_iterator end() const { return data_.begin() + count_; }
 
  // Reverse iterators
  reverse_iterator rbegin() { return reverse_iterator(end()); }
  reverse_iterator rend() { return reverse_iterator(begin()); }
  const_reverse_iterator rbegin() const { return const_reverse_iterator(end()); }
  const_reverse_iterator rend() const { return const_reverse_iterator(begin()); }
};
 
template<typename T> class FixedVector {
 private:
  T *data_{nullptr};
  size_t size_{0};
  size_t capacity_{0};
 
  // Helper to destroy all elements without freeing memory
  void destroy_elements_() {
    // Only call destructors for non-trivially destructible types
    if constexpr (!std::is_trivially_destructible<T>::value) {
      for (size_t i = 0; i < size_; i++) {
        data_[i].~T();
      }
    }
  }
 
  // Helper to destroy elements and free memory
  void cleanup_() {
    if (data_ != nullptr) {
      destroy_elements_();
      // Free raw memory
      ::operator delete(data_);
    }
  }
 
  // Helper to reset pointers after cleanup
  void reset_() {
    data_ = nullptr;
    capacity_ = 0;
    size_ = 0;
  }
 
  // Helper to assign from initializer list (shared by constructor and assignment operator)
  void assign_from_initializer_list_(std::initializer_list<T> init_list) {
    init(init_list.size());
    size_t idx = 0;
    for (const auto &item : init_list) {
      new (data_ + idx) T(item);
      ++idx;
    }
    size_ = init_list.size();
  }
 
 public:
  FixedVector() = default;
 
  FixedVector(std::initializer_list<T> init_list) { assign_from_initializer_list_(init_list); }
 
  ~FixedVector() { cleanup_(); }
 
  // Disable copy operations (avoid accidental expensive copies)
  FixedVector(const FixedVector &) = delete;
  FixedVector &operator=(const FixedVector &) = delete;
 
  // Enable move semantics (allows use in move-only containers like std::vector)
  FixedVector(FixedVector &&other) noexcept : data_(other.data_), size_(other.size_), capacity_(other.capacity_) {
    other.reset_();
  }
 
  // Allow conversion to std::vector
  operator std::vector<T>() const { return {data_, data_ + size_}; }
 
  FixedVector &operator=(FixedVector &&other) noexcept {
    if (this != &other) {
      // Delete our current data
      cleanup_();
      // Take ownership of other's data
      data_ = other.data_;
      size_ = other.size_;
      capacity_ = other.capacity_;
      // Leave other in valid empty state
      other.reset_();
    }
    return *this;
  }
 
  FixedVector &operator=(std::initializer_list<T> init_list) {
    cleanup_();
    reset_();
    assign_from_initializer_list_(init_list);
    return *this;
  }
 
  // Allocate capacity - can be called multiple times to reinit
  // IMPORTANT: After calling init(), you MUST use push_back() to add elements.
  // Direct assignment via operator[] does NOT update the size counter.
  void init(size_t n) {
    cleanup_();
    reset_();
    if (n > 0) {
      // Allocate raw memory without calling constructors
      // sizeof(T) is correct here for any type T (value types, pointers, etc.)
      // NOLINTNEXTLINE(bugprone-sizeof-expression)
      data_ = static_cast<T *>(::operator new(n * sizeof(T)));
      capacity_ = n;
    }
  }
 
  // Clear the vector (destroy all elements, reset size to 0, keep capacity)
  void clear() {
    destroy_elements_();
    size_ = 0;
  }
 
  // Release all memory (destroys elements and frees memory)
  void release() {
    cleanup_();
    reset_();
  }
 
  void push_back(const T &value) {
    if (size_ < capacity_) {
      // Use placement new to construct the object in pre-allocated memory
      new (&data_[size_]) T(value);
      size_++;
    }
  }
 
  void push_back(T &&value) {
    if (size_ < capacity_) {
      // Use placement new to move-construct the object in pre-allocated memory
      new (&data_[size_]) T(std::move(value));
      size_++;
    }
  }
 
  template<typename... Args> T &emplace_back(Args &&...args) {
    // Use placement new to construct the object in pre-allocated memory
    new (&data_[size_]) T(std::forward<Args>(args)...);
    size_++;
    return data_[size_ - 1];
  }
 
  T &front() { return data_[0]; }
  const T &front() const { return data_[0]; }
 
  T &back() { return data_[size_ - 1]; }
  const T &back() const { return data_[size_ - 1]; }
 
  size_t size() const { return size_; }
  bool empty() const { return size_ == 0; }
 
  T &operator[](size_t i) { return data_[i]; }
  const T &operator[](size_t i) const { return data_[i]; }
 
  T &at(size_t i) { return data_[i]; }
  const T &at(size_t i) const { return data_[i]; }
 
  // Iterator support for range-based for loops
  T *begin() { return data_; }
  T *end() { return data_ + size_; }
  const T *begin() const { return data_; }
  const T *end() const { return data_ + size_; }
};
 
template<size_t STACK_SIZE> class SmallBufferWithHeapFallback {
 public:
  explicit SmallBufferWithHeapFallback(size_t size) {
    if (size <= STACK_SIZE) {
      this->buffer_ = this->stack_buffer_;
    } else {
      this->heap_buffer_ = new uint8_t[size];
      this->buffer_ = this->heap_buffer_;
    }
  }
  ~SmallBufferWithHeapFallback() { delete[] this->heap_buffer_; }
 
  // Delete copy and move operations to prevent double-delete
  SmallBufferWithHeapFallback(const SmallBufferWithHeapFallback &) = delete;
  SmallBufferWithHeapFallback &operator=(const SmallBufferWithHeapFallback &) = delete;
  SmallBufferWithHeapFallback(SmallBufferWithHeapFallback &&) = delete;
  SmallBufferWithHeapFallback &operator=(SmallBufferWithHeapFallback &&) = delete;
 
  uint8_t *get() { return this->buffer_; }
 
 private:
  uint8_t stack_buffer_[STACK_SIZE];
  uint8_t *heap_buffer_{nullptr};
  uint8_t *buffer_;
};
 
 
 
template<typename T, typename U> T remap(U value, U min, U max, T min_out, T max_out) {
  return (value - min) * (max_out - min_out) / (max - min) + min_out;
}
 
uint8_t crc8(const uint8_t *data, uint8_t len, uint8_t crc = 0x00, uint8_t poly = 0x8C, bool msb_first = false);
 
uint16_t crc16(const uint8_t *data, uint16_t len, uint16_t crc = 0xffff, uint16_t reverse_poly = 0xa001,
               bool refin = false, bool refout = false);
uint16_t crc16be(const uint8_t *data, uint16_t len, uint16_t crc = 0, uint16_t poly = 0x1021, bool refin = false,
                 bool refout = false);
 
uint32_t fnv1_hash(const char *str);
inline uint32_t fnv1_hash(const std::string &str) { return fnv1_hash(str.c_str()); }
 
constexpr uint32_t FNV1_OFFSET_BASIS = 2166136261UL;
constexpr uint32_t FNV1_PRIME = 16777619UL;
 
constexpr uint32_t fnv1a_hash_extend(uint32_t hash, const char *str) {
  if (str) {
    while (*str) {
      hash ^= *str++;
      hash *= FNV1_PRIME;
    }
  }
  return hash;
}
inline uint32_t fnv1a_hash_extend(uint32_t hash, const std::string &str) {
  return fnv1a_hash_extend(hash, str.c_str());
}
template<std::integral T> constexpr uint32_t fnv1a_hash_extend(uint32_t hash, T value) {
  using UnsignedT = std::make_unsigned_t<T>;
  UnsignedT uvalue = static_cast<UnsignedT>(value);
  for (size_t i = 0; i < sizeof(T); i++) {
    hash ^= (uvalue >> (i * 8)) & 0xFF;
    hash *= FNV1_PRIME;
  }
  return hash;
}
constexpr uint32_t fnv1a_hash(const char *str) { return fnv1a_hash_extend(FNV1_OFFSET_BASIS, str); }
inline uint32_t fnv1a_hash(const std::string &str) { return fnv1a_hash(str.c_str()); }
 
uint32_t random_uint32();
float random_float();
bool random_bytes(uint8_t *data, size_t len);
 
 
 
constexpr uint16_t encode_uint16(uint8_t msb, uint8_t lsb) {
  return (static_cast<uint16_t>(msb) << 8) | (static_cast<uint16_t>(lsb));
}
constexpr uint32_t encode_uint24(uint8_t byte1, uint8_t byte2, uint8_t byte3) {
  return (static_cast<uint32_t>(byte1) << 16) | (static_cast<uint32_t>(byte2) << 8) | (static_cast<uint32_t>(byte3));
}
constexpr uint32_t encode_uint32(uint8_t byte1, uint8_t byte2, uint8_t byte3, uint8_t byte4) {
  return (static_cast<uint32_t>(byte1) << 24) | (static_cast<uint32_t>(byte2) << 16) |
         (static_cast<uint32_t>(byte3) << 8) | (static_cast<uint32_t>(byte4));
}
 
template<typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0> constexpr T encode_value(const uint8_t *bytes) {
  T val = 0;
  for (size_t i = 0; i < sizeof(T); i++) {
    val <<= 8;
    val |= bytes[i];
  }
  return val;
}
template<typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0>
constexpr T encode_value(const std::array<uint8_t, sizeof(T)> bytes) {
  return encode_value<T>(bytes.data());
}
template<typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0>
constexpr std::array<uint8_t, sizeof(T)> decode_value(T val) {
  std::array<uint8_t, sizeof(T)> ret{};
  for (size_t i = sizeof(T); i > 0; i--) {
    ret[i - 1] = val & 0xFF;
    val >>= 8;
  }
  return ret;
}
 
inline uint8_t reverse_bits(uint8_t x) {
  x = ((x & 0xAA) >> 1) | ((x & 0x55) << 1);
  x = ((x & 0xCC) >> 2) | ((x & 0x33) << 2);
  x = ((x & 0xF0) >> 4) | ((x & 0x0F) << 4);
  return x;
}
inline uint16_t reverse_bits(uint16_t x) {
  return (reverse_bits(static_cast<uint8_t>(x & 0xFF)) << 8) | reverse_bits(static_cast<uint8_t>((x >> 8) & 0xFF));
}
inline uint32_t reverse_bits(uint32_t x) {
  return (reverse_bits(static_cast<uint16_t>(x & 0xFFFF)) << 16) |
         reverse_bits(static_cast<uint16_t>((x >> 16) & 0xFFFF));
}
 
template<typename T> constexpr T convert_big_endian(T val) {
#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
  return byteswap(val);
#else
  return val;
#endif
}
 
template<typename T> constexpr T convert_little_endian(T val) {
#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
  return val;
#else
  return byteswap(val);
#endif
}
 
 
 
bool str_equals_case_insensitive(const std::string &a, const std::string &b);
bool str_equals_case_insensitive(StringRef a, StringRef b);
 
bool str_startswith(const std::string &str, const std::string &start);
bool str_endswith(const std::string &str, const std::string &end);
 
std::string str_truncate(const std::string &str, size_t length);
 
std::string str_until(const char *str, char ch);
std::string str_until(const std::string &str, char ch);
 
std::string str_lower_case(const std::string &str);
std::string str_upper_case(const std::string &str);
 
constexpr char to_snake_case_char(char c) { return (c == ' ') ? '_' : (c >= 'A' && c <= 'Z') ? c + ('a' - 'A') : c; }
std::string str_snake_case(const std::string &str);
 
constexpr char to_sanitized_char(char c) {
  return (c == '-' || c == '_' || (c >= '0' && c <= '9') || (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')) ? c : '_';
}
std::string str_sanitize(const std::string &str);
 
inline uint32_t fnv1_hash_object_id(const char *str, size_t len) {
  uint32_t hash = FNV1_OFFSET_BASIS;
  for (size_t i = 0; i < len; i++) {
    hash *= FNV1_PRIME;
    // Apply snake_case (space->underscore, uppercase->lowercase) then sanitize
    hash ^= static_cast<uint8_t>(to_sanitized_char(to_snake_case_char(str[i])));
  }
  return hash;
}
 
std::string __attribute__((format(printf, 1, 3))) str_snprintf(const char *fmt, size_t len, ...);
 
std::string __attribute__((format(printf, 1, 2))) str_sprintf(const char *fmt, ...);
 
std::string make_name_with_suffix(const std::string &name, char sep, const char *suffix_ptr, size_t suffix_len);
 
std::string make_name_with_suffix(const char *name, size_t name_len, char sep, const char *suffix_ptr,
                                  size_t suffix_len);
 
size_t 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);
 
 
 
template<typename T, enable_if_t<(std::is_integral<T>::value && std::is_unsigned<T>::value), int> = 0>
optional<T> parse_number(const char *str) {
  char *end = nullptr;
  unsigned long value = ::strtoul(str, &end, 10);  // NOLINT(google-runtime-int)
  if (end == str || *end != '\0' || value > std::numeric_limits<T>::max())
    return {};
  return value;
}
template<typename T, enable_if_t<(std::is_integral<T>::value && std::is_unsigned<T>::value), int> = 0>
optional<T> parse_number(const std::string &str) {
  return parse_number<T>(str.c_str());
}
template<typename T, enable_if_t<(std::is_integral<T>::value && std::is_signed<T>::value), int> = 0>
optional<T> parse_number(const char *str) {
  char *end = nullptr;
  signed long value = ::strtol(str, &end, 10);  // NOLINT(google-runtime-int)
  if (end == str || *end != '\0' || value < std::numeric_limits<T>::min() || value > std::numeric_limits<T>::max())
    return {};
  return value;
}
template<typename T, enable_if_t<(std::is_integral<T>::value && std::is_signed<T>::value), int> = 0>
optional<T> parse_number(const std::string &str) {
  return parse_number<T>(str.c_str());
}
template<typename T, enable_if_t<(std::is_same<T, float>::value), int> = 0> optional<T> parse_number(const char *str) {
  char *end = nullptr;
  float value = ::strtof(str, &end);
  if (end == str || *end != '\0' || value == HUGE_VALF)
    return {};
  return value;
}
template<typename T, enable_if_t<(std::is_same<T, float>::value), int> = 0>
optional<T> parse_number(const std::string &str) {
  return parse_number<T>(str.c_str());
}
 
size_t parse_hex(const char *str, size_t len, uint8_t *data, size_t count);
inline bool parse_hex(const char *str, uint8_t *data, size_t count) {
  return parse_hex(str, strlen(str), data, count) == 2 * count;
}
inline bool parse_hex(const std::string &str, uint8_t *data, size_t count) {
  return parse_hex(str.c_str(), str.length(), data, count) == 2 * count;
}
inline bool parse_hex(const char *str, std::vector<uint8_t> &data, size_t count) {
  data.resize(count);
  return parse_hex(str, strlen(str), data.data(), count) == 2 * count;
}
inline bool parse_hex(const std::string &str, std::vector<uint8_t> &data, size_t count) {
  data.resize(count);
  return parse_hex(str.c_str(), str.length(), data.data(), count) == 2 * count;
}
template<typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0>
optional<T> parse_hex(const char *str, size_t len) {
  T val = 0;
  if (len > 2 * sizeof(T) || parse_hex(str, len, reinterpret_cast<uint8_t *>(&val), sizeof(T)) == 0)
    return {};
  return convert_big_endian(val);
}
template<typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0> optional<T> parse_hex(const char *str) {
  return parse_hex<T>(str, strlen(str));
}
template<typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0> optional<T> parse_hex(const std::string &str) {
  return parse_hex<T>(str.c_str(), str.length());
}
 
constexpr uint8_t parse_hex_char(char c) {
  if (c >= '0' && c <= '9')
    return c - '0';
  if (c >= 'A' && c <= 'F')
    return c - 'A' + 10;
  if (c >= 'a' && c <= 'f')
    return c - 'a' + 10;
  return 255;
}
 
inline char format_hex_char(uint8_t v, char base) { return v >= 10 ? base + (v - 10) : '0' + v; }
 
inline char format_hex_char(uint8_t v) { return format_hex_char(v, 'a'); }
 
inline char format_hex_pretty_char(uint8_t v) { return format_hex_char(v, 'A'); }
 
inline char *int8_to_str(char *buf, int8_t val) {
  int32_t v = val;
  if (v < 0) {
    *buf++ = '-';
    v = -v;
  }
  if (v >= 100) {
    *buf++ = '1';  // int8 max is 128, so hundreds digit is always 1
    v -= 100;
    // Must write tens digit (even if 0) after hundreds
    int32_t tens = v / 10;
    *buf++ = '0' + tens;
    v -= tens * 10;
  } else if (v >= 10) {
    int32_t tens = v / 10;
    *buf++ = '0' + tens;
    v -= tens * 10;
  }
  *buf++ = '0' + v;
  return buf;
}
 
char *format_hex_to(char *buffer, size_t buffer_size, const uint8_t *data, size_t length);
 
template<size_t N> inline char *format_hex_to(char (&buffer)[N], const uint8_t *data, size_t length) {
  static_assert(N >= 3, "Buffer must hold at least one hex byte (3 chars)");
  return format_hex_to(buffer, N, data, length);
}
 
template<size_t N, typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0>
inline char *format_hex_to(char (&buffer)[N], T val) {
  static_assert(N >= sizeof(T) * 2 + 1, "Buffer too small for type");
  val = convert_big_endian(val);
  return format_hex_to(buffer, reinterpret_cast<const uint8_t *>(&val), sizeof(T));
}
 
template<size_t N> inline char *format_hex_to(char (&buffer)[N], const std::vector<uint8_t> &data) {
  return format_hex_to(buffer, data.data(), data.size());
}
 
template<size_t N, size_t M> inline char *format_hex_to(char (&buffer)[N], const std::array<uint8_t, M> &data) {
  return format_hex_to(buffer, data.data(), data.size());
}
 
constexpr size_t format_hex_size(size_t byte_count) { return byte_count * 2 + 1; }
 
constexpr size_t format_hex_prefixed_size(size_t byte_count) { return byte_count * 2 + 3; }
 
template<size_t N, typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0>
inline char *format_hex_prefixed_to(char (&buffer)[N], T val) {
  static_assert(N >= sizeof(T) * 2 + 3, "Buffer too small for prefixed hex");
  buffer[0] = '0';
  buffer[1] = 'x';
  val = convert_big_endian(val);
  format_hex_to(buffer + 2, N - 2, reinterpret_cast<const uint8_t *>(&val), sizeof(T));
  return buffer;
}
 
template<size_t N> inline char *format_hex_prefixed_to(char (&buffer)[N], const uint8_t *data, size_t length) {
  static_assert(N >= 5, "Buffer must hold at least '0x' + one hex byte + null");
  buffer[0] = '0';
  buffer[1] = 'x';
  format_hex_to(buffer + 2, N - 2, data, length);
  return buffer;
}
 
constexpr size_t format_hex_pretty_size(size_t byte_count) { return byte_count * 3; }
 
char *format_hex_pretty_to(char *buffer, size_t buffer_size, const uint8_t *data, size_t length, char separator = ':');
 
template<size_t N>
inline char *format_hex_pretty_to(char (&buffer)[N], const uint8_t *data, size_t length, char separator = ':') {
  static_assert(N >= 3, "Buffer must hold at least one hex byte");
  return format_hex_pretty_to(buffer, N, data, length, separator);
}
 
template<size_t N>
inline char *format_hex_pretty_to(char (&buffer)[N], const std::vector<uint8_t> &data, char separator = ':') {
  return format_hex_pretty_to(buffer, data.data(), data.size(), separator);
}
 
template<size_t N, size_t M>
inline char *format_hex_pretty_to(char (&buffer)[N], const std::array<uint8_t, M> &data, char separator = ':') {
  return format_hex_pretty_to(buffer, data.data(), data.size(), separator);
}
 
constexpr size_t format_hex_pretty_uint16_size(size_t count) { return count * 5; }
 
char *format_hex_pretty_to(char *buffer, size_t buffer_size, const uint16_t *data, size_t length, char separator = ':');
 
template<size_t N>
inline char *format_hex_pretty_to(char (&buffer)[N], const uint16_t *data, size_t length, char separator = ':') {
  static_assert(N >= 5, "Buffer must hold at least one hex uint16_t");
  return format_hex_pretty_to(buffer, N, data, length, separator);
}
 
static constexpr size_t MAC_ADDRESS_SIZE = 6;
static constexpr size_t MAC_ADDRESS_PRETTY_BUFFER_SIZE = format_hex_pretty_size(MAC_ADDRESS_SIZE);
static constexpr size_t MAC_ADDRESS_BUFFER_SIZE = MAC_ADDRESS_SIZE * 2 + 1;
 
inline char *format_mac_addr_upper(const uint8_t *mac, char *output) {
  return format_hex_pretty_to(output, MAC_ADDRESS_PRETTY_BUFFER_SIZE, mac, MAC_ADDRESS_SIZE, ':');
}
 
inline void format_mac_addr_lower_no_sep(const uint8_t *mac, char *output) {
  format_hex_to(output, MAC_ADDRESS_BUFFER_SIZE, mac, MAC_ADDRESS_SIZE);
}
 
std::string format_mac_address_pretty(const uint8_t mac[6]);
std::string format_hex(const uint8_t *data, size_t length);
std::string format_hex(const std::vector<uint8_t> &data);
template<typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0> std::string format_hex(T val) {
  val = convert_big_endian(val);
  return format_hex(reinterpret_cast<uint8_t *>(&val), sizeof(T));
}
template<std::size_t N> std::string format_hex(const std::array<uint8_t, N> &data) {
  return format_hex(data.data(), data.size());
}
 
std::string format_hex_pretty(const uint8_t *data, size_t length, char separator = '.', bool show_length = true);
 
std::string format_hex_pretty(const uint16_t *data, size_t length, char separator = '.', bool show_length = true);
 
std::string format_hex_pretty(const std::vector<uint8_t> &data, char separator = '.', bool show_length = true);
 
std::string format_hex_pretty(const std::vector<uint16_t> &data, char separator = '.', bool show_length = true);
 
std::string format_hex_pretty(const std::string &data, char separator = '.', bool show_length = true);
 
template<typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0>
std::string format_hex_pretty(T val, char separator = '.', bool show_length = true) {
  val = convert_big_endian(val);
  return format_hex_pretty(reinterpret_cast<uint8_t *>(&val), sizeof(T), separator, show_length);
}
 
std::string format_bin(const uint8_t *data, size_t length);
template<typename T, enable_if_t<std::is_unsigned<T>::value, int> = 0> std::string format_bin(T val) {
  val = convert_big_endian(val);
  return format_bin(reinterpret_cast<uint8_t *>(&val), sizeof(T));
}
 
enum ParseOnOffState : uint8_t {
  PARSE_NONE = 0,
  PARSE_ON,
  PARSE_OFF,
  PARSE_TOGGLE,
};
ParseOnOffState parse_on_off(const char *str, const char *on = nullptr, const char *off = nullptr);
 
ESPDEPRECATED("Allocates heap memory. Use value_accuracy_to_buf() instead. Removed in 2026.7.0.", "2026.1.0")
std::string value_accuracy_to_string(float value, int8_t accuracy_decimals);
 
static constexpr size_t VALUE_ACCURACY_MAX_LEN = 64;
 
size_t value_accuracy_to_buf(std::span<char, VALUE_ACCURACY_MAX_LEN> buf, float value, int8_t accuracy_decimals);
size_t value_accuracy_with_uom_to_buf(std::span<char, VALUE_ACCURACY_MAX_LEN> buf, float value,
                                      int8_t accuracy_decimals, StringRef unit_of_measurement);
 
int8_t step_to_accuracy_decimals(float step);
 
std::string base64_encode(const uint8_t *buf, size_t buf_len);
std::string base64_encode(const std::vector<uint8_t> &buf);
 
std::vector<uint8_t> base64_decode(const std::string &encoded_string);
size_t base64_decode(std::string const &encoded_string, uint8_t *buf, size_t buf_len);
size_t base64_decode(const uint8_t *encoded_data, size_t encoded_len, uint8_t *buf, size_t buf_len);
 
 
 
float gamma_correct(float value, float gamma);
float gamma_uncorrect(float value, float gamma);
 
void rgb_to_hsv(float red, float green, float blue, int &hue, float &saturation, float &value);
void hsv_to_rgb(int hue, float saturation, float value, float &red, float &green, float &blue);
 
 
 
constexpr float celsius_to_fahrenheit(float value) { return value * 1.8f + 32.0f; }
constexpr float fahrenheit_to_celsius(float value) { return (value - 32.0f) / 1.8f; }
 
 
 
template<typename... X> class CallbackManager;
 
template<typename... Ts> class CallbackManager<void(Ts...)> {
 public:
  void add(std::function<void(Ts...)> &&callback) { this->callbacks_.push_back(std::move(callback)); }
 
  void call(Ts... args) {
    for (auto &cb : this->callbacks_)
      cb(args...);
  }
  size_t size() const { return this->callbacks_.size(); }
 
  void operator()(Ts... args) { call(args...); }
 
 protected:
  std::vector<std::function<void(Ts...)>> callbacks_;
};
 
template<typename... X> class LazyCallbackManager;
 
template<typename... Ts> class LazyCallbackManager<void(Ts...)> {
 public:
  void add(std::function<void(Ts...)> &&callback) {
    if (!this->callbacks_) {
      this->callbacks_ = make_unique<CallbackManager<void(Ts...)>>();
    }
    this->callbacks_->add(std::move(callback));
  }
 
  void call(Ts... args) {
    if (this->callbacks_) {
      this->callbacks_->call(args...);
    }
  }
 
  size_t size() const { return this->callbacks_ ? this->callbacks_->size() : 0; }
 
  bool empty() const { return !this->callbacks_ || this->callbacks_->size() == 0; }
 
  void operator()(Ts... args) { this->call(args...); }
 
 protected:
  std::unique_ptr<CallbackManager<void(Ts...)>> callbacks_;
};
 
template<typename T> class Deduplicator {
 public:
  bool next(T value) {
    if (this->has_value_ && !this->value_unknown_ && this->last_value_ == value) {
      return false;
    }
    this->has_value_ = true;
    this->value_unknown_ = false;
    this->last_value_ = value;
    return true;
  }
  bool next_unknown() {
    bool ret = !this->value_unknown_;
    this->value_unknown_ = true;
    return ret;
  }
  bool has_value() const { return this->has_value_; }
 
 protected:
  bool has_value_{false};
  bool value_unknown_{false};
  T last_value_{};
};
 
template<typename T> class Parented {
 public:
  Parented() {}
  Parented(T *parent) : parent_(parent) {}
 
  T *get_parent() const { return parent_; }
  void set_parent(T *parent) { parent_ = parent; }
 
 protected:
  T *parent_{nullptr};
};
 
 
 
class Mutex {
 public:
  Mutex();
  Mutex(const Mutex &) = delete;
  ~Mutex();
  void lock();
  bool try_lock();
  void unlock();
 
  Mutex &operator=(const Mutex &) = delete;
 
 private:
#if defined(USE_ESP32) || defined(USE_LIBRETINY)
  SemaphoreHandle_t handle_;
#else
  // d-pointer to store private data on new platforms
  void *handle_;  // NOLINT(clang-diagnostic-unused-private-field)
#endif
};
 
class LockGuard {
 public:
  LockGuard(Mutex &mutex) : mutex_(mutex) { mutex_.lock(); }
  ~LockGuard() { mutex_.unlock(); }
 
 private:
  Mutex &mutex_;
};
 
class InterruptLock {
 public:
  InterruptLock();
  ~InterruptLock();
 
 protected:
#if defined(USE_ESP8266) || defined(USE_RP2040) || defined(USE_ZEPHYR)
  uint32_t state_;
#endif
};
 
class LwIPLock {
 public:
  LwIPLock();
  ~LwIPLock();
 
  // Delete copy constructor and copy assignment operator to prevent accidental copying
  LwIPLock(const LwIPLock &) = delete;
  LwIPLock &operator=(const LwIPLock &) = delete;
};
 
class HighFrequencyLoopRequester {
 public:
  void start();
  void stop();
 
  static bool is_high_frequency();
 
 protected:
  bool started_{false};
  static uint8_t num_requests;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
};
 
void get_mac_address_raw(uint8_t *mac);  // NOLINT(readability-non-const-parameter)
 
std::string get_mac_address();
 
std::string get_mac_address_pretty();
 
void get_mac_address_into_buffer(std::span<char, MAC_ADDRESS_BUFFER_SIZE> buf);
 
const char *get_mac_address_pretty_into_buffer(std::span<char, MAC_ADDRESS_PRETTY_BUFFER_SIZE> buf);
 
#ifdef USE_ESP32
void set_mac_address(uint8_t *mac);
#endif
 
bool has_custom_mac_address();
 
bool mac_address_is_valid(const uint8_t *mac);
 
void delay_microseconds_safe(uint32_t us);
 
 
 
template<class T> class RAMAllocator {
 public:
  using value_type = T;
 
  enum Flags {
    NONE = 0,                 // Perform external allocation and fall back to internal memory
    ALLOC_EXTERNAL = 1 << 0,  // Perform external allocation only.
    ALLOC_INTERNAL = 1 << 1,  // Perform internal allocation only.
    ALLOW_FAILURE = 1 << 2,   // Does nothing. Kept for compatibility.
  };
 
  RAMAllocator() = default;
  RAMAllocator(uint8_t flags) {
    // default is both external and internal
    flags &= ALLOC_INTERNAL | ALLOC_EXTERNAL;
    if (flags != 0)
      this->flags_ = flags;
  }
  template<class U> constexpr RAMAllocator(const RAMAllocator<U> &other) : flags_{other.flags_} {}
 
  T *allocate(size_t n) { return this->allocate(n, sizeof(T)); }
 
  T *allocate(size_t n, size_t manual_size) {
    size_t size = n * manual_size;
    T *ptr = nullptr;
#ifdef USE_ESP32
    if (this->flags_ & Flags::ALLOC_EXTERNAL) {
      ptr = static_cast<T *>(heap_caps_malloc(size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT));
    }
    if (ptr == nullptr && this->flags_ & Flags::ALLOC_INTERNAL) {
      ptr = static_cast<T *>(heap_caps_malloc(size, MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT));
    }
#else
    // Ignore ALLOC_EXTERNAL/ALLOC_INTERNAL flags if external allocation is not supported
    ptr = static_cast<T *>(malloc(size));  // NOLINT(cppcoreguidelines-owning-memory,cppcoreguidelines-no-malloc)
#endif
    return ptr;
  }
 
  T *reallocate(T *p, size_t n) { return this->reallocate(p, n, sizeof(T)); }
 
  T *reallocate(T *p, size_t n, size_t manual_size) {
    size_t size = n * manual_size;
    T *ptr = nullptr;
#ifdef USE_ESP32
    if (this->flags_ & Flags::ALLOC_EXTERNAL) {
      ptr = static_cast<T *>(heap_caps_realloc(p, size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT));
    }
    if (ptr == nullptr && this->flags_ & Flags::ALLOC_INTERNAL) {
      ptr = static_cast<T *>(heap_caps_realloc(p, size, MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT));
    }
#else
    // Ignore ALLOC_EXTERNAL/ALLOC_INTERNAL flags if external allocation is not supported
    ptr = static_cast<T *>(realloc(p, size));  // NOLINT(cppcoreguidelines-owning-memory,cppcoreguidelines-no-malloc)
#endif
    return ptr;
  }
 
  void deallocate(T *p, size_t n) {
    free(p);  // NOLINT(cppcoreguidelines-owning-memory,cppcoreguidelines-no-malloc)
  }
 
  size_t get_free_heap_size() const {
#ifdef USE_ESP8266
    return ESP.getFreeHeap();  // NOLINT(readability-static-accessed-through-instance)
#elif defined(USE_ESP32)
    auto max_internal =
        this->flags_ & ALLOC_INTERNAL ? heap_caps_get_free_size(MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL) : 0;
    auto max_external =
        this->flags_ & ALLOC_EXTERNAL ? heap_caps_get_free_size(MALLOC_CAP_8BIT | MALLOC_CAP_SPIRAM) : 0;
    return max_internal + max_external;
#elif defined(USE_RP2040)
    return ::rp2040.getFreeHeap();
#elif defined(USE_LIBRETINY)
    return lt_heap_get_free();
#else
    return 100000;
#endif
  }
 
  size_t get_max_free_block_size() const {
#ifdef USE_ESP8266
    return ESP.getMaxFreeBlockSize();  // NOLINT(readability-static-accessed-through-instance)
#elif defined(USE_ESP32)
    auto max_internal =
        this->flags_ & ALLOC_INTERNAL ? heap_caps_get_largest_free_block(MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL) : 0;
    auto max_external =
        this->flags_ & ALLOC_EXTERNAL ? heap_caps_get_largest_free_block(MALLOC_CAP_8BIT | MALLOC_CAP_SPIRAM) : 0;
    return std::max(max_internal, max_external);
#else
    return this->get_free_heap_size();
#endif
  }
 
 private:
  uint8_t flags_{ALLOC_INTERNAL | ALLOC_EXTERNAL};
};
 
template<class T> using ExternalRAMAllocator = RAMAllocator<T>;
 
template<typename T, typename U>
concept comparable_with = requires(T a, U b) {
  { a > b } -> std::convertible_to<bool>;
  { a < b } -> std::convertible_to<bool>;
};
 
template<std::totally_ordered T, comparable_with<T> U> T clamp_at_least(T value, U min) {
  if (value < min)
    return min;
  return value;
}
template<std::totally_ordered T, comparable_with<T> U> T clamp_at_most(T value, U max) {
  if (value > max)
    return max;
  return value;
}
 
 
template<typename T, enable_if_t<!std::is_pointer<T>::value, int> = 0> T id(T value) { return value; }
template<typename T, enable_if_t<std::is_pointer<T *>::value, int> = 0> T &id(T *value) { return *value; }
 
 
}  // namespace esphome