Removed non-Defensive Coding Guide bits and promoted source to root
This commit is contained in:
Eric Christensen
parent
9eb72b454b
commit
9dc8a003e5
402 changed files with 0 additions and 2049 deletions
202
en-US/CXX-Std.xml
Normal file
202
en-US/CXX-Std.xml
Normal file
|
|
@ -0,0 +1,202 @@
|
|||
<?xml version='1.0' encoding='utf-8' ?>
|
||||
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||||
]>
|
||||
<section id="sect-Defensive_Coding-CXX-Std">
|
||||
<title>The C++ standard library</title>
|
||||
<para>
|
||||
The C++ standard library includes most of its C counterpart
|
||||
by reference, see <xref linkend="sect-Defensive_Coding-C-Libc"/>.
|
||||
</para>
|
||||
<section id="sect-Defensive_Coding-CXX-Std-Functions">
|
||||
<title>Functions that are difficult to use</title>
|
||||
<para>
|
||||
This section collects functions and function templates which are
|
||||
part of the standard library and are difficult to use.
|
||||
</para>
|
||||
<section id="sect-Defensive_Coding-CXX-Std-Functions-Unpaired_Iterators">
|
||||
<title>Unpaired iterators</title>
|
||||
<para>
|
||||
Functions which use output operators or iterators which do not
|
||||
come in pairs (denoting ranges) cannot perform iterator range
|
||||
checking.
|
||||
(See <xref linkend="sect-Defensive_Coding-CXX-Std-Iterators"/>)
|
||||
Function templates which involve output iterators are
|
||||
particularly dangerous:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem><para><function>std::copy</function></para></listitem>
|
||||
<listitem><para><function>std::copy_backward</function></para></listitem>
|
||||
<listitem><para><function>std::copy_if</function></para></listitem>
|
||||
<listitem><para><function>std::move</function> (three-argument variant)</para></listitem>
|
||||
<listitem><para><function>std::move_backward</function></para></listitem>
|
||||
<listitem><para><function>std::partition_copy_if</function></para></listitem>
|
||||
<listitem><para><function>std::remove_copy</function></para></listitem>
|
||||
<listitem><para><function>std::remove_copy_if</function></para></listitem>
|
||||
<listitem><para><function>std::replace_copy</function></para></listitem>
|
||||
<listitem><para><function>std::replace_copy_if</function></para></listitem>
|
||||
<listitem><para><function>std::swap_ranges</function></para></listitem>
|
||||
<listitem><para><function>std::transform</function></para></listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
In addition, <function>std::copy_n</function>,
|
||||
<function>std::fill_n</function> and
|
||||
<function>std::generate_n</function> do not perform iterator
|
||||
checking, either, but there is an explicit count which has to be
|
||||
supplied by the caller, as opposed to an implicit length
|
||||
indicator in the form of a pair of forward iterators.
|
||||
</para>
|
||||
<para>
|
||||
These output-iterator-expecting functions should only be used
|
||||
with unlimited-range output iterators, such as iterators
|
||||
obtained with the <function>std::back_inserter</function>
|
||||
function.
|
||||
</para>
|
||||
<para>
|
||||
Other functions use single input or forward iterators, which can
|
||||
read beyond the end of the input range if the caller is not careful:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem><para><function>std::equal</function></para></listitem>
|
||||
<listitem><para><function>std::is_permutation</function></para></listitem>
|
||||
<listitem><para><function>std::mismatch</function></para></listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
</section>
|
||||
<section id="sect-Defensive_Coding-CXX-Std-String">
|
||||
<title>String handling with <literal>std::string</literal></title>
|
||||
<para>
|
||||
The <literal>std::string</literal> class provides a convenient
|
||||
way to handle strings. Unlike C strings,
|
||||
<literal>std::string</literal> objects have an explicit length
|
||||
(and can contain embedded NUL characters), and storage for its
|
||||
characters is managed automatically. This section discusses
|
||||
<literal>std::string</literal>, but these observations also
|
||||
apply to other instances of the
|
||||
<literal>std::basic_string</literal> template.
|
||||
</para>
|
||||
<para>
|
||||
The pointer returned by the <function>data()</function> member
|
||||
function does not necessarily point to a NUL-terminated string.
|
||||
To obtain a C-compatible string pointer, use
|
||||
<function>c_str()</function> instead, which adds the NUL
|
||||
terminator.
|
||||
</para>
|
||||
<para>
|
||||
The pointers returned by the <function>data()</function> and
|
||||
<function>c_str()</function> functions and iterators are only
|
||||
valid until certain events happen. It is required that the
|
||||
exact <literal>std::string</literal> object still exists (even
|
||||
if it was initially created as a copy of another string object).
|
||||
Pointers and iterators are also invalidated when non-const
|
||||
member functions are called, or functions with a non-const
|
||||
reference parameter. The behavior of the GCC implementation
|
||||
deviates from that required by the C++ standard if multiple
|
||||
threads are present. In general, only the first call to a
|
||||
non-const member function after a structural modification of the
|
||||
string (such as appending a character) is invalidating, but this
|
||||
also applies to member function such as the non-const version of
|
||||
<function>begin()</function>, in violation of the C++ standard.
|
||||
</para>
|
||||
<para>
|
||||
Particular care is necessary when invoking the
|
||||
<function>c_str()</function> member function on a temporary
|
||||
object. This is convenient for calling C functions, but the
|
||||
pointer will turn invalid as soon as the temporary object is
|
||||
destroyed, which generally happens when the outermost expression
|
||||
enclosing the expression on which <function>c_str()</function>
|
||||
is called completes evaluation. Passing the result of
|
||||
<function>c_str()</function> to a function which does not store
|
||||
or otherwise leak that pointer is safe, though.
|
||||
</para>
|
||||
<para>
|
||||
Like with <literal>std::vector</literal> and
|
||||
<literal>std::array</literal>, subscribing with
|
||||
<literal>operator[]</literal> does not perform bounds checks.
|
||||
Use the <function>at(size_type)</function> member function
|
||||
instead. See <xref
|
||||
linkend="sect-Defensive_Coding-CXX-Std-Subscript"/>.
|
||||
Furthermore, accessing the terminating NUL character using
|
||||
<literal>operator[]</literal> is not possible. (In some
|
||||
implementations, the <literal>c_str()</literal> member function
|
||||
writes the NUL character on demand.)
|
||||
</para>
|
||||
<para>
|
||||
Never write to the pointers returned by
|
||||
<function>data()</function> or <function>c_str()</function>
|
||||
after casting away <literal>const</literal>. If you need a
|
||||
C-style writable string, use a
|
||||
<literal>std::vector<char></literal> object and its
|
||||
<function>data()</function> member function. In this case, you
|
||||
have to explicitly add the terminating NUL character.
|
||||
</para>
|
||||
<para>
|
||||
GCC's implementation of <literal>std::string</literal> is
|
||||
currently based on reference counting. It is expected that a
|
||||
future version will remove the reference counting, due to
|
||||
performance and conformance issues. As a result, code that
|
||||
implicitly assumes sharing by holding to pointers or iterators
|
||||
for too long will break, resulting in run-time crashes or worse.
|
||||
On the other hand, non-const iterator-returning functions will
|
||||
no longer give other threads an opportunity for invalidating
|
||||
existing iterators and pointers because iterator invalidation
|
||||
does not depend on sharing of the internal character array
|
||||
object anymore.
|
||||
</para>
|
||||
</section>
|
||||
<section id="sect-Defensive_Coding-CXX-Std-Subscript">
|
||||
<title>Containers and <literal>operator[]</literal></title>
|
||||
<para>
|
||||
Many sequence containers similar to <literal>std::vector</literal>
|
||||
provide both <literal>operator[](size_type)</literal> and a
|
||||
member function <literal>at(size_type)</literal>. This applies
|
||||
to <literal>std::vector</literal> itself,
|
||||
<literal>std::array</literal>, <literal>std::string</literal>
|
||||
and other instances of <literal>std::basic_string</literal>.
|
||||
</para>
|
||||
<para>
|
||||
<literal>operator[](size_type)</literal> is not required by the
|
||||
standard to perform bounds checking (and the implementation in
|
||||
GCC does not). In contrast, <literal>at(size_type)</literal>
|
||||
must perform such a check. Therefore, in code which is not
|
||||
performance-critical, you should prefer
|
||||
<literal>at(size_type)</literal> over
|
||||
<literal>operator[](size_type)</literal>, even though it is
|
||||
slightly more verbose.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>front()</literal> and <literal>back()</literal>
|
||||
member functions are undefined if a vector object is empty. You
|
||||
can use <literal>vec.at(0)</literal> and
|
||||
<literal>vec.at(vec.size() - 1)</literal> as checked
|
||||
replacements. For an empty vector, <literal>data()</literal> is
|
||||
defined; it returns an arbitrary pointer, but not necessarily
|
||||
the NULL pointer.
|
||||
</para>
|
||||
</section>
|
||||
<section id="sect-Defensive_Coding-CXX-Std-Iterators">
|
||||
<title>Iterators</title>
|
||||
<para>
|
||||
Iterators do not perform any bounds checking. Therefore, all
|
||||
functions that work on iterators should accept them in pairs,
|
||||
denoting a range, and make sure that iterators are not moved
|
||||
outside that range. For forward iterators and bidirectional
|
||||
iterators, you need to check for equality before moving the
|
||||
first or last iterator in the range. For random-access
|
||||
iterators, you need to compute the difference before adding or
|
||||
subtracting an offset. It is not possible to perform the
|
||||
operation and check for an invalid operator afterwards.
|
||||
</para>
|
||||
<para>
|
||||
Output iterators cannot be compared for equality. Therefore, it
|
||||
is impossible to write code that detects that it has been
|
||||
supplied an output area that is too small, and their use should
|
||||
be avoided.
|
||||
</para>
|
||||
<para>
|
||||
These issues make some of the standard library functions
|
||||
difficult to use correctly, see <xref
|
||||
linkend="sect-Defensive_Coding-CXX-Std-Functions-Unpaired_Iterators"/>.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue