/src/icu/source/common/unicode/stringpiece.h

Source (jump to first uncovered line)
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
// Copyright (C) 2009-2013, International Business Machines
// Corporation and others. All Rights Reserved.
//
// Copyright 2001 and onwards Google Inc.
// Author: Sanjay Ghemawat

// This code is a contribution of Google code, and the style used here is
// a compromise between the original Google code and the ICU coding guidelines.
// For example, data types are ICU-ified (size_t,int->int32_t),
// and API comments doxygen-ified, but function names and behavior are
// as in the original, if possible.
// Assertion-style error handling, not available in ICU, was changed to
// parameter "pinning" similar to UnicodeString.
//
// In addition, this is only a partial port of the original Google code,
// limited to what was needed so far. The (nearly) complete original code
// is in the ICU svn repository at icuhtml/trunk/design/strings/contrib
// (see ICU ticket 6765, r25517).

#ifndef __STRINGPIECE_H__
#define __STRINGPIECE_H__

/**
 * \file 
 * \brief C++ API: StringPiece: Read-only byte string wrapper class.
 */

#include "unicode/utypes.h"
#include "unicode/uobject.h"
#include "unicode/std_string.h"

// Arghh!  I wish C++ literals were "string".

U_NAMESPACE_BEGIN

/**
 * A string-like object that points to a sized piece of memory.
 *
 * We provide non-explicit singleton constructors so users can pass
 * in a "const char*" or a "string" wherever a "StringPiece" is
 * expected.
 *
 * Functions or methods may use StringPiece parameters to accept either a
 * "const char*" or a "string" value that will be implicitly converted to a
 * StringPiece.
 *
 * Systematic usage of StringPiece is encouraged as it will reduce unnecessary
 * conversions from "const char*" to "string" and back again.
 *
 * @stable ICU 4.2
 */
class U_COMMON_API StringPiece : public UMemory {
 private:
  const char*   ptr_;
  int32_t       length_;

 public:
  /**
   * Default constructor, creates an empty StringPiece.
   * @stable ICU 4.2
   */
  StringPiece() : ptr_(NULL), length_(0) { }
  /**
   * Constructs from a NUL-terminated const char * pointer.
   * @param str a NUL-terminated const char * pointer
   * @stable ICU 4.2
   */
  StringPiece(const char* str);
  /**
   * Constructs from a std::string.
   * @stable ICU 4.2
   */
  StringPiece(const std::string& str)
    : ptr_(str.data()), length_(static_cast<int32_t>(str.size())) { }
  /**
   * Constructs from a const char * pointer and a specified length.
   * @param offset a const char * pointer (need not be terminated)
   * @param len the length of the string; must be non-negative
   * @stable ICU 4.2
   */
  StringPiece(const char* offset, int32_t len) : ptr_(offset), length_(len) { }
  /**
   * Substring of another StringPiece.
   * @param x the other StringPiece
   * @param pos start position in x; must be non-negative and <= x.length().
   * @stable ICU 4.2
   */
  StringPiece(const StringPiece& x, int32_t pos);
  /**
   * Substring of another StringPiece.
   * @param x the other StringPiece
   * @param pos start position in x; must be non-negative and <= x.length().
   * @param len length of the substring;
   *            must be non-negative and will be pinned to at most x.length() - pos.
   * @stable ICU 4.2
   */
  StringPiece(const StringPiece& x, int32_t pos, int32_t len);

  /**
   * Returns the string pointer. May be NULL if it is empty.
   *
   * data() may return a pointer to a buffer with embedded NULs, and the
   * returned buffer may or may not be null terminated.  Therefore it is
   * typically a mistake to pass data() to a routine that expects a NUL
   * terminated string.
   * @return the string pointer
   * @stable ICU 4.2
   */
  const char* data() const { return ptr_; }
  /**
   * Returns the string length. Same as length().
   * @return the string length
   * @stable ICU 4.2
   */
  int32_t size() const { return length_; }
  /**
   * Returns the string length. Same as size().
   * @return the string length
   * @stable ICU 4.2
   */
  int32_t length() const { return length_; }
  /**
   * Returns whether the string is empty.
   * @return TRUE if the string is empty
   * @stable ICU 4.2
   */
  UBool empty() const { return length_ == 0; }

  /**
   * Sets to an empty string.
   * @stable ICU 4.2
   */
  void clear() { ptr_ = NULL; length_ = 0; }

  /**
   * Reset the stringpiece to refer to new data.
   * @param xdata pointer the new string data.  Need not be nul terminated.
   * @param len the length of the new data
   * @stable ICU 4.8
   */
  void set(const char* xdata, int32_t len) { ptr_ = xdata; length_ = len; }

  /**
   * Reset the stringpiece to refer to new data.
   * @param str a pointer to a NUL-terminated string. 
   * @stable ICU 4.8
   */
  void set(const char* str);

