libg++.texinfo

早期freebsd实现

\input texinfo  @c -*-texinfo-*-

@settitle User's Guide to the GNU C++ Class Library
@setfilename libg++.info

@ifinfo
@format
START-INFO-DIR-ENTRY
* Libg++: (libg++).		The g++ library.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
This file documents the features and implementation of The GNU C++ library

Copyright (C) 1988, 1991, 1992 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through @TeX{} and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU Library General Public License'' is included exactly as
in the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU Library General Public License'' and
this permission notice may be included in translations approved by the
Free Software Foundation instead of in the original English.
@end ifinfo

@iftex
@finalout
@c @smallbook
@c @cropmarks
@end iftex

@setchapternewpage odd

@titlepage
@title User's Guide
@title to the GNU C++ Library
@sp 3
@subtitle last updated April 29, 1992
@subtitle for version 2.0
@author Doug Lea (dl@@g.oswego.edu)
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988, 1991, 1992 Free Software Foundation, Inc.


Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU Library General Public License'' is included exactly as
in the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU Library General Public License'' may be
included in a translation approved by the author instead of in the original
English.

@strong{Note: The GNU C++ library is still in test release. You will
be performing a valuable service if you report any bugs you encounter.}

@end titlepage

@ifinfo
@node Top, Copying, , (DIR)

Introduction
************

This manual documents how to install and use the GNU C++ library.

@end ifinfo
@menu
* Copying::	    GNU Library Public License says how you can copy
                    and share the GNU C++ library.
