Str_Cat_N()
Concatenates a string to the end of another string, up to a maximum number of characters.
Files
lib_str.h/lib_str.c
Prototype
CPU_CHAR *Str_Cat_N ( CPU_CHAR *pstr_dest, const CPU_CHAR *pstr_cat, CPU_SIZE_T len_max);
Arguments
pstr_dest
Pointer to the string memory buffer to append string characters into.
pstr_cat
Pointer to the string to concatenate onto the destination string.
len_max
Maximum number of string characters to concatenate.
Returned Value
Pointer to concatenated destination string, if no errors;
Pointer to NULL
, otherwise.
Required Configuration
None.
Notes / Warnings
The maximum number of characters concatenated does not include the terminating NULL
character. Note that IEEE Std 1003.1, 2004 Edition, Section ‘strncat()
: DESCRIPTION’ states that “the strncat()
function shall append ... the array pointed to by [pstr_cat
] to the end of the string pointed to by [pstr_dest
]” but “not more than [len_max
] bytes.”
Destination buffer size (pstr_dest
) is not validated; buffer overruns must be prevented by caller. IEEE Std 1003.1, 2004 Edition, Section ‘strncat()
: DESCRIPTION’ states that “the initial byte of [pstr_cat
] overwrites the null byte at the end of [pstr_dest
]” and “a terminating null byte is always appended to the result”. Therefore, the destination buffer size should be large enough to accomodate the original destination string size plus the entire concatenated string size, but including only a single terminating NULL
character.
String concatenation terminates if either string pointer points to or overlaps the NULL
address.
Example Usage
CPU_CHAR AppBuf[30]; CPU_CHAR *pstr; CPU_SIZE_T len; pstr = Str_Copy_N(&AppBuf[0], "Hello World!", sizeof(AppBuf)); if (pstr != (CPU_CHAR *)0) { len = Str_Len_N(<code >&AppBuf[0], sizeof(AppBuf)); if ((len + sizeof((CPU_CHAR)'\0')) /* If 'Hello' string including its NULL character ... */ < sizeof(AppBuf)) { /* ... fits entirely in AppBuf[], ... */ pstr = Str_Cat_N(&AppBuf[0], "Goodbye World!", /* ... concatenate 'Goodbye' string ... */ /* ... while limiting to remaining AppBuf[] size. */ (sizeof(AppBuf) - (len + sizeof((CPU_CHAR)'\0')))); } else { printf("COPY STRING IS TOO LONG!"); } } if (pstr == (CPU_CHAR *)0) { printf("STRING COPY/CONCATENATION FAILED!"); }