[boost] [xint] Boost.XInt formal review

Subject: [boost] [xint] Boost.XInt formal review
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-03-10 11:28:56

This is my review of the XInt library.

 >
 >          - What is your evaluation of the design?

The design looks clean and clear to me. The fact that the default 
boost::xint::integer provides immediate use of an extended integer is 
good. The fact that other classes can be created from the integer_t 
template, to change the functionality of an extended integer in various 
ways, is fine also.

I do not see the need for random number functionality in the library. It 
also appears to me that prime number generation belongs outside the library.

I think the design should be based on providing an extended integer 
which has the functionality of the C++ built-in integer types, and not 
try to have other functionality as part of the basic design. Other 
functionality for working with the extended integer outside of this core 
emulation of the C++ integer types can be presented as a separate 
library if necessary in the future.

One area that does not follow this emulation of C++ integer types which 
I would like to see is the ability to convert back and forth to floating 
point types, since one can do this with built-in integer types. It would 
be very nice if this were part of the library since converting to C++ 
integer types and then to a floating point type will fail if the 
extended integer type is too large for a C++ integer type. But the range 
of floating point types is large enough for most extended integer values.

 >          - What is your evaluation of the implementation?

I did not look at the code. In general I am not concerned with the 
implementation details of a library unless I am being asked to change 
things myself, or I see some bug or slowdown. As an end-user of a 
library I mainly concern myself with the public and protected 
functionality of any library components.

I feel in general that there is too much of an effort by reviewers to 
dictate how the internals of a library should be implemented, based on 
the reviewer's favorite ideas regarding coding. Unless there is a 
technical issue which will cause the library to not compile or run 
properly, or to compile or run much slower than need be, I do not see 
the point of such an effort to pick apart the internal implementation. 
Of course such technical areas of the internal implementation that 
causes the aforementioned problems should be critiqued.

 >          - What is your evaluation of the documentation?

The documentation presents a good first page. Things which I feel could 
be improved are:

1) Features are mentioned, but the "Detailed Usage Information" does not 
have topics which discuss all those features. I feel that each main 
feature of a library should have at least a brief discussion before 
suggesting to look in the reference.

2) Saying to look in the reference section for something more advanced 
than the basic use of instantiating and using a boost::xint::integer is 
certainly valid but I would greatly have preferred a more explanatory 
approach to what is considered "advanced" usage. Again this is similar 
to 1) in that I feel the documentation should provide as complete a 
discussion of the features, both simple and advanced, that it can. 
Furthermore what those "advanced" features are should be enumerated.

The reference section is very well done and makes using the integer 
class fairly easy to understand. However the options to integer_t are 
not easy to find in the reference section. I think that because this is 
one of the central concepts of the library, which is that creating an 
extended integer is flexible, the creation of an extended integer beyond 
the default boost::xint::integer should be its own topic.

I general I think the documentation is laid out well but should be more 
complete as far as topic explanations.

 >          - What is your evaluation of the potential usefulness of the 
library?

The potential usefulness is huge. Applications which need integer values 
beyond the maximum C++ long long values, but which do not want the 
problems of floating point number calculations, need such a library.

 >          - Did you try to use the library?  With what compiler?  Did 
you have any
 >          problems?

I have tried to use the library with VC++ 10 and gcc-4.5.2 with no problems.

 >          - How much effort did you put into your evaluation? A 
glance? A quick
 >          reading? In-depth study?

A slow reading of the documentation.

 >          - Are you knowledgeable about the problem domain?

Yes, fairly knowledgable but not an expert.

I vote to have the library accepted into Boost.

I feel that if one looks for the "perfect" extended integer library 
which meets everyone's criteria, then the search will go on forever, 
while Boost.XInt is certainly good enough in its 
functionality/design/documentation. I trust that the implementer of the 
library can work out issues in the future, and I see the library serving 
a fundamental need now.

Edward Diener