DEC C++ currently provides a partial implementation of the C++ Standard Library. The ANSI X3/J16 C++ committee is in the process of standardizing the C++ Standard Library, and when this process is complete, DEC C++ will provide a complete library implementation. In the meantime, the subset provided was selected from among the most stable parts of the library as defined in the ANSI C++ draft.

This release of DEC C++ contains the following components of the C++ Standard Library:

• Standard Template Library (STL)
• String Library
• Numeric Limits class
• Auto_ptr class
• Standard Exception classes
• Complex Math Library
• Allocator class

Some of the components in the C++ Standard Library are designed to replace nonstandard components that are currently distributed in the DEC C++ Class Library. DIGITAL will continue to provide the DEC C++ Class Library in its nonstandard form. However, you now have the option of using the new standard components.

The following sections provide more information on the DEC C++ implementation of the Standard Library, including upward compatibility, compiling and linking, thread safety, and details on each component of the library.

6.1 Important Compatibility Information

Because the standardization process for the C++ Standard Library is not yet completed, DIGITAL cannot guarantee that this version of the library is compatible with any past or future releases. We ship the run-time portion of the library in object form, not in shareable form, to emphasize this situation.

Therefore, DIGITAL recommends that you do not use this library for any production code that requires upward compatibility. This release of the library matches as closely as is feasible the standard described in the post-Stockholm ANSI C++ draft dated 24 September 1996.

6.2 How to Build Programs Using the C++ Standard Library

When you use the cxx command to compile and link programs that use the C++ Standard Library, no special switches are required. The DEC C++ driver automatically includes the Standard Library run-time support (-lcxxstd) on the link command, and automatic template instantiation (-pt) is the default mode.

For example, to build a program called prog.cxx that uses the Standard Library, you can simply use the following command:

cxx prog.cxx

Thread Safety

The C++ Standard Library is thread safe if you specify the -D_REENTRANT flag on your cxx command. You can also use the -threads flag to establish thread safety. This ensures that all internal library data is protected against simultaneous access from multiple threads.

6.3 Incompatibilities Between the DEC C++ Standard Library and the September 1996 ANSI C++ Draft

DEC C++ currently does not support all the necessary language features to compile a Standard Library that meets the specifications of the ANSI C++ draft. Therefore, where possible, the DIGITAL implementation of the Standard Library contains workarounds for these missing language features.

The following list shows the unsupported ANSI C++ language features and their workarounds in the DEC C++ Standard Library:

• Namespaces
  Athough the current version of the DEC C++ compiler offers this support, the Standard Library classes and functions are not placed in namespace std.
• Member function templates
  Some member function templates within the Standard Library have been substituted with member functions for a given type.
• Bool
  The current STL simulates bool as a typedef of int. Thus, the DEC C++ STL cannot supply the specialization vector<bool> because it would conflict with vector<int>. In the interim, DIGITAL supplies a bit_vector class in place of vector<bool>.
• Wide characters
  The DEC C++ compiler does not support wchar_t as a built-in type, therefore the current String Library does not support wide character types.
• Numeric Limits
  The DEC C++ Numeric Limits class does not provide a specialization for bool or for wchar_t because DEC C++ does not treat them as built-in types.
• Mutable
  DEC C++ does not support the mutable keyword, thus the auto_ptr release() member is not declared const.

The following data structures and algorithms supplied with the current STL differ from those specified in the September 1996 ANSI C++ draft:

• Because DEC C++ does not supply a new standard stream class, streambuf_iterators are not implemented. Note that stream_iterators are supplied.
• Because the allocator class from the latest ANSI C++ draft requires member templates, which DEC C++ does not support, two versions of the allocator are provided: one that is standard-conforming and an alternative that does not rely on member templates. See Section 6.10 for more details.

Additionally, the following are some minor incompatibilities in the current String Library that correct what DIGITAL believes are mistakes in the draft:

• The DEC C++ extraction operator clears the string before extraction.
• The DEC C++ extraction operator skips white space before extraction.
• The DEC C++ getline() function does not "end by storing the count in is." To do this may not be feasible.
• The DEC C++ insert() and replace() functions are different from the draft. For example, the second insert() function does not have any default arguments and, on return, the first insert() function performs an insert(pos1,str,0,npos). A similar modification was made to the replace() function.

DEC C++ provides an implementation of the Standard Template Library (STL).

The following sections provide information specific to the DEC C++ implementation of the STL. For information on how to program with the STL, refer to the STL Tutorial and Reference Guide that is part of the DEC C++ printed documentation set. See Section 6.4.3 for differences between the STL Tutorial and Reference Guide and the DEC C++ implementation of the STL.

6.4.1 Examples of Use

The following are some simple examples of using the containers and algorithms in the STL. You should compile these examples with the command:

cxx prog.cxx

For details on how to build programs that use the STL, see Section 6.2.

Using the vector class

