string_ref.h

Go to the documentation of this file.

#pragma once
 
#include <algorithm>
#include <cstdint>
#include <cstring>
#include <iterator>
#include <memory>
#include <string>
#include "esphome/core/defines.h"
 
#ifdef USE_JSON
#include "esphome/components/json/json_util.h"
#endif  // USE_JSON
 
#ifdef USE_ESP8266
#include <pgmspace.h>
#endif  // USE_ESP8266
 
namespace esphome {
 
class StringRef {
 public:
  using traits_type = std::char_traits<char>;
  using value_type = traits_type::char_type;
  using allocator_type = std::allocator<char>;
  using size_type = std::allocator_traits<allocator_type>::size_type;
  using difference_type = std::allocator_traits<allocator_type>::difference_type;
  using const_reference = const value_type &;
  using const_pointer = const value_type *;
  using const_iterator = const_pointer;
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
 
  constexpr StringRef() : base_(""), len_(0) {}
  explicit StringRef(const std::string &s) : base_(s.c_str()), len_(s.size()) {}
  explicit StringRef(const char *s) : base_(s), len_(strlen(s)) {}
  constexpr StringRef(const char *s, size_t n) : base_(s), len_(n) {}
  template<typename CharT>
  constexpr StringRef(const CharT *s, size_t n) : base_(reinterpret_cast<const char *>(s)), len_(n) {}
  template<typename InputIt>
  StringRef(InputIt first, InputIt last)
      : base_(reinterpret_cast<const char *>(&*first)), len_(std::distance(first, last)) {}
  template<typename InputIt>
  StringRef(InputIt *first, InputIt *last)
      : base_(reinterpret_cast<const char *>(first)), len_(std::distance(first, last)) {}
  template<typename CharT, size_t N> constexpr static StringRef from_lit(const CharT (&s)[N]) {
    return StringRef{s, N - 1};
  }
  static StringRef from_maybe_nullptr(const char *s) {
    if (s == nullptr) {
      return StringRef();
    }
 
    return StringRef(s);
  }
 
  constexpr const_iterator begin() const { return base_; };
  constexpr const_iterator cbegin() const { return base_; };
 
  constexpr const_iterator end() const { return base_ + len_; };
  constexpr const_iterator cend() const { return base_ + len_; };
 
  const_reverse_iterator rbegin() const { return const_reverse_iterator{base_ + len_}; }
  const_reverse_iterator crbegin() const { return const_reverse_iterator{base_ + len_}; }
 
  const_reverse_iterator rend() const { return const_reverse_iterator{base_}; }
  const_reverse_iterator crend() const { return const_reverse_iterator{base_}; }
 
  constexpr const char *c_str() const { return base_; }
  constexpr size_type size() const { return len_; }
  constexpr size_type length() const { return len_; }
  constexpr bool empty() const { return len_ == 0; }
  constexpr const_reference operator[](size_type pos) const { return *(base_ + pos); }
 
  bool starts_with(const StringRef &prefix) const {
    return len_ >= prefix.len_ && (prefix.len_ == 0 || std::memcmp(base_, prefix.base_, prefix.len_) == 0);
  }
  bool starts_with(const char *prefix) const { return this->starts_with(StringRef(prefix)); }
  bool starts_with(const std::string &prefix) const { return this->starts_with(StringRef(prefix)); }
 
  size_type copy(char *dest, size_type count, size_type pos = 0) const {
    if (pos >= len_)
      return 0;
    size_type actual = (count > len_ - pos) ? len_ - pos : count;
    std::memcpy(dest, base_ + pos, actual);
    return actual;
  }
 
  std::string str() const { return std::string(base_, len_); }  // fine for {nullptr, 0}: nothing is read
  const uint8_t *byte() const { return reinterpret_cast<const uint8_t *>(base_); }
 
  operator std::string() const { return str(); }
 
  int compare(const StringRef &other) const {
    size_type common = std::min(len_, other.len_);
    int result = common == 0 ? 0 : std::memcmp(base_, other.base_, common);
    if (result != 0)
      return result;
    if (len_ < other.len_)
      return -1;
    if (len_ > other.len_)
      return 1;
    return 0;
  }
  int compare(const char *s) const { return compare(StringRef(s)); }
  int compare(const std::string &s) const { return compare(StringRef(s)); }
 
  size_type find(const char *s, size_type pos = 0) const {
    if (pos >= len_)
      return std::string::npos;
    const char *result = std::strstr(base_ + pos, s);
    // Verify entire match is within bounds (strstr searches to null terminator)
    if (result && result + std::strlen(s) <= base_ + len_)
      return static_cast<size_type>(result - base_);
    return std::string::npos;
  }
  size_type find(char c, size_type pos = 0) const {
    if (pos >= len_)
      return std::string::npos;
    const void *result = std::memchr(base_ + pos, static_cast<unsigned char>(c), len_ - pos);
    return result ? static_cast<size_type>(static_cast<const char *>(result) - base_) : std::string::npos;
  }
 
