TEXAS INSTRUMENTS
`
`C++ Object-Oriented Library
`User’s Manual
`
`
`
`
`
`Page 1 of 252
`
`FORD 1114
`
`

`
`MANUAL REVISION HISTORY
`
`C++ Object-Oriented Library User’s Manual (2566801-0001)
`
`Original Issue
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`March 1990
`
`Copyright © 1990, 1991 Texas Instruments Incorporated
`
`Permission is granted to any individual or institution to use, copy, modify, and
`distribute this document, provided that this complete copyright and permission
`notice is maintained, intact, in all copies and supporting documentation.
`
`Texas Instruments Incorporated makes no representations about the suitability of
`this document or the software described herein for any purpose. It is provided
`”as is” without express or implied warranty.
`
`Texas Instruments Incorporated
`Information Technology Group
`Austin, Texas
`
`Page 2 of 252
`
`FORD 1114
`
`

`
`C++ OBJECT-ORIENTED LIBRARY
`USER’S MANUAL
`
`Page 3 of 252
`
`FORD 1114
`
`

`
`Page 4 of 252
`
`FORD 1114
`
`Page 4 of 252
`
`FORD 1114
`
`

`
`Paragraph Title
`
`CONTENTS
`
`Page
`
`About This Manual
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`xi
`
`Overview of COOL
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`1.1
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`1.2 Audience
`
`1.3 Major Attributes
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`1.4 Macros
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`1.5
`Parameterized Templates
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`1.6
`Symbols and Packages
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`1.7
`Polymorphic Management
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`1.8 Exception Handling
`
`1.9 Classes
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`1.10 Class Hierarchy
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`1-1
`1-1
`1-1
`1-2
`1-2
`1-3
`1-3
`1-4
`1-4
`1-7
`
`1
`
`2
`
`3
`
`String Classes
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`2.1
`
`2.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`2.3
`String Class
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`2.4
`String Example
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`2.5 Auxiliary char* Functions
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`2.6 Regular Expression Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`2.7 Regular Expression Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`2.8 General String Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`2.9 General String Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Number Classes
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`3.1
`
`3.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.3 Random Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.4 Random Class Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.5 Complex Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.6 Complex Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.7 Rational Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.8 Rational Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.9 Bignum Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.10 Bignum Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.11 Range Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`3.12 Range Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`2-1
`2-1
`2-1
`2-7
`2-8
`2-10
`2-12
`2-13
`2-20
`
`3-1
`3-1
`3-1
`3-3
`3-4
`3-7
`3-9
`3-13
`3-14
`3-19
`3-20
`3-21
`
`v
`
`COOL User’s Manual
`
`
`
`
`
`
`
`Page 5 of 252
`
`FORD 1114
`
`

`
`Contents
`
`Paragraph Title
`
`4
`
`5
`
`6
`
`7
`
`vi
`
`System Interface Classes
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`4.1
`
`4.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.3 Date_Time Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.4 Time zone.h File
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.5 Country.h File
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.6 Calendar.h File
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.7 Date_Time Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.8 Timer Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`4.9 Timer Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Parameterized Templates
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`5.1
`
`5.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`5.3
`Parameterized Classes
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`5.4 Templates
`
`5.5 DECLARE and IMPLEMENT Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5.6 Template Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5.7 COOL C++ Control Program
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5.8 CCC Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5.9 Container Classes
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5.10 Container Example (Current Position)
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`5.11
`Iterator Class
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`5.12
`Iterator Example
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`5.13 Making Your Own Container Classes
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`5.14
`Storing Objects in Container Classes
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Ordered Sequence Classes
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`6.1
`
`6.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`6.3 Vector Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`6.4 Vector Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`6.5
`Stack Class
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`6.6
`Stack Example
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`6.7 Queue Class
`
`6.8 Queue Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`6.9 Matrix Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`6.10 Matrix Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Unordered Sequence Classes
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`7.1
`
`7.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`7.3 List Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`7.4 List Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`7.5
`Pair Class
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`7.6 Association Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Page
`
`4-1
`4-1
`4-1
`4-6
`4-7
`4-7
`4-8
`4-9
`4-10
`
`5-1
`5-1
`5-2
`5-2
`5-5
`5-5
`5-7
`5-9
`5-10
`5-11
`5-12
`5-13
`5-13
`5-14
`
`6-1
`6-1
`6-2
`6-8
`6-9
`6-12
`6-13
`6-16
`6-16
`6-19
`
`7-1
`7-1
`7-2
`7-8
`7-10
`7-11
`
`
`
`
`
`
`
`COOL User’s Manual
`
`Page 6 of 252
`
`FORD 1114
`
`

`
`Paragraph Title
`
`Contents
`
`Page
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`7.7 Association Example
`
`
`7.8 Hash_Table Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`7.9 Hash_Table Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`7-14
`7-16
`7-19
`
`Set Classes
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`8.1
`8.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`8.3
`Set Class
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`8.4
`Set Class Example
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`8.5 Bit_Set Class
`
`8.6 Bit_Set Class Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`8-1
`8-1
`8-2
`8-5
`8-6
`8-11
`
`Node and Tree Classes
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`9.1
`
`9.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9.3 Binary_Node Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9.4 Binary_Tree Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9.5 Binary_Tree Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9.6 AVL_Tree Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9.7 AVL_Tree Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9.8 N_Node Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9.9 D_Node Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9.10 N_Tree Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9.11 N_Tree Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`9-1
`9-1
`9-2
`9-3
`9-5
`9-6
`9-9
`9-10
`9-12
`9-14
`9-17
`
`Macros
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Introduction
`10.1
`
`10.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`10.3 COOL Preprocessor
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`10.4
`defmacro
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`10.5 MACRO
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`10.6 MACRO Examples
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`10.7
`ISSAME
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`10.8 KEYARGS
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`10.9 ONCE_ONLY
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`10.10 EXPAND_ARGS
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`10.11
`INITIALIZE
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`10.12
`IGNORE MACRO
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`10-1
`10-1
`10-1
`10-3
`10-4
`10-5
`10-7
`10-8
`10-9
`10-9
`10-10
`10-11
`
`Symbols and Packages
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`11.1
`
`11.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`11.3
`Symbol and Package Classes
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`11.4
`Symbol Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`11.5
`Package Class
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`11.6 DEFPACKAGE
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`11-1
`11-1
`11-2
`11-2
`11-3
`11-6
`
`8
`
`9
`
`10
`
`11
`
`COOL User’s Manual
`
`
`
`
`
`
`
`vii
`
`Page 7 of 252
`
`FORD 1114
`
`

`
`Contents
`
`12
`
`13
`
`14
`
`viii
`
`Paragraph Title
`
`Page
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`11.7 Adding Symbols To A Package
`
`
`11.8 Enumeration Package
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`11.9 Enumeration Package Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`11.10 Text Package
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`11.11 Text Package Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`11.12
`Symbol Package
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`11.13
`Symbol Package Example
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`11.14 ONCE_ONLY Package
`11.15
`Interfacing to the SYM Package
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`11.16
`Symbol Package Implementation
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`11-8
`11-10
`11-10
`11-11
`11-12
`11-16
`11-17
`11-19
`11-20
`11-20
`
`Polymorphic Management
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`12.1
`
`12.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`12.3 Generic Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`12.4 Runtime Type Checking Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`12.5 TYPE_CASE Macro
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`12.6 Heterogenous Container Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`12.7 Class Macro
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`12.8 Class Macro Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`12-1
`12-1
`12-2
`12-4
`12-5
`12-5
`12-7
`12-9
`
`Exception Handling
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`13.1
`
`13.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`13.3 Exceptions
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`13.4 Exception Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`13.5 Excp_Handler Class
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`13.6 Excp_Handler Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`13.7
`Predefined Exception Types And Handlers
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`13.8 EXCEPTION
`
`13.9 EXCEPTION Examples
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`13.10 RAISE
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`13.11 RAISE Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`13.12
`STOP
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`13.13
`STOP Example
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`13.14 VERIFY
`
`13.15 VERIFY Example
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`13.16
`Jump_Handler Class
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`13.17
`IGNORE_ERRORS
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`13.18
`IGNORE_ERRORS Example
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`13.19 Exceptions as Symbols and Package
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`13.20 User-Defined Exception Types
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`13-1
`13-1
`13-1
`13-2
`13-5
`13-6
`13-7
`13-8
`13-9
`13-11
`13-12
`13-13
`13-14
`13-14
`13-15
`13-16
`13-17
`13-18
`13-18
`13-19
`
`COOL Methodology
`
`Introduction
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.1
`
`14.2 Requirements
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.3
`Preprocessor and Macros
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.4
`Parameterized Templates
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`14-1
`14-1
`14-1
`14-2
`
`
`
`
`
`
`
`COOL User’s Manual
`
`Page 8 of 252
`
`FORD 1114
`
`

`
`Paragraph Title
`
`Contents
`
`Page
`
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Symbols and Packages
`14.5
`
`Polymorphic Management
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.6
`
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.7 Exceptions
`
`14.8 Coding Style and Conventions
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.8.1
`Naming Conventions
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.8.2
`Class Header File Organization
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.8.3
`Private, Protected, and Public Data
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.8.4
`Documentation
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.8.5
`Source Code Indentation
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.8.6
`Error Message Resource Package
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.8.7
`Regression Test Suite
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.8.8
`Source Code System Independence
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.8.9
`Build Procedure
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`14.9 Class Hierarchy
`. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`14-4
`14-4
`14-6
`14-7
`14-8
`14-9
`14-10
`14-10
`14-10
`14-10
`14-11
`14-11
`14-11
`14-11
`
`Glossary
`Index
`
`COOL User’s Manual
`
`
`
`
`
`
`
`ix
`
`Page 9 of 252
`
`FORD 1114
`
`

