memory.h File Reference

#include <ilog/macros.h>
#include <stddef.h>
#include <string.h>

Macros
#define	IL_MALLOC(type, n)
	Allocates an array of objects. More...
#define	IL_REALLOC(type, array, n)
	Re-allocates an array of objects. More...
#define	IL_STRCASECMP(s1, s2)
	Compares two strings in a case-insensitive manner. More...
#define	IL_STRNCASECMP(s1, s2, n)
	Compares two strings in a case-insensitive manner. More...

Functions
char *	IlCopyString (const char *string, IlBoolean zeroIfEmpty=IlTrue)
	Allocates and returns a copy of a string. More...
void	IlFree (void *block)
	Deallocation routine. More...
void *	IlMalloc (std::size_t nBytes)
	Allocation routine. More...
void *	IlMemMove (void *destination, const void *source, std::size_t size)
	Allocation routine. More...
void *	IlRealloc (void *block, std::size_t size)
	Re-allocation routine. More...

Detailed Description

Library: ilog
Declaration of common memory management routines and macros used in Rogue Wave visualization products.

Macro Definition Documentation

IL_MALLOC

#define IL_MALLOC	(		type,
			n
	)

Allocates an array of objects.

The allocation is perfomed using IlMalloc() that is invoked with a total size of n * sizeof(type) bytes.

Note that if type has a constructor, it is not invoked by this macro. This macro is therefore dedicated to allocated arrays of simple types.

A typical use of this macro is:

// Allocate an array of 100 doubles.
IlDouble* array = IL_MALLOC(IlDouble, 100);

Parameters

type	The object type.
n	The number of memory slots to allocate.

Returns

A pointer to a memory location able to store up to n objects of type type or 0 if this memory could not be obtained from the system.
The returned type is a type*and must be released by a call to IlFree().

IL_REALLOC

#define IL_REALLOC	(		type,
			array,
			n
	)

Re-allocates an array of objects.

The re-allocation is perfomed using IlRealloc() that is invoked with a total size of n * sizeof(type) bytes.

Note that if type has a constructor, it is not invoked by this macro. This macro is therefore dedicated to allocated arrays of simple types.

A typical use of this macro is:

// Allocate an array of 100 doubles.
IlDouble* array = IL_MALLOC(IlDouble, 100);
// ...
// Enlarge the array of doubles:
array = IL_REALLOC(IlDouble, array, 300);

Parameters

type	The object type.
array	The initial array to be enlarged.
n	The number of memory slots to allocate.

Returns

A pointer to a memory location able to store up to n objects of type type or 0 if this memory could not be obtained from the system.
The returned type is a type* and must be released by a call to IlFree().
Note that the returned array may be (but does not have to be) the same as array.

See also

IL_MALLOC().

IL_STRCASECMP

#define IL_STRCASECMP	(		s1,
			s2
	)

Compares two strings in a case-insensitive manner.

This macro provides a portable version of _stricmp() (or strcasecmp()). It compares two specified strings, ignoring their case, and returns an integer that indicates their relative position in the lexical order.

Parameters

s1	The first string to compare.
s2	The second string to compare.

Returns

The result of _stricmp(s1, s2) (or the equivalent function of the target platform).

IL_STRNCASECMP

#define IL_STRNCASECMP	(		s1,
			s2,
			n
	)

Compares two strings in a case-insensitive manner.

This macro provides a portable version of _strnicmp() (or strncasecmp()). It compares two specified strings, ignoring their case, up to n characters, and returns an integer that indicates their relative position in the lexical order.

Parameters

s1	The first string to compare.
s2	The second string to compare.
n	The number of characters to compare.

Returns

The result of _strnicmp(s1, s2, n) (or the equivalent function of the target platform).

Function Documentation

IlCopyString()

char* IlCopyString	(	const char *	string,
		IlBoolean	zeroIfEmpty = IlTrue
	)

Allocates and returns a copy of a string.

Memory for the string copy is allocated using the new [] operator, and must therefore be released using the delete [] operator.

Parameters

string	The string to be copied.
zeroIfEmpty	Indicates, if IlTrue, that 0 should be returned if the input string is empty. If zeroIfEmpty is IlFalse and string is an empty string, then a new empty string is allocated and returned.

Returns

A new string where string is copied. The returned value is 0 if string is 0, or if string is empty and zeroIfEmpty is set to IlTrue.

IlFree()

void IlFree

(

void *

block

)

Deallocation routine.

This function is a portable version of free(). It releases a chunk of raw memory that was created by IlMalloc().

Parameters

block

A pointer to the memory block that was obtained by IlMalloc().

IlMalloc()

void* IlMalloc

(

std::size_t

nBytes

)

Allocation routine.

This function is a portable version of malloc(). It allocates raw memory that must be released by IlFree().

Note that if this function fails to allocate storage, it invokes the C++ new-handler function that may have been installed by a call to set_new_handler(). If that handler function returns, a new attempt to allocate the storage is tried.

Parameters

nBytes

The number of bytes to be allocated.

Returns

A pointer to the memory block that was allocated, or 0 if this memory could not be obtained from the system.

IlMemMove()

void* IlMemMove	(	void *	destination,
		const void *	source,
		std::size_t	size
	)

Allocation routine.

This function is a portable version of memmove(). It copies bytes from a memory location to another.

Parameters

destination	The destination array where the content of source is to be copied. It must be able to store at least size consecutive bytes.
source	The source array to be copied. It must be able to access at least size consecutive bytes.
size	The number of bytes to be copied.

Returns

The value of destination.

IlRealloc()

void* IlRealloc	(	void *	block,
		std::size_t	size
	)

Re-allocation routine.

This function is a portable version of realloc(). It re-allocates raw memory that was allocated by IlMalloc(), and that must be released by IlFree(). It is typically used to enlarge a previously allocated memory block.

Note that if this function fails to allocate storage, it invokes the C++ new-handler function that may have been installed by a call to set_new_handler(). If that handler function returns, a new attempt to allocate the storage is tried.

Parameters

block	The initial memory block to be enlarged.
size	The number of bytes to be allocated.

Returns

A pointer to the new memory block that was allocated, or 0 if this memory could not be obtained from the system. This pointer can be (but does not have to be) the same as block.