icuSources/common/charstr.h

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