1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4// Copied from strings/stringpiece.h with modifications
5//
6// A string-like object that points to a sized piece of memory.
7//
8// You can use StringPiece as a function or method parameter. A StringPiece
9// parameter can receive a double-quoted string literal argument, a "const
10// char*" argument, a string argument, or a StringPiece argument with no data
11// copying. Systematic use of StringPiece for arguments reduces data
12// copies and strlen() calls.
13//
14// Prefer passing StringPieces by value:
15// void MyFunction(StringPiece arg);
16// If circumstances require, you may also pass by const reference:
17// void MyFunction(const StringPiece& arg); // not preferred
18// Both of these have the same lifetime semantics. Passing by value
19// generates slightly smaller code. For more discussion, Googlers can see
20// the thread go/stringpiecebyvalue on c-users.
21
22#ifndef BASE_STRINGS_STRING_PIECE_H_
23#define BASE_STRINGS_STRING_PIECE_H_
24
25#include <stddef.h>
26
27#include <iosfwd>
28#include <string>
29#include <type_traits>
30
31#include "base/base_export.h"
32#include "base/logging.h"
33#include "base/strings/char_traits.h"
34#include "base/strings/string16.h"
35#include "base/strings/string_piece_forward.h"
36
37namespace base {
38
39// internal --------------------------------------------------------------------
40
41// Many of the StringPiece functions use different implementations for the
42// 8-bit and 16-bit versions, and we don't want lots of template expansions in
43// this (very common) header that will slow down compilation.
44//
45// So here we define overloaded functions called by the StringPiece template.
46// For those that share an implementation, the two versions will expand to a
47// template internal to the .cc file.
48namespace internal {
49
50BASE_EXPORT void CopyToString(const StringPiece& self, std::string* target);
51BASE_EXPORT void CopyToString(const StringPiece16& self, string16* target);
52
53BASE_EXPORT void AppendToString(const StringPiece& self, std::string* target);
54BASE_EXPORT void AppendToString(const StringPiece16& self, string16* target);
55
56BASE_EXPORT size_t copy(const StringPiece& self,
57 char* buf,
58 size_t n,
59 size_t pos);
60BASE_EXPORT size_t copy(const StringPiece16& self,
61 char16* buf,
62 size_t n,
63 size_t pos);
64
65BASE_EXPORT size_t find(const StringPiece& self,
66 const StringPiece& s,
67 size_t pos);
68BASE_EXPORT size_t find(const StringPiece16& self,
69 const StringPiece16& s,
70 size_t pos);
71BASE_EXPORT size_t find(const StringPiece& self,
72 char c,
73 size_t pos);
74BASE_EXPORT size_t find(const StringPiece16& self,
75 char16 c,
76 size_t pos);
77
78BASE_EXPORT size_t rfind(const StringPiece& self,
79 const StringPiece& s,
80 size_t pos);
81BASE_EXPORT size_t rfind(const StringPiece16& self,
82 const StringPiece16& s,
83 size_t pos);
84BASE_EXPORT size_t rfind(const StringPiece& self,
85 char c,
86 size_t pos);
87BASE_EXPORT size_t rfind(const StringPiece16& self,
88 char16 c,
89 size_t pos);
90
91BASE_EXPORT size_t find_first_of(const StringPiece& self,
92 const StringPiece& s,
93 size_t pos);
94BASE_EXPORT size_t find_first_of(const StringPiece16& self,
95 const StringPiece16& s,
96 size_t pos);
97
98BASE_EXPORT size_t find_first_not_of(const StringPiece& self,
99 const StringPiece& s,
100 size_t pos);
101BASE_EXPORT size_t find_first_not_of(const StringPiece16& self,
102 const StringPiece16& s,
103 size_t pos);
104BASE_EXPORT size_t find_first_not_of(const StringPiece& self,
105 char c,
106 size_t pos);
107BASE_EXPORT size_t find_first_not_of(const StringPiece16& self,
108 char16 c,
109 size_t pos);
110
111BASE_EXPORT size_t find_last_of(const StringPiece& self,
112 const StringPiece& s,
113 size_t pos);
114BASE_EXPORT size_t find_last_of(const StringPiece16& self,
115 const StringPiece16& s,
116 size_t pos);
117BASE_EXPORT size_t find_last_of(const StringPiece& self,
118 char c,
119 size_t pos);
120BASE_EXPORT size_t find_last_of(const StringPiece16& self,
121 char16 c,
122 size_t pos);
123
124BASE_EXPORT size_t find_last_not_of(const StringPiece& self,
125 const StringPiece& s,
126 size_t pos);
127BASE_EXPORT size_t find_last_not_of(const StringPiece16& self,
128 const StringPiece16& s,
129 size_t pos);
130BASE_EXPORT size_t find_last_not_of(const StringPiece16& self,
131 char16 c,
132 size_t pos);
133BASE_EXPORT size_t find_last_not_of(const StringPiece& self,
134 char c,
135 size_t pos);
136
137BASE_EXPORT StringPiece substr(const StringPiece& self,
138 size_t pos,
139 size_t n);
140BASE_EXPORT StringPiece16 substr(const StringPiece16& self,
141 size_t pos,
142 size_t n);
143
144#if DCHECK_IS_ON()
145// Asserts that begin <= end to catch some errors with iterator usage.
146BASE_EXPORT void AssertIteratorsInOrder(std::string::const_iterator begin,
147 std::string::const_iterator end);
148BASE_EXPORT void AssertIteratorsInOrder(string16::const_iterator begin,
149 string16::const_iterator end);
150#endif
151
152} // namespace internal
153
154// BasicStringPiece ------------------------------------------------------------
155
156// Defines the types, methods, operators, and data members common to both
157// StringPiece and StringPiece16. Do not refer to this class directly, but
158// rather to BasicStringPiece, StringPiece, or StringPiece16.
159//
160// This is templatized by string class type rather than character type, so
161// BasicStringPiece<std::string> or BasicStringPiece<base::string16>.
162template <typename STRING_TYPE> class BasicStringPiece {
163 public:
164 // Standard STL container boilerplate.
165 typedef size_t size_type;
166 typedef typename STRING_TYPE::value_type value_type;
167 typedef const value_type* pointer;
168 typedef const value_type& reference;
169 typedef const value_type& const_reference;
170 typedef ptrdiff_t difference_type;
171 typedef const value_type* const_iterator;
172 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
173
174 static const size_type npos;
175
176 public:
177 // We provide non-explicit singleton constructors so users can pass
178 // in a "const char*" or a "string" wherever a "StringPiece" is
179 // expected (likewise for char16, string16, StringPiece16).
180 constexpr BasicStringPiece() : ptr_(NULL), length_(0) {}
181 // TODO(dcheng): Construction from nullptr is not allowed for
182 // std::basic_string_view, so remove the special handling for it.
183 // Note: This doesn't just use STRING_TYPE::traits_type::length(), since that
184 // isn't constexpr until C++17.
185#if defined(COMPILER_GCC)
186 constexpr BasicStringPiece(const value_type* str) __attribute__((always_inline))
187#else
188 constexpr BasicStringPiece(const value_type* str)
189#endif
190 : ptr_(str), length_(!str ? 0 : CharTraits<value_type>::length(str)) {}
191 BasicStringPiece(const STRING_TYPE& str)
192 : ptr_(str.data()), length_(str.size()) {}
193 constexpr BasicStringPiece(const value_type* offset, size_type len)
194 : ptr_(offset), length_(len) {}
195 BasicStringPiece(const typename STRING_TYPE::const_iterator& begin,
196 const typename STRING_TYPE::const_iterator& end) {
197#if DCHECK_IS_ON()
198 // This assertion is done out-of-line to avoid bringing in logging.h and
199 // instantiating logging macros for every instantiation.
200 internal::AssertIteratorsInOrder(begin, end);
201#endif
202 length_ = static_cast<size_t>(std::distance(begin, end));
203
204 // The length test before assignment is to avoid dereferencing an iterator
205 // that may point to the end() of a string.
206 ptr_ = length_ > 0 ? &*begin : nullptr;
207 }
208
209 // data() may return a pointer to a buffer with embedded NULs, and the
210 // returned buffer may or may not be null terminated. Therefore it is
211 // typically a mistake to pass data() to a routine that expects a NUL
212 // terminated string.
213 constexpr const value_type* data() const { return ptr_; }
214 constexpr size_type size() const noexcept { return length_; }
215 constexpr size_type length() const noexcept { return length_; }
216 bool empty() const { return length_ == 0; }
217
218 void clear() {
219 ptr_ = NULL;
220 length_ = 0;
221 }
222 void set(const value_type* data, size_type len) {
223 ptr_ = data;
224 length_ = len;
225 }
226 void set(const value_type* str) {
227 ptr_ = str;
228 length_ = str ? STRING_TYPE::traits_type::length(str) : 0;
229 }
230
231 constexpr value_type operator[](size_type i) const {
232 CHECK(i < length_);
233 return ptr_[i];
234 }
235
236 value_type front() const {
237 CHECK_NE(0UL, length_);
238 return ptr_[0];
239 }
240
241 value_type back() const {
242 CHECK_NE(0UL, length_);
243 return ptr_[length_ - 1];
244 }
245
246 constexpr void remove_prefix(size_type n) {
247 CHECK(n <= length_);
248 ptr_ += n;
249 length_ -= n;
250 }
251
252 constexpr void remove_suffix(size_type n) {
253 CHECK(n <= length_);
254 length_ -= n;
255 }
256
257 constexpr int compare(BasicStringPiece x) const noexcept {
258 int r = CharTraits<value_type>::compare(
259 ptr_, x.ptr_, (length_ < x.length_ ? length_ : x.length_));
260 if (r == 0) {
261 if (length_ < x.length_) r = -1;
262 else if (length_ > x.length_) r = +1;
263 }
264 return r;
265 }
266
267 // This is the style of conversion preferred by std::string_view in C++17.
268 explicit operator STRING_TYPE() const { return as_string(); }
269
270 STRING_TYPE as_string() const {
271 // std::string doesn't like to take a NULL pointer even with a 0 size.
272 return empty() ? STRING_TYPE() : STRING_TYPE(data(), size());
273 }
274
275 const_iterator begin() const { return ptr_; }
276 const_iterator end() const { return ptr_ + length_; }
277 const_reverse_iterator rbegin() const {
278 return const_reverse_iterator(ptr_ + length_);
279 }
280 const_reverse_iterator rend() const {
281 return const_reverse_iterator(ptr_);
282 }
283
284 size_type max_size() const { return length_; }
285 size_type capacity() const { return length_; }
286
287 // Sets the value of the given string target type to be the current string.
288 // This saves a temporary over doing |a = b.as_string()|
289 void CopyToString(STRING_TYPE* target) const {
290 internal::CopyToString(*this, target);
291 }
292
293 void AppendToString(STRING_TYPE* target) const {
294 internal::AppendToString(*this, target);
295 }
296
297 size_type copy(value_type* buf, size_type n, size_type pos = 0) const {
298 return internal::copy(*this, buf, n, pos);
299 }
300
301 // Does "this" start with "x"
302 constexpr bool starts_with(BasicStringPiece x) const noexcept {
303 return (
304 (this->length_ >= x.length_) &&
305 (CharTraits<value_type>::compare(this->ptr_, x.ptr_, x.length_) == 0));
306 }
307
308 // Does "this" end with "x"
309 constexpr bool ends_with(BasicStringPiece x) const noexcept {
310 return ((this->length_ >= x.length_) &&
311 (CharTraits<value_type>::compare(
312 this->ptr_ + (this->length_ - x.length_), x.ptr_, x.length_) ==
313 0));
314 }
315
316 // find: Search for a character or substring at a given offset.
317 size_type find(const BasicStringPiece<STRING_TYPE>& s,
318 size_type pos = 0) const {
319 return internal::find(*this, s, pos);
320 }
321 size_type find(value_type c, size_type pos = 0) const {
322 return internal::find(*this, c, pos);
323 }
324
325 // rfind: Reverse find.
326 size_type rfind(const BasicStringPiece& s,
327 size_type pos = BasicStringPiece::npos) const {
328 return internal::rfind(*this, s, pos);
329 }
330 size_type rfind(value_type c, size_type pos = BasicStringPiece::npos) const {
331 return internal::rfind(*this, c, pos);
332 }
333
334 // find_first_of: Find the first occurence of one of a set of characters.
335 size_type find_first_of(const BasicStringPiece& s,
336 size_type pos = 0) const {
337 return internal::find_first_of(*this, s, pos);
338 }
339 size_type find_first_of(value_type c, size_type pos = 0) const {
340 return find(c, pos);
341 }
342
343 // find_first_not_of: Find the first occurence not of a set of characters.
344 size_type find_first_not_of(const BasicStringPiece& s,
345 size_type pos = 0) const {
346 return internal::find_first_not_of(*this, s, pos);
347 }
348 size_type find_first_not_of(value_type c, size_type pos = 0) const {
349 return internal::find_first_not_of(*this, c, pos);
350 }
351
352 // find_last_of: Find the last occurence of one of a set of characters.
353 size_type find_last_of(const BasicStringPiece& s,
354 size_type pos = BasicStringPiece::npos) const {
355 return internal::find_last_of(*this, s, pos);
356 }
357 size_type find_last_of(value_type c,
358 size_type pos = BasicStringPiece::npos) const {
359 return rfind(c, pos);
360 }
361
362 // find_last_not_of: Find the last occurence not of a set of characters.
363 size_type find_last_not_of(const BasicStringPiece& s,
364 size_type pos = BasicStringPiece::npos) const {
365 return internal::find_last_not_of(*this, s, pos);
366 }
367 size_type find_last_not_of(value_type c,
368 size_type pos = BasicStringPiece::npos) const {
369 return internal::find_last_not_of(*this, c, pos);
370 }
371
372 // substr.
373 BasicStringPiece substr(size_type pos,
374 size_type n = BasicStringPiece::npos) const {
375 return internal::substr(*this, pos, n);
376 }
377
378 protected:
379 const value_type* ptr_;
380 size_type length_;
381};
382
383template <typename STRING_TYPE>
384const typename BasicStringPiece<STRING_TYPE>::size_type
385BasicStringPiece<STRING_TYPE>::npos =
386 typename BasicStringPiece<STRING_TYPE>::size_type(-1);
387
388// MSVC doesn't like complex extern templates and DLLs.
389#if !defined(COMPILER_MSVC)
390extern template class BASE_EXPORT BasicStringPiece<std::string>;
391extern template class BASE_EXPORT BasicStringPiece<string16>;
392#endif
393
394// Comparison operators --------------------------------------------------------
395// operator ==
396template <typename StringT>
397constexpr bool operator==(BasicStringPiece<StringT> lhs,
398 BasicStringPiece<StringT> rhs) noexcept {
399 return lhs.size() == rhs.size() && lhs.compare(rhs) == 0;
400}
401
402// Here and below we make use of std::common_type_t to emulate an identity type
403// transformation. This creates a non-deduced context, so that we can compare
404// StringPieces with types that implicitly convert to StringPieces. See
405// https://wg21.link/n3766 for details.
406// Furthermore, we require dummy template parameters for these overloads to work
407// around a name mangling issue on Windows.
408template <typename StringT, int = 1>
409constexpr bool operator==(
410 BasicStringPiece<StringT> lhs,
411 std::common_type_t<BasicStringPiece<StringT>> rhs) noexcept {
412 return lhs.size() == rhs.size() && lhs.compare(rhs) == 0;
413}
414
415template <typename StringT, int = 2>
416constexpr bool operator==(std::common_type_t<BasicStringPiece<StringT>> lhs,
417 BasicStringPiece<StringT> rhs) noexcept {
418 return lhs.size() == rhs.size() && lhs.compare(rhs) == 0;
419}
420
421// operator !=
422template <typename StringT>
423constexpr bool operator!=(BasicStringPiece<StringT> lhs,
424 BasicStringPiece<StringT> rhs) noexcept {
425 return !(lhs == rhs);
426}
427
428template <typename StringT, int = 1>
429constexpr bool operator!=(
430 BasicStringPiece<StringT> lhs,
431 std::common_type_t<BasicStringPiece<StringT>> rhs) noexcept {
432 return !(lhs == rhs);
433}
434
435template <typename StringT, int = 2>
436constexpr bool operator!=(std::common_type_t<BasicStringPiece<StringT>> lhs,
437 BasicStringPiece<StringT> rhs) noexcept {
438 return !(lhs == rhs);
439}
440
441// operator <
442template <typename StringT>
443constexpr bool operator<(BasicStringPiece<StringT> lhs,
444 BasicStringPiece<StringT> rhs) noexcept {
445 return lhs.compare(rhs) < 0;
446}
447
448template <typename StringT, int = 1>
449constexpr bool operator<(
450 BasicStringPiece<StringT> lhs,
451 std::common_type_t<BasicStringPiece<StringT>> rhs) noexcept {
452 return lhs.compare(rhs) < 0;
453}
454
455template <typename StringT, int = 2>
456constexpr bool operator<(std::common_type_t<BasicStringPiece<StringT>> lhs,
457 BasicStringPiece<StringT> rhs) noexcept {
458 return lhs.compare(rhs) < 0;
459}
460
461// operator >
462template <typename StringT>
463constexpr bool operator>(BasicStringPiece<StringT> lhs,
464 BasicStringPiece<StringT> rhs) noexcept {
465 return rhs < lhs;
466}
467
468template <typename StringT, int = 1>
469constexpr bool operator>(
470 BasicStringPiece<StringT> lhs,
471 std::common_type_t<BasicStringPiece<StringT>> rhs) noexcept {
472 return rhs < lhs;
473}
474
475template <typename StringT, int = 2>
476constexpr bool operator>(std::common_type_t<BasicStringPiece<StringT>> lhs,
477 BasicStringPiece<StringT> rhs) noexcept {
478 return rhs < lhs;
479}
480
481// operator <=
482template <typename StringT>
483constexpr bool operator<=(BasicStringPiece<StringT> lhs,
484 BasicStringPiece<StringT> rhs) noexcept {
485 return !(rhs < lhs);
486}
487
488template <typename StringT, int = 1>
489constexpr bool operator<=(
490 BasicStringPiece<StringT> lhs,
491 std::common_type_t<BasicStringPiece<StringT>> rhs) noexcept {
492 return !(rhs < lhs);
493}
494
495template <typename StringT, int = 2>
496constexpr bool operator<=(std::common_type_t<BasicStringPiece<StringT>> lhs,
497 BasicStringPiece<StringT> rhs) noexcept {
498 return !(rhs < lhs);
499}
500
501// operator >=
502template <typename StringT>
503constexpr bool operator>=(BasicStringPiece<StringT> lhs,
504 BasicStringPiece<StringT> rhs) noexcept {
505 return !(lhs < rhs);
506}
507
508template <typename StringT, int = 1>
509constexpr bool operator>=(
510 BasicStringPiece<StringT> lhs,
511 std::common_type_t<BasicStringPiece<StringT>> rhs) noexcept {
512 return !(lhs < rhs);
513}
514
515template <typename StringT, int = 2>
516constexpr bool operator>=(std::common_type_t<BasicStringPiece<StringT>> lhs,
517 BasicStringPiece<StringT> rhs) noexcept {
518 return !(lhs < rhs);
519}
520
521BASE_EXPORT std::ostream& operator<<(std::ostream& o,
522 const StringPiece& piece);
523
524BASE_EXPORT std::ostream& operator<<(std::ostream& o,
525 const StringPiece16& piece);
526
527// Hashing ---------------------------------------------------------------------
528
529// We provide appropriate hash functions so StringPiece and StringPiece16 can
530// be used as keys in hash sets and maps.
531
532// This hash function is copied from base/strings/string16.h. We don't use the
533// ones already defined for string and string16 directly because it would
534// require the string constructors to be called, which we don't want.
535
536template <typename StringPieceType>
537struct StringPieceHashImpl {
538 std::size_t operator()(StringPieceType sp) const {
539 std::size_t result = 0;
540 for (auto c : sp)
541 result = (result * 131) + c;
542 return result;
543 }
544};
545
546using StringPieceHash = StringPieceHashImpl<StringPiece>;
547using StringPiece16Hash = StringPieceHashImpl<StringPiece16>;
548using WStringPieceHash = StringPieceHashImpl<WStringPiece>;
549
550} // namespace base
551
552#endif // BASE_STRINGS_STRING_PIECE_H_
553