strxfrm()

transform one string into another, to a given length

Synopsis:

#include <string.h>

size_t strxfrm( char *dst,
                const char *src,
                size_t n );

Description:

The strxfrm() function transforms, for no more than n characters, the string pointed to by src to the buffer pointed to by dst. The transformation uses the collating sequence selected by the setlocale() function so that two transformed strings will compare identically (using the strncmp() function) to a comparison of the original two strings using the strcoll() function.

The function is equivalent to the strncpy() function (except there is no padding of the dst argument with null characters when the argument src is shorter than n characters) when the collating sequence is selected from the "C" locale.

Returns:

The length of the transformed string. If this length is more than n, the contents of the array pointed to by dst are indeterminate.

Examples:

#include <stdio.h>
#include <string.h>
#include <locale.h>

char src[] = { "A sample STRING" };
char dst[20];

void main()
  {
    size_t len;

    setlocale( LC_ALL, "C" );
    printf( "%s\n", src );
    len = strxfrm( dst, src, 20 );
    printf( "%s (%u)\n", dst, len );
  }

produces the output:

A sample STRING
A sample STRING (15)

Classification:

ANSI

See also:

setlocale(), strcoll()