libg++.texinfo

早期freebsd实现

@end table

Set, Bag, and PQ classes possess

@table @code
@item Pix j = a.add(x) (or a.enq(x) for priority queues)
add x to the collection, returning its Pix. The Pix of an item
can change in collections where further additions and deletions
involve the actual movement of elements (currently in OXPSet,
OXPBag, XPPQ, VOHSet), but in all other cases, an item's Pix may
be considered a permanent key to its location.
@end table

@node Headers, Builtin, Pix, Top
@chapter Header files for interfacing C++ to C

The following files are provided so that C++ programmers may
invoke common C library and system calls. The names and contents
of these files are subject to change in order to be compatible
with the forthcoming GNU C library. Other files, not listed
here, are simply C++-compatible interfaces to corresponding C
library files.

@table @file
@item values.h
A collection of constants defining the numbers of bits in builtin
types, minimum and maximum values, and the like. Most names are
the same as those found in @file{values.h} found on Sun systems.

@item std.h
A collection of common system calls and @file{libc.a} functions.
Only those functions that can be declared without introducing
new type definitions (socket structures, for example) are
provided. Common @code{char*} functions (like @code{strcmp}) are among
the declarations. All functions are declared along with their
library names, so that they may be safely overloaded.

@item string.h
This file merely includes @file{<std.h>}, where string function
prototypes are declared. This is a workaround for the fact that
system @file{string.h} and @file{strings.h} files often differ
in contents.

@item osfcn.h
This file merely includes @file{<std.h>}, where system function
prototypes are declared. 

@item libc.h
This file merely includes @file{<std.h>}, where C library function
prototypes are declared. 

