plucky (3) uconvert.3alleg4.gz

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)