The standard C string type is not sufficient for handling the dynamic nature of D3 strings, so a hybrid data type has been created called CPSTR. This data type provides allocation, deallocation, and resizing of strings at a much higher performance level than that obtained using malloc() and free() with C strings.
WARNING |
The internal structure of a CPSTR is reserved and should not be accessed directly. Failure to abide by this rule will definitely guarantee incompatibility with future releases. |
The structure of a CPSTR is:
Header |
Internal use only-do not modify. |
String |
Character array containing the actual string. |
Terminator |
A single character used for termination. |
Footer |
Internal use only-do not modify. |
The macros listed below are provided to access all desired portions of a CPSTR structure:
Macro |
Description |
_CP_SLEN(s) |
Returns the current length of a string. This length does not include any terminating character such as a segment mark or a null character. |
_CP_SADDR(s) |
Returns a (char *) to the actual string data that may or may not be terminated by a 0x00. Note that this (char *) must not be passed to the free() C function or to any C function that may try to use free() on the (char *). Allocation of CPSTR strings is accomplished via special allocation routines. CPSTR strings must not be allocated with the C function malloc(). The allocation routines provided set necessary internal flags, and are much more efficient than malloc(). NOTE—These routines create dynamic structures which must be deallocated with the routines listed below. |
_CP_str_alloc(l) |
Returns a CPSTR of length l. The actual string data portion of the string is undefined. |
_CP_mkstr(char *s) |
Returns a CPSTR from a C string s terminated by a null character. The string portion of the CPSTR will contain a copy of the C string's data. This function is less efficient than _CP_mkstrl as it must scan the C string to determine its length. |
_CP_mkstrl(char *s, int l) |
Returns a CPSTR from a C string s, of length l. The string portion of the CPSTR will contain a copy of the C string's data. |
_CP_str_realloc(CPSTR **s, int l) |
Resizes the CPSTR s. |
_CP_str_free(CPSTR ** s) |
Frees the desired string s. |
NOTE |
When the _CP_logoff call is executed, all CPSTRs remain valid, but they cannot be passed to any of the _CP_ routines. All CPSTRs are properly cleaned up when the C program exits.
|
The user must be careful with termination. Any _CP_ routine may modify the termination character. Therefore, the user must use the _CP_TERM() macro to terminate CPSTRs with a 0x00 if it is necessary to pass the string portion of it to a standard UNIX routine.