string.h 27.6 KB
Newer Older
Kenton Varda's avatar
Kenton Varda committed
1 2
// Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
// Licensed under the MIT License:
3
//
Kenton Varda's avatar
Kenton Varda committed
4 5 6 7 8 9
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
10
//
Kenton Varda's avatar
Kenton Varda committed
11 12
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
13
//
Kenton Varda's avatar
Kenton Varda committed
14 15 16 17 18 19 20
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
21

22
#pragma once
23

24 25 26 27
#if defined(__GNUC__) && !KJ_HEADER_WARNINGS
#pragma GCC system_header
#endif

Kenton Varda's avatar
Kenton Varda committed
28
#include <initializer_list>
29 30 31 32
#include "array.h"
#include <string.h>

namespace kj {
33 34
  class StringPtr;
  class String;
35

36 37
  class StringTree;   // string-tree.h
}
Kenton Varda's avatar
Kenton Varda committed
38

39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
constexpr kj::StringPtr operator "" _kj(const char* str, size_t n);
// You can append _kj to a string literal to make its type be StringPtr. There are a few cases
// where you must do this for correctness:
// - When you want to declare a constexpr StringPtr. Without _kj, this is a compile error.
// - When you want to initialize a static/global StringPtr from a string literal without forcing
//   global constructor code to run at dynamic initialization time.
// - When you have a string literal that contains NUL characters. Without _kj, the string will
//   be considered to end at the first NUL.
// - When you want to initialize an ArrayPtr<const char> from a string literal, without including
//   the NUL terminator in the data. (Initializing an ArrayPtr from a regular string literal is
//   a compile error specifically due to this ambiguity.)
//
// In other cases, there should be no difference between initializing a StringPtr from a regular
// string literal vs. one with _kj (assuming the compiler is able to optimize away strlen() on a
// string literal).

namespace kj {
56

57 58
// Our STL string SFINAE trick does not work with GCC 4.7, but it works with Clang and GCC 4.8, so
// we'll just preprocess it out if not supported.
59
#if __clang__ || __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 8) || _MSC_VER
60 61 62
#define KJ_COMPILER_SUPPORTS_STL_STRING_INTEROP 1
#endif

Kenton Varda's avatar
Kenton Varda committed
63 64 65 66 67 68 69 70 71 72 73 74
// =======================================================================================
// StringPtr -- A NUL-terminated ArrayPtr<const char> containing UTF-8 text.
//
// NUL bytes are allowed to appear before the end of the string.  The only requirement is that
// a NUL byte appear immediately after the last byte of the content.  This terminator byte is not
// counted in the string's size.

class StringPtr {
public:
  inline StringPtr(): content("", 1) {}
  inline StringPtr(decltype(nullptr)): content("", 1) {}
  inline StringPtr(const char* value): content(value, strlen(value) + 1) {}
Kenton Varda's avatar
Kenton Varda committed
75 76 77
  inline StringPtr(const char* value, size_t size): content(value, size + 1) {
    KJ_IREQUIRE(value[size] == '\0', "StringPtr must be NUL-terminated.");
  }
78
  inline StringPtr(const char* begin, const char* end): StringPtr(begin, end - begin) {}
Kenton Varda's avatar
Kenton Varda committed
79 80
  inline StringPtr(const String& value);

81 82 83 84 85 86 87 88 89 90 91 92 93 94
#if KJ_COMPILER_SUPPORTS_STL_STRING_INTEROP
  template <typename T, typename = decltype(instance<T>().c_str())>
  inline StringPtr(const T& t): StringPtr(t.c_str()) {}
  // Allow implicit conversion from any class that has a c_str() method (namely, std::string).
  // We use a template trick to detect std::string in order to avoid including the header for
  // those who don't want it.

  template <typename T, typename = decltype(instance<T>().c_str())>
  inline operator T() const { return cStr(); }
  // Allow implicit conversion to any class that has a c_str() method (namely, std::string).
  // We use a template trick to detect std::string in order to avoid including the header for
  // those who don't want it.
#endif

95 96
  inline constexpr operator ArrayPtr<const char>() const;
  inline constexpr ArrayPtr<const char> asArray() const;
97
  inline ArrayPtr<const byte> asBytes() const { return asArray().asBytes(); }
Kenton Varda's avatar
Kenton Varda committed
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
  // Result does not include NUL terminator.

