wcsncat

Concatenates a counted number of wide-characters from one string to another.

Format

#include  <wchar.h>

wchar_t *wcsncat  (wchar_t *wstr_1, const wchar_t
                  *wstr_2, size_t maxchar);

Function Variants This function also has variants named _wcsncat32 and _wcsncat64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

Arguments

wstr_1, wstr_2: Pointers to null-terminated wide-character strings.
maxchar: The maximum number of wide characters from wstr_2 that are copied to wstr_1. If maxchar is 0, no characters are copied from wstr_2.

Description

This function appends wide characters from the wide-character string wstr_2 to the end of wstr_1, up to a maximum of maxchar characters. A terminating null wide character is always appended to the result of the wcsncat function. Therefore, the maximum number of wide characters that can end up in wstr_1 is wcslen(wstr_1) + maxchar + 1).

Return Values

x The first argument, wstr_ 1, which is assumed to be large enough to hold the concatenated result.

Example

#include <stdlib.h>
#include <stdio.h>
#include <wchar.h>
#include <string.h>

/* This program concatenates two wide-character strings using the     */
/* wcsncat function, and then manually compares the result to the     */
/* expected result                                                    */

#define S1LENGTH 10
#define S2LENGTH 8
#define SIZE     3

main()
{
    int         i;
    wchar_t     s1buf[S1LENGTH+S2LENGTH];
    wchar_t     s2buf[S2LENGTH];
    wchar_t     test1[S1LENGTH+S2LENGTH];

    /* Initialize the three wide-character strings */

    if (mbstowcs(s1buf, "abcmnexyz", S1LENGTH) == -1) {
        perror("mbstowcs");
        exit(EXIT_FAILURE);
    }

    if (mbstowcs(s2buf, " orthis", S2LENGTH) == -1) {
        perror("mbstowcs");
        exit(EXIT_FAILURE);
    }

    if (mbstowcs(test1, "abcmnexyz orthis", S1LENGTH+SIZE) == -1) {
        perror("mbstowcs");
        exit(EXIT_FAILURE);
    }

    /* Concatenate s1buf with SIZE characters from s2buf, placing the */
    /* result into s1buf. Then compare s1buf with the expected result */
    /* in test1.                                                      */

    wcsncat(s1buf, s2buf, SIZE);

    for (i=0; i <= S1LENGTH+SIZE-2; i++) {
        /* Check that each character is correct */
        if (test1[i] != s1buf[i]) {
            printf("Error in wcsncat\n");
            exit(EXIT_FAILURE);
        }
    }

    printf("Concatenated string: <%S>\n", s1buf);
}

Running the example produces the following result:

Concatenated string: <abcmnexyz or>