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

Description

Public Member Functions

Member Function Documentation