Detailed
Contents

Tables/Figures/Examples

1: Product Overview
   1.1 Definition
   1.2 Features and Benefits
   1.3 Documentation
      1.3.1 Documentation Set Overview
      1.3.2 Online Documentation
      1.3.3 Printed Manuals
   1.4 This Manual
      1.4.1 Assumptions
      1.4.2 Organization
      1.4.3 Conventions
   1.5 Consulting Services and Training
   1.6 Technical Support
      1.6.1 To Obtain Technical Support
      1.6.2 How to Contact Technical Support
   1.7 Product Information
2: Class Overview
   2.1 Introduction
   2.2 Class Groups
      2.2.1 Date and Time Classes
      2.2.2 String Processing Classes
      2.2.3 Virtual Stream Classes
      2.2.4 Collection Classes
      2.2.5 Internationalization Classes
      2.2.6 File System Classes
      2.2.7 Miscellaneous Classes
      2.2.8 Generic Classes (deprecated)
   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.1.3 Generic 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
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 Member Functions
      3.5.2 RWDateTime Sentinels
         3.5.2.1 The "Invalid" Sentinel
         3.5.2.2 The "Null" Sentinel
         3.5.2.3 The Past and Future Sentinels
         3.5.2.4 User-Defined Sentinels
   3.6 RWDate
   3.7 RWTime
   3.8 Migrating to RWDateTime
   3.9 The Date and Time Collectable Classes
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
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
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 Standard C++ Library Containers
      6.9.1 The Standard C++ 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 Standard C++ 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 Standard C++ Library
   6.16 Designing an RWCollectable Class
      6.16.1 Bus Example Scenario
      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 RWDECLARE_COLLECTABLE() 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
7: Generic Classes (deprecated)
   7.1 Introduction
   7.2 Generic Collection Classes
   7.3 Example
   7.4 Declaring Generic Collection Classes
   7.5 User-Defined Functions
      7.5.1 Tester Functions
      7.5.2 Apply Functions
8: Internationalization Classes
   8.1 Introduction
   8.2 Localizing Alphabets with RWCString and RWWString
   8.3 Localizing Messages
   8.4 Challenges of Localizing Currencies, Numbers, Dates, and Times
   8.5 RWLocale and RWZone
      8.5.1 RWLocaleSnapshot and RWAnsiLocale
      8.5.2 Dates
      8.5.3 Time
      8.5.4 Numbers
      8.5.5 Currency
9: Persistence
   9.1 Introduction
   9.2 Levels of Persistence
      9.2.1 A Note About Terminology
      9.2.2 About the Examples in this Section
   9.3 No Persistence
   9.4 Simple Persistence
      9.4.1 Two Examples of Simple Persistence
         9.4.1.1 Example One: Simple Persisting Objects of Fundamental Type
         9.4.1.2 Example Two: Simple Persistence and Pointers
   9.5 Isomorphic Persistence
      9.5.1 Isomorphic versus Simple Persistence
      9.5.2 Isomorphic Persistence of an Essential Tools Module Class
      9.5.3 Designing Your Class to Use Isomorphic Persistence
         9.5.3.1 Make All Necessary Class Data Available
         9.5.3.2 Add RWDECLARE_PERSISTABLE to Your Header File
         9.5.3.3 Add RWDEFINE_PERSISTABLE to One Source File
         9.5.3.4 Check for Possible Problems
         9.5.3.5 Define rwSaveGuts and rwRestoreGuts
      9.5.4 Writing rwSaveGuts and rwRestoreGuts Functions
         9.5.4.1 Guidelines for Writing rwSaveGuts
         9.5.4.2 Guidelines for Writing rwRestoreGuts
      9.5.5 Isomorphic Persistence of a User-designed Class
   9.6 Polymorphic Persistence
      9.6.1 Operators
      9.6.2 Designing your Class to Use Polymorphic Persistence
      9.6.3 Polymorphic Persistence Example
         9.6.3.1 Example One: Saving Polymorphically
         9.6.3.2 Example Two: Restoring Polymorphically
         9.6.3.3 Example Two Revisited
         9.6.3.4 Choosing Which Persistence Operator to Use
   9.7 A Few Friendly Warnings
      9.7.1 Always Save an Object by Value Before Saving the Identical Object by Pointer
      9.7.2 Don't Save Distinct Objects with the Same Address
      9.7.3 Don't Use Sorted RWCollections to Store Heterogeneous RWCollectables
      9.7.4 Define All RWCollectables That Will Be Restored