  std::string substr(size_type pos = 0, size_type count = std::string::npos) const {
    if (pos >= len_)
      return std::string();
    size_type actual_count = (count == std::string::npos || pos + count > len_) ? len_ - pos : count;
    return std::string(base_ + pos, actual_count);
  }
 
 private:
  const char *base_;
  size_type len_;
};
 
inline bool operator==(const StringRef &lhs, const StringRef &rhs) {
  return lhs.size() == rhs.size() && std::equal(std::begin(lhs), std::end(lhs), std::begin(rhs));
}
 
inline bool operator==(const StringRef &lhs, const std::string &rhs) {
  return lhs.size() == rhs.size() && std::equal(std::begin(lhs), std::end(lhs), std::begin(rhs));
}
 
inline bool operator==(const std::string &lhs, const StringRef &rhs) { return rhs == lhs; }
 
inline bool operator==(const StringRef &lhs, const char *rhs) {
  return lhs.size() == strlen(rhs) && std::equal(std::begin(lhs), std::end(lhs), rhs);
}
 
inline bool operator==(const char *lhs, const StringRef &rhs) { return rhs == lhs; }
 
inline bool operator!=(const StringRef &lhs, const StringRef &rhs) { return !(lhs == rhs); }
 
inline bool operator!=(const StringRef &lhs, const std::string &rhs) { return !(lhs == rhs); }
 
inline bool operator!=(const std::string &lhs, const StringRef &rhs) { return !(rhs == lhs); }
 
inline bool operator!=(const StringRef &lhs, const char *rhs) { return !(lhs == rhs); }
 
inline bool operator!=(const char *lhs, const StringRef &rhs) { return !(rhs == lhs); }
 
#ifdef USE_ESP8266
inline bool operator==(const StringRef &lhs, const __FlashStringHelper *rhs) {
  PGM_P p = reinterpret_cast<PGM_P>(rhs);
  size_t rhs_len = strlen_P(p);
  if (lhs.size() != rhs_len) {
    return false;
  }
  return memcmp_P(lhs.c_str(), p, rhs_len) == 0;
}
 
inline bool operator==(const __FlashStringHelper *lhs, const StringRef &rhs) { return rhs == lhs; }
 
inline bool operator!=(const StringRef &lhs, const __FlashStringHelper *rhs) { return !(lhs == rhs); }
 
inline bool operator!=(const __FlashStringHelper *lhs, const StringRef &rhs) { return !(rhs == lhs); }
 
#endif  // USE_ESP8266
 
inline bool operator<(const StringRef &lhs, const StringRef &rhs) {
  return std::lexicographical_compare(std::begin(lhs), std::end(lhs), std::begin(rhs), std::end(rhs));
}
 
inline std::string &operator+=(std::string &lhs, const StringRef &rhs) {
  lhs.append(rhs.c_str(), rhs.size());
  return lhs;
}
 
inline std::string operator+(const char *lhs, const StringRef &rhs) {
  auto str = std::string(lhs);
  str.append(rhs.c_str(), rhs.size());
  return str;
}
 
inline std::string operator+(const StringRef &lhs, const char *rhs) {
  auto str = lhs.str();
  str.append(rhs);
  return str;
}
 
inline std::string operator+(const StringRef &lhs, const std::string &rhs) {
  auto str = lhs.str();
  str.append(rhs);
  return str;
}
 
inline std::string operator+(const std::string &lhs, const StringRef &rhs) {
  std::string str(lhs);
  str.append(rhs.c_str(), rhs.size());
  return str;
}
 
class ProgmemStringRef {
 public:
  constexpr ProgmemStringRef() = default;
  constexpr ProgmemStringRef(const char *s, size_t len) : ref_(s, len) {}
  constexpr explicit ProgmemStringRef(const StringRef &s) : ref_(s) {}
  template<size_t N> static constexpr ProgmemStringRef from_lit(const char (&s)[N]) { return {s, N - 1}; }
 
  constexpr const char *progmem_ptr() const { return this->ref_.c_str(); }
  constexpr size_t size() const { return this->ref_.size(); }
  constexpr bool empty() const { return this->ref_.empty(); }
 
  size_t write_to(char *buf, size_t buf_size) const {
    if (buf_size == 0)
      return 0;
    size_t len = std::min(this->ref_.size(), buf_size - 1);
#ifdef USE_ESP8266
    memcpy_P(buf, this->ref_.c_str(), len);
#else
    std::memcpy(buf, this->ref_.c_str(), len);
#endif
    buf[len] = '\0';
    return len;
  }
 
