Museum

     COLLATION(S)              UNIX System V              COLLATION(S)



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

     INTERNATIONAL VERSION
     Syntax
          strxfrm(to, from, maxsize)
          char *to, *from;
          int maxsize;

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

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

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

     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 contained 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 '337'
               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  collates  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), nl_strcmp(S), string(S)


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

          Example 1:

          This is an example of the strxfrm routine:

                   char *to1, *to2;
                   int ret;

                   strxfrm(to1, "Stra337e", maxsize);
                   strxfrm(to2, "Strasse", maxsize);
                   ret= strcmp(to1, to2)

          ret will contain 0 as "Stra337e" and  "Strasse"  collate  as
          equal.

          Example 2:

          This is an example of the strcoll routine:

                   int ret;

                   ret = strcoll("Stra337e", "Strasse");

          ret will contain 0 as "Stra337e" and  "Strasse"  collate  as
          equal.

          Example 3:

          This is an example of the strnxfrm routine:

                   char *to;

                   strnxfrm("Stra337e", maxsize , 6);

          This will  transform  only  the  "Stra337"  portion  of  the
          string, as 337 counts as 2 characters.

          Example 4:

          This is an example of the strncoll routine:
                   strncoll("Stra337e", "Bahn", 6);

          This will compare only the "Stra337" portion of the  string,
          as 337 counts as two characters.

     Standards Conformance
          strcoll and strxfrm are conformant with:
          ANSI X3.159-198X C Language Draft Standard, May 13, 1988.

                                                (printed 6/20/89)