Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kArray1.h
Go to the documentation of this file.
1 /**
2 * @file kArray1.h
3 * @brief Declares the kArray1 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_1_H
11 #define K_API_ARRAY_1_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kArray1
19 * @extends kObject
20 * @implements kCollection
21 * @ingroup kApi-Data
22 * @brief Represents a 1D array.
23 *
24 * kArray1 represents 1D array of objects or values. The kArray1 constructor accepts arguments
25 * that determine the array item type (kType) and array length.
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 kArray1; --forward-declared in kApiDef.x.h
32
33 /**
34 * Constructs a kArray1 object.
35 *
36 * @public @memberof kArray1
37 * @param array Receives the constructed object.
38 * @param itemType Type of array element.
39 * @param length Length of array.
40 * @param allocator Memory allocator (or kNULL for default).
41 * @return Operation status.
42 */
43 kFx(kStatus) kArray1_Construct(kArray1* array, kType itemType, kSize length, kAlloc allocator);
44
45 /**
46 * Reallocates the internal array item buffer.
47 *
48 * @public @memberof kArray1
49 * @param array Array object.
50 * @param itemType Type of array element.
51 * @param length Length of array.
52 * @return Operation status.
53 */
54 kFx(kStatus) kArray1_Allocate(kArray1 array, kType itemType, kSize length);
55
56 /**
57 * Attaches the array to an external item buffer.
58 *
59 * Attached item buffers are not freed when the array is destroyed.
60 *
61 * @public @memberof kArray1
62 * @param array Array object.
63 * @param items External item buffer.
64 * @param itemType Type of array element.
65 * @param length Length of array.
66 * @return Operation status.
67 */
68 kFx(kStatus) kArray1_Attach(kArray1 array, void* items, kType itemType, kSize length);
69
70 /**
71 * Performs a shallow copy of the source array.
72 *
73 * Source items are copied by value; if the source array contains objects, the object
74 * handles are copied but the objects are not cloned.
75 *
76 * @public @memberof kArray1
77 * @param array Array object.
78 * @param source Source array to be copied.
79 * @return Operation status.
80 */
81 kFx(kStatus) kArray1_Assign(kArray1 array, kArray1 source);
82
83 /**
84 * Sets all array element bits to zero.
85 *
86 * @public @memberof kArray1
87 * @param array Array object.
88 * @return Operation status.
89 */
90 kFx(kStatus) kArray1_Zero(kArray1 array);
91
92 /**
93 * Sets the value of an item.
94 *
95 * @public @memberof kArray1
96 * @param array Array object.
97 * @param index Array item index.
98 * @param item Pointer to item that will be copied (by value) into the array.
99 * @return Operation status.
100 */
101 kFx(kStatus) kArray1_SetItem(kArray1 array, kSize index, const void* item);
102
103 /**
104 * Gets the value of an item.
105 *
106 * @public @memberof kArray1
107 * @param array Array object.
108 * @param index Array item index.
109 * @param item Destination for item that will be copied (by value) from the array.
110 * @return Operation status.
111 */
112 kFx(kStatus) kArray1_Item(kArray1 array, kSize index, void* item);
113
114 /**
115 * Returns a pointer to the array item buffer.
116 *
117 * @public @memberof kArray1
118 * @param array Array object.
119 * @return Pointer to array item buffer.
120 */
121 kFx(void*) kArray1_Data(kArray1 array);
122
123 /**
124 * Reports the size, in bytes, of the array item buffer.
125 *
126 * @public @memberof kArray1
127 * @param array Array object.
128 * @return Size of array item buffer (bytes).
129 */
130 kFx(kSize) kArray1_DataSize(kArray1 array);
131
132 /**
133 * Returns a pointer to the specified item in the array.
134 *
135 * @public @memberof kArray1
136 * @param array Array object.
137 * @param index Item index.
138 * @return Pointer to item.
139 */
140 kFx(void*) kArray1_At(kArray1 array, kSize index);
141
142 /**
143 * Returns the array item type.
144 *
145 * @public @memberof kArray1
146 * @param array Array object.
147 * @return Array item type.
148 */
149 kFx(kType) kArray1_ItemType(kArray1 array);
150
151 /**
152 * Returns the array item size.
153 *
154 * @public @memberof kArray1
155 * @param array Array object.
156 * @return Array item size.
157 */
158 kFx(kSize) kArray1_ItemSize(kArray1 array);
159
160 /**
161 * Returns the array length, in elements.
162 *
163 * @public @memberof kArray1
164 * @param array Array object.
165 * @return Array length (in elements).
166 */
167 kFx(kSize) kArray1_Length(kArray1 array);
168
169 /**
170 * Returns the array item count, in elements.
171 *
172 * This method is provided for symmetry with kArray2/kArray3. In practice,
173 * the item count for a 1D array is always equal to the length.
174 *
175 * @public @memberof kArray1
176 * @param array Array object.
177 * @return Array item count (in elements).
178 */
179 kFx(kSize) kArray1_Count(kArray1 array);
180
181 #define kArray1_ItemType_(ARRAY) kxArray1_ItemType_(ARRAY) ///< Macro version of kArray1_ItemType.
182 #define kArray1_ItemSize_(ARRAY) kxArray1_ItemSize_(ARRAY) ///< Macro version of kArray1_ItemSize.
183 #define kArray1_Length_(ARRAY) kxArray1_Length_(ARRAY) ///< Macro version of kArray1_Length.
184 #define kArray1_Count_(ARRAY) kxArray1_Count_(ARRAY) ///< Macro version of kArray1_Count.
185 #define kArray1_Data_(ARRAY) kxArray1_Data_(ARRAY) ///< Macro version of kArray1_Data.
186 #define kArray1_DataSize_(ARRAY) kxArray1_DataSize_(ARRAY) ///< Macro version of kArray1_DataSize.
187 #define kArray1_At_(ARRAY, INDEX) kxArray1_At_(ARRAY, INDEX) ///< Macro version of kArray1_At.
188
189 /** Accesses an array element at the specified index, and casts the value to the specified type. */
190 #define kArray1_As_(ARRAY, INDEX, TYPE) kxArray1_As_(ARRAY, INDEX, TYPE)
191
192 kEndHeader()
193
194 #include <kApi/Data/kArray1.x.h>
195
196 #endif
kArray1
Represents a 1D array.
kArray1::kArray1_ItemType
kType kArray1_ItemType(kArray1 array)
Returns the array item type.
kArray1::kArray1_Data
void * kArray1_Data(kArray1 array)
Returns a pointer to the array item buffer.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kArray1::kArray1_ItemSize
kSize kArray1_ItemSize(kArray1 array)
Returns the array item size.
kArray1::kArray1_Attach
kStatus kArray1_Attach(kArray1 array, void *items, kType itemType, kSize length)
Attaches the array to an external item buffer.
kArray1::kArray1_Zero
kStatus kArray1_Zero(kArray1 array)
Sets all array element bits to zero.
kArray1::kArray1_Count
kSize kArray1_Count(kArray1 array)
Returns the array item count, in elements.
kApiDef.h
Essential API declarations.
kArray1::kArray1_Allocate
kStatus kArray1_Allocate(kArray1 array, kType itemType, kSize length)
Reallocates the internal array item buffer.
kArray1::kArray1_SetItem
kStatus kArray1_SetItem(kArray1 array, kSize index, const void *item)
Sets the value of an item.
kArray1::kArray1_Item
kStatus kArray1_Item(kArray1 array, kSize index, void *item)
Gets the value of an item.
kArray1::kArray1_Length
kSize kArray1_Length(kArray1 array)
Returns the array length, in elements.
kType
Represents metadata about a type (class, interface, or value).
kArray1::kArray1_Construct
kStatus kArray1_Construct(kArray1 *array, kType itemType, kSize length, kAlloc allocator)
Constructs a kArray1 object.
kArray1::kArray1_DataSize
kSize kArray1_DataSize(kArray1 array)
Reports the size, in bytes, of the array item buffer.
kArray1::kArray1_At
void * kArray1_At(kArray1 array, kSize index)
Returns a pointer to the specified item in the array.
kStatus
Represents an enumeration of error codes.
kArray1::kArray1_Assign
kStatus kArray1_Assign(kArray1 array, kArray1 source)
Performs a shallow copy of the source array.