  inline const char* cStr() const { return content.begin(); }
  // Returns NUL-terminated string.

  inline size_t size() const { return content.size() - 1; }
  // Result does not include NUL terminator.

  inline char operator[](size_t index) const { return content[index]; }

  inline const char* begin() const { return content.begin(); }
  inline const char* end() const { return content.end() - 1; }

  inline bool operator==(decltype(nullptr)) const { return content.size() <= 1; }
  inline bool operator!=(decltype(nullptr)) const { return content.size() > 1; }

Kenton Varda's avatar
Kenton Varda committed
114 115 116 117 118 119
  inline bool operator==(const StringPtr& other) const;
  inline bool operator!=(const StringPtr& other) const { return !(*this == other); }
  inline bool operator< (const StringPtr& other) const;
  inline bool operator> (const StringPtr& other) const { return other < *this; }
  inline bool operator<=(const StringPtr& other) const { return !(other < *this); }
  inline bool operator>=(const StringPtr& other) const { return !(*this < other); }
Kenton Varda's avatar
Kenton Varda committed
120 121 122 123 124 125

  inline StringPtr slice(size_t start) const;
  inline ArrayPtr<const char> slice(size_t start, size_t end) const;
  // A string slice is only NUL-terminated if it is a suffix, so slice() has a one-parameter
  // version that assumes end = size().

126 127 128
  inline bool startsWith(const StringPtr& other) const;
  inline bool endsWith(const StringPtr& other) const;

129
  inline Maybe<size_t> findFirst(char c) const;
130
  inline Maybe<size_t> findLast(char c) const;
131

132 133
  template <typename T>
  T parseAs() const;
134 135 136 137 138
  // Parse string as template number type.
  // Integer numbers prefixed by "0x" and "0X" are parsed in base 16 (like strtoi with base 0).
  // Integer numbers prefixed by "0" are parsed in base 10 (unlike strtoi with base 0).
  // Overflowed integer numbers throw exception.
  // Overflowed floating numbers return inf.
139

Kenton Varda's avatar
Kenton Varda committed
140
private:
141
  inline constexpr StringPtr(ArrayPtr<const char> content): content(content) {}
Kenton Varda's avatar
Kenton Varda committed
142 143

  ArrayPtr<const char> content;
144 145

  friend constexpr kj::StringPtr (::operator "" _kj)(const char* str, size_t n);
Kenton Varda's avatar
Kenton Varda committed
146 147 148 149
};

inline bool operator==(const char* a, const StringPtr& b) { return b == a; }
inline bool operator!=(const char* a, const StringPtr& b) { return b != a; }
150

151 152 153 154 155 156 157 158 159 160 161 162 163 164
template <> char StringPtr::parseAs<char>() const;
template <> signed char StringPtr::parseAs<signed char>() const;
template <> unsigned char StringPtr::parseAs<unsigned char>() const;
template <> short StringPtr::parseAs<short>() const;
template <> unsigned short StringPtr::parseAs<unsigned short>() const;
template <> int StringPtr::parseAs<int>() const;
template <> unsigned StringPtr::parseAs<unsigned>() const;
template <> long StringPtr::parseAs<long>() const;
template <> unsigned long StringPtr::parseAs<unsigned long>() const;
template <> long long StringPtr::parseAs<long long>() const;
template <> unsigned long long StringPtr::parseAs<unsigned long long>() const;
template <> float StringPtr::parseAs<float>() const;
template <> double StringPtr::parseAs<double>() const;

165
// =======================================================================================
Kenton Varda's avatar
Kenton Varda committed
166 167 168 169 170 171 172 173
// String -- A NUL-terminated Array<char> containing UTF-8 text.
//
// NUL bytes are allowed to appear before the end of the string.  The only requirement is that
// a NUL byte appear immediately after the last byte of the content.  This terminator byte is not
// counted in the string's size.
//
// To allocate a String, you must call kj::heapString().  We do not implement implicit copying to
// the heap because this hides potential inefficiency from the developer.
174 175 176 177

class String {
public:
  String() = default;
Kenton Varda's avatar
Kenton Varda committed
178 179 180
  inline String(decltype(nullptr)): content(nullptr) {}
  inline String(char* value, size_t size, const ArrayDisposer& disposer);
  // Does not copy.  `size` does not include NUL terminator, but `value` must be NUL-terminated.
181 182
  inline explicit String(Array<char> buffer);
  // Does not copy.  Requires `buffer` ends with `\0`.
183

Kenton Varda's avatar
Kenton Varda committed
184 185
  inline operator ArrayPtr<char>();
  inline operator ArrayPtr<const char>() const;
186 187
  inline ArrayPtr<char> asArray();
  inline ArrayPtr<const char> asArray() const;
188 189
  inline ArrayPtr<byte> asBytes() { return asArray().asBytes(); }
  inline ArrayPtr<const byte> asBytes() const { return asArray().asBytes(); }
Kenton Varda's avatar
Kenton Varda committed
190 191
  // Result does not include NUL terminator.

192 193 194 195
  inline Array<char> releaseArray() { return kj::mv(content); }
  // Disowns the backing array (which includes the NUL terminator) and returns it. The String value
  // is clobbered (as if moved away).

Kenton Varda's avatar
Kenton Varda committed
196 197 198 199 200 201 202
  inline const char* cStr() const;

