Tools.h++ User's Guide

Chapter 1: About Tools.h++

• Overview and Features of Tools.h++

• Tools.h++ and the C++ Philosophy

• Tools.h++ and the Standardization of C++

• Harnessing the Standard

• What We Didn't Do

• Reading This Manual

Chapter 2: Class Overview

• Concrete Classes

• Simple Classes

• Template-based Collection Classes

• Generic Collection Classes

• Abstract Base Classes

• Smalltalk-like Collection Classes

• Common Member Functions

• Persistence

• Store Size

• Stream I/O

• Comparisons

• Memory Allocation and Deallocation

• Information Flow

• Multithread Safe

• Eight-bit Clean

• Embedded Nulls

• Indexing

• Version

Chapter 3: Using the String Classes

• An Introductory Example

• Lexicographic Comparisons

• Substrings

• Pattern Matching

• Simple Regular Expressions

• Extended Regular Expressions

• String I/O

• iostreams

• Virtual Streams

• Tokenizer

• Multibyte Strings

• Wide Character Strings

Chapter 4: Using Class RWDate

• Example

• Constructors

Chapter 5: Using Class RWTime

• Setting the Time Zone

• Constructors

• Member Functions

Chapter 6: Using Virtual Streams

• Specializing Virtual Streams

• Simple Example

• Windows Clipboard and DDE Streambufs

• DDE Example

• RWAuditStreamBuffer

• Recap

Chapter 7: Using Class RWFile

• Example

Chapter 8: Using Class RWFileManager

• Construction

• Member Functions

Chapter 9: Using Class RWBTreeOnDisk

• Construction

• Example

Chapter 10: Collection Classes

• Storage Methods of Collection Classes

• A Note on Memory Management

• Copying Collection Classes

• Copying Reference-based Collection Classes

• Copying Value-based Collection Classes

• Retrieving Objects in Collections

• Retrieval Methods

• Iterators in Collection Classes

• Traditional Tools.h++ Iterators

Chapter 11: Collection Class Templates

• Introduction

• Template Overview

• Template Naming Convention

• Value vs. Reference Semantics in Templates

• Intrusive Lists in Templates

• Tools.h++ Templates and the Standard C++ Library

• Standard C++ Library Not Required

• The Standard C++ Library Containers

• Commonality of Interface

• Parameter Requirements

• Comparators

• More on Total Ordering

• Hash Functors and Equalitors

• Iterators

• Standard C++ Library Iterators

• Map-Based Iteration and Pairs

• Iterators as Generalized Pointers

• Iterators and the std() Gateway

• The Best of Both Worlds

• Using Templates Without the Standard Library

• Keeping the Standard C++ Library in Mind for Portability

• An Example

• Another Example

• Migration Guide: For Users of Previous Versions of Tools.h++

Chapter 12: Generic Collection Classes

• Example

• Declaring Generic Collection Classes

• User-Defined Functions

• Tester Functions

• Apply Functions

Chapter 13: Smalltalk-Like Collection Classes

• Tables of the Smalltalk-like Classes

• Example

• Choosing a Smalltalk-like Collection Class

• Bags Versus Sets Versus Hash Tables

• Sequenceable Classes

• Dictionaries

• Virtual Functions Inherited From RWCollection

• insert()

• find() and Friends

• remove() Functions

• apply() Functions

• Functions clear() and clearAndDestroy()

• Other Functions Shared by All RWCollections

• Class Conversions

• Inserting and Removing Other Collections

• Selection

• Virtual Functions Inherited from RWSequenceable

• A Note on How Objects are Found

• Hashing

Chapter 14: Persistence

• Levels of Persistence

• A Note About Terminology

• About the Examples in this Section

• No Persistence

• Simple Persistence

• Two Examples of Simple Persistence

• Isomorphic Persistence

• Isomorphic versus Simple Persistence

• Isomorphic Persistence of a Tools.h++ Class

• Designing Your Class to Use Isomorphic Persistence

• Writing rwSaveGuts and rwRestoreGuts Functions

• Isomorphic Persistence of a User-designed Class

• Polymorphic Persistence

• Operators

• Designing your Class to Use Polymorphic Persistence

• Polymorphic Persistence Example

• A Few Friendly Warnings

• Always Save an Object by Value before Saving the Identical Object by Pointer

• Don't Save Distinct Objects with the Same Address

• Don't Use Sorted RWCollections to Store Heterogeneous RWCollectables

Chapter 15: Designing an RWCollectable Class

• Why Design an RWCollectable Class?

• An Example of RWCollectable Classes

• How to Create an RWCollectable Object

• Define a Default Constructor

• Add RWDECLARE_COLLECTABLE() to your Class Declaration

• Provide a Class Identifier for Your Class

• Add Definitions for Virtual Functions

• Object Destruction

• How to Add Polymorphic Persistence

• A Note on the RWFactory

• Summary

Chapter 16: Internationalization

• Localizing Alphabets with RWCString and RWWString

• Localizing Messages

• Challenges of Localizing Currencies, Numbers, Dates, and Times

• RWLocale and RWZone

• Dates

• Time

• Numbers

• Currency

• A Note on Setting Environment Variables

Chapter 17: Error Handling

• The Tools.h++ Error Model

• Internal Errors

• Non-recoverable Internal Errors

• Recoverable Internal Errors

• External Errors

• Exception Architecture

• Error Handlers

• The Debug Version of Tools.h++

Chapter 18: Advanced Topics

• Dynamic Link Library

• The DLL Example

• Copy on Write

• A More Comprehensive Example

• RWStringID

• Duration of Identifiers

• Programming with RWStringIDs

• Implementation Details of RWStringID

• More on Storing and Retrieving RWCollectables

• Multiple Inheritance

Chapter 19: Common Mistakes

• Redefinition of Virtual Functions

• Iterators

• Return Type of operator>>()

• Avoid Persisting Value Collections of Pointers

• Include Path

• Match Memory Models and Other Qualifiers

• Keep Related Methods Consistent

• DLL

• Use the Capabilities of the Library!

Appendix A: Choosing A Collection

• Selecting a Tools.h++ Collection Class

• How to Use the Decision Tree

• Additional Selection Criteria

• Time and Space Considerations

• RWGVector, RWGBitBec, RWTBitVec<size>, RWTPtrVector, and RWTValVector

• Singly Linked Lists

• Doubly Linked Lists

• Ordered Vectors

• Sorted Vectors

• Stacks and Queues

• Deques

• Binary Tree

• (multi)map and (multi)set family

• RWBTree, RWBTreeDictionary

• Hash_Based Collections

Appendix B: Typedefs and Macros

Appendix C: Messages

Appendix D: Bibliography