Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
Public Member Functions
kUtils Class Reference
kApi/Utils

## Description

Collection of utility functions.

## Public Member Functions
kStatus | kDestroyRef (kObject *object)
| Destroys an object and resets the object handle to kNULL. More...
kStatus | kDisposeRef (kObject *object)
| Disposes an object and resets the object handle to kNULL. More...
kStatus | kLoad5 (kObject *object, const kChar *fileName, kAlloc allocator)
| Loads an object from file using kDat-5 serialization. More...
kStatus | kLoad6 (kObject *object, const kChar *fileName, kAlloc allocator)
| Loads an object from file using kDat-6 serialization. More...
kStatus | kLogf (const kChar *format,...)
| Writes to logging handler (if registered). More...
kStatus | kLogvf (const kChar *format, kVarArgList argList)
| Variable-argument version of kLogf. More...
kStatus | kMemAlloc (kSize size, void *mem)
| Allocates a block of memory from the application heap. More...
kStatus | kMemAllocZero (kSize size, void *mem)
| Allocates and zero-initializes block of memory from the application heap. More...
kStatus | kMemCopy (void *dest, const void *src, kSize size)
| Copies memory from a source buffer to a non-overlapping destination. More...
kBool | kMemEquals (const void *a, const void *b, kSize size)
| Compares one memory buffer with another. More...
kStatus | kMemFree (void *mem)
| Frees a block of memory that was allocated using kMemAlloc or kMemAllocZero. More...
kStatus | kMemFreeRef (void *mem)
| Frees a block of memory that was allocated using kMemAlloc or kMemAllocZero and resets the memory pointer to kNULL. More...
kStatus | kMemMove (void *dest, const void *src, kSize size)
| Copies memory from a source buffer to a potentially-overlapping destination. More...
kStatus | kMemSet (void *dest, kByte fill, kSize size)
| Sets a block of memory to the given byte value. More...
k32u | kRandom32u ()
| Generates a random 32-bit number. More...
k64u | kRandom64u ()
| Generates a random 64-bit number. More...
kSize | kRandomSize ()
| Generates a random number of type kSize. More...
kStatus | kSave5 (kObject object, const kChar *fileName)
| Saves an object to file using kDat-5 serialization. More...
kStatus | kSave6 (kObject object, const kChar *fileName)
| Saves an object to file using kDat-6 serialization. More...
kStatus | kShareRef (kObject *object, kObject source)
| Shares an object and sets a handle to refer to the shared object. More...
kStatus | kStrCat (kChar *dest, kSize capacity, const kChar *src)
| Appends characters from source to destination. More...
k32s | kStrCompare (const kChar *a, const kChar *b)
| Compares one string to another. More...
k32s | kStrCompareLower (const kChar *a, const kChar *b)
| Performs a case-insenstive comparison of two strings. More...
kStatus | kStrCopy (kChar *dest, kSize capacity, const kChar *src)
| Copies characters from source to destination. More...
kBool | kStrEquals (const kChar *a, const kChar *b)
| Tests a pair of character sequences for equality. More...
const kChar * | kStrFindFirst (const kChar *str, const kChar *subStr)
| Finds the first occurrence of a character sequence. More...
const kChar * | kStrFindLast (const kChar *str, const kChar *subStr)
| Finds the last occurrence of a character sequence. More...
kSize | kStrLength (const kChar *str)
| Determines the number of kChar units in a characater sequence. More...
kStatus | kStrPrintf (kChar *dest, kSize capacity, const kChar *format,...)
| Formats a string using printf-style arguments. More...
kStatus | kStrPrintvf (kChar *dest, kSize capacity, const kChar *format, kVarArgList argList)
| Variable-argument version of kStrPrintf. More...
kStatus | kStrToLower (kChar *str)
| Converts characters in the given sequence to lower case. More...

## Member Function Documentation

kStatus kDestroyRef | ( | kObject * | object | ) |

Destroys an object and resets the object handle to kNULL.

Parameters

  object | Pointer to object, or pointer to kNULL.

Returns
  Operation status.

kStatus kDisposeRef | ( | kObject * | object | ) |

Disposes an object and resets the object handle to kNULL.

Parameters

  object | Pointer to object, or pointer to kNULL.

Returns
  Operation status.

kStatus kLoad5 | ( | kObject * | object,
|  | const kChar * | fileName,
|  | kAlloc | allocator
| ) |  |

