home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / gnu / libg++-2.5.3-bin.lha / info / libg++.info-2 < prev    next >
Encoding:
GNU Info File  |  1994-02-27  |  49.3 KB  |  1,161 lines

  1. This is Info file libg++.info, produced by Makeinfo-1.55 from the input
  2. file ./libg++.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Libg++::                      The g++ class library.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This file documents the features and implementation of The GNU C++
  9. library
  10.  
  11.    Copyright (C) 1988, 1991, 1992 Free Software Foundation, Inc.
  12.  
  13.    Permission is granted to make and distribute verbatim copies of this
  14. manual provided the copyright notice and this permission notice are
  15. preserved on all copies.
  16.  
  17.    Permission is granted to copy and distribute modified versions of
  18. this manual under the conditions for verbatim copying, provided also
  19. that the section entitled "GNU Library General Public License" is
  20. included exactly as in the original, and provided that the entire
  21. resulting derived work is distributed under the terms of a permission
  22. notice identical to this one.
  23.  
  24.    Permission is granted to copy and distribute translations of this
  25. manual into another language, under the above conditions for modified
  26. versions, except that the section entitled "GNU Library General Public
  27. License" and this permission notice may be included in translations
  28. approved by the Free Software Foundation instead of in the original
  29. English.
  30.  
  31. 
  32. File: libg++.info,  Node: Proto,  Next: Representations,  Prev: OK,  Up: Top
  33.  
  34. Introduction to container class prototypes
  35. ******************************************
  36.  
  37.    As a temporary mechanism enabling the support of generic classes,
  38. the GNU C++ Library distribution contains a directory (`g++-include')
  39. of files designed to serve as the basis for generating container
  40. classes of specified elements.  These files can be used to generate
  41. `.h' and `.cc' files in the current directory via a supplied shell
  42. script program that performs simple textual substitution to create
  43. specific classes.
  44.  
  45.    While these classes are generated independently, and thus share no
  46. code, it is possible to create versions that do share code among
  47. subclasses. For example, using `typedef void* ent', and then generating
  48. a `entList' class, other derived classes could be created using the
  49. `void*' coercion method described in Stroustrup, pp204-210.
  50.  
  51.    This very simple class-generation facility is useful enough to serve
  52. current purposes, but will be replaced with a more coherent mechanism
  53. for handling C++ generics in a way that minimally disrupts current
  54. usage.  Without knowing exactly when or how parametric classes might be
  55. added to the C++ language, provision of this simplest possible
  56. mechanism, textual substitution, appears to be the safest strategy,
  57. although it does require certain redundancies and awkward constructions.
  58.  
  59.    Specific classes may be generated via the `genclass' shell script
  60. program. This program has arguments specifying the kinds of base
  61. types(s) to be used. Specifying base types requires two arguments. The
  62. first is the name of the base type, which may be any named type, like
  63. `int' or `String'. Only named types are supported; things like `int*'
  64. are not accepted. However, pointers like this may be used by supplying
  65. the appropriate typedefs (e.g., editing the resulting files to include
  66. `typedef int* intp;'). The type name must be followed by one of the
  67. words `val' or `ref', to indicate whether the base elements should be
  68. passed to functions by-value or by-reference.
  69.  
  70.    You can specify basic container classes using `genclass base
  71. [val,ref] proto', where `proto' is the name of the class being
  72. generated.  Container classes like dictionaries and maps that require
  73. two types may be specified via `genclass -2 keytype [val, ref],
  74. basetype [val, ref] proto', where the key type is specified first and
  75. the contents type second.  The resulting classnames and filenames are
  76. generated by prepending the specified type names to the prototype names,
  77. and separating the filename parts with dots.  For example, `genclass
  78. int val List' generates class `intList' residing in files `int.List.h'
  79. and `int.List.cc'. `genclass -2 String ref int val VHMap' generates
  80. (the awkward, but unavoidable) class name `StringintVHMap'. Of course,
  81. programmers may use `typedef' or simple editing to create more
  82. appropriate names.  The existence of dot seperators in file names
  83. allows the use of GNU make to help automate configuration and
  84. recompilation. An example Makefile exploiting such capabilities may be
  85. found in the `libg++/proto-kit' directory.
  86.  
  87.    The `genclass' utility operates via simple text substitution using
  88. `sed'. All occurrences of the pseudo-types `<T>' and `<C>' (if there
  89. are two types) are replaced with the indicated type, and occurrences of
  90. `<T&>' and `<C&>' are replaced by just the types, if `val' is
  91. specified, or types followed by "&" if `ref' is specified.
  92.  
  93.    Programmers will frequently need to edit the `.h' file in order to
  94. insert additional `#include' directives or other modifications.  A
  95. simple utility, `prepend-header' to prepend other `.h' files to
  96. generated files is provided in the distribution.
  97.  
  98.    One dubious virtue of the prototyping mechanism is that, because
  99. sources files, not archived library classes, are generated, it is
  100. relatively simple for programmers to modify container classes in the
  101. common case where slight variations of standard container classes are
  102. required.
  103.  
  104.    It is often a good idea for programmers to archive (via `ar')
  105. generated classes into `.a' files so that only those class functions
  106. actually used in a given application will be loaded.  The test
  107. subdirectory of the distribution shows an example of this.
  108.  
  109.    Because of `#pragma interface' directives, the `.cc' files should be
  110. compiled with `-O' or `-DUSE_LIBGXX_INLINES' enabled.
  111.  
  112.    Many container classes require specifications over and above the base
  113. class type. For example, classes that maintain some kind of ordering of
  114. elements require specification of a comparison function upon which to
  115. base the ordering.  This is accomplished via a prototype file `defs.hP'
  116. that contains macros for these functions. While these macros default to
  117. perform reasonable actions, they can and should be changed in
  118. particular cases. Most prototypes require only one or a few of these.
  119. No harm is done if unused macros are defined to perform nonsensical
  120. actions. The macros are:
  121.  
  122. `DEFAULT_INITIAL_CAPACITY'
  123.      The initial capacity for containers (e.g., hash tables) that
  124.      require an initial capacity argument for constructors.  Default:
  125.      100
  126.  
  127. `<T>EQ(a, b)'
  128.      return true if a is considered equal to b for the purposes of
  129.      locating, etc., an element in a container.  Default: (a == b)
  130.  
  131. `<T>LE(a, b)'
  132.      return true if a is less than or equal to b Default: (a <= b)
  133.  
  134. `<T>CMP(a, b)'
  135.      return an integer < 0 if a<b, 0 if a==b, or > 0 if a>b.  Default:
  136.      (a <= b)? (a==b)? 0 : -1 : 1
  137.  
  138. `<T>HASH(a)'
  139.      return an unsigned integer representing the hash of a.  Default:
  140.      hash(a) ; where extern unsigned int hash(<T&>).  (note: several
  141.      useful hash functions are declared in builtin.h and defined in
  142.      hash.cc)
  143.  
  144.    Nearly all prototypes container classes support container traversal
  145. via `Pix' pseudo indices, as described elsewhere.
  146.  
  147.    All object containers must perform either a `X::X(X&)' (or `X::X()'
  148. followed by `X::operator =(X&)') to copy objects into containers.  (The
  149. latter form is used for containers built from C++ arrays, like
  150. `VHSets'). When containers are destroyed, they invoke `X::~X()'.  Any
  151. objects used in containers must have well behaved constructors and
  152. destructors. If you want to create containers that merely reference
  153. (point to) objects that reside elsewhere, and are not copied or
  154. destroyed inside the container, you must use containers of pointers,
  155. not containers of objects.
  156.  
  157.    All prototypes are designed to generate *HOMOGENOUS* container
  158. classes.  There is no universally applicable method in C++ to support
  159. heterogenous object collections with elements of various subclasses of
  160. some specified base class. The only way to get heterogenous structures
  161. is to use collections of pointers-to-objects, not collections of objects
  162. (which also requires you to take responsibility for managing storage for
  163. the objects pointed to yourself).
  164.  
  165.    For example, the following usage illustrates a commonly encountered
  166. danger in trying to use container classes for heterogenous structures:
  167.  
  168.      class Base { int x; ...}
  169.      class Derived : public Base { int y; ... }
  170.      
  171.      BaseVHSet s; // class BaseVHSet generated via something like
  172.                   // `genclass Base ref VHSet'
  173.      
  174.      void f()
  175.      {
  176.        Base b;
  177.        s.add(b); // OK
  178.      
  179.        Derived d;
  180.        s.add(d);  // (CHOP!)
  181.      }
  182.  
  183.    At the line flagged with `(CHOP!)', a `Base::Base(Base&)' is called
  184. inside `Set::add(Base&)'--*not* `Derived::Derived(Derived&)'.
  185. Actually, in `VHSet', a `Base::operator =(Base&)', is used instead to
  186. place the element in an array slot, but with the same effect.  So only
  187. the Base part is copied as a `VHSet' element (a so-called
  188. chopped-copy). In this case, it has an `x' part, but no `y' part; and a
  189. Base, not Derived, vtable. Objects formed via chopped copies are rarely
  190. sensible.
  191.  
  192.    To avoid this, you must resort to pointers:
  193.  
  194.      typedef Base* BasePtr;
  195.      
  196.      BasePtrVHSet s; // class BaseVHSet generated via something like
  197.                      // `genclass BasePtr val VHSet'
  198.      
  199.      void f()
  200.      {
  201.        Base* bp = new Base;
  202.        s.add(b);
  203.      
  204.        Base* dp = new Derived;
  205.        s.add(d);  // works fine.
  206.      
  207.        // Don't forget to delete bp and dp sometime.
  208.        // The VHSet won't do this for you.
  209.      }
  210.  
  211. Example
  212. =======
  213.  
  214.    The prototypes can be difficult to use on first attempt. Here is an
  215. example that may be helpful. The utilities in the `proto-kit' simplify
  216. much of the actions described, but are not used here.
  217.  
  218.    Suppose you create a class `Person', and want to make an Map that
  219. links the social security numbers associated with each person. You start
  220. off with a file `Person.h'
  221.  
  222.  
  223.      #include <String.h>
  224.      
  225.      class Person
  226.      {
  227.        String nm;
  228.        String addr;
  229.        //...
  230.      public:
  231.        const String& name() { return nm; }
  232.        const String& address() { return addr; }
  233.        void          print() { ... }
  234.        //...
  235.      }
  236.  
  237.    And in file `SSN.h',
  238.  
  239.      typedef unsigned int SSN;
  240.  
  241.    Your first decision is what storage/usage strategy to use. There are
  242. several reasonable alternatives here: You might create an "object
  243. collection" of Persons, a "pointer collection" of pointers-to-Persons,
  244. or even a simple String map, housing either copies of pointers to the
  245. names of Persons, since other fields are unused for purposes of the
  246. Map. In an object collection, instances of class Person "live" inside
  247. the Map, while in a pointer collection, the instances live elsewhere.
  248. Also, as above, if instances of subclasses of Person are to be used
  249. inside the Map, you must use pointers. In a String Map, the same
  250. difference holds, but now only for the name fields. Any of these
  251. choices might make sense in particular applications.
  252.  
  253.    The second choice is the Map implementation strategy. Either a tree
  254. or a hash table might make sense. Suppose you want an AVL tree Map.
  255. There are two things to now check. First, as an object collection, the
  256. AVLMap requires that the elsement class contain an `X(X&)' constructor.
  257. In C++, if you don't specify such a constructor, one is constructed for
  258. you, but it is a very good idea to always do this yourself, to avoid
  259. surprises. In this example, you'd use something like
  260.      class Person
  261.      { ...;
  262.          Person(const Person& p) :nm(p.nm), addr(p.addr) {}
  263.      };
  264.  
  265.    Also, an AVLMap requires a comparison function for elements in order
  266. to maintain order. Rather than requiring you to write a particular
  267. comparison function, a `defs' file is consulted to determine how to
  268. compare items. You must create and edit such a file.
  269.  
  270.    Before creating `Person.defs.h', you must first make one additional
  271. decision. Should the Map member functions like `m.contains(p)' take
  272. arguments (`p') by reference (i.e., typed as `int Map::contains(const
  273. Person& p)' or by value (i.e., typed as `int Map::contains(const Person
  274. p)'. Generally, for user-defined classes, you want to pass by
  275. reference, and for builtins and pointers, to pass by value. SO you
  276. should pick by-reference.
  277.  
  278.    You can now create `Person.defs.h' via `genclass Person ref defs'.
  279. This creates a simple skeleton that you must edit. First, add `#include
  280. "Person.h"' to the top. Second, edit the `<T>CMP(a,b)' macro to compare
  281. on name, via
  282.  
  283.      #define <T>CMP(a, b) ( compare(a.name(), b.name()) )
  284.  
  285. which invokes the `int compare(const String&, const String&)' function
  286. from `String.h'. Of course, you could define this in any other way as
  287. well. In fact, the default versions in the skeleton turn out to be OK
  288. (albeit inefficient) in this particular example.
  289.  
  290.    You may also want to create file `SSN.defs.h'. Here, choosing
  291. call-by-value makes sense, and since no other capabilities (like
  292. comparison functions) of the SSNs are used (and the defaults are OK
  293. anyway), you'd type
  294.  
  295.      genclass SSN val defs
  296.  
  297. and then edit to place `#include "SSN.h"' at the top.
  298.  
  299.    Finally, you can generate the classes. First, generate the base
  300. class for Maps via
  301.  
  302.      genclass -2 Person ref SSN val Map
  303.  
  304. This generates only the abstract class, not the implementation, in file
  305. `Person.SSN.Map.h' and `Person.SSN.Map.cc'.  To create the AVL
  306. implementation, type
  307.  
  308.      genclass -2 Person ref SSN val AVLMap
  309.  
  310. This creates the class `PersonSSNAVLMap', in `Person.SSN.AVLMap.h' and
  311. `Person.SSN.AVLMap.cc'.
  312.  
  313.    To use the AVL implementation, compile the two generated `.cc'
  314. files, and specify `#include "Person.SSN.AVLMap.h"' in the application
  315. program.  All other files are included in the right ways automatically.
  316.  
  317.    One last consideration, peculiar to Maps, is to pick a reasonable
  318. default contents when declaring an AVLMap. Zero might be appropriate
  319. here, so you might declare a Map,
  320.  
  321.      PersonSSNAVLMap m((SSN)0);
  322.  
  323.    Suppose you wanted a `VHMap' instead of an `AVLMap' Besides
  324. generating different implementations, there are two differences in how
  325. you should prepare the `defs' file. First, because a VHMap uses a C++
  326. array internally, and because C++ array slots are initialized
  327. differently than single elements, you must ensure that class Person
  328. contains (1) a no-argument constructor, and (2) an assignment operator.
  329. You could arrange this via
  330.  
  331.      class Person
  332.      { ...;
  333.          Person() {}
  334.        void operator = (const Person& p) { nm = p.nm; addr = p.addr; }
  335.      };
  336.  
  337.    (The lack of action in the constructor is OK here because `Strings'
  338. possess usable no-argument constructors.)
  339.  
  340.    You also need to edit `Person.defs.h' to indicate a usable hash
  341. function and default capacity, via something like
  342.  
  343.      #include <builtin.h>
  344.      #define <T>HASH(x)  (hashpjw(x.name().chars()))
  345.      #define DEFAULT_INITIAL_CAPACITY 1000
  346.  
  347.    Since the `hashpjw' function from `builtin.h' is appropriate here.
  348. Changing the default capacity to a value expected to exceed the actual
  349. capacity helps to avoid "hidden" inefficiencies when a new VHMap is
  350. created without overriding the default, which is all too easy to do.
  351.  
  352.    Otherwise, everything is the same as above, substituting `VHMap' for
  353. `AVLMap'.
  354.  
  355. 
  356. File: libg++.info,  Node: Representations,  Next: Expressions,  Prev: Proto,  Up: Top
  357.  
  358. Variable-Sized Object Representation
  359. ************************************
  360.  
  361.    One of the first goals of the GNU C++ library is to enrich the kinds
  362. of basic classes that may be considered as (nearly) "built into" C++. A
  363. good deal of the inspiration for these efforts is derived from
  364. considering features of other type-rich languages, particularly Common
  365. Lisp and Scheme.  The general characteristics of most class and friend
  366. operators and functions supported by these classes has been heavily
  367. influenced by such languages.
  368.  
  369.    Four of these types, Strings, Integers, BitSets, and BitStrings (as
  370. well as associated and/or derived classes) require representations
  371. suitable for managing variable-sized objects on the free-store. The
  372. basic technique used for all of these is the same, although various
  373. details necessarily differ from class to class.
  374.  
  375.    The general strategy for representing such objects is to create
  376. chunks of memory that include both header information (e.g., the size
  377. of the object), as well as the variable-size data (an array of some
  378. sort) at the end of the chunk. Generally the maximum size of an object
  379. is limited to something less than all of addressable memory, as a
  380. safeguard. The minimum size is also limited so as not to waste
  381. allocations expanding very small chunks. Internally, chunks are
  382. allocated in blocks well-tuned to the performance of the `new' operator.
  383.  
  384.    Class elements themselves are merely pointers to these chunks.  Most
  385. class operations are performed via inline "translation" functions that
  386. perform the required operation on the corresponding representation.
  387. However, constructors and assignments operate by copying entire
  388. representations, not just pointers.
  389.  
  390.    No attempt is made to control temporary creation in expressions and
  391. functions involving these classes. Users of previous versions of the
  392. classes will note the disappearance of both "Tmp" classes and reference
  393. counting. These were dropped because, while they did improve
  394. performance in some cases, they obscure class mechanics, lead
  395. programmers into the false belief that they need not worry about such
  396. things, and occasionally have paradoxical behavior.
  397.  
  398.    These variable-sized object classes are integrated as well as
  399. possible into C++. Most such classes possess converters that allow
  400. automatic coercion both from and to builtin basic types. (e.g., char*
  401. to and from String, long int to and from Integer, etc.). There are
  402. pro's and con's to circular converters, since they can sometimes lead
  403. to the conversion from a builtin type through to a class function and
  404. back to a builtin type without any special attention on the part of the
  405. programmer, both for better and worse.
  406.  
  407.    Most of these classes also provide special-case operators and
  408. functions mixing basic with class types, as a way to avoid constructors
  409. in cases where the operations do not rely on anything special about the
  410. representations.  For example, there is a special case concatenation
  411. operator for a String concatenated with a char, since building the
  412. result does not rely on anything about the String header. Again, there
  413. are arguments both for and against this approach. Supporting these cases
  414. adds a non-trivial degree of (mainly inline) function proliferation, but
  415. results in more efficient operations. Efficiency wins out over parsimony
  416. here, as part of the goal to produce classes that provide sufficient
  417. functionality and efficiency so that programmers are not tempted to try
  418. to manipulate or bypass the underlying representations.
  419.  
  420. 
  421. File: libg++.info,  Node: Expressions,  Next: Pix,  Prev: Representations,  Up: Top
  422.  
  423. Some guidelines for using expression-oriented classes
  424. *****************************************************
  425.  
  426.    The fact that C++ allows operators to be overloaded for user-defined
  427. classes can make programming with library classes like `Integer',
  428. `String', and so on very convenient. However, it is worth becoming
  429. familiar with some of the inherent limitations and problems associated
  430. with such operators.
  431.  
  432.    Many operators are *constructive*, i.e., create a new object based
  433. on some function of some arguments. Sometimes the creation of such
  434. objects is wasteful. Most library classes supporting expressions
  435. contain facilities that help you avoid such waste.
  436.  
  437.    For example, for `Integer a, b, c; ...;  c = a + b + a;', the plus
  438. operator is called to sum a and b, creating a new temporary object as
  439. its result. This temporary is then added with a, creating another
  440. temporary, which is finally copied into c, and the temporaries are then
  441. deleted. In other words, this code might have an effect similar to
  442. `Integer a, b, c; ...; Integer t1(a); t1 += b; Integer t2(t1); t2 += a;
  443. c = t2;'.
  444.  
  445.    For small objects, simple operators, and/or non-time/space critical
  446. programs, creation of temporaries is not a big problem. However, often,
  447. when fine-tuning a program, it may be a good idea to rewrite such code
  448. in a less pleasant, but more efficient manner.
  449.  
  450.    For builtin types like ints, and floats, C and C++ compilers already
  451. know how to optimize such expressions to reduce the need for
  452. temporaries. Unfortunately, this is not true for C++ user defined
  453. types, for the simple (but very annoying, in this context) reason that
  454. nothing at all is guaranteed about the semantics of overloaded operators
  455. and their interrelations. For example, if the above expression just
  456. involved ints, not Integers, a compiler might internally convert the
  457. statement into something like ` c += a; c += b; c+= a; ', or perhaps
  458. something even more clever.  But since C++ does not know that Integer
  459. operator += has any relation to Integer operator +, A C++ compiler
  460. cannot do this kind of expression optimization itself.
  461.  
  462.    In many cases, you can avoid construction of temporaries simply by
  463. using the assignment versions of operators whenever possible, since
  464. these versions create no temporaries. However, for maximum flexibility,
  465. most classes provide a set of "embedded assembly code" procedures that
  466. you can use to fully control time, space, and evaluation strategies.
  467. Most of these procedures are "three-address" procedures that take two
  468. `const' source arguments, and a destination argument. The procedures
  469. perform the appropriate actions, placing the results in the destination
  470. (which is may involve overwriting old contents). These procedures are
  471. designed to be fast and robust. In particular, aliasing is always
  472. handled correctly, so that, for example `add(x, x, x); ' is perfectly
  473. OK. (The names of these procedures are listed along with the classes.)
  474.  
  475.    For example, suppose you had an Integer expression ` a = (b - a) *
  476. -(d / c); '
  477.  
  478.    This would be compiled as if it were ` Integer t1=b-a; Integer
  479. t2=d/c; Integer t3=-t2; Integer t4=t1*t3; a=t4;'
  480.  
  481.    But, with some manual cleverness, you might yourself some up with `
  482. sub(a, b, a); mul(a, d, a); div(a, c, a); '
  483.  
  484.    A related phenomenon occurs when creating your own constructive
  485. functions returning instances of such types. Suppose you wanted to
  486. write function `Integer f(const Integer& a) { Integer r = a;  r += a;
  487. return r; }'
  488.  
  489.    This function, when called (as in ` a = f(a); ') demonstrates a
  490. similar kind of wasted copy. The returned value r must be copied out of
  491. the function before it can be used by the caller. In GNU C++, there is
  492. an alternative via the use of named return values.  Named return values
  493. allow you to manipulate the returned object directly, rather than
  494. requiring you to create a local inside a function and then copy it out
  495. as the returned value. In this example, this can be done via `Integer
  496. f(const Integer& a) return r(a) { r += a; return; }'
  497.  
  498.    A final guideline: The overloaded operators are very convenient, and
  499. much clearer to use than procedural code. It is almost always a good
  500. idea to make it right, *then* make it fast, by translating expression
  501. code into procedural code after it is known to be correct.
  502.  
  503. 
  504. File: libg++.info,  Node: Pix,  Next: Headers,  Prev: Expressions,  Up: Top
  505.  
  506. Pseudo-indexes
  507. **************
  508.  
  509.    Many useful classes operate as containers of elements. Techniques for
  510. accessing these elements from a container differ from class to class.
  511. In the GNU C++ library, access methods have been partially standardized
  512. across different classes via the use of pseudo-indexes called `Pixes'.
  513. A `Pix' acts in some ways like an index, and in some ways like a
  514. pointer. (Their underlying representations are just `void*' pointers).
  515. A `Pix' is a kind of "key" that is translated into an element access by
  516. the class.  In virtually all cases, `Pixes' are pointers to some kind
  517. internal storage cells. The containers use these pointers to extract
  518. items.
  519.  
  520.    `Pixes' support traversal and inspection of elements in a collection
  521. using analogs of array indexing. However, they are pointer-like in that
  522. `0' is treated as an invalid `Pix', and unsafe insofar as programmers
  523. can attempt to access nonexistent elements via dangling or otherwise
  524. invalid `Pixes' without first checking for their validity.
  525.  
  526.    In general it is a very bad idea to perform traversals in the the
  527. midst of destructive modifications to containers.
  528.  
  529.    Typical applications might include code using the idiom
  530.      for (Pix i = a.first(); i != 0; a.next(i)) use(a(i));
  531.    for some container `a' and function `use'.
  532.  
  533.    Classes supporting the use of `Pixes' always contain the following
  534. methods, assuming a container `a' of element types of `Base'.
  535.  
  536. `Pix i = a.first()'
  537.      Set i to index the first element of a or 0 if a is empty.
  538.  
  539. `a.next(i)'
  540.      advance i to the next element of a or 0 if there is no next
  541.      element;
  542.  
  543. `Base x = a(i); a(i) = x;'
  544.      a(i) returns a reference to the element indexed by i.
  545.  
  546. `int present = a.owns(i)'
  547.      returns true if Pix i is a valid Pix in a. This is often a
  548.      relatively slow operation, since the collection must usually
  549.      traverse through elements to see if any correspond to the Pix.
  550.  
  551.    Some container classes also support backwards traversal via
  552.  
  553. `Pix i = a.last()'
  554.      Set i to the last element of a or 0 if a is empty.
  555.  
  556. `a.prev(i)'
  557.      sets i to the previous element in a, or 0 if there is none.
  558.  
  559.    Collections supporting elements with an equality operation possess
  560.  
  561. `Pix j = a.seek(x)'
  562.      sets j to the index of the first occurrence of x, or 0 if x is not
  563.      contained in a.
  564.  
  565.    Bag classes possess
  566.  
  567. `Pix j = a.seek(x, Pix from = 0)'
  568.      sets j to the index of the next occurrence of x following i, or 0
  569.      if x is not contained in a. If i == 0, the first occurrence is
  570.      returned.
  571.  
  572.    Set, Bag, and PQ classes possess
  573.  
  574. `Pix j = a.add(x) (or a.enq(x) for priority queues)'
  575.      add x to the collection, returning its Pix. The Pix of an item can
  576.      change in collections where further additions and deletions
  577.      involve the actual movement of elements (currently in OXPSet,
  578.      OXPBag, XPPQ, VOHSet), but in all other cases, an item's Pix may
  579.      be considered a permanent key to its location.
  580.  
  581. 
  582. File: libg++.info,  Node: Headers,  Next: Builtin,  Prev: Pix,  Up: Top
  583.  
  584. Header files for interfacing C++ to C
  585. *************************************
  586.  
  587.    The following files are provided so that C++ programmers may invoke
  588. common C library and system calls. The names and contents of these
  589. files are subject to change in order to be compatible with the
  590. forthcoming GNU C library. Other files, not listed here, are simply
  591. C++-compatible interfaces to corresponding C library files.
  592.  
  593. `values.h'
  594.      A collection of constants defining the numbers of bits in builtin
  595.      types, minimum and maximum values, and the like. Most names are
  596.      the same as those found in `values.h' found on Sun systems.
  597.  
  598. `std.h'
  599.      A collection of common system calls and `libc.a' functions.  Only
  600.      those functions that can be declared without introducing new type
  601.      definitions (socket structures, for example) are provided. Common
  602.      `char*' functions (like `strcmp') are among the declarations. All
  603.      functions are declared along with their library names, so that
  604.      they may be safely overloaded.
  605.  
  606. `string.h'
  607.      This file merely includes `<std.h>', where string function
  608.      prototypes are declared. This is a workaround for the fact that
  609.      system `string.h' and `strings.h' files often differ in contents.
  610.  
  611. `osfcn.h'
  612.      This file merely includes `<std.h>', where system function
  613.      prototypes are declared.
  614.  
  615. `libc.h'
  616.      This file merely includes `<std.h>', where C library function
  617.      prototypes are declared.
  618.  
  619. `math.h'
  620.      A collection of prototypes for functions usually found in libm.a,
  621.      plus some `#define'd constants that appear to be consistent with
  622.      those provided in the AT&T version. The value of `HUGE' should be
  623.      checked before using. Declarations of all common math functions
  624.      are preceded with `overload' declarations, since these are
  625.      commonly overloaded.
  626.  
  627. `stdio.h'
  628.      Declaration of `FILE' (`_iobuf'), common macros (like `getc'), and
  629.      function prototypes for `libc.a' functions that operate on
  630.      `FILE*''s. The value `BUFSIZ' and the declaration of `_iobuf'
  631.      should be checked before using.
  632.  
  633. `assert.h'
  634.      C++ versions of assert macros.
  635.  
  636. `generic.h'
  637.      String concatenation macros useful in creating generic classes.
  638.      They are similar in function to the AT&T CC versions.
  639.  
  640. `new.h'
  641.      Declarations of the default global operator new, the two-argument
  642.      placement version, and associated error handlers.
  643.  
  644. 
  645. File: libg++.info,  Node: Builtin,  Next: New,  Prev: Headers,  Up: Top
  646.  
  647. Utility functions for built in types
  648. ************************************
  649.  
  650.    Files `builtin.h' and corresponding `.cc' implementation files
  651. contain various convenient inline and non-inline utility functions.
  652. These include useful enumeration types, such as `TRUE', `FALSE' ,the
  653. type definition for pointers to libg++ error handling functions, and
  654. the following functions.
  655.  
  656. `long abs(long x); double abs(double x);'
  657.      inline versions of abs. Note that the standard libc.a version,
  658.      `int abs(int)' is *not* declared as inline.
  659.  
  660. `void clearbit(long& x, long b);'
  661.      clears the b'th bit of x (inline).
  662.  
  663. `void setbit(long& x, long b);'
  664.      sets the b'th bit of x (inline)
  665.  
  666. `int testbit(long x, long b);'
  667.      returns the b'th bit of x (inline).
  668.  
  669. `int even(long y);'
  670.      returns true if x is even (inline).
  671.  
  672. `int odd(long y);'
  673.      returns true is x is odd (inline).
  674.  
  675. `int sign(long x); int sign(double x);'
  676.      returns -1, 0, or 1, indicating whether x is less than, equal to,
  677.      or greater than zero (inline).
  678.  
  679. `long gcd(long x, long y);'
  680.      returns the greatest common divisor of x and y.
  681.  
  682. `long lcm(long x, long y);'
  683.      returns the least common multiple of x and y.
  684.  
  685. `long lg(long x);'
  686.      returns the floor of the base 2 log of x.
  687.  
  688. `long pow(long x, long y); double pow(double x, long y);'
  689.      returns x to the integer power y using via the iterative O(log y)
  690.      "Russian peasant" method.
  691.  
  692. `long sqr(long x); double sqr(double x);'
  693.      returns x squared (inline).
  694.  
  695. `long sqrt(long y);'
  696.      returns the floor of the square root of x.
  697.  
  698. `unsigned int hashpjw(const char* s);'
  699.      a hash function for null-terminated char* strings using the method
  700.      described in Aho, Sethi, & Ullman, p 436.
  701.  
  702. `unsigned int multiplicativehash(int x);'
  703.      a hash function for integers that returns the lower bits of
  704.      multiplying x by the golden ratio times pow(2, 32).  See Knuth,
  705.      Vol 3, p 508.
  706.  
  707. `unsigned int foldhash(double x);'
  708.      a hash function for doubles that exclusive-or's the first and
  709.      second words of x, returning the result as an integer.
  710.  
  711. `double start_timer()'
  712.      Starts a process timer.
  713.  
  714. `double return_elapsed_time(double last_time)'
  715.      Returns the process time since last_time.  If last_time == 0
  716.      returns the time since the last start_timer.  Returns -1 if
  717.      start_timer was not first called.
  718.  
  719.    File `Maxima.h' includes versions of `MAX, MIN' for builtin types.
  720.  
  721.    File `compare.h' includes versions of `compare(x, y)' for builtin
  722. types. These return negative if the first argument is less than the
  723. second, zero for equal, and positive for greater.
  724.  
  725. 
  726. File: libg++.info,  Node: New,  Next: Stream,  Prev: Builtin,  Up: Top
  727.  
  728. Library dynamic allocation primitives
  729. *************************************
  730.  
  731.    Libg++ contains versions of `malloc, free, realloc' that were
  732. designed to be well-tuned to C++ applications. The source file
  733. `malloc.c' contains some design and implementation details.  Here are
  734. the major user-visible differences from most system malloc routines:
  735.  
  736.   1. These routines *overwrite* storage of freed space. This means that
  737.      it is never permissible to use a `delete''d object in any way.
  738.      Doing so will either result in trapped fatal errors or random
  739.      aborts within malloc, free, or realloc.
  740.  
  741.   2. The routines tend to perform well when a large number of objects
  742.      of the same size are allocated and freed. You may find that it is
  743.      not worth it to create your own special allocation schemes in such
  744.      cases.
  745.  
  746.   3. The library sets top-level `operator new()' to call malloc and
  747.      `operator delete()' to call free. Of course, you may override these
  748.      definitions in C++ programs by creating your own operators that
  749.      will take precedence over the library versions. However, if you do
  750.      so, be sure to define *both* `operator new()' and `operator
  751.      delete()'.
  752.  
  753.   4. These routines do *not* support the odd convention, maintained by
  754.      some versions of malloc, that you may call `realloc' with a pointer
  755.      that has been `free''d.
  756.  
  757.   5. The routines automatically perform simple checks on `free''d
  758.      pointers that can often determine whether users have accidentally
  759.      written beyond the boundaries of allocated space, resulting in a
  760.      fatal error.
  761.  
  762.   6. The function `malloc_usable_size(void* p)' returns the number of
  763.      bytes actually allocated for `p'. For a valid pointer (i.e., one
  764.      that has been `malloc''d or `realloc''d but not yet `free''d) this
  765.      will return a number greater than or equal to the requested size,
  766.      else it will normally return 0. Unfortunately, a non-zero return
  767.      can not be an absolutely perfect indication of lack of error. If a
  768.      chunk has been `free''d but then re-allocated for a different
  769.      purpose somewhere elsewhere, then `malloc_usable_size' will return
  770.      non-zero. Despite this, the function can be very valuable for
  771.      performing run-time consistency checks.
  772.  
  773.   7. `malloc' requires 8 bytes of overhead per allocated chunk, plus a
  774.      mmaximum alignment adjustment of 8 bytes. The number of bytes of
  775.      usable space is exactly as requested, rounded to the nearest 8
  776.      byte boundary.
  777.  
  778.   8. The routines do *not* contain any synchronization support for
  779.      multiprocessing. If you perform global allocation on a shared
  780.      memory multiprocessor, you should disable compilation and use of
  781.      libg++ malloc in the distribution `Makefile' and use your system
  782.      version of malloc.
  783.  
  784.  
  785. 
  786. File: libg++.info,  Node: Stream,  Next: Obstack,  Prev: New,  Up: Top
  787.  
  788. The old I/O library
  789. *******************
  790.  
  791.    WARNING: This chapter describes classes that are *obsolete*.  These
  792. classes are normally not available when libg++ is installed normally.
  793. The sources are currently included in the distribution, and you can
  794. configure libg++ to use these classes instead of the new iostream
  795. classes.  This is only a temporary measure; you should convert your
  796. code to use iostreams as soon as possible.  The iostream classes
  797. provide some compatibility support, but it is very incomplete (there is
  798. no longer a `File' class).
  799.  
  800. File-based classes
  801. ==================
  802.  
  803.    The `File' class supports basic IO on Unix files.  Operations are
  804. based on common C stdio library functions.
  805.  
  806.    `File' serves as the base class for istreams, ostreams, and other
  807. derived classes. It contains the interface between the Unix stdio file
  808. library and these more structured classes.  Most operations are
  809. implemented as simple calls to stdio functions. `File' class operations
  810. are also fully compatible with raw system file reads and writes (like
  811. the system `read' and `lseek' calls) when buffering is disabled (see
  812. below).  The `FILE*' stdio file pointer is, however maintained as
  813. protected.  Classes derived from File may only use the IO operations
  814. provided by File, which encompass essentially all stdio capabilities.
  815.  
  816.    The class contains four general kinds of functions: methods for
  817. binding `File's to physical Unix files, basic IO methods, file and
  818. buffer control methods, and methods for maintaining logical and
  819. physical file status.
  820.  
  821.    Binding and related tasks are accomplished via `File' constructors
  822. and destructors, and member functions `open, close, remove, filedesc,
  823. name, setname'.
  824.  
  825.    If a file name is provided in a constructor or open, it is
  826. maintained as class variable `nm' and is accessible via `name'.  If no
  827. name is provided, then `nm' remains null, except that `Files' bound to
  828. the default files stdin, stdout, and stderr are automatically given the
  829. names `(stdin), (stdout), (stderr)' respectively.  The function
  830. `setname' may be used to change the internal name of the `File'. This
  831. does not change the name of the physical file bound to the File.
  832.  
  833.    The member function `close' closes a file.  The `~File' destructor
  834. closes a file if it is open, except that stdin, stdout, and stderr are
  835. flushed but left open for the system to close on program exit since
  836. some systems may require this, and on others it does not matter.
  837. `remove' closes the file, and then deletes it if possible by calling the
  838. system function to delete the file with the name provided in the `nm'
  839. field.
  840.  
  841. Basic IO
  842. ========
  843.  
  844.    * `read' and `write' perform binary IO via stdio `fread' and
  845.      `fwrite'.
  846.  
  847.    * `get' and `put' for chars invoke stdio `getc' and `putc' macros.
  848.  
  849.    * `put(const char* s)' outputs a null-terminated string via stdio
  850.      `fputs'.
  851.  
  852.    * `unget' and `putback' are synonyms.  Both call stdio `ungetc'.
  853.  
  854. File Control
  855. ============
  856.  
  857.    `flush', `seek', `tell', and `tell' call the corresponding stdio
  858. functions.
  859.  
  860.    `flush(char)' and `fill()' call stdio `_flsbuf' and `_filbuf'
  861. respectively.
  862.  
  863.    `setbuf' is mainly useful to turn off buffering in cases where
  864. nonsequential binary IO is being performed. `raw' is a synonym for
  865. `setbuf(_IONBF)'.  After a `f.raw()', using the stdio functions instead
  866. of the system `read, write', etc., calls entails very little overhead.
  867. Moreover, these become fully compatible with intermixed system calls
  868. (e.g., `lseek(f.filedesc(), 0, 0)'). While intermixing `File' and
  869. system IO calls is not at all recommended, this technique does allow
  870. the `File' class to be used in conjunction with other functions and
  871. libraries already set up to operate on file descriptors. `setbuf'
  872. should be called at most once after a constructor or open, but before
  873. any IO.
  874.  
  875. File Status
  876. ===========
  877.  
  878.    File status is maintained in several ways.
  879.  
  880.    A `File' may be checked for accessibility via `is_open()', which
  881. returns true if the File is bound to a usable physical file,
  882. `readable()', which returns true if the File can be read from (opened
  883. for reading, and not in a _fail state), or `writable()', which returns
  884. true if the File can be written to.
  885.  
  886.    `File' operations return their status via two means: failure and
  887. success are represented via the logical state. Also, the return values
  888. of invoked stdio and system functions that return useful numeric values
  889. (not just failure/success flags) are held in a class variable
  890. accessible via `iocount'.  (This is useful, for example, in determining
  891. the number of items actually read by the `read' function.)
  892.  
  893.    Like the AT&T i/o-stream classes, but unlike the description in the
  894. Stroustrup book, p238, `rdstate()' returns the bitwise OR of `_eof',
  895. `_fail' and `_bad', not necessarily distinct values. The functions
  896. `eof()', `fail()', `bad()', and `good()' can be used to test for each of
  897. these conditions independently.
  898.  
  899.    `_fail' becomes set for any input operation that could not read in
  900. the desired data, and for other failed operations. As with all Unix IO,
  901. `_eof' becomes true only when an input operations fails because of an
  902. end of file. Therefore, `_eof' is not immediately true after the last
  903. successful read of a file, but only after one final read attempt. Thus,
  904. for input operations, `_fail' and `_eof' almost always become true at
  905. the same time.  `bad' is set for unbound files, and may also be set by
  906. applications in order to communicate input corruption. Conversely,
  907. `_good' is defined as 0 and is returned by `rdstate()' if all is well.
  908.  
  909.    The state may be modified via `clear(flag)', which, despite its
  910. name, sets the corresponding state_value flag.  `clear()' with no
  911. arguments resets the state to `_good'.  `failif(int cond)' sets the
  912. state to `_fail' only if `cond' is true.
  913.  
  914.    Errors occuring during constructors and file opens also invoke the
  915. function `error'.  `error' in turn calls a resetable error handling
  916. function pointed to by the non-member global variable
  917. `File_error_handler' only if a system error has been generated.  Since
  918. `error' cannot tell if the current system error is actually responsible
  919. for a failure, it may at times print out spurious messages.  Three
  920. error handlers are provided. The default, `verbose_File_error_handler'
  921. calls the system function `perror' to print the corresponding error
  922. message on standard error, and then returns to the caller.
  923. `quiet_File_error_handler' does nothing, and simply returns.
  924. `fatal_File_error_handler' prints the error and then aborts execution.
  925. These three handlers, or any other user-defined error handlers can be
  926. selected via the non-member function `set_File_error_handler'.
  927.  
  928.    All read and write operations communicate either logical or physical
  929. failure by setting the `_fail' flag.  All further operations are
  930. blocked if the state is in a `_fail' or`_bad' condition. Programmers
  931. must explicitly use `clear()' to reset the state in order to continue
  932. IO processing after either a logical or physical failure.  C
  933. programmers who are unfamiliar with these conventions should note that,
  934. unlike the stdio library, `File' functions indicate IO success, status,
  935. or failure solely through the state, not via return values of the
  936. functions.  The `void*' operator or `rdstate()' may be used to test
  937. success.  In particular, according to c++ conversion rules, the `void*'
  938. coercion is automatically applied whenever the `File&' return value of
  939. any `File' function is tested in an `if' or `while'.  Thus, for
  940. example, an easy way to copy all of stdin to stdout until eof (at which
  941. point `get' fails) or some error is `char c; while(cin.get(c) &&
  942. cout.put(c));'.
  943.  
  944.    The current version of istreams and ostreams differs significantly
  945. from previous versions in order to obtain compatibility with AT&T 1.2
  946. streams. Most code using previous versions should still work. However,
  947. the following features of `File' are not incorporated in streams (they
  948. are still present in `File'): `scan(const char* fmt...), remove(),
  949. read(), write(), setbuf(), raw()'. Additionally, the feature of
  950. previous streams that allowed free intermixing of stream and stdio
  951. input and output is no longer guaranteed to always behave as desired.
  952.  
  953. 
  954. File: libg++.info,  Node: Obstack,  Next: AllocRing,  Prev: Stream,  Up: Top
  955.  
  956. The Obstack class
  957. *****************
  958.  
  959.    The `Obstack' class is a simple rewrite of the C obstack macros and
  960. functions provided in the GNU CC compiler source distribution.
  961.  
  962.    Obstacks provide a simple method of creating and maintaining a string
  963. table, optimized for the very frequent task of building strings
  964. character-by-character, and sometimes keeping them, and sometimes not.
  965. They seem especially useful in any parsing application. One of the test
  966. files demonstrates usage.
  967.  
  968.    A brief summary:
  969. `grow'
  970.      places something on the obstack without committing to wrap it up
  971.      as a single entity yet.
  972.  
  973. `finish'
  974.      wraps up a constructed object as a single entity, and returns the
  975.      pointer to its start address.
  976.  
  977. `copy'
  978.      places things on the obstack, and *does* wrap them up.  `copy' is
  979.      always equivalent to first grow, then finish.
  980.  
  981. `free'
  982.      deletes something, and anything else put on the obstack since its
  983.      creation.
  984.  
  985.    The other functions are less commonly needed:
  986. `blank'
  987.      is like grow, except it just grows the space by size units without
  988.      placing anything into this space
  989.  
  990. `alloc'
  991.      is like `blank', but it wraps up the object and returns its
  992.      starting address.
  993.  
  994. `chunk_size, base, next_free, alignment_mask, size, room'
  995.      returns the appropriate class variables.
  996.  
  997. `grow_fast'
  998.      places a character on the obstack without checking if there is
  999.      enough room.
  1000.  
  1001. `blank_fast'
  1002.      like `blank', but without checking if there is enough room.
  1003.  
  1004. `shrink(int n)'
  1005.      shrink the current chunk by n bytes.
  1006.  
  1007. `contains(void* addr)'
  1008.      returns true if the Obstack holds the address addr.
  1009.  
  1010.    Here is a lightly edited version of the original C documentation:
  1011.  
  1012.    These functions operate a stack of objects.  Each object starts life
  1013. small, and may grow to maturity.  (Consider building a word syllable by
  1014. syllable.)  An object can move while it is growing.  Once it has been
  1015. "finished" it never changes address again.  So the "top of the stack"
  1016. is typically an immature growing object, while the rest of the stack is
  1017. of mature, fixed size and fixed address objects.
  1018.  
  1019.    These routines grab large chunks of memory, using the GNU C++ `new'
  1020. operator.  On occasion, they free chunks, via `delete'.
  1021.  
  1022.    Each independent stack is represented by a Obstack.
  1023.  
  1024.    One motivation for this package is the problem of growing char
  1025. strings in symbol tables.  Unless you are a "fascist pig with a
  1026. read-only mind" [Gosper's immortal quote from HAKMEM item 154, out of
  1027. context] you would not like to put any arbitrary upper limit on the
  1028. length of your symbols.
  1029.  
  1030.    In practice this often means you will build many short symbols and a
  1031. few long symbols.  At the time you are reading a symbol you don't know
  1032. how long it is.  One traditional method is to read a symbol into a
  1033. buffer, `realloc()'ating the buffer every time you try to read a symbol
  1034. that is longer than the buffer.  This is beaut, but you still will want
  1035. to copy the symbol from the buffer to a more permanent symbol-table
  1036. entry say about half the time.
  1037.  
  1038.    With obstacks, you can work differently.  Use one obstack for all
  1039. symbol names.  As you read a symbol, grow the name in the obstack
  1040. gradually.  When the name is complete, finalize it.  Then, if the
  1041. symbol exists already, free the newly read name.
  1042.  
  1043.    The way we do this is to take a large chunk, allocating memory from
  1044. low addresses.  When you want to build a symbol in the chunk you just
  1045. add chars above the current "high water mark" in the chunk.  When you
  1046. have finished adding chars, because you got to the end of the symbol,
  1047. you know how long the chars are, and you can create a new object.
  1048. Mostly the chars will not burst over the highest address of the chunk,
  1049. because you would typically expect a chunk to be (say) 100 times as
  1050. long as an average object.
  1051.  
  1052.    In case that isn't clear, when we have enough chars to make up the
  1053. object, *they are already contiguous in the chunk* (guaranteed) so we
  1054. just point to it where it lies.  No moving of chars is needed and this
  1055. is the second win: potentially long strings need never be explicitly
  1056. shuffled. Once an object is formed, it does not change its address
  1057. during its lifetime.
  1058.  
  1059.    When the chars burst over a chunk boundary, we allocate a larger
  1060. chunk, and then copy the partly formed object from the end of the old
  1061. chunk to the beginning of the new larger chunk.  We then carry on
  1062. accreting characters to the end of the object as we normally would.
  1063.  
  1064.    A special version of grow is provided to add a single char at a time
  1065. to a growing object.
  1066.  
  1067.    Summary:
  1068.  
  1069.    * We allocate large chunks.
  1070.  
  1071.    * We carve out one object at a time from the current chunk.
  1072.  
  1073.    * Once carved, an object never moves.
  1074.  
  1075.    * We are free to append data of any size to the currently growing
  1076.      object.
  1077.  
  1078.    * Exactly one object is growing in an obstack at any one time.
  1079.  
  1080.    * You can run one obstack per control block.
  1081.  
  1082.    * You may have as many control blocks as you dare.
  1083.  
  1084.    * Because of the way we do it, you can `unwind' a obstack back to a
  1085.      previous state. (You may remove objects much as you would with a
  1086.      stack.)
  1087.  
  1088.    The obstack data structure is used in many places in the GNU C++
  1089. compiler.
  1090.  
  1091.    Differences from the the GNU C version
  1092.   1. The obvious differences stemming from the use of classes and
  1093.      inline functions instead of structs and macros. The C `init' and
  1094.      `begin' macros are replaced by constructors.
  1095.  
  1096.   2. Overloaded function names are used for grow (and others), rather
  1097.      than the C `grow', `grow0', etc.
  1098.  
  1099.   3. All dynamic allocation uses the the built-in `new' operator.  This
  1100.      restricts flexibility by a little, but maintains compatibility
  1101.      with usual C++ conventions.
  1102.  
  1103.   4. There are now two versions of finish:
  1104.  
  1105.        1. finish() behaves like the C version.
  1106.  
  1107.        2. finish(char terminator) adds `terminator', and then calls
  1108.           `finish()'.  This enables the normal invocation of
  1109.           `finish(0)' to wrap up a string being grown
  1110.           character-by-character.
  1111.  
  1112.   5. There are special versions of grow(const char* s) and copy(const
  1113.      char* s) that add the null-terminated string `s' after computing
  1114.      its length.
  1115.  
  1116.   6. The shrink and contains functions are provided.
  1117.  
  1118.  
  1119. 
  1120. File: libg++.info,  Node: AllocRing,  Next: String,  Prev: Obstack,  Up: Top
  1121.  
  1122. The AllocRing class
  1123. *******************
  1124.  
  1125.    An AllocRing is a bounded ring (circular list), each of whose
  1126. elements contains a pointer to some space allocated via `new
  1127. char[some_size]'. The entries are used cyclicly.  The size, n, of the
  1128. ring is fixed at construction. After that, every nth use of the ring
  1129. will reuse (or reallocate) the same space. AllocRings are needed in
  1130. order to temporarily hold chunks of space that are needed transiently,
  1131. but across constructor-destructor scopes. They mainly useful for storing
  1132. strings containing formatted characters to print across various
  1133. functions and coercions. These strings are needed across routines, so
  1134. may not be deleted in any one of them, but should be recovered at some
  1135. point. In other words, an AllocRing is an extremely simple minded
  1136. garbage collection mechanism. The GNU C++ library used to use one
  1137. AllocRing for such formatting purposes, but it is being phased out, and
  1138. is now only used by obsolete functions.  These days, AllocRings are
  1139. probably not very useful.
  1140.  
  1141.    Support includes:
  1142.  
  1143. `AllocRing a(int n)'
  1144.      constructs an Alloc ring with n entries, all null.
  1145.  
  1146. `void* mem = a.alloc(sz)'
  1147.      moves the ring pointer to the next entry, and reuses the space if
  1148.      their is enough, also allocates space via new char[sz].
  1149.  
  1150. `int present = a.contains(void* ptr)'
  1151.      returns true if ptr is held in one of the ring entries.
  1152.  
  1153. `a.clear()'
  1154.      deletes all space pointed to in any entry. This is called
  1155.      automatically upon destruction.
  1156.  
  1157. `a.free(void* ptr)'
  1158.      If ptr is one of the entries, calls delete of the pointer, and
  1159.      resets to entry pointer to null.
  1160.  
  1161.