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