wsprintfA 函式 (winuser.h)

發行項
03/04/2024

將格式化的數據寫入指定的緩衝區。系統會根據格式字串中的對應格式規格，轉換任何自變數並複製到輸出緩衝區。函式會將終止的 Null 字元附加至其寫入的字元，但傳回值不會在其字元計數中包含終止的 Null 字元。

注意請勿使用。請考慮改用下列其中一個函式：StringCbPrintf、StringCbPrintfEx、StringCchPrintf 或 StringCchPrintfEx。請參閱安全性考慮。

語法

int WINAPIV wsprintfA(
  [out] LPSTR  unnamedParam1,
  [in]  LPCSTR unnamedParam2,
        ...    
);

參數

[out] unnamedParam1

類型： LPTSTR

要接收格式化輸出的緩衝區。緩衝區的大小上限為1,024個字節。

[in] unnamedParam2

類型： LPCTSTR

格式控制件規格。除了一般 ASCII 字元之外，每個自變數的格式規格也會在此字串中出現。如需格式規格的詳細資訊，請參閱一節。

...

一或多個選擇性自變數。自變數參數的數目和類型取決於 lpFmt 參數中對應的格式控制規格。

傳回值

類型： int

如果函式成功，傳回值就是儲存在輸出緩衝區中的字元數，而不是計算終止的 Null 字元。

如果函式失敗，傳回值會小於預期的輸出長度。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

格式控制字串包含格式規格，可決定 lpFmt 參數之後自變數的輸出格式。以下討論的格式規格一律以百分比符號 (%) 開始。如果百分比符號後面接著沒有意義做為格式欄位的字元，字元就不會格式化 (例如，%% 會產生單一百分比符號字元) 。

格式控制字串是從左至右讀取。如果遇到任何) ，則第一個格式規格 (時，會導致格式控制字串轉換后的第一個自變數值，並根據格式規格複製到輸出緩衝區。第二個格式規格會導致轉換和複製第二個自變數，依此類移。如果自變數數目超過格式規格，則會忽略額外的自變數。如果所有格式規格都沒有足夠的自變數，則結果不會定義。

格式規格的格式如下︰

%[-][#][0][width][.precision]type

每個欄位都是單一字元或代表特定格式選項的數位。最後一個選擇性格式字段之後出現的類型字元會判斷相關聯的自變數是否解譯為字元、字串或數位。最簡單的格式規格只包含百分比符號和類型字元 (例如%s) 。選擇性欄位可控制格式化的其他層面。以下是選擇性和必要欄位及其意義。

欄位	意義
-	在右側以空白或零填補輸出，以填滿字段寬度，使輸出靠左對齊。如果省略此欄位，輸出會填補到左邊，並將它靠右對齊。
#	前置十六進位值， (小寫) 或 0X (大寫) 。
0	以零填補輸出值，以填滿字段寬度。如果省略此欄位，輸出值會以空格填補。
width (寬度)	將指定的最小字元數複製到輸出緩衝區。寬度欄位是非負整數。寬度規格永遠不會截斷值;如果輸出值中的字元數大於指定的寬度，或寬度欄位不存在，則會列印值的所有字元，受限於有效位數規格。
.精度	針對數位，將指定的最小位數複製到輸出緩衝區。如果自變數中的位數小於指定的有效位數，輸出值會在左邊填補零。當位數超過指定的有效位數時，不會截斷值。如果指定的有效位數是 0 或完全省略，或者如果句點 (.) 出現在後沒有數位，則精確度會設定為 1。針對字串，將指定的最大字元數複製到輸出緩衝區。
type	將對應的自變數輸出為字元、字串或數位。此欄位可以是下列任何值。 `c` 單一字元。此值會依 wsprintfA 解譯為 CHAR 類型，並依 wsprintfW 輸入 WCHAR。注意 wsprintf 是定義為 wsprintfA 的宏， (未定義) 或 wsprintfW () 定義的 Unicode。 `C` 單一字元。此值會由 wsprintfA 解譯為類型 WCHAR，並依 wsprintfW 輸入 CHAR。注意 wsprintf 是定義為 wsprintfA 的宏， (未定義) 或 wsprintfW () 定義的 Unicode。 `d` 帶正負號的十進位整數。這個值相當於 `i`。 `hc`, `hC` 單一字元。如果字元的數值為零，則會忽略它。即使呼叫的應用程式定義 Unicode，這個值一律會解譯為 CHAR 類型。 `hd` 帶正負號的短整數自變數。 `hs`, `hS` 字串。即使呼叫的應用程式定義 Unicode，這個值一律會解譯為類型 LPSTR。 `hu` 不帶正負號的短整數。 `i` 帶正負號的十進位整數。這個值相當於 `d`。 `Ix`, `IX` 64 位平臺上小寫或大寫的 64 位不帶正負號十六進位整數、小寫或 32 位平臺上 32 位無符號十六進位整數。 `lc`, `lC` 單一字元。如果字元的數值為零，則會忽略它。即使呼叫的應用程式定義 Unicode，這個值一律會解譯為 WCHAR 類型。 `ld` 長帶正負號的整數。這個值相當於 `li`。 `li` 長帶正負號的整數。這個值相當於 `ld`。 `ls`, `lS` 字串。即使呼叫的應用程式未定義 Unicode，這個值一律會解譯為類型 LPWSTR。這個值相當於 `ws`。 `lu` 長無符號整數。 `lx`, `lX` 以小寫或大寫表示的長不帶正負號十六進位整數。 `p` 指標。位址會使用十六進位列印。 `s` 字串。此值會由 wsprintfA 解譯為 LPSTR 類型，並依 wsprintfW 輸入 LPWSTR。注意 wsprintf 是定義為 wsprintfA 的宏， (未定義) 或 wsprintfW () 定義的 Unicode。 `S` 字串。此值會由 wsprintfA 解譯為 LPWSTR 類型，而 wsprintfW 類型為 LPSTR。注意 wsprintf 是定義為 wsprintfA 的宏， (Unicode 未定義) 或 wsprintfW () 定義的 Unicode。 `u` 不帶正負號的整數自變數。 `x`, `X` 小寫或大寫不帶正負號的十六進位整數。

注意請務必注意， wsprintf 使用 C 呼叫慣例 (_cdecl) ，而不是標準呼叫 (_stdcall) 呼叫 慣例。因此，呼叫進程會負責將自變數從堆疊移出，而自變數會從右至左推送到堆棧上。在 C 語言模組中，C 編譯程式會執行這項工作。

若要使用大於 1024 個字節的緩衝區，請使用 _snwprintf。如需詳細資訊，請參閱 C 執行時間連結庫的檔。

注意

winuser.h 標頭會根據 UNICODE 預處理器常數的定義，將 wsprintf 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll