01 Rutinas Unicode

Allegro puede manipular y mostrar texto usando cualquier carácter en el rango que va de 0 a 2^32-1 (aunque por ahora grabber sólo puede crear fuentes usando carácteres hasta 2^16-1). Puede escoger entre varios tipos de formatos de codificación de texto, los cuales controlan la forma en la que las cadenas son almacenadas y cómo Allegro interpreta las que usted le pase. Esta configuración afecta a todos los aspectos del sistema: cada vez que observe una función que devuelve un puntero a carácter (char *) o que toma un puntero a carácter como argumento, el texto utilizará el formato que se le haya indicado a Allegro.

Por defecto, Allegro usa texto codificado en el formato UTF-8 (U_UTF8). Este es un formato de anchura variable donde los carácteres pueden tener cualquier tamaño de 1 a 6 bytes. Lo bueno de este formato es que los carácteres de 0 a 127 pueden ser almacenados directamente, o lo que es igual, significa que es compatible con códigos ASCII de 7 bits ("Hola, Mundo!" es exactamente la misma cadena en ASCII que en UTF-8). Cualquier carácter por encima del 128 como vocales acentuadas, el símbolo monetario inglés o carácteres árabes y chinos serán codificados como una secuencia de dos o más bytes con un valor en el rango 128-255. Esto permite que al mostrar la cadena no se obtengan carácteres extraños en ASCII que en realidad forman parte de la codificación de un carácter con diferente valor, lo que hace realmente fácil manipular cadenas UTF-8.

Existen algunos editores de texto que entienden ficheros UTF-8, pero alternativamente, puede escribir sus cadenas en ASCII plano o en formato Unicode de 16 bit y luego utilizar el programa textconv (suministrado con Allegro) para convertir el texto a UTF-8.

Si prefiere usar otros formatos de texto, Allegro permite la utilización de formatos ASCII de 8 bits (U_ASCII) o Unicode de 16 bits (U_UNICODE). Además puede programar sus propias funciones para manejar otros formatos de texto con Allegro (sería sencillo añadir soporte para el formato UCS-4 de 32 bits, o el formato GB-code chino).

También existe soporte limitado para páginas de códigos alternativas de 8 bits a través del modo U_ASCII_CP. Lo malo de este modo es que es muy lento y no debería utilizarse para aplicaciones serias. Sin embargo, puede utilizarse para convertir texto fácilmente entre diferentes páginas de códigos. Por defecto, el modo U_ASCII_CP es activado para convertir texto al formato ASCII de 7 bits, convirtiendo las vocales acentuadas en sus equivalente (por ejemplo, allegro_message() utiliza este modo para mostrar los mensajes en una consola DOS). Si necesita trabajar con otras páginas de códigos, puede hacerlo pasando un mapeado de carácteres a la función set_ucodepage().

Tenga en cuenta que puede usar las rutinas Unicode antes de llamar install_allegro() o allegro_init(). Si quiere trabajar en un formato de texto distinto al UTF-8, lo mejor es que lo seleccione con set_uformat() antes de llamar estas funciones.


void set_uformat(int type);
Establece el formato de codificación de texto a utilizar. Esta operación afectará a todos las funciónes de Allegro que devuelvan un puntero a carácter (char *) o acepten un puntero a carácter como parámetro. El parámetro type debe ser uno de los siguientes:

      U_ASCII     - carácteres ASCII de 8 bits de tamaño fijo
      U_ASCII_CP  - página de códigos alternativa de 8 bits (ver
                    set_ucodepage())
      U_UNICODE   - carácteres Unicode de 16 bits de tamaño fijo
      U_UTF8      - carácteres Unicode UTF-8 de tamaño variable
