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  * UTF-8 and Unicode string manipulation functions, plus convenience
  18  * functions for working with java/lang/String.
  19  */
  20 #ifndef _DALVIK_STRING
  21 #define _DALVIK_STRING
  22
  23 /*
  24  * Hash function for modified UTF-8 strings.
  25  */
  26 u4 dvmComputeUtf8Hash(const char* str);
  27
  28 /*
  29  * Hash function for string objects.
  30  */
  31 u4 dvmComputeStringHash(StringObject* strObj);
  32
  33 /*
  34  * Create a java/lang/String from a C string.
  35  *
  36  * The caller must call dvmReleaseTrackedAlloc() on the return value or
  37  * use a non-default value for "allocFlags".  It is never appropriate
  38  * to use ALLOC_DONT_TRACK with this function.
  39  *
  40  * Returns NULL and throws an exception on failure.
  41  */
  42 StringObject* dvmCreateStringFromCstr(const char* utf8Str, int allocFlags);
  43
  44 /*
  45  * Create a java/lang/String from a C string, given its UTF-16 length
  46  * (number of UTF-16 code points).
  47  *
  48  * The caller must call dvmReleaseTrackedAlloc() on the return value or
  49  * use a non-default value for "allocFlags".  It is never appropriate
  50  * to use ALLOC_DONT_TRACK with this function.
  51  *
  52  * Returns NULL and throws an exception on failure.
  53  */
  54 StringObject* dvmCreateStringFromCstrAndLength(const char* utf8Str,
  55     u4 utf16Length, int allocFlags);
  56
  57 /*
  58  * Compute the number of characters in a "modified UTF-8" string.  This will
  59  * match the result from strlen() so long as there are no multi-byte chars.
  60  */
  61 int dvmUtf8Len(const char* utf8Str);
  62
  63 /*
  64  * Convert a UTF-8 string to UTF-16.  "utf16Str" must have enough room
  65  * to hold the output.
  66  */
  67 void dvmConvertUtf8ToUtf16(u2* utf16Str, const char* utf8Str);
  68
  69 /*
  70  * Create a java/lang/String from a Unicode string.
  71  *
  72  * The caller must call dvmReleaseTrackedAlloc() on the return value.
  73  */
  74 StringObject* dvmCreateStringFromUnicode(const u2* unichars, int len);
  75
  76 /*
  77  * Create a UTF-8 C string from a java/lang/String.  Caller must free
  78  * the result.
  79  *
  80  * Returns NULL if "jstr" is NULL.
  81  */
  82 char* dvmCreateCstrFromString(StringObject* jstr);
  83
  84 /*
  85  * Create a UTF-8 C string from a region of a java/lang/String.  (Used by
  86  * the JNI GetStringUTFRegion call.)
  87  */
  88 void dvmCreateCstrFromStringRegion(StringObject* jstr, int start, int len,
  89     char* buf);
  90
  91 /*
  92  * Compute the length in bytes of the modified UTF-8 representation of a
  93  * string.
  94  */
  95 int dvmStringUtf8ByteLen(StringObject* jstr);
  96
  97 /*
  98  * Get the length in Unicode characters of a string.
  99  */
 100 int dvmStringLen(StringObject* jstr);
 101
 102 /*
 103  * Get the char[] object from the String.
 104  */
 105 ArrayObject* dvmStringCharArray(StringObject* jstr);
 106
 107 /*
 108  * Get a pointer to the Unicode data.
 109  */
 110 const u2* dvmStringChars(StringObject* jstr);
 111
 112 /*
 113  * Compare two string objects.  (This is a dvmHashTableLookup() callback.)
 114  */
 115 int dvmHashcmpStrings(const void* vstrObj1, const void* vstrObj2);
 116
 117 #endif /*_DALVIK_STRING*/