Table of Contents

There is also a listing of tables, figures, and captioned examples.

Chapter 1: Introduction

• 1.1 Overview
• 1.2 Features and Benefits
• 1.3 Examples
• 1.4 Products and Services Information

Chapter 2: Class Overview

• 2.1 Introduction
• 2.2 Class Groups
• 2.2.1 Date and Time Class Group
• 2.2.2 String Processing Class Group
• 2.2.3 Virtual Stream Class Group
• 2.2.4 Collection Class Group
• 2.2.5 Internationalization Class Group
• 2.2.6 File System Classes
• 2.2.7 Miscellaneous Class Group
• 2.3 Abstract and Concrete Classes
• 2.3.1 Concrete Classes
• 2.3.1.1 Simple Classes
• 2.3.1.2 Template-based Collection Classes
• 2.3.2 Abstract Base Classes
• 2.4 Common Functionality Among Classes
• 2.4.1 Common Member Functions
• 2.4.1.1 Persistence Functions
• 2.4.1.2 Store Size Functions
• 2.4.1.3 Stream I/O Functions
• 2.4.1.4 Comparison Functions
• 2.4.2 Memory Allocation and Deallocation
• 2.4.3 Information Flow
• 2.4.4 Multithread Safety
• 2.4.4.1 Assigning Thread Safety Levels to Classes and Libraries
• 2.4.4.2 Thread Safety in the Essential Tools Module
• 2.4.5 Indexing
• 2.4.6 Version

Chapter 3: Date and Time Classes

• 3.1 Introduction
• 3.2 Calendar and Time Formats
• 3.2.1 UTC (GMT) Dates and Times
• 3.2.2 Julian Day Number vs. Julian Date
• 3.2.3 Gregorian Calendar
• 3.3 International Standards for Dates and Times
• 3.3.1 Representing Dates
• 3.3.1.1 Complete Extended Format
• 3.3.1.2 Ordinal Dates Format
• 3.3.2 Representing Times
• 3.3.2.1 Applying the ISO Standard to Time Zone Offsets
• 3.3.3 Putting Dates and Times Together
• 3.3.4 Omitting Elements of a Date or Time String
• 3.3.5 Complete List of Supported Formats
• 3.4 Setting the Time Zone
• 3.5 RWDateTime
• 3.5.1 About Two or Four Digit Years
• 3.5.2 Member Functions
• 3.5.3 RWDateTime Sentinels
• 3.5.3.1 The "Invalid" Sentinel
• 3.5.3.2 The "Null" Sentinel
• 3.5.3.3 The Past and Future Sentinels
• 3.5.3.4 User-Defined Sentinels
• 3.6 RWDate (deprecated)
• 3.7 RWTime (deprecated)
• 3.8 Migrating to RWDateTime
• 3.9 The Date and Time Collectable Class

Chapter 4: String Processing Classes

• 4.1 Introduction
• 4.2 RWCString and RWWString
• 4.3 An Introductory Example
• 4.4 Lexicographic Comparisons
• 4.5 Substrings
• 4.6 Pattern Matching
• 4.6.1 Regular Expressions
• 4.6.1.1 The RWTRegex<T> Interface
• 4.6.1.2 Using Regular Expressions Efficiently
• 4.6.1.3 Introductory Examples Using Regular Expressions
• 4.7 String I/O
• 4.7.1 Iostreams
• 4.7.2 Virtual Streams
• 4.8 Tokenizer
• 4.9 Multibyte Strings
• 4.10 Wide Character Strings

Chapter 5: Virtual Stream Classes

• 5.1 Introduction
• 5.2 RWvios, RWvistream, and RWvostream
• 5.3 Specializing Virtual Streams
• 5.4 Simple Example
• 5.5 Recap

Chapter 6: Collection Classes

