Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kUtils.h
Go to the documentation of this file.
1 /**
2 * @file kUtils.h
3 * @brief Utility functions.
4 *
5 * @internal
6 * Copyright (C) 2008-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #include <kApi/kApiDef.h> //--inclusion order controlled by kApiDef
11
12 #ifndef K_API_UTILS_H
13 #define K_API_UTILS_H
14
15 kBeginHeader()
16
17 /**
18 * @class kUtils
19 * @ingroup kApi-Utils
20 * @brief Collection of utility functions.
21 */
22
23 /**
24 * Destroys an object and resets the object handle to kNULL.
25 *
26 * @public @memberof kUtils
27 * @param object Pointer to object, or pointer to kNULL.
28 * @return Operation status.
29 */
30 kFx(kStatus) kDestroyRef(kObject* object);
31
32 /**
33 * Disposes an object and resets the object handle to kNULL.
34 *
35 * @public @memberof kUtils
36 * @param object Pointer to object, or pointer to kNULL.
37 * @return Operation status.
38 */
39 kFx(kStatus) kDisposeRef(kObject* object);
40
41 /**
42 * Shares an object and sets a handle to refer to the shared object.
43 *
44 * @public @memberof kUtils
45 * @param object Receives shared object handle.
46 * @param source Object to be shared (or kNULL).
47 * @return Operation status.
48 */
49 kFx(kStatus) kShareRef(kObject* object, kObject source);
50
51 /**
52 * Loads an object from file using kDat-5 serialization.
53 *
54 * @public @memberof kUtils
55 * @param object Receives deserialized object.
56 * @param fileName Path of the file to load.
57 * @param allocator Memory allocator to use for loaded object (or kNULL for default).
58 * @return Operation status.
59 */
60 kFx(kStatus) kLoad5(kObject* object, const kChar* fileName, kAlloc allocator);
61
62 /**
63 * Saves an object to file using kDat-5 serialization.
64 *
65 * @public @memberof kUtils
66 * @param object Object to be serialized.
67 * @param fileName Path of the file to save.
68 * @return Operation status.
69 */
70 kFx(kStatus) kSave5(kObject object, const kChar* fileName);
71
72 /**
73 * Loads an object from file using kDat-6 serialization.
74 *
75 * @public @memberof kUtils
76 * @param object Receives deserialized object.
77 * @param fileName Path of the file to load.
78 * @param allocator Memory allocator to use for loaded object (or kNULL for default).
79 * @return Operation status.
80 */
81 kFx(kStatus) kLoad6(kObject* object, const kChar* fileName, kAlloc allocator);
82
83 /**
84 * Saves an object to file using kDat-6 serialization.
85 *
86 * @public @memberof kUtils
87 * @param object Object to be serialized.
88 * @param fileName Path of the file to save.
89 * @return Operation status.
90 */
91 kFx(kStatus) kSave6(kObject object, const kChar* fileName);
92
93 /**
94 * Allocates a block of memory from the application heap.
95 *
96 * Memory allocated with this function should be freed with the kMemFree function.
97 *
98 * @public @memberof kUtils
99 * @param size Size of memory to allocate, in bytes.
100 * @param mem Receives a pointer to the memory block.
101 * @return Operation status.
102 */
103 kFx(kStatus) kMemAlloc(kSize size, void* mem);
104
105 /**
106 * Allocates and zero-initializes block of memory from the application heap.
107 *
108 * Memory allocated with this function should be freed with the kMemFree function.
109 *
110 * @public @memberof kUtils
111 * @param size Size of memory to allocate, in bytes.
112 * @param mem Receives a pointer to the memory block.
113 * @return Operation status.
114 */
115 kFx(kStatus) kMemAllocZero(kSize size, void* mem);
116
117 /**
118 * Frees a block of memory that was allocated using kMemAlloc or kMemAllocZero.
119 *
120 * @public @memberof kUtils
121 * @param mem Pointer to memory to free (or kNULL).
122 * @return Operation status.
123 */
124 kFx(kStatus) kMemFree(void* mem);
125
126 /**
127 * Frees a block of memory that was allocated using kMemAlloc or kMemAllocZero and resets the memory pointer to kNULL.
128 *
129 * @public @memberof kUtils
130 * @param mem Pointer to pointer to memory to free (or pointer to kNULL).
131 * @return Operation status.
132 */
133 kFx(kStatus) kMemFreeRef(void* mem);
134
135 /**
136 * Sets a block of memory to the given byte value.
137 *
138 * @public @memberof kUtils
139 * @param dest Destination for the memory set operation.
140 * @param fill Value to be set.
141 * @param size Size of memory block to be set, in bytes.
142 * @return Operation status.
143 */
144 kFx(kStatus) kMemSet(void* dest, kByte fill, kSize size);
145
146 /**
147 * Copies memory from a source buffer to a non-overlapping destination.
148 *
149 * @public @memberof kUtils
150 * @param dest Destination for the memory copy.
151 * @param src Source for the memory copy.
152 * @param size Size of memory block to be copied, in bytes.
153 * @return Operation status.
154 */
155 kFx(kStatus) kMemCopy(void* dest, const void* src, kSize size);
156
157 /**
158 * Copies memory from a source buffer to a potentially-overlapping destination.
159 *
160 * @public @memberof kUtils
161 * @param dest Destination for the memory copy.
162 * @param src Source for the memory copy.
163 * @param size Size of memory block to be copied, in bytes.
164 * @return Operation status.
165 */
166 kFx(kStatus) kMemMove(void* dest, const void* src, kSize size);
167
168 /**
169 * Compares one memory buffer with another.
170 *
171 * @public @memberof kUtils
172 * @param a First buffer.
173 * @param b Second buffer.
174 * @param size Size of memory buffers to be compared, in bytes.
175 * @return kTRUE if the memory buffers are equal; otherwise, kFALSE.
176 * @return Operation status.
177 */
178 kFx(kBool) kMemEquals(const void* a, const void* b, kSize size);
179
180 /**
181 * Copies characters from source to destination.
182 *
183 * If the buffer is insufficient, the copy will transfer as many characters
184 * as possible, null-terminate the resulting string, and return kERROR_INCOMPLETE.
185 *
186 * If the destination capacity is zero, kERROR_PARAMETER will be returned.
187 *
188 * @public @memberof kUtils
189 * @param dest Destination for the string copy.
190 * @param capacity Capacity of destination buffer, in characters.
191 * @param src Source for the string copy.
192 * @return Operation status.
193 */
194 kFx(kStatus) kStrCopy(kChar* dest, kSize capacity, const kChar* src);
195
196 /**
197 * Appends characters from source to destination.
198 *
199 * If the buffer is insufficient, the concatenation will transfer as many characters
200 * as possible, null-terminate the resulting string, and return kERROR_INCOMPLETE.
201 *
202 * If the destination capacity is zero, kERROR_PARAMETER will be returned.
203 *
204 * @public @memberof kUtils
205 * @param dest Destination string to append to.
206 * @param capacity Capacity of destination buffer, in characters.
207 * @param src Source string to append.
208 * @return Operation status.
209 */
210 kFx(kStatus) kStrCat(kChar* dest, kSize capacity, const kChar* src);
211
212 /**
213 * Converts characters in the given sequence to lower case.
214 *
215 * This function currently supports conversion of characters only within the ASCII character range.
216 *
217 * @public @memberof kUtils
218 * @param str Character sequence to convert.
219 * @return Operation status.
220 */
221 kFx(kStatus) kStrToLower(kChar* str);
222
223 /**
224 * Tests a pair of character sequences for equality.
225 *
226 * @public @memberof kUtils
227 * @param a First string.
228 * @param b Second string.
229 * @return kTRUE if the character sequences are equal; otherwise, kFALSE.
230 */
231 kFx(kBool) kStrEquals(const kChar* a, const kChar* b);
232
233 /**
234 * Compares one string to another.
235 *
236 * The result is negative if the string a is lexically less than string b, positive
237 * if string a is lexically greater than string b, and zero if they are equal.
238 *
239 * This function performs comparison of UTF-8 encoded characters by Unicode code point.
240 *
241 * @public @memberof kUtils
242 * @param a First string.
243 * @param b Second string.
244 * @return Positive if a is greater than b, negative if b is greater than a; otherwise zero.
245 */
246 kFx(k32s) kStrCompare(const kChar* a, const kChar* b);
247
248 /**
249 * Performs a case-insenstive comparison of two strings.
250 *
251 * This function currently supports comparison of characters only within the ASCII character range.
252 *
253 * @public @memberof kUtils
254 * @param a First string.
255 * @param b Second string.
256 * @return Positive if a is greater than b, negative if b is greater than a; otherwise zero.
257 */
258 kFx(k32s) kStrCompareLower(const kChar* a, const kChar* b);
259
260 /**
261 * Determines the number of kChar units in a characater sequence.
262 *
263 * @public @memberof kUtils
264 * @param str Input string.
265 * @return Number of kChar units in sequence.
266 */
267 kFx(kSize) kStrLength(const kChar* str);
268
269 /**
270 * Finds the first occurrence of a character sequence.
271 *
272 * @public @memberof kUtils
273 * @param str Input string to be searched.
274 * @param subStr Substring to find.
275 * @return Pointer to first occurrence, or kNULL.
276 */
277 kFx(const kChar*) kStrFindFirst(const kChar* str, const kChar* subStr);
278
279 /**
280 * Finds the last occurrence of a character sequence.
281 *
282 * @public @memberof kUtils
283 * @param str Input string to be searched.
284 * @param subStr Substring to find.
285 * @return Pointer to last occurrence, or kNULL.
286 */
287 kFx(const kChar*) kStrFindLast(const kChar* str, const kChar* subStr);
288
289 /**
290 * Formats a string using printf-style arguments.
291 *
292 * This function relies on formatting support from underlying system libraries; results can vary.
293 *
294 * If the output buffer is insufficient, kERROR_INCOMPLETE will be returned. In this case, the
295 * destination buffer will contain truncated, null-terminated output.
296 *
297 * @public @memberof kUtils
298 * @param dest Destination for formatted output.
299 * @param capacity Capacity of output buffer.
300 * @param format Print format string.
301 * @return Operation status.
302 */
303 kFx(kStatus) kStrPrintf(kChar* dest, kSize capacity, const kChar* format, ...);
304
305 /**
306 * Variable-argument version of kStrPrintf.
307 *
308 * @public @memberof kUtils
309 * @param dest Destination for formatted output.
310 * @param capacity Capacity of output buffer.
311 * @param format Print format string.
312 * @param argList Variable argument list.
313 * @return Operation status.
314 * @see kStrPrintf
315 */
316 kFx(kStatus) kStrPrintvf(kChar* dest, kSize capacity, const kChar* format, kVarArgList argList);
317
318 /**
319 * Writes to logging handler (if registered).
320 *
321 * @public @memberof kUtils
322 * @param format Print format string.
323 * @return Operation status.
324 */
325 kFx(kStatus) kLogf(const kChar* format, ...);
326
327 /**
328 * Variable-argument version of kLogf.
329 *
330 * @public @memberof kUtils
331 * @param format Print format string.
332 * @param argList Variable argument list.
333 * @return Operation status.
334 * @see kLogf
335 */
336 kFx(kStatus) kLogvf(const kChar* format, kVarArgList argList);
337
338 /**
339 * Generates a random 32-bit number.
340 *
341 * @public @memberof kUtils
342 * @return Random 32-bit number.
343 */
344 kFx(k32u) kRandom32u();
345
346 /**
347 * Generates a random 64-bit number.
348 *
349 * @public @memberof kUtils
350 * @return Random 64-bit number.
351 */
352 kFx(k64u) kRandom64u();
353
354 /**
355 * Generates a random number of type kSize.
356 *
357 * @public @memberof kUtils
358 * @return Random number.
359 */
360 kFx(kSize) kRandomSize();
361
362 kEndHeader()
363
364 #include <kApi/Utils/kUtils.x.h>
365
366 #endif
k32u
Represents a 32-bit unsigned integer.
kUtils::kSave5
kStatus kSave5(kObject object, const kChar *fileName)
Saves an object to file using kDat-5 serialization.
kUtils::kStrEquals
kBool kStrEquals(const kChar *a, const kChar *b)
Tests a pair of character sequences for equality.
kUtils::kStrToLower
kStatus kStrToLower(kChar *str)
Converts characters in the given sequence to lower case.
k64u
Represents a 64-bit unsigned integer.
kUtils::kStrCopy
kStatus kStrCopy(kChar *dest, kSize capacity, const kChar *src)
Copies characters from source to destination.
kUtils::kMemCopy
kStatus kMemCopy(void *dest, const void *src, kSize size)
Copies memory from a source buffer to a non-overlapping destination.
kUtils::kSave6
kStatus kSave6(kObject object, const kChar *fileName)
Saves an object to file using kDat-6 serialization.
kUtils::kStrCat
kStatus kStrCat(kChar *dest, kSize capacity, const kChar *src)
Appends characters from source to destination.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kUtils::kMemFree
kStatus kMemFree(void *mem)
Frees a block of memory that was allocated using kMemAlloc or kMemAllocZero.
kUtils::kMemAlloc
kStatus kMemAlloc(kSize size, void *mem)
Allocates a block of memory from the application heap.
kUtils::kMemAllocZero
kStatus kMemAllocZero(kSize size, void *mem)
Allocates and zero-initializes block of memory from the application heap.
kUtils::kRandom64u
k64u kRandom64u()
Generates a random 64-bit number.
kUtils::kStrPrintvf
kStatus kStrPrintvf(kChar *dest, kSize capacity, const kChar *format, kVarArgList argList)
Variable-argument version of kStrPrintf.
kChar
Represents a single unit (byte) in a UTF-8 character.
kByte
Represents a byte on the current platform.
kUtils::kStrFindLast
const kChar * kStrFindLast(const kChar *str, const kChar *subStr)
Finds the last occurrence of a character sequence.
kUtils::kLoad5
kStatus kLoad5(kObject *object, const kChar *fileName, kAlloc allocator)
Loads an object from file using kDat-5 serialization.
kUtils::kLogvf
kStatus kLogvf(const kChar *format, kVarArgList argList)
Variable-argument version of kLogf.
kUtils::kMemEquals
kBool kMemEquals(const void *a, const void *b, kSize size)
Compares one memory buffer with another.
kUtils::kDisposeRef
kStatus kDisposeRef(kObject *object)
Disposes an object and resets the object handle to kNULL.
kUtils::kMemMove
kStatus kMemMove(void *dest, const void *src, kSize size)
Copies memory from a source buffer to a potentially-overlapping destination.
kUtils::kStrCompare
k32s kStrCompare(const kChar *a, const kChar *b)
Compares one string to another.
kUtils::kStrFindFirst
const kChar * kStrFindFirst(const kChar *str, const kChar *subStr)
Finds the first occurrence of a character sequence.
kUtils::kDestroyRef
kStatus kDestroyRef(kObject *object)
Destroys an object and resets the object handle to kNULL.
kUtils::kShareRef
kStatus kShareRef(kObject *object, kObject source)
Shares an object and sets a handle to refer to the shared object.
kApiDef.h
Essential API declarations.
k32s
Represents a 32-bit signed integer.
kUtils::kStrLength
kSize kStrLength(const kChar *str)
Determines the number of kChar units in a characater sequence.
kUtils::kStrCompareLower
k32s kStrCompareLower(const kChar *a, const kChar *b)
Performs a case-insenstive comparison of two strings.
kUtils::kRandom32u
k32u kRandom32u()
Generates a random 32-bit number.
kUtils::kLoad6
kStatus kLoad6(kObject *object, const kChar *fileName, kAlloc allocator)
Loads an object from file using kDat-6 serialization.
kUtils::kMemFreeRef
kStatus kMemFreeRef(void *mem)
Frees a block of memory that was allocated using kMemAlloc or kMemAllocZero and resets the memory poi...
kUtils::kMemSet
kStatus kMemSet(void *dest, kByte fill, kSize size)
Sets a block of memory to the given byte value.
kUtils::kRandomSize
kSize kRandomSize()
Generates a random number of type kSize.
kObject
Root of all class types in the Zen type system.
kStatus
Represents an enumeration of error codes.
kUtils::kStrPrintf
kStatus kStrPrintf(kChar *dest, kSize capacity, const kChar *format,...)
Formats a string using printf-style arguments.
kUtils::kLogf
kStatus kLogf(const kChar *format,...)
Writes to logging handler (if registered).
kBool
Represents a boolean value.