1/*
2**********************************************************************
3*   Copyright (c) 2001-2015, 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
20U_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
25template 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 */
39class U_COMMON_API CharString : public UMemory {
40public:
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    /** @return last index of c, or -1 if c is not in this string */
73    int32_t lastIndexOf(char c) const;
74
75    CharString &clear() { len=0; buffer[0]=0; return *this; }
76    CharString &truncate(int32_t newLength);
77
78    CharString &append(char c, UErrorCode &errorCode);
79    CharString &append(const StringPiece &s, UErrorCode &errorCode) {
80        return append(s.data(), s.length(), errorCode);
81    }
82    CharString &append(const CharString &s, UErrorCode &errorCode) {
83        return append(s.data(), s.length(), errorCode);
84    }
85    CharString &append(const char *s, int32_t sLength, UErrorCode &status);
86    /**
87     * Returns a writable buffer for appending and writes the buffer's capacity to
88     * resultCapacity. Guarantees resultCapacity>=minCapacity if U_SUCCESS().
89     * There will additionally be space for a terminating NUL right at resultCapacity.
90     * (This function is similar to ByteSink.GetAppendBuffer().)
91     *
92     * The returned buffer is only valid until the next write operation
93     * on this string.
94     *
95     * After writing at most resultCapacity bytes, call append() with the
96     * pointer returned from this function and the number of bytes written.
97     *
98     * @param minCapacity required minimum capacity of the returned buffer;
99     *                    must be non-negative
100     * @param desiredCapacityHint desired capacity of the returned buffer;
101     *                            must be non-negative
102     * @param resultCapacity will be set to the capacity of the returned buffer
103     * @param errorCode in/out error code
104     * @return a buffer with resultCapacity>=min_capacity
105     */
106    char *getAppendBuffer(int32_t minCapacity,
107                          int32_t desiredCapacityHint,
108                          int32_t &resultCapacity,
109                          UErrorCode &errorCode);
110
111    CharString &appendInvariantChars(const UnicodeString &s, UErrorCode &errorCode);
112
113    /**
114     * Appends a filename/path part, e.g., a directory name.
115     * First appends a U_FILE_SEP_CHAR if necessary.
116     * Does nothing if s is empty.
117     */
118    CharString &appendPathPart(const StringPiece &s, UErrorCode &errorCode);
119
120    /**
121     * Appends a U_FILE_SEP_CHAR if this string is not empty
122     * and does not already end with a U_FILE_SEP_CHAR or U_FILE_ALT_SEP_CHAR.
123     */
124    CharString &ensureEndsWithFileSeparator(UErrorCode &errorCode);
125
126private:
127    MaybeStackArray<char, 40> buffer;
128    int32_t len;
129
130    UBool ensureCapacity(int32_t capacity, int32_t desiredCapacityHint, UErrorCode &errorCode);
131
132    CharString(const CharString &other); // forbid copying of this class
133    CharString &operator=(const CharString &other); // forbid copying of this class
134};
135
136U_NAMESPACE_END
137
138#endif
139//eof
140