REGRESSION(Variation Fonts): Specifying Skia by PostScript name does not yield the...
[WebKit-https.git] / Source / WebCore / icu / unicode / stringpiece.h
1 // Copyright (C) 2009-2013, International Business Machines
2 // Corporation and others. All Rights Reserved.
3 //
4 // Copyright 2001 and onwards Google Inc.
5 // Author: Sanjay Ghemawat
6
7 // This code is a contribution of Google code, and the style used here is
8 // a compromise between the original Google code and the ICU coding guidelines.
9 // For example, data types are ICU-ified (size_t,int->int32_t),
10 // and API comments doxygen-ified, but function names and behavior are
11 // as in the original, if possible.
12 // Assertion-style error handling, not available in ICU, was changed to
13 // parameter "pinning" similar to UnicodeString.
14 //
15 // In addition, this is only a partial port of the original Google code,
16 // limited to what was needed so far. The (nearly) complete original code
17 // is in the ICU svn repository at icuhtml/trunk/design/strings/contrib
18 // (see ICU ticket 6765, r25517).
19
20 #ifndef __STRINGPIECE_H__
21 #define __STRINGPIECE_H__
22
23 /**
24  * \file 
25  * \brief C++ API: StringPiece: Read-only byte string wrapper class.
26  */
27
28 #include "unicode/utypes.h"
29 #include "unicode/uobject.h"
30 #include "unicode/std_string.h"
31
32 // Arghh!  I wish C++ literals were "string".
33
34 U_NAMESPACE_BEGIN
35
36 /**
37  * A string-like object that points to a sized piece of memory.
38  *
39  * We provide non-explicit singleton constructors so users can pass
40  * in a "const char*" or a "string" wherever a "StringPiece" is
41  * expected.
42  *
43  * Functions or methods may use const StringPiece& parameters to accept either
44  * a "const char*" or a "string" value that will be implicitly converted to
45  * a StringPiece.
46  *
47  * Systematic usage of StringPiece is encouraged as it will reduce unnecessary
48  * conversions from "const char*" to "string" and back again.
49  *
50  * @stable ICU 4.2
51  */
52 class U_COMMON_API StringPiece : public UMemory {
53  private:
54   const char*   ptr_;
55   int32_t       length_;
56
57  public:
58   /**
59    * Default constructor, creates an empty StringPiece.
60    * @stable ICU 4.2
61    */
62   StringPiece() : ptr_(NULL), length_(0) { }
63   /**
64    * Constructs from a NUL-terminated const char * pointer.
65    * @param str a NUL-terminated const char * pointer
66    * @stable ICU 4.2
67    */
68   StringPiece(const char* str);
69 #if U_HAVE_STD_STRING
70   /**
71    * Constructs from a std::string.
72    * @stable ICU 4.2
73    */
74   StringPiece(const std::string& str)
75     : ptr_(str.data()), length_(static_cast<int32_t>(str.size())) { }
76 #endif
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   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   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   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   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   UBool empty() const { return length_ == 0; }
130
131   /**
132    * Sets to an empty string.
133    * @stable ICU 4.2
134    */
135   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   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   void remove_prefix(int32_t n) {
158     if (n >= 0) {
159       if (n > length_) {
160         n = length_;
161       }
162       ptr_ += n;
163       length_ -= n;
164     }
165   }
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   void remove_suffix(int32_t n) {
173     if (n >= 0) {
174       if (n <= length_) {
175         length_ -= n;
176       } else {
177         length_ = 0;
178       }
179     }
180   }
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   StringPiece substr(int32_t pos, int32_t len = npos) const {
197     return StringPiece(*this, pos, len);
198   }
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 inline UBool operator!=(const StringPiece& x, const StringPiece& y) {
219   return !(x == y);
220 }
221
222 U_NAMESPACE_END
223
224 #endif  // __STRINGPIECE_H__