Aunque es posible cambiar el formato de texto en cualquier momento, no es una práctica demasiado recomendable. Muchas cadenas (entre ellas los nombres de los drivers de hardware y algunas traducciones) son inicializadas en la llamada a allegro_init(), por lo tanto, si se cambia el formato de texto tras dicha llamada, las cadenas estarán en un formato diferente al seleccionado y el sistema no funcionará de forma apropiada. Como normal general, sólo debería llamarse a set_uformat() una vez, antes de llamar a allegro_init(), y utilizar el formato de texto seleccionado durante toda la ejecución de su programa.
Relacionado con: get_uformat, register_uformat, set_ucodepage, set_uformat, uconvert, ugetat, usetat, uinsert, uremove, allegro_init, ustrsize, ugetc, ugetx, usetc, uwidth, ucwidth, uisok, uoffset.
int get_uformat(void);
Devuelve el formato de codificación de texto actualmente seleccionado.
Relacionado con: set_uformat.
void register_uformat(int type, int (*u_getc)(const char *s), int (*u_getx)(char **s), int (*u_setc)(char *s, int c), int (*u_width)(const char *s), int (*u_cwidth)(int c), int (*u_isok)(int c));
Instala un conjunto de funciones para el manejo de un nuevo formato de codificación de carácteres. El parámetro type identifica el nuevo formato, que debería ser una cadena de 4 carácteres como las producidas por la macro AL_ID(). Esta cadena será la que se pase posteriormente a funciones como set_uformat() y uconvert(). Los punteros a funciones pasados como parámetros, son manejadores que implementan el acceso a los carácteres de una cadena formateada con la nueva codificación (vea más abajo para más detalles).
Relacionado con: set_uformat, uconvert, ugetc, ugetx, usetc, uwidth, ucwidth, uisok.
void set_ucodepage(const unsigned short *table, const unsigned short *extras);
Cuando se selecciona el modo U_ASCII_CP, los carácteres de 8 bits son convertidos a sus equivalentes en Unicode a través de un conjunto de tablas. Se puede usar esta función para especificar un conjunto de tablas personalizadas que permitan la utilización de páginas de códigos de 8 bits alternativas. El parámetro table apunta a un array de 256 enteros short que contienen el valor Unicode para cada carácter en la página de códigos. El parámetro extras, si no es NULL, apunta a una lista de pares de valores que es utilizada para realizar la conversión inversa, es decir, reducir los valores Unicode a la representación correcta dentro de la nueva página de codigos. Cada par de valores consiste en un valor Unicode seguido por la forma de representación correspondiente dentro de la página de códigos. La tabla debe finalizar con el valor cero en Unicode. Esta tabla permite que varios carácteres Unicode puedan representarse mediante un solo valor en la página de codigos (por ejemplo para reducir vocales acentuadas a ASCII de 7 bits).
Relacionado con: set_uformat.
int need_uconvert(const char *s, int type, int newtype);
Dado un puntero a una cadena, el tipo de la cadena y el tipo al que se desea convertir, esta función indica si dicha conversión es necesaria. La conversión no es necesaria si type y newtype son el mismo tipo o son tipos equivalentes (por ejemplo ASCII y UTF-8 y la cadena contiene carácteres menores que 128). Como valor para uno de los parámetros type, se puede pasar U_CURRENT que representa el tipo actualmente seleccionado.
Relacionado con: set_uformat, get_uformat, do_uconvert, uconvert.
int uconvert_size(const char *s, int type, int newtype);
Devuelve el número de bytes que serán necesarios para almacenar la cadena especificada tras una conversión al nuevo tipo, incluyendo el carácter terminador nulo. Los parámetros type pueden usar el valor U_CURRENT para indicar el tipo actualmente seleccionado.
Relacionado con: need_uconvert, do_uconvert.
void do_uconvert(const char *s, int type, char *buf, int newtype, int size);
Convierte la cadena especificada del tipo type al tipo newtype, guardando como mucho size bytes en el buffer buf. Los parámetros type pueden utilizar el valor U_CURRENT para indicar el tipo actualmente seleccionado.
Relacionado con: uconvert.
char *uconvert(const char *s, int type, char *buf, int newtype, int size);
Esta es una función de alto nivel que sirve como ayuda para ejecutar do_uconvert(). Al igual que do_uconvert(), convierta la cadena especificada del tipo type al tipo newtype, guardando como mucho size bytes en el buffer buf. La ventaja que obtenemos a usar uconvert() es que comprueba los tipos antes de realizar la conversión, para asegurarse de que son tipos diferentes, no realizando conversión alguna si los tipos son iguales o equivalentes. Si la conversión fue realizada, devuelve un puntero a buf, en caso contrario, devuelve una copia de la cadena a convertir (s). Por lo tanto, debe usar el valor devuelto en lugar de asumir que la cadena ha sido movida a buf. Si buf es NULL, la cadena será convertida en un buffer estático interno. Sin embargo, debería tener cuidado al usar este comportamiento, ya que el buffer será sobreescrito cada vez que la rutina sea invocada, por lo que no espere que los datos persistan tras haber hecho llamadas a otras funciones de la biblioteca.
Relacionado con: set_uformat, need_uconvert, uconvert, uconvert_ascii, uconvert_toascii.
char *uconvert_ascii(const char *s, char buf[]);
Macro auxiliar para convertir cadenas desde ASCII al formato actual de codificación. Se expande a uconvert(s, U_ASCII, buf, U_CURRENT, sizeof(buf)).
Relacionado con: uconvert.
char *uconvert_toascii(const char *s, char buf[]);
Macro auxiliar para convertir cadenas desde el formato actual de codificación a ASCII. Se expande a uconvert(s, U_CURRENT, buf, U_ASCII, sizeof(buf)).
Relacionado con: uconvert.
extern char empty_string[];
No se puede fiar de que "" sea una cadena vacía válida en todos los formatos de codificación. Este búffer global contiene un número de ceros consecutivos, así que siempre será una cadena vacía válida, sin tener importancia si el programa se está ejecutando en modo ASCII, Unicode o UTF-8.


