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
22U_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
27template 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 */
41class U_COMMON_API CharString : public UMemory {
42public:
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) 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) 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 * Copies the contents of the string into dest.
92 * Checks if there is enough space in dest, extracts the entire string if possible,
93 * and NUL-terminates dest if possible.
94 *
95 * If the string fits into dest but cannot be NUL-terminated (length()==capacity),
96 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING.
97 * If the string itself does not fit into dest (length()>capacity),
98 * then the error code is set to U_BUFFER_OVERFLOW_ERROR.
99 *
100 * @param dest Destination string buffer.
101 * @param capacity Size of the dest buffer (number of chars).
102 * @param errorCode ICU error code.
103 * @return length()
104 */
105 int32_t extract(char *dest, int32_t capacity, UErrorCode &errorCode) const;
106
107 bool operator==(StringPiece other) const {
108 return len == other.length() && (len == 0 || uprv_memcmp(data(), other.data(), len) == 0);
109 }
110 bool operator!=(StringPiece other) const {
111 return !operator==(other);
112 }
113
114 /** @return last index of c, or -1 if c is not in this string */
115 int32_t lastIndexOf(char c) const;
116
117 bool contains(StringPiece s) const;
118
119 CharString &clear() { len=0; buffer[0]=0; return *this; }
120 CharString &truncate(int32_t newLength);
121
122 CharString &append(char c, UErrorCode &errorCode);
123 CharString &append(StringPiece s, UErrorCode &errorCode) {
124 return append(s.data(), s.length(), errorCode);
125 }
126 CharString &append(const CharString &s, UErrorCode &errorCode) {
127 return append(s.data(), s.length(), errorCode);
128 }
129 CharString &append(const char *s, int32_t sLength, UErrorCode &status);
130
131 CharString &appendNumber(int32_t number, UErrorCode &status);
132
133 /**
134 * Returns a writable buffer for appending and writes the buffer's capacity to
135 * resultCapacity. Guarantees resultCapacity>=minCapacity if U_SUCCESS().
136 * There will additionally be space for a terminating NUL right at resultCapacity.
137 * (This function is similar to ByteSink.GetAppendBuffer().)
138 *
139 * The returned buffer is only valid until the next write operation
140 * on this string.
141 *
142 * After writing at most resultCapacity bytes, call append() with the
143 * pointer returned from this function and the number of bytes written.
144 *
145 * @param minCapacity required minimum capacity of the returned buffer;
146 * must be non-negative
147 * @param desiredCapacityHint desired capacity of the returned buffer;
148 * must be non-negative
149 * @param resultCapacity will be set to the capacity of the returned buffer
150 * @param errorCode in/out error code
151 * @return a buffer with resultCapacity>=min_capacity
152 */
153 char *getAppendBuffer(int32_t minCapacity,
154 int32_t desiredCapacityHint,
155 int32_t &resultCapacity,
156 UErrorCode &errorCode);
157
158 CharString &appendInvariantChars(const UnicodeString &s, UErrorCode &errorCode);
159 CharString &appendInvariantChars(const char16_t* uchars, int32_t ucharsLen, UErrorCode& errorCode);
160
161 /**
162 * Appends a filename/path part, e.g., a directory name.
163 * First appends a U_FILE_SEP_CHAR or U_FILE_ALT_SEP_CHAR if necessary.
164 * Does nothing if s is empty.
165 */
166 CharString &appendPathPart(StringPiece s, UErrorCode &errorCode);
167
168 /**
169 * Appends a U_FILE_SEP_CHAR or U_FILE_ALT_SEP_CHAR if this string is not empty
170 * and does not already end with a U_FILE_SEP_CHAR or U_FILE_ALT_SEP_CHAR.
171 */
172 CharString &ensureEndsWithFileSeparator(UErrorCode &errorCode);
173
174private:
175 MaybeStackArray<char, 40> buffer;
176 int32_t len;
177
178 UBool ensureCapacity(int32_t capacity, int32_t desiredCapacityHint, UErrorCode &errorCode);
179
180 CharString(const CharString &other) = delete; // forbid copying of this class
181 CharString &operator=(const CharString &other) = delete; // forbid copying of this class
182
183 /**
184 * Returns U_FILE_ALT_SEP_CHAR if found in string, and U_FILE_SEP_CHAR is not found.
185 * Otherwise returns U_FILE_SEP_CHAR.
186 */
187 char getDirSepChar() const;
188};
189
190U_NAMESPACE_END
191
192#endif
193//eof
194