str5cat - concatenate a (sub)string

SYNOPSYS

	#include "str5.h"

	int str5cat( char * dst, size_t dstsize, const char * src, size_t nb, size_t mode ) ;

	int strtcat( char * dst, size_t dstsize, const char * src);


DESCRIPTION

The str5cat() function appends the first (not null) nb characters from the source string pointed to by src to the end of the string pointed to by dst and adds a terminating null byte ('\0').

The parameter dstsize indicates the full size of the destination array dst.

Parameter mode specifies if truncation is allowed (TRUNC) or not allowed (NOTRUNC).

If srclen is the length of the string pointed to by src and srclen is less than nb, str5cat() only appends srclen characters of src and an additional null byte to dst.

Concatenation is actually made if the size dstsize of the destination buffer dst is large enough or if the TRUNC mode is chosen.  When the remaining size of the destination buffer dst is too small and the TRUNC mode is chosen, only dstsize - strlen(dst) - 1 characters of src are appended and a terminating null byte is added.
After concatenation, the final string dst is always terminated with a null byte and its length is not more than dstsize-1.

Strtcat() concatenates the string pointed to by src (including the terminating null character) to the destination array of size dstsize pointed to by dst.
Truncation is allowed.

The behavior of str5cat() and strtcat() functions is undefined if:
- the destination array dst and the source string src overlap
- dstsize is different from 0 and does not correspond to the actual size of the destination buffer dst.


RETURN VALUE

Str5cat() returns:
- a non negative integer after success: 
    . OKNOTRUNC: no truncation was done during the concatenation
    . OKTRUNC: an allowed truncation was done during the concatenation
- and a negative integer after error:
    . EDSTPAR: a parameter related to the destination buffer is considered as incorrect (dst is a NULL pointer or is a bad-formed string, or dstsize is equal to 0)
    . ESRCPAR: src is a NULL pointer
    . EMODPAR: mode is invalid
    . ETRUNC: dstzise is too small and truncation is not allowed (NOTRUNC mode).  

Strtcat() returns OKNOTRUNC or OKTRUNC after success and EDSTPAR or ESRCPAR after error.

The destination buffer dst remains unchanged if:
- one of the above error conditions is realized
- nb or the length of src is equal to 0. The return value is OKNOTRUNC.


CONFORMING TO

C89 and beyond.


NOTES

Concatenating string is as simple as copying. To concatenate the first n bytes of src:

   r = str5cat(dst,sizeof(dst),src,n,NOTRUNC) ; /* or TRUNC */    

To concatenate the string src at the end of dst with an allowed truncation:

   r = strtcat(dst,DSTSIZE,src) ;