strcoll(S)                     6 January 1993                     strcoll(S)


 Name

    strcoll, strncoll, strnxfrm, strxfrm - handles collation of strings

 Syntax


    cc  . . .  -lintl


    int strcoll (str1, str2)
    char *str1, *str2;

    int strncoll (str1, str2, n)
    char *str1, *str2;
    int n;

    int strnxfrm (to, from, maxsize, n)
    char *to, *from;
    int maxsize, n;

    int strxfrm (to, from, maxsize)
    char *to, *from;
    int maxsize;


 Description

    These functions operate on null-terminated strings.

    The strxfrm routine transforms the string from according to the collation
    environment of the current locale. The result is placed in the character
    array to.  The maximum size of the resulting string is the value con-
    tained in the maxsize variable.  The result can then be compared with
    another transformed string to establish the collating order of the two
    original strings. The strnxfrm routine transforms at most n characters in
    the from string, where n is defined after the following collation rules
    have been applied:

    +    1->2 character transformations : for example, the german '<ss>'
         counts as two characters.

    +    2->1 character transformations : for example, the spanish 'ch'
         counts as a single character.

    +    1->1 character transformations : for example, 'a', 'b', etc. count
         as single characters.

    +    1->0 character transformations : for example, the hyphen, '-', is
         not counted.

    Both functions return the size of the array required to hold the
    transformed string. If the return value is greater than maxsize then the
    contents of to is undefined.

    The strcoll function is used to collate the two strings str1 and str2
    according to the collation environment of the current locale. The
    returned value is equal to, less than or greater than 0, according to
    whether str1 is equal to, less than or greater than str2.  strncoll col-
    lates the two strings until the nth character in str1 is reached.  The
    nth character is defined in the same way as strnxfrm.

 See also

    coltbl(M), nlstrcmp(S), string(S)

 Standards conformance

    strcoll and strxfrm are conformant with:
    ANSI X3.159-1989 Programming Language -- C.

 Examples

    It is assumed that the value of maxsize is large enough to contain the
    transformed string in the strxfrm and the strnxfrm examples.

    _________________________________________________________________________
       NOTE  Some non-English characters, on this manual page, are not
       representable on some terminals.  See the corresponding printed
       manual page in the Programmer's Reference Manual Volume 2.
    _________________________________________________________________________


    Example 1:

    This is an example of the strxfrm routine:

       char *to1, *to2;
       int ret;

       strxfrm(to1, "Stra<ss>e", maxsize);
       strxfrm(to2, "Strasse", maxsize);
       ret= strcmp(to1, to2)

    ret contains 0 becaues "Stra<ss>e" and "Strasse" collate as equal.

    Example 2:
    This is an example of the strcoll routine:

       int ret;

       ret = strcoll("Stra<ss>e", "Strasse");

    ret contains 0 because "Stra<ss>e" and "Strasse" collate as equal.

    Example 3:
    This is an example of the strnxfrm routine:

       char *to;

       strnxfrm(to, "Stra<ss>e", maxsize, 6);

    This transforms only the "Stra<ss>" portion of the string, as <ss> counts
    as two characters.

    Example 4:
    This is an example of the strncoll routine:

       strncoll("Stra<ss>e", "Bahn", 6);

    This compares only the "Stra<ss>" portion of the string, as <ss> counts
    as two characters.