sprintf_s
, _sprintf_s_l
, swprintf_s
, _swprintf_s_l
將格式化資料寫入字串。 這些函式是 、 _sprintf_l
、 swprintf
、 _swprintf_l
的版本 sprintf
, __swprintf_l
具有 CRT 中安全性功能中所述 的安全性增強功能。
語法
int sprintf_s(
char *buffer,
size_t sizeOfBuffer,
const char *format,
...
);
int _sprintf_s_l(
char *buffer,
size_t sizeOfBuffer,
const char *format,
_locale_t locale,
...
);
int swprintf_s(
wchar_t *buffer,
size_t sizeOfBuffer,
const wchar_t *format,
...
);
int _swprintf_s_l(
wchar_t *buffer,
size_t sizeOfBuffer,
const wchar_t *format,
_locale_t locale,
...
);
template <size_t size>
int sprintf_s(
char (&buffer)[size],
const char *format,
...
); // C++ only
template <size_t size>
int swprintf_s(
wchar_t (&buffer)[size],
const wchar_t *format,
...
); // C++ only
參數
buffer
輸出的儲存位置
sizeOfBuffer
要儲存的最大字元數。
format
格式控制字串
...
要進行格式化的選擇性引數
locale
要使用的地區設定。
如需詳細資訊,請參閱 格式規格語法 。
傳回值
寫入的字元數,如果發生錯誤,則為 -1。 如果 buffer
或 format
為 null 指標、則 sprintf_s
和 swprintf_s
會傳回 -1,並將 errno
設定為 EINVAL
。
sprintf_s
會傳回儲存在 buffer
中的位元組數目,不計結束的 null 字元。 swprintf_s
會傳回儲存在 buffer
中的寬字元數目,不計結束的 null 寬字元。
備註
sprintf_s
函式會在 buffer
中格式化並儲存一連串字元和值。 每個 argument
(如果有的話) 是根據 format
中的對應格式規格進行轉換和輸出。 此格式包含一般字元,與 printf
的 format
引數具有相同的形式和功能。 null 字元會附加至最後一個寫入的字元之後。 如果在重疊的字串之間進行複製,則行為是未定義的。
sprintf_s
和 sprintf
之間有一個主要差異,即在於 sprintf_s
會檢查格式字串中的格式化字元是否有效,而 sprintf
只檢查格式字串或緩衝區是否為 NULL
指標。 如果任一檢查失敗,則會叫用不正確參數處理常式,如參數驗證 中所述 。 如果允許繼續執行,則函式會傳回 -1 並將 errno
設定為 EINVAL
。
sprintf_s
和 sprintf
之間的另一個主要差異在於 sprintf_s
接受指定輸出緩衝區大小 (以字元為單位) 的長度參數。 若緩衝區對格式化文字而言太小 (包括結尾的 null),就會藉由 null 字元放在 buffer[0]
,將緩衝區設為空字串,並叫用無效的參數處理常式。 與 _snprintf
不同的是, sprintf_s
保證緩衝區會以 null 結尾 (除非緩衝區大小為零)。
swprintf_s
是 sprintf_s
的寬字元版本, swprintf_s
的指標引數是寬字元字串。 中的 swprintf_s
編碼錯誤偵測可能與 中的 sprintf_s
偵測不同。 這些有 _l
尾碼的函式版本是一樣的,不同之處在於會使用傳入的地區設定,而不使用目前的執行緒地區設定。
在 C++ 中,範本多載可簡化這些函式的使用。 多載可以自動推斷緩衝區長度,而不需要指定 size 引數。 而且,它們可以使用較新的、更安全的對應專案來自動取代較舊的非安全函式。 如需詳細資訊,請參閱 保護範本多載 。
有一些版本 sprintf_s
可更充分控制緩衝區太小時會發生什麼情況。 如需詳細資訊,請參閱 、 、 _snprintf_s_l
_snwprintf_s
_snwprintf_s_l
。 _snprintf_s
重要
從 Windows 10 版本 2004(組建 19041)開始,函 printf
式系列會根據 IEEE 754 規則來列印完全可代表的浮點數以進行四捨五入。 在舊版的 Windows 中,完全代表以 '5' 結尾的浮點數一律會四捨五入。 IEEE 754 指出,他們必須四捨五入到最接近的偶數數位(也稱為「銀行家的四捨五入」)。 例如, printf("%1.0f", 1.5)
和 應該 printf("%1.0f", 2.5)
四捨五入為 2。 先前,1.5 會四捨五入為 2,而 2.5 會四捨五入為 3。 這項變更只會影響確切可表示的數位。 例如,2.35 (在記憶體中表示時,其接近 2.3500000000000000008)會繼續四捨五入至 2.4。 這些函式完成的四捨五入現在也會遵守 所 fesetround
設定的浮點舍入模式。 之前,舍入一律選擇 FE_TONEAREST
行為。 這項變更只會影響使用 Visual Studio 2019 16.2 版和更新版本所建置的程式。 若要使用舊版浮點舍入行為,請連結至 'legacy_stdio_float_rounding.obj' 。
泛型文字常式對應
TCHAR.H 常式 | _UNICODE 和 _MBCS 未定義 |
_MBCS 定義 |
_UNICODE 定義 |
---|---|---|---|
_stprintf_s |
sprintf_s |
sprintf_s |
swprintf_s |
_stprintf_s_l |
_sprintf_s_l |
_sprintf_s_l |
_swprintf_s_l |
需求
常式 | 必要的標頭 |
---|---|
sprintf_s , _sprintf_s_l |
C: < stdio.h> C++: < cstdio > 或 < stdio.h> |
swprintf_s , _swprintf_s_l |
C: < stdio.h > 或 < wchar.h> C++: < cstdio > 、 < cwchar > 、 < stdio.h > 或 < wchar.h> |
如需相容性詳細資訊,請參閱相容性。
範例:使用sprintf_s格式化資料
// crt_sprintf_s.c
// This program uses sprintf_s to format various
// data and place them in the string named buffer.
//
#include <stdio.h>
int main( void )
{
char buffer[200], s[] = "computer", c = 'l';
int i = 35, j;
float fp = 1.7320534f;
// Format and print various data:
j = sprintf_s( buffer, 200, " String: %s\n", s );
j += sprintf_s( buffer + j, 200 - j, " Character: %c\n", c );
j += sprintf_s( buffer + j, 200 - j, " Integer: %d\n", i );
j += sprintf_s( buffer + j, 200 - j, " Real: %f\n", fp );
printf_s( "Output:\n%s\ncharacter count = %d\n", buffer, j );
}
Output:
String: computer
Character: l
Integer: 35
Real: 1.732053
character count = 79
範例:錯誤碼處理
// crt_swprintf_s.c
// wide character example
// also demonstrates swprintf_s returning error code
#include <stdio.h>
int main( void )
{
wchar_t buf[100];
int len = swprintf_s( buf, 100, L"%s", L"Hello world" );
printf( "wrote %d characters\n", len );
len = swprintf_s( buf, 100, L"%s", L"Hello\xffff world" );
// swprintf_s fails because string contains WEOF (\xffff)
printf( "wrote %d characters\n", len );
}
wrote 11 characters
wrote -1 characters
另請參閱
資料流 I/O
fprintf
, _fprintf_l
, fwprintf
, _fwprintf_l
printf
, _printf_l
, wprintf
, _wprintf_l
sprintf
, _sprintf_l
, swprintf
, _swprintf_l
, __swprintf_l
scanf
, _scanf_l
, wscanf
, _wscanf_l
sscanf
, _sscanf_l
, swscanf
, _swscanf_l
vprintf
函數
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應