// This example shows how to create a vector, // initialize it with values, sort and print it #include <vector> #include <algorithm> #include <iostream.hxx> int main() { // create a vector of 4 ints vector<int> v(4); // initialize the vector with values v[0]=2; v[1]=0; v[2]=3; v[3]=1; // sort the vector sort(v.begin(),v.end()); // print the sorted vector for (vector<int>::iterator viter=v.begin();viter!=v.end();viter++) cout << *viter << " "; cout << endl; return 0; }

Using the list class

// This example shows how to create a list, initialize // it with values, find a particular value and print // the element before and after that value #include <list> #include <iostream.hxx> #include <string> int main() { // create a list list<string> l; // add some values to the list l.insert(l.end(),"Stepanov"); l.insert(l.end(),"Koenig"); l.insert(l.end(),"Stroustrup"); l.insert(l.end(),"Lippman"); // find the value "Stroustrup" string value("Stroustrup"); list<string>::iterator liter=find(l.begin(),l.end(), value); // print out the value before and after "Stroustrup" if (liter!=l.end()) cout << "Stroustrup was found after " << *(--liter) << " and before " << *(++(++liter)) << endl; return 0; }

Using the map class

// This example shows how to create a map, // add some values, and find the number of elements // which match a specified criterion #include <map> #include <iostream.hxx> bool smaller (pair<const char* const, float> p) { // returns true if element costs less than $3.00 return p.second < 3.00; } int main() { // create a map map<const char*,float, less<const char*> > shopmap; // add some elements to the map shopmap["milk"]=1.29; shopmap["steak"]=5.99; shopmap["cornflakes"]=2.69; shopmap["cheese"]=3.42; shopmap["ricekrispies"]=2.25; // count the number of items less than $3.00 int num_items = 0; count_if(shopmap.begin(),shopmap.end(),smaller,num_items); // print the results cout << "number of items less than 3 dollars is: " << num_items << endl; return 0; }

6.4.2 Upgrading from the Nonstandard DEC C++ Class Library

The following discussion guides you through upgrading DEC C++ Class Library code to use the STL, specifically replacing the vector and stack classes that are currently in the vector.hxx header file.

6.4.2.1 Upgrading from the DEC C++ Class Library Vector to the STL Vector

To change your code from using the DEC C++ Class Library vector to the STL vector, consider the following actions:

• Change the name of your #include statement from <vector.h> or <vector.hxx> to <vector>.
• Remove the vectordeclare and vectorimplement declarations from your code.
• Change all vector(type) declarations to vector<type>. For example, vector(int) vi should become vector<int> vi.
• Note that the following member functions are replaced in the STL library:

  Nonstandard Vector Function	Replaced with STL Vector Function
  elem(int index)	operator[](size_t index) (no bounds checking)
  operator[](int index)	at(size_t index) (bounds checking)
  setsize(int newsize)	resize(size_t newsize)

• When copying vectors of unequal lengths, note that the STL vector has a different behavior as follows:
  When using the STL vector, if the target vector is smaller than the source vector, the target vector automatically increases to accommodate the additional elements.
  The DEC C++ Class Library vector displays an error and aborts when this situation occurs.
• Note that another difference in behavior occurs when you specify a negative index for a vector.
  The DEC C++ Class Library vector class detects the negative specification and issues an error message. However, the STL vector silently converts the negative value to a large positive value, because indices are represented as type size_t (unsigned long) rather than int.
• When an out-of-bounds error occurs, the existing vector prints an error message and aborts, whereas the STL vector throws an out-of-range object.

To change your code from using the existing stack to the STL stack, consider the following actions:

• Change the name of your #include statement from <vector.h> or <vector.hxx> to <stack>.
• Remove the stackdeclare and stackimplement declarations from your code.
• Change all stack(type) declarations to stack<type, deque<type> >. For example, stack(int) si should become stack<int, deque<int> > si.
• Do not specify an initial size for an STL stack. The stack must start out empty and grow dynamically (as you push and pop).
• The following member functions are not supported or have different semantics:

  Nonstandard Stack	STL Stack
  size_used()	Does not exist because the size() function always is equal to the size_used() function.
  full()	Does not exist because the stack always is full.
  pop()	Does not return the popped element. To simulate DEC C++ Class Library behavior, first get the element as the return type from the top() function and then call the pop() function. For example, change int i=s.pop(); to the following: int i=s.top(); s.pop();

• The STL stack differs from the DEC C++ Class Library stack in the way errors are detected. Unlike the nonstandard stack, you cannot overflow an STL stack because space is allocated dynamically as you push elements onto the stack. And if you underflow an STL stack, you will get a core dump instead of an error message.

The STL Tutorial and Reference Guide (the Guide) is based on the STL implementation provided by the Hewlett-Packard Company. Because the DEC C++ STL incorporates changes from the ANSI C++ draft, the two implementations differ slightly. Differences also exist because the DEC C++ compiler does not currently support all of the new language features specified in the ANSI C++ draft; refer to Section 6.3 for the list of missing language features. This section discusses the remaining differences.

6.4.3.1 Header File Names

The header file names shown in the STL Tutorial and Reference Guide differ from the DEC C++ header file names, as shown in the following table:

Names Used in the Guide	Names Supplied by DEC C++
algo.h	Divided into algorithm and numeric
deque.h	deque
function.h	functional
iterator.h	iterator
list.h	list
multiset.h	set
map.h	map
multimap.h	map
set.h	set
stack.h	Divided into stack and queue
vector.h	vector

6.4.3.2 STL Run-Time Support

The STL Tutorial and Reference Guide states that you need to compile the run-time .cpp files that are provided with the Hewlett-Packard implementation, such as random.cpp and tempbuf.cpp.

DEC C++ already provides this run-time support in an object library and automatically links this library into your application; therefore, you can ignore the Guide's comments about compiling this support.

6.4.3.3 Guide Examples Need to Be Modified

The STL Tutorial and Reference Guide contains many example programs. Appendix B of the Guide shows a World Wide Web address (active as of this printing) from which you can copy these example programs. Because of the differences outlined in the previous sections, these example programs must be modified to work with the DEC C++ STL. To perform the necessary modifications, DEC C++ provides the following script:

/usr/lib/cmplrs/cxx/update_stl_book_examples.sh

Before running this script, copy and prepare the example programs. Use the following steps as guidelines:

1. Determine whether you want to use the unzip or gunzip facility. For greater simplicity in preparing the example programs, use unzip.
   If neither unzip nor gunzip is available on your system, you can copy them from the following location:

   ftp://ftp.digital.com/pub/Alpha/apps

2. Copy the example programs from the following World Wide Web address specified in the Guide:

   http://www.aw.com/cp/musser-saini.html

   • If you will be using unzip, copy these files:

     diction.zip examples.zip

   • If you will be using gunzip, copy these files:

     diction.gz examples.taz

3. If you are using unzip, unzip the files into a directory as follows:

   unzip diction.zip unzip examples.zip

4. If you are using gunzip, unzip the files and unpack the examples into a directory as follows:

   gunzip diction.gz gunzip examples.taz tar -xvf examples.tar

   
   Because the resulting files have uppercase names, you will need to manually rename them to lowercase names.

5. Change your current working directory to the directory where the example programs exist, and execute the script to modify the files as follows:

   sh /usr/lib/cmplrs/cxx/update_stl_book_examples.sh

   Now that your example programs are ready, compile them with the following command:

   cxx -nopt -define_templates -writable_strings -I. ex.cpp

   To link ex17-01, you must compile screen.cpp and shape.cpp and link with the resulting object files.

   Note The header file, bstring.h, which is included with the example programs, is based on the string library as defined by an old version of the ANSI C++ draft. DIGITAL recommends that you do not use this header file and instead use the <string> header provided by DEC C++.

   6.4.3.4 Differences by Chapter

   This section describes functional differences between the DEC C++ STL and the STL Tutorial and Reference Guide by chapter.

   Chapter 6
   

   • The Guide does not discuss the specialization of vector, vector<bool>, which is in the ANSI C++ draft. See Section 6.3 for information about how the DEC C++ implementation handles the lack of a bool built-in type.
   • The DEC C++ STL supplies an assign() function, in addition to the assign() function specified in §6.1.7 of the Guide. The function that DEC C++ supplies has the following signature:

     assign(size_type position, const T& value)

     
     This function assigns value to the element at the position specified by the position argument.

   Chapter 18
   

   The DEC C++ STL description of the reverse_iterator type definition differs from the description in §18.9 of the Guide as follows:

   • The DEC C++ STL type definition of self has an extra Pointer argument as defined in the latest ANSI C++ draft:

     typedef reverse_iterator<RandomAccessIterator, T, Reference, Pointer, Distance> self;

   • This extra Pointer argument also occurs in the DEC C++ STL global functions: operator-, operator+, operator:=,=, and operator<.
   • The DEC C++ STL provides an additional member function: operator->.

   Chapter 19
   

   • Besides the member functions listed in §19.1.2 of the Guide, the DEC C++ STL provides the following member function:

     a.clear()

     
     This function erases all elements in the container.

   • Besides the member functions listed in §19.1.3 of the Guide, the DEC C++ STL provides the following member functions:

     a.assign(q1, q2)

     
     This function erases all the elements in the container and then inserts all elements in the range (q1, q2).

     a.assign(n, t)

     
     This function erases a[n] and inserts t at a[n].

   Chapter 20
   

   • The DEC C++ STL implementation of the for_each() function has a return type of Function and returns f.
   • The DEC C++ STL implementation of the rotate_copy() function has a return type of OutputIterator and returns the past-the-end iterator, result + last - first.

   Chapter 22
   

   • The Guide does not mention where allocator is declared. The DEC C++ STL places the declaration of allocator in the <memory> header.
   • See Section 6.3 for a description of how to customize allocators using the DEC C++ STL implementation.

   See also Section 6.5.5 for differences between the Guide string class and the DEC C++ Standard String Library.

   ---

   Previous

   Next

   Contents

   Index