CWG 616, 1213 - value category of subobject references.
[official-gcc.git] / libstdc++-v3 / doc / xml / manual / numerics.xml
blobcc2615390f2710de404c20670bf6b1f86100102f
1 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" 
2          xml:id="std.numerics" xreflabel="Numerics">
3 <?dbhtml filename="numerics.html"?>
5 <info><title>
6   Numerics
7   <indexterm><primary>Numerics</primary></indexterm>
8 </title>
9   <keywordset>
10     <keyword>ISO C++</keyword>
11     <keyword>library</keyword>
12   </keywordset>
13 </info>
17 <!-- Sect1 01 : Complex -->
18 <section xml:id="std.numerics.complex" xreflabel="complex"><info><title>Complex</title></info>
19 <?dbhtml filename="complex.html"?>
20   
21   <para>
22   </para>
23   <section xml:id="numerics.complex.processing" xreflabel="complex Processing"><info><title>complex Processing</title></info>
24     
25     <para>
26     </para>
27    <para>Using <code>complex&lt;&gt;</code> becomes even more comple- er, sorry,
28       <emphasis>complicated</emphasis>, with the not-quite-gratuitously-incompatible
29       addition of complex types to the C language.  David Tribble has
30       compiled a list of C++98 and C99 conflict points; his description of
31       C's new type versus those of C++ and how to get them playing together
32       nicely is
33 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://david.tribble.com/text/cdiffs.htm#C99-complex">here</link>.
34    </para>
35    <para><code>complex&lt;&gt;</code> is intended to be instantiated with a
36       floating-point type.  As long as you meet that and some other basic
37       requirements, then the resulting instantiation has all of the usual
38       math operators defined, as well as definitions of <code>op&lt;&lt;</code>
39       and <code>op&gt;&gt;</code> that work with iostreams: <code>op&lt;&lt;</code>
40       prints <code>(u,v)</code> and <code>op&gt;&gt;</code> can read <code>u</code>,
41       <code>(u)</code>, and <code>(u,v)</code>.
42    </para>
43    <para>As an extension to C++11 and for increased compatibility with C,
44       <code>&lt;complex.h&gt;</code> includes both <code>&lt;complex&gt;</code>
45       and the C99 <code>&lt;complex.h&gt;</code> (if the C library provides
46       it).
47    </para>
49   </section>
50 </section>
52 <!-- Sect1 02 : Generalized Operations -->
53 <section xml:id="std.numerics.generalized_ops" xreflabel="Generalized Ops"><info><title>Generalized Operations</title></info>
54 <?dbhtml filename="generalized_numeric_operations.html"?>
55   
56   <para>
57   </para>
59    <para>There are four generalized functions in the &lt;numeric&gt; header
60       that follow the same conventions as those in &lt;algorithm&gt;.  Each
61       of them is overloaded:  one signature for common default operations,
62       and a second for fully general operations.  Their names are
63       self-explanatory to anyone who works with numerics on a regular basis:
64    </para>
65    <itemizedlist>
66       <listitem><para><code>accumulate</code></para></listitem>
67       <listitem><para><code>inner_product</code></para></listitem>
68       <listitem><para><code>partial_sum</code></para></listitem>
69       <listitem><para><code>adjacent_difference</code></para></listitem>
70    </itemizedlist>
71    <para>Here is a simple example of the two forms of <code>accumulate</code>.
72    </para>
73    <programlisting>
74    int   ar[50];
75    int   someval = somefunction();
77    // ...initialize members of ar to something...
79    int  sum       = std::accumulate(ar,ar+50,0);
80    int  sum_stuff = std::accumulate(ar,ar+50,someval);
81    int  product   = std::accumulate(ar,ar+50,1,std::multiplies&lt;int&gt;());
82    </programlisting>
83    <para>The first call adds all the members of the array, using zero as an
84       initial value for <code>sum</code>.  The second does the same, but uses
85       <code>someval</code> as the starting value (thus, <code>sum_stuff == sum +
86       someval</code>).  The final call uses the second of the two signatures,
87       and multiplies all the members of the array; here we must obviously
88       use 1 as a starting value instead of 0.
89    </para>
90    <para>The other three functions have similar dual-signature forms.
91    </para>
93 </section>
95 <!-- Sect1 03 : Interacting with C -->
96 <section xml:id="std.numerics.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info>
97 <?dbhtml filename="numerics_and_c.html"?>
98   
100   <section xml:id="numerics.c.array" xreflabel="Numerics vs. Arrays"><info><title>Numerics vs. Arrays</title></info>
101     
103    <para>One of the major reasons why FORTRAN can chew through numbers so well
104       is that it is defined to be free of pointer aliasing, an assumption
105       that C89 is not allowed to make, and neither is C++98.  C99 adds a new
106       keyword, <code>restrict</code>, to apply to individual pointers.  The
107       C++ solution is contained in the library rather than the language
108       (although many vendors can be expected to add this to their compilers
109       as an extension).
110    </para>
111    <para>That library solution is a set of two classes, five template classes,
112       and "a whole bunch" of functions.  The classes are required
113       to be free of pointer aliasing, so compilers can optimize the
114       daylights out of them the same way that they have been for FORTRAN.
115       They are collectively called <code>valarray</code>, although strictly
116       speaking this is only one of the five template classes, and they are
117       designed to be familiar to people who have worked with the BLAS
118       libraries before.
119    </para>
121   </section>
123   <section xml:id="numerics.c.c99" xreflabel="C99"><info><title>C99</title></info>
124     
126    <para>In addition to the other topics on this page, we'll note here some
127       of the C99 features that appear in libstdc++.
128    </para>
129    <para>The C99 features depend on the <code>--enable-c99</code> configure flag.
130       This flag is already on by default, but it can be disabled by the
131       user.  Also, the configuration machinery will disable it if the
132       necessary support for C99 (e.g., header files) cannot be found.
133    </para>
134    <para>As of GCC 3.0, C99 support includes classification functions
135       such as <code>isnormal</code>, <code>isgreater</code>,
136       <code>isnan</code>, etc.
137       The functions used for 'long long' support such as <code>strtoll</code>
138       are supported, as is the <code>lldiv_t</code> typedef.  Also supported
139       are the wide character functions using 'long long', like
140       <code>wcstoll</code>.
141    </para>
143   </section>
144 </section>
146 </chapter>