[m-dev.] for review: Add new library predicate to reversibly encode two ints in a single int.

[Fergus Henderson]

On 18-Jan-2000, Peter Schachte <schachte at cs.mu.OZ.AU> wrote:
> 
> Add new library predicate to reversibly encode two ints in a single int.
> 
> Estimated hours taken: 0.5

You should swap the order of those two lines in the log message.

> +	% reversibly encode two ints in a single int.
> +	% code(Factor, Value, Residue, Coding)
> +	% holds iff Factor*Value+Residue = Coding, and 0 <= Value < Factor.
> +	% This is useful for things like converting between time as 
> +	% hours, minutes, and seconds, and raw seconds.
> +
> +:- pred code(int, int, int, int).
> +:- mode code(in, in, in, out) is det.
> +:- mode code(in, out, out, in) is det.

I suggest making that a (multi-moded) function rather than a predicate.

Also the name `code' is not very clear; I think something
like `encode_int_pair' or `encode_two_ints' would be better.

> +% XXX we really should check that 0 <= Value < Factor and raise an exception
> +% if not.  But for reasons of efficiency, we don't.

At very least that documentation should also be inlcuded with the interface
documentation, rather than being hidden in the module's implementation section.

But I think that for a standard library predicate it would probably be a
better idea to do the check.  If not doing the check is really crucial
for efficiency, then you could add another version of the predicate called
say `unchecked_<name>' which does not perform the check.

Note that if you don't do the check, then the predicate behaves
differently in the forward mode than it does in the reverse mode,
i.e. it is not pure, and so if you do call it with a value that
fails the check, then the behaviour is undefined, i.e. the
Mercury implementation is allowed to dump core (or worse), rather than
computing the value that you might expect.

> +:- pragma c_code(code(Factor::in, Value::in, Residue::in, Coding::out),
> +		 will_not_call_mercury, "
> +	Coding = Factor * Residue + Value;
> +").

The documentation says Coding = Factor * Value + Residue,
but the code says Coding = Factor * Residue + Value.
One of these must be wrong.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>  |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3        |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------