The function ULong2Long converts an unsigned long value into
a signed long, effectively inverting the standard C++ cast from
signed long to unsigned long. Note that applying a
static_cast might not produce the desired result -- officially
the outcome is "implementation defined".
There are three different implementations. The choice between them
is determined by the value of the CPP symbol COCOA_ULONG2LONG;
a suitable value for this symbol is found by a script called by the
configure script. That script selects the simplest implementation
which works (on certain test cases). Note that C++ explicitly forbids
the use of reinterpret_cast on built-in integral types, but the
trick of applying to a reference seems to work (it was suggested to
me by Chris Jefferson).
An earlier version of this function was in utils.H, but it turned
out to be simpler to place it by itself in a separate header file
(because the ULong2Long.H includes no further headers, so the test
compilations made by the script cpp-flags-ulong2long.sh are simpler
and safer).
Everything is in the header file; there is no ULong2Long.C file.
The fully portable definition is long and slow -- this seems to be a problem of the C++ standard.
2011