• 6.1 Introduction
• 6.2 Collection Class Groups
• 6.2.1 Traditional Collection Classes
• 6.2.2 STL-based Collection Classes
• 6.2.3 STL Extension-based Collection Classes
• 6.2.4 RWCollectable Classes
• 6.3 Storage Methods of Collection Classes
• 6.3.1 Value-based and Reference-based Collections
• 6.3.2 Examples of Value-based and Reference-based Collections
• 6.3.3 A Note on Memory Management
• 6.4 Copying Collection Classes
• 6.4.1 Copying Reference-based Collection Classes
• 6.4.2 Copying Value-based Collection Classes
• 6.5 Retrieving Objects in Collections
• 6.5.1 Retrieval Methods
• 6.6 Iterators in Collection Classes
• 6.6.1 Traditional Essential Tools Module Iterators
• 6.7 Collection Class Templates
• 6.8 Template Overview
• 6.8.1 Template Naming Convention
• 6.8.2 Value vs. Reference Semantics in Templates
• 6.8.2.1 An Important Distinction
• 6.8.3 Intrusive Lists in Templates
• 6.9 Essential Tools Module Templates and C++ Standard Library Containers
• 6.9.1 The C++ Standard Library Containers
• 6.9.2 Commonality of Interface
• 6.10 Parameter Requirements
• 6.11 Function Objects for Comparison
• 6.11.1 More on Total Ordering
• 6.12 Function Objects for Hashing and Equality
• 6.13 Iterators in Class Templates
• 6.13.1 C++ Standard Library Iterators
• 6.13.2 Map-Based Iteration and Pairs
• 6.13.3 Iterators as Generalized Pointers
• 6.14 Iterators and the std() Gateway
• 6.15 Example Using the Essential Tools Module with the C++ Standard Library
• 6.16 Designing an RWCollectable Class
• 6.16.1 Bus Example Scenario
• 6.16.1.1 Serialization Support Macros
• 6.16.1.2 Exporting Symbols in a Windows Environment
• 6.16.2 The Role of RWCollectable
• 6.16.3 Bus Example Code
• 6.17 Creating an RWCollectable Object
• 6.17.1 Define a Default Constructor
• 6.17.2 Add RW_DECLARE_COLLECTABLE_CLASS() to your Class Declaration
• 6.17.3 Provide a Class Identifier for Your Class
• 6.17.3.1 Virtual Function isA()
• 6.17.3.2 Virtual Function newSpecies()
• 6.17.3.3 Function stringID()
• 6.17.4 Add Definitions for Virtual Functions
• 6.17.4.1 Virtual Function compareTo()
• 6.17.4.2 Virtual Function isEqual()
• 6.17.4.3 Virtual Function hash()
• 6.17.4.4 An Example of compareTo(), isEqual(), and hash()
• 6.17.5 Object Destruction
• 6.17.6 How to Add Polymorphic Persistence
• 6.17.6.1 Virtual Functions saveGuts(RWFile&) and saveGuts(RWvostream&)
• 6.17.6.2 Virtual Functions restoreGuts(RWFile&) and restoreGuts(RWvistream&)
• 6.17.6.3 Multiply-referenced Objects
• 6.17.6.4 Virtual Function binaryStoreSize()
• 6.17.6.5 Polymorphically Persisting Custom Collections
• 6.17.7 A Note on the RWFactory
• 6.18 Complete Listing for Class Bus
• 6.19 Smalltalk-like Collection Classes
• 6.19.1 Tables of the Smalltalk-like Classes
• 6.19.2 Example
• 6.19.3 Choosing a Smalltalk-like Collection Class
• 6.19.3.1 Bags Versus Sets Versus Hash Tables
• 6.19.3.2 Sequenceable Classes
• 6.19.3.3 Dictionaries
• 6.19.4 Virtual Functions Inherited From RWCollection
• 6.19.4.1 insert()
• 6.19.4.2 find() and Friends
• 6.19.4.3 remove() Functions
• 6.19.4.4 apply() Functions
• 6.19.4.5 Functions clear() and clearAndDestroy()
• 6.19.5 Other Functions Shared by All RWCollections
• 6.19.5.1 Class Conversions
• 6.19.5.2 Inserting and Removing Other Collections
• 6.19.5.3 Selection
• 6.19.6 Virtual Functions Inherited from RWSequenceable
• 6.19.7 A Note on How Objects are Found
• 6.19.7.1 Hashing

Chapter 7: Internationalization Classes

• 7.1 Introduction
• 7.2 Localizing Alphabets with RWCString and RWWString
• 7.3 Localizing Messages
• 7.4 Challenges of Localizing Currencies, Numbers, Dates, and Times
• 7.5 RWLocale and RWZone
• 7.5.1 RWLocaleSnapshot and RWAnsiLocale
• 7.5.2 Dates
• 7.5.3 Time
• 7.5.4 Numbers
• 7.5.5 Currency

Chapter 8: Persistence

• 8.1 Introduction
• 8.2 Levels of Persistence
• 8.2.1 A Note About Terminology
• 8.2.2 About the Examples in this Section
• 8.3 No Persistence
• 8.4 Simple Persistence
• 8.4.1 Two Examples of Simple Persistence
• 8.4.1.1 Example One: Simple Persisting Objects of Fundamental Type
• 8.4.1.2 Example Two: Simple Persistence and Pointers
• 8.5 Isomorphic Persistence
• 8.5.1 Isomorphic versus Simple Persistence
• 8.5.2 Isomorphic Persistence of an Essential Tools Module Class
• 8.5.3 Designing Your Class to Use Isomorphic Persistence
• 8.5.3.1 Make All Necessary Class Data Available
• 8.5.3.2 Add RW_DECLARE_PERSISTABLE to Your Header File
• 8.5.3.3 Add RW_DEFINE_PERSISTABLE to One Source File
• 8.5.3.4 Check for Possible Problems
• 8.5.3.5 Define rwSaveGuts and rwRestoreGuts
• 8.5.4 Writing rwSaveGuts and rwRestoreGuts Functions
• 8.5.4.1 Guidelines for Writing rwSaveGuts
• 8.5.4.2 Guidelines for Writing rwRestoreGuts
• 8.5.5 Isomorphic Persistence of a User-designed Class
• 8.6 Polymorphic Persistence
• 8.6.1 Operators
• 8.6.2 Designing your Class to Use Polymorphic Persistence
• 8.6.3 Polymorphic Persistence Example
• 8.6.3.1 Example One: Saving Polymorphically
• 8.6.3.2 Example Two: Restoring Polymorphically
• 8.6.3.3 Example Two Revisited
• 8.6.3.4 Choosing Which Persistence Operator to Use
• 8.7 A Few Friendly Warnings
• 8.7.1 Always Save an Object by Value Before Saving the Identical Object by Pointer
• 8.7.2 Don't Save Distinct Objects with the Same Address
• 8.7.3 Don't Use Sorted RWCollections to Store Heterogeneous RWCollectables
• 8.7.4 Define All RWCollectables That Will Be Restored

