assert macro, _assert, _wassert

Avalia uma expressão e, quando o resultado é false, imprime uma mensagem de diagnóstico e anula o programa.

Sintaxe

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

Parâmetros

expression
Uma expressão escalar (incluindo expressões de ponteiro) avaliada como não zero (true) ou 0 (false).

message
A mensagem a ser exibida.

filename
O nome do arquivo de origem no qual a declaração falhou.

line
O número de linha no arquivo de origem da declaração com falha.

Comentários

A macro assert normalmente é usada para identificar erros de lógica durante o desenvolvimento do programa. Use-a para interromper a execução do programa quando ocorrerem condições inesperadas implementando o argumento expression para avaliá-la como false apenas quando o programa estiver funcionando incorretamente. As verificações de declaração podem ser desativadas no tempo de compilação definindo a macro NDEBUG. Você pode desativar a macro assert sem modificar os arquivos de origem usando uma opção de linha de comando /DNDEBUG. Você pode desativar a macro assert em seu código-fonte usando uma diretiva #define NDEBUG antes de <assert.h> ser incluída.

A macro assert imprime uma mensagem de diagnóstico quando expression é avaliada como false (0) e chama abort para interromper a execução do programa. Nenhuma ação será executada se expression for true (diferente de zero). A mensagem de diagnóstico inclui a expressão com falha, o nome do número de arquivo e o número de linha em que a declaração falhou.

A mensagem de diagnóstico é impressa em caracteres largos (wchar_t). Assim, ela funcionará conforme o esperado, mesmo que haja caracteres Unicode na expressão.

O destino da mensagem de diagnóstico depende do tipo de aplicativo que chamou a rotina. Aplicativos de console recebem a mensagem por meio de stderr. Em um aplicativo baseado no Windows, assert chama a função MessageBox do Windows para criar uma caixa de mensagem para exibir a mensagem junto com três botões: Anular, Repetir e Ignorar. Se o usuário escolher Abortar, o programa será anulado imediatamente. Se o usuário escolher Repetir, o depurador será chamado e o usuário poderá depurar o programa se a depuração JIT (just-in-time) estiver habilitada. Se o usuário escolher Ignorar, o programa continuará com a execução normal. O clique em Ignorar quando existe uma condição de erro poderá resultar em um comportamento indefinido, já que as pré-condições do código de chamada não foram atendidas.

Para substituir o comportamento de saída padrão, independentemente do tipo de aplicativo, chame _set_error_mode para selecionar entre os comportamentos de saída no stderr e exibir caixa de diálogo.

Depois que assert exibe a mensagem, ele chama abort, que exibe uma caixa de diálogo com botões Anular, Repetir e Ignorar. abort sai do programa para que os botões Repetir e Ignorar não retomem a execução do programa após a chamada assert. Se assert exibia uma caixa de diálogo, a caixa de diálogo abort não será mostrada. A única vez que a abort caixa de diálogo é mostrada é quando assert envia sua saída para stderr.

Como consequência do comportamento acima, uma caixa de diálogo sempre é exibida após uma chamada assert no modo de depuração. O comportamento de cada botão é capturado na tabela abaixo.

Modo de erro	Saída no stderr (Console/_OUT_TO_STDERR)	Exibir Caixa de diálogo (Windows/_OUT_TO_MSGBOX)
Abort	Sair imediatamente com o código de saída 3	Sair imediatamente com o código de saída 3
Retry	Invadir o depurador durante abort	Invadir o depurador durante assert
Ignore	Concluir a saída via abort	Continuar o programa como se assert não tivesse disparado (pode resultar em comportamento indefinido, pois as pré-condições do código de chamada não foram atendidas)

Para obter mais informações sobre a depuração de CRT, consulte Técnicas de depuração de CRT.

As funções _assert e _wassert são funções CRT internas. Elas ajudam a minimizar o código necessário em seus arquivos de objeto para dar suporte a declarações. Não recomendamos chamar essas funções diretamente.

A macro assert está habilitada nas versões de lançamento e depuração das bibliotecas de tempo de execução do C quando NDEBUG não está definido. Quando NDEBUG é definido, a macro está disponível, mas não avalia seu argumento e não tem efeito. Quando é habilitada, a macro assert chama _wassert para sua implementação. Outras macros de declaração, _ASSERT, _ASSERTE e _ASSERT_EXPR, também estão disponíveis, mas somente avaliarão as expressões passadas a elas quando a macro _DEBUG tiver sido definida e quando estiverem em um código vinculado à versão de depuração das bibliotecas de tempo de execução do C.

Requisitos

Rotina	Cabeçalho necessário
assert, _wassert	<assert.h>

A assinatura da função _assert não está disponível em um arquivo de cabeçalho. A assinatura da função _wassert está disponível somente quando a macro NDEBUG não está definida.

Exemplo

Neste programa, a função analyze_string usa a macro assert para testar várias condições relacionadas à cadeia de caracteres e ao comprimento. Se qualquer uma das condições falhar, o programa imprimirá uma mensagem indicando o que causou a falha.

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

O programa gera esta saída:

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

Após a falha de declaração, dependendo da versão do sistema operacional e da biblioteca de runtime, você poderá ver uma caixa de mensagem que contém algo semelhante a:

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

Se um depurador estiver instalado, escolha o botão Depurar para iniciar o depurador ou Fechar programa para sair.

Confira também

Tratamento de erros
Controle de processo e ambiente
abort
raise
signal
Macros _ASSERT, _ASSERTE, _ASSERT_EXPR
_DEBUG