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!");
          }