| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" |
| "http://www.w3.org/TR/html4/loose.dtd"> |
| |
| <html> |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| <link rel="stylesheet" type="text/css" href="../../../../boost.css"> |
| |
| <title>Checking policies</title> |
| </head> |
| |
| <body> |
| <h1>Checking policies</h1> |
| |
| <p>A checking policy controls how the <code>interval</code> class will deal |
| with special cases like: empty intervals, infinite numbers, invalid |
| values.</p> |
| |
| <p>For example, let's consider <code>operator+(interval, T)</code>. The |
| second argument could be an invalid value (for a floating-point number, it |
| is a NaN). What to do in such a case? First, we could say that the second |
| argument can never be an invalid number. Second, we could also say such a |
| situation can arise but is forbidden. Third, we could allow such values and |
| generate an empty interval when encountered. And there is many other |
| possibilities.</p> |
| |
| <p>It is the reason why such a policy is used: there is a lot of |
| interesting behaviors and it would be sad to arbitrarily select one of |
| these.</p> |
| |
| <h2>Requirements</h2> |
| |
| <p>The checking class should satisfy the following requirement (in the form |
| of an interface):</p> |
| <pre> |
| /* requirements for checking policy */ |
| struct checking |
| { |
| static T pos_inf(); |
| static T neg_inf(); |
| static T nan(); |
| static bool is_nan(const T&); |
| static T empty_lower(); |
| static T empty_upper(); |
| static bool is_empty(const T&, const T&); |
| }; |
| </pre> |
| |
| <p>The first two functions, <code>pos_inf</code> and <code>neg_inf</code>, |
| are invoked each time the library has to create the infinite bound of an |
| interval. For example, <code>interval::whole</code> computes |
| <code>interval(checking::neg_inf(), checking::pos_inf())</code>. If |
| infinite values are allowed and |
| <code>std::numeric_limits<T>::infinity()</code> returns a correct |
| value, such a value can be used.</p> |
| |
| <p>Next comes <code>nan</code>. This function is used each time a function |
| need to return a value of type <code>T</code> but is unable to compute it. |
| It only happens when one of the arguments of the function is invalid. For |
| example, if you ask what the median value of an empty interval is, |
| <code>nan</code> will be used. But please remember: <code>lower</code> and |
| <code>upper</code> directly return the value stocked in the interval; so, |
| if the interval is empty, <code>lower</code> will not answer |
| <code>by</code> a call to <code>checking::nan</code> (but will return the |
| same value than <code>checking::empty_lower</code> could return).</p> |
| |
| <p><code>empty_lower</code> and <code>empty_upper</code> respectively |
| return the lower and upper bound of the empty interval. There is no |
| requirements for <code>empty_lower</code> and <code>empty_upper</code> to |
| return the same value than <code>checking::nan</code>. For example, if the |
| type <code>T</code> does not have any invalid value, the |
| <code>empty_</code> functions can return the [1;0] interval.</p> |
| |
| <p><code>is_nan</code> is used to test if a value of type <code>T</code> is |
| invalid or not. <code>is_empty</code> tests if the interval formed by the |
| two arguments is empty or not. Such tests will generally be at the |
| beginning of each function which involves an argument of type |
| <code>T</code>. If one of the inputs is declared invalid, the the function |
| will try to produce an invalid value or an input interval.</p> |
| |
| <h2>Synopsis</h2> |
| <pre> |
| namespace boost { |
| namespace numeric { |
| namespace interval_lib { |
| |
| template<class T> |
| struct checking_base; |
| template<class T, class Checking = checking_base<T>, class Exception = exception_create_empty<T> > |
| struct checking_no_empty; |
| template<class T, class Checking = checking_base<T> > |
| struct checking_no_nan; |
| template<class T, class Checking = checking_base<T>, class Exception = exception_invalid_number<T> > |
| struct checking_catch_nan; |
| |
| template<class T> struct exception_create_empty { T operator()(); }; |
| template<class T> struct exception_invalid_number { void operator()(); }; |
| |
| } // namespace numeric |
| } // namespace interval_lib |
| } // namespace boost |
| </pre> |
| |
| <h2>Predefined classes</h2> |
| |
| <p>In order to simplify the customization of the policy, some templates are |
| already defined in the library.</p> |
| |
| <p>First of all, there is <code>checking_base</code>. Thanks to the |
| information provided by <code>std::numeric_limits<T></code>, this |
| class is able to generate a base for the policy. If <code>T</code> has |
| quiet NaNs (as said by <code>numeric_limits::has_quiet_NaN</code>), then |
| the value is used for <code>nan</code>, <code>empty_lower</code>, |
| <code>empty_upper</code>; and a basic test is used for <code>is_nan</code> |
| (it is <code>x!=x</code>). If <code>T</code> does not have quiet NaNs, then |
| <code>nan</code> is an <code>assert(false)</code>, the empty interval is |
| [1,0], and <code>is_nan</code> always return <code>false</code>. As for |
| <code>nan</code>, <code>pos_inf</code> returns |
| <code>numeric_limits::infinity()</code> if possible, or is an |
| <code>assert(false</code>) otherwise. <code>neg_inf</code> returns the |
| opposite. Finally, <code>is_empty(T l,T u)</code> is always defined by |
| <code>!(l<=u)</code>.</p> |
| |
| <p>Next comes <code>checking_no_empty</code>. Using it means that each time |
| an empty interval should be produced (by <code>empty_lower</code> and |
| <code>empty_upper</code>), the function object given by the |
| <code>Exception</code> argument of the template is invoked and the value it |
| returns is propagated. So, if <code>Exception</code> is appropriately |
| defined (for example it could throw an exception, hence the name of the |
| argument), you can be sure no empty interval will ever be created. So |
| <code>is_empty</code> will always return <code>false</code> (since there is |
| no need to test for an empty interval). And as explained before, in that |
| case we can also replace <code>nan</code> by an <code>assert(false)</code>; |
| you will be sure no invalid number will ever be produced. If this template |
| is not used, it implicitly means that all the functions can produce empty |
| intervals and they correctly deal with empty interval arguments.</p> |
| |
| <p>Finally there are <code>checking_no_nan</code> and |
| <code>checking_catch_nan</code>. The first one expresses the functions of |
| the library will never get an invalid number as argument. So |
| <code>is_nan</code> will only return <code>false</code>. The other one |
| means the arguments can be an invalid number but in that case, |
| <code>is_nan</code> will call the function object <code>Exception</code> |
| and return <code>false</code>. Indeed, this template means invalid numbers |
| should never make their way through to the body of the function. If none of |
| this two templates is used, it implicitly means that all the functions can |
| get invalid number arguments and they will correctly deal with them.</p> |
| |
| <p><code>exception_create_empty</code> throws |
| <code>std::runtime_error</code> with the message <code>"boost::interval: |
| empty interval created"</code> and <code>exception_invalid_number</code> |
| throws <code>std::invalid_argument</code> with the message |
| <code>"boost::interval: invalid number"</code>.</p> |
| |
| <h2>Customizing your own checking policy</h2> |
| |
| <p>In order to define a suitable policy, you need to correctly say what you |
| expect from your interval class. First of all, are you interested in |
| getting empty intervals at the end of a calculus? If you do not want to |
| obtain empty intervals, <code>empty_lower</code> and |
| <code>empty_upper</code> have to fail when invoked (they can throw an |
| exception, set a flag, etc). However, if no function is able to produce an |
| empty interval, it is no more necessary to do the test, so |
| <code>is_empty</code> may always return <code>false</code>. In this case, a |
| good compiler will do a lot of optimizations.</p> |
| |
| <p>You could also be interested in getting empty intervals at the end of |
| the calculus. For example, if you need to transform an array of unsure |
| values (or intervals) in a new array of intervals, you may not want to stop |
| the conversion at the first encountered problem. So |
| <code>empty_lower</code> and <code>empty_upper</code> need to return |
| suitable values in order to define an empty interval (you can use an upper |
| bound which is not greater or equal than the lower bound for example); and |
| <code>is_empty</code> must be able to distinguish empty intervals from the |
| valid intervals.</p> |
| |
| <p>Another important question is: is it possible that some base numbers |
| (objects of type <code>T</code>) are invalid? And if it is possible, are |
| they allowed or not ? If it is not possible, no test is necessary; |
| <code>is_nan</code> may always return <code>false</code>. In this case too, |
| a good compiler will do a lot of optimizations. If function arguments can |
| hold invalid numbers, two cases must be considered according to whether |
| they are allowed or not. If they are allowed, <code>is_nan</code> just has |
| to test if they are invalid or not. If they are forbidden, |
| <code>is_nan</code> should fail (exception, assert, etc.) when invoked on |
| an invalid argument and return <code>false</code> otherwise. The value |
| returned by <code>nan</code> does not have any interest since the interval |
| functions are guaranteed not to produce invalid interval bounds unless the |
| user passes invalid numbers to the constructors. So you can put an assert |
| inside if you do not trust the library. :-)</p> |
| |
| <p>And finally, you need to decide what to do with <code>nan</code> if it |
| has not already been decided at the beginning, and with |
| <code>pos_inf</code> and <code>neg_inf</code>. These functions should |
| return a value or start an exceptional behavior (especially if the base |
| type does not have corresponding values).</p> |
| |
| <h2>Some examples</h2> |
| |
| <ul> |
| <li>If you need a checking policy that allows the library to correctly |
| manipulate data, even if they contain invalid numbers and empty |
| intervals, then <code>checking_base<T></code> is a |
| possibility.</li> |
| |
| <li>If you do not want empty intervals to be created and are not sure all |
| the numbers are valid, then <code>checking_catch_nan<T, |
| checking_no_empty<T> ></code> can help you.</li> |
| |
| <li>If all the numbers will be valid and if no empty interval is supposed |
| to be created (or if you do not want them to be created), then you can |
| use <code>checking_no_nan<T, checking_no_empty<T> ></code>. |
| Please note that if <code>T</code> does not have a way to represent |
| invalid numbers, then this policy will behave the same way as |
| <code>checking_no_empty<T></code>. This is the default policy and |
| it is also called <code>interval_lib::checking_strict</code>.</li> |
| |
| <li>If all numerical data are valid but the algorithm can produce and |
| manipulate empty intervals, then <code>checking_no_nan<T></code> |
| should be used.</li> |
| |
| <li>Similarly, if invalid data have to be signaled and the algorithm can |
| manipulate empty intervals, the <code>checking_catch_nan<T></code> |
| is a solution.</li> |
| |
| <li>If you do not mind having undefined results when an empty interval or |
| an interval number is produced, your best bet is to create your own |
| policy by overloading <code>checking_base</code> and modifying |
| <code>is_nan</code> et <code>is_empty</code> in order for them to always |
| return <code>false</code>. It is probably the fastest checking policy |
| available; however, it suffers from its deficient security.</li> |
| </ul> |
| <hr> |
| |
| <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src= |
| "../../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional" |
| height="31" width="88"></a></p> |
| |
| <p>Revised |
| <!--webbot bot="Timestamp" s-type="EDITED" s-format="%Y-%m-%d" startspan -->2006-12-24<!--webbot bot="Timestamp" endspan i-checksum="12172" --></p> |
| |
| <p><i>Copyright © 2002 Guillaume Melquiond, Sylvain Pion, Hervé |
| Brönnimann, Polytechnic University<br> |
| Copyright © 2003-2004 Guillaume Melquiond</i></p> |
| |
| <p><i>Distributed under the Boost Software License, Version 1.0. (See |
| accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> |
| or copy at <a href= |
| "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p> |
| </body> |
| </html> |