libg++.texinfo

早期freebsd实现

to pass by value. SO you should pick by-reference.

You can now create @file{Person.defs.h} via @code{genclass Person ref defs}.
This creates a simple skeleton that you must edit. First, add
@code{#include "Person.h"} to the top. Second, edit the @code{<T>CMP(a,b)}
macro to compare on name, via

@example
#define <T>CMP(a, b) ( compare(a.name(), b.name()) )
@end example

@noindent
which invokes the @code{int compare(const String&, const String&)}
function from @file{String.h}. Of course, you could define this in any
other way as well. In fact, the default versions in the skeleton turn
out to be OK (albeit inefficient) in this particular example.

You may also want to create file @file{SSN.defs.h}. Here, choosing
call-by-value makes sense, and since no other capabilities (like
comparison functions) of the SSNs are used (and the defaults are OK
anyway), you'd type

@example
genclass SSN val defs
@end example

@noindent
and then edit to place @code{#include "SSN.h"} at the top.

Finally, you can generate the classes. First, generate the base
class for Maps via

@example
genclass -2 Person ref SSN val Map
@end example

@noindent
This generates only the abstract class, not the implementation, in file
@file{Person.SSN.Map.h} and @file{Person.SSN.Map.cc}.  To create the
AVL implementation, type

@example
genclass -2 Person ref SSN val AVLMap
@end example

@noindent
This creates the class @code{PersonSSNAVLMap}, in
@file{Person.SSN.AVLMap.h} and @file{Person.SSN.AVLMap.cc}.

To use the AVL implementation, compile the two generated @file{.cc} files, and
specify @samp{#include "Person.SSN.AVLMap.h"} in the application program.
All other files are included in the right ways automatically.

One last consideration, peculiar to Maps, is to pick a reasonable
default contents when declaring an AVLMap. Zero might be appropriate
here, so you might declare a Map,

@example
PersonSSNAVLMap m((SSN)0);
@end example

Suppose you wanted a @code{VHMap} instead of an @code{AVLMap} Besides
generating different implementations, there are two differences in
how you should prepare the @file{defs} file. First, because a VHMap
uses a C++ array internally, and because C++ array slots are initialized
differently than single elements, you must ensure that class Person
contains (1) a no-argument constructor, and (2) an assignment operator.
You could arrange this via

@smallexample
class Person 
@{ ...; 
    Person() @{@}
  void operator = (const Person& p) @{ nm = p.nm; addr = p.addr; @}
@};
@end smallexample

(The lack of action in the constructor is OK here because @code{Strings}
possess usable no-argument constructors.)

You also need to edit @file{Person.defs.h} to indicate a usable hash
function and default capacity, via something like

@example
#include <builtin.h>
#define <T>HASH(x)  (hashpjw(x.name().chars()))
#define DEFAULT_INITIAL_CAPACITY 1000
@end example

Since the @code{hashpjw} function from @file{builtin.h} is
appropriate here. Changing the default capacity to a value
expected to exceed the actual capacity helps to avoid
``hidden'' inefficiencies when a new VHMap is created without
overriding the default, which is all too easy to do.

Otherwise, everything is the same as above, substituting
@code{VHMap} for @code{AVLMap}.

@node Representations, Expressions, Proto, Top
@chapter Variable-Sized Object Representation

One of the first goals of the GNU C++ library is to enrich the kinds of
basic classes that may be considered as (nearly) ``built into'' C++. A good
deal of the inspiration for these efforts is derived from considering
features of other type-rich languages, particularly Common Lisp and Scheme.
The general characteristics of most class and friend operators and
functions supported by these classes has been heavily influenced
by such languages.

Four of these types, Strings, Integers, BitSets, and BitStrings (as well as
associated and/or derived classes) require representations suitable for
managing variable-sized objects on the free-store. The basic technique used
for all of these is the same, although various details necessarily differ
from class to class.

The general strategy for representing such objects is to create chunks of
memory that include both header information (e.g., the size of the object),
as well as the variable-size data (an array of some sort) at the end
of the chunk. Generally the maximum size of an object is limited to
something less than all of addressable memory, as a safeguard. The minimum
size is also limited so as not to waste allocations expanding very small
chunks. Internally, chunks are allocated in blocks well-tuned to the
performance of the @code{new} operator.

Class elements themselves are merely pointers to these chunks.
Most class operations are performed via inline ``translation''
functions that perform the required operation on the corresponding
representation. However, constructors and assignments operate by
copying entire representations, not just pointers.


No attempt is made to control temporary creation in expressions
and functions involving these classes. Users of previous versions
of the classes will note the disappearance of both ``Tmp'' classes
and reference counting. These were dropped because, while they
did improve performance in some cases, they obscure class
mechanics, lead programmers into the false belief that they need not
worry about such things, and occasionally have paradoxical behavior.


These variable-sized object classes are integrated as well as possible
into C++. Most such classes possess converters that allow automatic
coercion both from and to builtin basic types. (e.g., char* to and from
String, long int to and from Integer, etc.). There are pro's and con's
to circular converters, since they can sometimes lead to the conversion
from a builtin type through to a class function and back to a builtin
type without any special attention on the part of the programmer, both
for better and worse.

Most of these classes also provide special-case operators and functions
mixing basic with class types, as a way to avoid constructors in cases
where the operations do not rely on anything special about the
representations.  For example, there is a special case concatenation
operator for a String concatenated with a char, since building the
result does not rely on anything about the String header. Again, there
are arguments both for and against this approach. Supporting these cases
adds a non-trivial degree of (mainly inline) function proliferation, but
results in more efficient operations. Efficiency wins out over parsimony
here, as part of the goal to produce classes that provide sufficient
functionality and efficiency so that programmers are not tempted to try
to manipulate or bypass the underlying representations.

@node Expressions, Pix, Representations,  Top
@chapter Some guidelines for using expression-oriented classes


The fact that C++ allows operators to be overloaded for user-defined
classes can make programming with library classes like @code{Integer},
@code{String}, and so on very convenient. However, it is worth
becoming familiar with some of the inherent limitations and problems
associated with such operators.

Many operators are @emph{constructive}, i.e., create a new object
based on some function of some arguments. Sometimes the creation
of such objects is wasteful. Most library classes supporting
expressions contain facilities that help you avoid such waste.

For example, for @code{Integer a, b, c; ...;  c = a + b + a;}, the
plus operator is called to sum a and b, creating a new temporary object
as its result. This temporary is then added with a, creating another
temporary, which is finally copied into c, and the temporaries are then
deleted. In other words, this code might have an effect similar to
@code{Integer a, b, c; ...; Integer t1(a); t1 += b; Integer t2(t1);
t2 += a; c = t2;}.

For small objects, simple operators, and/or non-time/space critical
programs, creation of temporaries is not a big problem. However, often,
when fine-tuning a program, it may be a good idea to rewrite such
code in a less pleasant, but more efficient manner.

For builtin types like ints, and floats, C and C++ compilers already
know how to optimize such expressions to reduce the need for
temporaries. Unfortunately, this is not true for C++ user defined
types, for the simple (but very annoying, in this context) reason that
nothing at all is guaranteed about the semantics of overloaded operators
and their interrelations. For example, if the above expression just
involved ints, not Integers, a compiler might internally convert the
statement into something like @code{ c += a; c += b; c+= a; }, or
perhaps something even more clever.  But since C++ does not know that
Integer operator += has any relation to Integer operator +, A C++
compiler cannot do this kind of expression optimization itself.

In many cases, you can avoid construction of temporaries simply by
using the assignment versions of operators whenever possible, since
these versions create no temporaries. However, for maximum flexibility,
most classes provide a set of ``embedded assembly code'' procedures
that you can use to fully control time, space, and evaluation strategies.
Most of these procedures are ``three-address'' procedures that take
two @code{const} source arguments, and a destination argument. The
procedures perform the appropriate actions, placing the results in
the destination (which is may involve overwriting old contents). These
procedures are designed to be fast and robust. In particular, aliasing
is always handled correctly, so that, for example
@code{add(x, x, x); } is perfectly OK. (The names of these procedures
are listed along with the classes.)

For example, suppose you had an Integer expression
@code{ a = (b - a) * -(d / c); }

This would be compiled as if it were
@code{ Integer t1=b-a; Integer t2=d/c; Integer t3=-t2; Integer t4=t1*t3; a=t4;}

But, with some manual cleverness, you might yourself some up with
@code{ sub(a, b, a); mul(a, d, a); div(a, c, a); }


A related phenomenon occurs when creating your own constructive
functions returning instances of such types. Suppose you wanted
to write function 
@code{Integer f(const Integer& a) @{ Integer r = a;  r += a; return r; @}}

This function, when called (as in @code{ a = f(a); }) demonstrates a 
similar kind of wasted copy. The returned value r must be copied
out of the function before it can be used by the caller. In GNU
C++, there is an alternative via the use of named return values.
Named return values allow you to manipulate the returned object
directly, rather than requiring you to create a local inside
a function and then copy it out as the returned value. In this
example, this can be done via
@code{Integer f(const Integer& a) return r(a) @{ r += a; return; @}}


A final guideline: The overloaded operators are very convenient, and
much clearer to use than procedural code. It is almost always a good
idea to make it right, @emph{then} make it fast, by translating 
expression code into procedural code after it is known to be correct.



@node Pix, Headers, Expressions, Top
@chapter Pseudo-indexes

Many useful classes operate as containers of elements. Techniques for
accessing these elements from a container differ from class to class.
In the GNU C++ library, access methods have been partially standardized
across different classes via the use of pseudo-indexes called
@code{Pixes}.  A @code{Pix} acts in some ways like an index, and in some
ways like a pointer. (Their underlying representations are just
@code{void*} pointers). A @code{Pix} is a kind of ``key'' that is
translated into an element access by the class.  In virtually all cases,
@code{Pixes} are pointers to some kind internal storage cells. The
containers use these pointers to extract items.

@code{Pixes} support traversal and inspection of elements in a
collection using analogs of array indexing. However, they are
pointer-like in that @code{0} is treated as an invalid @code{Pix}, and
unsafe insofar as programmers can attempt to access nonexistent elements
via dangling or otherwise invalid @code{Pixes} without first checking
for their validity. 

In general it is a very bad idea to perform traversals in the the midst
of destructive modifications to containers.

Typical applications might include code using the idiom
@example
for (Pix i = a.first(); i != 0; a.next(i)) use(a(i));
@end example
for some container @code{a} and function @code{use}.

Classes supporting the use of @code{Pixes} always contain the following 
methods, assuming a container @code{a} of element types of @code{Base}.

@table @code

@item Pix i = a.first()
Set i to index the first element of a or 0 if a is empty.

@item a.next(i)
advance i to the next element of a or 0 if there is no next element;

@item Base x = a(i); a(i) = x;
a(i) returns a reference to the element indexed by i.

@item int present = a.owns(i)
returns true if Pix i is a valid Pix in a. This is often a
relatively slow operation, since the collection must usually 
traverse through elements to see if any correspond to the Pix.

@end table

Some container classes also support backwards traversal via

@table @code
@item Pix i = a.last()
Set i to the last element of a or 0 if a is empty.

@item a.prev(i)
sets i to the previous element in a, or 0 if there is none.
@end table

Collections supporting elements with an equality operation possess

@table @code
@item Pix j = a.seek(x)
sets j to the index of the first occurrence of x, or 0 if x is 
not contained in a.
@end table

Bag classes possess

@table @code
@item Pix j = a.seek(x, Pix from = 0)
sets j to the index of the next occurrence of x following i,
or 0 if x is not contained in a. If i == 0, the first occurrence 
is returned.