This chapter includes the following sections:
Tools.h++ is a rich, robust, and versatile C++ foundation class library: a set of software parts you can use to build virtually any application.
Tools.h++ is an industry standard. It is shipped by a wide variety of compiler vendors with every copy of their compilers. Preferred by thousands of users world wide, it is ported to numerous compilers and operating systems. Tools.h++ is available on almost any development platform you choose.
This new version of Tools.h++ is built on the Standard C++ Library. To aid your transition into this technology, Tools.h++ provides a familiar object-oriented interface, and a reliable upward migration path. You can count on Tools.h++ to track and incorporate revisions of the Standard C++ Library as they are approved.
Your new Tools.h++ package includes:
Powerful single, multibyte, and wide character support
You can manipulate single and multibyte strings with class RWCString's full suite of operators and functions, or choose class RWWString for wide character strings. Both classes make it easy to do concatenation, comparison, indexing (with optional bounds checking), I/O, case changes, stripping, and many other functions. In addition, classes RWCSubString and RWWSubString allow extraction and assignment to substrings; classes RWCRegexp and RWCRExpr support regular expression pattern searches; and classes RWCTokenizer and RWWTokenizer break single and wide character strings, respectively, into separate tokens.
Extended regular expressions
Here's a richer set of pattern matching tools you can use to search for information in strings. The new Tools.h++ extended regular expression features are a subset of those found in the ANSI/ISO standard POSIX.2 (Portable Operating System Interface), and require the presence of the Standard C++ Library.
Time and date handling classes
You can calculate the number of days between two dates, or the day of the week a date represents. Read and write days or times in arbitrary formats, or whatever you need to do. Tools.h++ helps you master time.
Internationalization support
You can internationalize your software with the convenient and easy-to-use framework of class RWLocale, and use class RWTimeZone to manipulate time zones and daylight-saving time. The entire library is eight-bit clean, so you can use it with any eight-bit character set. Embedded nulls are fully supported.
Endian streams
You can transfer information between operating systems with the efficiency of a binary stream. The endian streams mechanism, which keeps a record of the operating environment where information originates, allows the stream to be read on any system regardless of its native size or byte order.
Multithread safe
You can count on multithread safety. When compiled with a multithread option, the library uses multithread safe system facilities, with enough internal locking to maintain its internal integrity. See the release notes for your compiler.
Persistent store
This new version of Tools.h++ enhances an already powerful and sophisticated store facility. Isomorphic persistence, which maintains an object's pointer relationships, is now supported for most Tools.h++ collections, including the template-based collections. You can also implement isomorphic persistence on your own classes. Objects that inherit from RWCollectable have polymorphic persistence, which not only maintains pointer-relationships, but also allows processes to restore objects without knowing their types.
Template based classes
Twenty-eight new or re-engineered class templates based on the Standard C++ Library container classes. You can use the full interface to these classes if your development environment supports the Standard C++ Library. If you don't have the Standard C++ Library, Tools.h++ supplies template-based classes with a subset of the same interfaces.
Generic collection classes
If your compiler does not yet support templates, Tools.h++ includes a set of template-like classes that use the C++ preprocessor and <generic.h>, a header file included with most compilers. The interface to these generic classes is similar to the template-based classes, so you can make an easy transition.
Smalltalk-like collection classes
You get a complete library of collection classes, modeled after the Smalltalk-80 programming environment, including Set, Bag, Queue, Stack, OrderedCollection, SortedCollection, Dictionary, and more.
Many other features: RWFile Class encapsulates standard file operations. B-tree disk retrieval uses B-trees for efficient keyed access to disk records. File Space Manager allocates, deallocates and coalesces free space within a file. A complete error handling facility, which takes advantage of C++ exceptions if they are available. Still more classes, including: bit vectors, virtual I/O streams, cache managers, and virtual arrays.
If you're familiar with C++, you'll feel comfortable with Tools.h++. As a C++ class library, Tools.h++ shares many design goals with the C++ language itself. These mutual goals include:
Efficiency. In general, you will find no feature in Tools.h++ that impairs non-users of the feature. As many decisions as possible are made at compile time, consistent with the C++ philosophy of static type checking. In most cases, Tools.h++ offers you a choice between classes with extreme simplicity, but little generality, and complex classes with more generality.
Simplicity. To maintain simplicity, Tools.h++ uses few subclasses. Although the overall architecture is sophisticated and integrated, each class usually plays just one well-defined role. Many functions are also simple, consisting of a few lines of code. New features are added sparingly: in general, if there is already a way to do it, we leave it out!
Compactness. Like C++, Tools.h++ aims to make programs compile small. Always a desirable design goal, it also facilitates using programs in embedded systems. Templates have a mixed effect in this regard: encouraging compact source code, but in many cases compromising compactness when compiling.
Predictability. All of the familiar operators work just as you might expect—there are no surprises, no esoteric overloaded operators. And Tools.h++ offers you great symmetry, making it possible to do things like change the implementation of a dictionary from a hash table to a B-tree with impunity.
Almost everybody sees the benefits of standardizing the C++ language and the Standard C++ Library. The trick is to keep working during the process. We call this a period of transition, and the C++ community is engaged in it now.
Here is what the transition looks like: a standard nearing completion, but not yet fully stable. Although the standard itself is unlikely to be substantially revised, the fine tuning and ratification will continue into 1997.
And here is what the transition looks like: compilers evolving toward the standard at various rates. For a time, you will find new language features—such as namespaces, default template arguments, member function templates, nested class templates—supported on some compilers and not others. Some compilers may not even include a version of the Standard C++ Library; many will offer versions which conform to the standard only so far as they support the necessary language features. It will be some time before commercial compilers actually implement the exact C++ language, or include the Standard C++ Library as described in the standard.
Finally, here is what the transition looks like: you, the developer, and what you're going through now. You are the one evolving designs and implementations toward the emerging standard. Change will come at rates determined by your development environment, application domain, and corporate culture.
Our goal for Tools.h++ is to help you to maintain consistency in your development while moving, at your own pace, along the path of the latest C++ technology.
The primary challenge of this new version of Tools.h++ was to establish our relationship with the ANSI/ISO Standard C++ Library. Rogue Wave is committed not only to bringing our products into compliance with the standard, but to harnessing its full power. The object is to provide you with even more useful and efficient class libraries. The process of integrating our libraries with the C++ standard begins here with Tools.h++ Version 7.
For this version of Tools.h++, we have concentrated our integration efforts on the Standard C++ Library containers, often referred to as the STL or Standard Template Library. Each of the standard containers has been wrapped with a new or re-engineered Tools.h++ collection class template. You'll find a full explanation of templates in Section 11XX. Following are the major design goals for our integration of Tools.h++ and the Standard C++ Library, along with examples of how they are reflected in this version:
Design Goal: Leverage
To offer greater value by taking advantage of the Standard C++ Library to build upon a higher foundation than the base C++ language.
For example, Tools.h++ offers collections that use Standard C++ Library containers for their implementations. Building Tools.h++ upon the standard enables these collections to easily supply standard iterators, which in turn allows them to be used with the rich set of Standard C++ Library algorithms. At the same time, you retain the sTo support one of the primary benefits of the C++ standard, which is to allow libraries,
modules, classes, and algorithms from diverse providers to easily work together at a high
level.
afe, easy-to-use, object-oriented interface that Tools.h++ collections have always provided.
Design Goals: Interoperability
To support one of the primary benefits of the C++ standard, which is to allow libraries, modules, classes, and algorithms from diverse providers to easily work together at a high level.
For example, we made sure you can safely and efficiently pass a Tools.h++ doubly-linked list where a Standard C++ Library list is expected.
Design Goal: Freedom
To maintain access to the Standard C++ Library.
For example, when using a Tools.h++ collection implemented with a Standard C++ Library container, you are always free to drop down to the level of the implementation that takes advantage of the non-object-oriented features of the Standard C++ Library.
Design Goal: Object-orientation
To enhance the Standard C++ Library with efficient, object-oriented interfaces.
All our new and re-engineered collection class templates exemplify this goal. In each case, we have put an efficient wrapper around a corresponding Standard C++ Library container to provide a familiar, though expanded, Tools.h++ collection interface.
Design Goals: Simplicity and Safety
To enhance the Standard C++ Library with a simpler interface, which reduces risk and makes client code easily maintainable.
The object-oriented interface helps achieve this goal. Unlike the Standard C++ Library, the Tools.h++ container methods know what data they control, freeing the user from the need to specify iterators and algorithms.
Design Goal: Compatibility
To protect our customers' investment in code written with previous versions of Tools.h++.
For example, we have re-engineered the Tools.h++ Version 6.1 collection class templates to base them on Standard C++ Library containers. In almost all cases, your existing source code that used classes in the previous version of the library will compile with the new library without modification.
Design Goal: Smooth Transition
To provide the means for developers to begin moving along the path toward standard C++ at their own pace and with minimal hassle.
For example, you can use Tools.h++ with or without the Standard C++ Library. If your development environment supports a version of the Standard C++ Library certified for use with Tools.h++, we offer 28 new or re-engineered class templates implemented using the Standard C++ Library container classes. If you don't have the Standard C++ Library, we offer you a subset interface to many of the same class templates, implemented using the technology of previous versions of Tools.h++. The appropriate implementation is selected automatically and transparently at compile time. By coding to the more restricted interface, you will be able to take full advantage of the Standard C++ Library as soon as it becomes available to you.
Future versions of Tools.h++ will make full use of the Standard C++ Library and other newly added features of the C++ language. This version includes several areas where we have elected to wait before incorporating the latest available technology. In some cases, we're waiting until the standard library or language feature is more widely available. In other cases, frankly, we're waiting until we gain more experience with the new features to see how we can best mold them into a unified and effective whole. We want to be careful not to commit ourselves and our customers to less than optimal patterns of usage. In the meantime, we'd like to draw your attention to the following areas:
RWCString and RWWString
Tools.h++ continues to use classes RWCString and RWWString. These classes, along with their substring classes and collaborating regular expression and tokenizer classes, have long been considered among the most useful and powerful classes in the library. This suite of functionality is not offered by the Standard C++ Library. You may use the C++ standard string and wstring in your applications, but you may occasionally incur the overhead of copying if you must convert between Tools.h++ and standard strings.
RWLocale
Tools.h++ continues to use class RWLocale. At the time of this release, the C++ standard locale class specification is still undergoing review by the ANSI/ISO standards committees.
Exception Hierarchy
Tools.h++ continues to use its own exception hierarchy, which is similar to the exception hierarchy in the draft C++ Standard. We don't expect to change over until the standard exception hierarchy is more widely available. You are free to use standard exceptions in your application, but you must be prepared also to catch Tools.h++ exceptions when making calls into the Tools.h++ library from within your try blocks.
Namespaces
Tools.h++ is not yet using or attempting to use namespaces specified by the current draft. For now, we continue to use the RW prefix to distinguish our classes within the global namespace. Of course, this does not preclude you from using namespaces in your own application, if your compiler allows it.
This manual is an introduction to using Tools.h++, Rogue Wave's foundation class library. It assumes that you are familiar with C++. If you are not, you will find several books of interest in the Bibliography.
If you're an advanced C++ user, you may want to accompany this manual with Stroustrup [1991], Lippman [1991], or Ellis and Stroustrup [1990]. The latter is sometimes referred to as "The ARM," the Annotated Reference Manual. The terse but precise style of these works makes them excellent references to the language.
When reading this manual, you'll notice the following special conventions:
Courier font—Used for disk directories, file names, examples, operating system commands, function names, code and code fragments (for example, RWTPtrHashSet<int RWDefHArgs(int)> hset;, deque<T>, isEqual). Most function names start with a lower case letter, but subsequent words are capitalized (for example, compareTo()).
Italic—Used for classes (for example, RWCollectable or RWCString). Most Rogue Wave classes include a prefix RW which is capitalized. The class name conveys what the class does, and distinguishes a Rogue Wave class from the generically named class of another vendor (for example, RWIterator, not just Iterator.) Class names begin with capital letters.
Italic—Used for Rogue Wave product names (for example, Tools.h++).
Italic or bold—Conventional uses, such as emphasis or special terminology.
Bold—used in regular text to indicate functions.
Vertical ellipses—In code examples, they indicate that some part of the code is missing:
main()
{
.
. //Something happens
.
} |
To help you get a head start on your project, Rogue Wave Professional Services provides training that can put the power of Tools.h++, or any other robust Rogue Wave library, into your hands in less than a week.
Rogue Wave training and mentoring is available for all levels of project development, from analysis and design to implementation. We also offer world-class courses in C++ and object-oriented programming.
For information on Rogue Wave's products and professional services, call us by phone, contact us by e-mail, or review the information on our World Wide Web site:
Telephone: | (541) 754-5010 |
e-mail: | training@roguewave.com |
WWW: | http://www.roguewave.com |
Rogue Wave provides on-line documentation that supplements this manual. On-line documentation is in the rogue\docs directory. The docs directory contains important information regarding specific compilers and operating systems, how to use shared libraries and DLLs, and information that became available after the manual was published. We urge you to read all the files of the docs directory, but especially toolread.doc, the Tools.h++ readme file.
The Frequently Asked Questions (FAQ) document is a new feature of the Rogue Wave home page (http://www.roguewave.com). The home page also contains late-breaking information about Rogue Wave products.
Rogue Wave is proud of its reputation for superior technical support. Our support policies are described in the technical support brochure that accompanies this product. Extended technical support contracts can be purchased from Rogue Wave or authorized partners.
Your first line of technical support is the documentation provided with this product, both on-line and in the manual. Many times, you can find what you need there, and save us both a call.
If you do need to call technical support, the first thing we ask is your name, your company, and the serial number of your product. Look for this number on your disk, or contact your system administrator.
It would also save both your time and ours if you do the following before you call:
Review your information. Read relevant portions of the manual, the rogue\docs files, especially toolread.doc, and the FAQ (Frequently Asked Questions) file in the directory or at our web site.
Collect your numbers. In addition to your product serial number, we need to know what version of Tools.h++ you're using. You'll find this number at the top of toolread.doc. We'll also ask for your compiler and operating system, and their respective version numbers.
Isolate your problem to a small test case, if applicable. Short code is easier to understand, transmit, and verify on our systems..