gcc/libstdc++-v3/doc/xml/manual/algorithms.xml
Jonathan Wakely 16d0b033ca libstdc++: Remove trailing whitespace from XML docs
libstdc++-v3/ChangeLog:

	* doc/xml/book.txml: Remove trailing whitespace.
	* doc/xml/chapter.txml: Likewise.
	* doc/xml/class.txml: Likewise.
	* doc/xml/gnu/fdl-1.3.xml: Likewise.
	* doc/xml/gnu/gpl-3.0.xml: Likewise.
	* doc/xml/manual/abi.xml: Likewise.
	* doc/xml/manual/algorithms.xml: Likewise.
	* doc/xml/manual/allocator.xml: Likewise.
	* doc/xml/manual/appendix_contributing.xml: Likewise.
	* doc/xml/manual/appendix_free.xml: Likewise.
	* doc/xml/manual/appendix_porting.xml: Likewise.
	* doc/xml/manual/atomics.xml: Likewise.
	* doc/xml/manual/auto_ptr.xml: Likewise.
	* doc/xml/manual/backwards_compatibility.xml: Likewise.
	* doc/xml/manual/bitmap_allocator.xml: Likewise.
	* doc/xml/manual/build_hacking.xml: Likewise.
	* doc/xml/manual/codecvt.xml: Likewise.
	* doc/xml/manual/concurrency.xml: Likewise.
	* doc/xml/manual/concurrency_extensions.xml: Likewise.
	* doc/xml/manual/configure.xml: Likewise.
	* doc/xml/manual/containers.xml: Likewise.
	* doc/xml/manual/ctype.xml: Likewise.
	* doc/xml/manual/debug.xml: Likewise.
	* doc/xml/manual/debug_mode.xml: Likewise.
	* doc/xml/manual/diagnostics.xml: Likewise.
	* doc/xml/manual/documentation_hacking.xml: Likewise.
	* doc/xml/manual/evolution.xml: Likewise.
	* doc/xml/manual/internals.xml: Likewise.
	* doc/xml/manual/intro.xml: Likewise.
	* doc/xml/manual/io.xml: Likewise.
	* doc/xml/manual/iterators.xml: Likewise.
	* doc/xml/manual/locale.xml: Likewise.
	* doc/xml/manual/localization.xml: Likewise.
	* doc/xml/manual/messages.xml: Likewise.
	* doc/xml/manual/mt_allocator.xml: Likewise.
	* doc/xml/manual/numerics.xml: Likewise.
	* doc/xml/manual/parallel_mode.xml: Likewise.
	* doc/xml/manual/policy_data_structures.xml: Likewise.
	* doc/xml/manual/prerequisites.xml: Likewise.
	* doc/xml/manual/shared_ptr.xml: Likewise.
	* doc/xml/manual/spine.xml: Likewise.
	* doc/xml/manual/status_cxxtr1.xml: Likewise.
	* doc/xml/manual/status_cxxtr24733.xml: Likewise.
	* doc/xml/manual/strings.xml: Likewise.
	* doc/xml/manual/support.xml: Likewise.
	* doc/xml/manual/test.xml: Likewise.
	* doc/xml/manual/test_policy_data_structures.xml: Likewise.
	* doc/xml/manual/using.xml: Likewise.
	* doc/xml/manual/using_exceptions.xml: Likewise.
	* doc/xml/manual/utilities.xml: Likewise.
	* doc/html/*: Regenerate.
2020-10-13 16:50:41 +01:00

96 lines
3.4 KiB
XML

<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.algorithms" xreflabel="Algorithms">
<?dbhtml filename="algorithms.html"?>
<info><title>
Algorithms
<indexterm><primary>Algorithms</primary></indexterm>
</title>
<keywordset>
<keyword>ISO C++</keyword>
<keyword>library</keyword>
<keyword>algorithm</keyword>
</keywordset>
</info>
<para>
The neatest accomplishment of the algorithms section is that all the
work is done via iterators, not containers directly. This means two
important things:
</para>
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>
Anything that behaves like an iterator can be used in one of
these algorithms. Raw pointers make great candidates, thus
built-in arrays are fine containers, as well as your own
iterators.
</para>
</listitem>
<listitem>
<para>
The algorithms do not (and cannot) affect the container as a
whole; only the things between the two iterator endpoints. If
you pass a range of iterators only enclosing the middle third of
a container, then anything outside that range is inviolate.
</para>
</listitem>
</orderedlist>
<para>
Even strings can be fed through the algorithms here, although the
string class has specialized versions of many of these functions
(for example, <code>string::find()</code>). Most of the examples
on this page will use simple arrays of integers as a playground
for algorithms, just to keep things simple. The use of
<emphasis>N</emphasis> as a size in the examples is to keep things
easy to read but probably won't be valid code. You can use wrappers
such as those described in
the <link linkend="std.containers">containers section</link> to keep
real code readable.
</para>
<para>
The single thing that trips people up the most is the definition
of <emphasis>range</emphasis> used with iterators; the famous
"past-the-end" rule that everybody loves to hate. The
<link linkend="std.iterators">iterators section</link> of this
document has a complete explanation of this simple rule that seems
to cause so much confusion. Once you
get <emphasis>range</emphasis> into your head (it's not that hard,
honest!), then the algorithms are a cakewalk.
</para>
<!-- Sect1 01 : Non Modifying -->
<!-- Sect1 02 : Mutating -->
<section xml:id="std.algorithms.mutating" xreflabel="Mutating"><info><title>Mutating</title></info>
<section xml:id="algorithms.mutating.swap" xreflabel="swap"><info><title><function>swap</function></title></info>
<section xml:id="algorithms.swap.specializations" xreflabel="Specializations"><info><title>Specializations</title></info>
<para>If you call <code> std::swap(x,y); </code> where x and y are standard
containers, then the call will automatically be replaced by a call to
<code> x.swap(y); </code> instead.
</para>
<para>This allows member functions of each container class to take over, and
containers' swap functions should have O(1) complexity according to
the standard. (And while "should" allows implementations to
behave otherwise and remain compliant, this implementation does in
fact use constant-time swaps.) This should not be surprising, since
for two containers of the same type to swap contents, only some
internal pointers to storage need to be exchanged.
</para>
</section>
</section>
</section>
<!-- Sect1 03 : Sorting -->
</chapter>