icuSources/common/charstr.h

   1 /*
   2 **********************************************************************
   3 *   Copyright (c) 2001-2012, International Business Machines
   4 *   Corporation and others.  All Rights Reserved.
   5 **********************************************************************
   6 *   Date        Name        Description
   7 *   11/19/2001  aliu        Creation.
   8 *   05/19/2010  markus      Rewritten from scratch
   9 **********************************************************************
  10 */
  11
  12 #ifndef CHARSTRING_H
  13 #define CHARSTRING_H
  14
  15 #include "unicode/utypes.h"
  16 #include "unicode/unistr.h"
  17 #include "unicode/uobject.h"
  18 #include "cmemory.h"
  19
  20 U_NAMESPACE_BEGIN
  21
  22 // Windows needs us to DLL-export the MaybeStackArray template specialization,
  23 // but MacOS X cannot handle it. Same as in digitlst.h.
  24 #if !U_PLATFORM_IS_DARWIN_BASED
  25 template class U_COMMON_API MaybeStackArray<char, 40>;
  26 #endif
  27
  28 /**
  29  * ICU-internal char * string class.
  30  * This class does not assume or enforce any particular character encoding.
  31  * Raw bytes can be stored. The string object owns its characters.
  32  * A terminating NUL is stored, but the class does not prevent embedded NUL characters.
  33  *
  34  * This class wants to be convenient but is also deliberately minimalist.
  35  * Please do not add methods if they only add minor convenience.
  36  * For example:
  37  *   cs.data()[5]='a';  // no need for setCharAt(5, 'a')
  38  */
  39 class U_COMMON_API CharString : public UMemory {
  40 public:
  41     CharString() : len(0) { buffer[0]=0; }
  42     CharString(const StringPiece &s, UErrorCode &errorCode) : len(0) {
  43         buffer[0]=0;
  44         append(s, errorCode);
  45     }
  46     CharString(const CharString &s, UErrorCode &errorCode) : len(0) {
  47         buffer[0]=0;
  48         append(s, errorCode);
  49     }
  50     CharString(const char *s, int32_t sLength, UErrorCode &errorCode) : len(0) {
  51         buffer[0]=0;
  52         append(s, sLength, errorCode);
  53     }
  54     ~CharString() {}
  55
  56     /**
  57      * Replaces this string's contents with the other string's contents.
  58      * CharString does not support the standard copy constructor nor
  59      * the assignment operator, to make copies explicit and to
  60      * use a UErrorCode where memory allocations might be needed.
  61      */
  62     CharString &copyFrom(const CharString &other, UErrorCode &errorCode);
  63
  64     UBool isEmpty() const { return len==0; }
  65     int32_t length() const { return len; }
  66     char operator[](int32_t index) const { return buffer[index]; }
  67     StringPiece toStringPiece() const { return StringPiece(buffer.getAlias(), len); }
  68
  69     const char *data() const { return buffer.getAlias(); }
  70     char *data() { return buffer.getAlias(); }
  71
  72     CharString &clear() { len=0; buffer[0]=0; return *this; }
  73     CharString &truncate(int32_t newLength);
  74
  75     CharString &append(char c, UErrorCode &errorCode);
  76     CharString &append(const StringPiece &s, UErrorCode &errorCode) {
  77         return append(s.data(), s.length(), errorCode);
  78     }
  79     CharString &append(const CharString &s, UErrorCode &errorCode) {
  80         return append(s.data(), s.length(), errorCode);
  81     }
  82     CharString &append(const char *s, int32_t sLength, UErrorCode &status);
  83     /**
  84      * Returns a writable buffer for appending and writes the buffer's capacity to
  85      * resultCapacity. Guarantees resultCapacity>=minCapacity if U_SUCCESS().
  86      * There will additionally be space for a terminating NUL right at resultCapacity.
  87      * (This function is similar to ByteSink.GetAppendBuffer().)
  88      *
  89      * The returned buffer is only valid until the next write operation
  90      * on this string.
  91      *
  92      * After writing at most resultCapacity bytes, call append() with the
  93      * pointer returned from this function and the number of bytes written.
  94      *
  95      * @param minCapacity required minimum capacity of the returned buffer;
  96      *                    must be non-negative
  97      * @param desiredCapacityHint desired capacity of the returned buffer;
  98      *                            must be non-negative
  99      * @param resultCapacity will be set to the capacity of the returned buffer
 100      * @param errorCode in/out error code
 101      * @return a buffer with resultCapacity>=min_capacity
 102      */
 103     char *getAppendBuffer(int32_t minCapacity,
 104                           int32_t desiredCapacityHint,
 105                           int32_t &resultCapacity,
 106                           UErrorCode &errorCode);
 107
 108     CharString &appendInvariantChars(const UnicodeString &s, UErrorCode &errorCode);
 109
 110     /**
 111      * Appends a filename/path part, e.g., a directory name.
 112      * First appends a U_FILE_SEP_CHAR if necessary.
 113      * Does nothing if s is empty.
 114      */
 115     CharString &appendPathPart(const StringPiece &s, UErrorCode &errorCode);
 116
 117 private:
 118     MaybeStackArray<char, 40> buffer;
 119     int32_t len;
 120
 121     UBool ensureCapacity(int32_t capacity, int32_t desiredCapacityHint, UErrorCode &errorCode);
 122
 123     CharString(const CharString &other); // forbid copying of this class
 124     CharString &operator=(const CharString &other); // forbid copying of this class
 125 };
 126
 127 U_NAMESPACE_END
 128
 129 #endif
 130 //eof