wcsncmp() — Compare wide-character strings

Standards

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

Format

#include <wchar.h>

int wcsncmp(const wchar_t *string1, const wchar_t *string2, size_t count);

General description

Compares up to count wide characters in string1 to string2. The wcsncmp() 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

wcsncmp() returns a value indicating the relationship between the two strings, as follows:

Value: Meaning
< 0: string pointed to by string1 less than the string pointed to by string2
= 0: string pointed to by string1 identical to string pointed to by string2
> 0: string pointed to by string1 greater than string pointed to by string2

Example

CELEBW14

⁄* CELEBW14                                      

   This example demonstrates the difference between &wcscmp.                    
   and &wcsncmp..                                                               
                                                                                
 *⁄                                                                             
#include <stdio.h>                                                              
#include <wchar.h>                                                              
                                                                                
#define SIZE 10                                                                 
                                                                                
int main(void)                                                                  
{                                                                               
  int  result;                                                                  
  int  index = 3;                                                               
  wchar_t buffer1[SIZE] = L"abcdefg";                                           
  wchar_t buffer2[SIZE] = L"abcfg";                                             
  void print_result( int, wchar_t *, wchar_t * );                               
                                                                                
  result = wcscmp( buffer1, buffer2 );                                          
  printf( "Comparison of each character\n" );                                   
  printf( "  wcscmp: " );                                                       
  print_result( result, buffer1, buffer2 );                                     
                                                                                
  result = wcsncmp( buffer1, buffer2, index);                                   
  printf( "\nComparison of only the first %i characters\n", index );            
  printf( "  wcsncmp: " );                                                      
  print_result( result, buffer1, buffer2 );                                     
}                                                                               
                                                                                
void print_result( int res, wchar_t * p_buffer1, wchar_t * p_buffer2 )          
{                                                                               
  if ( res == 0 )                                                               
    printf( "\"%ls\" is identical to \"%ls\"\n", p_buffer1, p_buffer2);         
  else if ( res < 0 )                                                           
    printf( "\"%ls\" is less than \"%ls\"\n", p_buffer1, p_buffer2 );           
  else                                                                          
    printf( "\"%ls\" is greater than \"%ls\"\n", p_buffer1, p_buffer2 );        
}

Output:

Comparison of each character
  wcscmp: "abcdefg" is less than "abcfg"

Comparison of only the first 3 characters
  wcsncmp: "abcdefg" is identical to "abcfg"