Chapter 9: Error Handling and Reporting

• 9.1 Introduction
• 9.2 Error Categories
• 9.2.1 The Essential Tools Module Error Model
• 9.2.2 Internal Errors
• 9.2.2.1 Non-recoverable Internal Errors
• 9.2.2.2 Recoverable Internal Errors
• 9.2.3 External Errors
• 9.3 Error Reporting and Error Handling
• 9.3.1 Essential Tools Module Exception Architecture
• 9.3.1.1 RWxmsg
• 9.3.1.2 RWExternalErr
• 9.3.1.3 RWStreamErr
• 9.3.1.4 RWFileErr
• 9.3.1.5 RWxalloc
• 9.3.1.6 RWInternalErr
• 9.3.1.7 RWRegexErr
• 9.3.1.8 RWBoundsErr
• 9.3.2 Using the Error Reporting Classes to Handle Errors
• 9.3.2.1 When Exceptions are Supported
• 9.3.2.2 When Exceptions are Not Supported
• 9.4 The Debug Version of the Essential Tools Module
• 9.4.1 RW_PRECONDITION and RW_POSTCONDITION

Chapter 10: File System Classes

• 10.1 Introduction
• 10.2 RWFile
• 10.2.1 Example
• 10.3 RWFileStat
• 10.3.1 Construction
• 10.3.2 Example
• 10.4 RWDirectoryIterator
• 10.4.1 Flat Iteration Example
• 10.4.2 Recursive Iteration Example
• 10.5 RWFileManager
• 10.5.1 Construction
• 10.5.2 Member Functions
• 10.5.3 Example
• 10.6 RWBTreeOnDisk
• 10.6.1 Construction
• 10.6.2 Example

Chapter 11: Advanced Topics

• 11.1 Introduction
• 11.2 Copy on Write
• 11.2.1 A More Comprehensive Example
• 11.3 RWStringID
• 11.3.1 Duration of Identifiers
• 11.3.2 Programming with RWStringIDs
• 11.3.3 Implementation Details of RWStringID
• 11.3.3.1 Automatic RWClassIDs
• 11.3.3.2 Implementing Virtuals Via Statics
• 11.3.3.3 Polymorphic Persistence
• 11.3.3.4 Efficiency
• 11.3.3.5 Identification Collisions
• 11.4 More on Storing and Retrieving RWCollectables
• 11.5 Multiple Inheritance
• 11.6 Using Custom Allocators
• 11.6.1 Template Functions
• 11.6.2 Example

Chapter 12: Common Mistakes

• 12.1 Introduction
• 12.2 Redefinition of Virtual Functions
• 12.3 Iterators
• 12.4 Return Type of operator>>()
• 12.5 Avoid Persisting Value Collections of Pointers
• 12.6 Include Path
• 12.7 Match Memory Models and Other Qualifiers
• 12.8 Keep Related Methods Consistent
• 12.9 DLL
• 12.10 Use the Capabilities of the Module!

Appendix A: Choosing a Collection

• A.1 Introduction
• A.2 Selecting an Essential Tools Module Collection Class
• A.2.1 How to Use the Decision Tree
• A.2.2 Additional Selection Criteria
• A.3 Time and Space Considerations
• A.3.1 RWGVector, RWGBitVec, RWTBitVec<Size>, RWTPtrVector, and RWTValVector<T>
• A.3.2 Singly Linked Lists
• A.3.3 Doubly Linked Lists
• A.3.4 Ordered Vectors
• A.3.5 Sorted Vectors
• A.3.6 Stacks and Queues
• A.3.7 Deques
• A.3.8 Binary Tree
• A.3.9 (multi)map and (multi)set family
• A.3.10 RWBTree, RWBTreeDictionary
• A.3.11 Hash-based Collections

Appendix B: Constants, Typedefs, Pointers, Enumerations, and Macros

• B.1 Constants
• B.2 Typedefs
• B.3 Pointers to Functions
• B.4 Enumerations
• B.5 Public Macros
• B.5.1 In File collect.h
• B.5.2 In File defs.h
• B.5.3 In File edefs.h
• B.5.4 In File epersist.h
• B.5.5 In File strmshft.h
• B.5.6 In Files tphasht.h, tvhasht.h, tphdict.h, tvhdict.h, tphmmap.h, tvhmmap.h, tphset.h, tvhset.h
• B.5.7 In Files tpsrtvec.h, tvsrtvec.h
• B.6 Standard Smalltalk Interface Typedefs

Appendix C: Bibliography

• C.1 References

Topic Index

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.