  inline size_t size() const;
  // Result does not include NUL terminator.

  inline char operator[](size_t index) const;
  inline char& operator[](size_t index);
203

Kenton Varda's avatar
Kenton Varda committed
204 205 206 207
  inline char* begin();
  inline char* end();
  inline const char* begin() const;
  inline const char* end() const;
208

Kenton Varda's avatar
Kenton Varda committed
209 210 211
  inline bool operator==(decltype(nullptr)) const { return content.size() <= 1; }
  inline bool operator!=(decltype(nullptr)) const { return content.size() > 1; }

Kenton Varda's avatar
Kenton Varda committed
212
  inline bool operator==(const StringPtr& other) const { return StringPtr(*this) == other; }
213 214 215 216 217
  inline bool operator!=(const StringPtr& other) const { return StringPtr(*this) != other; }
  inline bool operator< (const StringPtr& other) const { return StringPtr(*this) <  other; }
  inline bool operator> (const StringPtr& other) const { return StringPtr(*this) >  other; }
  inline bool operator<=(const StringPtr& other) const { return StringPtr(*this) <= other; }
  inline bool operator>=(const StringPtr& other) const { return StringPtr(*this) >= other; }
218

219 220 221
  inline bool startsWith(const StringPtr& other) const { return StringPtr(*this).startsWith(other);}
  inline bool endsWith(const StringPtr& other) const { return StringPtr(*this).endsWith(other); }

222 223 224 225 226
  inline StringPtr slice(size_t start) const { return StringPtr(*this).slice(start); }
  inline ArrayPtr<const char> slice(size_t start, size_t end) const {
    return StringPtr(*this).slice(start, end);
  }

227
  inline Maybe<size_t> findFirst(char c) const { return StringPtr(*this).findFirst(c); }
228
  inline Maybe<size_t> findLast(char c) const { return StringPtr(*this).findLast(c); }
229

230 231 232 233
  template <typename T>
  T parseAs() const { return StringPtr(*this).parseAs<T>(); }
  // Parse as number

234 235 236 237
private:
  Array<char> content;
};

Kenton Varda's avatar
Kenton Varda committed
238 239 240 241 242 243 244 245 246 247
inline bool operator==(const char* a, const String& b) { return b == a; }
inline bool operator!=(const char* a, const String& b) { return b != a; }

String heapString(size_t size);
// Allocate a String of the given size on the heap, not including NUL terminator.  The NUL
// terminator will be initialized automatically but the rest of the content is not initialized.

String heapString(const char* value);
String heapString(const char* value, size_t size);
String heapString(StringPtr value);
248
String heapString(const String& value);
Kenton Varda's avatar
Kenton Varda committed
249 250 251
String heapString(ArrayPtr<const char> value);
// Allocates a copy of the given value on the heap.

Kenton Varda's avatar
Kenton Varda committed
252 253 254 255
// =======================================================================================
// Magic str() function which transforms parameters to text and concatenates them into one big
// String.

256
namespace _ {  // private
Kenton Varda's avatar
Kenton Varda committed
257 258 259 260 261 262 263 264 265 266

inline size_t sum(std::initializer_list<size_t> nums) {
  size_t result = 0;
  for (auto num: nums) {
    result += num;
  }
  return result;
}

inline char* fill(char* ptr) { return ptr; }
267
inline char* fillLimited(char* ptr, char* limit) { return ptr; }
Kenton Varda's avatar
Kenton Varda committed
268

269 270
template <typename... Rest>
char* fill(char* __restrict__ target, const StringTree& first, Rest&&... rest);
271 272
template <typename... Rest>
char* fillLimited(char* __restrict__ target, char* limit, const StringTree& first, Rest&&... rest);
273 274 275 276
// Make str() work with stringifiers that return StringTree by patching fill().
//
// Defined in string-tree.h.

Kenton Varda's avatar
Kenton Varda committed
277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300
template <typename First, typename... Rest>
char* fill(char* __restrict__ target, const First& first, Rest&&... rest) {
  auto i = first.begin();
  auto end = first.end();
  while (i != end) {
    *target++ = *i++;
  }
  return fill(target, kj::fwd<Rest>(rest)...);
}

template <typename... Params>
String concat(Params&&... params) {
  // Concatenate a bunch of containers into a single Array.  The containers can be anything that
  // is iterable and whose elements can be converted to `char`.

  String result = heapString(sum({params.size()...}));
  fill(result.begin(), kj::fwd<Params>(params)...);
  return result;
}

inline String concat(String&& arr) {
  return kj::mv(arr);
}

301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321
template <typename First, typename... Rest>
char* fillLimited(char* __restrict__ target, char* limit, const First& first, Rest&&... rest) {
  auto i = first.begin();
  auto end = first.end();
  while (i != end) {
    if (target == limit) return target;
    *target++ = *i++;
  }
  return fillLimited(target, limit, kj::fwd<Rest>(rest)...);
}

template <typename T>
class Delimited;
// Delimits a sequence of type T with a string delimiter. Implements kj::delimited().

template <typename T, typename... Rest>
char* fill(char* __restrict__ target, Delimited<T> first, Rest&&... rest);
template <typename T, typename... Rest>
char* fillLimited(char* __restrict__ target, char* limit, Delimited<T> first,Rest&&... rest);
// As with StringTree, we special-case Delimited<T>.

Kenton Varda's avatar
Kenton Varda committed
322 323 324 325 326 327 328 329 330 331 332 333 334 335
struct Stringifier {
  // This is a dummy type with only one instance: STR (below).  To make an arbitrary type
  // stringifiable, define `operator*(Stringifier, T)` to return an iterable container of `char`.
  // The container type must have a `size()` method.  Be sure to declare the operator in the same
  // namespace as `T` **or** in the global scope.
  //
  // A more usual way to accomplish what we're doing here would be to require that you define
  // a function like `toString(T)` and then rely on argument-dependent lookup.  However, this has
  // the problem that it pollutes other people's namespaces and even the global namespace.  For
  // example, some other project may already have functions called `toString` which do something
  // different.  Declaring `operator*` with `Stringifier` as the left operand cannot conflict with
  // anything.

