[/
 / Copyright (c) 2003 Boost.Test contributors 
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]


[section:custom_predicates Custom predicate support]

[def __class_predicate_result__ [classref boost::test_tools::predicate_result]]

Even though supplied testing tools cover wide range of possible checks and provide detailed report on cause of error in
some cases you may want to implement and use custom predicate that perform complex check and produce intelligent report
on failure. To satisfy this need testing tools implement custom predicate support. There two layers of custom predicate
support implemented by testing tools toolbox: with and without custom error message generation.

The first layer is supported by __BOOST_LEVEL_PREDICATE__ family of testing tools. You can use it to check any custom
predicate that reports the result as boolean value. The values of the predicate arguments are reported by the tool
automatically in case of failure.


[bt_example example30..Custom predicate support using __BOOST_LEVEL_PREDICATE__..run-fail]

To use second layer your predicate has to return __class_predicate_result__.

This class encapsulates boolean result value along with any error or information message you opt to report.

Usually you construct the instance of class __class_predicate_result__ inside your predicate function and return it by
value. The constructor expects one argument - the boolean result value. The constructor is implicit, so you can simply
return boolean value from your predicate and __class_predicate_result__ is constructed automatically to hold your value
and empty message. You can also assign boolean value to the constructed instance. You can check the current predicate
value by using `operator!` or directly accessing public read-only property `p_predicate_value`. The error message is
stored in public read-write property `p_message`.


[bt_example example31..Custom predicate support using class __class_predicate_result__..run-fail]

[endsect] [/predicate]
