Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kArray3.h
Go to the documentation of this file.
1 /**
2 * @file kArray3.h
3 * @brief Declares the kArray3 class.
4 *
5 * @internal
6 * Copyright (C) 2006-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_ARRAY_3_H
11 #define K_API_ARRAY_3_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kArray3
19 * @extends kObject
20 * @implements kCollection
21 * @ingroup kApi-Data
22 * @brief Represents a 3D array.
23 *
24 * kArray3 represents 3D array of objects or values. The kArray3 constructor accepts arguments
25 * that determine the array item type (kType) and array dimension lengths.
26 *
27 * For arrays that contain <em>objects</em> (e.g. kImage) as opposed to <em>values</em> (e.g. k32s), the objects
28 * are not automatically destroyed when the array is destroyed. To recursively destroy both the array and the
29 * array items, use kObject_Dispose.
30 */
31 //typedef kObject kArray3; --forward-declared in kApiDef.x.h
32
33 /**
34 * Constructs a kArray3 object.
35 *
36 * @public @memberof kArray3
37 * @param array Receives the constructed object.
38 * @param itemType Type of array element.
39 * @param length0 Length of first array dimension (outermost).
40 * @param length1 Length of second array dimension.
41 * @param length2 Length of third array dimension (innermost).
42 * @param allocator Memory allocator (or kNULL for default).
43 * @return Operation status.
44 */
45 kFx(kStatus) kArray3_Construct(kArray3* array, kType itemType, kSize length0, kSize length1, kSize length2, kAlloc allocator);
46
47 /**
48 * Reallocates the internal array item buffer.
49 *
50 * @public @memberof kArray3
51 * @param array Array object.
52 * @param itemType Type of array element.
53 * @param length0 Length of first array dimension (outermost).
54 * @param length1 Length of second array dimension.
55 * @param length2 Length of third array dimension (innermost).
56 * @return Operation status.
57 */
58 kFx(kStatus) kArray3_Allocate(kArray3 array, kType itemType, kSize length0, kSize length1, kSize length2);
59
60 /**
61 * Attaches the array to an external item buffer.
62 *
63 * Attached item buffers are not freed when the array is destroyed.
64 *
65 * @public @memberof kArray3
66 * @param array Array object.
67 * @param items External item buffer.
68 * @param itemType Type of array element.
69 * @param length0 Length of first array dimension (outermost).
70 * @param length1 Length of second array dimension.
71 * @param length2 Length of third array dimension (innermost).
72 * @return Operation status.
73 */
74 kFx(kStatus) kArray3_Attach(kArray3 array, void* items, kType itemType, kSize length0, kSize length1, kSize length2);
75
76 /**
77 * Performs a shallow copy of the source array.
78 *
79 * Source items are copied by value; if the source array contains objects, the object
80 * handles are copied but the objects are not cloned.
81 *
82 * @public @memberof kArray3
83 * @param array Array object.
84 * @param source Source array to be copied.
85 * @return Operation status.
86 */
87 kFx(kStatus) kArray3_Assign(kArray3 array, kArray3 source);
88
89 /**
90 * Sets all array element bits to zero.
91 *
92 * @public @memberof kArray3
93 * @param array Array object.
94 * @return Operation status.
95 */
96 kFx(kStatus) kArray3_Zero(kArray3 array);
97
98 /**
99 * Sets the value of an item.
100 *
101 * @public @memberof kArray3
102 * @param array Array object.
103 * @param index0 First dimension index.
104 * @param index1 Second dimension index.
105 * @param index2 Third dimension index.
106 * @param item Pointer to item that will be copied (by value) into the array.
107 * @return Operation status.
108 */
109 kFx(kStatus) kArray3_SetItem(kArray3 array, kSize index0, kSize index1, kSize index2, const void* item);
110
111 /**
112 * Gets the value of an item.
113 *
114 * @public @memberof kArray3
115 * @param array Array object.
116 * @param index0 First dimension index.
117 * @param index1 Second dimension index.
118 * @param index2 Third dimension index.
119 * @param item Destination for item that will be copied (by value) from the array.
120 * @return Operation status.
121 */
122 kFx(kStatus) kArray3_Item(kArray3 array, kSize index0, kSize index1, kSize index2, void* item);
123
124 /**
125 * Returns a pointer to the array item buffer.
126 *
127 * @public @memberof kArray3
128 * @param array Array object.
129 * @return Pointer to array item buffer.
130 */
131 kFx(void*) kArray3_Data(kArray3 array);
132
133 /**
134 * Reports the size, in bytes, of the array item buffer.
135 *
136 * @public @memberof kArray3
137 * @param array Array object.
138 * @return Size of array item buffer (bytes).
139 */
140 kFx(kSize) kArray3_DataSize(kArray3 array);
141
142 /**
143 * Returns a pointer to the specified item in the array.
144 *
145 * @public @memberof kArray3
146 * @param array Array object.
147 * @param index0 First dimension index.
148 * @param index1 Second dimension index.
149 * @param index2 Third dimension index.
150 * @return Pointer to item.
151 */
152 kFx(void*) kArray3_At(kArray3 array, kSize index0, kSize index1, kSize index2);
153
154 /**
155 * Returns the array item type.
156 *
157 * @public @memberof kArray3
158 * @param array Array object.
159 * @return Array item type.
160 */
161 kFx(kType) kArray3_ItemType(kArray3 array);
162
163 /**
164 * Returns the array item size.
165 *
166 * @public @memberof kArray3
167 * @param array Array object.
168 * @return Array item size.
169 */
170 kFx(kSize) kArray3_ItemSize(kArray3 array);
171
172 /**
173 * Returns the length of the specified array dimension, in elements.
174 *
175 * @public @memberof kArray3
176 * @param array Array object.
177 * @param dimension Array dimension object.
178 * @return Array dimension length (in elements).
179 */
180 kFx(kSize) kArray3_Length(kArray3 array, kSize dimension);
181
182 /**
183 * Returns the array item count, in elements.
184 *
185 * @public @memberof kArray3
186 * @param array Array object.
187 * @return Array item count (in elements).
188 */
189 kFx(kSize) kArray3_Count(kArray3 array);
190
191 #define kArray3_ItemType_(ARRAY) kxArray3_ItemType_(ARRAY) ///< Macro version of kArray2_ItemType.
192 #define kArray3_ItemSize_(ARRAY) kxArray3_ItemSize_(ARRAY) ///< Macro version of kArray2_ItemSize.
193 #define kArray3_Length_(ARRAY, DIM) kxArray3_Length_(ARRAY, DIM) ///< Macro version of kArray2_Length.
194 #define kArray3_Count_(ARRAY) kxArray3_Count_(ARRAY) ///< Macro version of kArray2_Count.
195 #define kArray3_Data_(ARRAY) kxArray3_Data_(ARRAY) ///< Macro version of kArray2_Data.
196 #define kArray3_DataSize_(ARRAY) kxArray3_DataSize_(ARRAY) ///< Macro version of kArray2_DataSize.
197 #define kArray3_At_(ARRAY, I0, I1, I2) kxArray3_At_(ARRAY, I0, I1, I2) ///< Macro version of kArray2_At.
198
199 /** Accesses an array element at the specified indices, and casts the value to the specified type. */
200 #define kArray3_As_(ARRAY, I0, I1, I2, TYPE) kxArray3_At_(ARRAY, I0, I1, I2)
201
202 kEndHeader()
203
204 #include <kApi/Data/kArray3.x.h>
205
206 #endif
kArray3::kArray3_Count
kSize kArray3_Count(kArray3 array)
Returns the array item count, in elements.
kArray3::kArray3_DataSize
kSize kArray3_DataSize(kArray3 array)
Reports the size, in bytes, of the array item buffer.
kArray3::kArray3_Allocate
kStatus kArray3_Allocate(kArray3 array, kType itemType, kSize length0, kSize length1, kSize length2)
Reallocates the internal array item buffer.
kArray3::kArray3_Attach
kStatus kArray3_Attach(kArray3 array, void *items, kType itemType, kSize length0, kSize length1, kSize length2)
Attaches the array to an external item buffer.
kArray3::kArray3_Length
kSize kArray3_Length(kArray3 array, kSize dimension)
Returns the length of the specified array dimension, in elements.
kArray3::kArray3_At
void * kArray3_At(kArray3 array, kSize index0, kSize index1, kSize index2)
Returns a pointer to the specified item in the array.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kArray3::kArray3_Assign
kStatus kArray3_Assign(kArray3 array, kArray3 source)
Performs a shallow copy of the source array.
kArray3::kArray3_Construct
kStatus kArray3_Construct(kArray3 *array, kType itemType, kSize length0, kSize length1, kSize length2, kAlloc allocator)
Constructs a kArray3 object.
kArray3
Represents a 3D array.
kArray3::kArray3_Item
kStatus kArray3_Item(kArray3 array, kSize index0, kSize index1, kSize index2, void *item)
Gets the value of an item.
kArray3::kArray3_Data
void * kArray3_Data(kArray3 array)
Returns a pointer to the array item buffer.
kApiDef.h
Essential API declarations.
kArray3::kArray3_ItemType
kType kArray3_ItemType(kArray3 array)
Returns the array item type.
kArray3::kArray3_SetItem
kStatus kArray3_SetItem(kArray3 array, kSize index0, kSize index1, kSize index2, const void *item)
Sets the value of an item.
kType
Represents metadata about a type (class, interface, or value).
kArray3::kArray3_Zero
kStatus kArray3_Zero(kArray3 array)
Sets all array element bits to zero.
kStatus
Represents an enumeration of error codes.
kArray3::kArray3_ItemSize
kSize kArray3_ItemSize(kArray3 array)
Returns the array item size.