winuser.h

wsprintf

La función wsprintf da formato y almacena una serie de caracteres y valores en un búfer. Cualquier argumento se convierte y copia al búfer de salida de acuerdo al formato correspondiente especificado en la cadena de formato. La función añade el carácter terminador nulo final a los caracteres que escribe, pero el valor de retorno no lo incluye en el número de caracteres.

Sintaxis

int wsprintf(
    LPTSTR lpOut,   // puntero al búfer de salida
    LPCTSTR lpFmt,  // puntero a la cadena de control de formato
    ...	            // argumentos opcionales
   );

Parámetros

lpOut: apunta al búfer que recibe la salida formateada.

lpFmt: apunta a una cadena terminada en nulo que contiene las especificaciones de control de formato. Además de caracteres ASCII corrientes, aparecerá una espcificación de formato para cada argumento. Para más información sobre los especificadores de formato, ver la sección de Observaciones.

...: especifica uno o más argumentos opcionales. El número y tipo de los parámetros dependerá de los especificadores de formato correspondientes en el parámetro lpFmt.

Valor de retorno

Si la función tiene éxito, el valor de retorno es el número de caracteres almacenados en el búfer de salida, sin contar el carácter nulo terminador.

Si la función falla, el valor de retorno es menor que la longitud de la cadena de control de formato. Para obtener más detalles sobre el error, llamar a GetLastError.

Observaciones

La cadena de control de formato contiene especificaciones de formato que determinan el formato de salida para los argumentos que siguen al parámetro lpFmt. Las especificaciones de formato, explicadas más abajo, siempre empiezan con el carácter de tanto por ciento (%). Si a continuación de un carácter de tanto por ciento hay un carácter que no tiene significado como campo de formato, el carácter no se formatea (por ejemplo, %% produce un único carácter de tanto por ciento).

La cadena de control de formato se lee de izquierda a derecha. Cuando se encuentra la primera especificación de formato (si es que hay), el valor del primer argumento a continuación de la cadena de control de formato se convierte y copia al búfer de salida de acuerdo con la especificación de formato. La segunda especificación de formato hace que se convierta y se copie el segundo argumento, y así sucesivamente. Si hay más argumentos que especificadores de formato, los argumentos extra son ignorados. Si no hay suficientes argumentos para todos los especificadores de formato, el resultado queda indefinido.

Una especificación de formato tiene la siguiente forma:

%[-][#][0][anchura][.precisión]tipo

Cada campo es un único carácter o un número con el significado de una opción de formato particular. Los caracteres de tipo que aparecen después del último campo opcional de formato determinan si el argumento asociado es interpretado como un carácter, una cadena o un número. La especificación de formato más simple sólo contiene el carácter de tanto por ciento y el carácter de tipo (por ejemplo, %s). Los campos opcionales controlan otros aspectos del formateo. A continuacuón se muestran los campos opcionales y requeridos y sus significados:

Campo	Significado
-	Rellena la salida con blancos o ceros a la derecha para completar la anchura del campo, justifica la salida a la izquierda. Si se omite este campo, la salida se rellena a la izquierda, justificando a la derecha.
#	Prefija los valores hexadecimales con 0x (minúscula) o 0X (mayúscula).
0	Rellena el valor de salida con cerso para completar el campo de anchura. Si se omite este campo, el valor de salida se rellena con espacios blancos.
width	Copia el número mínimo de caracteres especificado al búfer de salida. El campo anchura es un entero no negativo. La especificación de anchura nunca hace que un valor sea truncado; si el número de caracteres en el valor de salida es mayor que la anchura especificada, o si el campo anchura no está presente, se imprimen todos los caracteres del valor, según la especificación de precisión.
.precision	Para números, copia el número mínimo de dígitos especificado al búfer de salida. Si el número de dígitos en el argumento es menor que la especificación de precisión, el valor de salida se rellena a la izquierda con ceros. El valor no se trunca cuando el número de dígitos excede la especificación de precisión. Si la precisión especificada es 0, si se omite por completo o si el punto decimal (.) aparece sin un número a continuación, se usa una precisión de 1. Para cadenas, copia el número máximo de caracteres especificado al búfer de salida.
type	Extrae el argumento correspondiente como un carácter, una cadena o un número. Este campo puede ser uno de las siguientes secuencias de caracteres:

Secuencia	Inserción
c	Un único carácter. La función wsprintf ignora argumentos de carácter con un valor numérico cero. Esa secuencia se interpreta como tipo WCHAR cuando la aplicación que llama usa la bandera de compilación #define UNICODE y como tipo CHAR en otro caso.
C	Un único carácter. Esta secuencia se interpreta como tipo CHAR cuando la aplicación que llama usa la bandera de compilación #define UNICODE y como tipo WCHAR en otro caso.
d	Un argumento entero decimal con signo. Esta secuencia equivale a la secuencia i.
hc, hC	Un único carácter. La función wsprintf ignora argumentos de carácter con un valor numérico cero. Esta secuencia siempre se interpreta como tipo CHAR, aunque la aplicación que llame use la bandera de compilación #define UNICODE.
hs, hS	Una cadena. Esta secuencia siempre se interpreta como tipo LPSTR, aunque la aplicación que llame use la bandera de compilación #define UNICODE.
i	Un entero decimal con signo. Esta secuencia equivale a la secuencia d.
lc, lC	Un úncio carácter. La función wsprintf ignora argumentos de carácter con un valor numérico cero. Esta secuencia siempre se interpreta como tipo WCHAR, aunque la aplicación que llame use la bandera de compilación #define UNICODE.
ld	Un entero largo decimal con signo. Esta secuencia equinvale a la secuencia li.
li	Un entero largo decimal con signo. Esta secuencia equinvale a la secuencia ld.
ls, lS	Una cadena. Esta secuencia siempre se interpreta como tipo LPWSTR, aunque la aplicación que llame use la bandera de compilación #define UNICODE. Es equivalente a la secuencia ws.
lu	Un entero largo sin signo.
lx, lX	Un entero largo hexadecimal sin signo, en minúscula o mayúscula.
s	Una cadena. Esta secuencia se interpreta como tipo LPWSTR, cuando la aplicación que llame use la bandera de compilación #define UNICODE y como tipo LPSTR en otro caso.
S	Una cadena. Esta secuencia se interpreta como tipo LPSTR, cuando la aplicación que llame use la bandera de compilación #define UNICODE y como tipo LPWSTR en otro caso.
u	Un argumento entero sin signo.
x, X	Un entero hexadecimal sin signo, en minúscula o mayúscula.

Nota: Al contrario que otras funciones Windows, wsprintf usa la convención de llamada C (_cdecl), en lugar de la convención de llamada Pascal. De modo que es responsabilidad del proceso que llame retirar los argumentos de la pila, y los argumentos se colocan en la pila de derecha a izquierda. En módulos de lenguaje C, el compilador de C realiza esta tarea.