  /**
   * Removes the first n string units.
   * @param n prefix length, must be non-negative and <=length()
   * @stable ICU 4.2
   */
  void remove_prefix(int32_t n) {
    if (n >= 0) {
      if (n > length_) {
        n = length_;
      }
      ptr_ += n;
      length_ -= n;
    }
  }

  /**
   * Removes the last n string units.
   * @param n suffix length, must be non-negative and <=length()
   * @stable ICU 4.2
   */
  void remove_suffix(int32_t n) {
    if (n >= 0) {
      if (n <= length_) {
        length_ -= n;
      } else {
        length_ = 0;
      }
    }
  }

  /**
   * Maximum integer, used as a default value for substring methods.
   * @stable ICU 4.2
   */
  static const int32_t npos; // = 0x7fffffff;

  /**
   * Returns a substring of this StringPiece.
   * @param pos start position; must be non-negative and <= length().
   * @param len length of the substring;
   *            must be non-negative and will be pinned to at most length() - pos.
   * @return the substring StringPiece
   * @stable ICU 4.2
   */
  StringPiece substr(int32_t pos, int32_t len = npos) const {
    return StringPiece(*this, pos, len);
  }
};

/**
 * Global operator == for StringPiece
 * @param x The first StringPiece to compare.
 * @param y The second StringPiece to compare.
 * @return TRUE if the string data is equal
 * @stable ICU 4.8
 */
U_EXPORT UBool U_EXPORT2 
operator==(const StringPiece& x, const StringPiece& y);

/**
 * Global operator != for StringPiece
 * @param x The first StringPiece to compare.
 * @param y The second StringPiece to compare.
 * @return TRUE if the string data is not equal
 * @stable ICU 4.8
 */
inline UBool operator!=(const StringPiece& x, const StringPiece& y) {
  return !(x == y);
}

U_NAMESPACE_END

#endif  // __STRINGPIECE_H__

Coverage Report

Created: 2025-07-11 06:23