* Contributors::    People who have contributed to GNU C++ library.
* Installation::    How to configure, compile and install GNU C++ library
* Trouble::         If you have trouble installing GNU C++ library.
* General::         Aims, objectives, and limitations of the GNU C++ library
* Conventions::     Stylistic conventions
* OK::              Support for representation invariants
* Proto::           Introduction to container class prototypes
* Pix::             Pseudo-indexes
* Representations:: How variable-sized objects are represented
* Expressions::     Some guidance on programming expression-oriented classes
* Headers::         Header files and other support for interfacing C++ to C
* Builtin::         Utility functions for builtin types
* New::             Library dynamic allocation primitives
* IOStream::        input/output library (istreams and ostreams
* Stream::          obsolete I/O library
* Obstack::         Obstacks and their uses.
* AllocRing::       A place to store objects for a while
* String::          String, SubString, and Regex classes.
* Integer::         Multiple precision Integer class.
* Rational::        Multiple precision Rational class
* Complex::         Complex number class
* Fix::             Fixed point proportion classes
* Bit::             BitSet and BitString classes
* Random::          Random number generators
* Data::            SampleStatistic and related classes for data collection
* Curses::          CursesWindow class
* List::            Lisp-like List prototype
* LinkList::        Singly and doubly linked list class prototypes
* Vector::          Vector prototypes
* Plex::            Plex (adjustable array) prototypes
* Stack::           Stack prototypes
* Queue::           Queue prototypes
* Deque::           Double ended queue prototypes
* PQ::              Heap (priority queue) class prototypes
* Set::             Set class prototypes
* Bag::             Bag class prototypes
* Map::             Map (Associative array) prototypes
* GetOpt::          C++ class-based version of the GNU/UNIX getopt function
* Projects::	    Things Still Left to do
@end menu

@node Copying, Contributors, Top, Top
@include lgpl.texinfo

@node Contributors, Installation, Copying, Top
@unnumbered Contributors to GNU C++ library

Aside from Michael Tiemann, who worked out the front end for GNU C++, and
Richard Stallman, who worked out the back end, the following people (not
including those who have made their contributions to GNU CC) should not go
unmentioned.

@itemize @bullet
@item
Doug Lea contributed most otherwise unattributed classes.

@item
Per Bothner contributed the iostream I/O classes.

@item 
Dirk Grunwald contributed the Random number generation classes,
and PairingHeaps.

@item 
Kurt Baudendistel contributed Fixed precision reals.

@item 
Doug Schmidt contributed ordered hash tables, a perfect
hash function generator, and several other utilities.

@item
Marc Shapiro contributed the ideas and preliminary code for Plexes.

@item
Eric Newton contributed the curses window classes.

@item
Some of the I/O code is derived from BSD 4.4,
and was developed by the University of California, Berkeley.

@item
The code for converting accurately between floating point numbers
and their string representations was written by David M. Gay of AT&T.
@end itemize

@node Installation, Trouble, Contributors, Top
@chapter Installing GNU C++ library


@enumerate
@item
Read through the README file and the Makefile. Make sure that all
paths, system-dependent compile switches, and program names are correct.

@item
Check that files  @file{values.h}, @file{stdio.h},
and @file{math.h} declare and define values appropriate for your
system.

@item
Type @samp{make all} to compile the library, test, and install.
Current details about contents of the tests and utilities are in the 
@file{README} file.

@end enumerate

@node Trouble, General, Installation, Top
@chapter Trouble in Installation

Here are some of the things that have caused trouble for people installing
GNU C++ library.

@enumerate
@item
Make sure that your GNU C++ version number is at least as high as your
libg++ version number. For example, libg++ 1.22.0 requires g++ 1.22.0 or
later releases.

@item
Double-check system constants in the header files mentioned above.

@end enumerate

@node General, Conventions, Trouble, Top
@chapter GNU C++ library aims, objectives, and limitations

The GNU C++ library, libg++ is an attempt to provide a variety of C++
programming tools and other support to GNU C++ programmers.

Differences in distribution policy are only part of the difference
between libg++.a and AT&T libC.a.  libg++ is not intended to be an
exact clone of libC. For one, libg++ contains bits of code that depend
on special features of GNU g++ that are either different or lacking in
the AT&T version, including slightly different inlining and overloading
strategies, dynamic local arrays, wrappers, etc.  All of these
differences are minor. For example, while the AT&T and GNU stream
classes are implemented in very different ways, the vast majority of
C++ programs compile and run under either version with no visible
difference. Additionally, all g++-specific constructs are conditionally
compiled; The library is designed to be compatible with any 2.0 C++
compiler.

libg++ has also contained workarounds for some limitations in g++: both
g++ and libg++ are still undergoing rapid development and testing---a
task that is helped tremendously by the feedback of active users.  This
manual is also still under development; it has some catching up to do
to include all the facilities now in the library.

libg++ is not the only freely available source of C++ class libraries.
The most notable alternative sources are Interviews and OOPS. (A
g++-compatible version of OOPS is currently available on prep.ai.mit.edu.
InterViews has been available on the X-windows X11 tapes and also
from interviews.stanford.edu.)

As every C++ programmer knows, the design (moreso than the
implementation) of a C++ class library is something of a challenge.
Part of the reason is that C++ supports two, partially incompatible,
styles of object-oriented programming -- The "forest" approach,
involving a collection of free-standing classes that can be mixed and
matched, versus the completely hierarchical (smalltalk style)
approach, in which all classes are derived from a common ancestor.  Of
course, both styles have advantages and disadvantages.  So far, libg++
has adopted the "forest" approach.  Keith Gorlen's OOPS library adopts
the hierarchical approach, and may be an attractive alternative for C++
programmers who prefer this style.

Currently (and/or in the near future) libg++ provides support for a
few basic kinds of classes:

The first kind of support provides an interface between C++ programs and
C libraries. This includes basic header files (like @file{stdio.h}) as
well as things like the File and stream classes. Other classes that
interface to other aspects of C libraries (like those that maintain
environmental information) are in various stages of development; all
will undergo implementation modifications when the forthcoming GNU libc
library is released.

The second kind of support contains general-purpose basic classes that
transparently manage variable-sized objects on the freestore.  This
includes Obstacks, multiple-precision Integers and Rationals,
arbitrary length Strings, BitSets, and BitStrings.

Third, several classes and utilities of common interest (e.g.,
Complex numbers) are provided.

Fourth, a set of pseudo-generic prototype files are available
as a mechanism for generating common container classes. These
are described in more detail in the introduction to container
prototypes. Currently, only a textual substitution
mechanism is available for generic class creation.

@node Conventions, OK, General, Top
@chapter GNU C++ library stylistic conventions

@itemize @bullet

@item
C++ source files have file extension @file{.cc}. Both C-compatibility
header files and class declaration files have extension @file{.h}.

@item
C++ class names begin with capital letters, except for @code{istream}
and @code{ostream}, for AT&T C++ compatibility. Multi-word class
names capitalize each word, with no underscore separation.

@item 
Include files that define C++ classes begin with capital letters
(as do the names of the classes themselves).  @file{stream.h} is
uncapitalized for AT&T C++ compatibility.  

@item 
Include files that supply function prototypes for other C
functions (system calls and libraries) are all lower case.

@item 
All include files define a preprocessor variable _X_h, where X
is the name of the file, and conditionally compile only if this
has not been already defined. The @code{#pragma once} facility
is also used to avoid re-inclusion.

@item
Structures and objects that must be publicly defined,
but are not intended for public use have names beginning
with an underscore. (for example, the @code{_Srep} struct, which
is used only by the String and SubString classes.)

@item
The underscore is used to separate components of long function
names, @*e.g., @code{set_File_exception_handler()}.