vm/UtfString.h

   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  */
  51 u4 dvmComputeUtf8Hash(const char* str);
  52
  53 /*
  54  * Hash function for string objects.
  55  */
  56 u4 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  */
  67 StringObject* 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  */
  79 StringObject* 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  */
  86 int 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  */
  92 void 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  */
  99 StringObject* 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  */
 107 char* 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  */
 113 void 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  */
 120 int dvmStringUtf8ByteLen(StringObject* jstr);
 121
 122 /*
 123  * Get the length in Unicode characters of a string.
 124  */
 125 int dvmStringLen(StringObject* jstr);
 126
 127 /*
 128  * Get the char[] object from the String.
 129  */
 130 ArrayObject* dvmStringCharArray(StringObject* jstr);
 131
 132 /*
 133  * Get a pointer to the Unicode data.
 134  */
 135 const u2* dvmStringChars(StringObject* jstr);
 136
 137 /*
 138  * Compare two string objects.  (This is a dvmHashTableLookup() callback.)
 139  */
 140 int dvmHashcmpStrings(const void* vstrObj1, const void* vstrObj2);
 141
 142 #endif /*_DALVIK_STRING*/