wcsncpy() — Copy 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 *wcsncpy(wchar_t * __restrict__string1, 
                 const wchar_t * __restrict__string2, size_t count);

General description

Copies up to count wide characters from string2 to string1. If string2 is shorter than count characters, string1 is padded out to count characters with NULL wide characters. The wcsncpy() 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

wcsncpy() returns string1.

Example

CELEBW15

⁄* CELEBW15                                      

   This example demonstrates the difference between &wcscpy. and &wcsncpy..     
                                                                                
 *⁄                                                                             
#include <stdio.h>                                                              
#include <wchar.h>                                                              
                                                                                
#define SIZE    40                                                              
                                                                                
int main(void)                                                                  
{                                                                               
  wchar_t source[ SIZE ] = L"123456789";                                        
  wchar_t source1[ SIZE ] = L"123456789";                                       
  wchar_t destination[ SIZE ] = L"abcdefg";                                     
  wchar_t destination1[ SIZE ] = L"abcdefg";                                    
  wchar_t * return_string;                                                      
  int    index = 5;                                                             
                                                                                
  ⁄* This is how wcscpy works *⁄                                                
  printf( "destination is originally = '%ls'\n", destination );                 
  return_string = wcscpy( destination, source );                                
  printf( "After wcscpy, destination becomes '%ls'\n\n", destination );         
                                                                                
  ⁄* This is how wcsncpy works *⁄                                               
  printf( "destination1 is originally = '%ls'\n", destination1 );               
  return_string = wcsncpy( destination1, source1, index );                      
  printf( "After wcsncpy, destination1 becomes '%ls'\n", destination1 );        
}

Output:

destination is originally = 'abcdefg'
After wcscpy, destination becomes '123456789'

destination1 is originally = 'abcdefg'
After wcsncpy, destination1 becomes '12345fg'