LWG Issue #387 -- std::complex
preamble: The C++ Library Working Group is currently revising the
definition of std::complex. As time has progressed, Issue #387 has
fixed some problems and reintroduced others. Hopefully this post will
generate the discussion needed to obtain a widely-usable API.
Thanks,
Daniel Herring
dnuntius@gmail.com
Over the past few years LWG Issue #387 has dealt with two major issues.
In its earliest form, it improved C++ access to the real and imaginary
components of std::complex. In its current form, this issue mostly
addresses the data layout required for binary compatibility with C,
leaving a somewhat messy C++ interface.
C compatibility requires a strict layout of the std::complex class; the
current wording specifies that complex<T> must be reinterpret_cast
equivalent to T[2]. This neatly solves the C compatibility issue.
However, it does not fully address the C++ interface, nor does it
provide a testable condition for users to ensure that their compiler
fully supports the new API.
The current version of the issue [link 1] presents a "proposed API":
std::complex<T> z; reinterpret_cast<cv T(&)[2]>(z);
T real() const;
void real(T val);
T imag() const;
void imag(T val);
Another version of the issue [link 2] presented an older API:
T & real();
T & imag();
This return-by-reference has a distinct advantage over the set-by-value:
temporaries can be avoided.
e.g.
complex<float> z;
float tmp;
get_something(tmp);
z.real(tmp);
versus
complex<float> z;
get_something(z.real());
The proposed API leaves two situations which force user code to use
reinterpret_cast. The first is to pass an individual component by
reference and the second is to pass the complex as an array.
e.g.
T & lreal(complex<T> &z) { return reinterpret_cast<T(&)[2]>(z); }
and
extern "C" void f(T (&z)[2]);
f(reinterpret_cast<T(&)[2]>(z));
These situations frequently appear in code for language bindings, I/O,
byte-swapping, and hardware vectorization.
As for testability, it is important that the end-user be able to
implement automated tests (a la autoconf) to determine whether a
compiler supports a new feature. The return-by-reference presented in
the older API was easily testable; "z.real()=5" only compiles on
platforms which support it. Part of the new API is also testable;
"z.real(5)" will only compile on supporting platforms. However the
reinterpret_cast, by its nature, is not directly testable. Code
containing reinterpret_cast will compile on any C++ system; and a
sophisticated test suite would be required to run such code using magic
numbers and several data types just to be sure that the data appears to
be packed properly.
These two uses provide justification for adding the following to the
proposed C++ API.
typedef T (&array_type)[2]; // unable declare directly
in function prototype
array_type & c_array(); // similar to std::string::c_str()
const array_type & c_array() const ;
T & lreal(); // "l" for lvalue
const T & lreal() const;
T & limag();
const T & limag() const;
The names may need improvement, and return-by-reference may supersede
the getters and setters of the proposed API, but these basic methods are
required for C++ users to safely use the layout guarantee that Issue
#387 provides for compatibility with C and other languages. If they are
not implemented in the standard, then they will appear in user libraries.
Note that it is not sufficient to provide
T * c_array();
Since this discards type information which may be useful for template
expansions.
[link 1] July 22, 2008 --
http://open-std.org/JTC1/SC22/WG21/docs/lwg-defects.html#387
[link 2] (now broken) Feb 15, 2008 --
http://open-std.org/JTC1/SC22/WG21/docs/lwg-active.html#387
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.moderated. First time posters: Do this! ]