  inline ArrayPtr<const char> operator*(ArrayPtr<const char> s) const { return s; }
336
  inline ArrayPtr<const char> operator*(ArrayPtr<char> s) const { return s; }
Kenton Varda's avatar
Kenton Varda committed
337 338 339 340
  inline ArrayPtr<const char> operator*(const Array<const char>& s) const { return s; }
  inline ArrayPtr<const char> operator*(const Array<char>& s) const { return s; }
  template<size_t n>
  inline ArrayPtr<const char> operator*(const CappedArray<char, n>& s) const { return s; }
341 342
  template<size_t n>
  inline ArrayPtr<const char> operator*(const FixedArray<char, n>& s) const { return s; }
Kenton Varda's avatar
Kenton Varda committed
343 344 345 346
  inline ArrayPtr<const char> operator*(const char* s) const { return arrayPtr(s, strlen(s)); }
  inline ArrayPtr<const char> operator*(const String& s) const { return s.asArray(); }
  inline ArrayPtr<const char> operator*(const StringPtr& s) const { return s.asArray(); }

Kenton Varda's avatar
Kenton Varda committed
347 348 349
  inline Range<char> operator*(const Range<char>& r) const { return r; }
  inline Repeat<char> operator*(const Repeat<char>& r) const { return r; }

Kenton Varda's avatar
Kenton Varda committed
350 351 352 353 354 355
  inline FixedArray<char, 1> operator*(char c) const {
    FixedArray<char, 1> result;
    result[0] = c;
    return result;
  }

356
  StringPtr operator*(decltype(nullptr)) const;
Kenton Varda's avatar
Kenton Varda committed
357 358
  StringPtr operator*(bool b) const;

359 360 361 362 363 364 365 366 367 368
  CappedArray<char, 5> operator*(signed char i) const;
  CappedArray<char, 5> operator*(unsigned char i) const;
  CappedArray<char, sizeof(short) * 3 + 2> operator*(short i) const;
  CappedArray<char, sizeof(unsigned short) * 3 + 2> operator*(unsigned short i) const;
  CappedArray<char, sizeof(int) * 3 + 2> operator*(int i) const;
  CappedArray<char, sizeof(unsigned int) * 3 + 2> operator*(unsigned int i) const;
  CappedArray<char, sizeof(long) * 3 + 2> operator*(long i) const;
  CappedArray<char, sizeof(unsigned long) * 3 + 2> operator*(unsigned long i) const;
  CappedArray<char, sizeof(long long) * 3 + 2> operator*(long long i) const;
  CappedArray<char, sizeof(unsigned long long) * 3 + 2> operator*(unsigned long long i) const;
Kenton Varda's avatar
Kenton Varda committed
369 370
  CappedArray<char, 24> operator*(float f) const;
  CappedArray<char, 32> operator*(double f) const;
371
  CappedArray<char, sizeof(const void*) * 2 + 1> operator*(const void* s) const;
Kenton Varda's avatar
Kenton Varda committed
372 373

