Re: [Boost-users] About naming of integer log in base 2

Subject: Re: [Boost-users] About naming of integer log in base 2
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2010-08-13 03:25:32

From: boost-users-bounces_at_[hidden] [mailto:boost-users-bounces_at_[hidden]] On Behalf Of Murilo Adriano
Vasconcelos
Sent: Friday, August 13, 2010 1:04 AM
To: boost-users_at_[hidden]
Subject: Re: [Boost-users] About naming of integer log in base 2

 

Hi Murilo

 

> and maybe you need to document some examples of using policies that don't bother to check or at least do so quietly

(your > original idea), just quietly return -1, produce a message and return -1, or message and then throw an exception.

I should have said that there is an example at   \boost_1_43_0\libs\math\example\error_policy_example.cpp

and you will also want to provide some Boost.Test style tests too - something like

BOOST_CHECK_EQUAL(ilog2(1), 1);  //  Some plain values...
...
BOOST_CHECK_EQUAL(ilog2(FFFFFFFF), 1);  //  Some cases that might cause trouble.

BOOST_CHECK_EQUAL(ilog2(std::numeric_limits<unsigned_int>::max()), 1);  //  Other cases that might cause trouble.

Cases that really will cause trouble... in this case zero.

BOOST_CHECK_EQUAL(ilog2(0), -1);  // default policy is to just return -1 (or whatever you decide for default).

BOOST_CHECK_THROW(ilog2<policy<bad_argument_error<throw_on_error> > > (0));  // policy that throws an exception for
zero.

In the math library, these tests are obscured by using macros to repeat them for many functions and policies, but you
will find many examples to help you.

Setting this up is really mind-numbingly boring but is very well worth it to provide quality assurance for the users -
Boost quality.

It will make passing a review much more likely.

 

I have added some tests:

http://svn.boost.org/svn/boost/sandbox/SOC/2010/bits_and_ints/libs/integer/test/ilog2_test.cpp

 

A good start  (though I am not clear what using the macro ILOG2_TEST really buys you.  It will be less familiar to Boost
users.  It isn't as if it saves you much typing? 

 

I haven't looked at the coverage of difficult cases but it's on the right track.  Other tests can be added as you (or
worse, other people) find bugs  (features)   ;-)

 

You might like to indicate what feature is being tested as a comment - unless it's obvious.

 

And examples: http://svn.boost.org/svn/boost/sandbox/SOC/2010/bits_and_ints/libs/integer/example/ilog2_policy_test.cpp

I'd avoid using BOOST_TEST in examples.  The policies example isn't quite the template that users can copy and paste to
get them started quickly.  (And policies appear to be a bit scary - until you realise that most of time you can just
ignore them - until you need a better error message etc.  So the example would better show at least two cases - err
silently and return -1 or whatever, and err with some informative output. ).

 

(It took a real whizz like John Maddock to devise and apply policies.  My contribution was to complain that you couldn't
do some things that reasonable users would need to!).

 

I also think it is helpful to include the output from the example as a comment.  I think it often fits nicely on the end
of the same line as the cout << ....  (Saves moving ones eye down to notes at the end (or worse running the example to
find out!).  Of course if the output is long you will need another line, or it will fit better at the end.

 

That can be found in the docs: 

http://svn.boost.org/svn/boost/sandbox/SOC/2010/bits_and_ints/libs/integer/doc/html/boost_integer/bits_and_ints.html#boo
st_integer.bits_and_ints.integer_logarithm_base_2__ilog2_function__

 Looking very smart J

 

Have fun!

 

 

I am having, thank you :)

 

J

 

Keep up the good work!

 

(I hope some people will start to use this collection 'in anger' soon?)

 

PS I noted typos for 'wich' in more than one place.

 
and legth in

Not found a string of consecutive ones with legth at least 20
 
and lots of "it's" that should be "its"
 
Only use "it's" if short for "it is" !!

---
Paul A. Bristow
Prizet Farmhouse
Kendal, UK   LA8 8AB
[phone], mobile [phone]
pbristow_at_[hidden]