Using Exceptions

Return-Path: Delivered-To: apmail-incubator-stdcxx-commits-archive@www.apache.org Received: (qmail 60356 invoked from network); 19 Jan 2006 01:41:37 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 19 Jan 2006 01:41:37 -0000 Received: (qmail 95194 invoked by uid 500); 19 Jan 2006 01:41:37 -0000 Delivered-To: apmail-incubator-stdcxx-commits-archive@incubator.apache.org Received: (qmail 95143 invoked by uid 500); 19 Jan 2006 01:41:36 -0000 Mailing-List: contact stdcxx-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: stdcxx-dev@incubator.apache.org Delivered-To: mailing list stdcxx-commits@incubator.apache.org Received: (qmail 95122 invoked by uid 500); 19 Jan 2006 01:41:36 -0000 Delivered-To: apmail-incubator-stdcxx-cvs@incubator.apache.org Received: (qmail 95102 invoked by uid 99); 19 Jan 2006 01:41:36 -0000 Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 18 Jan 2006 17:41:36 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME,UPPERCASE_25_50 X-Spam-Check-By: apache.org Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.29) with SMTP; Wed, 18 Jan 2006 17:41:23 -0800 Received: (qmail 59883 invoked by uid 65534); 19 Jan 2006 01:41:02 -0000 Message-ID: <20060119014102.59877.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r370343 [11/17] - in /incubator/stdcxx/trunk/doc: stdlibref/ stdlibug/ Date: Thu, 19 Jan 2006 01:36:53 -0000 To: stdcxx-cvs@incubator.apache.org From: sebor@apache.org X-Mailer: svnmailer-1.0.5 X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Modified: incubator/stdcxx/trunk/doc/stdlibug/18-3.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/18-3.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/18-3.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/18-3.html Wed Jan 18 17:30:36 2006 @@ -3,10 +3,10 @@ Using Exceptions -

Rogue Wave C++ Standard Library User's Guide

Apache C++ Standard Library User's Guide

18.3 Using Exceptions

All exceptions thrown explicitly by any element of the Standard C++ Library are guaranteed to be part of the library's exception hierarchy. Please review the Standard C++ Library Module Reference Guide entries for these classes to determine which functions throw which exceptions. You can then choose to catch particular exceptions, or catch any that might be thrown by specifying the base class exception.

All exceptions thrown explicitly by any element of the C++ Standard Library are guaranteed to be part of the library's exception hierarchy. Please review the C++ Standard Library Module Reference Guide entries for these classes to determine which functions throw which exceptions. You can then choose to catch particular exceptions, or catch any that might be thrown by specifying the base class exception.

For instance, if you are going to call the insert function on string with a position value that could at some point be invalid, you should use code like this:

@@ -48,7 +48,7 @@
 if (bad_packet())
    throw bad_packet_error("Packet size incorrect");

This section has demonstrated how the Standard C++ Library exception classes provide you with a basic error model. From this foundation, you can build the right error detection and reporting methods required for your particular application.

This section has demonstrated how the C++ Standard Library exception classes provide you with a basic error model. From this foundation, you can build the right error detection and reporting methods required for your particular application.

Modified: incubator/stdcxx/trunk/doc/stdlibug/18-4.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/18-4.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/18-4.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/18-4.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Example Program: Exceptions -

Rogue Wave C++ Standard Library User's Guide

Apache C++ Standard Library User's Guide

18.4 Example Program: Exceptions

NOTE -- This program is in the file exceptn.cpp. @@ -22,7 +22,7 @@ std::string s; // First we'll try to incite then catch an exception - // from the Standard C++ Library string class. + // from the C++ Standard Library string class. // We'll try to replace at a position that is non-existent. // // By wrapping the body of main in a try-catch block we can be Modified: incubator/stdcxx/trunk/doc/stdlibug/18.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/18.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/18.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/18.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Exception Handling -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

Chapter 18: Exception Handling

18.1 Overview
Modified: incubator/stdcxx/trunk/doc/stdlibug/19-1.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/19-1.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/19-1.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/19-1.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Overview -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

19.1 Overview

The auto_ptr class wraps any pointer obtained through new and provides automatic deletion of that pointer. The pointer wrapped by an auto_ptr object is deleted when the auto_ptr itself is destroyed.
Modified: incubator/stdcxx/trunk/doc/stdlibug/19-2.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/19-2.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/19-2.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/19-2.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Declaration and Initialization of Autopointers -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

19.2 Declaration and Initialization of Autopointers

You attach an auto_ptr object to a pointer either by using one of the constructors for auto_ptr, by assigning one auto_ptr object to another, or by using the reset member function. Only one auto_ptr owns a particular pointer at any one time, except for the null pointer, which all auto_ptrs own by default. Any use of the auto_ptr copy constructor or assignment operator transfers ownership from one auto_ptr object to another. For instance, suppose we create an auto_ptr a like this:
Modified: incubator/stdcxx/trunk/doc/stdlibug/19.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/19.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/19.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/19.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ auto_ptr -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

Chapter 19: auto_ptr

19.1 Overview
Modified: incubator/stdcxx/trunk/doc/stdlibug/2-1.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/2-1.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/2-1.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/2-1.html Wed Jan 18 17:30:36 2006 @@ -3,10 +3,10 @@ Introduction to Iterators -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

2.1 Introduction to Iterators
-
The concept of iterators is fundamental to using the container classes and the associated algorithms provided by the Standard C++ Library. An iterator is a pointer-like object used to cycle through all the elements stored in a container. Because different algorithms need to traverse containers in a variety of fashions, there are different forms of iterators. Each container class in the Standard C++ Library can generate an iterator with functionality appropriate to the storage technique used in implementing the container. It is the category of iterators required as arguments that chiefly distinguishes which algorithms in the Standard C++ Library can be used with which container classes.
+
The concept of iterators is fundamental to using the container classes and the associated algorithms provided by the C++ Standard Library. An iterator is a pointer-like object used to cycle through all the elements stored in a container. Because different algorithms need to traverse containers in a variety of fashions, there are different forms of iterators. Each container class in the C++ Standard Library can generate an iterator with functionality appropriate to the storage technique used in implementing the container. It is the category of iterators required as arguments that chiefly distinguishes which algorithms in the C++ Standard Library can be used with which container classes.

Just as pointers can be used in a variety of ways in traditional programming, iterators can be used for a number of different purposes. An iterator can be used to denote a specific value, just as a pointer can be used to reference a specific memory location. A pair of iterators can be used to define a range or sequence of values held in a container, just as two pointers can be used to describe a contiguous region of memory. With iterators, however, the values being described may be only logically rather than physically in sequence because they are derived from the same container, and the second follows the first in the order in which the elements are maintained by the container.
@@ -19,7 +19,7 @@
NOTE -- Whenever two iterators are used to describe a range, it is assumed that the second iterator is reachable from the first, but this is not verified. Errors can occur if this expectation is not satisfied.
-
In the remainder of this chapter, we describe the different forms of iterators used by the Standard C++ Library, as well as various other iterator-related functions.
+
In the remainder of this chapter, we describe the different forms of iterators used by the C++ Standard Library, as well as various other iterator-related functions.

Modified: incubator/stdcxx/trunk/doc/stdlibug/2-2.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/2-2.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/2-2.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/2-2.html Wed Jan 18 17:30:36 2006 @@ -3,11 +3,11 @@ Varieties of Iterators -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

2.2 Varieties of Iterators
-
As shown in Table 3, there are five basic forms of iterators used in the Standard C++ Library:
-
Table 3: Iterator forms in the Standard C++ Library
+
As shown in Table 3, there are five basic forms of iterators used in the C++ Standard Library:
+
Table 3: Iterator forms in the C++ Standard Library

Iterator form Description @@ -32,8 +32,8 @@
Iterator categories are hierarchical. Forward iterators can be used wherever input or output iterators are required, bidirectional iterators can be used in place of forward iterators, and random access iterators can be used in situations requiring bidirectionality.

A second characteristic of iterators is whether or not they can be used to modify the values held by their associated container. A constant iterator is one that can be used for access only, and cannot be used for modification. Output iterators are never constant, and input iterators always are. Other iterators may or may not be constant, depending upon how they are created. There are both constant and non-constant bidirectional iterators, both constant and non-constant random access iterators, and so on.
-
Table 4 summarizes specific ways that various categories of iterators are generated by the containers in the Standard C++ Library.
-
Table 4: Iterators generated in the Standard C++ Library
+
Table 4 summarizes specific ways that various categories of iterators are generated by the containers in the C++ Standard Library.
+
Table 4: Iterators generated in the C++ Standard Library

Iterator form Produced by @@ -106,9 +106,9 @@ // can't modify location returned by the following const int* where = std::find(first, last, 7); -
Because ordinary pointers have the same functionality as random access iterators, most of the generic algorithms in the Standard C++ Library can be used with conventional C++ arrays, as well as with the containers provided by the Standard C++ Library.
+
Because ordinary pointers have the same functionality as random access iterators, most of the generic algorithms in the C++ Standard Library can be used with conventional C++ arrays, as well as with the containers provided by the C++ Standard Library.
-
Container iterators. All of the iterators constructed for the various containers provided by the Standard C++ Library are at least as general as input iterators. The iterator for the first element in a collection is always constructed by the member function begin(), while the iterator that denotes the past-the-end location is generated by the member function end(). For example, the following iterator searches for the value 7 in a list of integers:
+
Container iterators. All of the iterators constructed for the various containers provided by the C++ Standard Library are at least as general as input iterators. The iterator for the first element in a collection is always constructed by the member function begin(), while the iterator that denotes the past-the-end location is generated by the member function end(). For example, the following iterator searches for the value 7 in a list of integers:

std::list<int>::iterator where = @@ -116,7 +116,7 @@

Each container that supports iterators provides a type with the name iterator within the class declaration. Using this type, iterators can uniformly be declared in the fashion shown. If the container being accessed is constant, or if the description const_iterator is used, then the iterator is a constant iterator.
-
Input stream iterators. The Standard C++ Library provides a mechanism to operate on an input stream using an input iterator. This ability is provided by the class istream_iterator, described in more detail in Section 2.3.1.
+
Input stream iterators. The C++ Standard Library provides a mechanism to operate on an input stream using an input iterator. This ability is provided by the class istream_iterator, described in more detail in Section 2.3.1.

2.2.2 Output Iterators

An output iterator has the opposite function of an input iterator. Output iterators can be used to assign values in a sequence, but cannot be used to access values. For example, we can use an output iterator in a generic algorithm that copies values from one sequence into another:
@@ -134,7 +134,7 @@
A number of the generic algorithms manipulate two parallel sequences. Frequently the second sequence is described using only a beginning iterator, rather than an iterator pair. It is assumed, but not checked, that the second sequence has at least as many elements as the first.

In the algorithm shown here, two ranges are being manipulated: the range of source values specified by a pair of input iterators, and the destination range. The latter, however, is specified by only a single argument. It is assumed that the destination is large enough to include all values, and errors will ensue if this is not the case.

As illustrated by this algorithm, an output iterator can modify the element to which it points by being used as the target for an assignment. Output iterators can use the dereference operator only in this fashion; they cannot be used to return or to access the elements they denote.
-
As we noted earlier, ordinary pointers, like all iterators constructed by containers in the Standard C++ Library, can be used as output iterators. (Ordinary pointers are random access iterators, which are a superset of output iterators.) For example, in this code fragment elements from an ordinary C-style array are copied into a Standard C++ Library vector:
+
As we noted earlier, ordinary pointers, like all iterators constructed by containers in the C++ Standard Library, can be used as output iterators. (Ordinary pointers are random access iterators, which are a superset of output iterators.) For example, in this code fragment elements from an ordinary C-style array are copied into a C++ Standard Library vector:

int data[100]; @@ -142,7 +142,7 @@ ... std::copy(data, data+100, newdata.begin());
-
Just as the istream_iterator provides a way to operate on an input stream using the input iterator mechanism, the Standard C++ Library provides a datatype, ostream_iterator, that permits values to be written to an output stream in an iterator-like fashion (Section 2.3.2).
+
Just as the istream_iterator provides a way to operate on an input stream using the input iterator mechanism, the C++ Standard Library provides a datatype, ostream_iterator, that permits values to be written to an output stream in an iterator-like fashion (Section 2.3.2).

Yet another form of output iterator is an insert iterator (Section 2.4). An insert iterator changes the output iterator operations of dereferencing/assignment and increment into insertions into a container. This permits operations such as copy() to be used with variable length containers, such as lists and sets.

2.2.3 Forward Iterators
@@ -162,7 +162,7 @@ } } -
Ordinary pointers, like all iterators produced by containers in the Standard C++ Library, can be used as forward iterators. For example, in the following code instances of the value 7 are replaced with the value 11 in a vector of integers:
+
Ordinary pointers, like all iterators produced by containers in the C++ Standard Library, can be used as forward iterators. For example, in the following code instances of the value 7 are replaced with the value 11 in a vector of integers:

std::replace(aVec.begin(), aVec.end(), 7, 11); @@ -197,7 +197,7 @@
Some algorithms require more functionality than simply accessing values in either a forward or backward direction. Random access iterators permit values to be accessed by subscript, subtracted one from another (to yield the number of elements between their respective values), or modified by arithmetic operations, all in a manner similar to conventional pointers.

With conventional pointers, arithmetic operations can be related to the underlying memory; that is, x+10 is the memory ten elements after the beginning of x. With iterators the logical meaning is preserved (x+10 is the tenth element after x), however different the physical addresses being described.
-
Algorithms that use random access iterators include generic operations like sorting and binary search. For example, the following algorithm randomly shuffles the elements of a container. This is similar to, although simpler than, the function std::random_shuffle() provided by the Standard C++ Library.
+
Algorithms that use random access iterators include generic operations like sorting and binary search. For example, the following algorithm randomly shuffles the elements of a container. This is similar to, although simpler than, the function std::random_shuffle() provided by the C++ Standard Library.

template <class RandomAccessIterator> Modified: incubator/stdcxx/trunk/doc/stdlibug/2-3.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/2-3.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/2-3.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/2-3.html Wed Jan 18 17:30:36 2006 @@ -3,13 +3,13 @@ Stream Iterators -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

2.3 Stream Iterators

Stream iterators are used to access an existing input or output stream using iterator operations. An input stream iterator permits an input stream to be read using iterator operations. Similarly, an output stream iterator writes to an output stream when iterator operations are executed.

2.3.1 Input Stream Iterators
-
As we noted in the discussion of input iterators, the Standard C++ Library provides a mechanism for turning an input stream into an input iterator through the template <class T, class charT, class Traits, class Distance> std::istream_iterator . When declared, the four template arguments are the element type, the stream character type, the character traits type, and a type that measures the distance between elements. The latter two default to std::char_traits<charT > and std::ptrdiff_t. The default is almost always the appropriate behavior. The single argument provided to the constructor for an istream_iterator is the stream to be accessed. Each time that operator++() is invoked on an input stream iterator, a new value from the stream is read using operator>>() and stored. This value is then available through the use of the dereference operator operator*(). The va lue constructed by istream_iterator when no arguments are provided to the constructor can be used as an ending iterator value. For example, the following code finds the first value 7 in a file of integer values:
+
As we noted in the discussion of input iterators, the C++ Standard Library provides a mechanism for turning an input stream into an input iterator through the template <class T, class charT, class Traits, class Distance> std::istream_iterator . When declared, the four template arguments are the element type, the stream character type, the character traits type, and a type that measures the distance between elements. The latter two default to std::char_traits<charT > and std::ptrdiff_t. The default is almost always the appropriate behavior. The single argument provided to the constructor for an istream_iterator is the stream to be accessed. Each time that operator++() is invoked on an input stream iterator, a new value from the stream is read using operator>>() and stored. This value is then available through the use of the dereference operator operator*(). The va lue constructed by istream_iterator when no arguments are provided to the constructor can be used as an ending iterator value. For example, the following code finds the first value 7 in a file of integer values:

std::istream_iterator<int, char> intstream(std::cin), eof; @@ -25,7 +25,7 @@ std::copy(newdata.begin(), newdata.end(), std::ostream_iterator<int,char> (std::cout, " "));
-
Simple file transformation algorithms can be created by combining input and output stream iterators and the various algorithms provided by the Standard C++ Library. The following short program reads a file of integers from the standard input, removes all occurrences of the value 7, and copies the remainder to the standard output, separating each value by a new line:
+
Simple file transformation algorithms can be created by combining input and output stream iterators and the various algorithms provided by the C++ Standard Library. The following short program reads a file of integers from the standard input, removes all occurrences of the value 7, and copies the remainder to the standard output, separating each value by a new line:

int main() Modified: incubator/stdcxx/trunk/doc/stdlibug/2-4.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/2-4.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/2-4.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/2-4.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Insert Iterators -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

2.4 Insert Iterators

Assignment to the dereferenced value of an output iterator is normally used to overwrite the contents of an existing location. For example, the following invocation of the function std::copy() transfers values from one vector to another, although the space for the second vector was already set aside and even initialized by the declaration statement:
Modified: incubator/stdcxx/trunk/doc/stdlibug/2-5.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/2-5.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/2-5.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/2-5.html Wed Jan 18 17:30:36 2006 @@ -3,10 +3,10 @@ Iterator Operations -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