  template <typename T>
374
  _::Delimited<ArrayPtr<T>> operator*(ArrayPtr<T> arr) const;
Kenton Varda's avatar
Kenton Varda committed
375
  template <typename T>
376
  _::Delimited<ArrayPtr<const T>> operator*(const Array<T>& arr) const;
377 378 379 380 381

#if KJ_COMPILER_SUPPORTS_STL_STRING_INTEROP  // supports expression SFINAE?
  template <typename T, typename Result = decltype(instance<T>().toString())>
  inline Result operator*(T&& value) const { return kj::fwd<T>(value).toString(); }
#endif
Kenton Varda's avatar
Kenton Varda committed
382
};
383
static KJ_CONSTEXPR(const) Stringifier STR = Stringifier();
Kenton Varda's avatar
Kenton Varda committed
384

385
}  // namespace _ (private)
Kenton Varda's avatar
Kenton Varda committed
386 387

template <typename T>
388
auto toCharSequence(T&& value) -> decltype(_::STR * kj::fwd<T>(value)) {
Kenton Varda's avatar
Kenton Varda committed
389 390 391 392 393 394 395 396
  // Returns an iterable of chars that represent a textual representation of the value, suitable
  // for debugging.
  //
  // Most users should use str() instead, but toCharSequence() may occasionally be useful to avoid
  // heap allocation overhead that str() implies.
  //
  // To specialize this function for your type, see KJ_STRINGIFY.

397
  return _::STR * kj::fwd<T>(value);
Kenton Varda's avatar
Kenton Varda committed
398 399
}

400 401 402 403 404
CappedArray<char, sizeof(unsigned char) * 2 + 1> hex(unsigned char i);
CappedArray<char, sizeof(unsigned short) * 2 + 1> hex(unsigned short i);
CappedArray<char, sizeof(unsigned int) * 2 + 1> hex(unsigned int i);
CappedArray<char, sizeof(unsigned long) * 2 + 1> hex(unsigned long i);
CappedArray<char, sizeof(unsigned long long) * 2 + 1> hex(unsigned long long i);
Kenton Varda's avatar
Kenton Varda committed
405 406 407 408 409 410 411 412 413

template <typename... Params>
String str(Params&&... params) {
  // Magic function which builds a string from a bunch of arbitrary values.  Example:
  //     str(1, " / ", 2, " = ", 0.5)
  // returns:
  //     "1 / 2 = 0.5"
  // To teach `str` how to stringify a type, see `Stringifier`.

414
  return _::concat(toCharSequence(kj::fwd<Params>(params))...);
Kenton Varda's avatar
Kenton Varda committed
415 416 417 418 419
}

inline String str(String&& s) { return mv(s); }
// Overload to prevent redundant allocation.

420 421 422 423
template <typename T>
_::Delimited<T> delimited(T&& arr, kj::StringPtr delim);
// Use to stringify an array.

Kenton Varda's avatar
Kenton Varda committed
424 425 426
template <typename T>
String strArray(T&& arr, const char* delim) {
  size_t delimLen = strlen(delim);
427
  KJ_STACK_ARRAY(decltype(_::STR * arr[0]), pieces, kj::size(arr), 8, 32);
Kenton Varda's avatar
Kenton Varda committed
428
  size_t size = 0;
429
  for (size_t i = 0; i < kj::size(arr); i++) {
Kenton Varda's avatar
Kenton Varda committed
430
    if (i > 0) size += delimLen;
431
    pieces[i] = _::STR * arr[i];
Kenton Varda's avatar
Kenton Varda committed
432 433 434 435 436
    size += pieces[i].size();
  }

  String result = heapString(size);
  char* pos = result.begin();
437
  for (size_t i = 0; i < kj::size(arr); i++) {
Kenton Varda's avatar
Kenton Varda committed
438 439 440 441
    if (i > 0) {
      memcpy(pos, delim, delimLen);
      pos += delimLen;
    }
442
    pos = _::fill(pos, pieces[i]);
Kenton Varda's avatar
Kenton Varda committed
443 444 445 446
  }
  return result;
}

447 448 449 450 451 452 453 454 455 456 457 458 459
template <typename... Params>
StringPtr strPreallocated(ArrayPtr<char> buffer, Params&&... params) {
  // Like str() but writes into a preallocated buffer. If the buffer is not long enough, the result
  // is truncated (but still NUL-terminated).
  //
  // This can be used like:
  //
  //     char buffer[256];
  //     StringPtr text = strPreallocated(buffer, params...);
  //
  // This is useful for optimization. It can also potentially be used safely in async signal
  // handlers. HOWEVER, to use in an async signal handler, all of the stringifiers for the inputs
  // must also be signal-safe. KJ guarantees signal safety when stringifying any built-in integer
460 461 462 463
  // type (but NOT floating-points), basic char/byte sequences (ArrayPtr<byte>, String, etc.), as
  // well as Array<T> as long as T can also be stringified safely. To safely stringify a delimited
  // array, you must use kj::delimited(arr, delim) rather than the deprecated
  // kj::strArray(arr, delim).
464 465 466 467 468 469 470

  char* end = _::fillLimited(buffer.begin(), buffer.end() - 1,
      toCharSequence(kj::fwd<Params>(params))...);
  *end = '\0';
  return StringPtr(buffer.begin(), end);
}

471
namespace _ {  // private
Kenton Varda's avatar
Kenton Varda committed
472 473

template <typename T>
474 475
inline _::Delimited<ArrayPtr<T>> Stringifier::operator*(ArrayPtr<T> arr) const {
  return _::Delimited<ArrayPtr<T>>(arr, ", ");
Kenton Varda's avatar
Kenton Varda committed
476 477 478
}

template <typename T>
479 480
inline _::Delimited<ArrayPtr<const T>> Stringifier::operator*(const Array<T>& arr) const {
  return _::Delimited<ArrayPtr<const T>>(arr, ", ");
Kenton Varda's avatar
Kenton Varda committed
481 482
}

483
}  // namespace _ (private)
Kenton Varda's avatar
Kenton Varda committed
484

485
#define KJ_STRINGIFY(...) operator*(::kj::_::Stringifier, __VA_ARGS__)
Kenton Varda's avatar
Kenton Varda committed
486 487 488 489 490 491 492 493 494 495
// Defines a stringifier for a custom type.  Example:
//
//    class Foo {...};
//    inline StringPtr KJ_STRINGIFY(const Foo& foo) { return foo.name(); }
//
// This allows Foo to be passed to str().
//
// The function should be declared either in the same namespace as the target type or in the global
// namespace.  It can return any type which is an iterable container of chars.

Kenton Varda's avatar
Kenton Varda committed
496 497 498
// =======================================================================================
// Inline implementation details.

499
inline StringPtr::StringPtr(const String& value): content(value.cStr(), value.size() + 1) {}
Kenton Varda's avatar
Kenton Varda committed
500

501 502
inline constexpr StringPtr::operator ArrayPtr<const char>() const {
  return ArrayPtr<const char>(content.begin(), content.size() - 1);
Kenton Varda's avatar
Kenton Varda committed
503 504
}

505 506
inline constexpr ArrayPtr<const char> StringPtr::asArray() const {
  return ArrayPtr<const char>(content.begin(), content.size() - 1);
Kenton Varda's avatar
Kenton Varda committed
507 508
}

Kenton Varda's avatar
Kenton Varda committed
509
inline bool StringPtr::operator==(const StringPtr& other) const {
Kenton Varda's avatar
Kenton Varda committed
510 511 512 513
  return content.size() == other.content.size() &&
      memcmp(content.begin(), other.content.begin(), content.size() - 1) == 0;
}

Kenton Varda's avatar
Kenton Varda committed
514 515 516 517 518 519 520
inline bool StringPtr::operator<(const StringPtr& other) const {
  bool shorter = content.size() < other.content.size();
  int cmp = memcmp(content.begin(), other.content.begin(),
                   shorter ? content.size() : other.content.size());
  return cmp < 0 || (cmp == 0 && shorter);
}

Kenton Varda's avatar
Kenton Varda committed
521 522 523 524 525 526 527
inline StringPtr StringPtr::slice(size_t start) const {
  return StringPtr(content.slice(start, content.size()));
}
inline ArrayPtr<const char> StringPtr::slice(size_t start, size_t end) const {
  return content.slice(start, end);
}

528 529 530 531 532 533 534 535 536
inline bool StringPtr::startsWith(const StringPtr& other) const {
  return other.content.size() <= content.size() &&
      memcmp(content.begin(), other.content.begin(), other.size()) == 0;
}
inline bool StringPtr::endsWith(const StringPtr& other) const {
  return other.content.size() <= content.size() &&
      memcmp(end() - other.size(), other.content.begin(), other.size()) == 0;
}

537 538 539 540 541 542 543 544 545
inline Maybe<size_t> StringPtr::findFirst(char c) const {
  const char* pos = reinterpret_cast<const char*>(memchr(content.begin(), c, size()));
  if (pos == nullptr) {
    return nullptr;
  } else {
    return pos - content.begin();
  }
}

546
inline Maybe<size_t> StringPtr::findLast(char c) const {
547 548 549 550
  for (size_t i = size(); i > 0; --i) {
    if (content[i-1] == c) {
      return i-1;
    }
551
  }
552
  return nullptr;
553 554
}

Kenton Varda's avatar
Kenton Varda committed
555 556 557 558 559 560 561
inline String::operator ArrayPtr<char>() {
  return content == nullptr ? ArrayPtr<char>(nullptr) : content.slice(0, content.size() - 1);
}
inline String::operator ArrayPtr<const char>() const {
  return content == nullptr ? ArrayPtr<const char>(nullptr) : content.slice(0, content.size() - 1);
}

562 563 564 565
inline ArrayPtr<char> String::asArray() {
  return content == nullptr ? ArrayPtr<char>(nullptr) : content.slice(0, content.size() - 1);
}
inline ArrayPtr<const char> String::asArray() const {
Kenton Varda's avatar
Kenton Varda committed
566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582
  return content == nullptr ? ArrayPtr<const char>(nullptr) : content.slice(0, content.size() - 1);
}

inline const char* String::cStr() const { return content == nullptr ? "" : content.begin(); }

inline size_t String::size() const { return content == nullptr ? 0 : content.size() - 1; }

inline char String::operator[](size_t index) const { return content[index]; }
inline char& String::operator[](size_t index) { return content[index]; }

inline char* String::begin() { return content == nullptr ? nullptr : content.begin(); }
inline char* String::end() { return content == nullptr ? nullptr : content.end() - 1; }
inline const char* String::begin() const { return content == nullptr ? nullptr : content.begin(); }
inline const char* String::end() const { return content == nullptr ? nullptr : content.end() - 1; }

inline String::String(char* value, size_t size, const ArrayDisposer& disposer)
    : content(value, size + 1, disposer) {
Kenton Varda's avatar
Kenton Varda committed
583
  KJ_IREQUIRE(value[size] == '\0', "String must be NUL-terminated.");
Kenton Varda's avatar
Kenton Varda committed
584 585
}

586 587 588 589
inline String::String(Array<char> buffer): content(kj::mv(buffer)) {
  KJ_IREQUIRE(content.size() > 0 && content.back() == '\0', "String must be NUL-terminated.");
}

Kenton Varda's avatar
Kenton Varda committed
590 591 592 593 594 595
inline String heapString(const char* value) {
  return heapString(value, strlen(value));
}
inline String heapString(StringPtr value) {
  return heapString(value.begin(), value.size());
}
596 597 598
inline String heapString(const String& value) {
  return heapString(value.begin(), value.size());
}
Kenton Varda's avatar
Kenton Varda committed
599 600
inline String heapString(ArrayPtr<const char> value) {
  return heapString(value.begin(), value.size());
601 602
}

603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697
namespace _ {  // private

template <typename T>
class Delimited {
public:
  Delimited(T array, kj::StringPtr delimiter)
      : array(kj::fwd<T>(array)), delimiter(delimiter) {}

