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_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  */
  54 u4 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  */
  60 u4 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  */
  70 ArrayObject* 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  */
  79 StringObject* 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  */
  88 StringObject* 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  */
  98 StringObject* 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  */
 105 size_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  */
 111 void 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  */
 118 StringObject* 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  */
 126 char* 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  */
 132 void dvmGetStringUtfRegion(const StringObject* jstr,
 133         int start, int len, char* buf);
 134
 135 /*
 136  * Compare two string objects.  (This is a dvmHashTableLookup() callback.)
 137  */
 138 int dvmHashcmpStrings(const void* vstrObj1, const void* vstrObj2);
 139
 140 #endif  // DALVIK_STRING_H_