wsprintf

원형

int wsprintf(LPTSTR lpOut, LPCTSTR lpFmt, ...);

MFC 원형

void CString::Format( LPCTSTR lpszFormat, ... );

인수

▶lpOut : 서식화된 출력을 내보낼 문자열 버퍼. 최대 길이는 1024바이트이다.

▶lpFmt : 서식 문자열이며 일반 문자열 사이에 %로 시작되는 서식을 포함할 수 있다.

▶... : 서식 문자열내의 서식과 대응될 변수들. 서식의 개수만큼 변수를 제공해야 한다.

리턴

성공할 경우 버퍼로 복사된 문자 개수를 리턴해주되 널 종료 문자는 개수에서 제외된다. 실패할 경우 예상된 출력보다 더 작은 문자수가 리턴되며 이 경우 실패 원인은 GetLastError로 조사할 수 있다.

설명

서식화된 출력을 문자열 버퍼로 보낸다. 도스의 printf에 대응되는 API 함수이며 출력할 서식 문자열을 조립하는 가장 일반적인 방법을 제공한다. lpOut는 서식을 조립한 결과를 입력받을 버퍼이되 최대 1024길이의 문자열을 조립할 수 있으며 충분한 길이의 버퍼를 제공해야 한다. lpFmt는 출력에 사용될 문자열이되 이 문자열에는 서식이 포함될 수 있다. 서식은 일반적으로 다음과 같은 형식을 가진다.

