Str_Copy_N()

Copies string character values from one string memory buffer to another memory buffer, up to a maximum number of characters.

Files

lib_str.h/lib_str.c

Prototype

          CPU_CHAR  *Str_Copy_N (       CPU_CHAR    *pstr_dest,
                                 const  CPU_CHAR    *pstr_src,
                                        CPU_SIZE_T   len_max);

Arguments

pstr_dest

Pointer to the string memory buffer to copy string characters into.

pstr_src

Pointer to the string memory buffer to copy string characters from.

len_max

Maximum number of string characters to copy.

Returned Value

Pointer to copied destination string, if no errors;

Pointer to NULL, otherwise.

Required Configuration

None.

Notes / Warnings

The maximum number of characters copied may and should include the terminating NULL character. Note that IEEE Std 1003.1, 2004 Edition, Section ‘strncpy() : APPLICATION USAGE’ states that “if there is no null byte in the first [len_max] bytes of the array pointed to by [pstr_src], the result is not null-terminated”.

Destination buffer size (pstr_dest) is not validated; buffer overruns must be prevented by caller. Destination buffer size should be large enough to accomodate the entire source string size including its terminating NULL character.

String copy terminates if either string pointer points to or overlaps the NULL address.

Example Usage

          CPU_CHAR   AppBuf[20];
          CPU_CHAR  *pstr;


          pstr = Str_Copy_N(&AppBuf[0], "Hello World!", (sizeof(AppBuf)));
          if (pstr == (CPU_CHAR *)0) {
              printf("STRING COPY FAILED!");
          }