  // TODO(someday): In theory we should support iteration as a character sequence, but the iterator
  //   will be pretty complicated.

  size_t size() {
    ensureStringifiedInitialized();

    size_t result = 0;
    bool first = true;
    for (auto& e: stringified) {
      if (first) {
        first = false;
      } else {
        result += delimiter.size();
      }
      result += e.size();
    }
    return result;
  }

  char* flattenTo(char* __restrict__ target) {
    ensureStringifiedInitialized();

    bool first = true;
    for (auto& elem: stringified) {
      if (first) {
        first = false;
      } else {
        target = fill(target, delimiter);
      }
      target = fill(target, elem);
    }
    return target;
  }

  char* flattenTo(char* __restrict__ target, char* limit) {
    // This is called in the strPreallocated(). We want to avoid allocation. size() will not have
    // been called in this case, so hopefully `stringified` is still uninitialized. We will
    // stringify each item and immediately use it.
    bool first = true;
    for (auto&& elem: array) {
      if (target == limit) return target;
      if (first) {
        first = false;
      } else {
        target = fillLimited(target, limit, delimiter);
      }
      target = fillLimited(target, limit, kj::toCharSequence(elem));
    }
    return target;
  }

private:
  typedef decltype(toCharSequence(*instance<T>().begin())) StringifiedItem;
  T array;
  kj::StringPtr delimiter;
  Array<StringifiedItem> stringified;

