sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

Zapisywanie sformatowanych danych w ciągu. Te funkcje to wersje , sprintf, swprintf_sprintf_l, _swprintf_l__swprintf_l z ulepszeniami zabezpieczeń zgodnie z opisem w temacie Funkcje zabezpieczeń w środowisku CRT.

Składnia

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

Parametry

buffer
Lokalizacja magazynu dla danych wyjściowych

sizeOfBuffer
Maksymalna liczba znaków do zapisania.

format
Ciąg kontrolki formatu

...
Opcjonalne argumenty do sformatowania

locale
Ustawienia regionalne do użycia.

Aby uzyskać więcej informacji, zobacz Składnia specyfikacji formatu.

Wartość zwracana

Liczba zapisanych znaków lub -1, jeśli wystąpił błąd. Jeśli buffer lub format jest wskaźnikiem o wartości null, sprintf_s i swprintf_s zwróć wartość -1 i ustaw wartość errnoEINVAL.

sprintf_s Zwraca liczbę bajtów przechowywanych w bufferobiekcie , która nie zlicza znaku null zakończenia. swprintf_s Zwraca liczbę znaków szerokich przechowywanych w bufferobiekcie , która nie zlicza znaku szerokiego o wartości null zakończenia.

Uwagi

Funkcja sprintf_s formatuje i przechowuje serię znaków i wartości w pliku buffer. Każda argument (jeśli istnieje) jest konwertowana i wyjściowa zgodnie z odpowiednią specyfikacją formatu w pliku format. Format składa się ze zwykłych znaków i ma taką samą formę i funkcję jak format argument dla printfelementu . Znak null jest dołączany po zapisaniu ostatniego znaku. Jeśli kopiowanie odbywa się między nakładającymi się ciągami, zachowanie jest niezdefiniowane.

Jedną z głównych różnic między sprintf_s i sprintf jest to, że sprintf_s sprawdza ciąg formatu prawidłowych znaków formatowania, podczas gdy sprintf sprawdza, czy ciąg formatu lub bufor są NULL wskaźnikami. Jeśli sprawdzanie nie powiedzie się, wywoływana jest nieprawidłowa procedura obsługi parametrów, zgodnie z opisem w temacie Weryfikacja parametrów. Jeśli wykonywanie jest dozwolone do kontynuowania, funkcja zwraca wartość -1 i ustawia wartość errnoEINVAL.

Druga główna różnica między elementami sprintf_s i sprintf polega na tym, że sprintf_s przyjmuje parametr długości określający rozmiar buforu wyjściowego w znakach. Jeśli bufor jest za mały dla sformatowanego tekstu, w tym wartości null zakończenia, bufor jest ustawiony na pusty ciąg, umieszczając znak null w buffer[0]obiekcie , a wywoływana jest nieprawidłowa procedura obsługi parametrów. W przeciwieństwie do _snprintfprogramu sprintf_s gwarantuje, że bufor zostanie przerwany z wartością null, chyba że rozmiar buforu ma wartość zero.

swprintf_s jest wersją sprintf_swieloznakową ; argumenty wskaźnika do swprintf_s są ciągami o szerokim znaku. Wykrywanie błędów kodowania w swprintf_s programie może różnić się od wykrywania w programie sprintf_s. Wersje tych funkcji z sufiksem _l są identyczne, z tą różnicą, że używają parametru ustawień regionalnych przekazanych zamiast bieżących ustawień regionalnych wątku.

W języku C++użycie tych funkcji jest uproszczone przez przeciążenia szablonów. Przeciążenia mogą automatycznie wnioskować długość buforu, co eliminuje konieczność określenia argumentu rozmiaru. Ponadto mogą automatycznie zastępować starsze, niezabezpieczne funkcje nowszymi, bardziej bezpiecznymi odpowiednikami. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Istnieją wersje, sprintf_s które oferują większą kontrolę nad tym, co się stanie, jeśli bufor jest za mały. Aby uzyskać więcej informacji, zobacz , , _snwprintf_s_snprintf_s_l, _snwprintf_s_l._snprintf_s

Ważne

Począwszy od systemu Windows 10 w wersji 2004 (kompilacja 19041), printf rodzina funkcji drukuje dokładnie możliwe liczby zmiennoprzecinkowe zgodnie z regułami IEEE 754 dotyczącymi zaokrąglania. W poprzednich wersjach systemu Windows dokładnie reprezentowane liczby zmiennoprzecinkowe kończące się na "5" zawsze zaokrągla się w górę. IEEE 754 stwierdza, że muszą zaokrąglić do najbliższej parzysta cyfra (znana również jako "Zaokrąglanie Bankiera"). Na przykład oba printf("%1.0f", 1.5)printf("%1.0f", 2.5) elementy i powinny być zaokrąglone do 2. Wcześniej 1,5 zaokrągliłoby się do 2 i 2,5 do 3. Ta zmiana dotyczy tylko dokładnie możliwych do reprezentowania liczb. Na przykład 2,35 (który, gdy jest reprezentowany w pamięci, jest bliżej 2,350000000000000008) nadal zaokrągla się do 2,4. Zaokrąglanie wykonywane przez te funkcje jest teraz również zgodne z trybem zaokrąglania zmiennoprzecinkowego ustawionym przez fesetround. Wcześniej zaokrąglanie zawsze wybierało FE_TONEAREST zachowanie. Ta zmiana dotyczy tylko programów utworzonych przy użyciu programu Visual Studio 2019 w wersji 16.2 lub nowszej. Aby użyć starszego zachowania zaokrąglania zmiennoprzecinkowego, połącz się z elementem "legacy_stdio_float_rounding.obj".

Mapowania procedur tekstu ogólnego

Procedura TCHAR.H	_UNICODE i _MBCS niezdefiniowane	_MBCS Zdefiniowane	_UNICODE Zdefiniowane
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

Wymagania

Procedura	Wymagany nagłówek
sprintf_s, _sprintf_s_l	C: <stdio.h> C++: <cstdio> lub <stdio.h>
swprintf_s, _swprintf_s_l	C: <stdio.h> lub <wchar.h> C++: <cstdio>, <cwchar>, <stdio.h> lub <wchar.h>

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

Przykład: formatowanie danych za pomocą 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

Przykład: obsługa kodu błędu

// 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

Zobacz też

We/Wy strumienia
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, funkcje