1 /*
2 * Copyright (C) 2005 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #ifndef ANDROID_STRING8_H
18 #define ANDROID_STRING8_H
19
20 #include <utils/Errors.h>
21
22 // Need this for the char16_t type; String8.h should not
23 // be depedent on the String16 class.
24 #include <utils/String16.h>
25
26 #include <stdint.h>
27 #include <string.h>
28 #include <sys/types.h>
29
30 // ---------------------------------------------------------------------------
31
32 extern "C" {
33
34 typedef uint32_t char32_t;
35
36 size_t strlen32(const char32_t *);
37 size_t strnlen32(const char32_t *, size_t);
38
39 /*
40 * Returns the length of "src" when "src" is valid UTF-8 string.
41 * Returns 0 if src is NULL, 0-length string or non UTF-8 string.
42 * This function should be used to determine whether "src" is valid UTF-8
43 * characters with valid unicode codepoints. "src" must be null-terminated.
44 *
45 * If you are going to use other GetUtf... functions defined in this header
46 * with string which may not be valid UTF-8 with valid codepoint (form 0 to
47 * 0x10FFFF), you should use this function before calling others, since the
48 * other functions do not check whether the string is valid UTF-8 or not.
49 *
50 * If you do not care whether "src" is valid UTF-8 or not, you should use
51 * strlen() as usual, which should be much faster.
52 */
53 size_t utf8_length(const char *src);
54
55 /*
56 * Returns the UTF-32 length of "src".
57 */
58 size_t utf32_length(const char *src, size_t src_len);
59
60 /*
61 * Returns the UTF-8 length of "src".
62 */
63 size_t utf8_length_from_utf32(const char32_t *src, size_t src_len);
64
65 /*
66 * Returns the unicode value at "index".
67 * Returns -1 when the index is invalid (equals to or more than "src_len").
68 * If returned value is positive, it is able to be converted to char32_t, which
69 * is unsigned. Then, if "next_index" is not NULL, the next index to be used is
70 * stored in "next_index". "next_index" can be NULL.
71 */
72 int32_t utf32_at(const char *src, size_t src_len,
73 size_t index, size_t *next_index);
74
75 /*
76 * Stores a UTF-32 string converted from "src" in "dst", if "dst_length" is not
77 * large enough to store the string, the part of the "src" string is stored
78 * into "dst".
79 * Returns the size actually used for storing the string.
80 * "dst" is not null-terminated when dst_len is fully used (like strncpy).
81 */
82 size_t utf8_to_utf32(const char* src, size_t src_len,
83 char32_t* dst, size_t dst_len);
84
85 /*
86 * Stores a UTF-8 string converted from "src" in "dst", if "dst_length" is not
87 * large enough to store the string, the part of the "src" string is stored
88 * into "dst" as much as possible. See the examples for more detail.
89 * Returns the size actually used for storing the string.
90 * dst" is not null-terminated when dst_len is fully used (like strncpy).
91 *
92 * Example 1
93 * "src" == \u3042\u3044 (\xE3\x81\x82\xE3\x81\x84)
94 * "src_len" == 2
95 * "dst_len" >= 7
96 * ->
97 * Returned value == 6
98 * "dst" becomes \xE3\x81\x82\xE3\x81\x84\0
99 * (note that "dst" is null-terminated)
100 *
101 * Example 2
102 * "src" == \u3042\u3044 (\xE3\x81\x82\xE3\x81\x84)
103 * "src_len" == 2
104 * "dst_len" == 5
105 * ->
106 * Returned value == 3
107 * "dst" becomes \xE3\x81\x82\0
108 * (note that "dst" is null-terminated, but \u3044 is not stored in "dst"
109 * since "dst" does not have enough size to store the character)
110 *
111 * Example 3
112 * "src" == \u3042\u3044 (\xE3\x81\x82\xE3\x81\x84)
113 * "src_len" == 2
114 * "dst_len" == 6
115 * ->
116 * Returned value == 6
117 * "dst" becomes \xE3\x81\x82\xE3\x81\x84
118 * (note that "dst" is NOT null-terminated, like strncpy)
119 */
120 size_t utf32_to_utf8(const char32_t* src, size_t src_len,
121 char* dst, size_t dst_len);
122
123 }
124
125 // ---------------------------------------------------------------------------
126
127 namespace android {
128
129 class TextOutput;
130
131 //! This is a string holding UTF-8 characters. Does not allow the value more
132 // than 0x10FFFF, which is not valid unicode codepoint.
133 class String8
134 {
135 public:
136 String8();
137 String8(const String8& o);
138 explicit String8(const char* o);
139 explicit String8(const char* o, size_t numChars);
140
141 explicit String8(const String16& o);
142 explicit String8(const char16_t* o);
143 explicit String8(const char16_t* o, size_t numChars);
144 explicit String8(const char32_t* o);
145 explicit String8(const char32_t* o, size_t numChars);
146 ~String8();
147
148 inline const char* string() const;
149 inline size_t size() const;
150 inline size_t length() const;
151 inline size_t bytes() const;
152
153 inline const SharedBuffer* sharedBuffer() const;
154
155 void setTo(const String8& other);
156 status_t setTo(const char* other);
157 status_t setTo(const char* other, size_t numChars);
158 status_t setTo(const char16_t* other, size_t numChars);
159 status_t setTo(const char32_t* other,
160 size_t length);
161
162 status_t append(const String8& other);
163 status_t append(const char* other);
164 status_t append(const char* other, size_t numChars);
165
166 // Note that this function takes O(N) time to calculate the value.
167 // No cache value is stored.
168 size_t getUtf32Length() const;
169 int32_t getUtf32At(size_t index,
170 size_t *next_index) const;
171 size_t getUtf32(char32_t* dst, size_t dst_len) const;
172
173 inline String8& operator=(const String8& other);
174 inline String8& operator=(const char* other);
175
176 inline String8& operator+=(const String8& other);
177 inline String8 operator+(const String8& other) const;
178
179 inline String8& operator+=(const char* other);
180 inline String8 operator+(const char* other) const;
181
182 inline int compare(const String8& other) const;
183
184 inline bool operator<(const String8& other) const;
185 inline bool operator<=(const String8& other) const;
186 inline bool operator==(const String8& other) const;
187 inline bool operator!=(const String8& other) const;
188 inline bool operator>=(const String8& other) const;
189 inline bool operator>(const String8& other) const;
190
191 inline bool operator<(const char* other) const;
192 inline bool operator<=(const char* other) const;
193 inline bool operator==(const char* other) const;
194 inline bool operator!=(const char* other) const;
195 inline bool operator>=(const char* other) const;
196 inline bool operator>(const char* other) const;
197
198 inline operator const char*() const;
199
200 char* lockBuffer(size_t size);
201 void unlockBuffer();
202 status_t unlockBuffer(size_t size);
203
204 // return the index of the first byte of other in this at or after
205 // start, or -1 if not found
206 ssize_t find(const char* other, size_t start = 0) const;
207
208 void toLower();
209 void toLower(size_t start, size_t numChars);
210 void toUpper();
211 void toUpper(size_t start, size_t numChars);
212
213 /*
214 * These methods operate on the string as if it were a path name.
215 */
216
217 /*
218 * Set the filename field to a specific value.
219 *
220 * Normalizes the filename, removing a trailing '/' if present.
221 */
222 void setPathName(const char* name);
223 void setPathName(const char* name, size_t numChars);
224
225 /*
226 * Get just the filename component.
227 *
228 * "/tmp/foo/bar.c" --> "bar.c"
229 */
230 String8 getPathLeaf(void) const;
231
232 /*
233 * Remove the last (file name) component, leaving just the directory
234 * name.
235 *
236 * "/tmp/foo/bar.c" --> "/tmp/foo"
237 * "/tmp" --> "" // ????? shouldn't this be "/" ???? XXX
238 * "bar.c" --> ""
239 */
240 String8 getPathDir(void) const;
241
242 /*
243 * Retrieve the front (root dir) component. Optionally also return the
244 * remaining components.
245 *
246 * "/tmp/foo/bar.c" --> "tmp" (remain = "foo/bar.c")
247 * "/tmp" --> "tmp" (remain = "")
248 * "bar.c" --> "bar.c" (remain = "")
249 */
250 String8 walkPath(String8* outRemains = NULL) const;
251
252 /*
253 * Return the filename extension. This is the last '.' and up to
254 * four characters that follow it. The '.' is included in case we
255 * decide to expand our definition of what constitutes an extension.
256 *
257 * "/tmp/foo/bar.c" --> ".c"
258 * "/tmp" --> ""
259 * "/tmp/foo.bar/baz" --> ""
260 * "foo.jpeg" --> ".jpeg"
261 * "foo." --> ""
262 */
263 String8 getPathExtension(void) const;
264
265 /*
266 * Return the path without the extension. Rules for what constitutes
267 * an extension are described in the comment for getPathExtension().
268 *
269 * "/tmp/foo/bar.c" --> "/tmp/foo/bar"
270 */
271 String8 getBasePath(void) const;
272
273 /*
274 * Add a component to the pathname. We guarantee that there is
275 * exactly one path separator between the old path and the new.
276 * If there is no existing name, we just copy the new name in.
277 *
278 * If leaf is a fully qualified path (i.e. starts with '/', it
279 * replaces whatever was there before.
280 */
281 String8& appendPath(const char* leaf);
appendPath(const String8 & leaf)282 String8& appendPath(const String8& leaf) { return appendPath(leaf.string()); }
283
284 /*
285 * Like appendPath(), but does not affect this string. Returns a new one instead.
286 */
appendPathCopy(const char * leaf)287 String8 appendPathCopy(const char* leaf) const
288 { String8 p(*this); p.appendPath(leaf); return p; }
appendPathCopy(const String8 & leaf)289 String8 appendPathCopy(const String8& leaf) const { return appendPathCopy(leaf.string()); }
290
291 /*
292 * Converts all separators in this string to /, the default path separator.
293 *
294 * If the default OS separator is backslash, this converts all
295 * backslashes to slashes, in-place. Otherwise it does nothing.
296 * Returns self.
297 */
298 String8& convertToResPath();
299
300 private:
301 status_t real_append(const char* other, size_t numChars);
302 char* find_extension(void) const;
303
304 const char* mString;
305 };
306
307 TextOutput& operator<<(TextOutput& to, const String16& val);
308
309 // ---------------------------------------------------------------------------
310 // No user servicable parts below.
311
compare_type(const String8 & lhs,const String8 & rhs)312 inline int compare_type(const String8& lhs, const String8& rhs)
313 {
314 return lhs.compare(rhs);
315 }
316
strictly_order_type(const String8 & lhs,const String8 & rhs)317 inline int strictly_order_type(const String8& lhs, const String8& rhs)
318 {
319 return compare_type(lhs, rhs) < 0;
320 }
321
string()322 inline const char* String8::string() const
323 {
324 return mString;
325 }
326
length()327 inline size_t String8::length() const
328 {
329 return SharedBuffer::sizeFromData(mString)-1;
330 }
331
size()332 inline size_t String8::size() const
333 {
334 return length();
335 }
336
bytes()337 inline size_t String8::bytes() const
338 {
339 return SharedBuffer::sizeFromData(mString)-1;
340 }
341
sharedBuffer()342 inline const SharedBuffer* String8::sharedBuffer() const
343 {
344 return SharedBuffer::bufferFromData(mString);
345 }
346
347 inline String8& String8::operator=(const String8& other)
348 {
349 setTo(other);
350 return *this;
351 }
352
353 inline String8& String8::operator=(const char* other)
354 {
355 setTo(other);
356 return *this;
357 }
358
359 inline String8& String8::operator+=(const String8& other)
360 {
361 append(other);
362 return *this;
363 }
364
365 inline String8 String8::operator+(const String8& other) const
366 {
367 String8 tmp;
368 tmp += other;
369 return tmp;
370 }
371
372 inline String8& String8::operator+=(const char* other)
373 {
374 append(other);
375 return *this;
376 }
377
378 inline String8 String8::operator+(const char* other) const
379 {
380 String8 tmp;
381 tmp += other;
382 return tmp;
383 }
384
compare(const String8 & other)385 inline int String8::compare(const String8& other) const
386 {
387 return strcmp(mString, other.mString);
388 }
389
390 inline bool String8::operator<(const String8& other) const
391 {
392 return strcmp(mString, other.mString) < 0;
393 }
394
395 inline bool String8::operator<=(const String8& other) const
396 {
397 return strcmp(mString, other.mString) <= 0;
398 }
399
400 inline bool String8::operator==(const String8& other) const
401 {
402 return strcmp(mString, other.mString) == 0;
403 }
404
405 inline bool String8::operator!=(const String8& other) const
406 {
407 return strcmp(mString, other.mString) != 0;
408 }
409
410 inline bool String8::operator>=(const String8& other) const
411 {
412 return strcmp(mString, other.mString) >= 0;
413 }
414
415 inline bool String8::operator>(const String8& other) const
416 {
417 return strcmp(mString, other.mString) > 0;
418 }
419
420 inline bool String8::operator<(const char* other) const
421 {
422 return strcmp(mString, other) < 0;
423 }
424
425 inline bool String8::operator<=(const char* other) const
426 {
427 return strcmp(mString, other) <= 0;
428 }
429
430 inline bool String8::operator==(const char* other) const
431 {
432 return strcmp(mString, other) == 0;
433 }
434
435 inline bool String8::operator!=(const char* other) const
436 {
437 return strcmp(mString, other) != 0;
438 }
439
440 inline bool String8::operator>=(const char* other) const
441 {
442 return strcmp(mString, other) >= 0;
443 }
444
445 inline bool String8::operator>(const char* other) const
446 {
447 return strcmp(mString, other) > 0;
448 }
449
450 inline String8::operator const char*() const
451 {
452 return mString;
453 }
454
455 } // namespace android
456
457 // ---------------------------------------------------------------------------
458
459 #endif // ANDROID_STRING8_H
460