What is wcsncat_s in C?

The wcsncat_s function in C appends a specified number of characters from a given wide string to the end of another wide string. The wcsncat_s function also appends a null-terminating character to the end of the destination string after the concatenation is finished.

If the number of characters to append exceeds the destination string’s size, the wcsncat_s function raises an error.

The process is illustrated below:

Note: A wide string is comprised of characters from the Unicodehttps://unicodebook.readthedocs.io/programming_languages.html character set.

To use the wcsncat_s function, you will need to include the <wchar.h> library in the program, as shown below:

#include <wchar.h>

The prototype of the wcsncat_s function is shown below:

errno_t *wcsncat_s(wchar_t *dest, rsize_t numElements, const wchar_t *src, rsize_t count);

Parameters

The wcsncat_s function takes the following objects as parameters:

• dest: null-terminated destination string to append to
• numElements: the size of the destination string
• src: null-terminated source string to copy from
• count: the maximum number of characters to copy from src to dest

Return value

The wcsncat_s function appends the specified number of characters to the dest string and returns $0$ if the operation is successful; otherwise, it returns a non-zero value and writes the null-terminating character to dest.

The wcsncat_s function will raise an error in the following situations:

• If either src or dest are null pointers.
• If either numElements or count is $0$.
• If count is greater than the size of the destination string. We can avoid this by giving the count parameter a value of _TRUNCATEhttps://learn.microsoft.com/en-us/cpp/c-runtime-library/truncate?view=msvc-160, in which case wcsncat_s will only append the number of characters that the destination string can safely hold.
• If the src and dest strings overlap.

Example

The code below shows how the wcsncat_s function works in C:

Explanation

First, two wide strings are initialized for the source and destination addresses. The ‘L’ identifier in lines 9 and 10 informs the compiler that the Unicode character set is being used.

The wcsncat_s function proceeds to copy the entire source string to the destination address in line 13. The argument 20 specifies that the destination string can hold a maximum of $20$ characters. The wcslen function finds the length of the source string so that the entire string is appended to dest. After the src string is appended, the wcsncpy_s function adds a null-terminating character to dest.

The GCC compiler does not support the function in the example above; hence you will get an implicit declaration of function… error. Use the following variant to get the job done:

wchar_t* wcsncat(wchar_t* dest, const wchar_t* src, size_t count);