Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kArray2.h
Go to the documentation of this file.
1 /**
2 * @file kArray2.h
3 * @brief Declares the kArray2 class.
4 *
5 * @internal
6 * Copyright (C) 2005-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_2_H
11 #define K_API_ARRAY_2_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kArray2
19 * @extends kObject
20 * @implements kCollection
21 * @ingroup kApi-Data
22 * @brief Represents a 2D array.
23 *
24 * kArray2 represents 2D array of objects or values. The kArray2 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 kArray2; --forward-declared in kApiDef.x.h
32
33 /**
34 * Constructs a kArray2 object.
35 *
36 * @public @memberof kArray2
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 (innermost).
41 * @param allocator Memory allocator (or kNULL for default).
42 * @return Operation status.
43 */
44 kFx(kStatus) kArray2_Construct(kArray2* array, kType itemType, kSize length0, kSize length1, kAlloc allocator);
45
46 /**
47 * Reallocates the internal array item buffer.
48 *
49 * @public @memberof kArray2
50 * @param array Array object.
51 * @param itemType Type of array element.
52 * @param length0 Length of first array dimension (outermost).
53 * @param length1 Length of second array dimension (innermost).
54 * @return Operation status.
55 */
56 kFx(kStatus) kArray2_Allocate(kArray2 array, kType itemType, kSize length0, kSize length1);
57
58 /**
59 * Attaches the array to an external item buffer.
60 *
61 * Attached item buffers are not freed when the array is destroyed.
62 *
63 * @public @memberof kArray2
64 * @param array Array object.
65 * @param items External item buffer.
66 * @param itemType Type of array element.
67 * @param length0 Length of first array dimension (outermost).
68 * @param length1 Length of second array dimension (innermost).
69 * @return Operation status.
70 */
71 kFx(kStatus) kArray2_Attach(kArray2 array, void* items, kType itemType, kSize length0, kSize length1);
72
73 /**
74 * Performs a shallow copy of the source array.
75 *
76 * Source items are copied by value; if the source array contains objects, the object
77 * handles are copied but the objects are not cloned.
78 *
79 * @public @memberof kArray2
80 * @param array Array object.
81 * @param source Source array to be copied.
82 * @return Operation status.
83 */
84 kFx(kStatus) kArray2_Assign(kArray2 array, kArray2 source);
85
86 /**
87 * Sets all array element bits to zero.
88 *
89 * @public @memberof kArray2
90 * @param array Array object.
91 * @return Operation status.
92 */
93 kFx(kStatus) kArray2_Zero(kArray2 array);
94
95 /**
96 * Sets the value of an item.
97 *
98 * @public @memberof kArray2
99 * @param array Array object.
100 * @param index0 First dimension index.
101 * @param index1 Second dimension index.
102 * @param item Pointer to item that will be copied (by value) into the array.
103 * @return Operation status.
104 */
105 kFx(kStatus) kArray2_SetItem(kArray2 array, kSize index0, kSize index1, const void* item);
106
107 /**
108 * Gets the value of an item.
109 *
110 * @public @memberof kArray2
111 * @param array Array object.
112 * @param index0 First dimension index.
113 * @param index1 Second dimension index.
114 * @param item Destination for item that will be copied (by value) from the array.
115 * @return Operation status.
116 */
117 kFx(kStatus) kArray2_Item(kArray2 array, kSize index0, kSize index1, void* item);
118
119 /**
120 * Returns a pointer to the array item buffer.
121 *
122 * @public @memberof kArray2
123 * @param array Array object.
124 * @return Pointer to array item buffer.
125 */
126 kFx(void*) kArray2_Data(kArray2 array);
127
128 /**
129 * Reports the size, in bytes, of the array item buffer.
130 *
131 * @public @memberof kArray2
132 * @param array Array object.
133 * @return Size of array item buffer (bytes).
134 */
135 kFx(kSize) kArray2_DataSize(kArray2 array);
136
137 /**
138 * Returns a pointer to the specified item in the array.
139 *
140 * @public @memberof kArray2
141 * @param array Array object.
142 * @param index0 First dimension index.
143 * @param index1 Second dimension index.
144 * @return Pointer to item.
145 */
146 kFx(void*) kArray2_At(kArray2 array, kSize index0, kSize index1);
147
148 /**
149 * Returns the array item type.
150 *
151 * @public @memberof kArray2
152 * @param array Array object.
153 * @return Array item type.
154 */
155 kFx(kType) kArray2_ItemType(kArray2 array);
156
157 /**
158 * Returns the array item size.
159 *
160 * @public @memberof kArray2
161 * @param array Array object.
162 * @return Array item size.
163 */
164 kFx(kSize) kArray2_ItemSize(kArray2 array);
165
166 /**
167 * Returns the length of the specified array dimension, in elements.
168 *
169 * @public @memberof kArray2
170 * @param array Array object.
171 * @param dimension Array dimension object.
172 * @return Array dimension length (in elements).
173 */
174 kFx(kSize) kArray2_Length(kArray2 array, kSize dimension);
175
176 /**
177 * Returns the array item count, in elements.
178 *
179 * @public @memberof kArray2
180 * @param array Array object.
181 * @return Array item count (in elements).
182 */
183 kFx(kSize) kArray2_Count(kArray2 array);
184
185 #define kArray2_ItemType_(ARRAY) kxArray2_ItemType_(ARRAY) ///< Macro version of kArray2_ItemType.
186 #define kArray2_ItemSize_(ARRAY) kxArray2_ItemSize_(ARRAY) ///< Macro version of kArray2_ItemSize.
187 #define kArray2_Length_(ARRAY, DIM) kxArray2_Length_(ARRAY, DIM) ///< Macro version of kArray2_Length.
188 #define kArray2_Count_(ARRAY) kxArray2_Count_(ARRAY) ///< Macro version of kArray2_Count.
189 #define kArray2_Data_(ARRAY) kxArray2_Data_(ARRAY) ///< Macro version of kArray2_Data.
190 #define kArray2_DataSize_(ARRAY) kxArray2_DataSize_(ARRAY) ///< Macro version of kArray2_DataSize.
191 #define kArray2_At_(ARRAY, I0, I1) kxArray2_At_(ARRAY, I0, I1) ///< Macro version of kArray2_At.
192
193 /** Accesses an array element at the specified indices, and casts the value to the specified type. */
194 #define kArray2_As_(ARRAY, I0, I1, TYPE) kxArray2_As_(ARRAY, I0, I1, TYPE)
195
196 kEndHeader()
197
198 #include <kApi/Data/kArray2.x.h>
199
200 #endif
kArray2::kArray2_DataSize
kSize kArray2_DataSize(kArray2 array)
Reports the size, in bytes, of the array item buffer.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kArray2::kArray2_SetItem
kStatus kArray2_SetItem(kArray2 array, kSize index0, kSize index1, const void *item)
Sets the value of an item.
kArray2
Represents a 2D array.
kArray2::kArray2_Length
kSize kArray2_Length(kArray2 array, kSize dimension)
Returns the length of the specified array dimension, in elements.
kArray2::kArray2_Construct
kStatus kArray2_Construct(kArray2 *array, kType itemType, kSize length0, kSize length1, kAlloc allocator)
Constructs a kArray2 object.
kArray2::kArray2_Zero
kStatus kArray2_Zero(kArray2 array)
Sets all array element bits to zero.
kApiDef.h
Essential API declarations.
kArray2::kArray2_ItemSize
kSize kArray2_ItemSize(kArray2 array)
Returns the array item size.
kArray2::kArray2_Data
void * kArray2_Data(kArray2 array)
Returns a pointer to the array item buffer.
kArray2::kArray2_Allocate
kStatus kArray2_Allocate(kArray2 array, kType itemType, kSize length0, kSize length1)
Reallocates the internal array item buffer.
kArray2::kArray2_Attach
kStatus kArray2_Attach(kArray2 array, void *items, kType itemType, kSize length0, kSize length1)
Attaches the array to an external item buffer.
kArray2::kArray2_ItemType
kType kArray2_ItemType(kArray2 array)
Returns the array item type.
kType
Represents metadata about a type (class, interface, or value).
kArray2::kArray2_Item
kStatus kArray2_Item(kArray2 array, kSize index0, kSize index1, void *item)
Gets the value of an item.
kArray2::kArray2_Assign
kStatus kArray2_Assign(kArray2 array, kArray2 source)
Performs a shallow copy of the source array.
kArray2::kArray2_Count
kSize kArray2_Count(kArray2 array)
Returns the array item count, in elements.
kStatus
Represents an enumeration of error codes.
kArray2::kArray2_At
void * kArray2_At(kArray2 array, kSize index0, kSize index1)
Returns a pointer to the specified item in the array.