Re: [boost] Rational documentation

From: David Abrahams (abrahams_at_[hidden])
Date: 2000-10-18 10:19:21

----- Original Message -----
From: "Moore, Paul" <paul.moore_at_[hidden]>

> From: David Abrahams [mailto:abrahams_at_[hidden]]
> > I was just trying to use boost::rational<>
> > to test out new support for numeric types in
> > py_cpp, and I'm finding the documentation
> > missing quite a lot of important info. For
> > example, what are the constructors? How do you
> > access the numerator and denominator? I think
> > what's missing here is basically a table which
> > describes everything in the interface.
>
> The information is there, but I'd agree it's a bit non-obvious.
>
> <quote>
> Rationals can be constructed from a pair (numerator, denominator) of
> integers, or a single integer. There is also a default constructor, which
> initialises the rational to a value of zero.
>
> The single-argument constructor is not declared as explicit, so there is
an
> implicit conversion from the underlying integer type to the rational type.
> </quote>
>
> <quote>
> Finally, access to the internal representation of rationals is provided by
> the two member functions numerator() and denominator().
> </quote>

Thanks. I guess all I've proven is that you can't find this stuff out at a
glance. Maybe it still warrants an update?

> It's in the section "Interface" near the bottom. BTW, I refer to the
> numerator() and denominator() functionas as "access to the internal
> representation". The reason for this is that a num/den representation has
> some odd properties at the boundaries when used with a limited-precision
> integer type. I am reserving the right to change the internal
> representation. This gives rise to a question - is there any real-world
need
> to access the numerator or denominator of a rational number, in general?

Yeah! What if I want to print the number? I think without access to the rep
it is essentially a write-only medium. Kind of like a "data motel" (see
below).

Also, suppose I want to convert the number to a double? Is there a way to do
that?

> (And if so, should there be a normalisation guarantee? At present the
> results are normalised, but that's not necessary...)

I think that when we get to the stage of wanting a rational number that
isn't neccessarily normalized, we'll want to parametrize the type to allow
either behavior. So long as we're not (yet) overgeneralizing this class into
oblivion, I would prefer that we make maximal explicit guarantees.

> I may look at rewording this section of the documentation. Any suggestions
> would be gratefully received.

A simple table would probably help.

data-check-in-but-they-don't-check-out-ly y'rs,
dave