Loads an object from file using kDat-5 serialization.

Parameters

  object | Receives deserialized object.
  fileName | Path of the file to load.
  allocator | Memory allocator to use for loaded object (or kNULL for default).

Returns
  Operation status.

kStatus kLoad6 | ( | kObject * | object,
|  | const kChar * | fileName,
|  | kAlloc | allocator
| ) |  |

Loads an object from file using kDat-6 serialization.

Parameters

  object | Receives deserialized object.
  fileName | Path of the file to load.
  allocator | Memory allocator to use for loaded object (or kNULL for default).

Returns
  Operation status.

kStatus kLogf | ( | const kChar * | format,
|  |  | ...
| ) |  |

Writes to logging handler (if registered).

Parameters

  format | Print format string.

Returns
  Operation status.

kStatus kLogvf | ( | const kChar * | format,
|  | kVarArgList | argList
| ) |  |

Variable-argument version of kLogf.

Parameters

  format | Print format string.
  argList | Variable argument list.

Returns
  Operation status.

See also
  kLogf

kStatus kMemAlloc | ( | kSize | size,
|  | void * | mem
| ) |  |

Allocates a block of memory from the application heap.

Memory allocated with this function should be freed with the kMemFree function.

Parameters

  size | Size of memory to allocate, in bytes.
  mem | Receives a pointer to the memory block.

Returns
  Operation status.

kStatus kMemAllocZero | ( | kSize | size,
|  | void * | mem
| ) |  |

Allocates and zero-initializes block of memory from the application heap.

Memory allocated with this function should be freed with the kMemFree function.

Parameters

  size | Size of memory to allocate, in bytes.
  mem | Receives a pointer to the memory block.

Returns
  Operation status.

kStatus kMemCopy | ( | void * | dest,
|  | const void * | src,
|  | kSize | size
| ) |  |

Copies memory from a source buffer to a non-overlapping destination.

Parameters

  dest | Destination for the memory copy.
  src | Source for the memory copy.
  size | Size of memory block to be copied, in bytes.

Returns
  Operation status.

kBool kMemEquals | ( | const void * | a,
|  | const void * | b,
|  | kSize | size
| ) |  |

Compares one memory buffer with another.

Parameters

  a | First buffer.
  b | Second buffer.
  size | Size of memory buffers to be compared, in bytes.

Returns
  kTRUE if the memory buffers are equal; otherwise, kFALSE.
  Operation status.

kStatus kMemFree | ( | void * | mem | ) |

Frees a block of memory that was allocated using kMemAlloc or kMemAllocZero.

Parameters

  mem | Pointer to memory to free (or kNULL).

Returns
  Operation status.

kStatus kMemFreeRef | ( | void * | mem | ) |

Frees a block of memory that was allocated using kMemAlloc or kMemAllocZero and resets the memory pointer to kNULL.

Parameters

  mem | Pointer to pointer to memory to free (or pointer to kNULL).

Returns
  Operation status.

kStatus kMemMove | ( | void * | dest,
|  | const void * | src,
|  | kSize | size
| ) |  |

Copies memory from a source buffer to a potentially-overlapping destination.

Parameters

  dest | Destination for the memory copy.
  src | Source for the memory copy.
  size | Size of memory block to be copied, in bytes.

Returns
  Operation status.

kStatus kMemSet | ( | void * | dest,
|  | kByte | fill,
|  | kSize | size
| ) |  |

Sets a block of memory to the given byte value.

Parameters

  dest | Destination for the memory set operation.
  fill | Value to be set.
  size | Size of memory block to be set, in bytes.

Returns
  Operation status.

k32u kRandom32u | ( |  | ) |

Generates a random 32-bit number.

Returns
  Random 32-bit number.

k64u kRandom64u | ( |  | ) |

Generates a random 64-bit number.

Returns
  Random 64-bit number.

kSize kRandomSize | ( |  | ) |

Generates a random number of type kSize.

Returns
  Random number.

kStatus kSave5 | ( | kObject | object,
|  | const kChar * | fileName
| ) |  |

Saves an object to file using kDat-5 serialization.

Parameters

  object | Object to be serialized.
  fileName | Path of the file to save.

Returns
  Operation status.

kStatus kSave6 | ( | kObject | object,
|  | const kChar * | fileName
| ) |  |

Saves an object to file using kDat-6 serialization.

Parameters

  object | Object to be serialized.
  fileName | Path of the file to save.

