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 Unicode 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 00 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 00.
  • If count is greater than the size of the destination string. We can avoid this by giving the count parameter a value of _TRUNCATE, 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:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <wchar.h>
#include <string.h>
int main() {
// initializing strings
wchar_t src[] = L"World";
wchar_t dst[20] = L"Hello";
// concatenating strings
wcsncat_s(dst, 20, src, wcslen(src));
return 0;
}

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 2020 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);

Free Resources

Copyright ©2024 Educative, Inc. All rights reserved