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" may be included in a translation approved by the author instead of in the original English.
Note: The GNU C++ library is still in test release. You will be performing a valuable service if you report any bugs you encounter.
Copyright (C) 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.]
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users.
This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it.
For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights.
Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library.
Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license.
The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such.
Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better.
However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries.
The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library.
Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one.
A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.
The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".)
"Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
(For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.
In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of the Library into a program that is not a library.
If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.
However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.
You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:
For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.
If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).
To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the library's name and an idea of what it does. Copyright (C) year name of author This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. signature of Ty Coon, 1 April 1990 Ty Coon, President of Vice
That's all there is to it!
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.
Here are some of the things that have caused trouble for people installing GNU C++ library.
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, 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. Some notable alternative sources are Interviews and NIHCL. (InterViews has been available on the X-windows X11 tapes and also from interviews.stanford.edu. NIHCL is available by anonymous ftp from GNU archives (such as the pub directory of prep.ai.mit.edu), although it is not supported by the FSF - and needs some work before it will work with g++.)
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 `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.
istream
and ostream, for AT&T C++ compatibility. Multi-word class
names capitalize each word, with no underscore separation.
#pragma once facility
is also used to avoid re-inclusion.
_Srep struct, which
is used only by the String and SubString classes.)
set_File_exception_handler().
error(char* msg)
that invokes an associated error handler function via a pointer to that
function, so that the error handling function may be reset by
programmers. By default nearly all call *lib_error_handler, which
prints the message and then aborts execution. This system is subject
to change. In general, errors are assumed to be non-recoverable:
Library classes do not include code that allows graceful continuation
after exceptions.
Most GNU C++ library classes possess a method named OK(),
that is useful in helping to verify correct performance of class
operations.
The OK() operations checks the "representation invariant" of a
class object. This is a test to check whether the object is in a valid
state. In effect, it is a (sometimes partial) verification of the
library's promise that (1) class operations always leave objects in
valid states, and (2) the class protects itself so that client functions
cannot corrupt this state.
While no simple validation technique can assure that all operations
perform correctly, calls to OK() can at least verify that
operations do not corrupt representations. For example for String
a, b, c; ... a = b + c;, a call to a.OK(); will guarantee that
a is a valid String, but does not guarantee that it
contains the concatenation of b + c. However, given that a
is known to be valid, it is possible to further verify its properties,
for example via a.after(b) == c && a.before(c) == b. In other
words, OK() generally checks only those internal representation
properties that are otherwise inaccessible to users of the class. Other
class operations are often useful for further validation.
Failed calls to OK() call a class's error method if
one exists, else directly call abort. Failure indicates
an implementation error that should be reported.
With only rare exceptions, the internal support functions for a class
never themselves call OK() (although many of the test files
in the distribution call OK() extensively).
Verification of representational invariants can sometimes be very time consuming for complicated data structures.
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
<T>EQ(a, b)
<T>LE(a, b)
<T>CMP(a, b)
<T>HASH(a)
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 container classes for heterogenous structures:
class Base { int x; ...}
class Derived : public Base { int y; ... }
BaseVHSet s; // class BaseVHSet generated via something like
// `genclass Base ref VHSet'
void f()
{
Base b;
s.add(b); // OK
Derived d;
s.add(d); // (CHOP!)
}
At the line flagged with `(CHOP!)', a Base::Base(Base&) is
called inside Set::add(Base&)---not
Derived::Derived(Derived&). Actually, in VHSet, a
Base::operator =(Base&), is used instead to place the element in
an array slot, but with the same effect. So only the Base part is
copied as a VHSet element (a so-called chopped-copy). In this
case, it has an x part, but no y part; and a Base, not
Derived, vtable. Objects formed via chopped copies are rarely
sensible.
To avoid this, you must resort to pointers:
typedef Base* BasePtr;
BasePtrVHSet s; // class BaseVHSet generated via something like
// `genclass BasePtr val VHSet'
void f()
{
Base* bp = new Base;
s.add(b);
Base* dp = new Derived;
s.add(d); // works fine.
// Don't forget to delete bp and dp sometime.
// The VHSet won't do this for you.
}
The prototypes can be difficult to use on first attempt. Here is an example that may be helpful. The utilities in the `proto-kit' simplify much of the actions described, but are not used here.
Suppose you create a class Person, and want to make an Map that
links the social security numbers associated with each person. You start
off with a file `Person.h'
#include <String.h>
class Person
{
String nm;
String addr;
//...
public:
const String& name() { return nm; }
const String& address() { return addr; }
void print() { ... }
//...
}
And in file `SSN.h',
typedef unsigned int SSN;
Your first decision is what storage/usage strategy to use. There are several reasonable alternatives here: You might create an "object collection" of Persons, a "pointer collection" of pointers-to-Persons, or even a simple String map, housing either copies of pointers to the names of Persons, since other fields are unused for purposes of the Map. In an object collection, instances of class Person "live" inside the Map, while in a pointer collection, the instances live elsewhere. Also, as above, if instances of subclasses of Person are to be used inside the Map, you must use pointers. In a String Map, the same difference holds, but now only for the name fields. Any of these choices might make sense in particular applications.
The second choice is the Map implementation strategy. Either a tree
or a hash table might make sense. Suppose you want an AVL tree Map.
There are two things to now check. First, as an object collection,
the AVLMap requires that the elsement class contain an X(X&)
constructor. In C++, if you don't specify such a constructor, one
is constructed for you, but it is a very good idea to always do this
yourself, to avoid surprises. In this example, you'd use something like
class Person
{ ...;
Person(const Person& p) :nm(p.nm), addr(p.addr) {}
};
Also, an AVLMap requires a comparison function for elements in order to maintain order. Rather than requiring you to write a particular comparison function, a `defs' file is consulted to determine how to compare items. You must create and edit such a file.
Before creating `Person.defs.h', you must first make one additional
decision. Should the Map member functions like m.contains(p)
take arguments (p) by reference (i.e., typed as
int Map::contains(const Person& p) or by value (i.e., typed as
int Map::contains(const Person p). Generally, for user-defined
classes, you want to pass by reference, and for builtins and pointers,
to pass by value. SO you should pick by-reference.
You can now create `Person.defs.h' via genclass Person ref defs.
This creates a simple skeleton that you must edit. First, add
#include "Person.h" to the top. Second, edit the <T>CMP(a,b)
macro to compare on name, via
#define <T>CMP(a, b) ( compare(a.name(), b.name()) )
which invokes the int compare(const String&, const String&)
function from `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 `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
genclass SSN val defs
and then edit to place #include "SSN.h" at the top.
Finally, you can generate the classes. First, generate the base class for Maps via
genclass -2 Person ref SSN val Map
This generates only the abstract class, not the implementation, in file `Person.SSN.Map.h' and `Person.SSN.Map.cc'. To create the AVL implementation, type
genclass -2 Person ref SSN val AVLMap
This creates the class PersonSSNAVLMap, in
`Person.SSN.AVLMap.h' and `Person.SSN.AVLMap.cc'.
To use the AVL implementation, compile the two generated `.cc' files, and specify `#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,
PersonSSNAVLMap m((SSN)0);
Suppose you wanted a VHMap instead of an AVLMap Besides
generating different implementations, there are two differences in
how you should prepare the `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
class Person
{ ...;
Person() {}
void operator = (const Person& p) { nm = p.nm; addr = p.addr; }
};
(The lack of action in the constructor is OK here because Strings
possess usable no-argument constructors.)
You also need to edit `Person.defs.h' to indicate a usable hash function and default capacity, via something like
#include <builtin.h> #define <T>HASH(x) (hashpjw(x.name().chars())) #define DEFAULT_INITIAL_CAPACITY 1000
Since the hashpjw function from `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
VHMap for AVLMap.
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 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.
The fact that C++ allows operators to be overloaded for user-defined
classes can make programming with library classes like Integer,
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 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 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
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 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 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
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
a = (b - a) * -(d / c);
This would be compiled as if it were
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
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
Integer f(const Integer& a) { Integer r = a; r += a; return r; }
This function, when called (as in 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
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, then make it fast, by translating expression code into procedural code after it is known to be correct.
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
Pixes. A Pix acts in some ways like an index, and in some
ways like a pointer. (Their underlying representations are just
void* pointers). A Pix is a kind of "key" that is
translated into an element access by the class. In virtually all cases,
Pixes are pointers to some kind internal storage cells. The
containers use these pointers to extract items.
Pixes support traversal and inspection of elements in a
collection using analogs of array indexing. However, they are
pointer-like in that 0 is treated as an invalid Pix, and
unsafe insofar as programmers can attempt to access nonexistent elements
via dangling or otherwise invalid 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
for (Pix i = a.first(); i != 0; a.next(i)) use(a(i));for some container
a and function use.
Classes supporting the use of Pixes always contain the following
methods, assuming a container a of element types of Base.
Pix i = a.first()
a.next(i)
Base x = a(i); a(i) = x;
int present = a.owns(i)
Some container classes also support backwards traversal via
Pix i = a.last()
a.prev(i)
Collections supporting elements with an equality operation possess
Pix j = a.seek(x)
Bag classes possess
Pix j = a.seek(x, Pix from = 0)
Set, Bag, and PQ classes possess
Pix j = a.add(x) (or a.enq(x) for priority queues)
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.
char* functions (like strcmp) are among
the declarations. All functions are declared along with their
library names, so that they may be safely overloaded.
#defined constants that appear to be
consistent with those provided in the AT&T version. The value
of HUGE should be checked before using. Declarations of
all common math functions are preceded with overload
declarations, since these are commonly overloaded.
FILE (_iobuf), common macros (like
getc), and function prototypes for `libc.a'
functions that operate on FILE*'s. The value
BUFSIZ and the declaration of _iobuf should be
checked before using.
Files `builtin.h' and corresponding `.cc' implementation
files contain various convenient
inline and non-inline utility functions. These include useful
enumeration types, such as TRUE, FALSE ,the type
definition for pointers to libg++ error handling functions, and
the following functions.
long abs(long x); double abs(double x);
int abs(int) is not declared as inline.
void clearbit(long& x, long b);
void setbit(long& x, long b);
int testbit(long x, long b);
int even(long y);
int odd(long y);
int sign(long x); int sign(double x);
long gcd(long x, long y);
long lcm(long x, long y);
long lg(long x);
long pow(long x, long y); double pow(double x, long y);
long sqr(long x); double sqr(double x);
long sqrt(long y);
unsigned int hashpjw(const char* s);
unsigned int multiplicativehash(int x);
unsigned int foldhash(double x);
double start_timer()
double return_elapsed_time(double last_time)
File `Maxima.h' includes versions of MAX, MIN
for builtin types.
File `compare.h' includes versions of 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.
Libg++ contains versions of malloc, free, realloc that were
designed to be well-tuned to C++ applications. The source file
`malloc.c' contains some design and implementation details.
Here are the major user-visible differences from most system
malloc routines:
delete'd
object in any way. Doing so will either result in trapped
fatal errors or random aborts within malloc, free, or realloc.
operator new() to call malloc and
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 both operator new() and operator
delete().
realloc with a pointer
that has been free'd.
free'd
pointers that can often determine whether users have accidentally
written beyond the boundaries of allocated space, resulting in a fatal
error.
malloc_usable_size(void* p) returns the number of
bytes actually allocated for p. For a valid pointer (i.e., one
that has been malloc'd or realloc'd but not yet
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 free'd but then re-allocated for a
different purpose somewhere elsewhere, then malloc_usable_size
will return non-zero. Despite this, the function can be very valuable
for performing run-time consistency checks.
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.
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).
These classes are available in libg++ for convenience and for
compatibility with older releases; however, since the iostream classes
are licensed under less stringent terms than libg++, they are now
also available in a separate library called libio---and
documented in a separate manual, corresponding to that library.
See section 'Introduction' in The GNU C++ Iostream Library.
WARNING: This chapter describes classes that are obsolete.
These classes are normally not available when libg++
is installed normally. The sources are currently included
in the distribution, and you can configure libg++ to use
these classes instead of the new iostream classes.
This is only a temporary measure; you should convert your
code to use iostreams as soon as possible. The iostream
classes provide some compatibility support, but it is
very incomplete (there is no longer a File class).
File class supports basic IO on Unix files. Operations are
based on common C stdio library functions.
File serves as the base class for istreams, ostreams, and other
derived classes. It contains the interface between the Unix stdio file
library and these more structured classes. Most operations are implemented
as simple calls to stdio functions. File class operations are also fully
compatible with raw system file reads and writes (like the system
read and lseek calls) when buffering is disabled (see below).
The FILE* stdio file pointer is, however maintained as protected.
Classes derived from File may only use the IO operations provided by File,
which encompass essentially all stdio capabilities.
The class contains four general kinds of functions: methods for binding
Files to physical Unix files, basic IO methods, file and buffer
control methods, and methods for maintaining logical and physical file
status.
Binding and related tasks are accomplished via File constructors and
destructors, and member functions open, close, remove, filedesc,
name, setname.
If a file name is provided in a constructor or open, it is
maintained as class variable nm and is accessible
via name. If no name is provided, then nm remains
null, except that Files bound to the default files stdin,
stdout, and stderr are automatically given the names
(stdin), (stdout), (stderr) respectively.
The function setname may be used to change the
internal name of the File. This does not change the name
of the physical file bound to the File.
The member function close closes a file. The
~File destructor closes a file if it is open, except
that stdin, stdout, and stderr are flushed but left open for
the system to close on program exit since some systems may
require this, and on others it does not matter. remove
closes the file, and then deletes it if possible by calling the
system function to delete the file with the name provided in
the nm field.
read and write perform binary IO via stdio
fread and fwrite.
get and put for chars invoke stdio getc
and putc macros.
put(const char* s) outputs a null-terminated string via
stdio fputs.
unget and putback are synonyms. Both call stdio
ungetc.
flush, seek, tell, and tell call the
corresponding stdio functions.
flush(char) and fill() call stdio _flsbuf
and _filbuf respectively.
setbuf is mainly useful to turn off buffering in cases
where nonsequential binary IO is being performed. raw is a
synonym for setbuf(_IONBF). After a f.raw(), using
the stdio functions instead of the system read, write,
etc., calls entails very little overhead. Moreover, these become
fully compatible with intermixed system calls (e.g.,
lseek(f.filedesc(), 0, 0)). While intermixing File
and system IO calls is not at all recommended, this technique
does allow the File class to be used in conjunction with
other functions and libraries already set up to operate on file
descriptors. setbuf should be called at most once after a
constructor or open, but before any IO.
File status is maintained in several ways.
A File may be checked for accessibility via
is_open(), which returns true if the File is bound to a
usable physical file, readable(), which returns true if
the File can be read from (opened for reading, and not in a
_fail state), or writable(), which returns true if the
File can be written to.
File operations return their status via two means: failure and
success are represented via the logical state. Also, the
return values of invoked stdio and system functions that
return useful numeric values (not just failure/success flags)
are held in a class variable accessible via iocount.
(This is useful, for example, in determining the number of
items actually read by the read function.)
Like the AT&T i/o-stream classes, but unlike the description in
the Stroustrup book, p238, rdstate() returns the bitwise
OR of _eof, _fail and _bad, not necessarily
distinct values. The functions eof(), fail(),
bad(), and good() can be used to test for each of
these conditions independently.
_fail becomes set for any input operation that could not
read in the desired data, and for other failed operations. As
with all Unix IO, _eof becomes true only when an input
operations fails because of an end of file. Therefore,
_eof is not immediately true after the last successful
read of a file, but only after one final read attempt. Thus, for
input operations, _fail and _eof almost always
become true at the same time. bad is set for unbound
files, and may also be set by applications in order to communicate
input corruption. Conversely, _good is defined as 0 and
is returned by rdstate() if all is well.
The state may be modified via clear(flag), which,
despite its name, sets the corresponding state_value flag.
clear() with no arguments resets the state to _good.
failif(int cond) sets the state to _fail only if
cond is true.
Errors occuring during constructors and file opens also invoke the
function error. error in turn calls a resetable error
handling function pointed to by the non-member global variable
File_error_handler only if a system error has been generated.
Since error cannot tell if the current system error is actually
responsible for a failure, it may at times print out spurious messages.
Three error handlers are provided. The default,
verbose_File_error_handler calls the system function
perror to print the corresponding error message on standard
error, and then returns to the caller. quiet_File_error_handler
does nothing, and simply returns. fatal_File_error_handler
prints the error and then aborts execution. These three handlers, or any
other user-defined error handlers can be selected via the non-member
function set_File_error_handler.
All read and write operations communicate either logical or
physical failure by setting the _fail flag. All further
operations are blocked if the state is in a _fail or_bad
condition. Programmers must explicitly use clear() to
reset the state in order to continue IO processing after
either a logical or physical failure. C programmers who are
unfamiliar with these conventions should note that, unlike
the stdio library, File functions indicate IO success,
status, or failure solely through the state, not via return values of
the functions. The void* operator or rdstate()
may be used to test success. In particular, according to c++
conversion rules, the void* coercion is automatically
applied whenever the File& return value of any File
function is tested in an if or while. Thus,
for example, an easy way to copy all of stdin to stdout until
eof (at which point get fails) or some error is
char c; while(cin.get(c) && cout.put(c));.
The current version of istreams and ostreams differs significantly
from previous versions in order to obtain compatibility with
AT&T 1.2 streams. Most code using previous versions should still
work. However, the following features of File are not
incorporated in streams (they are still present in File):
scan(const char* fmt...), remove(), read(), write(),
setbuf(), raw(). Additionally, the feature of previous streams
that allowed free intermixing of stream and stdio input and output
is no longer guaranteed to always behave as desired.
The Obstack class is a simple rewrite of the C obstack macros and
functions provided in the GNU CC compiler source distribution.
Obstacks provide a simple method of creating and maintaining a string table, optimized for the very frequent task of building strings character-by-character, and sometimes keeping them, and sometimes not. They seem especially useful in any parsing application. One of the test files demonstrates usage.
A brief summary:
grow
finish
copy
copy is always equivalent to first grow, then finish.
free
The other functions are less commonly needed:
blank
alloc
blank, but it wraps up the object and returns its starting
address.
chunk_size, base, next_free, alignment_mask, size, room
grow_fast
blank_fast
blank, but without checking if there is enough room.
shrink(int n)
contains(void* addr)
Here is a lightly edited version of the original C documentation:
These functions operate a stack of objects. Each object starts life small, and may grow to maturity. (Consider building a word syllable by syllable.) An object can move while it is growing. Once it has been "finished" it never changes address again. So the "top of the stack" is typically an immature growing object, while the rest of the stack is of mature, fixed size and fixed address objects.
These routines grab large chunks of memory, using the GNU C++ new
operator. On occasion, they free chunks, via delete.
Each independent stack is represented by a Obstack.
One motivation for this package is the problem of growing char strings in symbol tables. Unless you are a "fascist pig with a read-only mind" [Gosper's immortal quote from HAKMEM item 154, out of context] you would not like to put any arbitrary upper limit on the length of your symbols.
In practice this often means you will build many short symbols and a
few long symbols. At the time you are reading a symbol you don't know
how long it is. One traditional method is to read a symbol into a
buffer, realloc()ating the buffer every time you try to read a
symbol that is longer than the buffer. This is beaut, but you still will
want to copy the symbol from the buffer to a more permanent
symbol-table entry say about half the time.
With obstacks, you can work differently. Use one obstack for all symbol names. As you read a symbol, grow the name in the obstack gradually. When the name is complete, finalize it. Then, if the symbol exists already, free the newly read name.
The way we do this is to take a large chunk, allocating memory from low addresses. When you want to build a symbol in the chunk you just add chars above the current "high water mark" in the chunk. When you have finished adding chars, because you got to the end of the symbol, you know how long the chars are, and you can create a new object. Mostly the chars will not burst over the highest address of the chunk, because you would typically expect a chunk to be (say) 100 times as long as an average object.
In case that isn't clear, when we have enough chars to make up the object, they are already contiguous in the chunk (guaranteed) so we just point to it where it lies. No moving of chars is needed and this is the second win: potentially long strings need never be explicitly shuffled. Once an object is formed, it does not change its address during its lifetime.
When the chars burst over a chunk boundary, we allocate a larger chunk, and then copy the partly formed object from the end of the old chunk to the beginning of the new larger chunk. We then carry on accreting characters to the end of the object as we normally would.
A special version of grow is provided to add a single char at a time to a growing object.
Summary:
The obstack data structure is used in many places in the GNU C++ compiler.
Differences from the the GNU C version
init and begin macros are replaced by constructors.
grow, grow0, etc.
new operator.
This restricts flexibility by a little, but maintains compatibility
with usual C++ conventions.
terminator, and then calls
finish(). This enables the normal invocation of finish(0) to
wrap up a string being grown character-by-character.
s
after computing its length.
An AllocRing is a bounded ring (circular list), each of whose elements
contains a pointer to some space allocated via new
char[some_size]. The entries are used cyclicly. The size, n, of the
ring is fixed at construction. After that, every nth use of the ring
will reuse (or reallocate) the same space. AllocRings are needed in
order to temporarily hold chunks of space that are needed transiently,
but across constructor-destructor scopes. They mainly useful for storing
strings containing formatted characters to print across various
functions and coercions. These strings are needed across routines, so
may not be deleted in any one of them, but should be recovered at some
point. In other words, an AllocRing is an extremely simple minded
garbage collection mechanism. The GNU C++ library used to use one
AllocRing for such formatting purposes, but it is being phased out,
and is now only used by obsolete functions.
These days, AllocRings are probably not very useful.
Support includes:
AllocRing a(int n)
void* mem = a.alloc(sz)
int present = a.contains(void* ptr)
a.clear()
a.free(void* ptr)
The String class is designed to extend GNU C++ to support
string processing capabilities similar to those in languages like
Awk. The class provides facilities that ought to be convenient
and efficient enough to be useful replacements for char*
based processing via the C string library (i.e., strcpy,
strcmp, etc.) in many applications. Many details about String
representations are described in the Representation section.
A separate SubString class supports substring extraction
and modification operations. This is implemented in a way that
user programs never directly construct or represent substrings,
which are only used indirectly via String operations.
Another separate class, Regex is also used indirectly via String
operations in support of regular expression searching, matching, and the
like. The Regex class is based entirely on the GNU Emacs regex
functions. See section 'Syntax of Regular Expressions' in GNU Emacs Manual, for a full
explanation of regular expression syntax. (For implementation details,
see the internal documentation in files `regex.h' and
`regex.c'.)
Strings are initialized and assigned as in the following examples:
String x; String y = 0; String z = "";
String x = "Hello"; String y("Hello");
String x = 'A'; String y('A');
String u = x; String v(x);
String u = x.at(1,4); String v(x.at(1,4));
String x("abc", 2);
String x = dec(20);
char* function.
There are no directly accessible forms for declaring SubString variables.
The declaration Regex r("[a-zA-Z_][a-zA-Z0-9_]*"); creates
a compiled regular expression suitable for use in String
operations described below. (In this case, one that matches any
C++ identifier). The first argument may also be a String.
Be careful in distinguishing the role of backslashes in quoted
GNU C++ char* constants versus those in Regexes. For example, a Regex
that matches either one or more tabs or all strings beginning
with "ba" and ending with any number of occurrences of "na"
could be declared as Regex r = "\\(\t+\\)\\|\\(ba\\(na\\)*\\)"
Note that only one backslash is needed to signify the tab, but
two are needed for the parenthesization and virgule, since the
GNU C++ lexical analyzer decodes and strips backslashes before
they are seen by Regex.
There are three additional optional arguments to the Regex constructor that are less commonly useful:
fast (default 0)
fast may be set to true (1) if the Regex should be
"fast-compiled". This causes an additional compilation step that
is generally worthwhile if the Regex will be used many times.
bufsize (default max(40, length of the string))
transtable (default none == 0)
As a convenience, several Regexes are predefined and usable in any program. Here are their declarations from `String.h'.
extern Regex RXwhite; // = "[ \n\t]+"
extern Regex RXint; // = "-?[0-9]+"
extern Regex RXdouble; // = "-?\\(\\([0-9]+\\.[0-9]*\\)\\|
// \\([0-9]+\\)\\|
// \\(\\.[0-9]+\\)\\)
// \\([eE][---+]?[0-9]+\\)?"
extern Regex RXalpha; // = "[A-Za-z]+"
extern Regex RXlowercase; // = "[a-z]+"
extern Regex RXuppercase; // = "[A-Z]+"
extern Regex RXalphanum; // = "[0-9A-Za-z]+"
extern Regex RXidentifier; // = "[A-Za-z_][A-Za-z0-9_]*"
Most String class capabilities are best shown via example.
The examples below use the following declarations.
String x = "Hello";
String y = "world";
String n = "123";
String z;
char* s = ",";
String lft, mid, rgt;
Regex r = "e[a-z]*o";
Regex r2("/[a-z]*/");
char c;
int i, pos, len;
double f;
String words[10];
words[0] = "a";
words[1] = "b";
words[2] = "c";
The usual lexicographic relational operators (==, !=, <, <=, >, >=)
are defined. A functional form compare(String, String) is also
provided, as is fcompare(String, String), which compares
Strings without regard for upper vs. lower case.
All other matching and searching operations are based on some form of the
(non-public) match and search functions. match and
search differ in that match attempts to match only at the
given starting position, while search starts at the position, and
then proceeds left or right looking for a match. As seen in the following
examples, the second optional startpos argument to functions using
match and search specifies the starting position of the
search: If non-negative, it results in a left-to-right search starting at
position startpos, and if negative, a right-to-left search starting
at position x.length() + startpos. In all cases, the index returned
is that of the beginning of the match, or -1 if there is no match.
Three String functions serve as front ends to search and match.
index performs a search, returning the index, matches performs
a match, returning nonzero (actually, the length of the match) on success,
and contains is a boolean function performing either a search or
match, depending on whether an index argument is provided:
x.index("lo")
x.index("l", 2)
x.index("l", -1)
x.index("l", -3)
pos = r.search("leo", 3, len, 0)
char* string of length 3,
starting at position 0, also placing the length of the match
in reference parameter len.
x.contains("He")
x.contains("el", 1)
contains,
if present, means to match the substring only at that position,
and not to search elsewhere in the string.
x.contains(RXwhite);
RXwhite is a global whitespace Regex.
x.matches("lo", 3)
x.matches(r)
int f = x.freq("l")
Substrings may be extracted via the at, before,
through, from, and after functions.
These behave as either lvalues or rvalues.
z = x.at(2, 3)
x.at(2, 2) = "r"
x.at("He") = "je";
x.at("l", -1) = "i";
z = x.at(r)
z = x.before("o")
x.before("ll") = "Bri";
z = x.before(2)
z = x.after("Hel")
z = x.through("el")
z = x.from("el")
x.after("Hel") = "p";
z = x.after(3)
z = " ab c"; z = z.after(RXwhite)
x[0] = 'J';
common_prefix(x, "Help")
common_suffix(x, "to")
z = x + s + ' ' + y.at("w") + y.after("w") + ".";
x += y;
cat(x, y, z)
cat(z, y, x, x)
y.prepend(x);
z = replicate(x, 3);
z = join(words, 3, "/")
z = "this string has five words"; i = split(z, words, 10, RXwhite);
int nmatches x.gsub("l","ll")
z = x + y; z.del("loworl");
z = reverse(x)
z = upcase(x)
z = downcase(x)
z = capitalize(x)
x.reverse(), x.upcase(), x.downcase(), x.capitalize()
cout << x
cout << x.at(2, 3)
cin >> x
x.length()
s = (const char*)x
char* char array. This
coercion is useful for sending a String as an argument to any
function expecting a const char* argument (like
atoi, and File::open). This operator must be
used with care, since the conversion returns a pointer
to String internals without copying the characters:
The resulting (char*) is only valid until
the next String operation, and you must not modify it.
(The conversion is defined to return a const
value so that GNU C++ will produce warning and/or error
messages if changes are attempted.)
The Integer class provides multiple precision integer arithmetic
facilities. Some representation details are discussed in the
Representation section.
Integers may be up to b * ((1 << b) - 1) bits long, where
b is the number of bits per short (typically 1048560 bits when
b = 16). The implementation assumes that a long is at least
twice as long as a short. This assumption hides beneath almost all
primitive operations, and would be very difficult to change. It also relies
on correct behavior of unsigned arithmetic operations.
Some of the arithmetic algorithms are very loosely based on those provided in the MIT Scheme `bignum.c' release, which is Copyright (c) 1987 Massachusetts Institute of Technology. Their use here falls within the provisions described in the Scheme release.
Integers may be constructed in the following ways:
Integer x;
Integer x = 2; Integer y(2);
Integer u(x); Integer v = x;
Method: long Integer::as_long() const
Used to coerce an Integer back into longs via the long
coercion operator. If the Integer cannot fit into a long, this returns
MINLONG or MAXLONG (depending on the sign) where MINLONG is the most
negative, and MAXLONG is the most positive representable long.
Method: int Integer::fits_in_long() const
Returns true iff the Integer is < MAXLONG and > MINLONG.
Method: double Integer::as_double() const
Coerce the Integer to a double, with potential
loss of precision.
+/-HUGE is returned if the Integer cannot fit into a double.
Method: int Integer::fits_in_double() const
Returns true iff the Integer can fit into a double.
All of the usual arithmetic operators are provided (+, -, *, /,
%, +=, ++, -=, --, *=, /=, %=, ==, !=, <, <=, >, >=). All operators
support special versions for mixed arguments of Integers and regular
C++ longs in order to avoid useless coercions, as well as to allow
automatic promotion of shorts and ints to longs, so that they may be
applied without additional Integer coercion operators. The only
operators that behave differently than the corresponding int or long
operators are ++ and --. Because C++ does not
distinguish prefix from postfix application, these are declared as
void operators, so that no confusion can result from applying
them as postfix. Thus, for Integers x and y, ++x; y = x; is
correct, but y = ++x; and y = x++; are not.
Bitwise operators (~, &, |, ^, <<,
>>, &=, |=, ^=, <<=, >>=) are
also provided. However, these operate on sign-magnitude, rather than
two's complement representations. The sign of the result is arbitrarily
taken as the sign of the first argument. For example, Integer(-3)
& Integer(5) returns Integer(-1), not -3, as it would using
two's complement. Also, ~, the complement operator, complements
only those bits needed for the representation. Bit operators are also
provided in the BitSet and BitString classes. One of these classes
should be used instead of Integers when the results of bit manipulations
are not interpreted numerically.
The following utility functions are also provided. (All arguments are Integers unless otherwise noted).
Function: void divide(const Integer& x, const Integer& y, Integer& q, Integer& r)
Sets q to the quotient and r to the remainder of x and y. (q and r are returned by reference).
Function: Integer pow(const Integer& x, const Integer& p)
Returns x raised to the power p.
Function: Integer Ipow(long x, long p)
Returns x raised to the power p.
Function: Integer gcd(const Integer& x, const Integer& p)
Returns the greatest common divisor of x and y.
Function: Integer lcm(const Integer& x, const Integer& p)
Returns the least common multiple of x and y.
Function: Integer abs(const Integer& x
Returns the absolute value of x.
Method: void Integer::negate()
Negates this in place.
Integer sqr(x)
Integer sqrt(x)
long lg(x);
int sign(x)
if (sign(x) == 0) is a generally faster method
of testing for zero than using relational operators.
int even(x)
int odd(x)
void setbit(Integer& x, long b)
void clearbit(Integer& x, long b)
int testbit(Integer x, long b)
Integer atoI(char* asciinumber, int base = 10);
void Integer::printon(ostream& s, int base = 10, int width = 0);
(*this) as a base base
number, in field width at least width.
ostream << x;
istream >> x;
int compare(Integer x, Integer y)
int ucompare(Integer x, Integer y)
add(x, y, z)
sub(x, y, z)
mul(x, y, z)
div(x, y, z)
mod(x, y, z)
and(x, y, z)
or(x, y, z)
xor(x, y, z)
lshift(x, y, z)
rshift(x, y, z)
pow(x, y, z)
complement(x, z)
negate(x, z)
Class Rational provides multiple precision rational
number arithmetic. All rationals are maintained in simplest
form (i.e., with the numerator and denominator relatively
prime, and with the denominator strictly positive).
Rational arithmetic and relational operators are provided
(+, -, *, /, +=, -=, *=, /=, ==, !=, <, <=, >, >=).
Operations resulting in a rational number with zero denominator
trigger an exception.
Rationals may be constructed and used in the following ways:
Rational x;
Rational x = 2; Rational y(2);
Rational x(2, 3);
Rational x = 1.2;
Rational x(Integer(123), Integer(4567));
Rational u(x); Rational v = x;
double(Rational x)
Rational abs(x)
void x.negate()
void x.invert()
int sign(x)
Rational sqr(x)
Rational pow(x, Integer y)
Integer x.numerator()
Integer x.denominator()
Integer floor(x)
Integer ceil(x)
Integer trunc(x)
Integer round(x)
int compare(x, y)
ostream << x;
istream >> x;
add(x, y, z)
sub(x, y, z)
mul(x, y, z)
div(x, y, z)
pow(x, y, z)
negate(x, z)
Class Complex is implemented in a way similar to that
described by Stroustrup. In keeping with libg++ conventions,
the class is named Complex, not complex.
Complex arithmetic and relational operators are provided
(+, -, *, /, +=, -=, *=, /=, ==, !=).
Attempted division by (0, 0) triggers an exception.
Complex numbers may be constructed and used in the following ways:
Complex x;
Complex x = 2; Complex y(2.0);
Complex x(2, 3);
Complex u(x); Complex v = x;
double real(Complex& x);
double imag(Complex& x);
double abs(Complex& x);
double norm(Complex& x);
double arg(Complex& x);
Complex polar(double r, double t = 0.0);
Complex conj(Complex& x);
Complex cos(Complex& x);
Complex sin(Complex& x);
Complex cosh(Complex& x);
Complex sinh(Complex& x);
Complex exp(Complex& x);
Complex log(Complex& x);
Complex pow(Complex& x, long p);
Complex pow(Complex& x, Complex& p);
Complex sqrt(Complex& x);
ostream << x;
istream >> x;
Classes Fix16, Fix24, Fix32, and Fix48
support operations on 16, 24, 32, or 48 bit quantities that are
considered as real numbers in the range [-1, +1). Such numbers are
often encountered in digital signal processing applications. The classes
may be be used in isolation or together. Class Fix32
operations are entirely self-contained. Class Fix16 operations
are self-contained except that the multiplication operation Fix16
* Fix16 returns a Fix32. Fix24 and Fix48 are
similarly related.
The standard arithmetic and relational operations are supported
(=, +, -, *, /, <<, >>,
+=, -=, *=, /=, <<=, >>=,
==, !=, <, <=, >, >=).
All operations include provisions for special handling in cases where
the result exceeds +/- 1.0. There are two cases that may be handled
separately: "overflow" where the results of addition and subtraction
operations go out of range, and all other "range errors" in which
resulting values go off-scale (as with division operations, and
assignment or initialization with off-scale values). In signal
processing applications, it is often useful to handle these two cases
differently. Handlers take one argument, a reference to the integer
mantissa of the offending value, which may then be manipulated. In
cases of overflow, this value is the result of the (integer) arithmetic
computation on the mantissa; in others it is a fully saturated (i.e.,
most positive or most negative) value. Handling may be reset to any of
several provided functions or any other user-defined function via
set_overflow_handler and set_range_error_handler. The
provided functions for Fix16 are as follows (corresponding
functions are also supported for the others).
Fix16_overflow_saturate
Fix16_ignore
Fix16_overflow_warning_saturate
Fix16_warning
Fix16_abort
In addition to arithmetic operations, the following are provided:
Fix16 a = 0.5;
short& mantissa(a); long& mantissa(b);
double value(a); double value(b);
libg++ provides several different classes supporting the use and manipulation of collections of bits in different ways.
Integer provides "integer" semantics. It supports
manipulation of bits in ways that are often useful when treating bit arrays
as numerical (integer) quantities. This class is described elsewhere.
BitSet provides "set" semantics. It supports operations
useful when treating collections of bits as representing potentially
infinite sets of integers.
BitSet32 supports fixed-length BitSets holding exactly
32 bits.
BitSet256 supports fixed-length BitSets holding exactly
256 bits.
BitString provides "string" (or "vector") semantics.
It supports operations useful when treating collections of bits as
strings of zeros and ones.
These classes also differ in the following ways:
~, &,
|, ^, -, the semantics differ. BitSets perform bit operations that
precisely mirror those for infinite sets. For example, complementing an
empty BitSet returns one representing an infinite number of set bits.
Operations on BitStrings and Integers operate only on those bits
actually present in the representation. For BitStrings and Integers,
the the & operation returns a BitString with a length equal to
the minimum length of the operands, and |, ^ return one with
length of the maximum.
BitSets are objects that contain logically infinite sets of nonnegative integers. Representational details are discussed in the Representation chapter. Because they are logically infinite, all BitSets possess a trailing, infinitely replicated 0 or 1 bit, called the "virtual bit", and indicated via 0* or 1*.
BitSet32 and BitSet256 have they same properties, except they are of fixed length, and thus have no virtual bit.
BitSets may be constructed as follows:
BitSet a;
BitSet a = atoBitSet("001000");
BitSet a = atoBitSet("00101*");
BitSet a = longtoBitSet((long)23);
BitSet a = utoBitSet((unsigned)23);
The following functions and operators are provided (Assume the declaration of BitSets a = 0011010*, b = 101101*, throughout, as examples).
~a
a.complement()
a & b; a &= b;
a | b; a |= b;
a - b; a -= b;
a ^ b; a ^= b;
a.empty()
a == b;
a <= b;
a < b;
a != b; a >= b; a > b;
a.set(7)
a.clear(2)
a.clear()
a.set()
a.invert(0)
a.set(0,1)
a.test(3)
a.test(3, 5)
int i = a[3]; a[3] = 0;
a.first(1) or a.first()
a.first(0)
a.next(2, 1) or a.next(2)
first and next may be used as
iterators, as in
for (int i = a.first(); i >= 0; i = a.next(i))....
a.last(1)
a.prev(3, 0)
a.count(1)
a.virtual_bit()
a = atoBitSet("ababX", 'a', 'b', 'X');