Home | History | Annotate | Download | only in unicode
      1 // Copyright (C) 2010, 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 U_STD_NSQ 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 data pointer the new string data.  Need not be nul terminated.
    140    * @param len the length of the new data
    141    * @internal
    142    */
    143   void set(const char* data, int32_t len) { ptr_ = data; length_ = len; }
    144 
    145   /**
    146    * Reset the stringpiece to refer to new data.
    147    * @param str a pointer to a NUL-terminated string.
    148    * @internal
    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  * @internal
    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  * @internal
    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__
    225