2.5 Iterator Operations
-
The Standard C++ Library provides two functions that can be used to manipulate iterators. The function std::advance() takes an iterator and a numeric value as argument, and modifies the iterator by moving the given amount.
+
The C++ Standard Library provides two functions that can be used to manipulate iterators. The function std::advance() takes an iterator and a numeric value as argument, and modifies the iterator by moving the given amount.

namespace std { Modified: incubator/stdcxx/trunk/doc/stdlibug/2.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/2.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/2.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/2.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Iterators -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

Chapter 2: Iterators

2.1 Introduction to Iterators
Modified: incubator/stdcxx/trunk/doc/stdlibug/20-1.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/20-1.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/20-1.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/20-1.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Overview -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

20.1 Overview

The class complex is a template class used to create objects for representing and manipulating complex numbers. The operations defined on complex numbers allow them to be freely intermixed with the other numeric types available in the C++ language, thereby permitting numeric software to be easily and naturally expressed.
Modified: incubator/stdcxx/trunk/doc/stdlibug/20-2.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/20-2.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/20-2.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/20-2.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Creating and Using Complex Numbers -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

20.2 Creating and Using Complex Numbers

In the following sections we describe the operations used to create and manipulate complex numbers.

20.2.1 Declaring Complex Numbers
@@ -88,7 +88,7 @@
The transcendental functions std::exp(), std::log(), std::log10(), and std::sqrt() have been extended to complex arguments. Each takes a single complex number as argument, and returns a complex number as result.
-
The Standard C++ Library defines several variations of the exponential function std::pow(). Versions exist to raise a complex number to an integer power, to raise a complex number to a complex power or to a real power, or to raise a real value to a complex power.
+
The C++ Standard Library defines several variations of the exponential function std::pow(). Versions exist to raise a complex number to an integer power, to raise a complex number to a complex power or to a real power, or to raise a real value to a complex power.

Modified: incubator/stdcxx/trunk/doc/stdlibug/20-3.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/20-3.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/20-3.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/20-3.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Example Program: Roots of a Polynomial -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

20.3 Example Program: Roots of a Polynomial

Modified: incubator/stdcxx/trunk/doc/stdlibug/20.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/20.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/20.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/20.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ complex -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

Chapter 20: complex

20.1 Overview
Modified: incubator/stdcxx/trunk/doc/stdlibug/21-1.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/21-1.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/21-1.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/21-1.html Wed Jan 18 17:30:36 2006 @@ -3,10 +3,10 @@ Overview -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

21.1 Overview
-
A feature of the Standard C++ Library is an organized mechanism for describing the characteristics of the fundamental types provided in the execution environment. In older C and C++ libraries, these characteristics were often described by large collections of symbolic constants or macros. For example, the smallest representable value that could be stored in a variable of type char would be found in the constant named CHAR_MIN; the similar constant for a short would be known as SHRT_MIN; a float would be FLT_MIN, and so on. These manifest constants are still available in the headers <climits> and <cfloat>.
+
A feature of the C++ Standard Library is an organized mechanism for describing the characteristics of the fundamental types provided in the execution environment. In older C and C++ libraries, these characteristics were often described by large collections of symbolic constants or macros. For example, the smallest representable value that could be stored in a variable of type char would be found in the constant named CHAR_MIN; the similar constant for a short would be known as SHRT_MIN; a float would be FLT_MIN, and so on. These manifest constants are still available in the headers <climits> and <cfloat>.

The class template numeric_limits provides a uniform way of representing this information for all numeric types. Instead of using a different symbolic name for each new datatype, the primary class template defines a generic interface in the form of static data members and static member functions. The primary template supplies useless values just so that it can still be used in generic code. It can be distinguished from its specializations by examining the value of the static const bool data member std::numeric_limits<>::is_specialized which will be false for the primary template and true for any specialization. Specializations of this class template then provide a meaningful definition of every member for each fundamental type. For example, the smallest character value is found as the result of invoking the function std::numeric_limits<char>:: min(), while the smallest floating point value is found using std::numeric_limits<float>::min(), and so on.

Using a class template not only greatly reduces the number of symbolic names that need to be defined to describe the operating environment, but it also ensures consistency between the descriptions of the various types. Most important, however, it allows programs to treat any object or variable generically, without regard to its specific type.
Modified: incubator/stdcxx/trunk/doc/stdlibug/21-2.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/21-2.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/21-2.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/21-2.html Wed Jan 18 17:30:36 2006 @@ -3,12 +3,12 @@ Fundamental Datatypes -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

21.2 Fundamental Datatypes
-
The Standard C++ Library describes a specific type by providing a specialization of the numeric_limits template for the type. Static member functions and static constant data members then provide information specific to the type. The Standard C++ Library includes descriptions of the fundamental datatypes given in Table 21.
-
Table 21: Fundamental datatypes of the Standard C++ Library
+
The C++ Standard Library describes a specific type by providing a specialization of the numeric_limits template for the type. Static member functions and static constant data members then provide information specific to the type. The C++ Standard Library includes descriptions of the fundamental datatypes given in Table 21.
+
Table 21: Fundamental datatypes of the C++ Standard Library

bool char Modified: incubator/stdcxx/trunk/doc/stdlibug/21-3.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/21-3.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/21-3.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/21-3.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ numeric_limits Members -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

21.3 numeric_limits Members

Since a number of the members in the numeric_limits template specializations are meaningful only for floating point specializations, it is useful to separate the description of the members into common fields and floating-point specific fields.
Modified: incubator/stdcxx/trunk/doc/stdlibug/21.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/21.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/21.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/21.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ numeric_limits -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

Chapter 21: numeric_limits

21.1 Overview
Modified: incubator/stdcxx/trunk/doc/stdlibug/22-1.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/22-1.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/22-1.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/22-1.html Wed Jan 18 17:30:36 2006 @@ -3,9 +3,9 @@ Overview -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

22.1 Overview
-
The C++ language is often used in scientific and engineering work to perform long and difficult operations on arrays of numbers. While the language itself provides the flexibility and efficiency needed for these kind of calculations, the code can become very complex. Naturally, we can use the object-oriented features of the language to encapsulate this complexity, but classes designed to simplify numeric programming without sacrificing performance are notoriously difficult to code correctly. Fortunately, the Standard C++ Library now provides some relief in the form of the valarray class template.
+
The C++ language is often used in scientific and engineering work to perform long and difficult operations on arrays of numbers. While the language itself provides the flexibility and efficiency needed for these kind of calculations, the code can become very complex. Naturally, we can use the object-oriented features of the language to encapsulate this complexity, but classes designed to simplify numeric programming without sacrificing performance are notoriously difficult to code correctly. Fortunately, the C++ Standard Library now provides some relief in the form of the valarray class template.

This class template provides the necessary efficiency in the form of a single-dimensional array. Class valarray can be used to perform calculations directly on arrays in a single dimension, and to represent higher order arrays with a little more effort. An extended set of subscripting operators provides the basis for building matrices and other more sophisticated classes from the relatively simple and lean valarray.

22.1.1 Performance Issues
Modified: incubator/stdcxx/trunk/doc/stdlibug/22-2.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/22-2.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/22-2.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/22-2.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Declaring a valarray -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

22.2 Declaring a valarray

A valarray can be constructed by any of the following means:
Modified: incubator/stdcxx/trunk/doc/stdlibug/22-3.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/22-3.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/22-3.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/22-3.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Assignment Operators -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

22.3 Assignment Operators

Class valarray provides six assignment operations. These are: assignment from another valarray, assignment from a T value, and assignment from any of the four auxiliary classes returned by the subset operations.
Modified: incubator/stdcxx/trunk/doc/stdlibug/22-4.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/22-4.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/22-4.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/22-4.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Element and Subset Access -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

22.4 Element and Subset Access

22.4.1 Ordinary Index Operators
@@ -33,7 +33,7 @@
22.4.2.2 The gslice Operation

The gslice operation differs from the slice in that it defines a set of strides and an associated set of lengths. This set of lengths and strides allows a program to treat a single-dimensional valarray as a multidimensional array and to pull multi-dimensional slices from that array. Note that the gslice subset operator takes a gslice argument and returns a gslice_array in the same manner that the slice operation takes a slice and returns a slice_array.
-
Here is a simple example that uses gslices to represent a three-dimensional array. In this example, the first three numbers form the top row of a two-dimensional array whose center and bottom rows are completed with the next six numbers. The next nine numbers represent the second or middle two-dimensional array, and the last nine the back two-dimensional array. Taken together they form a three- dimensional cube. See the Standard C++ Library Module Reference Guide for an extended version of this example that uses additional gslices to pull slices along several different axes of the three-dimensional cube defined by this first slice.
+
Here is a simple example that uses gslices to represent a three-dimensional array. In this example, the first three numbers form the top row of a two-dimensional array whose center and bottom rows are completed with the next six numbers. The next nine numbers represent the second or middle two-dimensional array, and the last nine the back two-dimensional array. Taken together they form a three- dimensional cube. See the C++ Standard Library Module Reference Guide for an extended version of this example that uses additional gslices to pull slices along several different axes of the three-dimensional cube defined by this first slice.

using std::gslice; Modified: incubator/stdcxx/trunk/doc/stdlibug/22-5.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/22-5.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/22-5.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/22-5.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Computed Assignment Operators -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

22.5 Computed Assignment Operators

Class valarray offers two different versions of the following operators: operator*=(), operator/=(), operator%=(), operator+=(), operator-=(), operator^=(), operator&=(), operator|=(), operator<<=(), and operator>>=(). In each case, one version takes a valarray reference and the second takes a T&. The first version of each operation applies its operation to the corresponding elements of self and the valarray argument. The second version applies the operation to all elements of self using the T& argument. For example:
Modified: incubator/stdcxx/trunk/doc/stdlibug/22-6.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/22-6.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/22-6.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/22-6.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ Member Functions -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

22.6 Member Functions

The member functions of class valarray include the size() function, which returns the size of a valarray, and the sum() function, which returns the sum of all elements in a valarray. The functions min() and max() return, respectively, the minimum and maximum values in a valarray.
Modified: incubator/stdcxx/trunk/doc/stdlibug/22-7.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/22-7.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/22-7.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/22-7.html Wed Jan 18 17:30:36 2006 @@ -3,11 +3,11 @@ Non-Member Functions -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

22.7 Non-Member Functions

22.7.1 Binary Operators
-
Class valarray provides a large block of binary operators that allow a program to apply these operators to two valarrays or to a valarray and a T value, where the T can occur on the left- or right-hand side of the expression. As you'd expect, these operators do not modify either of their arguments, but instead return a new valarray containing the result of the operation. Each version that takes two valarray arguments returns the result of applying the operation to the corresponding elements of the arrays. The versions with a T& argument return a valarray whose elements result from applying the operation to each element in the valarray argument along with the T& argument. See the valarray entry in the Standard C++ Library Mo dule Reference Guide for a complete list of binary operators.
+
Class valarray provides a large block of binary operators that allow a program to apply these operators to two valarrays or to a valarray and a T value, where the T can occur on the left- or right-hand side of the expression. As you'd expect, these operators do not modify either of their arguments, but instead return a new valarray containing the result of the operation. Each version that takes two valarray arguments returns the result of applying the operation to the corresponding elements of the arrays. The versions with a T& argument return a valarray whose elements result from applying the operation to each element in the valarray argument along with the T& argument. See the valarray entry in the C++ Standard Library Mo dule Reference Guide for a complete list of binary operators.

Arithmetic and bitwise operators return a valarray of T. Logical operators return a valarray<bool>, where each element represents the comparison of corresponding elements in two valarrays or the comparison of each element in an array with a particular value. For example:

@@ -23,7 +23,7 @@

22.7.2 Transcendental Functions
-
Class valarray also provides 20 transcendental functions, four of which are overloads. Each function returns a new valarray that contains elements resulting from the application of the transcendental function to each element in the valarray passed as an argument. See the valarray entry in the Standard C++ Library Module Reference Guide for a complete list of transcendental functions.
+
Class valarray also provides 20 transcendental functions, four of which are overloads. Each function returns a new valarray that contains elements resulting from the application of the transcendental function to each element in the valarray passed as an argument. See the valarray entry in the C++ Standard Library Module Reference Guide for a complete list of transcendental functions.

The following example squares each of the elements of an array:

Modified: incubator/stdcxx/trunk/doc/stdlibug/22.html URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/doc/stdlibug/22.html?rev=370343&r1=370342&r2=370343&view=diff ============================================================================== --- incubator/stdcxx/trunk/doc/stdlibug/22.html (original) +++ incubator/stdcxx/trunk/doc/stdlibug/22.html Wed Jan 18 17:30:36 2006 @@ -3,7 +3,7 @@ valarray -
Rogue Wave C++ Standard Library User's Guide
+
Apache C++ Standard Library User's Guide

Chapter 22: valarray

22.1 Overview