`
`Contents
`
`x
`
`
`
`
`
`
`
`COOL User’s Manual
`
`Page 10 of 252
`
`FORD 1114
`
`

`
`ABOUT THIS MANUAL
`
`Introduction
`
`This manual contains supporting software documentation for COOL (the C++ Object-
`Oriented Library), a collection of classes, objects, templates, and macros that extend the
`capabilities of the C++ language. This manual is written for high level C++ application
`programmers using COOL.
`
`Organization
`
`This manual is divided into the following sections and appendixes:
`
`•
`
`•
`
`•
`
`•
`
`•
`
`•
`
`•
`
`•
`
`•
`
`•
`
`•
`
`Section 1: Overview of COOL — Contains an introduction to the COOL User’s
`Manual and what to expect on the various classes, macros and other enhancements
`to C++ that are discussed in this manual.
`
`Section 2: String Classes — Describes a collection of classes that implement tex-
`tual operations and functions.
`
`Section 3: Number Classes — Contains information on a collection of numeri-
`cally oriented classes that augment the built-in numerical data types to provide ex-
`tended precision, range-checked types, and complex numbers.
`
`Section 4: System Interface Classes — Includes classes for calculating the date
`and time in different time zones and countries.
`
`Section 5: Parameterized Templates — Describes classes that allow a program-
`mer to design and implement a class template without specifying the data type.
`
`Section 6: Ordered Sequence Classes — Describes classes that are a collection of
`basic data structures that implement sequential-access data structures as
`parameterized classes.
`
`Section 7: Unordered Sequence Classes — Describes classes that are a collection
`of basic data structures that implement random-access data structures as
`parameterized classes.
`
`Section 8: Set Classes — Describes classes that implement two basic data struc-
`tures for random-access set operations.
`
`Section 9: Node and Tree Classes — Describes classes that are a collection of
`basic data structures that implement several standard tree data structures as
`parameterized classes.
`
`Section 10: Macros — Describes COOL macro facilities that are an extension to
`the standard ANSI C macro preprocessor functions and that support constant sym-
`bols, keyword and body arguments, parameterized templates and complex expres-
`sion evaluation.
`
`Section 11: Symbols and Packages — Describes functions that manage error
`message textual descriptions, provide polymorphic extensions to C++ for object
`type and contents queries, and support sophisticated symbolic computing.
`
`COOL User’s Manual
`
`
`
`
`
`
`
`xi
`
`Page 11 of 252
`
`FORD 1114
`
`

`
`About This Manual
`
`•
`
`•
`
`•
`
`Section 12: Polymorphic Management — Describes the mode of managing sym-
`bolic constants and run-time symbolic objects and packages. Also discusses the
`Generic class, which is inherited by most COOL classes and manipulates lists of
`symbols to manage type information.
`
`Section 13: Exception Handling — Describes COOL exception handling, which
`is a raise, handle, and proceed mechanism that uses the COOL symbolic computing
`capability.
`
`Section 14: COOL Methodology — Describes COOL methodology for manag-
`ers and programmers who need a brief overview of COOL components, organiza-
`tion, style guide, and rules for extending the library.
`
`Conventions
`
`Certain conventions and syntax are used to simplify presentation of the material in this
`manual. The following typographical conventions are used:
`
`•
`
`•
`
`•
`
`Bold type — Words in bold represent either a class name, macro name, or system-
`supplied function.
`
`Italics — Words in italics enclosed by angle brackets or parenthesis represent argu-
`ments that must be specified by the programmer .
`
`Monowidth Font — Program examples and output are distinguished by monowidth
`font of a smaller size than the normal manual text. (e.g., #include <COOL/
`String.h>)
`
`Program examples illustrated and defined within this manual are supplied and can be
`found in the ~COOL/examples subdirectory. Examples are given specific file names by
`appending a suffix of .C to its associated paragraph number. For example, the string
`class example in paragraph 2.4 is located in the 2.4.C filename.
`
`Each section includes a requirements paragraph that states the prerequisites needed to
`understand and use the components or functions being discussed.
`
`Certain paragraphs document reference information about COOL classes. A special
`format is used that provides the following information:
`
`Class Name
`
`Synopsis
`
`Base Classes
`
`Friend Classes
`
`•
`•
`•
`•
`•
`Constructors
`• Member Functions
`•
`•
`
`Friend Functions
`
`Example Program
`
`xii
`
`
`
`
`
`
`
`COOL User’s Manual
`
`Page 12 of 252
`
`FORD 1114
`
`

`
`Introduction
`
`Audience
`
`Features
`
`OVERVIEW OF
` COOL
`
`1.1
`The C++ Object-Oriented Library (COOL) is a collection of classes, objects,
`templates, and macros to extend the capabilities of the C++ language for developing
`complex problem-solving applications. Significant language features in COOL, such as
`parameterized types, symbolic computing, and exception handling, are implemented
`with sophisticated C++ macro facilities. These features and facilities are designed to
`enhance and improve a programmer’s development capability.
`
`COOL is intended to simplify the programming task by allowing the programmer to
`concentrate on the application problem to be solved, not on implementing base data
`structures, macros, and classes. In addition, COOL provides a system-independent soft-
`ware platform on which applications are built. An application built on top of COOL will
`compile and run on any platform supporting COOL.
`
`1.2
`This manual is intended for use by programmers who have a working under-
`standing of the C++ programming language as implemented by AT&T in release 2.0
`and type system. Users must also understand the distinction between the concepts and
`principles associated with overloaded operators and friend functions.
`
`1.3
`The major features that COOL contributes to enhancing the C++ language and
`program development capabilities are the following:
`
`• An enhanced macro language that supports constant symbols, keyword and body
`arguments, parameterized templates, and complex expression evaluation
`
`•
`
`Parameterized templates that allow development of type-independent container
`classes with support for multiple iterators
`
`• Dynamic, user-defined packages implementing name spaces for symbols with
`names, property lists, and values
`
`•
`
`Polymorphic features derived from the Generic virtual base class that supports
`is_type_of() run-time queries
`
`• A multi-level exception handling mechanism that utilizes macros, symbols, and a
`global error package and is similar in design to the Common Lisp Condition Han-
`dling System
`
`• A collection of classes implementing a wide range of useful data structures and
`system interface facilities
`
`The following paragraphs provide brief descriptions of each of these features, including
`information on what to expect in the rest of this manual on the various classes, macros,
`symbolic computing facilities, exception handling routines, and methodology that gov-
`erns the implementation of COOL.
`
`COOL User’s Manual
`
`
`
`
`
`
`
`1-1
`
`Page 13 of 252
`
`FORD 1114
`
`

