source/common/unicode/stringpiece.h

   1 // Copyright (C) 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   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 #if U_HAVE_STD_STRING
  72   /**
  73    * Constructs from a std::string.
  74    * @stable ICU 4.2
  75    */
  76   StringPiece(const std::string& str)
  77     : ptr_(str.data()), length_(static_cast<int32_t>(str.size())) { }
  78 #endif
  79   /**
  80    * Constructs from a const char * pointer and a specified length.
  81    * @param offset a const char * pointer (need not be terminated)
  82    * @param len the length of the string; must be non-negative
  83    * @stable ICU 4.2
  84    */
  85   StringPiece(const char* offset, int32_t len) : ptr_(offset), length_(len) { }
  86   /**
  87    * Substring of another StringPiece.
  88    * @param x the other StringPiece
  89    * @param pos start position in x; must be non-negative and <= x.length().
  90    * @stable ICU 4.2
  91    */
  92   StringPiece(const StringPiece& x, int32_t pos);
  93   /**
  94    * Substring of another StringPiece.
  95    * @param x the other StringPiece
  96    * @param pos start position in x; must be non-negative and <= x.length().
  97    * @param len length of the substring;
  98    *            must be non-negative and will be pinned to at most x.length() - pos.
  99    * @stable ICU 4.2
 100    */
 101   StringPiece(const StringPiece& x, int32_t pos, int32_t len);
 102
 103   /**
 104    * Returns the string pointer. May be NULL if it is empty.
 105    *
 106    * data() may return a pointer to a buffer with embedded NULs, and the
 107    * returned buffer may or may not be null terminated.  Therefore it is
 108    * typically a mistake to pass data() to a routine that expects a NUL
 109    * terminated string.
 110    * @return the string pointer
 111    * @stable ICU 4.2
 112    */
 113   const char* data() const { return ptr_; }
 114   /**
 115    * Returns the string length. Same as length().
 116    * @return the string length
 117    * @stable ICU 4.2
 118    */
 119   int32_t size() const { return length_; }
 120   /**
 121    * Returns the string length. Same as size().
 122    * @return the string length
 123    * @stable ICU 4.2
 124    */
 125   int32_t length() const { return length_; }
 126   /**
 127    * Returns whether the string is empty.
 128    * @return TRUE if the string is empty
 129    * @stable ICU 4.2
 130    */
 131   UBool empty() const { return length_ == 0; }
 132
 133   /**
 134    * Sets to an empty string.
 135    * @stable ICU 4.2
 136    */
 137   void clear() { ptr_ = NULL; length_ = 0; }
 138
 139   /**
 140    * Reset the stringpiece to refer to new data.
 141    * @param xdata pointer the new string data.  Need not be nul terminated.
 142    * @param len the length of the new data
 143    * @stable ICU 4.8
 144    */
 145   void set(const char* xdata, int32_t len) { ptr_ = xdata; length_ = len; }
 146
 147   /**
 148    * Reset the stringpiece to refer to new data.
 149    * @param str a pointer to a NUL-terminated string.
 150    * @stable ICU 4.8
 151    */
 152   void set(const char* str);
 153
 154   /**
 155    * Removes the first n string units.
 156    * @param n prefix length, must be non-negative and <=length()
 157    * @stable ICU 4.2
 158    */
 159   void remove_prefix(int32_t n) {
 160     if (n >= 0) {
 161       if (n > length_) {
 162         n = length_;
 163       }
 164       ptr_ += n;
 165       length_ -= n;
 166     }
 167   }
 168
 169   /**
 170    * Removes the last n string units.
 171    * @param n suffix length, must be non-negative and <=length()
 172    * @stable ICU 4.2
 173    */
 174   void remove_suffix(int32_t n) {
 175     if (n >= 0) {
 176       if (n <= length_) {
 177         length_ -= n;
 178       } else {
 179         length_ = 0;
 180       }
 181     }
 182   }
 183
 184   /**
 185    * Maximum integer, used as a default value for substring methods.
 186    * @stable ICU 4.2
 187    */
 188   static const int32_t npos; // = 0x7fffffff;
 189
 190   /**
 191    * Returns a substring of this StringPiece.
 192    * @param pos start position; must be non-negative and <= length().
 193    * @param len length of the substring;
 194    *            must be non-negative and will be pinned to at most length() - pos.
 195    * @return the substring StringPiece
 196    * @stable ICU 4.2
 197    */
 198   StringPiece substr(int32_t pos, int32_t len = npos) const {
 199     return StringPiece(*this, pos, len);
 200   }
 201 };
 202
 203 /**
 204  * Global operator == for StringPiece
 205  * @param x The first StringPiece to compare.
 206  * @param y The second StringPiece to compare.
 207  * @return TRUE if the string data is equal
 208  * @stable ICU 4.8
 209  */
 210 U_EXPORT UBool U_EXPORT2
 211 operator==(const StringPiece& x, const StringPiece& y);
 212
 213 /**
 214  * Global operator != for StringPiece
 215  * @param x The first StringPiece to compare.
 216  * @param y The second StringPiece to compare.
 217  * @return TRUE if the string data is not equal
 218  * @stable ICU 4.8
 219  */
 220 inline UBool operator!=(const StringPiece& x, const StringPiece& y) {
 221   return !(x == y);
 222 }
 223
 224 U_NAMESPACE_END
 225
 226 #endif  // __STRINGPIECE_H__