# String handling

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. |
 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.

- It is necessary to free strings only when the user has finished with them completely. All resizing of strings is accomplished automatically by the _CP_ routines. For example, if a process repeatedly reads data into a buffer via the _CP_read call, this buffer will be automatically resized to fit the new data within the _CP_read call at every read.

 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.

---
Source: https://d3codex.com/cfunctions/string-handling/ - part of the D3Codex reference.