int ugetc(const char *s);
Función auxiliar de bajo nivel para leer datos de texto en Unicode. Dado un puntero a una cadena en el formato de codificación actual devuelve el siguiente caracter de la cadena.

Relacionado con: ugetx, usetc, uwidth, ucwidth, uisok.
int ugetx(char **s);
int ugetxc(const char **s);
Función auxiliar de bajo nivel para leer datos de texto en Unicode. Dada la dirección de un puntero a un string en el formato de codificación actual devuelve el siguiente caracter de la cadena y avanza el puntero al siguiente caracter.

ugetxc es para trabajar con datos char constantes puntero a puntero.

Relacionado con: ugetc, usetc, uwidth, ucwidth, uisok.
int usetc(char *s, int c);
Función auxiliar de bajo nivel para escribir datos de texto en Unicode. Escribe el caracter especificado en la dirección dada usando el formato de codificación actual y devuelve el número de bytes escritos.
Relacionado con: ugetc, ugetx, uwidth, ucwidth, uisok.
int uwidth(const char *s);
Función auxiliar de bajo nivel para comprobar datos de texto en Unicode. Devuelve el número de bytes ocupados por el primer caracter de la cadena especificada en el formato de codificación actual.
Relacionado con: uwidth_max, ugetc, ugetx, usetc, ucwidth, uisok.
int ucwidth(int c);
Función auxiliar de bajo nivel para comprobar datos de texto en Unicode. Devuelve el número de bytes que ocuparía el caracter especificado en caso de codificarse en el formato actual.
Relacionado con: uwidth_max, ugetc, ugetx, usetc, uwidth, uisok.
int uisok(int c);
Función auxiliar de bajo nivel para comprobar datos de texto en Unicode. Comprueba que el valor especificado puede ser codificado correctamente en en el formato actual.
Relacionado con: ugetc, ugetx, usetc, uwidth, ucwidth.
int uoffset(const char *s, int index);
Devuelve el desplazamiento en bytes desde el comienzo de la cadena hasta el caracter correspondiente al índice especificado. Si el índice es negativo, cuenta hacía atrás desde el final de la cadena, así que un índice de -1 devolverá un desplazamiento al último caracter.
Relacionado con: ugetat, usetat, uinsert, uremove.
int ugetat(const char *s, int index);
Devuelve el valor del caracter de la cadena correspondiente al índice especificado. Un parámetro indice igual a 0 devolverá el primer caracter de la cadena. Si el índice es negativo, cuenta hacia atrás desde el final de la cadena. Así pues un índice de -1 devolverá el ultimo caracter de la cadena.
Relacionado con: uoffset, usetat, uinsert, uremove.
int usetat(char *s, int index, int c);
Reemplaza el caracter del string con el índice especificado por el valor c, haciendo los ajustes necesarios debido a la anchura de la variable (ej: si c se codifica con una anchura diferente que el valor que había antes en esa posición). Devuelve el número de bytes que ha sido desplazada la parte derecha de la cadena. Si el índice es negativo cuenta hacia atrás desde el final de la cadena.
Relacionado con: uoffset, ugetat, uinsert, uremove.
int uinsert(char *s, int index, int c);
Inserta el caracter c en la posición de la cadena especificada por index, desplazando el resto de los datos para hacer sitio. Devuelve el número de bytes que ha desplazado la parte derecha. Si el índice es negativo cuenta hacia atras desde el final de la cadena.
Relacionado con: uoffset, ugetat, usetat, uremove.
int uremove(char *s, int index);
Borra el caracter que hay en la posición index de la cadena, desplazando el resto de los datos para llenar la posición vacía. Devuelve el número de bytes que se ha tenido que desplazar la parte derecha de la cadena, si index es negativo empieza a contar desde el final de la cadena
Relacionado con: uoffset, ugetat, usetat, uinsert.
int ustrsize(const char *s);
Devuelve el tamaño de la cadena especificada en bytes, sin incluir el caracter nulo finalizador de cadena.
Relacionado con: ustrsizez.
int ustrsizez(const char *s);
Devuelve el tamaño de la cadena especificada en bytes, incluyendo el caracter nulo finalizador de cadena.
Relacionado con: ustrsize.
int uwidth_max(int type);
Rutinas ayudantes de bajo nivel para trabajar con texto Unicode. Devuelven el mayor número de bytes que un carácter puede ocupar en el formato de codificación especificado. Pase U_CURRENT para indicar el formato de codificación actual.
Relacionado con: uwidth, ucwidth.
int utolower(int c);
Esta función devuelve c, convirtiéndola a minúsculas si estaba en mayúsculas.
Relacionado con: utoupper, ugetc, ugetx, usetc, uwidth, ucwidth, uisok.
int utoupper(int c);
Esta función devuelve c, convirtiéndola a mayúsculas si estaba en minúsculas.
Relacionado con: utolower, ugetc, ugetx, usetc, uwidth, ucwidth, uisok.
int uisspace(int c);
Devuelve distinto de cero si c es carácter de espaciado, es decir, un retorno de carro, una nueva línea, página, un tabulador, un tabulador vertical o un espacio.
Relacionado con: uisdigit, ugetc, usetc, uwidth, ucwidth, uisok.
int uisdigit(int c);
Devuelve distinto de cero si c es un dígito.
Relacionado con: uisspace, ugetc, usetc, uwidth, ucwidth, uisok.
char *ustrdup(const char *src)
Esta función copia la cadena src terminada en NULL en una nueva área de memoria reservada. La memoria devuelta por esta llamada debe ser liberada por el usuario. Devuelve NULL si no puede reservar espacio para la cadena duplicada.
Relacionado con: _ustrdup, uconvert, ustrsize, ustrsizez.
char *_ustrdup(const char *src, void* (*malloc_func) (size_t))
Hace lo mismo que ustrdup(), pero permite especificar al usuario su propia rutina para reservar memoria.
Relacionado con: ustrdup, uconvert, ustrsize, ustrsizez.
char *ustrcpy(char *dest, const char *src);
Esta función copia src en dest (incluyendo el terminador de cadena NULL). El valor de retorno es el valor de dest.
Relacionado con: uconvert, ustrsize, ustrsizez, ustrncpy.
char *ustrzcpy(char *dest, int size, const char *src);
Esta función copia src en dest (incluyendo el terminador de cadena NULL), cuya longitud en bytes es especificada por size y que está garantizado que termine en carácter NULL. El valor de retoron es el valor de dest.
Relacionado con: uconvert, ustrcpy, ustrzncpy.
char *ustrcat(char *dest, const char *src);
Esta función concatena src al final de dest. El valor de retorno es el valor de dest.
Relacionado con: uconvert, ustrzcat, ustrncat.
char *ustrzcat(char *dest, int size, const char *src);
Esta función concatena src al final de dest, cuya longitud en bytes es especificada por size y que está garantizado que termine en carácter NULL. El valor de retorno es el valor de dest.
Relacionado con: uconvert, ustrcat, ustrzncat.
int ustrlen(const char *s);
Esta función devuelve el número de carácteres de s. Tenga en cuenta que esto no tiene que ser igual que el tamaño de la cadena en bytes.
Relacionado con: uconvert, ustrsize, ustrsizez.
int ustrcmp(const char *s1, const char *s2);
Esta función compara s1 con s2. Devuelve cero si las cadenas son iguales, un número positivo si s1 va detrás de s2 en la secuencia ASCII apropiada, o negativo en caso contrario.
Relacionado con: uconvert, ustrsize, ustrsizez, ustrncmp, ustricmp.
char *ustrncpy(char *dest, const char *src, int n);
Esta función es como ustrcpy() excepto que no copiará más de n carácteres de src a dest. Si src es menor en longitud que n carácteres, se añadirán carácteres NULL en dest hasta rellenar los n carácteres especificados. Note que si src es mayor que n carácteres, dest no terminará en NULL. El valor de retorno es el valor de dest.
Relacionado con: uconvert, ustrcpy, ustrzncpy.
char *ustrzncpy(char *dest, int size, const char *src, int n);
Esta función es como ustrzcpy() excepto que no copiará más de n carácteres de src a dest. Si src es menor en longitud que n carácteres, se añadirán carácteres NULL en dest hasta rellenar los n carácteres especificados. Note que está garantizado que dest acabe en carácter NULL. El valor de retorno es el valor de dest.
Relacionado con: uconvert, ustrzcpy, ustrncpy.
char *ustrncat(char *dest, const char *src, int n);
Esta función es como `strcat' con la excepción de que no se añadirán más de n bytes de src al final de dest. Si el carácter terminador NULL es encontrado en src antes de haber escrito n carácteres, el carácter NULL será copiado, pero no se escribirán más carácteres. Si n carácteres son copiados antes de encontrar el carácter NULL, la función añadirá automáticamente el carácter NULL a dest, por lo que se escribirán n+1 carácteres. El valor de retorno es dest.
Relacionado con: uconvert, ustrcat, ustrzncat.
char *ustrzncat(char *dest, int size, const char *src, int n);
Esta función es como ustrszcat() con la excepción de que no se añadirán más de n carácteres de src al final de dest. Si el carácter terminador NULL es encontrado en src antes de haber escrito n carácteres, el carácter NULL será copiado, pero no se escribirán más carácteres. Note que está garantizado que dest acabe en carácter NULL. El valor de retorno es el valor de dest.
Relacionado con: uconvert, ustrzcat, ustrncat.
int ustrncmp(const char *s1, const char *s2, int n);
Esta función compara hasta n carácteres de s1 con s2. Devuelve cero si las cadenas son iguales, un número positivo si s1 va detrás de s2 en la secuencia ASCII apropiada, o negativo en caso contrario.
Relacionado con: uconvert, ustrsize, ustrsizez, ustrcmp, ustricmp.
int ustricmp(const char *s1, const char *s2);
Esta función compara s1 con s2, ignorando las mayúsculas.
Relacionado con: uconvert, ustrsize, ustrsizez, ustrcmp, ustrncmp.
char *ustrlwr(char *s);
Esta función sustituye todas las letras mayúsculas de s con minúsculas.
Relacionado con: uconvert, utolower, ustrupr.
char *ustrupr(char *s);
Esta función sustituye todas las letras minúsculas de s con mayúscylas.
Relacionado con: uconvert, utolower, ustrlwr.
char *ustrchr(const char *s, int c);
Esta función devuelve un puntero a la primera ocurrencia de c en s, o NULL si s no contiene c. Tenga en cuenta que si c es NULL, esta función devolverá un puntero al final de la cadena.
Relacionado con: uconvert, ustrrchr, ustrstr, ustrpbrk, ustrtok.
char *ustrrchr(const char *s, int c);
Esta función devuelve un puntero a la última ocurrencia de c en s, o NULL si s no contiene c.
Relacionado con: uconvert, ustrchr, ustrstr, ustrpbrk, ustrtok.
char *ustrstr(const char *s1, const char *s2);
Esta función busca la primera ocurrencia de s2 en s1. Devuelve un puntero dentro de s1, o NULL si s2 no fue encontrada.
Relacionado con: uconvert, ustrchr, ustrrchr, ustrpbrk, ustrtok.
char *ustrpbrk(const char *s, const char *set);
Esta función encuentra el primer carácter de s que esté contenido en set. Devuelve un puntero a la primera ocurrencia, o NULL si no se encontró nada.
Relacionado con: uconvert, ustrchr, ustrrchr, ustrstr, ustrtok.
char *ustrtok(char *s, const char *set);
Esta función recupera palabras de s que están delimitadas por carácteres de set. Para iniciar la búsqueda, pase la cadena que quiere analizar como s. Para el resto de las palabras, pase NULL en su lugar. Devuelve un puntero a la palabra, o NULL si no se encontró nada. Aviso: dado que ustrtok altera la cadena que está analizando, debe copiar siempre su cadena a un buffer temporal antes de analizarla. Además, esta función no es reentrante (ej: no puede analizar dos cadenas simultáneamente).
Relacionado con: uconvert, ustrchr, ustrrchr, ustrstr, ustrpbrk, ustrtok_r.
char *ustrtok_r(char *s, const char *set, char **last);
Versión reentrante de ustrtok. El último parámetro es usado para almacenar por dónde iba el procesado de la cadena y debe ser un puntero a una variable char * reservada por el usuario que no debe ser modificada mientras se procesa la misma cadena.
Relacionado con: ustrtok.
double uatof(const char *s);
Convierte tanto como sea posible de la cadena a un número equivalente en coma flotante de doble precisión. Esta función es casi como `ustrtod(s, NULL)'. Devuelve un valor equivalente, o cero si la cadena no representa un número.
Relacionado con: uconvert, ustrtol, ustrtod.
long ustrtol(const char *s, char **endp, int base);
Esta función convierte la parte inicial de s a un entero con signo, el cual será devuelto como un valor de tipo `long int', haciendo que *endp apunte al primer carácter no convertido, si endp no es un puntero nulo. Si el parámetro base es cero, la base es determinada buscando cosas como `0x', `0X', o `0' como parte inicial de la cadena, y ajusta la base a 16, 16 u 8 respectivamente si se encuentra algo. La base por defecto es 10 en el caso de que no se detecte ninguno de esos prefijos.
Relacionado con: uconvert, ustrtod, uatof.
double ustrtod(const char *s, char **endp);
Convierte en número de coma flotante tantos carácteres de s que parezcan un número en coma flotante, y hace que *endp apunte al primer carácter no usado, si endp no es un puntero nulo.
Relacionado con: uconvert, ustrtol, uatof.
const char *ustrerror(int err);
Esta función devuelve una cadena que describe el código de error `err', que normalmente vendrá de la variable `errno'. Devuelve un puntero a una cadena estática que no debe ser modificada o liberada. Si hace llamadas posteriores a ustrerror, la cadena puede ser sobreescrita.
Relacionado con: uconvert, allegro_error.
int usprintf(char *buf, const char *format, ...);
Esta función escribe datos formateados en el buffer de salida. El carácter NULL es escrito para marcar el final de la cadena. Devuelve el número de carácteres que fueron escritos, sin incluír el carácter terminador nulo.
Relacionado con: uconvert, uszprintf, uvsprintf.
int uszprintf(char *buf, int size, const char *format, ...);
Esta función escribe datos formateados en el buffer de salida, cuya longitud en bytes es especificada por size, y que está garantizado que acabará en carácter NULL. Devuelve el número de carácteres que se hubiesen escrito sin contar la truncación eventual (como con usprintf), y sin incluír el carácter terminador NULL.
Relacionado con: uconvert, usprintf, uvszprintf.
int uvsprintf(char *buf, const char *format, va_list args);
Esto es como usprintf, pero usted pasa una lista variable de argumentos en vez de los propios argumentos.
Relacionado con: uconvert, usprintf, uvszprintf.
int uvszprintf(char *buf, int size, const char *format, va_list args);
Esto es como uszprintf(), pero usted pasa una lista variable de argumentos en vez de los propios argumentos.
Relacionado con: uconvert, uszprintf, uvsprintf.

Volver al Indice