Fresh Fish 4/FreshFish_May-June1994.bin/gnu/info/libg++.info-2

GNU Info File | 1994-02-27 | 50KB | 912 lines

This is Info file libg++.info, produced by Makeinfo-1.55 from the input
file ./libg++.texi.
START-INFO-DIR-ENTRY
* Libg++::                      The g++ class library.
END-INFO-DIR-ENTRY
   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.
   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.
File: libg++.info,  Node: Proto,  Next: Representations,  Prev: OK,  Up: Top
Introduction to container class prototypes
******************************************
   As a temporary mechanism enabling the support of generic classes,
the GNU C++ Library distribution contains a directory (`g++-include')
of files designed to serve as the basis for generating container
classes of specified elements.  These files can be used to generate
`.h' and `.cc' files in the current directory via a supplied shell
script program that performs simple textual substitution to create
specific classes.
   While these classes are generated independently, and thus share no
code, it is possible to create versions that do share code among
subclasses. For example, using `typedef void* ent', and then generating
a `entList' class, other derived classes could be created using the
`void*' coercion method described in Stroustrup, pp204-210.
   This very simple class-generation facility is useful enough to serve
current purposes, but will be replaced with a more coherent mechanism
for handling C++ generics in a way that minimally disrupts current
usage.  Without knowing exactly when or how parametric classes might be
added to the C++ language, provision of this simplest possible
mechanism, textual substitution, appears to be the safest strategy,
although it does require certain redundancies and awkward constructions.
   Specific classes may be generated via the `genclass' shell script
program. This program has arguments specifying the kinds of base
types(s) to be used. Specifying base types requires two arguments. The
first is the name of the base type, which may be any named type, like
`int' or `String'. Only named types are supported; things like `int*'
are not accepted. However, pointers like this may be used by supplying
the appropriate typedefs (e.g., editing the resulting files to include
`typedef int* intp;'). The type name must be followed by one of the
words `val' or `ref', to indicate whether the base elements should be
passed to functions by-value or by-reference.
   You can specify basic container classes using `genclass base
[val,ref] proto', where `proto' is the name of the class being
generated.  Container classes like dictionaries and maps that require
two types may be specified via `genclass -2 keytype [val, ref],
basetype [val, ref] proto', where the key type is specified first and
the contents type second.  The resulting classnames and filenames are
generated by prepending the specified type names to the prototype names,
and separating the filename parts with dots.  For example, `genclass
int val List' generates class `intList' residing in files `int.List.h'
and `int.List.cc'. `genclass -2 String ref int val VHMap' generates
(the awkward, but unavoidable) class name `StringintVHMap'. Of course,
programmers may use `typedef' or simple editing to create more
appropriate names.  The existence of dot seperators in file names
allows the use of GNU make to help automate configuration and
recompilation. An example Makefile exploiting such capabilities may be
found in the `libg++/proto-kit' directory.
   The `genclass' utility operates via simple text substitution using
`sed'. All occurrences of the pseudo-types `<T>' and `<C>' (if there
are two types) are replaced with the indicated type, and occurrences of
`<T&>' and `<C&>' are replaced by just the types, if `val' is
specified, or types followed by "&" if `ref' is specified.
   Programmers will frequently need to edit the `.h' file in order to
insert additional `#include' directives or other modifications.  A
simple utility, `prepend-header' to prepend other `.h' files to
generated files is provided in the distribution.
   One dubious virtue of the prototyping mechanism is that, because
sources files, not archived library classes, are generated, it is
relatively simple for programmers to modify container classes in the
common case where slight variations of standard container classes are
required.
   It is often a good idea for programmers to archive (via `ar')
generated classes into `.a' files so that only those class functions
actually used in a given application will be loaded.  The test
subdirectory of the distribution shows an example of this.
   Because of `#pragma interface' directives, the `.cc' files should be
compiled with `-O' or `-DUSE_LIBGXX_INLINES' enabled.
   Many container classes require specifications over and above the base
class type. For example, classes that maintain some kind of ordering of
elements require specification of a comparison function upon which to
base the ordering.  This is accomplished via a prototype file `defs.hP'
that contains macros for these functions. While these macros default to
perform reasonable actions, they can and should be changed in
particular cases. Most prototypes require only one or a few of these.
No harm is done if unused macros are defined to perform nonsensical
actions. The macros are:
`DEFAULT_INITIAL_CAPACITY'
     The initial capacity for containers (e.g., hash tables) that
     require an initial capacity argument for constructors.  Default:
     100
`<T>EQ(a, b)'
     return true if a is considered equal to b for the purposes of
     locating, etc., an element in a container.  Default: (a == b)
`<T>LE(a, b)'
     return true if a is less than or equal to b Default: (a <= b)
`<T>CMP(a, b)'
     return an integer < 0 if a<b, 0 if a==b, or > 0 if a>b.  Default:
     (a <= b)? (a==b)? 0 : -1 : 1
`<T>HASH(a)'
     return an unsigned integer representing the hash of a.  Default:
     hash(a) ; where extern unsigned int hash(<T&>).  (note: several
     useful hash functions are declared in builtin.h and defined in
     hash.cc)
   Nearly all prototypes container classes support container traversal
via `Pix' pseudo indices, as described elsewhere.
   All object containers must perform either a `X::X(X&)' (or `X::X()'
followed by `X::operator =(X&)') to copy objects into containers.  (The
latter form is used for containers built from C++ arrays, like
`VHSets'). When containers are destroyed, they invoke `X::~X()'.  Any
objects used in containers must have well behaved constructors and
destructors. If you want to create containers that merely reference
(point to) objects that reside elsewhere, and are not copied or
destroyed inside the container, you must use containers of pointers,
not containers of objects.
   All prototypes are designed to generate *HOMOGENOUS* container
classes.  There is no universally applicable method in C++ to support
heterogenous object collections with elements of various subclasses of
some specified base class. The only way to get heterogenous structures
is to use collections of pointers-to-objects, not collections of objects
(which also requires you to take responsibility for managing storage for
the objects pointed to yourself).
   For example, the following usage illustrates a commonly encountered
danger in trying to use conta