src/SquidString.h

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