wcsncat() — Append to wide-character string

Standards

Standards / Extensions	C or C++	Dependencies
ISO C Amendment XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#include <wchar.h>

wchar_t *wcsncat(wchar_t * __restrict__string1, 
                 const wchar_t * __restrict__string2, size_t count);

General description

Appends up to count wide characters from string2 to the end of string1 and appends a NULL wide character to the result. The wcsncat() function operates on NULL-terminated wide-character strings. The string arguments to this function must contain a NULL wide character marking the end of the string.

The behavior of this wide-character function is affected by the LC_CTYPE category of the current locale. If you change the category, undefined results can occur.

Returned value

wcsncat() returns string1.

Example

CELEBW13

⁄* CELEBW13                                      

   This example demonstrates the difference between &wcscat. and                
   &wcsncat..                                                                   
   &wcscat. appends the entire second string to the first                       
   whereas &wcsncat. appends only the specified number of                       
   characters in the second string to the first.                                
                                                                                
 *⁄                                                                             
#include <stdio.h>                                                              
#include <wchar.h>                                                              
#include <string.h>                                                             
                                                                                
#define SIZE 40                                                                 
                                                                                
int main(void)                                                                  
{                                                                               
  wchar_t buffer1[SIZE] = L"computer";                                          
  wchar_t * ptr;                                                                
                                                                                
  ⁄* Call wcscat with buffer1 and " program" *⁄                                 
                                                                                
  ptr = wcscat( buffer1, L" program" );                                         
  printf( "wcscat : buffer1 = \"%ls\"\n", buffer1 );                            
                                                                                
  ⁄* Reset buffer1 to contain just the string "computer" again *⁄               
                                                                                
  memset( buffer1, L'\0', sizeof( buffer1 ));                                   
  ptr = wcscpy( buffer1, L"computer" );                                         
                                                                                
  ⁄* Call wcsncat with buffer1 and " program" *⁄                                
  ptr = wcsncat( buffer1, L" program", 3 );                                     
  printf( "wcsncat: buffer1 = \"%ls\"\n", buffer1 );                            
}

Output:

wcscat : buffer1 = "computer program"
wcsncat: buffer1 = "computer pr"