Source/cmStringAlgorithms.h

   1 /* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   2    file Copyright.txt or https://cmake.org/licensing for details.  */
   3 #pragma once
   4
   5 #include "cmConfigure.h" // IWYU pragma: keep
   6
   7 #include <cctype>
   8 #include <cstring>
   9 #include <initializer_list>
  10 #include <sstream>
  11 #include <string>
  12 #include <utility>
  13 #include <vector>
  14
  15 #include <cm/string_view>
  16
  17 #include "cmRange.h"
  18 #include "cmValue.h"
  19
  20 /** String range type.  */
  21 using cmStringRange = cmRange<std::vector<std::string>::const_iterator>;
  22
  23 /** Returns length of a literal string.  */
  24 template <size_t N>
  25 constexpr size_t cmStrLen(const char (&/*str*/)[N])
  26 {
  27   return N - 1;
  28 }
  29
  30 /** Callable string comparison struct.  */
  31 struct cmStrCmp
  32 {
  33   cmStrCmp(std::string str)
  34     : Test_(std::move(str))
  35   {
  36   }
  37
  38   bool operator()(cm::string_view sv) const { return this->Test_ == sv; }
  39
  40 private:
  41   std::string const Test_;
  42 };
  43
  44 /** Returns true if the character @a ch is a whitespace character.  **/
  45 inline bool cmIsSpace(char ch)
  46 {
  47   return ((ch & 0x80) == 0) && std::isspace(ch);
  48 }
  49
  50 /** Returns a string that has whitespace removed from the start and the end. */
  51 std::string cmTrimWhitespace(cm::string_view str);
  52
  53 /** Returns a string that has quotes removed from the start and the end. */
  54 std::string cmRemoveQuotes(cm::string_view str);
  55
  56 /** Escape quotes in a string.  */
  57 std::string cmEscapeQuotes(cm::string_view str);
  58
  59 /** Joins elements of a range with separator into a single string.  */
  60 template <typename Range>
  61 std::string cmJoin(Range const& rng, cm::string_view separator)
  62 {
  63   if (rng.empty()) {
  64     return std::string();
  65   }
  66
  67   std::ostringstream os;
  68   auto it = rng.begin();
  69   auto const end = rng.end();
  70   os << *it;
  71   while (++it != end) {
  72     os << separator << *it;
  73   }
  74   return os.str();
  75 }
  76
  77 /**
  78  * Faster overloads for std::string ranges.
  79  * If @a initial is provided, it prepends the resulted string without
  80  * @a separator between them.
  81  */
  82 std::string cmJoin(std::vector<std::string> const& rng,
  83                    cm::string_view separator, cm::string_view initial = {});
  84
  85 std::string cmJoin(cmStringRange const& rng, cm::string_view separator,
  86                    cm::string_view initial = {});
  87
  88 /** Extract tokens that are separated by any of the characters in @a sep.  */
  89 std::vector<std::string> cmTokenize(cm::string_view str, cm::string_view sep);
  90
  91 /**
  92  * Expand the ; separated string @a arg into multiple arguments.
  93  * All found arguments are appended to @a argsOut.
  94  */
  95 void cmExpandList(cm::string_view arg, std::vector<std::string>& argsOut,
  96                   bool emptyArgs = false);
  97 inline void cmExpandList(cmValue arg, std::vector<std::string>& argsOut,
  98                          bool emptyArgs = false)
  99 {
 100   if (arg) {
 101     cmExpandList(*arg, argsOut, emptyArgs);
 102   }
 103 }
 104
 105 /**
 106  * Expand out any arguments in the string range [@a first, @a last) that have
 107  * ; separated strings into multiple arguments.  All found arguments are
 108  * appended to @a argsOut.
 109  */
 110 template <class InputIt>
 111 void cmExpandLists(InputIt first, InputIt last,
 112                    std::vector<std::string>& argsOut)
 113 {
 114   for (; first != last; ++first) {
 115     cmExpandList(*first, argsOut);
 116   }
 117 }
 118
 119 /**
 120  * Same as cmExpandList but a new vector is created containing
 121  * the expanded arguments from the string @a arg.
 122  */
 123 std::vector<std::string> cmExpandedList(cm::string_view arg,
 124                                         bool emptyArgs = false);
 125 inline std::vector<std::string> cmExpandedList(cmValue arg,
 126                                                bool emptyArgs = false)
 127 {
 128   if (!arg) {
 129     return {};
 130   }
 131   return cmExpandedList(*arg, emptyArgs);
 132 }
 133
 134 /**
 135  * Same as cmExpandList but a new vector is created containing the expanded
 136  * versions of all arguments in the string range [@a first, @a last).
 137  */
 138 template <class InputIt>
 139 std::vector<std::string> cmExpandedLists(InputIt first, InputIt last)
 140 {
 141   std::vector<std::string> argsOut;
 142   for (; first != last; ++first) {
 143     cmExpandList(*first, argsOut);
 144   }
 145   return argsOut;
 146 }
 147
 148 /** Concatenate string pieces into a single string.  */
 149 std::string cmCatViews(std::initializer_list<cm::string_view> views);
 150
 151 /** Utility class for cmStrCat.  */
 152 class cmAlphaNum
 153 {
 154 public:
 155   cmAlphaNum(cm::string_view view)
 156     : View_(view)
 157   {
 158   }
 159   cmAlphaNum(std::string const& str)
 160     : View_(str)
 161   {
 162   }
 163   cmAlphaNum(const char* str)
 164     : View_(str)
 165   {
 166   }
 167   cmAlphaNum(char ch)
 168     : View_(this->Digits_, 1)
 169   {
 170     this->Digits_[0] = ch;
 171   }
 172   cmAlphaNum(int val);
 173   cmAlphaNum(unsigned int val);
 174   cmAlphaNum(long int val);
 175   cmAlphaNum(unsigned long int val);
 176   cmAlphaNum(long long int val);
 177   cmAlphaNum(unsigned long long int val);
 178   cmAlphaNum(float val);
 179   cmAlphaNum(double val);
 180   cmAlphaNum(cmValue value)
 181     : View_(*value)
 182   {
 183   }
 184
 185   cm::string_view View() const { return this->View_; }
 186
 187 private:
 188   cm::string_view View_;
 189   char Digits_[32];
 190 };
 191
 192 /** Concatenate string pieces and numbers into a single string.  */
 193 template <typename... AV>
 194 inline std::string cmStrCat(cmAlphaNum const& a, cmAlphaNum const& b,
 195                             AV const&... args)
 196 {
 197   return cmCatViews(
 198     { a.View(), b.View(), static_cast<cmAlphaNum const&>(args).View()... });
 199 }
 200
 201 /** Joins wrapped elements of a range with separator into a single string.  */
 202 template <typename Range>
 203 std::string cmWrap(cm::string_view prefix, Range const& rng,
 204                    cm::string_view suffix, cm::string_view sep)
 205 {
 206   if (rng.empty()) {
 207     return std::string();
 208   }
 209   return cmCatViews(
 210     { prefix, cmJoin(rng, cmCatViews({ suffix, sep, prefix })), suffix });
 211 }
 212
 213 /** Joins wrapped elements of a range with separator into a single string.  */
 214 template <typename Range>
 215 std::string cmWrap(char prefix, Range const& rng, char suffix,
 216                    cm::string_view sep)
 217 {
 218   return cmWrap(cm::string_view(&prefix, 1), rng, cm::string_view(&suffix, 1),
 219                 sep);
 220 }
 221
 222 /** Returns true if string @a str starts with the character @a prefix.  */
 223 inline bool cmHasPrefix(cm::string_view str, char prefix)
 224 {
 225   return !str.empty() && (str.front() == prefix);
 226 }
 227
 228 /** Returns true if string @a str starts with string @a prefix.  */
 229 inline bool cmHasPrefix(cm::string_view str, cm::string_view prefix)
 230 {
 231   return str.compare(0, prefix.size(), prefix) == 0;
 232 }
 233
 234 /** Returns true if string @a str starts with string @a prefix.  */
 235 inline bool cmHasPrefix(cm::string_view str, cmValue prefix)
 236 {
 237   if (!prefix) {
 238     return false;
 239   }
 240
 241   return str.compare(0, prefix->size(), *prefix) == 0;
 242 }
 243
 244 /** Returns true if string @a str starts with string @a prefix.  */
 245 template <size_t N>
 246 inline bool cmHasLiteralPrefix(cm::string_view str, const char (&prefix)[N])
 247 {
 248   return cmHasPrefix(str, cm::string_view(prefix, N - 1));
 249 }
 250
 251 /** Returns true if string @a str ends with the character @a suffix.  */
 252 inline bool cmHasSuffix(cm::string_view str, char suffix)
 253 {
 254   return !str.empty() && (str.back() == suffix);
 255 }
 256
 257 /** Returns true if string @a str ends with string @a suffix.  */
 258 inline bool cmHasSuffix(cm::string_view str, cm::string_view suffix)
 259 {
 260   return str.size() >= suffix.size() &&
 261     str.compare(str.size() - suffix.size(), suffix.size(), suffix) == 0;
 262 }
 263
 264 /** Returns true if string @a str ends with string @a suffix.  */
 265 inline bool cmHasSuffix(cm::string_view str, cmValue suffix)
 266 {
 267   if (!suffix) {
 268     return false;
 269   }
 270
 271   return str.size() >= suffix->size() &&
 272     str.compare(str.size() - suffix->size(), suffix->size(), *suffix) == 0;
 273 }
 274
 275 /** Returns true if string @a str ends with string @a suffix.  */
 276 template <size_t N>
 277 inline bool cmHasLiteralSuffix(cm::string_view str, const char (&suffix)[N])
 278 {
 279   return cmHasSuffix(str, cm::string_view(suffix, N - 1));
 280 }
 281
 282 /** Removes an existing suffix character of from the string @a str.  */
 283 inline void cmStripSuffixIfExists(std::string& str, char suffix)
 284 {
 285   if (cmHasSuffix(str, suffix)) {
 286     str.pop_back();
 287   }
 288 }
 289
 290 /** Removes an existing suffix string of from the string @a str.  */
 291 inline void cmStripSuffixIfExists(std::string& str, cm::string_view suffix)
 292 {
 293   if (cmHasSuffix(str, suffix)) {
 294     str.resize(str.size() - suffix.size());
 295   }
 296 }
 297
 298 /** Converts a string to long. Expects that the whole string is an integer.  */
 299 bool cmStrToLong(const char* str, long* value);
 300 bool cmStrToLong(std::string const& str, long* value);
 301
 302 /** Converts a string to unsigned long. Expects that the whole string is an
 303  * integer */
 304 bool cmStrToULong(const char* str, unsigned long* value);
 305 bool cmStrToULong(std::string const& str, unsigned long* value);
 306
 307 /** Converts a string to long long. Expects that the whole string
 308  * is an integer */
 309 bool cmStrToLongLong(const char* str, long long* value);
 310 bool cmStrToLongLong(std::string const& str, long long* value);
 311
 312 /** Converts a string to unsigned long long. Expects that the whole string
 313  * is an integer */
 314 bool cmStrToULongLong(const char* str, unsigned long long* value);
 315 bool cmStrToULongLong(std::string const& str, unsigned long long* value);