@item math.h
A collection of prototypes for functions usually found in
libm.a, plus some @code{#define}d constants that appear to be
consistent with those provided in the AT&T version. The value
of @code{HUGE} should be checked before using. Declarations of
all common math functions are preceded with @code{overload}
declarations, since these are commonly overloaded.

@item stdio.h
Declaration of @code{FILE} (@code{_iobuf}), common macros (like
@code{getc}), and function prototypes for @file{libc.a}
functions that operate on @code{FILE*}'s. The value
@code{BUFSIZ} and the declaration of @code{_iobuf} should be
checked before using.

@item assert.h
C++ versions of assert macros.

@item generic.h
String concatenation macros useful in creating generic classes.
They are similar in function to the AT&T CC versions.

@item new.h
Declarations of the default global operator new, the two-argument
placement version, and associated error handlers.
@end table

@node Builtin, New, Headers, Top
@chapter Utility functions for built in types

Files @file{builtin.h} and corresponding @file{.cc} implementation
files contain various convenient
inline and non-inline utility functions. These include useful
enumeration types, such as @code{TRUE}, @code{FALSE} ,the type
definition for pointers to libg++ error handling functions, and
the following functions.

@table @code
@item long abs(long x); double abs(double x);
inline versions of abs. Note that the standard libc.a version,
@code{int abs(int)} is @emph{not} declared as inline.

@item void clearbit(long& x, long b);
clears the b'th bit of x (inline).

@item void setbit(long& x, long b);
sets the b'th bit of x (inline)

@item int testbit(long x, long b);
returns the b'th bit of x (inline).

@item int even(long y);
returns true if x is even (inline).

@item int odd(long y);
returns true is x is odd (inline).

@item int sign(long x); int sign(double x);
returns -1, 0, or 1, indicating whether x is less than, equal to, or
greater than zero (inline).

@item long gcd(long x, long y);
returns the greatest common divisor of x and y.

@item long lcm(long x, long y);
returns the least common multiple of x and y.

@item long lg(long x); 
returns the floor of the base 2 log of x.

@item long pow(long x, long y); double pow(double x, long y);
returns x to the integer power y using via the iterative O(log y)
``Russian peasant'' method.

@item long sqr(long x); double sqr(double x);
returns x squared (inline).

@item long sqrt(long y);
returns the floor of the square root of x.

@item unsigned int hashpjw(const char* s);
a hash function for null-terminated char* strings using the
method described in Aho, Sethi, & Ullman, p 436.

@item unsigned int multiplicativehash(int x);
a hash function for integers that returns the lower bits of 
multiplying x by the golden ratio times pow(2, 32). 
See Knuth, Vol 3, p 508.

@item unsigned int foldhash(double x);
a hash function for doubles that exclusive-or's the first and
second words of x, returning the result as an integer.

@item double start_timer()
Starts a process timer.

@item double return_elapsed_time(double last_time)
Returns the process time since last_time. 
If last_time == 0 returns the time since the last start_timer. 
Returns -1 if start_timer was not first called.

@end table

File @file{Maxima.h} includes versions of @code{MAX, MIN}
for builtin types.

File @file{compare.h} includes versions of @code{compare(x, y)}
for builtin types. These return negative if the first argument
is less than the second, zero for equal, and positive for greater.

@node New, IOStream, Builtin, Top
@chapter Library dynamic allocation primitives

Libg++ contains versions of @code{malloc, free, realloc} that were
designed to be well-tuned to C++ applications. The source file
@file{malloc.c} contains some design and implementation details.
Here are the major user-visible differences from most system
malloc routines:

@enumerate

@item
These routines @emph{overwrite} storage of freed space. This
means that it is never permissible to use a @code{delete}'d
object in any way. Doing so will either result in trapped
fatal errors or random aborts within malloc, free, or realloc.

@item
The routines tend to perform well when a large number
of objects of the same size are allocated and freed. You
may find that it is not worth it to create your
own special allocation schemes in such cases.

@item
The library sets top-level @code{operator new()} to call malloc and
@code{operator delete()} to call free. Of course, you may override these
definitions in C++ programs by creating your own operators that will
take precedence over the library versions. However, if you do so, be
sure to define @emph{both} @code{operator new()} and @code{operator
delete()}.

@item
These routines do @emph{not} support the odd convention, maintained by
some versions of malloc, that you may call @code{realloc} with a pointer
that has been @code{free}'d.

@item
The routines automatically perform simple checks on @code{free}'d
pointers that can often determine whether users have accidentally
written beyond the boundaries of allocated space, resulting in a fatal
error.

@item
The function @code{malloc_usable_size(void* p)} returns the number of
bytes actually allocated for @code{p}. For a valid pointer (i.e., one
that has been @code{malloc}'d or @code{realloc}'d but not yet
@code{free}'d) this will return a number greater than or equal to the
requested size, else it will normally return 0. Unfortunately, a
non-zero return can not be an absolutely perfect indication of lack of
error. If a chunk has been @code{free}'d but then re-allocated for a
different purpose somewhere elsewhere, then @code{malloc_usable_size}
will return non-zero. Despite this, the function can be very valuable
for performing run-time consistency checks.

@item
@code{malloc} requires 8 bytes of overhead per allocated chunk, plus a
mmaximum alignment adjustment of 8 bytes. The number of bytes of usable
space is exactly as requested, rounded to the nearest 8 byte boundary.

@item
The routines do @emph{not} contain any synchronization support for
multiprocessing. If you perform global allocation on a shared
memory multiprocessor, you should disable compilation and use
of libg++ malloc in the distribution @file{Makefile} and use your
system version of malloc.

@end enumerate

@node IOStream, Stream, New, Top
@chapter The new input/output classes

The iostream classes implement most of the features of AT&T
version 2.0 iostream library classes, and most of the features
of the ANSI X3J16 library draft (which is based on the AT&T design).
The iostream classes replace all of the old stream classes
in previous versions of libg++.  It is not totally compatible,
so you will probably need to change your code in places.

@c (THIS CHAPTER NEEDS WORK!  -FIXME)

@section The @code{streambuf} layer

The lower level abstraction is the @code{streambuf} layer.
A @code{streambuf} (or one of the classes derived from it)
implements a character source and/or sink, usually with buffering.

Classes derived from @code{streambuf} include:
@itemize @bullet

@item
A @code{filebuf} is used for reading and writing from files.

@item
A @code{strstreambuf} can read and write from a string in main memory.
The string buffer will be re-allocated as needed it, unless it is ``frozen''.

@item
An @code{indirectbuf} just forwards all read/write
requests to some other buffer.
	
@item
A @code{procbuf} can read from or write to a Unix process.

@item
A @code{parsebuf} has some useful features for scanning
text:  It keeps track of line and column numbers, and it
guarantees to remember at least the current line (with the
linefeeds at either end), so you can arbitrarily backup
within that time.  WARNING:  The interface is likely to change.

@item
An @code{edit_streambuf} reads and writes into a region of an
@code{edit_buffer} called an @code{edit_string}.  Emacs-like marks are
supported, and sub-strings are first-class functions.  WARNING: The
interface is almost certain to change.
@end itemize

@section The istream and ostream classes

The stream layer provides an efficient, easy-to-use, and type-secure
interface between C++ and an underlying @code{streambuf}.

Most C++ textbooks will at least given an overview of
the stream classes.  Some libg++ specifics:
@table @code
@item istream::get(char* s, int maxlength, char terminator='\n')
Behaves as described by Stroustrup. It reads at most maxlength characters
into s, stopping when the terminator is read, and pushing the
terminator back into the input stream.

@item istream::getline(char* s, int maxlength, char terminator = '\n')
Behaves like get, except that the terminator is read (and not pushed back),
though it does not become part of the string.

@item istream::gets(char** ss, char terminator = '\n')
reads in a line (as in get) of unknown length, and places
it in a free-store allocated spot and attaches it to @code{ss}. The
programmer must take responsibility for deleting @code{*ss}
when it is no longer needed.

@item ostream::form(const char* format...)
outputs @code{printf}-formated data.
@end table

@section The SFile class

@code{SFile} (short for structure file) is provided both as a demonstration
of how to build derived classes from @code{iostream}, and as a useful class for
processing files containing fixed-record-length binary data.  They are
created with constructors with one additional argument declaring the size
(in bytes, i.e., @code{sizeof} units) of the records.  @code{get}, will
input one record, @code{put} will output one, and the @code{[]} operator,
as in @code{f[i]}, will position to the i'th record. If the file is being
used mainly for random access, it is often a good idea to eliminate
internal buffering via @code{setbuf} or @code{raw}. Here is an example:

@smallexample            
class record
@{
  friend class SFile;
  char c; int i; double d;     // or anything at all
@};

void demo()