Memory and String Handling

This group contains memory allocation functions as well as string utility functions. More...

Detailed Description

This group contains memory allocation functions as well as string utility functions.

All returned values must be freed after use with GlgFree to avoid memory leaks.

Functions
void *	GlgAlloc (GlgLong size)
	Allocates memory using the Toolkit's memory allocator. More...
char *	GlgConcatResNames (char *resource_name1, char *resource_name2)
	Creates a composite resource path from two components. More...
char *	GlgConcatStrings (char *string1, char *string2)
	Concatenates two character strings. More...
char *	GlgCreateIndexedName (char *template_name, GlgLong resource_index)
	Creates a string with a name of an enumerated resource. More...
void	GlgFree (void *ptr)
	Frees memory used to store character strings or allocated using GlgAlloc. More...
GlgBoolean	GlgPreAlloc (GlgLong size, GlgPreAllocType type)
	Preallocates memory under the control of mission critical real-time applications. More...
char *	GlgStrClone (char *string)
	Creates a copy of a character string. More...

Function Documentation

GlgAlloc()

void* GlgAlloc

(

GlgLong

size

)

Allocates memory using the Toolkit's memory allocator.

The memory must be freed with GlgAlloc when it is no longer used.

Parameters

size	Specifies the size of a memory block in bytes.

Returns

Pointer to the allocated memory.

GlgConcatResNames()

char* GlgConcatResNames	(	char *	resource_name1,
		char *	resource_name2
	)

Creates a composite resource path from two components.

Parameters

resource_name1	Specifies the first resource path component.
resource_name2	Specifies the second resource path component.

Returns

Created resource path.

This function creates and returns a resource path formed by concatenating the two components with the / character between them. The function checks if a trailing / separator is already present in the first string, and adds it only if the separator is not present.

Either argument may be NULL, in which case the returned string will precisely equal the input value of the other argument.

The string containing the returned resource path should be freed later with GlgFree.

Examples

The following code:

char * resource_path = GlgConcatResNames( "DataGroup", "DataSample2" );
printf( "resource_path: %s\n", resource_path );
GlgFree( resource_path );

produces the following output:

resource_path: DataGroup/DataSample2

Multiple calls to GlgConcatResNames may be used to create composite paths from more than two components:

char * temp_name = GlgConcatResNames( "DataGroup", "DataSample2" );
char * resource_path = GlgConcatResNames( temp_name, "Value" );
GlgFree( temp_name )
printf( "resource_path: %s\n", resource_path );
GlgFree( resource_path );

producing the following output:

resource_path: DataGroup/DataSample2/Value

GlgConcatStrings()

char* GlgConcatStrings	(	char *	string1,
		char *	string2
	)

Concatenates two character strings.

Parameters

string1	The first string to be concatenated.
string2	The second string to be concatenated.

Returns

The concatenated string.

This function creates a new string from two input strings. Either input string may be NULL, in which case the returned string is a copy of the non-NULL input string. If both strings are NULL, then NULL is returned.

The output of this function must be freed with GlgFree. GlgFree also handles NULL pointers, so the following code may be used without needing to check for NULL values:

string3 = GlgConcatStrings( string1, string2 );
...
GlgFree( string3 );

GlgCreateIndexedName()

char* GlgCreateIndexedName	(	char *	template_name,
		GlgLong	resource_index
	)

Creates a string with a name of an enumerated resource.

Parameters

template_name	A character string containing the template name to be expanded. This name uses the % character to define the expansion position.
resource_index	Specifies the number to use for expanding the % character in the template name.

Returns

Created resource name.

This function creates and returns a resource name by replacing the first (leftmost) occurrence of the % expansion character within the template name with the number corresponding to the resource_index parameter. If the template name does not contain the expansion character, the number is added to the end of the name. The returned expanded name should later be freed with GlgFree.

Examples

The following code:

for( int i=0; i<3; ++i )
{
   char * name = GlgCreateIndexedName( "XLabelGroup/XLabel%/String", i );
   printf( "Name: %s\n", name );
   GlgFree( name );
}

produces the following output:

Name: XLabelGroup/XLabel0/String
Name: XLabelGroup/XLabel1/String
Name: XLabelGroup/XLabel2/String

GlgCreateIndexedName may be used repeatedly if a template name has more than one expansion character. For example, the following code:

char * name1 = GlgCreateIndexedName( "Chart%/Plots/Plot#%/Value", 4 );
char * name2 = GlgCreateIndexedName( name1, 3 );
GlgFree( name1 );
printf( "Name: %s\n", name2 );
GlgFree( name2 );

produces the following output:

Name: Chart4/Plots/Plot#3/Value

GlgFree()

void GlgFree

(

void *

ptr

)

Frees memory used to store character strings or allocated using GlgAlloc.

Parameters

ptr	Specifies a memory pointer to be freed.

This function is used to free memory allocated by GlgAlloc and GLG string utilities. This is not to be used to free the memory occupied by any GLG object (GlgObject). Use GlgDropObject and GlgReferenceObject to manage these objects.

The function checks for NULL address pointers, and will not fail or generate an error message if a NULL pointer is passed.

GlgPreAlloc()

GlgBoolean GlgPreAlloc	(	GlgLong	size,
		GlgPreAllocType	type
	)

Preallocates memory under the control of mission critical real-time applications.

Parameters

size

The size of the memory to allocate.

type

The allocation type that controls the meaning of the size parameter: GLG_PREALLOC_MEMORY - allocates a specified number of spare memory blocks. GLG_PREALLOC_POLYGON_POINT_BUFFERS - allocates a buffer of the requested size to be used for rendering large polygons. It can be set to the maximum expected number of points in one polygon. GLG_PREALLOC_GRAPH_POINT_BUFFERS - allocates a buffer of the requested size used for rendering plots of real-time charts. It can be set to the maximum expected number of points in one plot. GLG_PREALLOC_TESS_BUFFERS - allocates a buffer of the requested size for tessellation vertices. The buffer is used by the OpenGL driver for tessellating filled polygons; it is not used by the GDI driver or in GTK.

Returns

Success or failure status.

Mission-critical applications can use this function to preallocate memory on start-up and then allocate more memory as needed outside of the application's critical sections.

The GlgGetLParameter function can be used to query the amount of spare memory in the preallocated memory blocks. If the buffers are not preallocated, they are allocated and automatically adjusted as needed.

GlgStrClone()

char* GlgStrClone

(

char *

string

)

Creates a copy of a character string.

The copy should later be freed with GlgFree.

Parameters

string

The string to be copied. If a NULL pointer is passed, the return value will also be NULL.

Returns

The cloned string.