src/SquidString.h

   1 /*
   2  * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 /* DEBUG: section 67    String */
  10
  11 #ifndef SQUID_SRC_SQUIDSTRING_H
  12 #define SQUID_SRC_SQUIDSTRING_H
  13
  14 #include "base/TextException.h"
  15 #include "debug/Stream.h"
  16 #include "sbuf/forward.h"
  17
  18 #include <ostream>
  19
  20 /* squid string placeholder (for printf) */
  21 #ifndef SQUIDSTRINGPH
  22 #define SQUIDSTRINGPH "%.*s"
  23 #define SQUIDSTRINGPRINT(s) (s).psize(),(s).rawBuf()
  24 #endif /* SQUIDSTRINGPH */
  25
  26 class String
  27 {
  28
  29 public:
  30     String() = default;
  31     String(char const *);
  32     String(String const &);
  33     String(String && S) : size_(S.size_), len_(S.len_), buf_(S.buf_) {
  34         S.buf_ = nullptr; // S is about to be destructed
  35         S.size_ = S.len_ = 0;
  36     }
  37     ~String();
  38
  39     typedef size_t size_type; //storage size intentionally unspecified
  40     const static size_type npos = static_cast<size_type>(-1);
  41
  42     String &operator =(char const *);
  43     String &operator =(String const &);
  44     String &operator =(String && S) {
  45         if (this != &S) {
  46             clean();
  47             size_ = S.size_;
  48             len_ = S.len_;
  49             buf_ = S.buf_;
  50             S.size_ = 0;
  51             S.len_ = 0;
  52             S.buf_ = nullptr; // S is about to be destructed
  53         }
  54         return *this;
  55     }
  56
  57     bool operator ==(String const &) const;
  58     bool operator !=(String const &) const;
  59
  60     /**
  61      * Retrieve a single character in the string.
  62      \param aPos Position of character to retrieve.
  63      */
  64     char operator [](unsigned int aPos) const {
  65         assert(aPos < size_);
  66         return buf_[aPos];
  67     }
  68
  69     /// The absolute size limit on data held in a String.
  70     /// Since Strings can be nil-terminated implicitly it is best to ensure
  71     /// the useful content length is strictly less than this limit.
  72     static size_type SizeMaxXXX() { return SizeMax_; }
  73
  74     size_type size() const { return len_; }
  75
  76     /// variant of size() suited to be used for printf-alikes.
  77     /// throws when size() >= INT_MAX
  78     int psize() const {
  79         Must(size() < INT_MAX);
  80         return size();
  81     }
  82
  83     /**
  84      * Returns a raw pointer to the underlying backing store. The caller has been
  85      * verified not to make any assumptions about null-termination
  86      */
  87     char const * rawBuf() const { return buf_; }
  88
  89     /**
  90      * Returns a raw pointer to the underlying backing store.
  91      * The caller requires it to be null-terminated.
  92      */
  93     char const * termedBuf() const { return buf_; }
  94
  95     void assign(const char *str, int len);
  96     void clean();
  97     void reset(char const *str);
  98     void append(char const *buf, int len);
  99     void append(char const *buf);
 100     void append(char const);
 101     void append(String const &);
 102     void append(const SBuf &); ///< adds the entire given buffer
 103     void absorb(String &old);
 104     const char * pos(char const *aString) const;
 105     const char * pos(char const ch) const;
 106     ///offset from string start of the first occurrence of ch
 107     /// returns String::npos if ch is not found
 108     size_type find(char const ch) const;
 109     size_type find(char const *aString) const;
 110     const char * rpos(char const ch) const;
 111     size_type rfind(char const ch) const;
 112     int cmp(char const *) const;
 113     int cmp(char const *, size_type count) const;
 114     int cmp(String const &) const;
 115     int caseCmp(char const *) const;
 116     int caseCmp(char const *, size_type count) const;
 117     int caseCmp(String const &str) const {
 118         return caseCmp(str.rawBuf(),str.size());
 119     }
 120
 121     /// Whether creating a totalLen-character string is safe (i.e., unlikely to assert).
 122     /// Optional extras can be used for overflow-safe length addition.
 123     /// Implementation has to add 1 because many String allocation methods do.
 124     static bool CanGrowTo(size_type totalLen, const size_type extras = 0) { return SafeAdd(totalLen, extras) && SafeAdd(totalLen, 1); }
 125     /// whether appending growthLen characters is safe (i.e., unlikely to assert)
 126     bool canGrowBy(const size_type growthLen) const { return CanGrowTo(size(), growthLen); }
 127
 128     String substr(size_type from, size_type to) const;
 129
 130     void cut(size_type newLength);
 131
 132 private:
 133     void allocAndFill(const char *str, int len);
 134     void allocBuffer(size_type sz);
 135     void setBuffer(char *buf, size_type sz);
 136
 137     bool defined() const {return buf_!=nullptr;}
 138     bool undefined() const {return !defined();}
 139
 140     /* never reference these directly! */
 141     size_type size_ = 0; /* buffer size; limited by SizeMax_ */
 142
 143     size_type len_ = 0;  /* current length  */
 144
 145     /// An earlier 64KB limit was meant to protect some fixed-size buffers, but
 146     /// (a) we do not know where those buffers are (or whether they still exist)
 147     /// (b) too many String users unknowingly exceeded that limit and asserted.
 148     /// We are now using a larger limit to reduce the number of (b) cases,
 149     /// especially cases where "compact" lists of items grow 50% in size when we
 150     /// convert them to canonical form. The new limit is selected to withstand
 151     /// concatenation and ~50% expansion of two HTTP headers limited by default
 152     /// request_header_max_size and reply_header_max_size settings.
 153     static const size_type SizeMax_ = 3*64*1024 - 1;
 154
 155     /// returns true after increasing the first argument by extra if the sum does not exceed SizeMax_
 156     static bool SafeAdd(size_type &base, size_type extra) { if (extra <= SizeMax_ && base <= SizeMax_ - extra) { base += extra; return true; } return false; }
 157
 158     char *buf_ = nullptr;
 159
 160     void set(char const *loc, char const ch) {
 161         if (loc < buf_ || loc > (buf_ + size_))
 162             return;
 163         buf_[loc-buf_] = ch;
 164     }
 165
 166     void cutPointer(char const *loc) {
 167         if (loc < buf_ || loc > (buf_ + size_))
 168             return;
 169         len_ = loc-buf_;
 170         buf_[len_] = '\0';
 171     }
 172 };
 173
 174 inline std::ostream & operator<<(std::ostream &os, String const &aString)
 175 {
 176     os.write(aString.rawBuf(),aString.size());
 177     return os;
 178 }
 179
 180 inline bool operator<(const String &a, const String &b)
 181 {
 182     return a.cmp(b) < 0;
 183 }
 184
 185 const char *checkNullString(const char *p);
 186 int stringHasWhitespace(const char *);
 187 int stringHasCntl(const char *);
 188 char *strwordtok(char *buf, char **t);
 189
 190 #endif /* SQUID_SRC_SQUIDSTRING_H */
 191