assert macro, _assert, _wassert

Valuta un'espressione e, quando il risultato è false, stampa un messaggio di diagnostica e arresta il programma.

Sintassi

assert(
   expression
);
void _assert(
   char const* message,
   char const* filename,
   unsigned line
);
void _wassert(
   wchar_t const* message,
   wchar_t const* filename,
   unsigned line
);

Parametri

expression
Espressione scalare (incluse le espressioni puntatore) che restituisce un valore diverso da zero (true) oppure 0 (false).

message
Messaggio da visualizzare.

filename
Nome del file di origine in cui l'asserzione non è riuscita.

line
Numero di riga nel file di origine dell'asserzione non riuscita.

Osservazioni:

La assert viene in genere usata per identificare gli errori di logica durante lo sviluppo di programmi. Può essere usata per arrestare l'esecuzione del programma quando si verificano condizioni impreviste implementando l'argomento expression in modo che restituisca false solo quando il programma funziona in modo non corretto. I controlli delle asserzioni possono essere disattivati in fase di compilazione definendo la macro NDEBUG. È possibile disattivare la assert macro senza modificare i file di origine usando un'opzione /DNDEBUG della riga di comando. È possibile disattivare la assert macro nel codice sorgente usando una #define NDEBUG direttiva prima <assert.h> di essere inclusa.

La assert macro stampa un messaggio di diagnostica quando expression restituisce false (0) e chiama abort per arrestare l'esecuzione del programma. Se expression è true (diverso da zero), non verrà eseguita alcuna azione. Il messaggio di diagnostica include l'espressione non riuscita, il nome del file di origine e il numero di riga in cui l'asserzione non è riuscita.

Il messaggio di diagnostica viene stampato in caratteri wide (wchar_t). Pertanto, funzionerà come previsto anche se sono presenti caratteri Unicode nell'espressione.

La destinazione dei messaggi di diagnostica dipende dal tipo di applicazione che ha chiamato la routine. Le applicazioni console ricevono il messaggio tramite stderr. In un'applicazione basata su Windows chiama assert la funzione Windows MessageBox per creare una finestra di messaggio per visualizzare il messaggio con tre pulsanti: Interrompi, Riprova e Ignora. Se l'utente sceglie Interrompi, il programma viene interrotto immediatamente. Se l'utente sceglie Riprova, viene chiamato il debugger e l'utente può eseguire il debug del programma se è abilitato il debug JIT (Just-In-Time). Se l'utente sceglie Ignora, il programma continuerà con l'esecuzione normale. Se si fa clic su Ignora quando esiste una condizione di errore, è possibile che si verifica un comportamento non definito perché le precondizioni del codice chiamante non sono state soddisfatte.

Per eseguire l'override del comportamento di output predefinito indipendentemente dal tipo di app, chiamare _set_error_mode per selezionare tra il comportamento da output a stderr e display-dialog-box.

Dopo assert aver visualizzato il messaggio, chiama abort, che visualizza una finestra di dialogo con i pulsanti Interrompi, Riprova e Ignora . abort esce dal programma, quindi il pulsante Riprova e Ignora non riprenderà l'esecuzione del programma dopo la assert chiamata. Se assert viene visualizzata una finestra di dialogo, la abort finestra di dialogo non viene visualizzata. L'unica volta che viene visualizzata la abort finestra di dialogo, è quando assert invia l'output a stderr.

Di conseguenza del comportamento precedente, una finestra di dialogo viene sempre visualizzata dopo una assert chiamata in modalità di debug. Il comportamento di ogni pulsante viene acquisito nella tabella seguente.

Modalità errore	Output in stderr (console/_OUT_TO_STDERR)	Finestra di dialogo Visualizza (Windows/_OUT_TO_MSGBOX)
Abort	Uscire immediatamente con il codice di uscita 3	Uscire immediatamente con il codice di uscita 3
Retry	Eseguire l'interruzione nel debugger durante abort	Eseguire l'interruzione nel debugger durante assert
Ignore	Terminare l'uscita tramite abort	Continuare il programma come se assert non fosse stato attivato (potrebbe comportare un comportamento non definito perché le precondizioni del codice chiamante non sono state soddisfatte)

Per altre informazioni sul debug CRT, vedere Tecniche di debug CRT.

Le funzioni _assert e _wassert sono funzioni CRT interne. Contribuiscono a ridurre al minimo il codice necessario nei file oggetto per supportare le asserzioni. Non è consigliabile chiamare direttamente queste funzioni.

La assert macro è abilitata sia nelle versioni di rilascio che di debug delle librerie di runtime C quando NDEBUG non viene definita. Quando NDEBUG viene definita, la macro è disponibile, ma non ne valuta l'argomento e non ha alcun effetto. Quando è abilitata, la assert macro chiama _wassert l'implementazione. Sono disponibili anche altre macro di asserzione, _ASSERT, _ASSERTE e _ASSERT_EXPR, ma valutano solo le espressioni passate quando la _DEBUG macro è stata definita e quando si trovano nel codice collegato alla versione di debug delle librerie di runtime C.

Requisiti

Ciclo	Intestazione obbligatoria
assert, _wassert	<assert.h>

La firma della _assert funzione non è disponibile in un file di intestazione. La firma della _wassert funzione è disponibile solo quando la NDEBUG macro non è definita.

Esempio

In questo programma la funzione analyze_string usa la macro assert per testare diverse condizioni correlate alla stringa e alla lunghezza. Se una qualsiasi delle condizioni non riesce, il programma stampa un messaggio indicando la causa dell'errore.

// crt_assert.c
// compile by using: cl /W4 crt_assert.c
#include <stdio.h>
#include <assert.h>
#include <string.h>

void analyze_string( char *string );   // Prototype

int main( void )
{
   char  test1[] = "abc", *test2 = NULL, test3[] = "";

   printf ( "Analyzing string '%s'\n", test1 ); fflush( stdout );
   analyze_string( test1 );
   printf ( "Analyzing string '%s'\n", test2 ); fflush( stdout );
   analyze_string( test2 );
   printf ( "Analyzing string '%s'\n", test3 ); fflush( stdout );
   analyze_string( test3 );
}

// Tests a string to see if it is NULL,
// empty, or longer than 0 characters.
void analyze_string( char * string )
{
   assert( string != NULL );        // Cannot be NULL
   assert( *string != '\0' );       // Cannot be empty
   assert( strlen( string ) > 2 );  // Length must exceed 2
}

Il programma genera l'output seguente:

Analyzing string 'abc'
Analyzing string '(null)'
Assertion failed: string != NULL, file crt_assert.c, line 25

Dopo l'errore di asserzione, a seconda della versione del sistema operativo e della libreria di runtime, è possibile che venga visualizzata una finestra di messaggio che contiene elementi simili a:

A problem caused the program to stop working correctly. Windows will close the program and notify you if a solution is available.

Se è installato un debugger, scegliere Debug per avviare il debugger oppure Chiudi programma per uscire.

Vedi anche

Gestione errori
Processo e controllo dell'ambiente
abort
raise
signal
_ASSERT, _ASSERTE, _ASSERT_EXPR macro
_DEBUG