Re: [boost] [safe_numerics] Review Part 1 (Documentation)

Subject: Re: [boost] [safe_numerics] Review Part 1 (Documentation)
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2017-03-03 00:49:02

AMDG

On 03/02/2017 03:47 PM, Robert Ramey via Boost wrote:
> On 3/2/17 12:12 PM, Steven Watanabe via Boost wrote:
>> <snip>
>>
>> The include paths used in the documentation are a mess.
>> I see at least 6 different variations:
>> - <snip>
> 
> Hmmm - where - in the documentation? In the examples? or?.
> 

  This was just from reading the html documentation.
the code taken from example/ constently uses ../include/
(probably because it was actually tested and
this variation is one that works).
The reference sections under Type Requirements and
Types have the most variations such as:

Header
#include <safe/numeric/safe_literal.hpp>

Header
#include <boost/safe_numerics/safe_integer.hpp>

>>
>> In boostbook, <code language="c++"> enables C++
>> syntax highlighting for code snippets.  (This is
>> enabled by default for programlisting, but <code>
>> is used for non-C++ content enough that it needs
>> to be specified.)
> Hmmm - right now I'm using program listing and it looks good - syntax is
> colorized.  For inline I'm using <code ...> without the language.  Are
> you suggesting that I change the inline to <code language="c++" ... ?
> 

  Yes.  This is just a minor stylistic detail.
The only real difference is that it will change
the color of int in inline code.

> <snip>
> 
>> "However, it would be very surprising if any implementation were to be
>> more complex that O(0);"
>> I think you mean O(1).  O(0) means that it takes no time at all.
> Hmm - to me O(0) is fixed time while O(1) is time proportional to x^1.
> But I'll rephrase the O() notation which is confusing in this context.
> 

The formal definition of O() is
f(x) \in O(g(x)) iff. \exists C, x_0: \forall x > x_0: |f(x)| <= |Cg(x)|

If g(x) = 0, then this reduces to
\exists x_0 \forall x > x_0: f(x) = 0
i.e. the running time is zero.

If g(x) = 1, then we have
\exists x_0 \forall x > x_0: |f(x)| <= |C|
meaning that the running time is less than
some constant, regardless of the value of x.
...which brings us to the real problem with
using big-O here: what is x?  For sequence
algorithms, x is the length of the sequence,
but there's nothing like that here.

>> <snip>
>> What happens for binary operators when the arguments
>> have different promotion policies?  Is it an error?
>> Does the implementation randomly pick one?  Is there
>> some kind of precedence rule for promotion policies?
>> (Note: the same thing applies to exception policies)
> 
> In both cases:
>     at least one policy must be non void
>     if both are non void they must be equal
> 
> I'll clarify this.
> 

Err, what is a void policy?

>> <snip>
>> "EP::underflow_error(const char * message)"
>> Underflow is a floating point error that happens
>> when the value is too close to 0.  (INT_MIN - 1)
>> is an overflow error, not an underflow error.
> 
> Right.  There is no underflow error thrown in the current code.

I found one use (probably accidental) at checked.hpp:410.

> <snip>
> 
>> Also, safe is defined in safe_integer.hpp which is not #included.
> 
> this is included by safe_range.hpp.  But I agree that if I use
> safe<..> I should include safe_integer.hpp even though it's
> redundent.

safe_range.hpp only includes safe_base.hpp.
The only reason I noticed this was that
Intellisense highlighted safe as undefined.

> 
>> <snip>
>> promotion_policies/cpp.html
>>
>> Unless I'm misunderstanding something, the use
>> of trap_exception will fail to compile at:
>> d *= velocity;
> 
> <snip>
> 
> ....  I guess this illustrates the impossibility
> for normal people to actually write demonstrably correct code.
> 

Tell me about it:
https://github.com/boostorg/random/blob/develop/include/boost/random/uniform_int_distribution.hpp#L93

> <snip>
> 
> Ahhh - finally I see your point.  assignment using d as
> an accumuator loses the range calculated at compile time
> so subsequent operations can't be guaranteed to not
> overflow.
> 

Yeah.  This makes it a bit inconvenient to use
trap_exception with anything other than a strict
functional style.

In Christ,
Steven Watanabe