  bool equals(const StringRef &other) const {
#ifdef USE_ESP8266
    // A StringRef may be {nullptr, 0}, and memcmp_P with a null pointer is undefined even for 0 bytes
    return other.size() == this->ref_.size() &&
           (other.empty() || memcmp_P(other.c_str(), this->ref_.c_str(), other.size()) == 0);
#else
    return other == this->ref_;
#endif
  }
 
#ifndef USE_ESP8266
  constexpr const StringRef &ram_ref() const { return this->ref_; }
#endif
 
  // Remove before 2027.5.0
  [[deprecated(
      "May point to flash; use progmem_ptr() or the owner's accessors. Removed in 2027.5.0")]] constexpr const char *
  c_str() const {
    return this->ref_.c_str();
  }
 
 private:
  StringRef ref_;
};
 
#ifdef USE_ESP8266
inline bool operator==(const StringRef &lhs, const ProgmemStringRef &rhs) { return rhs.equals(lhs); }
inline bool operator!=(const StringRef &lhs, const ProgmemStringRef &rhs) { return !rhs.equals(lhs); }
inline bool operator==(const std::string &lhs, const ProgmemStringRef &rhs) { return rhs.equals(StringRef(lhs)); }
inline bool operator!=(const std::string &lhs, const ProgmemStringRef &rhs) { return !rhs.equals(StringRef(lhs)); }
#endif
 
// String conversion functions for ADL compatibility (allows stoi(x) where x is StringRef)
// Must be in esphome namespace for ADL to find them. Uses strtol/strtod directly to avoid heap allocation.
namespace internal {
// NOLINTBEGIN(google-runtime-int)
template<typename R, typename F> inline R parse_number(const StringRef &str, size_t *pos, F conv) {
  if (str.empty()) {  // nothing to parse, and a null view must not reach the C library
    if (pos)
      *pos = 0;
    return R{};
  }
  char *end;
  R result = conv(str.c_str(), &end);
  // Set pos to 0 on conversion failure (when no characters consumed), otherwise index after number
  if (pos)
    *pos = (end == str.c_str()) ? 0 : static_cast<size_t>(end - str.c_str());
  return result;
}
template<typename R, typename F> inline R parse_number(const StringRef &str, size_t *pos, int base, F conv) {
  if (str.empty()) {  // nothing to parse, and a null view must not reach the C library
    if (pos)
      *pos = 0;
    return R{};
  }
  char *end;
  R result = conv(str.c_str(), &end, base);
  // Set pos to 0 on conversion failure (when no characters consumed), otherwise index after number
  if (pos)
    *pos = (end == str.c_str()) ? 0 : static_cast<size_t>(end - str.c_str());
  return result;
}
// NOLINTEND(google-runtime-int)
}  // namespace internal
// readability-non-const-parameter: `pos` is written through by internal::parse_number, one call
// frame away; the check only inspects these bodies, so it wrongly proposes `const size_t *`.
// NOLINTBEGIN(readability-identifier-naming,google-runtime-int,readability-non-const-parameter)
inline int stoi(const StringRef &str, size_t *pos = nullptr, int base = 10) {
  return static_cast<int>(internal::parse_number<long>(str, pos, base, std::strtol));
}
inline long stol(const StringRef &str, size_t *pos = nullptr, int base = 10) {
  return internal::parse_number<long>(str, pos, base, std::strtol);
}
inline float stof(const StringRef &str, size_t *pos = nullptr) {
  return internal::parse_number<float>(str, pos, std::strtof);
}
inline double stod(const StringRef &str, size_t *pos = nullptr) {
  return internal::parse_number<double>(str, pos, std::strtod);
}
// NOLINTEND(readability-identifier-naming,google-runtime-int,readability-non-const-parameter)
 
#ifdef USE_JSON
// A StringRef may view a scratch buffer (mqtt topics do), so the document copies it
// NOLINTNEXTLINE(readability-identifier-naming)
inline void convertToJson(const StringRef &src, JsonVariant dst) {
  // Bounded by the view length; a null, empty view becomes "" rather than JSON null
  if (src.empty()) {
    dst.set("");
    return;
  }
  // The explicit isStatic is load bearing: without it clang-tidy reads size() as the bool of the two argument
  // constructor and asks for empty() instead
  dst.set(JsonString(src.c_str(), src.size(), /* isStatic= */ false));
}
 
namespace json {
// For a view that outlives the document, see json_util.h. ArduinoJson keeps a linked string as a bare
// pointer and reads it to its terminator on every platform, so the view must be a whole string, as the
// entity getters' views are. A null, empty view links "" too
inline JsonString linked(const StringRef &s) { return JsonString(s.empty() ? "" : s.c_str(), s.size(), true); }
#ifdef USE_ESP8266
// ArduinoJson copies a flash string into the document
inline ProgmemStr linked(const ProgmemStringRef &s) { return reinterpret_cast<ProgmemStr>(s.progmem_ptr()); }
#else
inline JsonString linked(const ProgmemStringRef &s) { return JsonString(s.progmem_ptr(), s.size(), true); }
#endif
}  // namespace json
#endif  // USE_JSON
 
}  // namespace esphome