NAME

       uconvert  -  High  level  string  encoding  conversion  wrapper.  Allegro game programming
       library.

SYNOPSIS

       #include <allegro.h>

       char *uconvert(const char *s, int type, char *buf, int newtype, int size);

DESCRIPTION

       Higher level function  running  on  top  of  do_uconvert().  This  function  converts  the
       specified  string  `s'  from  `type'  to  `newtype', storing at most `size' bytes into the
       output `buf' (including the terminating null character), but it checks  before  doing  the
       conversion,  and  doesn't  bother  if the string formats are already the same (either both
       types are equal, or one is ASCII, the other is UTF-8, and the string contains  only  7-bit
       ASCII characters).

       As  a  convenience,  if  `buf'  is NULL it will convert the string into an internal static
       buffer and the `size' parameter will be ignored. You should be wary of using this feature,
       though,  because  that buffer will be overwritten the next time this routine is called, so
       don't expect the data to persist across any other library calls.  The  static  buffer  may
       hold  less  than  1024  characters,  so you won't be able to convert large chunks of text.
       Example:

          char *p = uconvert(input_string, U_CURRENT, buffer, U_ASCII, 256);

RETURN VALUE

       Returns a pointer to `buf' (or the static buffer if you used NULL)  if  a  conversion  was
       performed.  Otherwise returns a copy of `s'. In any cases, you should use the return value
       rather than assuming that the string will always be moved to `buf'.

SEE ALSO

       set_uformat(3alleg4), need_uconvert(3alleg4), uconvert(3alleg4),  uconvert_ascii(3alleg4),
       uconvert_toascii(3alleg4), do_uconvert(3alleg4)