1. Introduction

1.1. Library contents and limitations

The graphics classes are not intended to be a professional-level set of classes. They are directly tailored to this book, and its many inefficiencies make them unsuitable for general-purpose programming. The same holds for the date class, the graphics editor and simulation frameworks, and the persistent stream class. The code for all these classes (with the possible exception of some wizardry in the persistent streams) is intended to be read and understood by students.

The list, queue, and priority queue templates are not particularly efficient, but the code is accessible to the interested reader. Like most libraries on the market, they are also somewhat unsafe: Iterators can point to deleted elements or be attached to destroyed lists. Using such iterators leads to `undefined behavior'. Professional-level templates should use copy on write and safe iterators, but that would make the code much harder to read.

The array template and string classes are highly optimized for efficiency, and the code is neither accessible nor particularly interesting from the perspective of object-oriented design. They have proven to be marvelous tools to eliminate the drudgery of managing pointers and heap memory. They are quite efficient--certainly ample for instructional and prototyping use.

The class for argument parsing is a simplified version of a professional- level class, with some of the more confusing options removed. In this book, it is used only to eliminate the need to use C strings in parsing command line arguments.

1.2. Name prefixes

		namespace Cay_Horstmanns_Interesting_Library

but at the time of this writing, all classes and templates are prefixed with Chi_, such as Chi_Array, Chi_String, Chi_List, Chi_Date.

In all documentation and printed code samples in this book, the Chi_ prefix is not included because it just clutters up the code. (Of course, the code on the disk has the prefix.) Library users must remember to supply the prefix in actual code. This sounds like yet another nuisance, but it has proven not to be a problem in practice.

1.3. Error handling

If no exception support is available from the compiler, the library ensures that assertion failures are raised from a specific function Error::abort. Set a breakpoint in that function to trap the error and inspect the call stack. Once the program is aborted, the call stack is gone and it is difficult to find the cause of the error. (Of course, the error object stores and prints the file name and line number of the code that generated the error, but that is the library code. Knowing that an array bounds error occurred in file chiarray.cpp, line number 151, doesn't help much.)

1.4. Organization of files

The optimal setup is the following:

1. Place a directory, chilib, at an appropriate place (under /usr/local or \spring95\cs151 or wherever), and make subdirectories include, source, sample, and lib.
2. Compile all files in the source directory and make them into a library archive. Place it into the lib directory. A make file to build the library for some compilers is supplied.
3. Add the path to the chilib\include subdirectory to the compiler's path for searching include files, the path to chilib\lib to the linker's path for searching libraries. The method for achieving that differs from one compiler to the next.

To use the library, the user simply includes the appropriate header file, such as <chiarray.h>, and builds the program in the normal way.

The optimal setup requires more control over the computing environment than instructors and students typically have. An alternate setup is less efficient but does not require system administration knowledge or privileges. This setup presumes that you have a private directory to work on the book lessons. Do the following.

1. Copy the source and include files onto the work directory. They all start with chi....., to make them easy to identify if you want to move to them to another computer or (gasp!) delete them.
2. Make a subdirectory sample under your current directory to hold the sample files.

1.5. Building programs

The library contains the following header files:

You should include them in the normal way, with the preprocessor directive

      #include "chixxxxx.h"  

(You can use #include <chixxxxx.h> if the chilib\include directory has been added to the search path for header files. That saves a millisecond or so by skipping the search on the current directory.) When including chigc.h, you must #define one of CHI_BGI, CHI_WIN, or CHI_X11.

To build a program containing one or more library components, you have two choices. The simpler one for everyday work requires that you (or a knowledgeable person such as the system administrator) precompile all library sources to a library archive (chilib.lib or chilib.a). You then direct the compiler to search that library. Instructions differ for each compiler. Make files for some compilers have been provided. Under DOS and Windows the memory model matters, and you need to specify chilibs for small and chilibl for large model.

The other choice is to add all source files that you need to the current project. For example, if you use shapes, you need to include chishape.cpp, chigc.cpp, chiarray.cpp, chistr.cpp, and chierror.cpp, and of course the source file(s) including your own code. The old-fashioned method is to write a make file, but most modern compilation environment have a tool to specify projects in a more convenient way.

All modules require that chierror be present. There are several different implementations of the graphics context: chigcbgi for the Borland Graphics Interface under DOS, chigcwin for Windows, and chigcx11 for Xlib. If you forget to include a module in the project, the linker will complain about unresolved external names. The names should give you a hint which module is missing.