moreassert.h

/**
 * copyright 2002-2004 Bryce "Zooko" Wilcox-O'Hearn
 * mailto:zooko@zooko.com
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software to deal in this software without restriction (including the
 * rights to use, modify, distribute, sublicense, and/or sell copies) provided
 * that the above copyright notice and this permission notice is included in
 * all copies or substantial portions of this software. THIS SOFTWARE IS
 * PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.
 */

#ifndef __INCL_moreassert_h
#define __INCL_moreassert_h

/* implementation stuff that you needn't see in order to use the library */
#include "moreassertimp.h"

/**
 * A verbose abort message contains the file name, line number, function name, 
 * and a description string, like this:
 * test.c:238: test_minmax_strict: This string describes what went wrong.
 *
 * Use verbose_abort as though it is defined like this (although in reality it 
 * is a macro instead of a function):
 *
 * void verbose_abort(const char* msg);
 * void verbose_abort2(const char* msg1, const char* msg2);
 * void verbose_abort3(const char* msg1, const char* msg2, const char* msg3);
 * ... etc up to verbose_abort8()
 *
 * runtime_assert2 processes the msg arguments in the following simple way: 
 * first it treats any NULL pointers as empty strings, second it concatenates 
 * all the msg arguments together.  It does not do any other interpolation or 
 * processing of their contents.
 */

/**
 * runtime_assert() gets checked even if NDEBUG is set.
 *
 * A typical use of runtime_assert() is to test input and exit if the input 
 * isn't correct.  You shouldn't use normal assert() for this, because you 
 * ought to test the input even if the program was compiled with the NDEBUG 
 * flag.
 *
 * Use runtime_assert as though it is defined like this (although in reality it 
 * is a macro instead of a function):
 * void runtime_assert(int condition, const char* msg);
 * void runtime_assert2(int condition, const char* msg1, const char* msg2);
 * void runtime_assert3(int condition, const char* msg1, const char* msg2, const char* msg3);
 * void runtime_assert4(int condition, const char* msg1, const char* msg2, const char* msg3, const char* msg4);
 *
 * Sometimes it can be useful to have two error messages, especially if one of 
 * them is generated by lower-level code, like this:
 *
 * retval = somelib_frob(whatsit);
 * runtime_assert2(retval == 0, "non-zero return value from somelib_frob(). somelib error message: ", somelib_geterrmsg());
 *
 * runtime_assert2 processes the msg arguments in the following simple way: 
 * first it treats any NULL pointers as empty strings, second it concatenates 
 * all the msg arguments together, inserting a separator string ("; ") between 
 * each successive pair of msgs.  It does not do any other interpolation or 
 * processing of their contents.
 */

#endif /* #ifndef __INCL_moreassert_h */