%[-][#][0][w][.p]타입

[]괄호안에 있는 옵션은 필요할 경우만 지정하며 %와 타입은 반드시 적어주어야 한다. 사용할 수 있는 타입은 다음과 같다.

서식 설명
d,i,li,ld

32비트의 부호있는 정수값. i와 d는 같은 서식이며 l은 long이라는 뜻이나 Win32에서는 long이 곧 32비트이므로 4가지 서식은 모두 동일하다.
u,lu

32비트의 부호없는 정수값.
x,X,lx,lX

부호없는 16진 정수값. x는 영문자를 소문자로 출력하며 X는 대문자로 출력한다.
c

문자 하나. UNICODE 매크로가 정의되어 있으면 WCHAR와 대응되며 그렇지 않으면 CHAR와 대응된다.
C

문자 하나. UNICODE 매크로가 정의되어 있으면 CHAR와 대응되며 그렇지 않으면 WCHAR와 대응된다.
lc, lC

문자 하나. UNICODE 매크로의 정의여부와는 상관없이 무조건 WCHAR과 대응된다.
hc, hC

문자 하나. UNICODE 매크로의 정의여부와는 상관없이 무조건 CHAR과 대응된다.
s

문자열. UNICODE 매크로가 정의되어 있으면 LPWSTR과 대응되며 그렇지 않으면 LPSTR과 대응된다.
S

문자열. UNICODE 매크로가 정의되어 있으면 LPSTR과 대응되며 그렇지 않으면 LPWSTR과 대응된다.
ls, lS

문자열. UNICODE 매크로의 정의여부와는 상관없이 무조건 LPWSTR과 대응된다.
hs, hS

문자열. UNICODE 매크로의 정의여부와는 상관없이 무조건 LPSTR과 대응된다.
p

2000이상에서만 사용할 수 있으며 16진수의 주소값과 대응된다.
%

%문자 자체를 나타낼 때 사용한다.

wsprintf는 유니코드를 지원하며 UNICODE 매크로의 정의 여부에 따라 서식과 대응되는 변수의 포맷이 달라질 수 있다. lpFmt 인수 다음에는 서식에 대응되는 변수가 오며 이 변수들은 lpFmt에서 나타나는 서식과 순서대로 일대일 대응된다. 예를 들어 다음과 같이 이 함수를 호출했다고 하자.

wsprintf(lpOut, "선택하신 값 %d는 %d번째의 %s설정을 변경합니다.",iValue, iOrder, szConf);

첫번째 %d는 세번째 변수 iValue를 받으며 두번째 %d는 다섯번째 변수 iOrder값을 받으며 %s는 마지막 인수 szConf를 받는다. 서식 문자열에 나타나는 서식의 개수와 호환되는 타입의 변수가 반드시 제공되어야 한다.

다음 예제는 기본적인 타입에 대해 서식 문자열을 조립하여 출력해 본 것이다.

예제 1 

LRESULT CALLBACK WndProc(HWND hWnd,UINT iMessage,WPARAM wParam,LPARAM lParam)
{
	HDC hdc;
	PAINTSTRUCT ps;
	TCHAR lpOut[1024];

	switch(iMessage) {
	case WM_PAINT:
		hdc=BeginPaint(hWnd, &ps);
		wsprintf(lpOut,TEXT("정수=%d, 부호없는 정수=%u"),1234567890,3234567890);
		TextOut(hdc,10,10,lpOut,lstrlen(lpOut));
		wsprintf(lpOut,TEXT("16진수=%x, 16진수=%X"),0xabcd,0xabcd);
		TextOut(hdc,10,30,lpOut,lstrlen(lpOut));

		wsprintf(lpOut,TEXT("문자=%c, 문자=%C"),'S',L'한');
		TextOut(hdc,10,50,lpOut,lstrlen(lpOut));

		wsprintf(lpOut,TEXT("문자열=%s, 문자열=%S"),"대한민국",L"우리나라");
		TextOut(hdc,10,70,lpOut,lstrlen(lpOut));

		EndPaint(hWnd, &ps);
		return 0;
	case WM_DESTROY:
		PostQuitMessage(0);
		return 0;
	}
	return(DefWindowProc(hWnd,iMessage,wParam,lParam));
}

정수형과 16진 정수, 문자, 문자열에 대해 서식을 적용해 보았다. wsprintf는 유니코드를 지원하므로 서식문자열을 작성할 때도 TEXT 매크로를 사용하는 것이 좋다.

기본적인 서식외에도 %와 타입 사이에 다음과 같은 옵션을 지정할 수 있다. 옵션에 따라 변수 출력 자리수와 정렬 방식, 선행 제로 처리 방식에 변화를 줄 수 있다. 아래 도표에서 E는 공백을 의미한다.

인수 설명

-

출력을 왼쪽으로 정렬한다. 이 옵션이 없으면 오른쪽으로 정렬된다. 예를 들어 %8d일 경우 EEEE1234가 되지만 %-08d일 경우 1234EEEE로 출력된다.
#

%x와 %X사이에 삽입되며 0x 또는 0X를 붙여준다.
0

남는 공간을 공백으로 두지 않고 0으로 채운다.
w

최소폭을 지정한다. %d는 대응되는 변수값만큼의 폭에 출력되지만 최소폭을 지정하면 최소한 이 폭만큼은 자리수를 채운다. 예를 들어 %d는 1234가 되지만 %6d는 EE1234가 된다. 만약 변수값이 최소폭보다 더 클 경우 변수값이 잘리지는 않도록 해 준다. 예를 들어 %6d로 12345678을 출력하더라도 폭을 강제로 여섯자리로 축소하지는 않으며 이 경우 변수값이 요구하는 폭을 모두 할당한다.
.p

숫자의 경우 출력 버퍼에 사용될 최소 폭을 지정한다. 만약 변수값이 이 폭보다 작을 경우 0으로 채운다.

다음 예제는 서식에 옵션을 적용하여 다양한 형태로 출력해 본 것이다.

예제 2

LRESULT CALLBACK WndProc(HWND hWnd,UINT iMessage,WPARAM wParam,LPARAM lParam)
{
	HDC hdc;
	PAINTSTRUCT ps;
	TCHAR lpOut[1024];
	int i;

	switch(iMessage) {
	case WM_PAINT:
		hdc=BeginPaint(hWnd, &ps);
		i=1234;
		wsprintf(lpOut,TEXT("정수1=%d, 정수2=%8d, 정수3=%-8d, 정수4=%08d"),i,i,i,i);
		TextOut(hdc,10,10,lpOut,lstrlen(lpOut));
		wsprintf(lpOut,TEXT("정수5=%.8d"),i);
		TextOut(hdc,10,30,lpOut,lstrlen(lpOut));
		wsprintf(lpOut,TEXT("16진수1=%x, 16진수2=%#x"),0xab,0xab);
		TextOut(hdc,10,50,lpOut,lstrlen(lpOut));
		EndPaint(hWnd, &ps);
		return 0;
	case WM_DESTROY:
		PostQuitMessage(0);
		return 0;
	}
	return(DefWindowProc(hWnd,iMessage,wParam,lParam));
}

%d는 단순히 정수형 변수를 받으므로 정수값 1234의 자리수에 맞게만 출력한다. %8d는 정수값을 출력하되 최소 8자리를 반드시 차지하도록 해 주며 이 때 남는 자리수는 공백으로 남겨진다. %-8d는 공백을 오른쪽으로 보내 왼쪽으로 정렬되도록 해 준다. %08d와 %.8d는 8자리로 정수값을 출력하되 남는 자리는 선행 제로로 채우도록 한다.

다음은 이 함수의 몇가지 간단한 활용예이다.

1.에러 메시지를 조립할 때 사용한다.

wsprintf(sError, "선택하신 %s 옵션은 지금 사용할 수 없습니다",szOption);

2.SQL 쿼리문을 조립한다.

wsprintf(szSQL, "select * from tblSample where age > %d and height < %d",iAge,iHeight);

3.디버깅을 위해 변수값을 메시지 박스로 확인한다.

wsprintf(szMessage,"x=%d, y=%d, sOrder=%s",x,y,sOrder);
MessageBox(hWnd,szMessage,"봐",MB_OK);

4.타이틀 바에 출력할 문자열을 조립한다.

wsprintf(sCaption,"MyProgram - %s",sDocument);
SetWindowText(hWnd,sCaption);

이 함수는 굉장히 사용하기 쉽고 유용하다. 물론 printf도 모르는 사람에게는 다소 어려울 수도 있으나 서식 출력은 C언어의 표준화된 기능이므로 대부분의 사람이 익숙하게 사용할 수 있다. 그러나 이 함수는 또한 몇가지 주의 사항을 지키지 않으면 에러를 발생할 가능성이 아주 많으므로 주의해야 한다. 다음은 이 함수를 사용할 때 주의해야할 일반적인 사항이다.

1.서식 문자열 내의 서식과 변수의 개수는 일치해야 한다. 만약 서식의 개수보다 더 많은 변수가 제공될 경우 남는 변수는 무시되므로 크게 문제가 되지 않지만 반대의 경우, 즉 서식보다 변수가 더 작을 경우는 결과를 예측할 수 없으며 치명적인 에러의 원인이 된다. 다음 코드를 보자.

wsprintf(lpOut,"%s의 결과는 %d,%d이다",sOp,x);

서식은 세 개이나 제공된 변수는 두 개 뿐이다. 이 함수는 가변 인수를 취하므로 컴파일시에는 인수의 개수가 부족하다고 해서 에러가 발생하지 않으며 실행중에 변수가 부족할 경우 스택의 다음 번지에서 쓰레기값을 가져와 채워 넣게 되므로 엉뚱한 결과가 출력될 수 있으며 포인터값을 읽을 경우는 Access Violation 등의 예외를 일으킬 수도 있다.

2.서식과 대응되는 변수의 타입은 반드시 일치해야 한다. %d에 문자열 변수가 대응되거나 반대로 %s에 정수형 변수가 대응되면 마찬가지로 예외를 일으킬 수 있다.

3.wsprintf는 1024자까지의 출력 버퍼만을 지원한다. 쿼리문이나 로그문같이 대단히 긴 문자열을 조립할 때는 이 함수를 사용할 수 없다. 1024자 이상의 문자열을 조립할 때는 sprintf 등의 C 런타임 함수를 사용해야 한다.

4.wsprintf는 실수 서식은 조립하지 못한다. 실수 서식을 문자열에 조립하고자 할 경우는 strtod 등의 함수로 실수를 문자열로 먼저 바꿔 놓고 %s로 받거나 아니면 sprintf 등의 C 런타임 함수를 사용하는 것이 좋다.

5.이 함수는 가변 인수를 지원하기 때문에 일반적인 API 함수와는 달리 _cdecl 호출 규약을 사용한다. 따라서 이 함수를 호출하는 프로세스는 반드시 스택을 정리해 주어야 하며 인수는 반드시 오른쪽에서 왼쪽으로 전달해 주어야 한다. C언어 컴파일러는 이 과정을 자동으로 수행해 주지만 다른 방법(예를 들어 어셈블리)으로 이 함수를 사용할 때는 호출규약에 따른 처리를 반드시 해 주어야 한다.

참고함수

sprintf : 1000자 이상을 지원하며 실수 서식도 사용할 수 있다. API 함수는 아니며 유니코드는 지원하지 않는다.

플랫폼

95이상

참조

 


written by http://www.winapi.co.kr