  void ensureStringifiedInitialized() {
    if (array.size() > 0 && stringified.size() == 0) {
      stringified = KJ_MAP(e, array) { return toCharSequence(e); };
    }
  }
};

template <typename T, typename... Rest>
char* fill(char* __restrict__ target, Delimited<T> first, Rest&&... rest) {
  target = first.flattenTo(target);
  return fill(target, kj::fwd<Rest>(rest)...);
}
template <typename T, typename... Rest>
char* fillLimited(char* __restrict__ target, char* limit, Delimited<T> first, Rest&&... rest) {
  target = first.flattenTo(target, limit);
  return fillLimited(target, limit, kj::fwd<Rest>(rest)...);
}

template <typename T>
inline Delimited<T>&& KJ_STRINGIFY(Delimited<T>&& delimited) { return kj::mv(delimited); }
template <typename T>
inline const Delimited<T>& KJ_STRINGIFY(const Delimited<T>& delimited) { return delimited; }

}  // namespace _ (private)

template <typename T>
_::Delimited<T> delimited(T&& arr, kj::StringPtr delim) {
  return _::Delimited<T>(kj::fwd<T>(arr), delim);
}

698 699
}  // namespace kj

700 701 702
constexpr kj::StringPtr operator "" _kj(const char* str, size_t n) {
  return kj::StringPtr(kj::ArrayPtr<const char>(str, n + 1));
};