      utils
      Copyright (c)  2006,2014 John Abbott
      GNU Free Documentation License, Version 1.2
%!includeconf: ../aux-txt2tags/config.t2t
      TeXTitle{utils}{John Abbott}



== User documentation for file utils.H ==
%======================================================================

This file defines a few very basic functions which I feel should
really be part of the standard C++.  Nevertheless I have placed all
definitions inside the namespace ``CoCoA``.  Here is a summary:

- ``DeleteObject`` -- struct useful when using the C++ standard
  library containers to hold plain pointers to data they own.  I took
  it from Scott Meyers's book "More Effective STL".

- ``cmp(a,b)`` -- template function which conducts a three-way comparison of
  its two arguments: returns
        ``-1`` if ``a<b``,  ``0`` if ``a==b``,  ``1`` if ``a>b``
    (you can think of cmp(a,b) = sgn(a-b)).

- ``ULongDiff(hi,lo)`` -- computes ``hi-lo`` as **unsigned long** (assumes ``hi>=lo``)

- ``LongRange(lo,hi)`` -- returns a ``vector<long>`` filled with ``lo,lo+1,...,hi`` (useful for ``submat``)

- ``MaxSquarableInteger<T>()`` -- returns largest integer whose square fits in type ``T``

- ``LexCmp3(a,b)`` -- template function which conducts a three-way lex
  comparison of two sequences (specified by start/end iterators).
  The call LexCmp3(StartA, EndA, StartB, EndB) gives the result
  -1, 0, or 1 according as sequence A is lexicographically before
  sequence B, equal to sequence B, or after sequence B.

- ``len(v)`` -- same as ``v.size()`` except that result is ``long``
             rather than ``size_t``
-

== Maintainer documentation for files utils.H ==
%======================================================================

Everything is in ``utils.H``;
the functions are all so simple that they can be implemented inline.

The type ``int`` seemed the most natural choice for the return value of the
three-way comparison functions (though ``signed char`` would be big enough).
The implementation assumes that ``operator<`` is defined; this decision was
inspired by assumptions made by various STL functions.  The types of the
arguments may be different as this is probably be more convenient for the
user.  Obviously the generic definition given here can be overridden by
more efficient specific definitions for certain argument types.


Impl of template fn ``MaxSquarableInteger`` uses GMP to compute the
memorized values.  A table of constants would be faster but potentially
less portable (given that CoCoALib requires GMP anyway).  I haven't yet
found a neat way of ensuring that the type ``T`` is integral & bounded.



== Bugs, Shortcomings and other ideas ==
%======================================================================

Should the template function ``cmp`` require its args to be exactly the same type?

A possibly better idea for ``MaxSquarableInteger``: precompute 2^63*sqrt(2) as
``unsigned long``, then simply right shift this value for integral types with
less than 127 bits.  This suggestion presupposes a binary computer.