10: Error Handling and Reporting
   10.1 Introduction
   10.2 Error Categories
      10.2.1 The Essential Tools Module Error Model
      10.2.2 Internal Errors
         10.2.2.1 Non-recoverable Internal Errors
         10.2.2.2 Recoverable Internal Errors
      10.2.3 External Errors
   10.3 Error Reporting and Error Handling
      10.3.1 Essential Tools Module Exception Architecture
         10.3.1.1 RWxmsg
         10.3.1.2 RWExternalErr
         10.3.1.3 RWStreamErr
         10.3.1.4 RWFileErr
         10.3.1.5 RWxalloc
         10.3.1.6 RWInternalErr
         10.3.1.7 RWRegexErr
         10.3.1.8 RWBoundsErr
      10.3.2 Using the Error Reporting Classes to Handle Errors
         10.3.2.1 When Exceptions are Supported
         10.3.2.2 When Exceptions are Not Supported
   10.4 The Debug Version of the Essential Tools Module
      10.4.1 RWPRECONDITION and RWPOSTCONDITION
11: File System Classes
   11.1 Introduction
   11.2 RWFile
      11.2.1 Construction
      11.2.2 Example
   11.3 RWFileManager
      11.3.1 Construction
      11.3.2 Member Functions
      11.3.3 Example
   11.4 RWBTreeOnDisk
      11.4.1 Construction
      11.4.2 Example
12: Advanced Topics
   12.1 Introduction
   12.2 Copy on Write
      12.2.1 A More Comprehensive Example
   12.3 RWStringID
      12.3.1 Duration of Identifiers
      12.3.2 Programming with RWStringIDs
      12.3.3 Implementation Details of RWStringID
         12.3.3.1 Automatic RWClassIDs
         12.3.3.2 Implementing Virtuals Via Statics
         12.3.3.3 Polymorphic Persistence
         12.3.3.4 Efficiency
         12.3.3.5 Identification Collisions
   12.4 More on Storing and Retrieving RWCollectables
   12.5 Multiple Inheritance
   12.6 Using Custom Allocators
      12.6.1 Template Functions
      12.6.2 Example
13: Common Mistakes
   13.1 Introduction
   13.2 Redefinition of Virtual Functions
   13.3 Iterators
   13.4 Return Type of operator>>()
   13.5 Avoid Persisting Value Collections of Pointers
   13.6 Include Path
   13.7 Match Memory Models and Other Qualifiers
   13.8 Keep Related Methods Consistent
   13.9 DLL
   13.10 Use the Capabilities of the Module!
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
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
C: Messages
   C.1 Core Messages
   C.2 Essential Tools Module Messages
D: Change Log
   D.1 From SourcePro Core 9.0 to 9.1
   D.2 From SourcePro Core 8.5 to 9.0
      D.2.1 General Changes
      D.2.2 Specific Changes
         D.2.2.1 Enhanced and new Regular Expression Capabilities
         D.2.2.2 RWBasicUString
         D.2.2.3 Support for ISO 8601 in RWDateTime
         D.2.2.4 Const Iterators
         D.2.2.5 Custom Allocators
         D.2.2.6 Expanded Error Reporting Discussion
         D.2.2.7 Deprecated Classes
   D.3 From SourcePro Core 8.0 to 8.5
   D.4 From Tools.h++ 7.1.1 to the Essential Tools Module of SourcePro Core 8.0
      D.4.1 General Changes
      D.4.2 Specific Changes
         D.4.2.1 RWDateTime
         D.4.2.2 RWCString
         D.4.2.3 RWClockTimer
         D.4.2.4 RWDecimalPortable
         D.4.2.5 Primitive Types
         D.4.2.6 Generic Classes
E: Bibliography

Topic Index