UtfString.h revision d8a3f9fa1951e552f5f65c2914689083cc0c46c2 
1/*
2 * Copyright (C) 2008 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/*
18 * UTF-8 and Unicode string manipulation functions, plus convenience
19 * functions for working with java/lang/String.
20 */
21#ifndef DALVIK_STRING_H_
22#define DALVIK_STRING_H_
23
24#include <string>
25#include <vector>
26
27/*
28 * (This is private to UtfString.c, but we cheat a bit and also use it
29 * for InlineNative.c.  Not really worth creating a separate header.)
30 *
31 * We can avoid poking around in gDvm by hard-coding the expected values of
32 * the String field offsets.  This will be annoying if String is in flux
33 * or the VM field layout is changing, so we use defines here to make it
34 * easy to switch back to the gDvm version.
35 *
36 * The values are checked for correctness during startup.
37 */
38//#define USE_GLOBAL_STRING_DEFS
39#ifdef USE_GLOBAL_STRING_DEFS
40# define STRING_FIELDOFF_VALUE      gDvm.offJavaLangString_value
41# define STRING_FIELDOFF_OFFSET     gDvm.offJavaLangString_offset
42# define STRING_FIELDOFF_COUNT      gDvm.offJavaLangString_count
43# define STRING_FIELDOFF_HASHCODE   gDvm.offJavaLangString_hashCode
44#else
45# define STRING_FIELDOFF_VALUE      8
46# define STRING_FIELDOFF_HASHCODE   12
47# define STRING_FIELDOFF_OFFSET     16
48# define STRING_FIELDOFF_COUNT      20
49#endif
50
51/*
52 * Hash function for modified UTF-8 strings.
53 */
54u4 dvmComputeUtf8Hash(const char* str);
55
56/*
57 * Hash function for string objects. Ensures the hash code field is
58 * populated and returns its value.
59 */
60u4 dvmComputeStringHash(StringObject* strObj);
61
62/*
63 * Create a java.lang.String[] from a vector of C++ strings.
64 *
65 * The caller must call dvmReleaseTrackedAlloc() on the returned array,
66 * but not on the individual elements.
67 *
68 * Returns NULL and throws an exception on failure.
69 */
70ArrayObject* dvmCreateStringArray(const std::vector<std::string>& strings);
71
72/*
73 * Create a java/lang/String from a C string.
74 *
75 * The caller must call dvmReleaseTrackedAlloc() on the return value.
76 *
77 * Returns NULL and throws an exception on failure.
78 */
79StringObject* dvmCreateStringFromCstr(const char* utf8Str);
80
81/*
82 * Create a java/lang/String from a C++ string.
83 *
84 * The caller must call dvmReleaseTrackedAlloc() on the return value.
85 *
86 * Returns NULL and throws an exception on failure.
87 */
88StringObject* dvmCreateStringFromCstr(const std::string& utf8Str);
89
90/*
91 * Create a java/lang/String from a C string, given its UTF-16 length
92 * (number of UTF-16 code points).
93 *
94 * The caller must call dvmReleaseTrackedAlloc() on the return value.
95 *
96 * Returns NULL and throws an exception on failure.
97 */
98StringObject* dvmCreateStringFromCstrAndLength(const char* utf8Str,
99    u4 utf16Length);
100
101/*
102 * Compute the number of characters in a "modified UTF-8" string.  This will
103 * match the result from strlen() so long as there are no multi-byte chars.
104 */
105size_t dvmUtf8Len(const char* utf8Str);
106
107/*
108 * Convert a UTF-8 string to UTF-16.  "utf16Str" must have enough room
109 * to hold the output.
110 */
111void dvmConvertUtf8ToUtf16(u2* utf16Str, const char* utf8Str);
112
113/*
114 * Create a java/lang/String from a Unicode string.
115 *
116 * The caller must call dvmReleaseTrackedAlloc() on the return value.
117 */
118StringObject* dvmCreateStringFromUnicode(const u2* unichars, int len);
119
120/*
121 * Create a UTF-8 C string from a java/lang/String.  Caller must free
122 * the result.
123 *
124 * Returns NULL if "jstr" is NULL.
125 */
126char* dvmCreateCstrFromString(const StringObject* jstr);
127
128/*
129 * Create a UTF-8 C string from a region of a java/lang/String.  (Used by
130 * the JNI GetStringUTFRegion call.)
131 */
132void dvmGetStringUtfRegion(const StringObject* jstr,
133        int start, int len, char* buf);
134
135/*
136 * Compare two string objects.  (This is a dvmHashTableLookup() callback.)
137 */
138int dvmHashcmpStrings(const void* vstrObj1, const void* vstrObj2);
139
140#endif  // DALVIK_STRING_H_
141