Array.h revision a4f4a73edf03cd08b5b2d775913bcac674a117bb 
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 * Array handling.
18 */
19#ifndef _DALVIK_OO_ARRAY
20#define _DALVIK_OO_ARRAY
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26/* width of an object reference, for arrays of objects */
27#define kObjectArrayRefWidth    sizeof(Object*)
28
29/*
30 * Find a matching array class.  If it doesn't exist, create it.
31 *
32 * "descriptor" looks like "[I".
33 *
34 * "loader" should be the defining class loader for the elements held
35 * in the array.
36 */
37ClassObject* dvmFindArrayClass(const char* descriptor, Object* loader);
38
39/*
40 * Find the array class for the specified class.  If "elemClassObj" is the
41 * class "Foo", this returns the class object for "[Foo".
42 */
43ClassObject* dvmFindArrayClassForElement(ClassObject* elemClassObj);
44
45/*
46 * Allocate space for a new array object.
47 *
48 * "allocFlags" determines whether the new object will be added to the
49 * "tracked alloc" table.
50 *
51 * Returns NULL with an exception raised if allocation fails.
52 */
53ArrayObject* dvmAllocArray(ClassObject* arrayClass, size_t length,
54    size_t elemWidth, int allocFlags);
55
56/*
57 * Create a new array, given an array class.  The class may represent an
58 * array of references or primitives.
59 *
60 * Returns NULL with an exception raised if allocation fails.
61 */
62ArrayObject* dvmAllocArrayByClass(ClassObject* arrayClass,
63    size_t length, int allocFlags);
64
65/*
66 * Allocate an array whose members are primitives (bools, ints, etc.).
67 *
68 * "type" should be 'I', 'J', 'Z', etc.
69 *
70 * The new object will be added to the "tracked alloc" table.
71 *
72 * Returns NULL with an exception raised if allocation fails.
73 */
74ArrayObject* dvmAllocPrimitiveArray(char type, size_t length, int allocFlags);
75
76/*
77 * Allocate an array with multiple dimensions.  Elements may be Objects or
78 * primitive types.
79 *
80 * The base object will be added to the "tracked alloc" table.
81 *
82 * Returns NULL with an exception raised if allocation fails.
83 */
84ArrayObject* dvmAllocMultiArray(ClassObject* arrayClass, int curDim,
85    const int* dimensions);
86
87/*
88 * Verify that the object is actually an array.
89 *
90 * Does not verify that the object is actually a non-NULL object.
91 */
92INLINE bool dvmIsArray(const ArrayObject* arrayObj)
93{
94    return ( ((Object*)arrayObj)->clazz->descriptor[0] == '[' );
95}
96
97/*
98 * Verify that the array is an object array and not a primitive array.
99 *
100 * Does not verify that the object is actually a non-NULL object.
101 */
102INLINE bool dvmIsObjectArrayClass(const ClassObject* clazz)
103{
104    const char* descriptor = clazz->descriptor;
105    return descriptor[0] == '[' && (descriptor[1] == 'L' ||
106                                    descriptor[1] == '[');
107}
108
109/*
110 * Verify that the array is an object array and not a primitive array.
111 *
112 * Does not verify that the object is actually a non-NULL object.
113 */
114INLINE bool dvmIsObjectArray(const ArrayObject* arrayObj)
115{
116    return dvmIsObjectArrayClass(arrayObj->obj.clazz);
117}
118
119/*
120 * Verify that the class is an array class.
121 *
122 * TODO: there may be some performance advantage to setting a flag in
123 * the accessFlags field instead of chasing into the name string.
124 */
125INLINE bool dvmIsArrayClass(const ClassObject* clazz)
126{
127    return (clazz->descriptor[0] == '[');
128}
129
130/*
131 * Copy the entire contents of one array of objects to another.  If the copy
132 * is impossible because of a type clash, we fail and return "false".
133 *
134 * "dstElemClass" is the type of element that "dstArray" holds.
135 */
136bool dvmCopyObjectArray(ArrayObject* dstArray, const ArrayObject* srcArray,
137    ClassObject* dstElemClass);
138
139/*
140 * Copy the entire contents of an array of boxed primitives into an
141 * array of primitives.  The boxed value must fit in the primitive (i.e.
142 * narrowing conversions are not allowed).
143 */
144bool dvmUnboxObjectArray(ArrayObject* dstArray, const ArrayObject* srcArray,
145    ClassObject* dstElemClass);
146
147/*
148 * Returns the size of the given array object in bytes.
149 */
150size_t dvmArrayObjectSize(const ArrayObject *array);
151
152/*
153 * Returns the width, in bytes, required by elements in instances of
154 * the array class.
155 */
156size_t dvmArrayClassElementWidth(const ClassObject* clazz);
157
158#ifdef __cplusplus
159}
160#endif
161
162#endif /*_DALVIK_OO_ARRAY*/
163