`
`Overview Of COOL
`
`Macros
`
`Parameterized
`Templates
`
`1.4
`Supplied as part of the library, the COOL macro facilities are an extension to the
`standard ANSI C macro preprocessor functions and are portable and compiler-inde-
`pendent. The COOL macro facilities support constant symbols, keyword and body ar-
`guments, parameterized templates, and complex expression evaluation. Some macros,
`such as those that support the parameterized types, are implementations of theoretical
`design papers published by Bjarne Stroustrup.
`
`The COOL preprocessor is derived from and based upon the DECUS ANSI C
`preprocessor made available by the DEC User’s group in the public domain and sup-
`plied on the X11R3 source tape from MIT. The preprocessor complies with the draft
`ANSI C specification with the exception that trigraph sequences are not implemented.
`
`The preprocessor was modified to recognize a #pragma defmacro statement to allow a
`programmer to define powerful extensions to the C++ language. The proposed draft
`ANSI C standard indicates that extensions and changes to the language and features
`implemented in a preprocessor and compiler should be made by using the #pragma
`statement. The COOL preprocessor follows this recommendation and uses this as the
`means by which all macro extensions are made. The #pragma defmacro statement is
`the single hook through which features such as the class macro, parameterized tem-
`plates, and polymorphic enhancements are implemented. This statement also allows ar-
`bitrary filter programs and macro expanders to be run on C++ code fragments passing
`through the preprocessor. Note, however, that once a macro is expanded, the resulting
`code is conventional C++ 2.0 syntax acceptable to any conforming C++ translator or
`compiler.
`
`1.5 Parameterized classes allow a programmer to design and implement a
`class template without specifying the data type. The user can then customize the class by
`specifying the type when it is used in a program. Parameterized classes can be thought
`of as metaclasses in that only one source base needs to be maintained to support numer-
`ous variations of a type of class.
`
`An important and useful type of parameterized class is known as a container class. A
`container class is a special type of parameterized class where you put objects of a par-
`ticular type. A container class that is parameterized over an object does not require the
`user to manage memory, activate destructors, and so forth. COOL supplies several com-
`mon container class data structures that include support for the notion of a built-in
`iterator that maintains a current position in the container object. Multiple iterators into
`an instance of a container class are provided by the Iterator<Type> class.
`
`Parameterized classes are handled by the COOL C++ Control program (CCC) which
`provides all functions of the original CC program and also supports the COOL
`preprocessor and COOL macro language. CCC controls and invokes the various com-
`ponents of the compilation process.
`
`Alternately, a declaration macro can be used to instantiate a type-independent
`parameterized class fo