Index for Section 3

Alphabetical listing for W

Bottom of page

wcscoll(3)
NAME
  wcscoll - Compare wide-character strings by using collation information

SYNOPSIS
  #include <wchar.h>

  int wcscoll(
	  const wchar_t *wcs1,
	  const wchar_t *wcs2 );

LIBRARY
  Standard C Library (libc)

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  wcscoll(): XSH5.0

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  wcs1
      Points to a wide-character string.

  wcs2
      Points to a wide-character string.

DESCRIPTION
  The wcscoll() function compares the two wide-character strings pointed to
  by the wcs1 and wcs2 parameters based on the collation values specified by
  the LC_COLLATE category of the program's current locale.

  The wcscoll() function may be unsuccessful if the wide-character strings
  specified by the wcs1 or wcs2 parameters contain characters outside the
  domain of the current collating sequence.

NOTES
  The wcscoll() function differs from the wcscmp() function in that the
  former compares wide characters based on locale-dependent collating order,
  while the latter compares wide characters based on machine collating order.
  The wcscoll() function is more expensive in terms of time than the wcscmp()
  function because of the overhead of obtaining the collation values from the
  current locale.

  If an application does multiple comparisons based on the current locale's
  collation values and uses the same set of text strings, the wcsxfrm()
  transformation function in conjunction with the wcscmp() function may be
  more efficient than the wcscoll() collation function. This is because the
  string is transformed based on the locale tables only once. However, the
  transformation function must convert all characters in the string for each
  level of a multilevel collation. In comparison, the collation function
  stops comparing characters at the first inequality. These tradeoffs make
  the most efficient method for a specific application dependent on the
  number of repeated comparisons of strings within the set, the number of
  collation levels for the current locale, and the values of the strings
  within the set.

RETURN VALUES
  On successful completion, the wcscoll() function returns an integer whose
  value is greater than 0 (zero) if wcs1 is greater than wcs2, returns 0
  (zero) if the strings are equivalent, and returns an integer whose value is
  less than 0 (zero) if wcs1 is less than wcs2. The sign of a nonzero return
  value is determined by the sign of the difference between the collation
  weights of the first pair of wide-character codes that differ in the
  objects being compared.

  The wcscoll() function indicates error conditions by setting errno;
  however, there is no return value to indicate an error. To check for
  errors, errno should be set to 0 (zero), then checked upon return from the
  wcscoll() function. If errno has a nonzero value, an error occurred.

ERRORS
  If the following condition occurs, the wcscoll() function sets errno to the
  corresponding value:

  [EINVAL]
      The wide-character string pointed to by the wcs1 or wcs2 string
      contained characters outside of the domain of the collating sequence.

SEE ALSO
  Functions: strcoll(3), wcscmp(3), wcsxfrm(3)

  Standards: standards(5)

Index for Section 3

Alphabetical listing for W

Top of page