Returns
  Operation status.

kStatus kShareRef | ( | kObject * | object,
|  | kObject | source
| ) |  |

Shares an object and sets a handle to refer to the shared object.

Parameters

  object | Receives shared object handle.
  source | Object to be shared (or kNULL).

Returns
  Operation status.

kStatus kStrCat | ( | kChar * | dest,
|  | kSize | capacity,
|  | const kChar * | src
| ) |  |

Appends characters from source to destination.

If the buffer is insufficient, the concatenation will transfer as many characters as possible, null-terminate the resulting string, and return kERROR_INCOMPLETE.

If the destination capacity is zero, kERROR_PARAMETER will be returned.

Parameters

  dest | Destination string to append to.
  capacity | Capacity of destination buffer, in characters.
  src | Source string to append.

Returns
  Operation status.

k32s kStrCompare | ( | const kChar * | a,
|  | const kChar * | b
| ) |  |

Compares one string to another.

The result is negative if the string a is lexically less than string b, positive if string a is lexically greater than string b, and zero if they are equal.

This function performs comparison of UTF-8 encoded characters by Unicode code point.

Parameters

  a | First string.
  b | Second string.

Returns
  Positive if a is greater than b, negative if b is greater than a; otherwise zero.

k32s kStrCompareLower | ( | const kChar * | a,
|  | const kChar * | b
| ) |  |

Performs a case-insenstive comparison of two strings.

This function currently supports comparison of characters only within the ASCII character range.

Parameters

  a | First string.
  b | Second string.

Returns
  Positive if a is greater than b, negative if b is greater than a; otherwise zero.

kStatus kStrCopy | ( | kChar * | dest,
|  | kSize | capacity,
|  | const kChar * | src
| ) |  |

Copies characters from source to destination.

If the buffer is insufficient, the copy will transfer as many characters as possible, null-terminate the resulting string, and return kERROR_INCOMPLETE.

If the destination capacity is zero, kERROR_PARAMETER will be returned.

Parameters

  dest | Destination for the string copy.
  capacity | Capacity of destination buffer, in characters.
  src | Source for the string copy.

Returns
  Operation status.

kBool kStrEquals | ( | const kChar * | a,
|  | const kChar * | b
| ) |  |

Tests a pair of character sequences for equality.

Parameters

  a | First string.
  b | Second string.

Returns
  kTRUE if the character sequences are equal; otherwise, kFALSE.

const kChar * kStrFindFirst | ( | const kChar * | str,
|  | const kChar * | subStr
| ) |  |

Finds the first occurrence of a character sequence.

Parameters

  str | Input string to be searched.
  subStr | Substring to find.

Returns
  Pointer to first occurrence, or kNULL.

const kChar * kStrFindLast | ( | const kChar * | str,
|  | const kChar * | subStr
| ) |  |

Finds the last occurrence of a character sequence.

Parameters

  str | Input string to be searched.
  subStr | Substring to find.

Returns
  Pointer to last occurrence, or kNULL.

kSize kStrLength | ( | const kChar * | str | ) |

Determines the number of kChar units in a characater sequence.

Parameters

  str | Input string.

Returns
  Number of kChar units in sequence.

kStatus kStrPrintf | ( | kChar * | dest,
|  | kSize | capacity,
|  | const kChar * | format,
|  |  | ...
| ) |  |

Formats a string using printf-style arguments.

This function relies on formatting support from underlying system libraries; results can vary.

If the output buffer is insufficient, kERROR_INCOMPLETE will be returned. In this case, the destination buffer will contain truncated, null-terminated output.

Parameters

  dest | Destination for formatted output.
  capacity | Capacity of output buffer.
  format | Print format string.

Returns
  Operation status.

kStatus kStrPrintvf | ( | kChar * | dest,
|  | kSize | capacity,
|  | const kChar * | format,
|  | kVarArgList | argList
| ) |  |

Variable-argument version of kStrPrintf.

Parameters

  dest | Destination for formatted output.
  capacity | Capacity of output buffer.
  format | Print format string.
  argList | Variable argument list.

Returns
  Operation status.

See also
  kStrPrintf

kStatus kStrToLower | ( | kChar * | str | ) |

Converts characters in the given sequence to lower case.

This function currently supports conversion of characters only within the ASCII character range.

Parameters

  str | Character sequence to convert.

Returns
  Operation status.

The documentation for this class was generated from the following file:

- Utils/kUtils.h