Line	Count	Source (jump to first uncovered line)
1		// © 2016 and later: Unicode, Inc. and others.
2		// License & terms of use: http://www.unicode.org/copyright.html
3		// Copyright (C) 2009-2013, International Business Machines
4		// Corporation and others. All Rights Reserved.
5		//
6		// Copyright 2001 and onwards Google Inc.
7		// Author: Sanjay Ghemawat
8
9		// This code is a contribution of Google code, and the style used here is
10		// a compromise between the original Google code and the ICU coding guidelines.
11		// For example, data types are ICU-ified (size_t,int->int32_t),
12		// and API comments doxygen-ified, but function names and behavior are
13		// as in the original, if possible.
14		// Assertion-style error handling, not available in ICU, was changed to
15		// parameter "pinning" similar to UnicodeString.
16		//
17		// In addition, this is only a partial port of the original Google code,
18		// limited to what was needed so far. The (nearly) complete original code
19		// is in the ICU svn repository at icuhtml/trunk/design/strings/contrib
20		// (see ICU ticket 6765, r25517).
21
22		#ifndef __STRINGPIECE_H__
23		#define __STRINGPIECE_H__
24
25		/**
26		* \file
27		* \brief C++ API: StringPiece: Read-only byte string wrapper class.
28		*/
29
30		#include "unicode/utypes.h"
31		#include "unicode/uobject.h"
32		#include "unicode/std_string.h"
33
34		// Arghh! I wish C++ literals were "string".
35
36		U_NAMESPACE_BEGIN
37
38		/**
39		* A string-like object that points to a sized piece of memory.
40		*
41		* We provide non-explicit singleton constructors so users can pass
42		* in a "const char*" or a "string" wherever a "StringPiece" is
43		* expected.
44		*
45		* Functions or methods may use StringPiece parameters to accept either a
46		* "const char*" or a "string" value that will be implicitly converted to a
47		* StringPiece.
48		*
49		* Systematic usage of StringPiece is encouraged as it will reduce unnecessary
50		* conversions from "const char*" to "string" and back again.
51		*
52		* @stable ICU 4.2
53		*/
54		class U_COMMON_API StringPiece : public UMemory {
55		private:
56		const char* ptr_;
57		int32_t length_;
58
59		public:
60		/**
61		* Default constructor, creates an empty StringPiece.
62		* @stable ICU 4.2
63		*/
64	0	StringPiece() : ptr_(NULL), length_(0) { }
65		/**
66		* Constructs from a NUL-terminated const char * pointer.
67		* @param str a NUL-terminated const char * pointer
68		* @stable ICU 4.2
69		*/
70		StringPiece(const char* str);
71		/**
72		* Constructs from a std::string.
73		* @stable ICU 4.2
74		*/
75		StringPiece(const std::string& str)
76	0	: ptr_(str.data()), length_(static_cast<int32_t>(str.size())) { }
77		/**
78		* Constructs from a const char * pointer and a specified length.
79		* @param offset a const char * pointer (need not be terminated)
80		* @param len the length of the string; must be non-negative
81		* @stable ICU 4.2
82		*/
83	0	StringPiece(const char* offset, int32_t len) : ptr_(offset), length_(len) { }
84		/**
85		* Substring of another StringPiece.
86		* @param x the other StringPiece
87		* @param pos start position in x; must be non-negative and <= x.length().
88		* @stable ICU 4.2
89		*/
90		StringPiece(const StringPiece& x, int32_t pos);
91		/**
92		* Substring of another StringPiece.
93		* @param x the other StringPiece
94		* @param pos start position in x; must be non-negative and <= x.length().
95		* @param len length of the substring;
96		* must be non-negative and will be pinned to at most x.length() - pos.
97		* @stable ICU 4.2
98		*/
99		StringPiece(const StringPiece& x, int32_t pos, int32_t len);
100
101		/**
102		* Returns the string pointer. May be NULL if it is empty.
103		*
104		* data() may return a pointer to a buffer with embedded NULs, and the
105		* returned buffer may or may not be null terminated. Therefore it is
106		* typically a mistake to pass data() to a routine that expects a NUL
107		* terminated string.
108		* @return the string pointer
109		* @stable ICU 4.2
110		*/
111	7.82k	const char* data() const { return ptr_; }
112		/**
113		* Returns the string length. Same as length().
114		* @return the string length
115		* @stable ICU 4.2
116		*/
117	0	int32_t size() const { return length_; }
118		/**
119		* Returns the string length. Same as size().
120		* @return the string length
121		* @stable ICU 4.2
122		*/
123	7.82k	int32_t length() const { return length_; }
124		/**
125		* Returns whether the string is empty.
126		* @return TRUE if the string is empty
127		* @stable ICU 4.2
128		*/
129	0	UBool empty() const { return length_ == 0; }
130
131		/**
132		* Sets to an empty string.
133		* @stable ICU 4.2
134		*/
135	0	void clear() { ptr_ = NULL; length_ = 0; }
136
137		/**
138		* Reset the stringpiece to refer to new data.
139		* @param xdata pointer the new string data. Need not be nul terminated.
140		* @param len the length of the new data
141		* @stable ICU 4.8
142		*/
143	0	void set(const char* xdata, int32_t len) { ptr_ = xdata; length_ = len; }
144
145		/**
146		* Reset the stringpiece to refer to new data.
147		* @param str a pointer to a NUL-terminated string.
148		* @stable ICU 4.8
149		*/
150		void set(const char* str);
151
152		/**
153		* Removes the first n string units.
154		* @param n prefix length, must be non-negative and <=length()
155		* @stable ICU 4.2
156		*/
157	0	void remove_prefix(int32_t n) {
158	0	if (n >= 0) {
159	0	if (n > length_) {
160	0	n = length_;
161	0	}
162	0	ptr_ += n;
163	0	length_ -= n;
164	0	}
165	0	}
166
167		/**
168		* Removes the last n string units.
169		* @param n suffix length, must be non-negative and <=length()
170		* @stable ICU 4.2
171		*/
172	0	void remove_suffix(int32_t n) {
173	0	if (n >= 0) {
174	0	if (n <= length_) {
175	0	length_ -= n;
176	0	} else {
177	0	length_ = 0;
178	0	}
179	0	}
180	0	}
181
182		/**
183		* Maximum integer, used as a default value for substring methods.
184		* @stable ICU 4.2
185		*/
186		static const int32_t npos; // = 0x7fffffff;
187
188		/**
189		* Returns a substring of this StringPiece.
190		* @param pos start position; must be non-negative and <= length().
191		* @param len length of the substring;
192		* must be non-negative and will be pinned to at most length() - pos.
193		* @return the substring StringPiece
194		* @stable ICU 4.2
195		*/
196	0	StringPiece substr(int32_t pos, int32_t len = npos) const {
197	0	return StringPiece(*this, pos, len);
198	0	}
199		};
200
201		/**
202		* Global operator == for StringPiece
203		* @param x The first StringPiece to compare.
204		* @param y The second StringPiece to compare.
205		* @return TRUE if the string data is equal
206		* @stable ICU 4.8
207		*/
208		U_EXPORT UBool U_EXPORT2
209		operator==(const StringPiece& x, const StringPiece& y);
210
211		/**
212		* Global operator != for StringPiece
213		* @param x The first StringPiece to compare.
214		* @param y The second StringPiece to compare.
215		* @return TRUE if the string data is not equal
216		* @stable ICU 4.8
217		*/
218	0	inline UBool operator!=(const StringPiece& x, const StringPiece& y) {
219	0	return !(x == y);
220	0	}
221
222		U_NAMESPACE_END
223
224		#endif // __STRINGPIECE_H__