wcsncmp() — Compare Wide-Character Strings

Format

#include <wchar.h>
int wcsncmp(const wchar_t *string1, const wchar_t *string2, size_t count);

Language Level

XPG4

Threadsafe

Yes

Wide Character Function

See Wide Characters for more information.

Description

The wcsncmp() function compares up to count wide characters in string1 to string2.

The wcsncmp() function operates on null-ended wide-character strings; string arguments to this function should contain a wchar_t null character marking the end of the string.

Return Value

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

Table 1. Return values of wcsncmp()
Value Meaning
Less than 0 string1 less than string2
0 string1 identical to string2
Greater than 0 string1 greater than string2

Example

This example demonstrates the difference between the wcscmp() function, which compares the entire strings, and the wcsncmp() function, which compares only a specified number of wide characters in the strings. 
#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 should be similar to: ******************
 
Comparison of each character
  wcscmp: "abcdefg" is less than "abcfg"
 
Comparison of only the first 3 characters
  wcsncmp: "abcdefg" is identical to "abcfg"
*/

Related Information