Table of Contents
Table of Contents
Table of Contents
Create successful ePaper yourself
Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.
Open Watcom C++Class Library ReferenceVersion 1.8
Notice <strong>of</strong> CopyrightCopyright © 2002-2008 the Open Watcom Contributors. Portions Copyright © 1984-2002 Sybase, Inc.and its subsidiaries. All rights reserved.Any part <strong>of</strong> this publication may be reproduced, transmitted, or translated in any form or by any means,electronic, mechanical, manual, optical, or otherwise, without the prior written permission <strong>of</strong> anyone.For more information please visit http://www.openwatcom.org/ii
PrefaceOpen Watcom C++ is an implementation <strong>of</strong> the C++ programming language. In addition to the C++ draftstandard, the compiler supports numerous extensions for the PC environment.This manual describes the Open Watcom C++ Class Libraries for DOS, Windows 3.x, Windows NT,Windows 95, 16-bit OS/2 1.x, 32-bit OS/2, and QNX. It includes a String Class, a Complex Class,Container Classes, and an I/O Stream hierarchy <strong>of</strong> classes. The Container classes include a set <strong>of</strong> intrusive,value and pointer list classes with their associated iterators.This book was produced with the Open Watcom GML electronic publishing system, a s<strong>of</strong>tware tooldeveloped by WATCOM. In this system, writers use an ASCII text editor to create source files containingtext annotated with tags. These tags label the structural elements <strong>of</strong> the document, such as chapters,sections, paragraphs, and lists. The Open Watcom GML s<strong>of</strong>tware, which runs on a variety <strong>of</strong> operatingsystems, interprets the tags to format the text into a form such as you see here. Writers can produce outputfor a variety <strong>of</strong> printers, including laser printers, using separately specified layout directives for such thingsas font selection, column width and height, number <strong>of</strong> columns, etc. The result is type-set quality copycontaining integrated text and graphics.July, 1997.Trademarks Used in this ManualIBM is a registered trademark and OS/2 is a trademark <strong>of</strong> International Business Machines Corp.Micros<strong>of</strong>t is a registered trademark <strong>of</strong> Micros<strong>of</strong>t Corp. Windows, Windows NT and Windows 95 aretrademarks <strong>of</strong> Micros<strong>of</strong>t Corp.QNX is a registered trademark <strong>of</strong> QNX S<strong>of</strong>tware Systems Ltd.WATCOM is a trademark <strong>of</strong> Sybase, Inc. and its subsidiaries.iii
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>Open Watcom C++ Class Library Reference ................................................................................................. 11 Header Files ........................................................................................................................................... 32 Common Types ...................................................................................................................................... 73 Predefined Objects ................................................................................................................................. 93.1 cin .................................................................................................................................................. 93.2 cout ................................................................................................................................................ 93.3 cerr ................................................................................................................................................. 93.4 clog ................................................................................................................................................ 104 istream Input ........................................................................................................................................... 114.1 Formatted Input: Extractors ........................................................................................................... 114.2 Unformatted Input ......................................................................................................................... 115 ostream Output ....................................................................................................................................... 135.1 Formatted Output: Inserters ........................................................................................................... 135.2 Unformatted Output ....................................................................................................................... 136 Library Functions and Types .................................................................................................................. 157 Complex Class ........................................................................................................................................ 17Complex Class Description ................................................................................................................. 18Complex abs() ................................................................................................................................ 20Complex acos() .............................................................................................................................. 21Complex acosh() ............................................................................................................................ 22Complex arg() ................................................................................................................................ 23Complex asin() ............................................................................................................................... 24Complex asinh() ............................................................................................................................. 25Complex atan() .............................................................................................................................. 26Complex atanh() ............................................................................................................................ 27Complex() ...................................................................................................................................... 28Complex() ...................................................................................................................................... 29Complex() ...................................................................................................................................... 30~Complex() .................................................................................................................................... 31Complex conj() .............................................................................................................................. 32Complex cos() ................................................................................................................................ 33Complex cosh() .............................................................................................................................. 34Complex exp() ............................................................................................................................... 35imag() ............................................................................................................................................. 36Complex imag() ............................................................................................................................. 37Complex log() ................................................................................................................................ 38Complex log10() ............................................................................................................................ 39Complex norm() ............................................................................................................................. 40Complex operator !=() ................................................................................................................... 41Complex operator *() ..................................................................................................................... 42operator *=() .................................................................................................................................. 43operator +() .................................................................................................................................... 44Complex operator +() .................................................................................................................... 45operator +=() .................................................................................................................................. 46operator -() ..................................................................................................................................... 47v
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>Complex operator -() ..................................................................................................................... 48operator -=() ................................................................................................................................... 49Complex operator /() ...................................................................................................................... 50operator /=() ................................................................................................................................... 51Complex operator () .................................................................................................................. 55Complex polar() ............................................................................................................................. 56Complex pow() .............................................................................................................................. 57real() ............................................................................................................................................... 58Complex real() ............................................................................................................................... 59Complex sin() ................................................................................................................................ 60Complex sinh() .............................................................................................................................. 61Complex sqrt() ............................................................................................................................... 62Complex tan() ................................................................................................................................ 63Complex tanh() .............................................................................................................................. 648 Container Exception Classes .................................................................................................................. 65WCExcept Class Description .............................................................................................................. 66WCExcept() ................................................................................................................................... 67~WCExcept() ................................................................................................................................. 68exceptions() .................................................................................................................................... 69wc_state ......................................................................................................................................... 70WCIterExcept Class Description ......................................................................................................... 71WCIterExcept() .............................................................................................................................. 72~WCIterExcept() ........................................................................................................................... 73exceptions() .................................................................................................................................... 74wciter_state .................................................................................................................................... 759 Container Allocators and Deallocators .................................................................................................. 7710 Hash Containers ................................................................................................................................... 81WCPtrHashDict Class Description ................................................................................ 82WCPtrHashDict() .......................................................................................................................... 84WCPtrHashDict() .......................................................................................................................... 85WCPtrHashDict() .......................................................................................................................... 86~WCPtrHashDict() ........................................................................................................................ 87bitHash() ........................................................................................................................................ 88buckets() ........................................................................................................................................ 89clear() ............................................................................................................................................. 90clearAndDestroy() ......................................................................................................................... 91contains() ....................................................................................................................................... 92entries() .......................................................................................................................................... 93find() .............................................................................................................................................. 94findKeyAndValue() ....................................................................................................................... 95forAll() ........................................................................................................................................... 96insert() ............................................................................................................................................ 97isEmpty() ....................................................................................................................................... 98operator []() .................................................................................................................................... 99operator []() .................................................................................................................................... 100operator =() .................................................................................................................................... 101vi
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>operator ==() .................................................................................................................................. 102remove() ......................................................................................................................................... 103resize() ........................................................................................................................................... 104WCPtrHash<strong>Table</strong>, WCPtrHashSet Class Description ................................................ 105WCPtrHashSet() ............................................................................................................................ 107WCPtrHashSet() ............................................................................................................................ 108WCPtrHashSet() ............................................................................................................................ 109~WCPtrHashSet() .......................................................................................................................... 110WCPtrHash<strong>Table</strong>() ........................................................................................................................ 111WCPtrHash<strong>Table</strong>() ........................................................................................................................ 112WCPtrHash<strong>Table</strong>() ........................................................................................................................ 113~WCPtrHash<strong>Table</strong>() ...................................................................................................................... 114bitHash() ........................................................................................................................................ 115buckets() ........................................................................................................................................ 116clear() ............................................................................................................................................. 117clearAndDestroy() ......................................................................................................................... 118contains() ....................................................................................................................................... 119entries() .......................................................................................................................................... 120find() .............................................................................................................................................. 121forAll() ........................................................................................................................................... 122insert() ............................................................................................................................................ 123isEmpty() ....................................................................................................................................... 124occurencesOf() ............................................................................................................................... 125operator =() .................................................................................................................................... 126operator ==() .................................................................................................................................. 127remove() ......................................................................................................................................... 128removeAll() .................................................................................................................................... 129resize() ........................................................................................................................................... 130WCValHashDict Class Description ............................................................................... 131WCValHashDict() ......................................................................................................................... 133WCValHashDict() ......................................................................................................................... 134WCValHashDict() ......................................................................................................................... 135~WCValHashDict() ....................................................................................................................... 136bitHash() ........................................................................................................................................ 137buckets() ........................................................................................................................................ 138clear() ............................................................................................................................................. 139contains() ....................................................................................................................................... 140entries() .......................................................................................................................................... 141find() .............................................................................................................................................. 142findKeyAndValue() ....................................................................................................................... 143forAll() ........................................................................................................................................... 144insert() ............................................................................................................................................ 145isEmpty() ....................................................................................................................................... 146operator []() .................................................................................................................................... 147operator []() .................................................................................................................................... 148operator =() .................................................................................................................................... 149operator ==() .................................................................................................................................. 150remove() ......................................................................................................................................... 151resize() ........................................................................................................................................... 152WCValHash<strong>Table</strong>, WCValHashSet Class Description ............................................. 153WCValHashSet() ........................................................................................................................... 155WCValHashSet() ........................................................................................................................... 156vii
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>WCValHashSet() ........................................................................................................................... 157~WCValHashSet() ......................................................................................................................... 158WCValHash<strong>Table</strong>() ....................................................................................................................... 159WCValHash<strong>Table</strong>() ....................................................................................................................... 160WCValHash<strong>Table</strong>() ....................................................................................................................... 161~WCValHash<strong>Table</strong>() ..................................................................................................................... 162bitHash() ........................................................................................................................................ 163buckets() ........................................................................................................................................ 164clear() ............................................................................................................................................. 165contains() ....................................................................................................................................... 166entries() .......................................................................................................................................... 167find() .............................................................................................................................................. 168forAll() ........................................................................................................................................... 169insert() ............................................................................................................................................ 170isEmpty() ....................................................................................................................................... 171occurencesOf() ............................................................................................................................... 172operator =() .................................................................................................................................... 173operator ==() .................................................................................................................................. 174remove() ......................................................................................................................................... 175removeAll() .................................................................................................................................... 176resize() ........................................................................................................................................... 17711 Hash Iterators ....................................................................................................................................... 179WCPtrHashDictIter Class Description .......................................................................... 180WCPtrHashDictIter() ..................................................................................................................... 181WCPtrHashDictIter() ..................................................................................................................... 182~WCPtrHashDictIter() ................................................................................................................... 183container() ...................................................................................................................................... 184key() ............................................................................................................................................... 185operator ()() .................................................................................................................................... 186operator ++() .................................................................................................................................. 187reset() ............................................................................................................................................. 188reset() ............................................................................................................................................. 189value() ............................................................................................................................................ 190WCValHashDictIter Class Description ......................................................................... 191WCValHashDictIter() .................................................................................................................... 192WCValHashDictIter() .................................................................................................................... 193~WCValHashDictIter() .................................................................................................................. 194container() ...................................................................................................................................... 195key() ............................................................................................................................................... 196operator ()() .................................................................................................................................... 197operator ++() .................................................................................................................................. 198reset() ............................................................................................................................................. 199reset() ............................................................................................................................................. 200value() ............................................................................................................................................ 201WCPtrHashSetIter, WCPtrHash<strong>Table</strong>Iter Class Description .................................... 202WCPtrHashSetIter() ....................................................................................................................... 203WCPtrHashSetIter() ....................................................................................................................... 204~WCPtrHashSetIter() ..................................................................................................................... 205WCPtrHash<strong>Table</strong>Iter() ................................................................................................................... 206WCPtrHash<strong>Table</strong>Iter() ................................................................................................................... 207~WCPtrHash<strong>Table</strong>Iter() ................................................................................................................. 208viii
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>container() ...................................................................................................................................... 209current() ......................................................................................................................................... 210operator ()() .................................................................................................................................... 211operator ++() .................................................................................................................................. 212reset() ............................................................................................................................................. 213reset() ............................................................................................................................................. 214WCValHashSetIter, WCValHash<strong>Table</strong>Iter Class Description .................................. 215WCValHashSetIter() ...................................................................................................................... 216WCValHashSetIter() ...................................................................................................................... 217~WCValHashSetIter() ................................................................................................................... 218WCValHash<strong>Table</strong>Iter() .................................................................................................................. 219WCValHash<strong>Table</strong>Iter() .................................................................................................................. 220~WCValHash<strong>Table</strong>Iter() ............................................................................................................... 221container() ...................................................................................................................................... 222current() ......................................................................................................................................... 223operator ()() .................................................................................................................................... 224operator ++() .................................................................................................................................. 225reset() ............................................................................................................................................. 226reset() ............................................................................................................................................. 22712 List Containers ..................................................................................................................................... 229WCDLink Class Description ............................................................................................................... 230WCDLink() .................................................................................................................................... 231~WCDLink() .................................................................................................................................. 232WCIsvSList, WCIsvDList Class Description ............................................................ 233WCIsvSList() ................................................................................................................................. 235WCIsvSList() ................................................................................................................................. 236~WCIsvSList() ............................................................................................................................... 237WCIsvDList() ................................................................................................................................ 238WCIsvDList() ................................................................................................................................ 239~WCIsvDList() .............................................................................................................................. 240append() ......................................................................................................................................... 241clear() ............................................................................................................................................. 242clearAndDestroy() ......................................................................................................................... 243contains() ....................................................................................................................................... 244entries() .......................................................................................................................................... 245find() .............................................................................................................................................. 246findLast() ....................................................................................................................................... 247forAll() ........................................................................................................................................... 248get() ................................................................................................................................................ 249index() ............................................................................................................................................ 250index() ............................................................................................................................................ 251insert() ............................................................................................................................................ 252isEmpty() ....................................................................................................................................... 253operator =() .................................................................................................................................... 254operator ==() .................................................................................................................................. 255WCPtrSList, WCPtrDList Class Description ............................................................. 256WCPtrSList() ................................................................................................................................. 258WCPtrSList() ................................................................................................................................. 259WCPtrSList() ................................................................................................................................. 260~WCPtrSList() ............................................................................................................................... 261WCPtrDList() ................................................................................................................................ 262ix
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>WCPtrDList() ................................................................................................................................ 263WCPtrDList() ................................................................................................................................ 264~WCPtrDList() .............................................................................................................................. 265append() ......................................................................................................................................... 266clear() ............................................................................................................................................. 267clearAndDestroy() ......................................................................................................................... 268contains() ....................................................................................................................................... 269entries() .......................................................................................................................................... 270find() .............................................................................................................................................. 271findLast() ....................................................................................................................................... 272forAll() ........................................................................................................................................... 273get() ................................................................................................................................................ 274index() ............................................................................................................................................ 275insert() ............................................................................................................................................ 276isEmpty() ....................................................................................................................................... 277operator =() .................................................................................................................................... 278operator ==() .................................................................................................................................. 279WCSLink Class Description ................................................................................................................ 280WCSLink() .................................................................................................................................... 281~WCSLink() .................................................................................................................................. 282WCValSList, WCValDList Class Description .......................................................... 283WCValSList() ................................................................................................................................ 285WCValSList() ................................................................................................................................ 286WCValSList() ................................................................................................................................ 287~WCValSList() .............................................................................................................................. 288WCValDList() ............................................................................................................................... 289WCValDList() ............................................................................................................................... 290WCValDList() ............................................................................................................................... 291~WCValDList() ............................................................................................................................. 292append() ......................................................................................................................................... 293clear() ............................................................................................................................................. 294clearAndDestroy() ......................................................................................................................... 295contains() ....................................................................................................................................... 296entries() .......................................................................................................................................... 297find() .............................................................................................................................................. 298findLast() ....................................................................................................................................... 299forAll() ........................................................................................................................................... 300get() ................................................................................................................................................ 301index() ............................................................................................................................................ 302insert() ............................................................................................................................................ 303isEmpty() ....................................................................................................................................... 304operator =() .................................................................................................................................... 305operator ==() .................................................................................................................................. 30613 List Iterators ......................................................................................................................................... 307WCIsvConstSListIter, WCIsvConstDListIter Class Description .............................. 308WCIsvConstSListIter() .................................................................................................................. 309WCIsvConstSListIter() .................................................................................................................. 310~WCIsvConstSListIter() ................................................................................................................ 311WCIsvConstDListIter() ................................................................................................................. 312WCIsvConstDListIter() ................................................................................................................. 313~WCIsvConstDListIter() ............................................................................................................... 314x
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>container() ...................................................................................................................................... 315current() ......................................................................................................................................... 316operator ()() .................................................................................................................................... 317operator ++() .................................................................................................................................. 318operator +=() .................................................................................................................................. 319operator --() .................................................................................................................................... 320operator -=() ................................................................................................................................... 321reset() ............................................................................................................................................. 322reset() ............................................................................................................................................. 323WCIsvSListIter, WCIsvDListIter Class Description ................................................. 324WCIsvSListIter() ........................................................................................................................... 326WCIsvSListIter() ........................................................................................................................... 327~WCIsvSListIter() ......................................................................................................................... 328WCIsvDListIter() ........................................................................................................................... 329WCIsvDListIter() ........................................................................................................................... 330~WCIsvDListIter() ......................................................................................................................... 331append() ......................................................................................................................................... 332container() ...................................................................................................................................... 333current() ......................................................................................................................................... 334insert() ............................................................................................................................................ 335operator ()() .................................................................................................................................... 336operator ++() .................................................................................................................................. 337operator +=() .................................................................................................................................. 338operator --() .................................................................................................................................... 339operator -=() ................................................................................................................................... 340reset() ............................................................................................................................................. 341reset() ............................................................................................................................................. 342WCPtrConstSListIter, WCPtrConstDListIter Class Description ............................... 343WCPtrConstSListIter() .................................................................................................................. 344WCPtrConstSListIter() .................................................................................................................. 345~WCPtrConstSListIter() ................................................................................................................ 346WCPtrConstDListIter() .................................................................................................................. 347WCPtrConstDListIter() .................................................................................................................. 348~WCPtrConstDListIter() ............................................................................................................... 349container() ...................................................................................................................................... 350current() ......................................................................................................................................... 351operator ()() .................................................................................................................................... 352operator ++() .................................................................................................................................. 353operator +=() .................................................................................................................................. 354operator --() .................................................................................................................................... 355operator -=() ................................................................................................................................... 356reset() ............................................................................................................................................. 357reset() ............................................................................................................................................. 358WCPtrSListIter, WCPtrDListIter Class Description ................................................. 359WCPtrSListIter() ............................................................................................................................ 361WCPtrSListIter() ............................................................................................................................ 362~WCPtrSListIter() ......................................................................................................................... 363WCPtrDListIter() ........................................................................................................................... 364WCPtrDListIter() ........................................................................................................................... 365~WCPtrDListIter() ......................................................................................................................... 366append() ......................................................................................................................................... 367container() ...................................................................................................................................... 368xi
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>current() ......................................................................................................................................... 369insert() ............................................................................................................................................ 370operator ()() .................................................................................................................................... 371operator ++() .................................................................................................................................. 372operator +=() .................................................................................................................................. 373operator --() .................................................................................................................................... 374operator -=() ................................................................................................................................... 375reset() ............................................................................................................................................. 376reset() ............................................................................................................................................. 377WCValConstSListIter, WCValConstDListIter Class Description ............................. 378WCValConstSListIter() ................................................................................................................. 379WCValConstSListIter() ................................................................................................................. 380~WCValConstSListIter() ............................................................................................................... 381WCValConstDListIter() ................................................................................................................. 382WCValConstDListIter() ................................................................................................................. 383~WCValConstDListIter() .............................................................................................................. 384container() ...................................................................................................................................... 385current() ......................................................................................................................................... 386operator ()() .................................................................................................................................... 387operator ++() .................................................................................................................................. 388operator +=() .................................................................................................................................. 389operator --() .................................................................................................................................... 390operator -=() ................................................................................................................................... 391reset() ............................................................................................................................................. 392reset() ............................................................................................................................................. 393WCValSListIter, WCValDListIter Class Description ............................................... 394WCValSListIter() .......................................................................................................................... 396WCValSListIter() .......................................................................................................................... 397~WCValSListIter() ........................................................................................................................ 398WCValDListIter() .......................................................................................................................... 399WCValDListIter() .......................................................................................................................... 400~WCValDListIter() ........................................................................................................................ 401append() ......................................................................................................................................... 402container() ...................................................................................................................................... 403current() ......................................................................................................................................... 404insert() ............................................................................................................................................ 405operator ()() .................................................................................................................................... 406operator ++() .................................................................................................................................. 407operator +=() .................................................................................................................................. 408operator --() .................................................................................................................................... 409operator -=() ................................................................................................................................... 410reset() ............................................................................................................................................. 411reset() ............................................................................................................................................. 41214 Queue Container ................................................................................................................................... 413WCQueue Class Description ....................................................................................... 414WCQueue() .................................................................................................................................... 415WCQueue() .................................................................................................................................... 416~WCQueue() .................................................................................................................................. 417clear() ............................................................................................................................................. 418entries() .......................................................................................................................................... 419first() .............................................................................................................................................. 420xii
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>get() ................................................................................................................................................ 421insert() ............................................................................................................................................ 422isEmpty() ....................................................................................................................................... 423last() ............................................................................................................................................... 42415 Skip List Containers ............................................................................................................................. 425WCPtrSkipListDict Class Description ........................................................................... 426WCPtrSkipListDict() ..................................................................................................................... 428WCPtrSkipListDict() ..................................................................................................................... 429WCPtrSkipListDict() ..................................................................................................................... 430~WCPtrSkipListDict() ................................................................................................................... 431clear() ............................................................................................................................................. 432clearAndDestroy() ......................................................................................................................... 433contains() ....................................................................................................................................... 434entries() .......................................................................................................................................... 435find() .............................................................................................................................................. 436findKeyAndValue() ....................................................................................................................... 437forAll() ........................................................................................................................................... 438insert() ............................................................................................................................................ 439isEmpty() ....................................................................................................................................... 440operator []() .................................................................................................................................... 441operator []() .................................................................................................................................... 442operator =() .................................................................................................................................... 443operator ==() .................................................................................................................................. 444remove() ......................................................................................................................................... 445WCPtrSkipList, WCPtrSkipListSet Class Description .............................................. 446WCPtrSkipListSet() ....................................................................................................................... 448WCPtrSkipListSet() ....................................................................................................................... 449WCPtrSkipListSet() ....................................................................................................................... 450~WCPtrSkipListSet() ..................................................................................................................... 451WCPtrSkipList() ............................................................................................................................ 452WCPtrSkipList() ............................................................................................................................ 453WCPtrSkipList() ............................................................................................................................ 454~WCPtrSkipList() .......................................................................................................................... 455clear() ............................................................................................................................................. 456clearAndDestroy() ......................................................................................................................... 457contains() ....................................................................................................................................... 458entries() .......................................................................................................................................... 459find() .............................................................................................................................................. 460forAll() ........................................................................................................................................... 461insert() ............................................................................................................................................ 462isEmpty() ....................................................................................................................................... 463occurrencesOf() ............................................................................................................................. 464operator =() .................................................................................................................................... 465operator ==() .................................................................................................................................. 466remove() ......................................................................................................................................... 467removeAll() .................................................................................................................................... 468WCValSkipListDict Class Description ......................................................................... 469WCValSkipListDict() .................................................................................................................... 471WCValSkipListDict() .................................................................................................................... 472WCValSkipListDict() .................................................................................................................... 473~WCValSkipListDict() .................................................................................................................. 474xiii
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>clear() ............................................................................................................................................. 475contains() ....................................................................................................................................... 476entries() .......................................................................................................................................... 477find() .............................................................................................................................................. 478findKeyAndValue() ....................................................................................................................... 479forAll() ........................................................................................................................................... 480insert() ............................................................................................................................................ 481isEmpty() ....................................................................................................................................... 482operator []() .................................................................................................................................... 483operator []() .................................................................................................................................... 484operator =() .................................................................................................................................... 485operator ==() .................................................................................................................................. 486remove() ......................................................................................................................................... 487WCValSkipList, WCValSkipListSet Class Description ............................................ 488WCValSkipListSet() ...................................................................................................................... 490WCValSkipListSet() ...................................................................................................................... 491WCValSkipListSet() ...................................................................................................................... 492~WCValSkipListSet() .................................................................................................................... 493WCValSkipList() ........................................................................................................................... 494WCValSkipList() ........................................................................................................................... 495WCValSkipList() ........................................................................................................................... 496~WCValSkipList() ......................................................................................................................... 497clear() ............................................................................................................................................. 498contains() ....................................................................................................................................... 499entries() .......................................................................................................................................... 500find() .............................................................................................................................................. 501forAll() ........................................................................................................................................... 502insert() ............................................................................................................................................ 503isEmpty() ....................................................................................................................................... 504occurrencesOf() ............................................................................................................................. 505operator =() .................................................................................................................................... 506operator ==() .................................................................................................................................. 507remove() ......................................................................................................................................... 508removeAll() .................................................................................................................................... 50916 Stack Container .................................................................................................................................... 511WCStack Class Description ........................................................................................ 512WCStack() ..................................................................................................................................... 513WCStack() ..................................................................................................................................... 514~WCStack() ................................................................................................................................... 515clear() ............................................................................................................................................. 516entries() .......................................................................................................................................... 517isEmpty() ....................................................................................................................................... 518pop() ............................................................................................................................................... 519push() ............................................................................................................................................. 520top() ................................................................................................................................................ 52117 Vector Containers ................................................................................................................................. 523WCPtrSortedVector, WCPtrOrderedVector Class Description ................................. 524WCPtrOrderedVector() .................................................................................................................. 526WCPtrOrderedVector() .................................................................................................................. 527~WCPtrOrderedVector() ............................................................................................................... 528xiv
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>WCPtrSortedVector() .................................................................................................................... 529WCPtrSortedVector() .................................................................................................................... 530~WCPtrSortedVector() .................................................................................................................. 531append() ......................................................................................................................................... 532clear() ............................................................................................................................................. 533clearAndDestroy() ......................................................................................................................... 534contains() ....................................................................................................................................... 535entries() .......................................................................................................................................... 536find() .............................................................................................................................................. 537first() .............................................................................................................................................. 538index() ............................................................................................................................................ 539insert() ............................................................................................................................................ 540insertAt() ........................................................................................................................................ 541isEmpty() ....................................................................................................................................... 542last() ............................................................................................................................................... 543occurrencesOf() ............................................................................................................................. 544operator []() .................................................................................................................................... 545operator =() .................................................................................................................................... 546operator ==() .................................................................................................................................. 547prepend() ........................................................................................................................................ 548remove() ......................................................................................................................................... 549removeAll() .................................................................................................................................... 550removeAt() ..................................................................................................................................... 551removeFirst() ................................................................................................................................. 552removeLast() .................................................................................................................................. 553resize() ........................................................................................................................................... 554WCPtrVector Class Description ............................................................................................. 555WCPtrVector() ............................................................................................................................... 556WCPtrVector() ............................................................................................................................... 557WCPtrVector() ............................................................................................................................... 558~WCPtrVector() ............................................................................................................................. 559clear() ............................................................................................................................................. 560clearAndDestroy() ......................................................................................................................... 561length() ........................................................................................................................................... 562operator []() .................................................................................................................................... 563operator =() .................................................................................................................................... 564operator ==() .................................................................................................................................. 565resize() ........................................................................................................................................... 566WCValSortedVector, WCValOrderedVector Class Description ............................... 567WCValOrderedVector() ................................................................................................................ 570WCValOrderedVector() ................................................................................................................ 571~WCValOrderedVector() .............................................................................................................. 572WCValSortedVector() ................................................................................................................... 573WCValSortedVector() ................................................................................................................... 574~WCValSortedVector() ................................................................................................................. 575append() ......................................................................................................................................... 576clear() ............................................................................................................................................. 577contains() ....................................................................................................................................... 578entries() .......................................................................................................................................... 579find() .............................................................................................................................................. 580first() .............................................................................................................................................. 581index() ............................................................................................................................................ 582xv
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>insert() ............................................................................................................................................ 583insertAt() ........................................................................................................................................ 584isEmpty() ....................................................................................................................................... 585last() ............................................................................................................................................... 586occurrencesOf() ............................................................................................................................. 587operator []() .................................................................................................................................... 588operator =() .................................................................................................................................... 589operator ==() .................................................................................................................................. 590prepend() ........................................................................................................................................ 591remove() ......................................................................................................................................... 592removeAll() .................................................................................................................................... 593removeAt() ..................................................................................................................................... 594removeFirst() ................................................................................................................................. 595removeLast() .................................................................................................................................. 596resize() ........................................................................................................................................... 597WCValVector Class Description ............................................................................................ 598WCValVector() .............................................................................................................................. 599WCValVector() .............................................................................................................................. 600WCValVector() .............................................................................................................................. 601~WCValVector() ........................................................................................................................... 602clear() ............................................................................................................................................. 603length() ........................................................................................................................................... 604operator []() .................................................................................................................................... 605operator =() .................................................................................................................................... 606operator ==() .................................................................................................................................. 607resize() ........................................................................................................................................... 60818 Input/Output Classes ............................................................................................................................ 609filebuf Class Description ..................................................................................................................... 610attach() ........................................................................................................................................... 612close() ............................................................................................................................................ 613fd() ................................................................................................................................................. 614filebuf() .......................................................................................................................................... 615filebuf() .......................................................................................................................................... 616filebuf() .......................................................................................................................................... 617~filebuf() ........................................................................................................................................ 618is_open() ........................................................................................................................................ 619open() ............................................................................................................................................. 620openprot ......................................................................................................................................... 621overflow() ...................................................................................................................................... 622pbackfail() ...................................................................................................................................... 623seek<strong>of</strong>f() ......................................................................................................................................... 624setbuf() ........................................................................................................................................... 625sync() ............................................................................................................................................. 626underflow() .................................................................................................................................... 627fstream Class Description .................................................................................................................... 628fstream() ......................................................................................................................................... 629fstream() ......................................................................................................................................... 630fstream() ......................................................................................................................................... 631fstream() ......................................................................................................................................... 632~fstream() ....................................................................................................................................... 633open() ............................................................................................................................................. 634xvi
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>fstreambase Class Description ............................................................................................................. 635attach() ........................................................................................................................................... 636close() ............................................................................................................................................ 637fstreambase() .................................................................................................................................. 638fstreambase() .................................................................................................................................. 639fstreambase() .................................................................................................................................. 640fstreambase() .................................................................................................................................. 641~fstreambase() ............................................................................................................................... 642is_open() ........................................................................................................................................ 643fd() ................................................................................................................................................. 644open() ............................................................................................................................................. 645rdbuf() ............................................................................................................................................ 646setbuf() ........................................................................................................................................... 647ifstream Class Description ................................................................................................................... 648ifstream() ........................................................................................................................................ 649ifstream() ........................................................................................................................................ 650ifstream() ........................................................................................................................................ 651ifstream() ........................................................................................................................................ 652~ifstream() ..................................................................................................................................... 653open() ............................................................................................................................................. 654ios Class Description ........................................................................................................................... 655bad() ............................................................................................................................................... 657bitalloc() ......................................................................................................................................... 658clear() ............................................................................................................................................. 659e<strong>of</strong>() ................................................................................................................................................ 660exceptions() .................................................................................................................................... 661fail() ............................................................................................................................................... 662fill() ................................................................................................................................................ 663flags() ............................................................................................................................................. 664fmtflags .......................................................................................................................................... 665good() ............................................................................................................................................. 668init() ............................................................................................................................................... 669ios() ................................................................................................................................................ 670ios() ................................................................................................................................................ 671~ios() .............................................................................................................................................. 672iostate ............................................................................................................................................. 673iword() ........................................................................................................................................... 674openmode ....................................................................................................................................... 675operator !() ..................................................................................................................................... 677operator void *() ............................................................................................................................ 678precision() ...................................................................................................................................... 679pword() .......................................................................................................................................... 680rdbuf() ............................................................................................................................................ 681rdstate() .......................................................................................................................................... 682seekdir ............................................................................................................................................ 683setf() ............................................................................................................................................... 684setstate() ......................................................................................................................................... 685sync_with_stdio() .......................................................................................................................... 686tie() ................................................................................................................................................. 687unsetf() ........................................................................................................................................... 688width() ............................................................................................................................................ 689xalloc() ........................................................................................................................................... 690xvii
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>iostream Class Description .................................................................................................................. 691iostream() ....................................................................................................................................... 692iostream() ....................................................................................................................................... 693iostream() ....................................................................................................................................... 694~iostream() ..................................................................................................................................... 695operator =() .................................................................................................................................... 696operator =() .................................................................................................................................... 697istream Class Description .................................................................................................................... 698eatwhite() ....................................................................................................................................... 700gcount() .......................................................................................................................................... 701get() ................................................................................................................................................ 702get() ................................................................................................................................................ 703get() ................................................................................................................................................ 704get() ................................................................................................................................................ 705getline() .......................................................................................................................................... 706ignore() .......................................................................................................................................... 707ipfx() .............................................................................................................................................. 708isfx() ............................................................................................................................................... 709istream() ......................................................................................................................................... 710istream() ......................................................................................................................................... 711istream() ......................................................................................................................................... 712~istream() ....................................................................................................................................... 713operator =() .................................................................................................................................... 714operator =() .................................................................................................................................... 715operator >>() .................................................................................................................................. 716operator >>() .................................................................................................................................. 717operator >>() .................................................................................................................................. 718operator >>() .................................................................................................................................. 719operator >>() .................................................................................................................................. 720operator >>() .................................................................................................................................. 721peek() ............................................................................................................................................. 722putback() ........................................................................................................................................ 723read() .............................................................................................................................................. 724seekg() ............................................................................................................................................ 725seekg() ............................................................................................................................................ 726sync() ............................................................................................................................................. 727tellg() .............................................................................................................................................. 728istrstream Class Description ................................................................................................................ 729istrstream() ..................................................................................................................................... 730istrstream() ..................................................................................................................................... 731~istrstream() ................................................................................................................................... 732Manipulators .................................................................................................................................. 733manipulator dec() ........................................................................................................................... 734manipulator endl() ......................................................................................................................... 735manipulator ends() ......................................................................................................................... 736manipulator flush() ........................................................................................................................ 737manipulator hex() ........................................................................................................................... 738manipulator oct() ........................................................................................................................... 739manipulator resetiosflags() ............................................................................................................ 740manipulator setbase() ..................................................................................................................... 741manipulator setfill() ....................................................................................................................... 742manipulator setiosflags() ................................................................................................................ 743xviii
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>manipulator setprecision() ............................................................................................................. 744manipulator setw() ......................................................................................................................... 745manipulator setwidth() ................................................................................................................... 746manipulator ws() ............................................................................................................................ 747<strong>of</strong>stream Class Description .................................................................................................................. 748<strong>of</strong>stream() ....................................................................................................................................... 749<strong>of</strong>stream() ....................................................................................................................................... 750<strong>of</strong>stream() ....................................................................................................................................... 751<strong>of</strong>stream() ....................................................................................................................................... 752~<strong>of</strong>stream() ..................................................................................................................................... 753open() ............................................................................................................................................. 754ostream Class Description ................................................................................................................... 755flush() ............................................................................................................................................. 757operator
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>do_sputn() ...................................................................................................................................... 799doallocate() .................................................................................................................................... 800eback() ........................................................................................................................................... 801ebuf() .............................................................................................................................................. 802egptr() ............................................................................................................................................ 803epptr() ............................................................................................................................................ 804gbump() .......................................................................................................................................... 805gptr() .............................................................................................................................................. 806in_avail() ........................................................................................................................................ 807out_waiting() .................................................................................................................................. 808overflow() ...................................................................................................................................... 809pbackfail() ...................................................................................................................................... 810pbase() ............................................................................................................................................ 811pbump() .......................................................................................................................................... 812pptr() .............................................................................................................................................. 813sbumpc() ........................................................................................................................................ 814seek<strong>of</strong>f() ......................................................................................................................................... 815seekpos() ........................................................................................................................................ 816setb() .............................................................................................................................................. 817setbuf() ........................................................................................................................................... 818setg() .............................................................................................................................................. 819setp() .............................................................................................................................................. 820sgetc() ............................................................................................................................................ 821sgetchar() ....................................................................................................................................... 822sgetn() ............................................................................................................................................ 823snextc() .......................................................................................................................................... 824speekc() .......................................................................................................................................... 825sputbackc() ..................................................................................................................................... 826sputc() ............................................................................................................................................ 827sputn() ............................................................................................................................................ 828stossc() ........................................................................................................................................... 829streambuf() ..................................................................................................................................... 830streambuf() ..................................................................................................................................... 831~streambuf() ................................................................................................................................... 832sync() ............................................................................................................................................. 833unbuffered() ................................................................................................................................... 834underflow() .................................................................................................................................... 835strstream Class Description ................................................................................................................. 836str() ................................................................................................................................................. 837strstream() ...................................................................................................................................... 838strstream() ...................................................................................................................................... 839~strstream() .................................................................................................................................... 840strstreambase Class Description .......................................................................................................... 841rdbuf() ............................................................................................................................................ 842strstreambase() ............................................................................................................................... 843strstreambase() ............................................................................................................................... 844~strstreambase() ............................................................................................................................. 845strstreambuf Class Description ............................................................................................................ 846alloc_size_increment() ................................................................................................................... 847doallocate() .................................................................................................................................... 848freeze() ........................................................................................................................................... 849overflow() ...................................................................................................................................... 850xx
<strong>Table</strong> <strong>of</strong> <strong>Contents</strong>seek<strong>of</strong>f() ......................................................................................................................................... 851setbuf() ........................................................................................................................................... 852str() ................................................................................................................................................. 853strstreambuf() ................................................................................................................................. 854strstreambuf() ................................................................................................................................. 855strstreambuf() ................................................................................................................................. 856strstreambuf() ................................................................................................................................. 857~strstreambuf() ............................................................................................................................... 858sync() ............................................................................................................................................. 859underflow() .................................................................................................................................... 86019 String Class .......................................................................................................................................... 861String Class Description ...................................................................................................................... 862alloc_mult_size() ........................................................................................................................... 864get_at() ........................................................................................................................................... 865index() ............................................................................................................................................ 866length() ........................................................................................................................................... 867lower() ............................................................................................................................................ 868match() ........................................................................................................................................... 869operator !() ..................................................................................................................................... 870String operator !=() ........................................................................................................................ 871operator ()() .................................................................................................................................... 872operator ()() .................................................................................................................................... 873String operator +() ......................................................................................................................... 874operator +=() .................................................................................................................................. 875String operator () ....................................................................................................................... 883operator []() .................................................................................................................................... 884operator char() ............................................................................................................................... 885operator char const *() ................................................................................................................... 886put_at() ........................................................................................................................................... 887String() ........................................................................................................................................... 888String() ........................................................................................................................................... 889String() ........................................................................................................................................... 890String() ........................................................................................................................................... 891String() ........................................................................................................................................... 892~String() ......................................................................................................................................... 893upper() ............................................................................................................................................ 894String valid() .................................................................................................................................. 895valid() ............................................................................................................................................. 896xxi
xxii
Open Watcom C++ Class LibraryReference
Open Watcom C++ Class Library Reference2
1 Header FilesThe following header files are supplied with the Open Watcom C++ library. When a class or function fromthe library is used in a source file the related header file should be included in that source file. The headerfiles can be included multiple times and in any order with no ill effect.The facilities <strong>of</strong> the C standard library can be used in C++ programs by including the appropriate "cname"header. In that case all <strong>of</strong> the C standard library functions are in namespace std. For example, to usefunction std::printf one should include the header cstdio. Note that the cname headers declare in theglobal namespace any non-standard names they contain as extensions. It is also possible to include in aC++ program the same headers used by C programs. In that case, the standard functions are in both theglobal namespace as well as in namespace std.Some <strong>of</strong> C++ standard library headers described below come in a form with a .h extension and in a formwithout an extension. The extensionless headers declare their library classes and functions in namespacestd. The headers with a .h extension declare their library classes and functions in both the globalnamespace and in namespace std. Such headers are provided as a convenience and for compatibility withlegacy code. Programs that intend to conform to Standard C++ should use the extensionless headers toaccess the facilities <strong>of</strong> the C++ standard library.Certain headers defined by Standard C++ have names that are longer than the 8.3 limit imposed by theFAT16 filesystem. Such headers are provided with names that are truncated to eight characters so they canbe used with the DOS host. However, one can still refer to them in #include directives using their fullnames as defined by the standard. If the Open Watcom C++ compiler is unable to open a header with thelong name, it will truncate the name and try again.The Open Watcom C++ library contains some components that were developed before C++ wasstandardized. These legacy components continue to be supported and are described in this documentation.The header files are all located in the \WATCOM\H directory.algorithm (algorith) This header file defines the standard algorithm templates.complexcomplex.hThis header file defines the std::complex class template and related function templates.This template can be instantiated for the three different floating point types. It can be usedto represent complex numbers and to perform complex arithmetic.This header file defines the legacy Complex class. This class is used to represent complexnumbers and to perform complex arithmetic. The class defined in this header is not theStandard C++ std::complex class template.exception/exception.h (exceptio/exceptio.h) This header file defines components to be used with theexception handling mechanism. It defines the base class <strong>of</strong> the standard exceptionhierarchy.functional (function) This header file defines the standard functional templates. This includes the functorsand binders described by Standard C++.Header Files 3
Open Watcom C++ Class Library Referencefstream/fstream.h This header file defines the filebuf, fstreambase, ifstream, <strong>of</strong>stream, andfstream classes. These classes are used to perform C++ file input and output operations.The various class members are declared and inline member functions for the classes aredefined.generic.hThis header file is part <strong>of</strong> the macro support required to implement generic containers priorto the introduction <strong>of</strong> templates in the C++ language. It is retained for backwardscompatibility.iomanip/iomanip.h This header file defines the parameterized manipulators.ios/ios.hThis header file defines the class ios that is used as a base <strong>of</strong> the other iostream classes.iosfwd/iosfwd.h This header file provides forward declarations <strong>of</strong> the iostream classes. It should be used incases where the full class definitions are not needed but where one still wants to declarepointers or references to iostream related objects. Typically this occurs in a header foranother class that wants to provide overloaded inserter or extractor operators. By includingiosfwd instead <strong>of</strong> iostream (for example), compilation speed can be improved becauseless material must be processed by the compiler.Note that including iosfwd is the only appropriate way to forward declare the iostreamclasses. Manually writing forward declarations is not recommended.iostream/iostream.h This header file (indirectly) defines the ios, istream, ostream, and iostreamclasses. These classes form the basis <strong>of</strong> the C++ formatted input and output support. Thevarious class members are declared and inline member functions for the classes are defined.The cin, cout, cerr, and clog predefined objects are declared along with thenon-parameterized manipulators.istream/istream.h This header file defines class istream and class iostream. It also defines theirassociated parameterless manipulators.iteratorlimitsThis header file defines several templates to facilitate the handling <strong>of</strong> iterators. Inparticular, it defines the std::iterator_traits template as well as several othersupporting iterator related templates.This header file defines the std::umeric_limits template and providesspecializations <strong>of</strong> that template for each <strong>of</strong> the built-in types.Note that this header is not directly related to the header limits.h from the C standardlibrary (or to the C++ form <strong>of</strong> that header, climits).listmapmemoryThis header file defines the std::list class template. It provides a way to make asequence <strong>of</strong> objects with efficient insert and erase operations.This header file defines the std::map and std::multimap class templates. Theyprovide ways to associate keys to values.This header file defines the default allocator template, std::allocator, as well asseveral function templates for manipulating raw (uninitialized) memory regions. Inaddition this header defines the std::auto_ptr template.Note that the header memory.h is part <strong>of</strong> the Open Watcom C library and is unrelated tomemory.4 Header Files
Header Filesnew/new.hnumericThis header file provides declarations to be used with the intrinsic operator new andoperator delete memory management functions.This header file defines several standard algorithm templates pertaining to numericalcomputation.ostream/ostream.h This header file defines class ostream. It also defines its associated parameterlessmanipulators.setstdiobuf.hThis header file defines the std::set and std::multiset class templates. Theyprovide ways to make ordered collections <strong>of</strong> objects with efficient insert, erase, and findoperations.This header file defines the stdiobuf class which provides the support for the C++ inputand output operations to standard input, standard output, and standard error streams.streambuf/streambuf.h (streambu/streambu.h) This header file defines the streambuf class whichprovides the support for buffering <strong>of</strong> input and output operations. This header file isautomatically included by the iostream.h header file.stringstring.hppThis header file defines the std::basic_string class template. It also contains thetype definitions for std::string and std::wstring. In addition, this headercontains specializations <strong>of</strong> the std::char_traits template for both characters andwide characters.This header file defines the legacy String class. The String class is used tomanipulate character strings. Note that the hpp extension is used to avoid colliding withthe Standard C string.h header file. The class defined in this header is not the StandardC++ std::string class.strstream.h (strstrea.h) This header files defines the strstreambuf, strstreambase,istrstream, ostrstream, and strstream classes. These classes are used toperform C++ in-memory formatting. The various class members are declared and inlinemember functions for the classes are defined.vectorwcdefs.hThis header contains the std::vector class template.This header file contains definitions used by the Open Watcom legacy container libraries.If a container class needs any <strong>of</strong> these definitions, the file is automatically included.Note that all headers having names that start with "wc" are related to the legacy containerlibraries.wclbase.hwclcom.hwclibase.hwclist.hwclistit.hThis header file defines the base classes which are used by the list containers.This header file defines the classes which are common to the list containers.This header file defines the base classes which are used by the list iterators.This header file defines the list container classes. The available list container classes aresingle and double linked versions <strong>of</strong> intrusive, value and pointer lists.This header file defines the iterator classes that correspond to the list containers.Header Files 5
Open Watcom C++ Class Library Referencewcqueue.hwcstack.hThis header file defines the queue class. Entries in a queue class are accessed first in, firstout.This header file defines the stack class. Entries in a stack class are accessed last in, firstout.6 Header Files
2 Common TypesThe set <strong>of</strong> classes that make up the C++ class library use several common typedefs and macros. They aredeclared in and .typedef long streampos;typedef long stream<strong>of</strong>f;typedef int filedesc;#define __NOT_EOF 0#define EOF -1The streampos type represents an absolute position within the file. For Open Watcom C++, the fileposition can be represented by an integral type. For some file systems, or at a lower level within the filesystem, the stream position might be represented by an aggregate (structure) containing information such ascylinder, track, sector and <strong>of</strong>fset.The stream<strong>of</strong>f type represents a relative position within the file. The <strong>of</strong>fset can always be representedas a signed integer quantity since it is a number <strong>of</strong> characters before or after an absolute position within thefile.The filedesc type represents the type <strong>of</strong> a C library file handle. It is used in places where the I/O streamlibrary takes a C library file handle as an argument.The __NOT_EOF macro is defined for cases where a function needs to return something other than EOF toindicate success.The EOF macro is defined to be identical to the value provided by the header file.Common Types 7
Open Watcom C++ Class Library Reference8 Common Types
3 Predefined ObjectsMost programs interact in some manner with the keyboard and screen. The C programming languageprovides three values, stdin, stdout and stderr, that are used for communicating with these"standard" devices, which are opened before the user program starts execution at main(). These threevalues are FILE pointers and can be used in virtually any file operation supported by the C library.In a similar manner, C++ provides seven objects for communicating with the same "standard" devices.C++ provides the three C FILE pointers stdin, stdout and stderr, but they cannot be used with theextractors and inserters provided as part <strong>of</strong> the C++ library. C++ provides four new objects, called cin,cout, cerr and clog, which correspond to stdin, stdout, stderr and buffered stderr.3.1 cincin is an istream object which is connected to "standard input" (usually the keyboard) prior to programexecution. Values extracted using the istream operator >> class extractor operators are read fromstandard input and interpreted according to the type <strong>of</strong> the object being extracted.Extractions from standard input via cin skip whitespace characters by default because the ios::skipwsbit is on. The default behavior can be changed with the ios::setf public member function or with thesetiosflags manipulator.3.2 coutcout is an ostream object which is connected to "standard output" (usually the screen) prior to programexecution. Values inserted using the ostream operator
4 istream InputThis chapter describes formatted and unformatted input.4.1 Formatted Input: ExtractorsThe operator >> function is used to read formatted values from a stream. It is called an extractor.Characters are read and interpreted according to the type <strong>of</strong> object being extracted.All operator >> functions perform the same basic sequence <strong>of</strong> operations. First, the input prefixfunction ipfx is called with a parameter <strong>of</strong> zero, causing leading whitespace characters to be discarded ifios::skipws is set in ios::fmtflags. If the input prefix function fails and returns zero, theoperator >> function also fails and returns immediately. If the input prefix function succeeds,characters are read from the stream and interpreted in terms <strong>of</strong> the type <strong>of</strong> object being extracted andios::fmtflags. Finally, the input suffix function isfx is called.The operator >> functions return a reference to the specified stream so that multiple extractions can bedone in one statement.Errors are indicated via ios::iostate. ios::failbit is set if the characters read from the streamcould not be interpreted for the required type. ios::badbit is set if the extraction <strong>of</strong> characters fromthe stream failed in such a way as to make subsequent extractions impossible. ios::e<strong>of</strong>bit is set if thestream was located at the end when the extraction was attempted.4.2 Unformatted InputThe unformatted input functions are used to read characters from the stream without interpretation.Like the extractors, the unformatted input functions follow a pattern. First, they call ipfx, the input prefixfunction, with a parameter <strong>of</strong> one, causing no leading whitespace characters to be discarded. If the inputprefix function fails and returns zero, the unformatted input function also fails and returns immediately. Ifthe input prefix function succeeds, characters are read from the stream without interpretation. Finally,isfx, the input suffix function, is called.Errors are indicated via the iostate bits. ios::failbit is set if the extraction <strong>of</strong> characters from thestream failed. ios::e<strong>of</strong>bit is set if the stream was located at the end <strong>of</strong> input when the operation wasattempted.Unformatted Input 11
Open Watcom C++ Class Library Reference12 Unformatted Input
5 ostream OutputThis chapter describes formatted and unformatted output.5.1 Formatted Output: InsertersThe operator
Open Watcom C++ Class Library Reference14 Unformatted Output
6 Library Functions and TypesEach <strong>of</strong> the classes and functions in the Class Library is described in this chapter. Each description consists<strong>of</strong> a number <strong>of</strong> subsections:Declared:This optional subsection specifies which header file contains the declaration for a class. It is only foundin sections describing class declarations.Derived From:This optional subsection shows the inheritance for a class. It is only found in sections describing classdeclarations.Derived By:Synopsis:This optional subsection shows which classes inherit from this class. It is only found in sectionsdescribing class declarations.This subsection gives the name <strong>of</strong> the header file that contains the declaration <strong>of</strong> the function. Thisheader file must be included in order to reference the function.For class member functions, the protection associated with the function is indicated via the presence <strong>of</strong>one <strong>of</strong> the private, protected, or public keywords.The full function prototype is specified. Virtual class member functions are indicated via the presence<strong>of</strong> the virtual keyword in the function prototype.Semantics:This subsection is a description <strong>of</strong> the function.Derived Implementation Protocol:This optional subsection is present for virtual member functions. It describes how derivedimplementations <strong>of</strong> the virtual member function should behave.Default Implementation:This optional subsection is present for virtual member functions. It describes how the defaultimplementation provided with the base class definition behaves.Results:See Also:This optional subsection describes the function’s return value, if any, and the impact <strong>of</strong> a memberfunction on its object’s state.This optional subsection provides a list <strong>of</strong> related functions or classes.Functions and Types 15
Open Watcom C++ Class Library Reference16 Functions and Types
7 Complex ClassThis class is used for the storage and manipulation <strong>of</strong> complex numbers, which are <strong>of</strong>ten represented byreal and imaginary components (Cartesian coordinates), or by magnitude and angle (polar coordinates).Each object stores exactly one complex number. An object may be used in expressions in the same manneras floating-point values.The class documented here is the Open Watcom legacy complex class. It is not the std::complex classtemplate specified by Standard C++.Complex Class 17
ComplexDeclared:complex.hThe Complex class is used for the storage and manipulation <strong>of</strong> complex numbers, which are <strong>of</strong>tenrepresented by real and imaginary components (Cartesian coordinates), or by magnitude and angle(polar coordinates). Each Complex object stores exactly one complex number. A Complex objectmay be used in expressions in the same manner as floating-point values.Public Member FunctionsThe following constructors and destructors are declared:Complex();Complex( Complex const & );Complex( double, double = 0.0 );~Complex();The following arithmetic member functions are declared:Complex &operator =( Complex const & );Complex &operator =( double );Complex &operator +=( Complex const & );Complex &operator +=( double );Complex &operator -=( Complex const & );Complex &operator -=( double );Complex &operator *=( Complex const & );Complex &operator *=( double );Complex &operator /=( Complex const & );Complex &operator /=( double );Complex operator +() const;Complex operator -() const;double imag() const;double real() const;Friend FunctionsThe following I/O Stream inserter and extractor friend functions are declared:friend istream &operator >>( istream &, Complex & );friend ostream &operator
Complexint operator ==( Complex const &, double );int operator ==( double , Complex const & );int operator !=( Complex const &, Complex const & );int operator !=( Complex const &, double );int operator !=( double , Complex const & );Related FunctionsThe following related functions are declared:double abs ( Complex const & );Complex acos ( Complex const & );Complex acosh( Complex const & );double arg ( Complex const & );Complex asin ( Complex const & );Complex asinh( Complex const & );Complex atan ( Complex const & );Complex atanh( Complex const & );Complex conj ( Complex const & );Complex cos ( Complex const & );Complex cosh ( Complex const & );Complex exp ( Complex const & );double imag ( Complex const & );Complex log ( Complex const & );Complex log10( Complex const & );double norm ( Complex const & );Complex polar( double , double = 0 );Complex pow ( Complex const &, Complex const & );Complex pow ( Complex const &, double );Complex pow ( double , Complex const & );Complex pow ( Complex const &, int );double real ( Complex const & );Complex sin ( Complex const & );Complex sinh ( Complex const & );Complex sqrt ( Complex const & );Complex tan ( Complex const & );Complex tanh ( Complex const & );Complex Class 19
Complex abs()Synopsis:Semantics:Results:See Also:#include double abs( Complex const &num );The abs function computes the magnitude <strong>of</strong> num, which is equivalent to the length (magnitude) <strong>of</strong> thevector when the num is represented in polar coordinates.The abs function returns the magnitude <strong>of</strong> num.arg, norm, polar20 Complex Class
Complex acos()Synopsis:Semantics:Results:See Also:#include Complex acos( Complex const &num );The acos function computes the arccosine <strong>of</strong> num.The acos function returns the arccosine <strong>of</strong> num.asin, atan, cosComplex Class 21
Complex acosh()Synopsis:Semantics:Results:See Also:#include Complex acosh( Complex const &num );The acosh function computes the inverse hyperbolic cosine <strong>of</strong> num.The acosh function returns the inverse hyperbolic cosine <strong>of</strong> num.asinh, atanh, cosh22 Complex Class
Complex arg()Synopsis:Semantics:Results:See Also:#include double arg( Complex const &num );The arg function computes the angle <strong>of</strong> the vector when the num is represented in polar coordinates.The angle has the same sign as the real component <strong>of</strong> the num. It is positive in the 1st and 2ndquadrants, and negative in the 3rd and 4th quadrants.The arg function returns the angle <strong>of</strong> the vector when the num is represented in polar coordinates.abs, norm, polarComplex Class 23
Complex asin()Synopsis:Semantics:Results:See Also:#include Complex asin( Complex const &num );The asin function computes the arcsine <strong>of</strong> num.The asin function returns the arcsine <strong>of</strong> num.acos, atan, sin24 Complex Class
Complex asinh()Synopsis:Semantics:Results:See Also:#include Complex asinh( Complex const &num );The asinh function computes the inverse hyperbolic sine <strong>of</strong> num.The asinh function returns the inverse hyperbolic sine <strong>of</strong> num.acosh, atanh, sinhComplex Class 25
Complex atan()Synopsis:Semantics:Results:See Also:#include Complex atan( Complex const &num );The atan function computes the arctangent <strong>of</strong> num.The atan function returns the arctangent <strong>of</strong> num.acos, asin, tan26 Complex Class
Complex atanh()Synopsis:Semantics:Results:See Also:#include Complex atanh( Complex const &num );The atanh function computes the inverse hyperbolic tangent <strong>of</strong> num.The atanh function returns the inverse hyperbolic tangent <strong>of</strong> num.acosh, asinh, tanhComplex Class 27
Complex::Complex()Synopsis:Semantics:Results:See Also:#include public:Complex::Complex();This form <strong>of</strong> the public Complex constructor creates a default Complex object with value zero forboth the real and imaginary components.This form <strong>of</strong> the public Complex constructor produces a default Complex object.~Complex, real, imag28 Complex Class
Complex::Complex()Synopsis:Semantics:Results:See Also:#include public:Complex::Complex( Complex const &num );This form <strong>of</strong> the public Complex constructor creates a Complex object with the same value as num.This form <strong>of</strong> the public Complex constructor produces a Complex object.~Complex, real, imagComplex Class 29
Complex::Complex()Synopsis:Semantics:Results:See Also:#include public:Complex::Complex( double real, double imag = 0.0 );This form <strong>of</strong> the public Complex constructor creates a Complex object with the real component set toreal and the imaginary component set to imag. If no imaginary component is specified, imag takes thedefault value <strong>of</strong> zero.This form <strong>of</strong> the public Complex constructor produces a Complex object.~Complex, real, imag30 Complex Class
Complex::~Complex()Synopsis:Semantics:Results:See Also:#include public:Complex::~Complex();The public ~Complex destructor destroys the Complex object. The call to the public ~Complexdestructor is inserted implicitly by the compiler at the point where the Complex object goes out <strong>of</strong>scope.The Complex object is destroyed.ComplexComplex Class 31
Complex conj()Synopsis:Semantics:Results:#include Complex conj( Complex const &num );The conj function computes the conjugate <strong>of</strong> num. The conjugate consists <strong>of</strong> the unchanged realcomponent, and the negative <strong>of</strong> the imaginary component.The conj function returns the conjugate <strong>of</strong> num.32 Complex Class
Complex cos()Synopsis:Semantics:Results:See Also:#include Complex cos( Complex const &num );The cos function computes the cosine <strong>of</strong> num.The cos function returns the cosine <strong>of</strong> num.acos, sin, tanComplex Class 33
Complex cosh()Synopsis:Semantics:Results:See Also:#include Complex cosh( Complex const &num );The cosh function computes the hyperbolic cosine <strong>of</strong> num.The cosh function returns the hyperbolic cosine <strong>of</strong> num.acosh, sinh, tanh34 Complex Class
Complex exp()Synopsis:Semantics:Results:See Also:#include Complex exp( Complex const &num );The exp function computes the value <strong>of</strong> e raised to the power num.The exp function returns the value <strong>of</strong> e raised to the power num.log, log10, pow, sqrtComplex Class 35
Complex::imag()Synopsis:Semantics:Results:See Also:#include public:double Complex::imag();The imag public member function extracts the imaginary component <strong>of</strong> the Complex object.The imag public member function returns the imaginary component <strong>of</strong> the Complex object.imag, realComplex::real36 Complex Class
Complex imag()Synopsis:Semantics:Results:See Also:#include double imag( Complex const &num );The imag function extracts the imaginary component <strong>of</strong> num.The imag function returns the imaginary component <strong>of</strong> num.realComplex::imag, realComplex Class 37
Complex log()Synopsis:Semantics:Results:See Also:#include Complex log( Complex const &num );The log function computes the natural, or base e, logarithm <strong>of</strong> num.The log function returns the natural, or base e, logarithm <strong>of</strong> num.exp, log10, pow, sqrt38 Complex Class
Complex log10()Synopsis:Semantics:Results:See Also:#include Complex log10( Complex const &num );The log10 function computes the base 10 logarithm <strong>of</strong> num.The log10 function returns the base 10 logarithm <strong>of</strong> num.exp, log, pow, sqrtComplex Class 39
Complex norm()Synopsis:Semantics:Results:See Also:#include double norm( Complex const &num );The norm function computes the square <strong>of</strong> the magnitude <strong>of</strong> num, which is equivalent to the square <strong>of</strong>the length (magnitude) <strong>of</strong> the vector when num is represented in polar coordinates.The norm function returns the square <strong>of</strong> the magnitude <strong>of</strong> num.arg, polar40 Complex Class
Complex operator !=()Synopsis:Semantics:#include int operator !=( Complex const &num1, Complex const &num2 );int operator !=( Complex const &num1, double num2 );int operator !=( double num1, Complex const &num2 );The operator != function compares num1 and num2 for inequality. At least one <strong>of</strong> the parametersmust be a Complex object for this function to be called.Two Complex objects are not equal if either <strong>of</strong> their corresponding real or imaginary components arenot equal.If the operator != function is used with a Complex object and an object <strong>of</strong> any other built-innumeric type, the non- Complex object is converted to a double and the second or third form <strong>of</strong> theoperator != function is used.Results:The operator != function returns a non-zero value if num1 is not equal to num2, otherwise zero isreturned.See Also: operator ==Complex Class 41
Complex operator *()Synopsis:Semantics:#include Complex operator *( Complex const &num1, Complex const &num2 );Complex operator *( Complex const &num1, double num2 );Complex operator *( double num1, Complex const &num2 );The operator * function is used to multiply num1 by num2 yielding a Complex object.The first operator * function multiplies two Complex objects.The second operator * function multiplies a Complex object and a floating-point value. In effect,the real and imaginary components <strong>of</strong> the Complex object are multiplied by the floating-point value.The third operator * function multiplies a floating-point value and a Complex object. In effect,the real and imaginary components <strong>of</strong> the Complex object are multiplied by the floating-point value.If the operator * function is used with a Complex object and an object <strong>of</strong> any other built-innumeric type, the non- Complex object is converted to a double and the second or third form <strong>of</strong> theoperator * function is used.Results:The operator * function returns a Complex object that is the product <strong>of</strong> num1 and num2.See Also: operator +, operator -, operator /Complex::operator *=42 Complex Class
Complex::operator *=()Synopsis:Semantics:#include public:Complex &Complex::operator *=( Complex const &num );Complex &Complex::operator *=( double num );The operator *= public member function is used to multiply the num argument into the Complexobject.The first form <strong>of</strong> the operator *= public member function multiplies the Complex object by theComplex parameter.The second form <strong>of</strong> the operator *= public member function multiplies the real and imaginarycomponents <strong>of</strong> the Complex object by num.A call to the operator *= public member function where num is any <strong>of</strong> the other built-in numerictypes, causes num to be promoted to double and the second form <strong>of</strong> the operator *= publicmember function to be used.Results:The operator *= public member function returns a reference to the target <strong>of</strong> the assignment.See Also: operator *Complex::operator +=, operator -=, operator /=, operator =Complex Class 43
Complex::operator +()Synopsis:Semantics:Results:#include public:Complex Complex::operator +();The unary operator + public member function is provided for completeness. It performs nooperation on the Complex object.The unary operator + public member function returns a Complex object with the same value asthe original Complex object.See Also: operator +Complex::operator +=, operator -44 Complex Class
Complex operator +()Synopsis:Semantics:#include Complex operator +( Complex const &num1, Complex const &num2 );Complex operator +( Complex const &num1, double num2 );Complex operator +( double num1, Complex const &num2 );The operator + function is used to add num1 to num2 yielding a Complex object.The first operator + function adds two Complex objects.The second operator + function adds a Complex object and a floating-point value. In effect, thefloating-point value is added to the real component <strong>of</strong> the Complex object.The third operator + function adds a floating-point value and a Complex object. In effect, thefloating-point value is added to the real component <strong>of</strong> the Complex object.If the operator + function is used with a Complex object and an object <strong>of</strong> any other built-innumeric type, the non- Complex object is converted to a double and the second or third form <strong>of</strong> theoperator + function is used.Results:The operator + function returns a Complex object that is the sum <strong>of</strong> num1 and num2.See Also: operator *, operator -, operator /Complex::operator +, operator +=Complex Class 45
Complex::operator +=()Synopsis:Semantics:#include public:Complex &Complex::operator +=( Complex const &num );Complex &Complex::operator +=( double num );The operator += public member function is used to add num to the value <strong>of</strong> the Complex object.The second form <strong>of</strong> the operator += public member function adds num to the real component <strong>of</strong> theComplex object.A call to the operator += public member function where num is any <strong>of</strong> the other built-in numerictypes, causes num to be promoted to double and the second form <strong>of</strong> the operator += publicmember function to be used.Results:The operator += public member function returns a reference to the target <strong>of</strong> the assignment.See Also: operator +Complex::operator *=, operator +, operator /=, operator -=, operator =46 Complex Class
Complex::operator -()Synopsis:Semantics:Results:#include public:Complex Complex::operator -();The unary operator - public member function yields a Complex object with the real andimaginary components having the same magnitude as those <strong>of</strong> the original object, but with oppositesign.The unary operator - public member function returns a Complex object with the same magnitudeas the original Complex object and with opposite sign.See Also: operator -Complex::operator +, operator -=Complex Class 47
Complex operator -()Synopsis:Semantics:#include Complex operator -( Complex const &num1, Complex const &num2 );Complex operator -( Complex const &num1, double num2 );Complex operator -( double num1, Complex const &num2 );The operator - function is used to subtract num2 from num1 yielding a Complex object.The first operator - function computes the difference between two Complex objects.The second operator - function computes the difference between a Complex object and afloating-point value. In effect, the floating-point value is subtracted from the real component <strong>of</strong> theComplex object.The third operator - function computes the difference between a floating-point value and aComplex object. In effect, the real component <strong>of</strong> the result is num1 minus the real component <strong>of</strong> num2:CONT, and the imaginary component <strong>of</strong> the result is the negative <strong>of</strong> the imaginary component <strong>of</strong>num2.If the operator - function is used with a Complex object and an object <strong>of</strong> any other built-innumeric type, the non- Complex object is converted to a double and the second or third form <strong>of</strong> theoperator - function is used.Results:The operator - function returns a Complex object that is the difference between num1 and num2.See Also: operator *, operator +, operator /Complex::operator -, operator -=48 Complex Class
Complex::operator -=()Synopsis:Semantics:#include public:Complex &Complex::operator -=( Complex const &num );Complex &Complex::operator -=( double num );The operator -= public member function is used to subtract num from the value <strong>of</strong> the Complexobject. The second form <strong>of</strong> the operator -= public member function subtracts num from the realcomponent <strong>of</strong> the *obj..A call to the operator -= public member function where num is any <strong>of</strong> the other built-in numerictypes, causes num to be promoted to double and the second form <strong>of</strong> the operator -= publicmember function to be used.Results:The operator -= public member function returns a reference to the target <strong>of</strong> the assignment.See Also: operator -Complex::operator *=, operator +=, operator -, operator /=, operator =Complex Class 49
Complex operator /()Synopsis:Semantics:#include Complex operator /( Complex const &num1, Complex const &num2 );Complex operator /( Complex const &num1, double num2 );Complex operator /( double num1, Complex const &num2 );The operator / function is used to divide num1 by num2 yielding a Complex object.The first operator / function divides two Complex objects.The second operator / function divides a Complex object by a floating-point value. In effect, thereal and imaginary components <strong>of</strong> the complex number are divided by the floating-point value.The third operator / function divides a floating-point value by a Complex object. Conceptually,the floating-point value is converted to a Complex object and then the division is done.If the operator / function is used with a Complex object and an object <strong>of</strong> any other built-innumeric type, the non- Complex object is converted to a double and the second or third form <strong>of</strong> theoperator / function is used.Results:The operator / function returns a Complex object that is the quotient <strong>of</strong> num1 divided by num2.See Also: operator *, operator +, operator -Complex::operator /=50 Complex Class
Complex::operator /=()Synopsis:Semantics:#include public:Complex &Complex::operator /=( Complex const &num );Complex &Complex::operator /=( double num );The operator /= public member function is used to divide the Complex object by num. Thesecond form <strong>of</strong> the operator /= public member function divides the real and imaginary components<strong>of</strong> the Complex object by num.A call to the operator /= public member function where num is any <strong>of</strong> the other built-in numerictypes, causes num to be promoted to double and the second form <strong>of</strong> the operator /= publicmember function to be used.Results:The operator /= public member function returns a reference to the target <strong>of</strong> the assignment.See Also: operator /Complex::operator *=, operator +=, operator -=, operator =Complex Class 51
Complex operator
Complex::operator =()Synopsis:Semantics:#include public:Complex &Complex::operator =( Complex const &num );Complex &Complex::operator =( double num );The operator = public member function is used to set the value <strong>of</strong> the Complex object to num.The first assignment operator copies the value <strong>of</strong> num into the Complex object.The second assignment operator sets the real component <strong>of</strong> the Complex object to num and theimaginary component to zero.A call to the operator = public member function where num is any <strong>of</strong> the other built-in numerictypes, causes num to be promoted to double and the second form <strong>of</strong> the operator = publicmember function to be used.Results:The operator = public member function returns a reference to the target <strong>of</strong> the assignment.See Also: Complex::operator *=, operator +=, operator -=, operator /=Complex Class 53
Complex operator ==()Synopsis:Semantics:#include int operator ==( Complex const &num1, Complex const &num2 );int operator ==( Complex const &num1, double num2 );int operator ==( double num1, Complex const &num2 );The operator == function compares num1 and num2 for equality. At least one <strong>of</strong> the argumentsmust be a Complex object for this function to be called.Two Complex objects are equal if their corresponding real and imaginary components are equal.If the operator == function is used with a Complex object and an object <strong>of</strong> any other built-innumeric type, the non- Complex object is converted to a double and the second or third form <strong>of</strong> theoperator == function is used.Results:The operator == function returns a non-zero value if num1 is equal to num2, otherwise zero isreturned.See Also: operator !=54 Complex Class
Complex operator >>()Synopsis:Semantics:#include friend istream &operator >>( istream &strm, Complex &num );The operator >> function is used to read a Complex object from an I/O stream. A valid complexvalue is <strong>of</strong> one <strong>of</strong> the following forms:(real,imag)real,imag(real)If the imaginary portion is omitted, zero is assumed.While reading a Complex object, whitespace is ignored before and between the various components <strong>of</strong>the number if the ios::skipws bit is set in ios::fmtflags.Results:See Also:The operator >> function returns a reference to strm. num contains the value read from strm onsuccess, otherwise it is unchanged.istreamComplex Class 55
Complex polar()Synopsis:Semantics:Results:See Also:#include Complex polar( double mag, double angle = 0.0 );The polar function converts mag and angle (polar coordinates) into a complex number. The angle isoptional and defaults to zero if it is unspecified.The polar function returns a Complex object that is mag and angle interpreted as polar coordinates.abs, arg, norm56 Complex Class
Complex pow()Synopsis:Semantics:Results:See Also:#include Complex pow( Complex const &num, Complex const &exp );Complex pow( Complex const &num, double exp );Complex pow( double num, Complex const &exp );Complex pow( Complex const &num, int exp );The pow function computes num raised to the power exp. The various forms are provided to minimizethe amount <strong>of</strong> floating-point calculation performed.The pow function returns a Complex object that is num raised to the power a Complex object that isexp.exp, log, log10, sqrtComplex Class 57
Complex::real()Synopsis:Semantics:Results:See Also:#include public:double Complex::real();The real public member function extracts the real component <strong>of</strong> the Complex object.The real public member function returns the real component <strong>of</strong> the Complex object.imag, realComplex::imag58 Complex Class
Complex real()Synopsis:Semantics:Results:See Also:#include double real( Complex const &num );The real function extracts the real component <strong>of</strong> num.The real function returns the real component <strong>of</strong> num.imagComplex::imag, realComplex Class 59
Complex sin()Synopsis:Semantics:Results:See Also:#include Complex sin( Complex const &num );The sin function computes the sine <strong>of</strong> num.The sin function returns the sine <strong>of</strong> num.asin, cos, tan60 Complex Class
Complex sinh()Synopsis:Semantics:Results:See Also:#include Complex sinh( Complex const &num );The sinh function computes the hyperbolic sine <strong>of</strong> num.The sinh function returns the hyperbolic sine <strong>of</strong> num.asinh, cosh, tanhComplex Class 61
Complex sqrt()Synopsis:Semantics:Results:See Also:#include Complex sqrt( Complex const &num );The sqrt function computes the square root <strong>of</strong> num.The sqrt function returns the square root <strong>of</strong> num.exp, log, log10, pow62 Complex Class
Complex tan()Synopsis:Semantics:Results:See Also:#include Complex tan( Complex const &num );The tan function computes the tangent <strong>of</strong> num.The tan function returns the tangent <strong>of</strong> num.atan, cos, sinComplex Class 63
Complex tanh()Synopsis:Semantics:Results:See Also:#include Complex tanh( Complex const &num );The tanh function computes the hyperbolic tangent <strong>of</strong> num.The tanh function returns the hyperbolic tangent <strong>of</strong> num.atanh, cosh, sinh64 Complex Class
8 Container Exception ClassesThis chapter describes exception handling for the container classes.Container Exception Classes 65
WCExceptDeclared:wcexcept.hThe WCExcept class provides the exception handling for the container classes. If you have compiledyour code with exception handling enabled, the C++ exception processing can be used to catch errors.Your source file must be compiled with the exception handling compile switch for C++ exceptionprocessing to occur. The container classes will attempt to set the container object into a reasonable stateif there is an error and exception handling is not enabled, or if the trap for the specific error has not beenenabled by your program.By default, no exception traps are enabled and no exceptions will be thrown. Exception traps areenabled by setting the exception state with the exceptions member function.The wcexcept.h header file is included by the header files for each <strong>of</strong> the container classes. There isnormally no need to explicitly include the wcexcept.h header file, but no errors will result if it isincluded. This class is inherited as a base class for each <strong>of</strong> the containers. You do not need to derivefrom it directly.The WCListExcept class (formally used by the list container classes) has been replaced by theWCExcept class. A typedef <strong>of</strong> the WCListExcept class to the WCExcept class and thewclist_state type to the wc_state type provide backward compatability with previous versions<strong>of</strong> the list containers.Public EnumerationsThe following enumeration typedefs are declared in the public interface:typedef int wc_state;Public Member FunctionsThe following public member functions are declared:WCExcept();virtual ~WCExcept();wc_state exceptions() const;wc_state exceptions( wc_state );66 Container Exception Classes
WCExcept::WCExcept()Synopsis:Semantics:#include public:WCExcept();This form <strong>of</strong> the public WCExcept constructor creates an WCExcept object.The public WCExcept constructor is used implicitly by the compiler when it generates a constructorfor a derived class. It is automatically used by the list container classes, and should not be required inany user derived classes.Results:See Also:The public WCExcept constructor produces an initialized WCExcept object with no exception trapsenabled.~WCExceptContainer Exception Classes 67
WCExcept::~WCExcept()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCExcept();The public ~WCExcept destructor does not do anything explicit. The call to the public ~WCExceptdestructor is inserted implicitly by the compiler at the point where the object derived from WCExceptgoes out <strong>of</strong> scope.The object derived from WCExcept is destroyed.WCExcept68 Container Exception Classes
WCExcept::exceptions()Synopsis:Semantics:Results:#include public:wc_state exceptions() const;wc_state exceptions( wc_state set_flags );The exceptions public member function queries and/or sets the bits that control which exceptionsare enabled for the list class. Each bit corresponds to an exception, and is set if the exception isenabled. The first form <strong>of</strong> the exceptions public member function returns the current settings <strong>of</strong> theexception bits. The second form <strong>of</strong> the function sets the exception bits to those specified by set_flags.The current exception bits are returned. If a new set <strong>of</strong> bits are being set, the returned value is the oldset <strong>of</strong> exception bits.Container Exception Classes 69
WCExcept::wc_stateSynopsis:Semantics:#include public:enum wcstate {all_fine = 0x0000, // - no errorscheck_none = all_fine,// - throw no exceptionsnot_empty = 0x0001, // - container not emptyindex_range = 0x0002, // - index is out <strong>of</strong> rangeempty_container= 0x0004, // - empty container errorout_<strong>of</strong>_memory = 0x0008, // - allocation failedresize_required= 0x0010, // - request needs resizenot_unique = 0x0020, // - adding duplicatezero_buckets = 0x0040, // - resizing hash to zero// value to use to check for all errorscheck_all = (not_empty|index_range|empty_container|out_<strong>of</strong>_memory|resize_required|not_unique|zero_buckets)};typedef int wc_state;The type WCExcept::wcstate is a set <strong>of</strong> bits representing the current state <strong>of</strong> the container object.The WCExcept::wc_state member typedef represents the same set <strong>of</strong> bits, but uses an int torepresent the values, thereby avoiding problems made possible by the compiler’s ability to use smallertypes for enumerations. All uses <strong>of</strong> these bits should use the WCExcept::wc_state membertypedef.The bit values defined by the WCExcept::wc_state member typedef can be read and set by theexceptions member function, which is also used to control exception handling.The WCExcept::not_empty bit setting traps the destruction <strong>of</strong> a container when the container hasat one or more entries. If this error is not trapped, memory may not be properly released back to thesystem.The WCExcept::index_range state setting traps an attempt to access a container item by an indexvalue that is either not positive or is larger than the index <strong>of</strong> the last item in the container.The WCExcept::empty_container bit setting traps an attempt to perform and invalid operationon a container with no entries.The WCExcept::out_<strong>of</strong>_memory bit setting traps any container class allocation failures. If thisexception is not enabled, the operation in which the allocation failed will return a FALSE (zero) value.Container class copy constructors and assignment operators can also throw this exception, and if notenabled incomplete copies may result.The WCExcept::resize_required bit setting traps any vector operations which cannot beperformed unless the vector is resized to a larger size. If this exception is not enabled, the vector classwill attempt an appropriate resize when necessary for an operation.The WCExcept::not_unique bit setting traps an attempt to add a duplicate value to a set container,or a duplicate key to a dictionary container. The duplicate value is not added to the container objectregardless <strong>of</strong> the exception trap state.The WCExcept::zero_buckets bit setting traps an attempt to resize <strong>of</strong> hash container to have zerobuckets. No resize is performed whether or not the exception is enabled.70 Container Exception Classes
WCIterExceptDeclared:wcexcept.hThe WCIterExcept class provides the exception handling for the container iterators. If you havecompiled your code with exception handling enabled, the C++ exception processing can be used tocatch errors. Your source file must be compiled with the exception handling compile switch for C++exception processing to occur. The iterators will attempt to set the class into a reasonable state if thereis an error and exception handling is not enabled, or if the trap for the specific error has not beenenabled by your program.By default, no exception traps are enabled and no exceptions will be thrown. Exception traps areenabled by setting the exception state with the exceptions member function.The wcexcept.h header file is included by the header files for each <strong>of</strong> the iterator classes. There isnormally no need to explicitly include the wcexcept.h header file, but no errors will result if it isincluded. This class is inherited as part <strong>of</strong> the base construction for each <strong>of</strong> the iterators. You do notneed to derive from it directly.Public EnumerationsThe following enumeration typedefs are declared in the public interface:typedef int wciter_state;Public Member FunctionsThe following public member functions are declared:WCIterExcept();virtual ~WCIterExcept();wciter_state exceptions() const;wciter_state exceptions( wciter_state );Container Exception Classes 71
WCIterExcept::WCIterExcept()Synopsis:Semantics:#include public:WCIterExcept();This form <strong>of</strong> the public WCIterExcept constructor creates an WCIterExcept object.The public WCIterExcept constructor is used implicitly by the compiler when it generates aconstructor for a derived class.Results:See Also:The public WCIterExcept constructor produces an initialized WCIterExcept object with noexception traps enabled.~WCIterExcept72 Container Exception Classes
WCIterExcept::~WCIterExcept()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCIterExcept();The public ~WCIterExcept destructor does not do anything explicit. The call to the public~WCIterExcept destructor is inserted implicitly by the compiler at the point where the objectderived from WCIterExcept goes out <strong>of</strong> scope.The object derived from WCIterExcept is destroyed.WCIterExceptContainer Exception Classes 73
WCIterExcept::exceptions()Synopsis:Semantics:Results:#include public:wciter_state exceptions() const;wciter_state exceptions( wciter_state set_flags );The exceptions public member function queries and/or sets the bits that control which exceptionsare enabled for the iterator class. Each bit corresponds to an exception, and is set if the exception isenabled. The first form <strong>of</strong> the exceptions public member function returns the current settings <strong>of</strong> theexception bits. The second form <strong>of</strong> the function sets the exception bits to those specified by set_flags.The current exception bits are returned. If a new set <strong>of</strong> bits are being set, the returned value is the oldset <strong>of</strong> exception bits.74 Container Exception Classes
WCIterExcept::wciter_stateSynopsis:Semantics:#include public:enum wciterstate {all_fine = 0x0000, // - no errorscheck_none = all_fine,// - disable all exceptionsundef_iter = 0x0001, // - position is undefinedundef_item = 0x0002, // - iterator item is undefinediter_range = 0x0004, // - advance value is bad// value to use to check for all errorscheck_all= (undef_iter|undef_item|iter_range)};typedef int wciter_state;The type WCIterExcept::wciterstate is a set <strong>of</strong> bits representing the current state <strong>of</strong> theiterator. The WCIterExcept::wciter_state member typedef represents the same set <strong>of</strong> bits, butuses an int to represent the values, thereby avoiding problems made possible by the compiler’s abilityto use smaller types for enumerations. All uses <strong>of</strong> these bits should use theWCIterExcept::wciter_state member typedef.The bit values defined by the WCIterExcept::wciter_state member typedef can be read andset by the member function exceptions, which is used to control exception handling.The WCIterExcept::undef_iter bit setting traps the use <strong>of</strong> the iterator when the position withinthe container object is undefined. Trying to operate on an iterator with no associated container object,increment an iterator which is after the last element, or decrement an iterator positioned before the firstelement is an undefined operation.The WCIterExcept::undef_item bit setting traps an attempt to obtain the current element <strong>of</strong> theiterator when the iterator has no associated container object, or is positioned either before or after thecontainer elements. The undef_item exception can be thrown only by the key and valuedictionary iterator member functions, and the current member function for non-dictionary iterators.The WCIterExcept::iter_range bit setting traps an attempt to use a iteration count value thatwould place the iterator more than one element past the end or before the beginning <strong>of</strong> the containerelements. The iter_range exception can be thrown only by the operator += and operator-= operators.Container Exception Classes 75
WCIterExcept::wciter_state76 Container Exception Classes
9 Container Allocators and DeallocatorsExample#include #include #include #include #include #include #pragma warning 549 9const int ElemsPerBlock = 50;//// Simple block allocation class. Allocate blocks for ElemsPerBlock// elements, and use part <strong>of</strong> the block for each <strong>of</strong> the next ElemsPerBlock// allocations, incrementing the number allocated elements. Repeat getting// more blocks as needed.//// Store the blocks in an intrusive single linked list.//// On a element deallocation, assume we allocated the memory and just// decrement the count <strong>of</strong> allocated elements. When the count gets to zero,// free all allocated blocks//// This implementation assumes size<strong>of</strong>( char ) == 1//class BlockAlloc {private:// the size <strong>of</strong> elements (in bytes)unsigned elem_size;// number <strong>of</strong> elements allocatedunsigned num_allocated;// free space <strong>of</strong> this number <strong>of</strong> elements available in first blockunsigned num_free_in_block;// list <strong>of</strong> blocks used to store elements (block are chunks <strong>of</strong> memory,// pointed by (char *) pointers.WCPtrSList block_list;// pointer to the first block in the listchar *curr_block;public:inline BlockAlloc( unsigned size ): elem_size( size ), num_allocated( 0 ), num_free_in_block( 0 ) {};inline BlockAlloc() {block_list.clearAndDestroy();};// get memory for an element using block allocationvoid *allocator( size_t elem_size );};// free memory for an element using block allocation and deallocationvoid deallocator( void *old_ptr, size_t elem_size );Container Allocators and Deallocators 77
WCIterExcept::wciter_statevoid *BlockAlloc::allocator( size_t size ) {// need a new block to perform allocationif( num_free_in_block == 0 ) {// allocate memory for ElemsPerBlock elementscurr_block = new char[ size * ElemsPerBlock ];if( curr_block == 0 ) {// allocation failedreturn( 0 );}// add new block to beginning <strong>of</strong> listif( !block_list.insert( curr_block ) ) {// allocation <strong>of</strong> list element faileddelete( curr_block );return( 0 );}num_free_in_block = ElemsPerBlock;}}// curr block points to a block <strong>of</strong> memory with some free memorynum_allocated++;num_free_in_block--;// return pointer to a free part <strong>of</strong> the block, starting at the end// <strong>of</strong> the blockreturn( curr_block + num_free_in_block * size );void BlockAlloc::deallocator( void *, size_t ) {// just decrement the count// don’t free anything until all elements are deallocatednum_allocated--;if( num_allocated == 0 ) {// all the elements allocated BlockAlloc object have now been// deallocated, free all the blocksblock_list.clearAndDestroy();num_free_in_block = 0;}}const unsigned NumTestElems = 200;// array with random elementsstatic unsigned test_elems[ NumTestElems ];static void fill_test_elems() {for( int i = 0; i < NumTestElems; i++ ) {test_elems[ i ] = rand();}}void test_isv_list();void test_val_list();void test_val_skip_list();void main() {fill_test_elems();}test_isv_list();test_val_list();test_val_skip_list();// An intrusive list class78 Container Allocators and Deallocators
Container Allocators and Deallocatorsclass isvInt : public WCSLink {public:static BlockAlloc memory_manage;int data;isvInt( int datum ) : data( datum ) {};void *operator new( size_t size ) {return( memory_manage.allocator( size ) );};};void operator delete( void *old, size_t size ) {memory_manage.deallocator( old, size );};// define static member dataBlockAlloc isvInt::memory_manage( size<strong>of</strong>( isvInt ) );void test_isv_list() {WCIsvSList list;for( int i = 0; i < NumTestElems; i++ ) {list.insert( new isvInt( test_elems[ i ] ) );}}WCIsvSListIter iter( list );while( ++iter ) {cout data
WCIterExcept::wciter_stateconst int two_ptr_size = WCValSkipListItemSize( int, 2 );static BlockAlloc one_ptr_manager( one_ptr_size );static BlockAlloc two_ptr_manager( two_ptr_size );static void *val_skip_list_alloc( size_t size ) {switch( size ) {case one_ptr_size:return( one_ptr_manager.allocator( size ) );case two_ptr_size:return( two_ptr_manager.allocator( size ) );default:return( new char[ size ] );}}static void val_skip_list_dealloc( void *old, size_t size ) {switch( size ) {case one_ptr_size:one_ptr_manager.deallocator( old, size );break;case two_ptr_size:two_ptr_manager.deallocator( old, size );break;default:delete old;break;}}// test WCValSkipListvoid test_val_skip_list() {WCValSkipList skiplist( WCSKIPLIST_PROB_QUARTER, WCDEFAULT_SKIPLIST_MAX_PTRS, &val_skip_list_alloc, &val_skip_list_dealloc );for( int i = 0; i < NumTestElems; i++ ) {skiplist.insert( test_elems[ i ] );}}WCValSkipListIter iter( skiplist );while( ++iter ) {cout
10 Hash ContainersThis chapter describes hash containers.Hash Containers 81
WCPtrHashDictDeclared:wchash.hThe WCPtrHashDict class is a templated class used to store objects in a dictionary.Dictionaries store values with an associated key, which may be <strong>of</strong> any type. One example <strong>of</strong> adictionary used in everyday life is the phone book. The phone numbers are the data values, and thecustomer name is the key. An example <strong>of</strong> a specialized dictionary is a vector, where the key value is theinteger index.As an element is looked up or inserted into the dictionary, the associated key is hashed. Hashingconverts the key into a numeric index value which is used to locate the value. The storage areareferenced by the hash value is usually called a bucket. If more than one key results in the same hash,the values associated with the keys are placed in a list stored in the bucket. The equality operator <strong>of</strong> thekey’s type is used to locate the key-value pairs.In the description <strong>of</strong> each member function, the text Key is used to indicate the template parameterdefining the type <strong>of</strong> the indices pointed to by the pointers stored in the dictionary. The text Value isused to indicate the template parameter defining the type <strong>of</strong> the data pointed to by the pointers stored inthe dictionary.The constructor for the WCPtrHashDict class requires a hashing function, whichgiven a reference to Key, returns an unsigned value. The returned value modulo the number <strong>of</strong>buckets determines the bucket into which the key-value pair will be located. The return values <strong>of</strong> thehash function can be spread over the entire range <strong>of</strong> unsigned numbers. The hash function return valuemust be the same for values which are equivalent by the equivalence operator for Key.Note that pointers to the key values are stored in the dictionary. Destructors are not called on the keyspointed to. The key values pointed to in the dictionary should not be changed such that the equivalenceto the old value is modified.The WCExcept class is a base class <strong>of</strong> the WCPtrHashDict class and provides theexceptions member function. This member function controls the exceptions which can be thrownby the WCPtrHashDict object. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> KeyThe WCPtrHashDict class requires Key to have:A well defined equivalence operator with constant parameters( int operator ==( const Key & ) const ).Public Member FunctionsThe following member functions are declared in the public interface:WCPtrHashDict( unsigned (*hash_fn)( const Key & ), unsigned =WC_DEFAULT_HASH_SIZE );WCPtrHashDict( unsigned (*hash_fn)( const Key & ), unsigned =WC_DEFAULT_HASH_SIZE, void * (*user_alloc)( size_t size ), void(*user_dealloc)( void *old, size_t size ) );WCPtrHashDict( const WCPtrHashDict & );virtual ~WCPtrHashDict();static unsigned bitHash( const void *, size_t );unsigned buckets() const;void clear();82 Hash Containers
WCPtrHashDictvoid clearAndDestroy();int contains( const Key * ) const;unsigned entries() const;Value * find( const Key * ) const;Value * findKeyAndValue( const Key *, Key * & ) const;void forAll( void (*user_fn)( Key *, Value *, void * ) , void * );int insert( Key *, Value * );int isEmpty() const;Value * remove( const Key * );void resize( unsigned );Public Member OperatorsThe following member operators are declared in the public interface:Value * & operator []( const Key & );const Value * & operator []( const Key & ) const;WCPtrHashDict & operator =( const WCPtrHashDict & );int operator ==( const WCPtrHashDict & ) const;Hash Containers 83
WCPtrHashDict::WCPtrHashDict()Synopsis:Semantics:#include public:WCPtrHashDict( unsigned (*hash_fn)( const Key & ),unsigned = WC_DEFAULT_HASH_SIZE );The public WCPtrHashDict constructor creates anWCPtrHashDict object with no entries and with the number <strong>of</strong> buckets in the secondoptional parameter, which defaults to the constant WC_DEFAULT_HASH_SIZE (currently defined as101). The number <strong>of</strong> buckets specified must be greater than zero, and will be forced to at least one. Ifthe hash dictionary object can be created, but an allocation failure occurs when creating the buckets, thetable will be created with zero buckets. If the out_<strong>of</strong>_memory exception is enabled, then attemptingto insert into a hash table with zero buckets with throw an out_<strong>of</strong>_memory error.The hash function hash_fn is used to determine which bucket each key-value pair will be assigned. Ifno hash function exists, the static member function bitHash is available to help create one.Results:See Also:The public WCPtrHashDict constructor creates an initializedWCPtrHashDict object with the specified number <strong>of</strong> buckets and hash function.~WCPtrHashDict, bitHash, WCExcept::out_<strong>of</strong>_memory84 Hash Containers
WCPtrHashDict::WCPtrHashDict()Synopsis:Semantics:#include public:WCPtrHashDict( unsigned (*hash_fn)( const Key & ),unsigned = WC_DEFAULT_HASH_SIZE,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thehash dictionary. The semantics <strong>of</strong> this constructor are the same as the constructor without the memorymanagement functions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a hash dictionary. To determine the size <strong>of</strong> the objects that the memorymanagement functions will be required to allocate and free, the following macro may be used:WCPtrHashDictItemSize( Key, Value )Results:See Also:The public WCPtrHashDict constructor creates an initializedWCPtrHashDict object with the specified number <strong>of</strong> buckets and hash function.~WCPtrHashDict, bitHash, WCExcept::out_<strong>of</strong>_memoryHash Containers 85
WCPtrHashDict::WCPtrHashDict()Synopsis:Semantics:Results:See Also:#include public:WCPtrHashDict( const WCPtrHashDict & );The public WCPtrHashDict constructor is the copy constructor for theWCPtrHashDict class. The new dictionary is created with the same number <strong>of</strong>buckets, hash function, all values or pointers stored in the dictionary, and the exception trap states. Ifthe hash dictionary object can be created, but an allocation failure occurs when creating the buckets, thetable will be created with zero buckets. If there is not enough memory to copy all <strong>of</strong> the values in thedictionary, then only some will be copied, and the number <strong>of</strong> entries will correctly reflect the numbercopied. If all <strong>of</strong> the elements cannot be copied, then the out_<strong>of</strong>_memory exception is thrown if it isenabled.The public WCPtrHashDict constructor creates anWCPtrHashDict object which is a copy <strong>of</strong> the passed dictionary.~WCPtrHashDict, operator =, WCExcept::out_<strong>of</strong>_memory86 Hash Containers
WCPtrHashDict::~WCPtrHashDict()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCPtrHashDict();The public ~WCPtrHashDict destructor is the destructor for theWCPtrHashDict class. If the number <strong>of</strong> dictionary elements is not zero and thenot_empty exception is enabled, the exception is thrown. Otherwise, the dictionary elements arecleared using the clear member function. The objects which the dictionary elements point to are notdeleted unless the clearAndDestroy member function is explicitly called before the destructor iscalled. The call to the public ~WCPtrHashDict destructor is inserted implicitly bythe compiler at the point where the WCPtrHashDict object goes out <strong>of</strong> scope.The public ~WCPtrHashDict destructor destroys anWCPtrHashDict object.clear, clearAndDestroy, WCExcept::not_emptyHash Containers 87
WCPtrHashDict::bitHash()Synopsis:Semantics:Results:See Also:#include public:static unsigned bitHash( void *, size_t );The bitHash public member function can be used to implement a hashing function for any type. Ahashing value is generated from the value stored for the number <strong>of</strong> specified bytes pointed to by the firstparameter.The bitHash public member function returns an unsigned value which can be used as the basis <strong>of</strong> auser defined hash function.WCPtrHashDict88 Hash Containers
WCPtrHashDict::buckets()Synopsis:Semantics:Results:See Also:#include public:unsigned buckets const;The buckets public member function is used to find the number <strong>of</strong> buckets contained in theWCPtrHashDict object.The buckets public member function returns the number <strong>of</strong> buckets in the dictionary.resizeHash Containers 89
WCPtrHashDict::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the dictionary so that it has no entries. The number<strong>of</strong> buckets remain unaffected. Objects pointed to by the dictionary elements are not deleted. Thedictionary object is not destroyed and re-created by this function, so the object destructor is not invoked.The clear public member function clears the dictionary to have no elements.See Also: ~WCPtrHashDict, clearAndDestroy, operator =90 Hash Containers
WCPtrHashDict::clearAndDestroy()Synopsis:Semantics:Results:See Also:#include public:void clearAndDestroy();The clearAndDestroy public member function is used to clear the dictionary and delete the objectspointed to by the dictionary elements. The dictionary object is not destroyed and re-created by thisfunction, so the dictionary object destructor is not invoked.The clearAndDestroy public member function clears the dictionary by deleting the objects pointedto by the dictionary elements.clearHash Containers 91
WCPtrHashDict::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Key * ) const;The contains public member function returns non-zero if an element with the specified key is storedin the dictionary, or zero if there is no equivalent element. Note that equivalence is based on theequivalence operator <strong>of</strong> the Key type.The contains public member function returns a non-zero value if the Key is found in the dictionary.find, findKeyAndValue92 Hash Containers
WCPtrHashDict::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to return the current number <strong>of</strong> elements stored in thedictionary.The entries public member function returns the number <strong>of</strong> elements in the dictionary.buckets, isEmptyHash Containers 93
WCPtrHashDict::find()Synopsis:Semantics:Results:See Also:#include public:Value * find( const Key * ) const;The find public member function is used to find an element with an equivalent key in the dictionary.If an equivalent element is found, a pointer to the element Value is returned. Zero is returned if theelement is not found. Note that equivalence is based on the equivalence operator <strong>of</strong> the Key type.The element equivalent to the passed key is located in the dictionary.findKeyAndValue94 Hash Containers
WCPtrHashDict::findKeyAndValue()Synopsis:Semantics:Results:See Also:#include public:Value * findKeyAndValue( const Key *,Key &, Value & ) const;The findKeyAndValue public member function is used to find an element in the dictionary with ankey equivalent to the first parameter. If an equivalent element is found, a pointer to the element Valueis returned. The reference to a Key passed as the second parameter is assigned the found element’s key.Zero is returned if the element is not found. Note that equivalence is based on the equivalence operator<strong>of</strong> the Key type.The element equivalent to the passed key is located in the dictionary.findKeyAndValueHash Containers 95
WCPtrHashDict::forAll()Synopsis:Semantics:#include public:void forAll(void (*user_fn)( Key *, Value *, void * ),void * );The forAll public member function causes the user supplied function to be invoked for everykey-value pair in the dictionary. The user function has the prototypevoid user_func( Key * key, Value * value, void * data );As the elements are visited, the user function is invoked with the Key and Value components <strong>of</strong> theelement passed as the first two parameters. The second parameter <strong>of</strong> the forAll function is passed asthe third parameter to the user function. This value can be used to pass any appropriate data from themain code to the user function.Results:See Also:The elements in the dictionary are all visited, with the user function being invoked for each one.find, findKeyAndValue96 Hash Containers
WCPtrHashDict::insert()Synopsis:Semantics:#include public:int insert( Key *, Value * );The insert public member function inserts a key and value into the dictionary, using the hashfunction on the key to determine to which bucket it should be stored. If allocation <strong>of</strong> the node to storethe key-value pair fails, then the out_<strong>of</strong>_memory exception is thrown if it is enabled. If theexception is not enabled, the insert will not be completed.At some point, the number <strong>of</strong> buckets initially selected may be too small for the number <strong>of</strong> elementsinserted. The resize <strong>of</strong> the dictionary can be controlled by the insertion mechanism by usingWCPtrHashDict as a base class, and providing an insert member function to do a resize whenappropriate. This insert could then call WCPtrHashDict::insert to insert the element. Note thatcopy constructors and assignment operators are not inherited in your class, but you can provide thefollowing inline definitions (assuming that the class inherited from WCPtrHashDict is namedMyHashDict):inline MyHashDict( const MyHashDict &orig ) : WCPtrHashDict( orig ) {};inline MyHashDict &operator=( const MyHashDict &orig ) {return( WCPtrHashDict::operator=( orig ) );}Results:See Also:The insert public member function inserts a key and value into the dictionary. If the insert issuccessful, a non-zero will returned. A zero will be returned if the insert fails.operator =, WCExcept::out_<strong>of</strong>_memoryHash Containers 97
WCPtrHashDict::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if the dictionary is empty.The isEmpty public member function returns zero if it contains at least one entry, non-zero if thedictionary is empty.buckets, entries98 Hash Containers
WCPtrHashDict::operator []()Synopsis:Semantics:Results:See Also:#include public:Value * & operator[]( const Key & );operator [] is the dictionary index operator. A reference to the object stored in the dictionary withthe given Key is returned. If no equivalent element is found, then a new key-value pair is created withthe specified Key value, and initialized with the default constructor. The returned reference can then beassigned to, so that insertions can be made with the operator. If an allocation error occurs whileinserting a new key-value pair, then the out_<strong>of</strong>_memory exception is thrown if it is enabled. If theexception is not enabled, then a reference to address zero will be returned. This will result in a run-timeerror on systems which trap address zero references.The operator [] public member function returns a reference to the element at the given key value.If the key does not exist, a reference to a created element is returned. The result <strong>of</strong> the operator may beassigned to.WCExcept::out_<strong>of</strong>_memoryHash Containers 99
WCPtrHashDict::operator []()Synopsis:Semantics:Results:See Also:#include public:Value * const & operator[]( const Key * ) const;operator [] is the dictionary index operator. A constant reference to the object stored in thedictionary with the given Key is returned. If no equivalent element is found, then the index_rangeexception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero willbe returned. This will result in a run-time error on systems which trap address zero references.The operator [] public member function returns a constant reference to the element at the givenkey value. The result <strong>of</strong> the operator may not be assigned to.WCExcept::index_range100 Hash Containers
WCPtrHashDict::operator =()Synopsis:Semantics:Results:See Also:#include public:WCPtrHashDict & operator =( const WCPtrHashDict & );The operator = public member function is the assignment operator for theWCPtrHashDict class. The left hand side dictionary is first cleared using theclear member function, and then the right hand side dictionary is copied. The hash function,exception trap states, and all <strong>of</strong> the dictionary elements are copied. If an allocation failure occurs whencreating the buckets, the table will be created with zero buckets, and the out_<strong>of</strong>_memory exceptionis thrown if it is enabled. If there is not enough memory to copy all <strong>of</strong> the values or pointers in thedictionary, then only some will be copied, and the out_<strong>of</strong>_memory exception is thrown if it isenabled. The number <strong>of</strong> entries will correctly reflect the number copied.The operator = public member function assigns the left hand side dictionary to be a copy <strong>of</strong> theright hand side.clear, WCExcept::out_<strong>of</strong>_memoryHash Containers 101
WCPtrHashDict::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCPtrHashDict & ) const;The operator == public member function is the equivalence operator for theWCPtrHashDict class. Two dictionary objects are equivalent if they are the sameobject and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side dictionary are the sameobject. A FALSE (zero) value is returned otherwise.102 Hash Containers
WCPtrHashDict::remove()Synopsis:Semantics:Results:#include public:Value * remove( const Key * );The remove public member function is used to remove the specified element from the dictionary. Ifan equivalent element is found, the pointer value is returned. Zero is returned if the element is notfound. Note that equivalence is based on the equivalence operator <strong>of</strong> the Key type.The element is removed from the dictionary if it found.Hash Containers 103
WCPtrHashDict::resize()Synopsis:Semantics:Results:See Also:#include public:void resize( unsigned );The resize public member function is used to change the number <strong>of</strong> buckets contained in thedictionary. If the new number is larger than the previous dictionary size, then the hash function will beused on all <strong>of</strong> the stored elements to determine which bucket they should be stored into. Entries are notdestroyed or created in the process <strong>of</strong> being moved. If there is not enough memory to resize thedictionary, the out_<strong>of</strong>_memory exception is thrown if it is enabled, and the dictionary will containthe number <strong>of</strong> buckets it contained before the resize. If the new number is zero, then thezero_buckets exception is thrown if it is enabled, and no resize will be performed. The dictionaryis guaranteed to contain the same number <strong>of</strong> entries after the resize.The dictionary is resized to the new number <strong>of</strong> buckets.WCExcept::out_<strong>of</strong>_memory, WCExcept::zero_buckets104 Hash Containers
WCPtrHash<strong>Table</strong>, WCPtrHashSetDeclared:wchash.hWCPtrHash<strong>Table</strong> and WCPtrHashSet classes are templated classes used to storeobjects in a hash. A hash saves objects in such a way as to make it efficient to locate and retrieve anelement. As an element is looked up or inserted into the hash, the value <strong>of</strong> the element is hashed.Hashing results in a numeric index which is used to locate the value. The storage area referenced by thehash value is usually called a bucket. If more than one element results in the same hash, the valueassociated with the hash is placed in a list stored in the bucket. A hash table allows more than one copy<strong>of</strong> an element that is equivalent, while the hash set allows only one copy. The equality operator <strong>of</strong> theelement’s type is used to locate the value.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type <strong>of</strong> the data pointed to by the pointers stored in the hash.The constructor for the WCPtrHash<strong>Table</strong> and WCPtrHashSet classes requires ahashing function, which given a reference to Type, returns an unsigned value. The returned valuemodulo the number <strong>of</strong> buckets determines the bucket into which the element will be located. The returnvalues <strong>of</strong> the hash function can be spread over the entire range <strong>of</strong> unsigned numbers. The hash functionreturn value must be the same for values which are equivalent by the equivalence operator for Type.Note that pointers to the elements are stored in the hash. Destructors are not called on the elementspointed to. The data values pointed to in the hash should not be changed such that the equivalence tothe old value is modified.The WCExcept class is a base class <strong>of</strong> the WCPtrHash<strong>Table</strong> andWCPtrHashSet classes and provides the exceptions member function. This memberfunction controls the exceptions which can be thrown by the WCPtrHash<strong>Table</strong> andWCPtrHashSet objects. No exceptions are enabled unless they are set by the exceptionsmember function.Requirements <strong>of</strong> TypeThe WCPtrHash<strong>Table</strong> and WCPtrHashSet classes requires Type to have:A well defined equivalence operator with constant parameters( int operator ==( const Type & ) const ).Public Member FunctionsThe following member functions are declared in the public interface:WCPtrHashSet( unsigned (*hash_fn)( const Type & ), unsigned =WC_DEFAULT_HASH_SIZE );WCPtrHashSet( unsigned (*hash_fn)( const Type & ), unsigned =WC_DEFAULT_HASH_SIZE, void * (*user_alloc)( size_t size ), void(*user_dealloc)( void *old, size_t size ) );WCPtrHashSet( const WCPtrHashSet & );virtual ~WCPtrHashSet();WCPtrHash<strong>Table</strong>( unsigned (*hash_fn)( const Type & ), unsigned =WC_DEFAULT_HASH_SIZE );WCPtrHash<strong>Table</strong>( unsigned (*hash_fn)( const Type & ), unsigned =WC_DEFAULT_HASH_SIZE, void * (*user_alloc)( size_t size ), void(*user_dealloc)( void *old, size_t size ) );WCPtrHash<strong>Table</strong>( const WCPtrHash<strong>Table</strong> & );virtual ~WCPtrHash<strong>Table</strong>();Hash Containers 105
WCPtrHash<strong>Table</strong>, WCPtrHashSetstatic unsigned bitHash( const void *, size_t );unsigned buckets() const;void clear();void clearAndDestroy();int contains( const Type * ) const;unsigned entries() const;Type * find( const Type * ) const;void forAll( void (*user_fn)( Type *, void * ) , void * );int insert( Type * );int isEmpty() const;Type * remove( const Type * );void resize( unsigned );The following public member functions are available for the WCPtrHash<strong>Table</strong> class only:unsigned occurrencesOf( const Type * ) const;unsigned removeAll( const Type * );Public Member OperatorsThe following member operators are declared in the public interface:WCPtrHashSet & operator =( const WCPtrHashSet & );int operator ==( const WCPtrHashSet & ) const;WCPtrHash<strong>Table</strong> & operator =( const WCPtrHash<strong>Table</strong> & );int operator ==( const WCPtrHash<strong>Table</strong> & ) const;106 Hash Containers
WCPtrHashSet::WCPtrHashSet()Synopsis:Semantics:#include public:WCPtrHashSet( unsigned (*hash_fn)( const Type & ),unsigned = WC_DEFAULT_HASH_SIZE );The WCPtrHashSet constructor creates a WCPtrHashSet object with no entries and withthe number <strong>of</strong> buckets in the second optional parameter, which defaults to the constantWC_DEFAULT_HASH_SIZE (currently defined as 101). The number <strong>of</strong> buckets specified must begreater than zero, and will be forced to at least one. If the hash object can be created, but an allocationfailure occurs when creating the buckets, the table will be created with zero buckets. If theout_<strong>of</strong>_memory exception is enabled, then attempting to insert into a hash table with zero bucketswith throw an out_<strong>of</strong>_memory error.The hash function hash_fn is used to determine which bucket each value will be assigned to. If nohash function exists, the static member function bitHash is available to help create one.Results:See Also:The WCPtrHashSet constructor creates an initialized WCPtrHashSet object with thespecified number <strong>of</strong> buckets and hash function.~WCPtrHashSet, bitHash, WCExcept::out_<strong>of</strong>_memoryHash Containers 107
WCPtrHashSet::WCPtrHashSet()Synopsis:Semantics:#include public:WCPtrHashSet( unsigned (*hash_fn)( const Type & ),unsigned = WC_DEFAULT_HASH_SIZE,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thehash. The semantics <strong>of</strong> this constructor are the same as the constructor without the memorymanagement functions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a hash. To determine the size <strong>of</strong> the objects that the memory managementfunctions will be required to allocate and free, the following macro may be used:WCPtrHashSetItemSize( Type )Results:See Also:The WCPtrHashSet constructor creates an initialized WCPtrHashSet object with thespecified number <strong>of</strong> buckets and hash function.~WCPtrHashSet, bitHash, WCExcept::out_<strong>of</strong>_memory108 Hash Containers
WCPtrHashSet::WCPtrHashSet()Synopsis:Semantics:Results:See Also:#include public:WCPtrHashSet( const WCPtrHashSet & );The WCPtrHashSet is the copy constructor for the WCPtrHashSet class. The new hash iscreated with the same number <strong>of</strong> buckets, hash function, all values or pointers stored in the hash, andthe exception trap states. If the hash object can be created, but an allocation failure occurs whencreating the buckets, the hash will be created with zero buckets. If there is not enough memory to copyall <strong>of</strong> the values, then only some will be copied, and the number <strong>of</strong> entries will correctly reflect thenumber copied. If all <strong>of</strong> the elements cannot be copied, then the out_<strong>of</strong>_memory exception isthrown if it is enabled.The WCPtrHashSet constructor creates a WCPtrHashSet object which is a copy <strong>of</strong> thepassed hash.~WCPtrHashSet, operator =, WCExcept::out_<strong>of</strong>_memoryHash Containers 109
WCPtrHashSet::~WCPtrHashSet()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCPtrHashSet();The WCPtrHashSet destructor is the destructor for the WCPtrHashSet class. If thenumber <strong>of</strong> elements is not zero and the not_empty exception is enabled, the exception is thrown.Otherwise, the hash elements are cleared using the clear member function. The objects which thehash elements point to are not deleted unless the clearAndDestroy member function is explicitlycalled before the destructor is called. The call to the WCPtrHashSet destructor is insertedimplicitly by the compiler at the point where the WCPtrHashSet object goes out <strong>of</strong> scope.The call to the WCPtrHashSet destructor destroys a WCPtrHashSet object.clear, clearAndDestroy, WCExcept::not_empty110 Hash Containers
WCPtrHash<strong>Table</strong>::WCPtrHash<strong>Table</strong>()Synopsis:Semantics:#include public:WCPtrHash<strong>Table</strong>( unsigned (*hash_fn)( const Type & ),unsigned = WC_DEFAULT_HASH_SIZE );The WCPtrHash<strong>Table</strong> constructor creates a WCPtrHash<strong>Table</strong> object with no entries andwith the number <strong>of</strong> buckets in the second optional parameter, which defaults to the constantWC_DEFAULT_HASH_SIZE (currently defined as 101). The number <strong>of</strong> buckets specified must begreater than zero, and will be forced to at least one. If the hash object can be created, but an allocationfailure occurs when creating the buckets, the table will be created with zero buckets. If theout_<strong>of</strong>_memory exception is enabled, then attempting to insert into a hash table with zero bucketswith throw an out_<strong>of</strong>_memory error.The hash function hash_fn is used to determine which bucket each value will be assigned to. If nohash function exists, the static member function bitHash is available to help create one.Results:See Also:The WCPtrHash<strong>Table</strong> constructor creates an initialized WCPtrHash<strong>Table</strong> object withthe specified number <strong>of</strong> buckets and hash function.~WCPtrHash<strong>Table</strong>, bitHash, WCExcept::out_<strong>of</strong>_memoryHash Containers 111
WCPtrHash<strong>Table</strong>::WCPtrHash<strong>Table</strong>()Synopsis:Semantics:#include public:WCPtrHash<strong>Table</strong>( unsigned (*hash_fn)( const Type & ),unsigned = WC_DEFAULT_HASH_SIZE,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thehash. The semantics <strong>of</strong> this constructor are the same as the constructor without the memorymanagement functions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a hash. To determine the size <strong>of</strong> the objects that the memory managementfunctions will be required to allocate and free, the following macro may be used:WCPtrHash<strong>Table</strong>ItemSize( Type )Results:See Also:The WCPtrHash<strong>Table</strong> constructor creates an initialized WCPtrHash<strong>Table</strong> object withthe specified number <strong>of</strong> buckets and hash function.~WCPtrHash<strong>Table</strong>, bitHash, WCExcept::out_<strong>of</strong>_memory112 Hash Containers
WCPtrHash<strong>Table</strong>::WCPtrHash<strong>Table</strong>()Synopsis:Semantics:Results:See Also:#include public:WCPtrHash<strong>Table</strong>( const WCPtrHash<strong>Table</strong> & );The WCPtrHash<strong>Table</strong> is the copy constructor for the WCPtrHash<strong>Table</strong> class. The newhash is created with the same number <strong>of</strong> buckets, hash function, all values or pointers stored in the hash,and the exception trap states. If the hash object can be created, but an allocation failure occurs whencreating the buckets, the hash will be created with zero buckets. If there is not enough memory to copyall <strong>of</strong> the values, then only some will be copied, and the number <strong>of</strong> entries will correctly reflect thenumber copied. If all <strong>of</strong> the elements cannot be copied, then the out_<strong>of</strong>_memory exception isthrown if it is enabled.The WCPtrHash<strong>Table</strong> constructor creates a WCPtrHash<strong>Table</strong> object which is a copy <strong>of</strong>the passed hash.~WCPtrHash<strong>Table</strong>, operator =, WCExcept::out_<strong>of</strong>_memoryHash Containers 113
WCPtrHash<strong>Table</strong>::~WCPtrHash<strong>Table</strong>()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCPtrHash<strong>Table</strong>();The WCPtrHash<strong>Table</strong> destructor is the destructor for the WCPtrHash<strong>Table</strong> class. If thenumber <strong>of</strong> elements is not zero and the not_empty exception is enabled, the exception is thrown.Otherwise, the hash elements are cleared using the clear member function. The objects which thehash elements point to are not deleted unless the clearAndDestroy member function is explicitlycalled before the destructor is called. The call to the WCPtrHash<strong>Table</strong> destructor is insertedimplicitly by the compiler at the point where the WCPtrHash<strong>Table</strong> object goes out <strong>of</strong> scope.The call to the WCPtrHash<strong>Table</strong> destructor destroys a WCPtrHash<strong>Table</strong> object.clear, clearAndDestroy, WCExcept::not_empty114 Hash Containers
WCPtrHash<strong>Table</strong>::bitHash(), WCPtrHashSet::bitHash()Synopsis:Semantics:Results:See Also:#include public:static unsigned bitHash( void *, size_t );The bitHash public member function can be used to implement a hashing function for any type. Ahashing value is generated from the value stored for the number <strong>of</strong> specified bytes pointed to by the firstparameter.The bitHash public member function returns an unsigned value which can be used as the basis <strong>of</strong> auser defined hash function.WCPtrHashSet, WCPtrHash<strong>Table</strong>Hash Containers 115
WCPtrHash<strong>Table</strong>::buckets(), WCPtrHashSet::buckets()Synopsis:Semantics:Results:See Also:#include public:unsigned buckets() const;The buckets public member function is used to find the number <strong>of</strong> buckets contained in the hashobject.The buckets public member function returns the number <strong>of</strong> buckets in the hash.resize116 Hash Containers
WCPtrHash<strong>Table</strong>::clear(), WCPtrHashSet::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the hash so that it has no entries. The number <strong>of</strong>buckets remain unaffected. Objects pointed to by the hash elements are not deleted. The hash object isnot destroyed and re-created by this function, so the object destructor is not invoked.The clear public member function clears the hash to have no elements.See Also: ~WCPtrHashSet, ~WCPtrHash<strong>Table</strong>, clearAndDestroy, operator =Hash Containers 117
WCPtrHash<strong>Table</strong>,WCPtrHashSet::clearAndDestroy()Synopsis:Semantics:Results:See Also:#include public:void clearAndDestroy();The clearAndDestroy public member function is used to clear the hash and delete the objectspointed to by the hash elements. The hash object is not destroyed and re-created by this function, so thehash object destructor is not invoked.The clearAndDestroy public member function clears the hash by deleting the objects pointed to bythe hash elements.clear118 Hash Containers
WCPtrHash<strong>Table</strong>::contains(), WCPtrHashSet::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Type * ) const;The contains public member function returns non-zero if the element is stored in the hash, or zero ifthere is no equivalent element. Note that equivalence is based on the equivalence operator <strong>of</strong> theelement type.The contains public member function returns a non-zero value if the element is found in the hash.findHash Containers 119
WCPtrHash<strong>Table</strong>::entries(), WCPtrHashSet::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to return the current number <strong>of</strong> elements stored in thehash.The entries public member function returns the number <strong>of</strong> elements in the hash.buckets, isEmpty120 Hash Containers
WCPtrHash<strong>Table</strong>::find(), WCPtrHashSet::find()Synopsis:Semantics:Results:#include public:Type * find( const Type * ) const;The find public member function is used to find an element with an equivalent key in the hash. If anequivalent element is found, a pointer to the element is returned. Zero is returned if the element is notfound. Note that equivalence is based on the equivalence operator <strong>of</strong> the element type.The element equivalent to the passed key is located in the hash.Hash Containers 121
WCPtrHash<strong>Table</strong>::forAll(), WCPtrHashSet::forAll()Synopsis:Semantics:#include public:void forAll(void (*user_fn)( Type *, void * ),void * );The forAll public member function causes the user supplied function to be invoked for every value inthe hash. The user function has the prototypevoid user_func( Type * value, void * data );As the elements are visited, the user function is invoked with the element passed as the first. Thesecond parameter <strong>of</strong> the forAll function is passed as the second parameter to the user function. Thisvalue can be used to pass any appropriate data from the main code to the user function.Results:See Also:The elements in the hash are all visited, with the user function being invoked for each one.find122 Hash Containers
WCPtrHash<strong>Table</strong>::insert(), WCPtrHashSet::insert()Synopsis:Semantics:#include public:int insert( Type * );The insert public member function inserts a value into the hash, using the hash function to determineto which bucket it should be stored. If allocation <strong>of</strong> the node to store the value fails, then theout_<strong>of</strong>_memory exception is thrown if it is enabled. If the exception is not enabled, the insert willnot be completed.With a WCPtrHashSet, there must be only one equivalent element in the set. If an elementequivalent to the inserted element is already in the hash set, the hash set will remain unchanged, and thenot_unique exception is thrown if it is enabled. If the exception is not enabled, the insert will not becompleted.At some point, the number <strong>of</strong> buckets initially selected may be too small for the number <strong>of</strong> elementsinserted. The resize <strong>of</strong> the hash can be controlled by the insertion mechanism by usingWCPtrHashSet (or WCPtrHash<strong>Table</strong>) as a base class, and providing an insert member function todo a resize when appropriate. This insert could then call WCPtrHashSet::insert (orWCPtrHash<strong>Table</strong>::insert) to insert the element. Note that copy constructors and assignmentoperators are not inherited in your class, but you can provide the following inline definitions (assumingthat the class inherited from WCPtrHash<strong>Table</strong> is named MyHash<strong>Table</strong>):inline MyHash<strong>Table</strong>( const MyHash<strong>Table</strong> &orig ): WCPtrHash<strong>Table</strong>( orig ) {};inline MyHash<strong>Table</strong> &operator=( const MyHash<strong>Table</strong> &orig ) {return( WCPtrHash<strong>Table</strong>::operator=( orig ) );}Results:See Also:The insert public member function inserts a value into the hash. If the insert is successful, anon-zero will returned. A zero will be returned if the insert fails.operator =, WCExcept::out_<strong>of</strong>_memoryHash Containers 123
WCPtrHash<strong>Table</strong>::isEmpty(), WCPtrHashSet::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if the hash is empty.The isEmpty public member function returns zero if it contains at least one entry, non-zero if the hashis empty.buckets, entries124 Hash Containers
WCPtrHash<strong>Table</strong>::occurencesOf()Synopsis:Semantics:Results:See Also:#include public:unsigned occurrencesOf( const Type * ) const;The occurencesOf public member function is used to return the current number <strong>of</strong> elements storedin the hash which are equivalent to the passed value. Note that equivalence is based on the equivalenceoperator <strong>of</strong> the element type.The occurencesOf public member function returns the number <strong>of</strong> elements in the hash.buckets, entries, find, isEmptyHash Containers 125
WCPtrHash<strong>Table</strong>::operator =(), WCPtrHashSet::operator =()Synopsis:Semantics:Results:See Also:#include public:WCPtrHashSet & operator =( const WCPtrHashSet & );WCPtrHash<strong>Table</strong> & operator =( const WCPtrHash<strong>Table</strong> & );The operator = public member function is the assignment operator for theWCPtrHash<strong>Table</strong> and WCPtrHashSet classes. The left hand side hash is firstcleared using the clear member function, and then the right hand side hash is copied. The hashfunction, exception trap states, and all <strong>of</strong> the hash elements are copied. If an allocation failure occurswhen creating the buckets, the table will be created with zero buckets, and the out_<strong>of</strong>_memoryexception is thrown if it is enabled. If there is not enough memory to copy all <strong>of</strong> the values or pointersin the hash, then only some will be copied, and the out_<strong>of</strong>_memory exception is thrown if it isenabled. The number <strong>of</strong> entries will correctly reflect the number copied.The operator = public member function assigns the left hand side hash to be a copy <strong>of</strong> the righthand side.clear, WCExcept::out_<strong>of</strong>_memory126 Hash Containers
WCPtrHash<strong>Table</strong>::operator ==(), WCPtrHashSet::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCPtrHashSet & ) const;int operator ==( const WCPtrHash<strong>Table</strong> & ) const;The operator == public member function is the equivalence operator for theWCPtrHash<strong>Table</strong> and WCPtrHashSet classes. Two hash objects are equivalentif they are the same object and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side hash are the same object.A FALSE (zero) value is returned otherwise.Hash Containers 127
WCPtrHash<strong>Table</strong>::remove(), WCPtrHashSet::remove()Synopsis:Semantics:Results:#include public:Type * remove( const Type * );The remove public member function is used to remove the specified element from the hash. If anequivalent element is found, the pointer value is returned. Zero is returned if the element is not found.If the hash is a table and there is more than one element equivalent to the specified element, then thefirst equivalent element added to the table is removed. Note that equivalence is based on theequivalence operator <strong>of</strong> the element type.The element is removed from the hash if it found.128 Hash Containers
WCPtrHash<strong>Table</strong>::removeAll()Synopsis:Semantics:Results:#include public:unsigned removeAll( const Type * );The removeAll public member function is used to remove all elements equivalent to the specifiedelement from the hash. Zero is returned if no equivalent elements are found. Note that equivalence isbased on the equivalence operator <strong>of</strong> the element type.All equivalent elements are removed from the hash.Hash Containers 129
WCPtrHash<strong>Table</strong>::resize(), WCPtrHashSet::resize()Synopsis:Semantics:Results:See Also:#include public:void resize( unsigned );The resize public member function is used to change the number <strong>of</strong> buckets contained in the hash. Ifthe new number is larger than the previous hash size, then the hash function will be used on all <strong>of</strong> thestored elements to determine which bucket they should be stored into. Entries are not destroyed orcreated in the process <strong>of</strong> being moved. If there is not enough memory to resize the hash, theout_<strong>of</strong>_memory exception is thrown if it is enabled, and the hash will contain the number <strong>of</strong> bucketsit contained before the resize. If the new number is zero, then the zero_buckets exception isthrown if it is enabled, and no resize will be performed. The hash is guaranteed to contain the samenumber <strong>of</strong> entries after the resize.The hash is resized to the new number <strong>of</strong> buckets.WCExcept::out_<strong>of</strong>_memory, WCExcept::zero_buckets130 Hash Containers
WCValHashDictDeclared:wchash.hThe WCValHashDict class is a templated class used to store objects in a dictionary.Dictionaries store values with an associated key, which may be <strong>of</strong> any type. One example <strong>of</strong> adictionary used in everyday life is the phone book. The phone numbers are the data values, and thecustomer name is the key. An example <strong>of</strong> a specialized dictionary is a vector, where the key value is theinteger index.As an element is looked up or inserted into the dictionary, the associated key is hashed. Hashingconverts the key into a numeric index value which is used to locate the value. The storage areareferenced by the hash value is usually called a bucket. If more than one key results in the same hash,the values associated with the keys are placed in a list stored in the bucket. The equality operator <strong>of</strong> thekey’s type is used to locate the key-value pairs.In the description <strong>of</strong> each member function, the text Key is used to indicate the template parameterdefining the type <strong>of</strong> the indices used to store data in the dictionary. The text Value is used to indicatethe template parameter defining the type <strong>of</strong> the data stored in the dictionary.The constructor for the WCValHashDict class requires a hashing function, whichgiven a reference to Key, returns an unsigned value. The returned value modulo the number <strong>of</strong>buckets determines the bucket into which the key-value pair will be located. The return values <strong>of</strong> thehash function can be spread over the entire range <strong>of</strong> unsigned numbers. The hash function return valuemust be the same for values which are equivalent by the equivalence operator for Key.Values are copied into the dictionary, which could be undesirable if the stored objects are complicatedand copying is expensive. Value dictionaries should not be used to store objects <strong>of</strong> a base class if anyderived types <strong>of</strong> different sizes would be stored in the dictionary, or if the destructor for a derived classmust be called.The WCExcept class is a base class <strong>of</strong> the WCValHashDict class and provides theexceptions member function. This member function controls the exceptions which can be thrownby the WCValHashDict object. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> Key and ValueThe WCValHashDict class requires Key to have:A default constructor ( Key::Key() ).A well defined copy constructor ( Key::Key( const Key & ) ).A well defined assignment operator ( Key & operator =( const Key & ) ).A well defined equivalence operator with constant parameters( int operator ==( const Key & ) const ).The WCValHashDict class requires Value to have:A default constructor ( Value::Value() ).A well defined copy constructor ( Value::Value( const Value & ) ).A well defined assignment operator ( Value & operator =( const Value & ) ).Hash Containers 131
WCValHashDictPublic Member FunctionsThe following member functions are declared in the public interface:WCValHashDict( unsigned (*hash_fn)( const Key & ), unsigned =WC_DEFAULT_HASH_SIZE );WCValHashDict( unsigned (*hash_fn)( const Key & ), unsigned =WC_DEFAULT_HASH_SIZE, void * (*user_alloc)( size_t size ), void(*user_dealloc)( void *old, size_t size ) );WCValHashDict( const WCValHashDict & );virtual ~WCValHashDict();static unsigned bitHash( const void *, size_t );unsigned buckets() const;void clear();int contains( const Key & ) const;unsigned entries() const;int find( const Key &, Value & ) const;int findKeyAndValue( const Key &, Key &, Value & ) const;void forAll( void (*user_fn)( Key, Value, void * ), void * );int insert( const Key &, const Value & );int isEmpty() const;int remove( const Key & );void resize( unsigned );Public Member OperatorsThe following member operators are declared in the public interface:Value & operator []( const Key & );const Value & operator []( const Key & ) const;WCValHashDict & operator =( const WCValHashDict & );int operator ==( const WCValHashDict & ) const;132 Hash Containers
WCValHashDict::WCValHashDict()Synopsis:Semantics:#include public:WCValHashDict( unsigned (*hash_fn)( const Key & ),unsigned = WC_DEFAULT_HASH_SIZE );The public WCValHashDict constructor creates anWCValHashDict object with no entries and with the number <strong>of</strong> buckets in the secondoptional parameter, which defaults to the constant WC_DEFAULT_HASH_SIZE (currently defined as101). The number <strong>of</strong> buckets specified must be greater than zero, and will be forced to at least one. Ifthe hash dictionary object can be created, but an allocation failure occurs when creating the buckets, thetable will be created with zero buckets. If the out_<strong>of</strong>_memory exception is enabled, then attemptingto insert into a hash table with zero buckets with throw an out_<strong>of</strong>_memory error.The hash function hash_fn is used to determine which bucket each key-value pair will be assigned. Ifno hash function exists, the static member function bitHash is available to help create one.Results:See Also:The public WCValHashDict constructor creates an initializedWCValHashDict object with the specified number <strong>of</strong> buckets and hash function.~WCValHashDict, bitHash, WCExcept::out_<strong>of</strong>_memoryHash Containers 133
WCValHashDict::WCValHashDict()Synopsis:Semantics:#include public:WCValHashDict( unsigned (*hash_fn)( const Key & ),unsigned = WC_DEFAULT_HASH_SIZE,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thehash dictionary. The semantics <strong>of</strong> this constructor are the same as the constructor without the memorymanagement functions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a hash dictionary. To determine the size <strong>of</strong> the objects that the memorymanagement functions will be required to allocate and free, the following macro may be used:WCValHashDictItemSize( Key, Value )Results:See Also:The public WCValHashDict constructor creates an initializedWCValHashDict object with the specified number <strong>of</strong> buckets and hash function.~WCValHashDict, bitHash, WCExcept::out_<strong>of</strong>_memory134 Hash Containers
WCValHashDict::WCValHashDict()Synopsis:Semantics:Results:See Also:#include public:WCValHashDict( const WCValHashDict & );The public WCValHashDict constructor is the copy constructor for theWCValHashDict class. The new dictionary is created with the same number <strong>of</strong>buckets, hash function, all values or pointers stored in the dictionary, and the exception trap states. Ifthe hash dictionary object can be created, but an allocation failure occurs when creating the buckets, thetable will be created with zero buckets. If there is not enough memory to copy all <strong>of</strong> the values in thedictionary, then only some will be copied, and the number <strong>of</strong> entries will correctly reflect the numbercopied. If all <strong>of</strong> the elements cannot be copied, then the out_<strong>of</strong>_memory exception is thrown if it isenabled.The public WCValHashDict constructor creates anWCValHashDict object which is a copy <strong>of</strong> the passed dictionary.~WCValHashDict, operator =, WCExcept::out_<strong>of</strong>_memoryHash Containers 135
WCValHashDict::~WCValHashDict()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCValHashDict();The public ~WCValHashDict destructor is the destructor for theWCValHashDict class. If the number <strong>of</strong> dictionary elements is not zero and thenot_empty exception is enabled, the exception is thrown. Otherwise, the dictionary elements arecleared using the clear member function. The call to the public ~WCValHashDictdestructor is inserted implicitly by the compiler at the point where theWCValHashDict object goes out <strong>of</strong> scope.The public ~WCValHashDict destructor destroys anWCValHashDict object.clear, WCExcept::not_empty136 Hash Containers
WCValHashDict::bitHash()Synopsis:Semantics:#include public:static unsigned bitHash( void *, size_t );The bitHash public member function can be used to implement a hashing function for any type. Ahashing value is generated from the value stored for the number <strong>of</strong> specified bytes pointed to by the firstparameter. For example:unsigned my_hash_fn( const int & key ) {return( WCValHashDict::bitHash( &key, size<strong>of</strong>( int ) );}WCValHashDict data_object( &my_hash_fn );Results:See Also:The bitHash public member function returns an unsigned value which can be used as the basis <strong>of</strong> auser defined hash function.WCValHashDictHash Containers 137
WCValHashDict::buckets()Synopsis:Semantics:Results:See Also:#include public:unsigned buckets const;The buckets public member function is used to find the number <strong>of</strong> buckets contained in theWCValHashDict object.The buckets public member function returns the number <strong>of</strong> buckets in the dictionary.resize138 Hash Containers
WCValHashDict::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the dictionary so that it has no entries. The number<strong>of</strong> buckets remain unaffected. Elements stored in the dictionary are destroyed using the destructors <strong>of</strong>Key and <strong>of</strong> Value. The dictionary object is not destroyed and re-created by this function, so theobject destructor is not invoked.The clear public member function clears the dictionary to have no elements.See Also: ~WCValHashDict, operator =Hash Containers 139
WCValHashDict::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Key & ) const;The contains public member function returns non-zero if an element with the specified key is storedin the dictionary, or zero if there is no equivalent element. Note that equivalence is based on theequivalence operator <strong>of</strong> the Key type.The contains public member function returns a non-zero value if the Key is found in the dictionary.find, findKeyAndValue140 Hash Containers
WCValHashDict::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to return the current number <strong>of</strong> elements stored in thedictionary.The entries public member function returns the number <strong>of</strong> elements in the dictionary.buckets, isEmptyHash Containers 141
WCValHashDict::find()Synopsis:Semantics:Results:See Also:#include public:int find( const Key &, Value & ) const;The find public member function is used to find an element with an equivalent key in the dictionary.If an equivalent element is found, a non-zero value is returned. The reference to a Value passed as thesecond argument is assigned the found element’s Value. Zero is returned if the element is not found.Note that equivalence is based on the equivalence operator <strong>of</strong> the Key type.The element equivalent to the passed key is located in the dictionary.findKeyAndValue142 Hash Containers
WCValHashDict::findKeyAndValue()Synopsis:Semantics:Results:See Also:#include public:int findKeyAndValue( const Key &, Key &, Value & ) const;The findKeyAndValue public member function is used to find an element in the dictionary with ankey equivalent to the first parameter. If an equivalent element is found, a non-zero value is returned.The reference to a Key passed as the second parameter is assigned the found element’s key. Thereference to a Value passed as the third argument is assigned the found element’s Value. Zero isreturned if the element is not found. Note that equivalence is based on the equivalence operator <strong>of</strong> theKey type.The element equivalent to the passed key is located in the dictionary.findKeyAndValueHash Containers 143
WCValHashDict::forAll()Synopsis:Semantics:#include public:void forAll(void (*user_fn)( Key, Value, void * ),void * );The forAll public member function causes the user supplied function to be invoked for everykey-value pair in the dictionary. The user function has the prototypevoid user_func( Key key, Value value, void * data );As the elements are visited, the user function is invoked with the Key and Value components <strong>of</strong> theelement passed as the first two parameters. The second parameter <strong>of</strong> the forAll function is passed asthe third parameter to the user function. This value can be used to pass any appropriate data from themain code to the user function.Results:See Also:The elements in the dictionary are all visited, with the user function being invoked for each one.find, findKeyAndValue144 Hash Containers
WCValHashDict::insert()Synopsis:Semantics:#include public:int insert( const Key &, const Value & );The insert public member function inserts a key and value into the dictionary, using the hashfunction on the key to determine to which bucket it should be stored. If allocation <strong>of</strong> the node to storethe key-value pair fails, then the out_<strong>of</strong>_memory exception is thrown if it is enabled. If theexception is not enabled, the insert will not be completed.At some point, the number <strong>of</strong> buckets initially selected may be too small for the number <strong>of</strong> elementsinserted. The resize <strong>of</strong> the dictionary can be controlled by the insertion mechanism by usingWCValHashDict as a base class, and providing an insert member function to do a resize whenappropriate. This insert could then call WCValHashDict::insert to insert the element. Note thatcopy constructors and assignment operators are not inherited in your class, but you can provide thefollowing inline definitions (assuming that the class inherited from WCValHashDict is namedMyHashDict):inline MyHashDict( const MyHashDict &orig ) : WCValHashDict( orig ) {};inline MyHashDict &operator=( const MyHashDict &orig ) {return( WCValHashDict::operator=( orig ) );}Results:See Also:The insert public member function inserts a key and value into the dictionary. If the insert issuccessful, a non-zero will returned. A zero will be returned if the insert fails.operator =, WCExcept::out_<strong>of</strong>_memoryHash Containers 145
WCValHashDict::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if the dictionary is empty.The isEmpty public member function returns zero if it contains at least one entry, non-zero if thedictionary is empty.buckets, entries146 Hash Containers
WCValHashDict::operator []()Synopsis:Semantics:#include public:Value & operator[]( const Key & );operator [] is the dictionary index operator. A reference to the object stored in the dictionary withthe given Key is returned. If no equivalent element is found, then a new key-value pair is created withthe specified Key value, and initialized with the default constructor. The returned reference can then beassigned to, so that insertions can be made with the operator.WCValHashDict data_object( &my_hash_fn );data_object[ 5 ] = "Hello";If an allocation error occurs while inserting a new key-value pair, then the out_<strong>of</strong>_memoryexception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero willbe returned. This will result in a run-time error on systems which trap address zero references.Results:See Also:The operator [] public member function returns a reference to the element at the given key value.If the key does not exist, a reference to a created element is returned. The result <strong>of</strong> the operator may beassigned to.WCExcept::out_<strong>of</strong>_memoryHash Containers 147
WCValHashDict::operator []()Synopsis:Semantics:Results:See Also:#include public:const Value & operator[]( const Key & ) const;operator [] is the dictionary index operator. A constant reference to the object stored in thedictionary with the given Key is returned. If no equivalent element is found, then the index_rangeexception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero willbe returned. This will result in a run-time error on systems which trap address zero references.The operator [] public member function returns a constant reference to the element at the givenkey value. The result <strong>of</strong> the operator may not be assigned to.WCExcept::index_range148 Hash Containers
WCValHashDict::operator =()Synopsis:Semantics:Results:See Also:#include public:WCValHashDict & operator =( const WCValHashDict & );The operator = public member function is the assignment operator for theWCValHashDict class. The left hand side dictionary is first cleared using theclear member function, and then the right hand side dictionary is copied. The hash function,exception trap states, and all <strong>of</strong> the dictionary elements are copied. If an allocation failure occurs whencreating the buckets, the table will be created with zero buckets, and the out_<strong>of</strong>_memory exceptionis thrown if it is enabled. If there is not enough memory to copy all <strong>of</strong> the values or pointers in thedictionary, then only some will be copied, and the out_<strong>of</strong>_memory exception is thrown if it isenabled. The number <strong>of</strong> entries will correctly reflect the number copied.The operator = public member function assigns the left hand side dictionary to be a copy <strong>of</strong> theright hand side.clear, WCExcept::out_<strong>of</strong>_memoryHash Containers 149
WCValHashDict::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCValHashDict & ) const;The operator == public member function is the equivalence operator for theWCValHashDict class. Two dictionary objects are equivalent if they are the sameobject and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side dictionary are the sameobject. A FALSE (zero) value is returned otherwise.150 Hash Containers
WCValHashDict::remove()Synopsis:Semantics:Results:#include public:int remove( const Key & );The remove public member function is used to remove the specified element from the dictionary. Ifan equivalent element is found, a non-zero value is returned. Zero is returned if the element is notfound. Note that equivalence is based on the equivalence operator <strong>of</strong> the Key type.The element is removed from the dictionary if it found.Hash Containers 151
WCValHashDict::resize()Synopsis:Semantics:Results:See Also:#include public:void resize( unsigned );The resize public member function is used to change the number <strong>of</strong> buckets contained in thedictionary. If the new number is larger than the previous dictionary size, then the hash function will beused on all <strong>of</strong> the stored elements to determine which bucket they should be stored into. Entries are notdestroyed or created in the process <strong>of</strong> being moved. If there is not enough memory to resize thedictionary, the out_<strong>of</strong>_memory exception is thrown if it is enabled, and the dictionary will containthe number <strong>of</strong> buckets it contained before the resize. If the new number is zero, then thezero_buckets exception is thrown if it is enabled, and no resize will be performed. The dictionaryis guaranteed to contain the same number <strong>of</strong> entries after the resize.The dictionary is resized to the new number <strong>of</strong> buckets.WCExcept::out_<strong>of</strong>_memory, WCExcept::zero_buckets152 Hash Containers
WCValHash<strong>Table</strong>, WCValHashSetDeclared:wchash.hWCValHash<strong>Table</strong> and WCValHashSet classes are templated classes used to storeobjects in a hash. A hash saves objects in such a way as to make it efficient to locate and retrieve anelement. As an element is looked up or inserted into the hash, the value <strong>of</strong> the element is hashed.Hashing results in a numeric index which is used to locate the value. The storage area referenced by thehash value is usually called a bucket. If more than one element results in the same hash, the valueassociated with the hash is placed in a list stored in the bucket. A hash table allows more than one copy<strong>of</strong> an element that is equivalent, while the hash set allows only one copy. The equality operator <strong>of</strong> theelement’s type is used to locate the value.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type <strong>of</strong> the data to be stored in the hash.The constructor for the WCValHash<strong>Table</strong> and WCValHashSet classes requires ahashing function, which given a reference to Type, returns an unsigned value. The returned valuemodulo the number <strong>of</strong> buckets determines the bucket into which the element will be located. The returnvalues <strong>of</strong> the hash function can be spread over the entire range <strong>of</strong> unsigned numbers. The hash functionreturn value must be the same for values which are equivalent by the equivalence operator for Type.Values are copied into the hash, which could be undesirable if the stored objects are complicated andcopying is expensive. Value hashes should not be used to store objects <strong>of</strong> a base class if any derivedtypes <strong>of</strong> different sizes would be stored in the hash, or if the destructor for a derived class must becalled.The WCExcept class is a base class <strong>of</strong> the WCValHash<strong>Table</strong> andWCValHashSet classes and provides the exceptions member function. This memberfunction controls the exceptions which can be thrown by the WCValHash<strong>Table</strong> andWCValHashSet objects. No exceptions are enabled unless they are set by the exceptionsmember function.Requirements <strong>of</strong> TypeThe WCValHash<strong>Table</strong> and WCValHashSet classes requires Type to have:A default constructor ( Type::Type() ).A well defined copy constructor ( Type::Type( const Type & ) ).A well defined assignment operator ( Type & operator =( const Type & ) ).A well defined equivalence operator with constant parameters( int operator ==( const Type & ) const ).Public Member FunctionsThe following member functions are declared in the public interface:WCValHashSet( unsigned (*hash_fn)( const Type & ), unsigned =WC_DEFAULT_HASH_SIZE );WCValHashSet( unsigned (*hash_fn)( const Type & ), unsigned =WC_DEFAULT_HASH_SIZE, void * (*user_alloc)( size_t size ), void(*user_dealloc)( void *old, size_t size ) );WCValHashSet( const WCValHashSet & );virtual ~WCValHashSet();Hash Containers 153
WCValHash<strong>Table</strong>, WCValHashSetWCValHash<strong>Table</strong>( unsigned (*hash_fn)( const Type & ), unsigned =WC_DEFAULT_HASH_SIZE );WCValHash<strong>Table</strong>( unsigned (*hash_fn)( const Type & ), unsigned =WC_DEFAULT_HASH_SIZE, void * (*user_alloc)( size_t size ), void(*user_dealloc)( void *old, size_t size ) );WCValHash<strong>Table</strong>( const WCValHash<strong>Table</strong> & );virtual ~WCValHash<strong>Table</strong>();static unsigned bitHash( const void *, size_t );unsigned buckets() const;void clear();int contains( const Type & ) const;unsigned entries() const;int find( const Type &, Type & ) const;void forAll( void (*user_fn)( Type, void * ), void * );int insert( const Type & );int isEmpty() const;int remove( const Type & );void resize( unsigned );The following public member functions are available for the WCValHash<strong>Table</strong> class only:unsigned occurrencesOf( const Type & ) const;unsigned removeAll( const Type & );Public Member OperatorsThe following member operators are declared in the public interface:WCValHashSet & operator =( const WCValHashSet & );int operator ==( const WCValHashSet & ) const;WCValHash<strong>Table</strong> & operator =( const WCValHash<strong>Table</strong> & );int operator ==( const WCValHash<strong>Table</strong> & ) const;154 Hash Containers
WCValHashSet::WCValHashSet()Synopsis:Semantics:#include public:WCValHashSet( unsigned (*hash_fn)( const Type & ),unsigned = WC_DEFAULT_HASH_SIZE );The WCValHashSet constructor creates a WCValHashSet object with no entries and withthe number <strong>of</strong> buckets in the second optional parameter, which defaults to the constantWC_DEFAULT_HASH_SIZE (currently defined as 101). The number <strong>of</strong> buckets specified must begreater than zero, and will be forced to at least one. If the hash object can be created, but an allocationfailure occurs when creating the buckets, the table will be created with zero buckets. If theout_<strong>of</strong>_memory exception is enabled, then attempting to insert into a hash table with zero bucketswith throw an out_<strong>of</strong>_memory error.The hash function hash_fn is used to determine which bucket each value will be assigned to. If nohash function exists, the static member function bitHash is available to help create one.Results:See Also:The WCValHashSet constructor creates an initialized WCValHashSet object with thespecified number <strong>of</strong> buckets and hash function.~WCValHashSet, bitHash, WCExcept::out_<strong>of</strong>_memoryHash Containers 155
WCValHashSet::WCValHashSet()Synopsis:Semantics:#include public:WCValHashSet( unsigned (*hash_fn)( const Type & ),unsigned = WC_DEFAULT_HASH_SIZE,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thehash. The semantics <strong>of</strong> this constructor are the same as the constructor without the memorymanagement functions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a hash. To determine the size <strong>of</strong> the objects that the memory managementfunctions will be required to allocate and free, the following macro may be used:WCValHashSetItemSize( Type )Results:See Also:The WCValHashSet constructor creates an initialized WCValHashSet object with thespecified number <strong>of</strong> buckets and hash function.~WCValHashSet, bitHash, WCExcept::out_<strong>of</strong>_memory156 Hash Containers
WCValHashSet::WCValHashSet()Synopsis:Semantics:Results:See Also:#include public:WCValHashSet( const WCValHashSet & );The WCValHashSet is the copy constructor for the WCValHashSet class. The new hash iscreated with the same number <strong>of</strong> buckets, hash function, all values or pointers stored in the hash, andthe exception trap states. If the hash object can be created, but an allocation failure occurs whencreating the buckets, the hash will be created with zero buckets. If there is not enough memory to copyall <strong>of</strong> the values, then only some will be copied, and the number <strong>of</strong> entries will correctly reflect thenumber copied. If all <strong>of</strong> the elements cannot be copied, then the out_<strong>of</strong>_memory exception isthrown if it is enabled.The WCValHashSet constructor creates a WCValHashSet object which is a copy <strong>of</strong> thepassed hash.~WCValHashSet, operator =, WCExcept::out_<strong>of</strong>_memoryHash Containers 157
WCValHashSet::~WCValHashSet()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCValHashSet();The WCValHashSet destructor is the destructor for the WCValHashSet class. If thenumber <strong>of</strong> elements is not zero and the not_empty exception is enabled, the exception is thrown.Otherwise, the hash elements are cleared using the clear member function. The call to theWCValHashSet destructor is inserted implicitly by the compiler at the point where theWCValHashSet object goes out <strong>of</strong> scope.The call to the WCValHashSet destructor destroys a WCValHashSet object.clear, WCExcept::not_empty158 Hash Containers
WCValHash<strong>Table</strong>::WCValHash<strong>Table</strong>()Synopsis:Semantics:#include public:WCValHash<strong>Table</strong>( unsigned (*hash_fn)( const Type & ),unsigned = WC_DEFAULT_HASH_SIZE );The WCValHash<strong>Table</strong> constructor creates a WCValHash<strong>Table</strong> object with no entries andwith the number <strong>of</strong> buckets in the second optional parameter, which defaults to the constantWC_DEFAULT_HASH_SIZE (currently defined as 101). The number <strong>of</strong> buckets specified must begreater than zero, and will be forced to at least one. If the hash object can be created, but an allocationfailure occurs when creating the buckets, the table will be created with zero buckets. If theout_<strong>of</strong>_memory exception is enabled, then attempting to insert into a hash table with zero bucketswith throw an out_<strong>of</strong>_memory error.The hash function hash_fn is used to determine which bucket each value will be assigned to. If nohash function exists, the static member function bitHash is available to help create one.Results:See Also:The WCValHash<strong>Table</strong> constructor creates an initialized WCValHash<strong>Table</strong> object withthe specified number <strong>of</strong> buckets and hash function.~WCValHash<strong>Table</strong>, bitHash, WCExcept::out_<strong>of</strong>_memoryHash Containers 159
WCValHash<strong>Table</strong>::WCValHash<strong>Table</strong>()Synopsis:Semantics:#include public:WCValHash<strong>Table</strong>( unsigned (*hash_fn)( const Type & ),unsigned = WC_DEFAULT_HASH_SIZE,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thehash. The semantics <strong>of</strong> this constructor are the same as the constructor without the memorymanagement functions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a hash. To determine the size <strong>of</strong> the objects that the memory managementfunctions will be required to allocate and free, the following macro may be used:WCValHash<strong>Table</strong>ItemSize( Type )Results:See Also:The WCValHash<strong>Table</strong> constructor creates an initialized WCValHash<strong>Table</strong> object withthe specified number <strong>of</strong> buckets and hash function.~WCValHash<strong>Table</strong>, bitHash, WCExcept::out_<strong>of</strong>_memory160 Hash Containers
WCValHash<strong>Table</strong>::WCValHash<strong>Table</strong>()Synopsis:Semantics:Results:See Also:#include public:WCValHash<strong>Table</strong>( const WCValHash<strong>Table</strong> & );The WCValHash<strong>Table</strong> is the copy constructor for the WCValHash<strong>Table</strong> class. The newhash is created with the same number <strong>of</strong> buckets, hash function, all values or pointers stored in the hash,and the exception trap states. If the hash object can be created, but an allocation failure occurs whencreating the buckets, the hash will be created with zero buckets. If there is not enough memory to copyall <strong>of</strong> the values, then only some will be copied, and the number <strong>of</strong> entries will correctly reflect thenumber copied. If all <strong>of</strong> the elements cannot be copied, then the out_<strong>of</strong>_memory exception isthrown if it is enabled.The WCValHash<strong>Table</strong> constructor creates a WCValHash<strong>Table</strong> object which is a copy <strong>of</strong>the passed hash.~WCValHash<strong>Table</strong>, operator =, WCExcept::out_<strong>of</strong>_memoryHash Containers 161
WCValHash<strong>Table</strong>::~WCValHash<strong>Table</strong>()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCValHash<strong>Table</strong>();The WCValHash<strong>Table</strong> destructor is the destructor for the WCValHash<strong>Table</strong> class. If thenumber <strong>of</strong> elements is not zero and the not_empty exception is enabled, the exception is thrown.Otherwise, the hash elements are cleared using the clear member function. The call to theWCValHash<strong>Table</strong> destructor is inserted implicitly by the compiler at the point where theWCValHash<strong>Table</strong> object goes out <strong>of</strong> scope.The call to the WCValHash<strong>Table</strong> destructor destroys a WCValHash<strong>Table</strong> object.clear, WCExcept::not_empty162 Hash Containers
WCValHash<strong>Table</strong>::bitHash(), WCValHashSet::bitHash()Synopsis:Semantics:#include public:static unsigned bitHash( void *, size_t );The bitHash public member function can be used to implement a hashing function for any type. Ahashing value is generated from the value stored for the number <strong>of</strong> specified bytes pointed to by the firstparameter. For example:unsigned my_hash_fn( const int & elem ) {return( WCValHashSet::bitHash(&elem, size<strong>of</strong>(int));}WCValHashSet data_object( &my_hash_fn );Results:See Also:The bitHash public member function returns an unsigned value which can be used as the basis <strong>of</strong> auser defined hash function.WCValHashSet, WCValHash<strong>Table</strong>Hash Containers 163
WCValHash<strong>Table</strong>::buckets(), WCValHashSet::buckets()Synopsis:Semantics:Results:See Also:#include public:unsigned buckets() const;The buckets public member function is used to find the number <strong>of</strong> buckets contained in the hashobject.The buckets public member function returns the number <strong>of</strong> buckets in the hash.resize164 Hash Containers
WCValHash<strong>Table</strong>::clear(), WCValHashSet::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the hash so that it has no entries. The number <strong>of</strong>buckets remain unaffected. Elements stored in the hash are destroyed using the destructors <strong>of</strong> Type.The hash object is not destroyed and re-created by this function, so the object destructor is not invoked.The clear public member function clears the hash to have no elements.See Also: ~WCValHashSet, ~WCValHash<strong>Table</strong>, operator =Hash Containers 165
WCValHash<strong>Table</strong>::contains(), WCValHashSet::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Type & ) const;The contains public member function returns non-zero if the element is stored in the hash, or zero ifthere is no equivalent element. Note that equivalence is based on the equivalence operator <strong>of</strong> theelement type.The contains public member function returns a non-zero value if the element is found in the hash.find166 Hash Containers
WCValHash<strong>Table</strong>::entries(), WCValHashSet::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to return the current number <strong>of</strong> elements stored in thehash.The entries public member function returns the number <strong>of</strong> elements in the hash.buckets, isEmptyHash Containers 167
WCValHash<strong>Table</strong>::find(), WCValHashSet::find()Synopsis:Semantics:Results:#include public:int find( const Type &, Type & ) const;The find public member function is used to find an element with an equivalent key in the hash. If anequivalent element is found, a non-zero value is returned. The reference to the element passed as thesecond argument is assigned the found element’s value. Zero is returned if the element is not found.Note that equivalence is based on the equivalence operator <strong>of</strong> the element type.The element equivalent to the passed key is located in the hash.168 Hash Containers
WCValHash<strong>Table</strong>::forAll(), WCValHashSet::forAll()Synopsis:Semantics:#include public:void forAll(void (*user_fn)( Type, void * ),void * );The forAll public member function causes the user supplied function to be invoked for every value inthe hash. The user function has the prototypevoid user_func( Type & value, void * data );As the elements are visited, the user function is invoked with the element passed as the first. Thesecond parameter <strong>of</strong> the forAll function is passed as the second parameter to the user function. Thisvalue can be used to pass any appropriate data from the main code to the user function.Results:See Also:The elements in the hash are all visited, with the user function being invoked for each one.findHash Containers 169
WCValHash<strong>Table</strong>::insert(), WCValHashSet::insert()Synopsis:Semantics:#include public:int insert( const Type & );The insert public member function inserts a value into the hash, using the hash function to determineto which bucket it should be stored. If allocation <strong>of</strong> the node to store the value fails, then theout_<strong>of</strong>_memory exception is thrown if it is enabled. If the exception is not enabled, the insert willnot be completed.With a WCValHashSet, there must be only one equivalent element in the set. If an elementequivalent to the inserted element is already in the hash set, the hash set will remain unchanged, and thenot_unique exception is thrown if it is enabled. If the exception is not enabled, the insert will not becompleted.At some point, the number <strong>of</strong> buckets initially selected may be too small for the number <strong>of</strong> elementsinserted. The resize <strong>of</strong> the hash can be controlled by the insertion mechanism by usingWCValHashSet (or WCValHash<strong>Table</strong>) as a base class, and providing an insert member function todo a resize when appropriate. This insert could then call WCValHashSet::insert (orWCValHash<strong>Table</strong>::insert) to insert the element. Note that copy constructors and assignmentoperators are not inherited in your class, but you can provide the following inline definitions (assumingthat the class inherited from WCValHash<strong>Table</strong> is named MyHash<strong>Table</strong>):inline MyHash<strong>Table</strong>( const MyHash<strong>Table</strong> &orig ): WCValHash<strong>Table</strong>( orig ) {};inline MyHash<strong>Table</strong> &operator=( const MyHash<strong>Table</strong> &orig ) {return( WCValHash<strong>Table</strong>::operator=( orig ) );}Results:See Also:The insert public member function inserts a value into the hash. If the insert is successful, anon-zero will returned. A zero will be returned if the insert fails.operator =, WCExcept::out_<strong>of</strong>_memory170 Hash Containers
WCValHash<strong>Table</strong>::isEmpty(), WCValHashSet::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if the hash is empty.The isEmpty public member function returns zero if it contains at least one entry, non-zero if the hashis empty.buckets, entriesHash Containers 171
WCValHash<strong>Table</strong>::occurencesOf()Synopsis:Semantics:Results:See Also:#include public:unsigned occurrencesOf( const Type & ) const;The occurencesOf public member function is used to return the current number <strong>of</strong> elements storedin the hash which are equivalent to the passed value. Note that equivalence is based on the equivalenceoperator <strong>of</strong> the element type.The occurencesOf public member function returns the number <strong>of</strong> elements in the hash.buckets, entries, find, isEmpty172 Hash Containers
WCValHash<strong>Table</strong>::operator =(), WCValHashSet::operator =()Synopsis:Semantics:Results:See Also:#include public:WCValHashSet & operator =( const WCValHashSet & );WCValHash<strong>Table</strong> & operator =( const WCValHash<strong>Table</strong> & );The operator = public member function is the assignment operator for theWCValHash<strong>Table</strong> and WCValHashSet classes. The left hand side hash is firstcleared using the clear member function, and then the right hand side hash is copied. The hashfunction, exception trap states, and all <strong>of</strong> the hash elements are copied. If an allocation failure occurswhen creating the buckets, the table will be created with zero buckets, and the out_<strong>of</strong>_memoryexception is thrown if it is enabled. If there is not enough memory to copy all <strong>of</strong> the values or pointersin the hash, then only some will be copied, and the out_<strong>of</strong>_memory exception is thrown if it isenabled. The number <strong>of</strong> entries will correctly reflect the number copied.The operator = public member function assigns the left hand side hash to be a copy <strong>of</strong> the righthand side.clear, WCExcept::out_<strong>of</strong>_memoryHash Containers 173
WCValHash<strong>Table</strong>::operator ==(), WCValHashSet::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCValHashSet & ) const;int operator ==( const WCValHash<strong>Table</strong> & ) const;The operator == public member function is the equivalence operator for theWCValHash<strong>Table</strong> and WCValHashSet classes. Two hash objects are equivalentif they are the same object and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side hash are the same object.A FALSE (zero) value is returned otherwise.174 Hash Containers
WCValHash<strong>Table</strong>::remove(), WCValHashSet::remove()Synopsis:Semantics:Results:#include public:int remove( const Type & );The remove public member function is used to remove the specified element from the hash. If anequivalent element is found, a non-zero value is returned. Zero is returned if the element is not found.If the hash is a table and there is more than one element equivalent to the specified element, then thefirst equivalent element added to the table is removed. Note that equivalence is based on theequivalence operator <strong>of</strong> the element type.The element is removed from the hash if it found.Hash Containers 175
WCValHash<strong>Table</strong>::removeAll()Synopsis:Semantics:Results:#include public:unsigned removeAll( const Type & );The removeAll public member function is used to remove all elements equivalent to the specifiedelement from the hash. Zero is returned if no equivalent elements are found. Note that equivalence isbased on the equivalence operator <strong>of</strong> the element type.All equivalent elements are removed from the hash.176 Hash Containers
WCValHash<strong>Table</strong>::resize(), WCValHashSet::resize()Synopsis:Semantics:Results:See Also:#include public:void resize( unsigned );The resize public member function is used to change the number <strong>of</strong> buckets contained in the hash. Ifthe new number is larger than the previous hash size, then the hash function will be used on all <strong>of</strong> thestored elements to determine which bucket they should be stored into. Entries are not destroyed orcreated in the process <strong>of</strong> being moved. If there is not enough memory to resize the hash, theout_<strong>of</strong>_memory exception is thrown if it is enabled, and the hash will contain the number <strong>of</strong> bucketsit contained before the resize. If the new number is zero, then the zero_buckets exception isthrown if it is enabled, and no resize will be performed. The hash is guaranteed to contain the samenumber <strong>of</strong> entries after the resize.The hash is resized to the new number <strong>of</strong> buckets.WCExcept::out_<strong>of</strong>_memory, WCExcept::zero_bucketsHash Containers 177
WCValHash<strong>Table</strong>::resize(), WCValHashSet::resize()178 Hash Containers
11 Hash IteratorsHash iterators are used to step through a hash one or more elements at a time. Iterators which are newlyconstructed or reset are positioned before the first element in the hash. The hash may be traversed oneelement at a time using the pre-increment or call operator. An increment operation causing the iterator tobe positioned after the end <strong>of</strong> the hash returns zero. Further increments will cause the undef_iterexception to be thrown, if it is enabled. The WCIterExcept class provides the common exceptionhandling control interface for all <strong>of</strong> the iterators.Since the iterator classes are all template classes, most <strong>of</strong> the functionality was derived from common baseclasses. In the listing <strong>of</strong> class member functions, those public member functions which appear to be in theiterator class but are actually defined in the common base class are identified as if they were explicitlyspecified in the iterator class.Hash Iterators 179
WCPtrHashDictIterDeclared:wchiter.hThe WCPtrHashDictIter class is the templated class used to create iterator objectsfor WCPtrHashDict objects. In the description <strong>of</strong> each member function, the textKey is used to indicate the template parameter defining the type <strong>of</strong> the indices pointed to by the pointersstored in the dictionary. The text Value is used to indicate the template parameter defining the type <strong>of</strong>the data pointed to by the pointers stored in the dictionary. The WCIterExcept class is a base class<strong>of</strong> the WCPtrHashDictIter class and provides the exceptions memberfunction. This member function controls the exceptions which can be thrown by theWCPtrHashDictIter object. No exceptions are enabled unless they are set by theexceptions member function.Public Member FunctionsThe following member functions are declared in the public interface:WCPtrHashDictIter();WCPtrHashDictIter( const WCPtrHashDict & );~WCPtrHashDictIter();const WCPtrHashDict *container() const;Key *key();void reset();void reset( WCPtrHashDict & );Value * value();Public Member OperatorsThe following member operators are declared in the public interface:int operator ()();int operator ++();180 Hash Iterators
WCPtrHashDictIter::WCPtrHashDictIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrHashDictIter();The public WCPtrHashDictIter constructor is the default constructor for the classand initializes the iterator with no hash to operate on. The reset member function must be called toprovide the iterator with a hash to iterate over.The public WCPtrHashDictIter constructor creates an initializedWCPtrHashDictIter hash iterator object.~WCPtrHashDictIter, resetHash Iterators 181
WCPtrHashDictIter::WCPtrHashDictIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrHashDictIter( WCPtrHashDict & );The public WCPtrHashDictIter constructor is a constructor for the class. Thevalue passed as a parameter is a WCPtrHashDict hash object. The iterator will be initialized for thathash object and positioned before the first hash element. To position the iterator to a valid elementwithin the hash, increment it using one <strong>of</strong> the operator ++ or operator () operators.The public WCPtrHashDictIter constructor creates an initializedWCPtrHashDictIter hash iterator object positioned before the first element in the hash.~WCPtrHashDictIter, operator (), operator ++, reset182 Hash Iterators
WCPtrHashDictIter::~WCPtrHashDictIter()Synopsis:Semantics:Results:See Also:#include public:~WCPtrHashDictIter();The public ~WCPtrHashDictIter destructor is the destructor for the class. Thecall to the destructor is inserted implicitly by the compiler at the point where theWCPtrHashDictIter hash iterator object goes out <strong>of</strong> scope.The WCPtrHashDictIter hash iterator object is destroyed.WCPtrHashDictIterHash Iterators 183
WCPtrHashDictIter::container()Synopsis:Semantics:Results:See Also:#include public:WCPtrHashDict *container() const;The container public member function returns a pointer to the hash container object. If the iteratorhas not been initialized with a hash object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the hash object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a hash.WCPtrHashDictIter, reset, WCIterExcept::undef_iter184 Hash Iterators
WCPtrHashDictIter::key()Synopsis:Semantics:#include public:Key *key();The key public member function returns a pointer to the Key value <strong>of</strong> the hash item at the currentiterator position.If the iterator is not associated with a hash, or the iterator position is either before the first element orpast the last element in the hash, the current iterator position is undefined. In this case theundef_item exception is thrown, if enabled.Results:See Also:A pointer to Key at the current iterator element is returned. If the current element is undefined, anundefined pointer is returned.operator (), operator ++, reset, WCIterExcept::undef_itemHash Iterators 185
WCPtrHashDictIter::operator ()()Synopsis:Semantics:#include public:int operator ()();The operator () public member function is the call operator for the class. The hash element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the hash, the iterator is positioned after the end <strong>of</strong> the hash.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first hash element, the current item will be set to the firstelement. If the hash is empty, the iterator will be positioned after the end <strong>of</strong> the hash.If the iterator is not associated with a hash or the iterator position before the increment was past the lastelement the hash, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a non-zero value if the iterator is positioned on ahash item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the hash.operator ++, reset, WCIterExcept::undef_iter186 Hash Iterators
WCPtrHashDictIter::operator ++()Synopsis:Semantics:#include public:int operator ++();The operator ++ public member function is the pre-increment operator for the class. The hashelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the hash, the iterator is positioned after the end <strong>of</strong> the hash.The operator ++ public member function has the same semantics as the call operator, operator().The current item will be set to the first hash element if the iterator was positioned before the firstelement in the hash. If the hash is empty, the iterator will be positioned after the end <strong>of</strong> the hash.If the iterator is not associated with a hash or the iterator position before the increment was past the lastelement the hash, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a non-zero value if the iterator is positioned on ahash item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the hash.operator (), reset, WCIterExcept::undef_iterHash Iterators 187
WCPtrHashDictIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated hash.The iterator is positioned before the first hash element.WCPtrHashDictIter, container188 Hash Iterators
WCPtrHashDictIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset( WCPtrHashDict & );The reset public member function resets the iterator to operate on the specified hash. The iterator ispositioned before the first element in the hash.The iterator is positioned before the first element <strong>of</strong> the specified hash.WCPtrHashDictIter, containerHash Iterators 189
WCPtrHashDictIter::value()Synopsis:Semantics:#include public:Value *value();The value public member function returns a pointer to the Value the current iterator position.If the iterator is not associated with a hash, or the iterator position is either before the first element orpast the last element in the hash, the current iterator position is undefined. In this case theundef_item exception is thrown, if enabled.Results:See Also:A pointer to the Value at the current iterator element is returned. If the current element is undefined,an undefined pointer is returned.operator (), operator ++, reset, WCIterExcept::undef_item190 Hash Iterators
WCValHashDictIterDeclared:wchiter.hThe WCValHashDictIter class is the templated class used to create iterator objectsfor WCValHashDict objects. In the description <strong>of</strong> each member function, the textKey is used to indicate the template parameter defining the type <strong>of</strong> the indices used to store data in thedictionary. The text Value is used to indicate the template parameter defining the type <strong>of</strong> the datastored in the dictionary. The WCIterExcept class is a base class <strong>of</strong> theWCValHashDictIter class and provides the exceptions member function. Thismember function controls the exceptions which can be thrown by theWCValHashDictIter object. No exceptions are enabled unless they are set by theexceptions member function.Public Member FunctionsThe following member functions are declared in the public interface:WCValHashDictIter();WCValHashDictIter( const WCValHashDict & );~WCValHashDictIter();const WCValHashDict *container() const;Key key();void reset();void reset( WCValHashDict & );Value value();Public Member OperatorsThe following member operators are declared in the public interface:int operator ()();int operator ++();Hash Iterators 191
WCValHashDictIter::WCValHashDictIter()Synopsis:Semantics:Results:See Also:#include public:WCValHashDictIter();The public WCValHashDictIter constructor is the default constructor for the classand initializes the iterator with no hash to operate on. The reset member function must be called toprovide the iterator with a hash to iterate over.The public WCValHashDictIter constructor creates an initializedWCValHashDictIter hash iterator object.~WCValHashDictIter, reset192 Hash Iterators
WCValHashDictIter::WCValHashDictIter()Synopsis:Semantics:Results:See Also:#include public:WCValHashDictIter( WCValHashDict & );The public WCValHashDictIter constructor is a constructor for the class. Thevalue passed as a parameter is a WCValHashDict hash object. The iterator will be initialized for thathash object and positioned before the first hash element. To position the iterator to a valid elementwithin the hash, increment it using one <strong>of</strong> the operator ++ or operator () operators.The public WCValHashDictIter constructor creates an initializedWCValHashDictIter hash iterator object positioned before the first element in the hash.~WCValHashDictIter, operator (), operator ++, resetHash Iterators 193
WCValHashDictIter::~WCValHashDictIter()Synopsis:Semantics:Results:See Also:#include public:~WCValHashDictIter();The public ~WCValHashDictIter destructor is the destructor for the class. Thecall to the destructor is inserted implicitly by the compiler at the point where theWCValHashDictIter hash iterator object goes out <strong>of</strong> scope.The WCValHashDictIter hash iterator object is destroyed.WCValHashDictIter194 Hash Iterators
WCValHashDictIter::container()Synopsis:Semantics:Results:See Also:#include public:WCValHashDict *container() const;The container public member function returns a pointer to the hash container object. If the iteratorhas not been initialized with a hash object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the hash object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a hash.WCValHashDictIter, reset, WCIterExcept::undef_iterHash Iterators 195
WCValHashDictIter::key()Synopsis:Semantics:#include public:Key key();The key public member function returns the value <strong>of</strong> Key at the current iterator position.If the iterator is not associated with a hash, or the iterator position is either before the first element orpast the last element in the hash, the current iterator position is undefined. In this case theundef_item exception is thrown, if enabled.Results:See Also:The value <strong>of</strong> Key at the current iterator element is returned. If the current element is undefined, adefault initialized object is returned.operator (), operator ++, reset, WCIterExcept::undef_item196 Hash Iterators
WCValHashDictIter::operator ()()Synopsis:Semantics:#include public:int operator ()();The operator () public member function is the call operator for the class. The hash element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the hash, the iterator is positioned after the end <strong>of</strong> the hash.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first hash element, the current item will be set to the firstelement. If the hash is empty, the iterator will be positioned after the end <strong>of</strong> the hash.If the iterator is not associated with a hash or the iterator position before the increment was past the lastelement the hash, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a non-zero value if the iterator is positioned on ahash item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the hash.operator ++, reset, WCIterExcept::undef_iterHash Iterators 197
WCValHashDictIter::operator ++()Synopsis:Semantics:#include public:int operator ++();The operator ++ public member function is the pre-increment operator for the class. The hashelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the hash, the iterator is positioned after the end <strong>of</strong> the hash.The operator ++ public member function has the same semantics as the call operator, operator().The current item will be set to the first hash element if the iterator was positioned before the firstelement in the hash. If the hash is empty, the iterator will be positioned after the end <strong>of</strong> the hash.If the iterator is not associated with a hash or the iterator position before the increment was past the lastelement the hash, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a non-zero value if the iterator is positioned on ahash item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the hash.operator (), reset, WCIterExcept::undef_iter198 Hash Iterators
WCValHashDictIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated hash.The iterator is positioned before the first hash element.WCValHashDictIter, containerHash Iterators 199
WCValHashDictIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset( WCValHashDict & );The reset public member function resets the iterator to operate on the specified hash. The iterator ispositioned before the first element in the hash.The iterator is positioned before the first element <strong>of</strong> the specified hash.WCValHashDictIter, container200 Hash Iterators
WCValHashDictIter::value()Synopsis:Semantics:#include public:Value value();The value public member function returns the value <strong>of</strong> Value at the current iterator position.If the iterator is not associated with a hash, or the iterator position is either before the first element orpast the last element in the hash, the current iterator position is undefined. In this case theundef_item exception is thrown, if enabled.Results:See Also:The value <strong>of</strong> the Value at the current iterator element is returned. If the current element is undefined,a default initialized object is returned.operator (), operator ++, reset, WCIterExcept::undef_itemHash Iterators 201
WCPtrHashSetIter, WCPtrHash<strong>Table</strong>IterDeclared:wchiter.hThe WCPtrHashSetIter and WCPtrHash<strong>Table</strong>Iter classes are the templatedclasses used to create iterator objects for WCPtrHash<strong>Table</strong> and WCPtrHashSetobjects. In the description <strong>of</strong> each member function, the text Type is used to indicate the hash elementtype specified as the template parameter. The WCIterExcept class is a base class <strong>of</strong> theWCPtrHashSetIter and WCPtrHash<strong>Table</strong>Iter classes and provides theexceptions member function. This member function controls the exceptions which can be thrownby the WCPtrHashSetIter and WCPtrHash<strong>Table</strong>Iter objects. Noexceptions are enabled unless they are set by the exceptions member function.Public Member FunctionsThe following member functions are declared in the public interface:WCPtrHashSetIter();WCPtrHashSetIter( const WCPtrHashSet & );~WCPtrHashSetIter();WCPtrHash<strong>Table</strong>Iter();WCPtrHash<strong>Table</strong>Iter( const WCPtrHash<strong>Table</strong> & );~WCPtrHash<strong>Table</strong>Iter();const WCPtrHash<strong>Table</strong> *container() const;const WCPtrHashSet *container() const;Type *current() const;void reset();void WCPtrHashSetIter::reset( WCPtrHashSet & );void WCPtrHash<strong>Table</strong>Iter::reset( WCPtrHash<strong>Table</strong> & );Public Member OperatorsThe following member operators are declared in the public interface:int operator ()();int operator ++();202 Hash Iterators
WCPtrHashSetIter::WCPtrHashSetIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrHashSetIter();The public WCPtrHashSetIter constructor is the default constructor for the class andinitializes the iterator with no hash to operate on. The reset member function must be called toprovide the iterator with a hash to iterate over.The public WCPtrHashSetIter constructor creates an initialized WCPtrHashSetIterhash iterator object.~WCPtrHashSetIter, WCPtrHash<strong>Table</strong>Iter, resetHash Iterators 203
WCPtrHashSetIter::WCPtrHashSetIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrHashSetIter( WCPtrHashSet & );The public WCPtrHashSetIter constructor is a constructor for the class. The value passedas a parameter is a WCPtrHashSet hash object. The iterator will be initialized for that hash objectand positioned before the first hash element. To position the iterator to a valid element within the hash,increment it using one <strong>of</strong> the operator ++ or operator () operators.The public WCPtrHashSetIter constructor creates an initialized WCPtrHashSetIterhash iterator object positioned before the first element in the hash.~WCPtrHashSetIter, operator (), operator ++, reset204 Hash Iterators
WCPtrHashSetIter::~WCPtrHashSetIter()Synopsis:Semantics:Results:See Also:#include public:~WCPtrHashSetIter();The public ~WCPtrHashSetIter destructor is the destructor for the class. The call to thedestructor is inserted implicitly by the compiler at the point where the WCPtrHashSetIter hashiterator object goes out <strong>of</strong> scope.The WCPtrHashSetIter hash iterator object is destroyed.WCPtrHashSetIter, WCPtrHash<strong>Table</strong>IterHash Iterators 205
WCPtrHash<strong>Table</strong>Iter::WCPtrHash<strong>Table</strong>Iter()Synopsis:Semantics:Results:See Also:#include public:WCPtrHash<strong>Table</strong>Iter();The public WCPtrHash<strong>Table</strong>Iter constructor is the default constructor for the class andinitializes the iterator with no hash to operate on. The reset member function must be called toprovide the iterator with a hash to iterate over.The public WCPtrHash<strong>Table</strong>Iter constructor creates an initializedWCPtrHash<strong>Table</strong>Iter hash iterator object.~WCPtrHash<strong>Table</strong>Iter, WCPtrHashSetIter, reset206 Hash Iterators
WCPtrHash<strong>Table</strong>Iter::WCPtrHash<strong>Table</strong>Iter()Synopsis:Semantics:Results:See Also:#include public:WCPtrHash<strong>Table</strong>Iter( WCPtrHash<strong>Table</strong> & );The public WCPtrHash<strong>Table</strong>Iter constructor is a constructor for the class. The valuepassed as a parameter is a WCPtrHash<strong>Table</strong> hash object. The iterator will be initialized for that hashobject and positioned before the first hash element. To position the iterator to a valid element within thehash, increment it using one <strong>of</strong> the operator ++ or operator () operators.The public WCPtrHash<strong>Table</strong>Iter constructor creates an initializedWCPtrHash<strong>Table</strong>Iter hash iterator object positioned before the first element in the hash.~WCPtrHash<strong>Table</strong>Iter, operator (), operator ++, resetHash Iterators 207
WCPtrHash<strong>Table</strong>Iter::~WCPtrHash<strong>Table</strong>Iter()Synopsis:Semantics:Results:See Also:#include public:~WCPtrHash<strong>Table</strong>Iter();The WCPtrHash<strong>Table</strong>Iter destructor is the destructor for the class. The call to thedestructor is inserted implicitly by the compiler at the point where the WCPtrHash<strong>Table</strong>Iter hashiterator object goes out <strong>of</strong> scope.The WCPtrHash<strong>Table</strong>Iter hash iterator object is destroyed.WCPtrHashSetIter, WCPtrHash<strong>Table</strong>Iter208 Hash Iterators
WCPtrHashSetIter,WCPtrHash<strong>Table</strong>Iter::container()Synopsis:Semantics:Results:See Also:#include public:WCPtrHash<strong>Table</strong> *WCPtrHash<strong>Table</strong>Iter::container() const;WCPtrHashSet *WCPtrHashSetIter::container() const;The container public member function returns a pointer to the hash container object. If the iteratorhas not been initialized with a hash object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the hash object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a hash.WCPtrHashSetIter, WCPtrHash<strong>Table</strong>Iter, reset, WCIterExcept::undef_iterHash Iterators 209
WCPtrHashSetIter::current(), WCPtrHash<strong>Table</strong>Iter::current()Synopsis:Semantics:#include public:Type *current();The current public member function returns a pointer to the hash item at the current iterator position.If the iterator is not associated with a hash, or the iterator position is either before the first element orpast the last element in the hash, the current iterator position is undefined. In this case theundef_item exception is thrown, if enabled.Results:See Also:A pointer to the current iterator element is returned. If the current element is undefined, NULL(0) isreturned.operator (), operator ++, reset, WCIterExcept::undef_item210 Hash Iterators
WCPtrHashSetIter,WCPtrHash<strong>Table</strong>Iter::operator ()()Synopsis:Semantics:#include public:int operator ()();The operator () public member function is the call operator for the class. The hash element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the hash, the iterator is positioned after the end <strong>of</strong> the hash.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first hash element, the current item will be set to the firstelement. If the hash is empty, the iterator will be positioned after the end <strong>of</strong> the hash.If the iterator is not associated with a hash or the iterator position before the increment was past the lastelement the hash, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a non-zero value if the iterator is positioned on ahash item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the hash.operator ++, reset, WCIterExcept::undef_iterHash Iterators 211
WCPtrHashSetIter,WCPtrHash<strong>Table</strong>Iter::operator ++()Synopsis:Semantics:#include public:int operator ++();The operator ++ public member function is the pre-increment operator for the class. The hashelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the hash, the iterator is positioned after the end <strong>of</strong> the hash.The operator ++ public member function has the same semantics as the call operator, operator().The current item will be set to the first hash element if the iterator was positioned before the firstelement in the hash. If the hash is empty, the iterator will be positioned after the end <strong>of</strong> the hash.If the iterator is not associated with a hash or the iterator position before the increment was past the lastelement the hash, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a non-zero value if the iterator is positioned on ahash item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the hash.current, operator (), reset, WCIterExcept::undef_iter212 Hash Iterators
WCPtrHashSetIter::reset(), WCPtrHash<strong>Table</strong>Iter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated hash.The iterator is positioned before the first hash element.WCPtrHashSetIter, WCPtrHash<strong>Table</strong>Iter, containerHash Iterators 213
WCPtrHashSetIter::reset(), WCPtrHash<strong>Table</strong>Iter::reset()Synopsis:Semantics:Results:See Also:#include public:void WCPtrHashSetIter::reset( WCPtrHashSet & );void WCPtrHash<strong>Table</strong>Iter::reset( WCPtrHash<strong>Table</strong> & );The reset public member function resets the iterator to operate on the specified hash. The iterator ispositioned before the first element in the hash.The iterator is positioned before the first element <strong>of</strong> the specified hash.WCPtrHashSetIter, WCPtrHash<strong>Table</strong>Iter, container214 Hash Iterators
WCValHashSetIter, WCValHash<strong>Table</strong>IterDeclared:wchiter.hThe WCValHashSetIter and WCValHash<strong>Table</strong>Iter classes are the templatedclasses used to create iterator objects for WCValHash<strong>Table</strong> and WCValHashSetobjects. In the description <strong>of</strong> each member function, the text Type is used to indicate the hash elementtype specified as the template parameter. The WCIterExcept class is a base class <strong>of</strong> theWCValHashSetIter and WCValHash<strong>Table</strong>Iter classes and provides theexceptions member function. This member function controls the exceptions which can be thrownby the WCValHashSetIter and WCValHash<strong>Table</strong>Iter objects. Noexceptions are enabled unless they are set by the exceptions member function.Public Member FunctionsThe following member functions are declared in the public interface:WCValHashSetIter();WCValHashSetIter( const WCValHashSet & );~WCValHashSetIter();WCValHash<strong>Table</strong>Iter();WCValHash<strong>Table</strong>Iter( const WCValHash<strong>Table</strong> & );~WCValHash<strong>Table</strong>Iter();const WCValHash<strong>Table</strong> *container() const;const WCValHashSet *container() const;Type current() const;void reset();void WCValHashSetIter::reset( WCValHashSet & );void WCValHash<strong>Table</strong>Iter::reset( WCValHash<strong>Table</strong> & );Public Member OperatorsThe following member operators are declared in the public interface:int operator ()();int operator ++();Hash Iterators 215
WCValHashSetIter::WCValHashSetIter()Synopsis:Semantics:Results:See Also:#include public:WCValHashSetIter();The public WCValHashSetIter constructor is the default constructor for the class andinitializes the iterator with no hash to operate on. The reset member function must be called toprovide the iterator with a hash to iterate over.The public WCValHashSetIter constructor creates an initialized WCValHashSetIterhash iterator object.~WCValHashSetIter, WCValHash<strong>Table</strong>Iter, reset216 Hash Iterators
WCValHashSetIter::WCValHashSetIter()Synopsis:Semantics:Results:See Also:#include public:WCValHashSetIter( WCValHashSet & );The public WCValHashSetIter constructor is a constructor for the class. The value passedas a parameter is a WCValHashSet hash object. The iterator will be initialized for that hash objectand positioned before the first hash element. To position the iterator to a valid element within the hash,increment it using one <strong>of</strong> the operator ++ or operator () operators.The public WCValHashSetIter constructor creates an initialized WCValHashSetIterhash iterator object positioned before the first element in the hash.~WCValHashSetIter, operator (), operator ++, resetHash Iterators 217
WCValHashSetIter::~WCValHashSetIter()Synopsis:Semantics:Results:See Also:#include public:~WCValHashSetIter();The public ~WCValHashSetIter destructor is the destructor for the class. The call to thedestructor is inserted implicitly by the compiler at the point where the WCValHashSetIter hashiterator object goes out <strong>of</strong> scope.The WCValHashSetIter hash iterator object is destroyed.WCValHashSetIter, WCValHash<strong>Table</strong>Iter218 Hash Iterators
WCValHash<strong>Table</strong>Iter::WCValHash<strong>Table</strong>Iter()Synopsis:Semantics:Results:See Also:#include public:WCValHash<strong>Table</strong>Iter();The public WCValHash<strong>Table</strong>Iter constructor is the default constructor for the class andinitializes the iterator with no hash to operate on. The reset member function must be called toprovide the iterator with a hash to iterate over.The public WCValHash<strong>Table</strong>Iter constructor creates an initializedWCValHash<strong>Table</strong>Iter hash iterator object.~WCValHash<strong>Table</strong>Iter, WCValHashSetIter, resetHash Iterators 219
WCValHash<strong>Table</strong>Iter::WCValHash<strong>Table</strong>Iter()Synopsis:Semantics:Results:See Also:#include public:WCValHash<strong>Table</strong>Iter( WCValHash<strong>Table</strong> & );The public WCValHash<strong>Table</strong>Iter constructor is a constructor for the class. The valuepassed as a parameter is a WCValHash<strong>Table</strong> hash object. The iterator will be initialized for that hashobject and positioned before the first hash element. To position the iterator to a valid element within thehash, increment it using one <strong>of</strong> the operator ++ or operator () operators.The public WCValHash<strong>Table</strong>Iter constructor creates an initializedWCValHash<strong>Table</strong>Iter hash iterator object positioned before the first element in the hash.~WCValHash<strong>Table</strong>Iter, operator (), operator ++, reset220 Hash Iterators
WCValHash<strong>Table</strong>Iter::~WCValHash<strong>Table</strong>Iter()Synopsis:Semantics:Results:See Also:#include public:~WCValHash<strong>Table</strong>Iter();The WCValHash<strong>Table</strong>Iter destructor is the destructor for the class. The call to thedestructor is inserted implicitly by the compiler at the point where the WCValHash<strong>Table</strong>Iter hashiterator object goes out <strong>of</strong> scope.The WCValHash<strong>Table</strong>Iter hash iterator object is destroyed.WCValHashSetIter, WCValHash<strong>Table</strong>IterHash Iterators 221
WCValHashSetIter,WCValHash<strong>Table</strong>Iter::container()Synopsis:Semantics:Results:See Also:#include public:WCValHash<strong>Table</strong> *WCValHash<strong>Table</strong>Iter::container() const;WCValHashSet *WCValHashSetIter::container() const;The container public member function returns a pointer to the hash container object. If the iteratorhas not been initialized with a hash object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the hash object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a hash.WCValHashSetIter, WCValHash<strong>Table</strong>Iter, reset, WCIterExcept::undef_iter222 Hash Iterators
WCValHashSetIter::current(), WCValHash<strong>Table</strong>Iter::current()Synopsis:Semantics:#include public:Type current();The current public member function returns the value <strong>of</strong> the hash element at the current iteratorposition.If the iterator is not associated with a hash, or the iterator position is either before the first element orpast the last element in the hash, the current iterator position is undefined. In this case theundef_item exception is thrown, if enabled.Results:See Also:The value at the current iterator element is returned. If the current element is undefined, a defaultinitialized object is returned.operator (), operator ++, reset, WCIterExcept::undef_itemHash Iterators 223
WCValHashSetIter,WCValHash<strong>Table</strong>Iter::operator ()()Synopsis:Semantics:#include public:int operator ()();The operator () public member function is the call operator for the class. The hash element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the hash, the iterator is positioned after the end <strong>of</strong> the hash.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first hash element, the current item will be set to the firstelement. If the hash is empty, the iterator will be positioned after the end <strong>of</strong> the hash.If the iterator is not associated with a hash or the iterator position before the increment was past the lastelement the hash, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a non-zero value if the iterator is positioned on ahash item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the hash.operator ++, reset, WCIterExcept::undef_iter224 Hash Iterators
WCValHashSetIter,WCValHash<strong>Table</strong>Iter::operator ++()Synopsis:Semantics:#include public:int operator ++();The operator ++ public member function is the pre-increment operator for the class. The hashelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the hash, the iterator is positioned after the end <strong>of</strong> the hash.The operator ++ public member function has the same semantics as the call operator, operator().The current item will be set to the first hash element if the iterator was positioned before the firstelement in the hash. If the hash is empty, the iterator will be positioned after the end <strong>of</strong> the hash.If the iterator is not associated with a hash or the iterator position before the increment was past the lastelement the hash, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a non-zero value if the iterator is positioned on ahash item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the hash.current, operator (), reset, WCIterExcept::undef_iterHash Iterators 225
WCValHashSetIter::reset(), WCValHash<strong>Table</strong>Iter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated hash.The iterator is positioned before the first hash element.WCValHashSetIter, WCValHash<strong>Table</strong>Iter, container226 Hash Iterators
WCValHashSetIter::reset(), WCValHash<strong>Table</strong>Iter::reset()Synopsis:Semantics:Results:See Also:#include public:void WCValHashSetIter::reset( WCValHashSet & );void WCValHash<strong>Table</strong>Iter::reset( WCValHash<strong>Table</strong> & );The reset public member function resets the iterator to operate on the specified hash. The iterator ispositioned before the first element in the hash.The iterator is positioned before the first element <strong>of</strong> the specified hash.WCValHashSetIter, WCValHash<strong>Table</strong>Iter, containerHash Iterators 227
WCValHashSetIter::reset(), WCValHash<strong>Table</strong>Iter::reset()228 Hash Iterators
12 List ContainersList containers are single or double linked lists. The choice <strong>of</strong> which type <strong>of</strong> list to use is determined by thedirection in which the list is traversed and by what is stored in the list. A list to which items are just addedand removed may be most efficiently implemented as a single linked list. If frequent retrievals <strong>of</strong> items atgiven indexes within the list are made, double linked lists can <strong>of</strong>fer some improved search performance.There are three sets <strong>of</strong> list container classes: value, pointer and intrusive.Value lists are the simplest to use but have the most requirements on the type stored in the lists. Copies aremade <strong>of</strong> the values stored in the list, which could be undesirable if the stored objects are complicated andcopying is expensive. Value lists should not be used to store objects <strong>of</strong> a base class if any derived types <strong>of</strong>different sizes would be stored in the list, or if the destructor for the derived class must be called. TheWCValSList container class implements single linked value lists, and theWCValDList class double linked value lists.Pointer list elements store pointers to objects. No creating, copying or destroying <strong>of</strong> objects stored in thelist occurs. The only requirement <strong>of</strong> the type pointed to is that an equivalence operator is provided so thatlookups can be performed. The WCPtrSList class implements single linked pointer lists, andthe WCPtrDList class double linked pointer lists.Intrusive lists require that the list elements are objects derived from the WCSLink or WCDLink class,depending on whether a single or double linked list is used. The list classes require nothing else from thelist elements. No creating, destroying or copying <strong>of</strong> any object is performed by the intrusive list classes,and must be done by the user <strong>of</strong> the class. One advantage <strong>of</strong> an intrusive list is a list element can beremoved from one list and inserted into another list without creating new list element objects or deletingold objects. The WCIsvSList class implements single linked intrusive lists, and theWCIsvDList class double linked intrusive lists.A list may be traversed using the corresponding list iterator class. Iterators allow lists to be steppedthrough one or more elements at a time. The iterator classes which correspond to single linked listcontainers have some functionality inhibited. If backward traversal is required, the double linkedcontainers and iterators must be used.The classes are presented in alphabetical order. The WCSLink and WCDLink class provide a commoncontrol interface for the list elements for the intrusive classes.Since the container classes are all template classes, deriving most <strong>of</strong> the functionality from common baseclasses was used. In the listing <strong>of</strong> class member functions, those public member functions which appear tobe in the container class but are actually defined in the common base class are identified as if they wereexplicitly specified in the container class.List Containers 229
WCDLinkDeclared:wclcom.hDerived from: WCSLinkThe WCDLink class is the building block for all <strong>of</strong> the double linked list classes. It is implemented interms <strong>of</strong> the WCSLink base class. Since no user data is stored directly with it, the WCDLink classshould only be used as a base class to derive a user defined class.When creating a double linked intrusive list, the WCDLink class is used to derive the user defined classthat holds the data to be inserted into the list.The wclcom.h header file is included by the wclist.h header file. There is no need to explicitlyinclude the wclcom.h header file unless the wclist.h header file is not included. No errors willresult if it is included.Note that the destructor is non-virtual so that list elements are <strong>of</strong> minimum size. Objects created as aclass derived from the WCDLink class, but destroyed while typed as a WCDLink object will not invokethe destructor <strong>of</strong> the derived class.Public Member FunctionsThe following public member functions are declared:WCDLink();~WCDLink();See Also:WCSLink230 List Containers
WCDLink::WCDLink()Synopsis:Semantics:Results:See Also:#include public:WCDLink();The public WCDLink constructor creates an WCDLink object. The public WCDLink constructor isused implicitly by the compiler when it generates a constructor for a derived class.The public WCDLink constructor produces an initialized WCDLink object.~WCDLinkList Containers 231
WCDLink::~WCDLink()Synopsis:Semantics:Results:See Also:#include public:~WCDLink();The public ~WCDLink destructor does not do anything explicit. The call to the public ~WCDLinkdestructor is inserted implicitly by the compiler at the point where the object derived from WCDLinkgoes out <strong>of</strong> scope.The object derived from WCDLink is destroyed.WCDLink232 List Containers
WCIsvSList, WCIsvDListDeclared:wclist.hThe WCIsvSList and WCIsvDList classes are the templated classes used tocreate objects which are single or double linked lists. The created list is intrusive, which means that listelements which are inserted must be created with a library supplied base class. The class WCSLinkprovides the base class definition for single linked lists, and should be inherited by the definition <strong>of</strong> anylist item for single linked lists. It provides the linkage that is used to traverse the list elements.Similarly, the class WCDLink provides the base class definition for double lists, and should be inheritedby the definition <strong>of</strong> any list item for double lists.In the description <strong>of</strong> each member function, the text Type is used to indicate the type value specified asthe template parameter. Type is the type <strong>of</strong> the list elements, derived from WCSLink or WCDLink.The WCExcept class is a base class <strong>of</strong> the WCIsvSList and WCIsvDList classesand provides the exceptions member function. This member function controls the exceptions whichcan be thrown by the WCIsvSList and WCIsvDList objects. No exceptions areenabled unless they are set by the exceptions member function.Requirements <strong>of</strong> TypeThe WCIsvSList class requires only that Type is derived from WCSLink. TheWCIsvDList class requires only that Type is derived from WCDLink.Private Member FunctionsIn an intrusive list, copying a list is undefined. Setting the copy constructor and assignment operator asprivate is the standard mechanism to ensure a copy cannot be made. The following member functionsare declared private:void WCIsvSList( const WCIsvSList & );void WCIsvDList( const WCIsvDList & );WCIsvSList & WCIsvSList::operator =( const WCIsvSList & );WCIsvDList & WCIsvDList::operator =( const WCIsvDList & );Public Member FunctionsThe following member functions are declared in the public interface:WCIsvSList();~WCIsvSList();WCIsvDList();~WCIsvDList();int append( Type * );void clear();void clearAndDestroy();int contains( const Type * ) const;int entries() const;Type * find( int = 0 ) const;Type * findLast() const;void forAll( void (*)( Type *, void * ), void *);Type * get( int = 0 );int index( const Type * ) const;int index( int (*)( const Type *, void * ), void * ) const;int insert( Type * );int isEmpty() const;List Containers 233
WCIsvSList, WCIsvDListPublic Member OperatorsThe following member operators are declared in the public interface:int WCIsvSList::operator ==( const WCIsvSList & ) const;int WCIsvDList::operator ==( const WCIsvDList & ) const;Sample Program Using an Intrusive List#include #include class int_ddata : public WCDLink {public:inline int_ddata() {};inline int_ddata() {};inline int_ddata( int datum ) : info( datum ) {};};intinfo;static void test1( void );void data_isv_prt( int_ddata * data, void * str ) {cout
WCIsvSList::WCIsvSList()Synopsis:Semantics:Results:See Also:#include public:WCIsvSList();The WCIsvSList public member function creates an empty WCIsvSList object.The WCIsvSList public member function produces an initialized WCIsvSList object.~WCIsvSListList Containers 235
WCIsvSList::WCIsvSList()Synopsis:Semantics:#include private:void WCIsvSList( const WCIsvSList & );The WCIsvSList private member function is the copy constructor for the single linked list class.Making a copy <strong>of</strong> the list object would result in a error condition, since intrusive lists cannot share dataitems with other lists.236 List Containers
WCIsvSList::~WCIsvSList()Synopsis:Semantics:Results:See Also:#include public:~WCIsvSList();The ~WCIsvSList public member function destroys the WCIsvSList object. If the list is notempty and the not_empty exception is enabled, the exception is thrown. If the not_emptyexception is not enabled and the list is not empty, the list is cleared using the clear member function.The call to the ~WCIsvSList public member function is inserted implicitly by the compiler at thepoint where the WCIsvSList object goes out <strong>of</strong> scope.The WCIsvSList object is destroyed.WCIsvSList, clear, clearAndDestroy, WCExcept::not_emptyList Containers 237
WCIsvDList::WCIsvDList()Synopsis:Semantics:Results:See Also:#include public:WCIsvDList();The WCIsvDList public member function creates an empty WCIsvDList object.The WCIsvDList public member function produces an initialized WCIsvDList object.~WCIsvDList238 List Containers
WCIsvDList::WCIsvDList()Synopsis:Semantics:#include private:WCIsvDList( const WCIsvDList & );The WCIsvDList private member function is the copy constructor for the double linked list class.Making a copy <strong>of</strong> the list object would result in a error condition, since intrusive lists cannot share dataitems with other lists.List Containers 239
WCIsvDList::~WCIsvDList()Synopsis:Semantics:Results:See Also:#include public:~WCIsvDList();The ~WCIsvDList public member function destroys the WCIsvDList object. If the list is notempty and the not_empty exception is enabled, the exception is thrown. If the not_emptyexception is not enabled and the list is not empty, the list is cleared using the clear member function.The call to the ~WCIsvDList public member function is inserted implicitly by the compiler at thepoint where the WCIsvDList object goes out <strong>of</strong> scope.The WCIsvDList object is destroyed.WCIsvDList, clear, clearAndDestroy, WCExcept::not_empty240 List Containers
WCIsvSList::append(), WCIsvDList::append()Synopsis:Semantics:#include public:int append( Type * );The append public member function is used to append the list element object to the end <strong>of</strong> the list.The address <strong>of</strong> (a pointer to) the list element object should be passed, not the value. Since the linkageinformation is stored in the list element, it is not possible for the element to be in more than one list, orin the same list more than once.The passed list element should be constructed using the appropriate link class as a base. WCSLinkmust be used as a list element base class for single linked lists, and WCDLink must be used as a listelement base class for double linked lists.Results:See Also:The list element is appended to the end <strong>of</strong> the list and a TRUE value (non-zero) is returned.insertList Containers 241
WCIsvSList::clear(), WCIsvDList::clear()Synopsis:Semantics:#include public:void clear();The clear public member function is used to clear the list object and set it to the state <strong>of</strong> the objectjust after the initial construction. The list object is not destroyed and re-created by this operator, so theobject destructor is not invoked. The list elements are not cleared. Any list items still in the list are lostunless pointed to by some pointer object in the program code.If any <strong>of</strong> the list elements are not allocated with new (local variable or global list elements), then theclear public member function must be used. When all list elements are allocated with new, theclearAndDestory member function should be used.Results:The clear public member function resets the list object to the state <strong>of</strong> the object immediately after theinitial construction.See Also: ~WCIsvSList, ~WCIsvDList, clearAndDestroy, get, operator =242 List Containers
WCIsvSList,WCIsvDList::clearAndDestroy()Synopsis:Semantics:#include public:void clearAndDestroy();The clearAndDestroy public member function is used to clear the list object and set it to the state<strong>of</strong> the object just after the initial construction. The list object is not destroyed and re-created by thisoperator, so the object destructor is not invoked. The link elements are deleted before the list isre-initialized.If any elements in the list were not allocated by the new operator, the clearAndDestroy publicmember function must not be called. The clearAndDestroy public member function destroys eachlist element with the destructor for Type even if the list element was created as an object derived fromType, unless Type has a pure virtual destructor.Results:See Also:The clearAndDestroy public member function resets the list object to the initial state <strong>of</strong> the objectimmediately after the initial construction and deletes the list elements.clear, getList Containers 243
WCIsvSList::contains(), WCIsvDList::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Type * ) const;The contains public member function is used to determine if a list element object is alreadycontained in the list. The address <strong>of</strong> (a pointer to) the list element object should be passed, not thevalue. Each list element is compared to the passed element object to determine if it has the sameaddress. Note that the comparison is <strong>of</strong> the addresses <strong>of</strong> the elements, not the contained values.Zero(0) is returned if the passed list element object is not found in the list. A non-zero result is returnedif the element is found in the list.find, index244 List Containers
WCIsvSList::entries(), WCIsvDList::entries()Synopsis:Semantics:Results:See Also:#include public:int entries() const;The entries public member function is used to determine the number <strong>of</strong> list elements contained inthe list object.The number <strong>of</strong> entries stored in the list is returned, zero(0) is returned if there are no list elements.isEmptyList Containers 245
WCIsvSList::find(), WCIsvDList::find()Synopsis:Semantics:#include public:Type * find( int = 0 ) const;The find public member function returns a pointer to a list element in the list object. The list elementis not removed from the list, so care must be taken not to delete the element returned to you. Theoptional parameter specifies which element to locate, and defaults to the first element. Since the firstelement <strong>of</strong> the list is the zero’th element, the last element will be the number <strong>of</strong> list entries minus one.If the list is empty and the empty_container exception is enabled, the exception is thrown. If theindex_range exception is enabled, the exception is thrown if the index value is negative or is greaterthan the number <strong>of</strong> list entries minus one.Results:See Also:A pointer to the selected list element or the closest list element is returned. If the index value isnegative, the closest list element is the first element. The last element is the closest element if the indexvalue is greater than the number <strong>of</strong> list entries minus one. A value <strong>of</strong> NULL(0) is returned if there areno elements in the list.findLast, get, index, isEmpty, WCExcept::empty_container,WCExcept::index_range246 List Containers
WCIsvSList::findLast(), WCIsvDList::findLast()Synopsis:Semantics:#include public:Type * findLast() const;The findLast public member function returns a pointer to the last list element in the list object. Thelist element is not removed from the list, so care must be taken not to delete the element returned to you.If the list is empty, one <strong>of</strong> two exceptions can be thrown. If the empty_container exception isenabled, it is thrown. The index_range exception is thrown if it is enabled and theempty_container exception is not enabled.Results:See Also:A pointer to the last list element is returned. A value <strong>of</strong> NULL(0) is returned if there are no elements inthe list.find, get, isEmpty, WCExcept::empty_container, WCExcept::index_rangeList Containers 247
WCIsvSList::forAll(), WCIsvDList::forAll()Synopsis:Semantics:#include public:void forAll( void (*fn)( Type *, void * ), void *);The forAll public member function is used to cause the function fn to be invoked for each listelement. The fn function should have the prototypevoid (*fn)( Type *, void * )The first parameter <strong>of</strong> fn shall accept a pointer to the list element currently active. The second argumentpassed to fn is the second argument <strong>of</strong> the forAll function. This allows a callback function to bedefined which can accept data appropriate for the point at which the forAll function is invoked.See Also:WCIsvConstSListIter, WCIsvConstDListIter, WCIsvSListIter, WCIsvDListIter248 List Containers
WCIsvSList::get(), WCIsvDList::get()Synopsis:Semantics:#include public:Type * get( int = 0 );The get public member function returns a pointer to a list element in the list object. The list element isalso removed from the list. The optional parameter specifies which element to remove, and defaults tothe first element. Since the first element <strong>of</strong> the list is the zero’th element, the last element will be thenumber <strong>of</strong> list entries minus one.If the list is empty and the empty_container exception is enabled, the exception is thrown. If theindex_range exception trap is enabled, the exception is thrown if the index value is negative or isgreater than the number <strong>of</strong> list entries minus one.Results:See Also:A pointer to the selected list element or the closest list element is removed and returned. If the indexvalue is negative, the closest list element is the first element. The last element is the closest element ifthe index value is greater than the number <strong>of</strong> list entries minus one. A value <strong>of</strong> NULL(0) is returned ifthere are no elements in the list.clear, clearAndDestroy, find, index, WCExcept::empty_container,WCExcept::index_rangeList Containers 249
WCIsvSList::index(), WCIsvDList::index()Synopsis:Semantics:Results:See Also:#include public:int index( const Type * ) const;The index public member function is used to determine the index <strong>of</strong> the first list element equivalent tothe passed element. The address <strong>of</strong> (a pointer to) the list element object should be passed, not the value.Each list element is compared to the passed element object to determine if it has the same address. Notethat the comparison is <strong>of</strong> the addresses <strong>of</strong> the elements, not the contained values.The index <strong>of</strong> the first element equivalent to the passed element is returned. If the passed element is notin the list, negative one (-1) is returned.contains, find, get250 List Containers
WCIsvSList::index(), WCIsvDList::index()Synopsis:Semantics:#include public:int index( int (*test_fn)( const Type *, void * ),void * ) const;The index public member function is used to determine the index <strong>of</strong> the first list element for which thesupplied test_fn function returns true. The test_fn function must have the prototype:int (*test_fn)( const Type *, void * );Each list element is passed in turn to the test_fn function as the first argument. The second parameterpassed is the second argument <strong>of</strong> the index function. This allows the test_fn callback function toaccept data appropriate for the point at which the index function is invoked. The supplied test_fnshall return a TRUE (non-zero) value when the index <strong>of</strong> the passed element is desired. Otherwise, aFALSE (zero) value shall be returned.Results:See Also:The index <strong>of</strong> the first list element for which the test_fn function returns non-zero is returned. If thetest_fn function returns zero for all list elements, negative one (-1) is returned.contains, find, getList Containers 251
WCIsvSList::insert(), WCIsvDList::insert()Synopsis:Semantics:#include public:int insert( Type * );The insert public member function is used to insert the list element object to the beginning <strong>of</strong> thelist. The address <strong>of</strong> (a pointer to) the list element object should be passed, not the value. Since thelinkage information is stored in the list element, it is not possible for the element to be in more than onelist, or in the same list more than once.The passed list element should be constructed using the appropriate link class as a base. WCSLinkmust be used as a list element base class for single linked lists, and WCDLink must be used as a listelement base class for double linked lists.Results:See Also:The list element is inserted as the first element <strong>of</strong> the list and a TRUE value (non-zero) is returned.append252 List Containers
WCIsvSList::isEmpty(), WCIsvDList::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if a list object has any list elementscontained in it.A TRUE value (non-zero) is returned if the list object does not have any list elements contained withinit. A FALSE (zero) result is returned if the list contains at least one element.entriesList Containers 253
WCIsvSList::operator =(), WCIsvDList::operator =()Synopsis:Semantics:#include private:WCIsvSList & WCIsvSList::operator =( const WCIsvSList & );WCIsvDList & WCIsvDList::operator =( const WCIsvDList & );The operator = private member function is the assignment operator for the class. Since making acopy <strong>of</strong> the list object would result in a error condition, it is made inaccessible by making it a privateoperator.254 List Containers
WCIsvSList::operator ==(), WCIsvDList::operator ==()Synopsis:Semantics:Results:#include public:int WCIsvSList::operator ==( const WCIsvSList & ) const;int WCIsvDList::operator ==( const WCIsvDList & ) const;The operator == public member function is the equivalence operator for theWCIsvSList and WCIsvDList classes. Two list objects are equivalent if they arethe same object and share the same address.A TRUE (non-zero) value is returned if the left hand side object and the right hand side objects are thesame object. A FALSE (zero) value is returned otherwise.List Containers 255
WCPtrSList, WCPtrDListDeclared:wclist.hThe WCPtrSList and WCPtrDList classes are the templated classes used tocreate objects which are single or double linked lists.In the description <strong>of</strong> each member function, the text Type is used to indicate the type value specified asthe template parameter. The pointers stored in the list point to values <strong>of</strong> type Type.The WCExcept class is a base class <strong>of</strong> the WCPtrSList and WCPtrDList classesand provides the exceptions member function. This member function controls the exceptions whichcan be thrown by the WCPtrSList and WCPtrDList objects. No exceptions areenabled unless they are set by the exceptions member function.Requirements <strong>of</strong> TypeThe WCPtrSList and WCPtrDList classes requires Type to have:(1) an equivalence operator with constant parametersType::operator ==( const Type & ) constPublic Member FunctionsThe following member functions are declared in the public interface:WCPtrSList();WCPtrSList( void * (*)( size_t ), void (*)( void *, size_t ));WCPtrSList( const WCPtrSList & );~WCPtrSList();WCPtrDList();WCPtrDList( void * (*)( size_t ), void (*)( void *, size_t ));WCPtrDList( const WCPtrDList & );~WCPtrDList();int append( Type * );void clear();void clearAndDestroy();int contains( const Type * ) const;int entries() const;Type * find( int = 0 ) const;Type * findLast() const;void forAll( void (*)( Type *, void * ), void *) const;Type * get( int = 0 );int index( const Type * ) const;int insert( Type * );int isEmpty() const;Public Member OperatorsThe following member operators are declared in the public interface:WCPtrSList & WCPtrSList::operator =( const WCPtrSList & );WCPtrDList & WCPtrDList::operator =( const WCPtrDList & );int WCPtrSList::operator ==( const WCPtrSList & ) const;int WCPtrDList::operator ==( const WCPtrDList & ) const;Sample Program Using a Pointer List256 List Containers
WCPtrSList, WCPtrDList#include #include static void test1( void );void data_ptr_prt( int * data, void * str ) {cout
WCPtrSList::WCPtrSList()Synopsis:Semantics:Results:See Also:#include public:WCPtrSList();The WCPtrSList public member function creates an empty WCPtrSList object.The WCPtrSList public member function produces an initialized WCPtrSList object.WCPtrSList, ~WCPtrSList258 List Containers
WCPtrSList::WCPtrSList()Synopsis:Semantics:#include public:WCPtrSList( void *(*allocator)( size_t ),void (*deallocator)( void *, size_t ) );The WCPtrSList public member function creates an empty WCPtrSList object. Theallocator function is registered to perform all memory allocations <strong>of</strong> the list elements, and thedeallocator function to perform all freeing <strong>of</strong> the list elements’ memory. These functions provide theability to control how the allocation and freeing <strong>of</strong> memory is performed, allowing for more efficientmemory handling than the general purpose global operator new() and operator delete()can provide. Memory management optimizations may potentially be made through the allocator anddeallocator functions, but are not recommended before managing memory is understood anddetermined to be worth while.The allocator function shall return a pointer to allocated memory <strong>of</strong> size at least the argument, orzero(0) if the allocation cannot be performed. Initialization <strong>of</strong> the memory returned is performed by theWCPtrSList class.The WCPtrSList class calls the deallocator function only on memory allocated by theallocator function. The deallocator shall free the memory pointed to by the first argument which is <strong>of</strong>size the second argument. The size passed to the deallocator function is guaranteed to be the same sizepassed to the allocator function when the memory was allocated.The allocator and deallocator functions may assume that for a list object instance, the allocator isalways called with the same first argument (the size <strong>of</strong> the memory to be allocated). TheWCValSListItemSize(Type) macro returns the size <strong>of</strong> the elements which are allocated by theallocator function.Results:See Also:The WCPtrSList public member function creates an initialized WCPtrSList object andregisters the allocator and deallocator functions.WCPtrSList, ~WCPtrSListList Containers 259
WCPtrSList::WCPtrSList()Synopsis:Semantics:#include public:void WCPtrSList( const WCPtrSList & );The WCPtrSList public member function is the copy constructor for the single linked list class. All<strong>of</strong> the list elements are copied to the new list, as well as the exception trap states, and any registeredallocator and deallocator functions.If all <strong>of</strong> the elements cannot be copied and the out_<strong>of</strong>_memory is enabled in the list being copied,the exception is thrown. The new list is created in a valid state, even if all <strong>of</strong> the list elements could notbe copied.Results:See Also:The WCPtrSList public member function produces a copy <strong>of</strong> the list.WCPtrSList, ~WCPtrSList, clear, WCExcept::out_<strong>of</strong>_memory260 List Containers
WCPtrSList::~WCPtrSList()Synopsis:Semantics:Results:See Also:#include public:~WCPtrSList();The ~WCPtrSList public member function destroys the WCPtrSList object. If the list is notempty and the not_empty exception is enabled, the exception is thrown. If the not_emptyexception is not enabled and the list is not empty, the list is cleared using the clear member function.The call to the ~WCPtrSList public member function is inserted implicitly by the compiler at thepoint where the WCPtrSList object goes out <strong>of</strong> scope.The WCPtrSList object is destroyed.WCPtrSList, clear, clearAndDestroy, WCExcept::not_emptyList Containers 261
WCPtrDList::WCPtrDList()Synopsis:Semantics:Results:See Also:#include public:WCPtrDList();The WCPtrDList public member function creates an empty WCPtrDList object.The WCPtrDList public member function produces an initialized WCPtrDList object.WCPtrDList, ~WCPtrDList262 List Containers
WCPtrDList::WCPtrDList()Synopsis:Semantics:#include public:WCPtrDList( void *(*allocator)( size_t ),void (*deallocator)( void *, size_t ) );The WCPtrDList public member function creates an empty WCPtrDList object. Theallocator function is registered to perform all memory allocations <strong>of</strong> the list elements, and thedeallocator function to perform all freeing <strong>of</strong> the list elements’ memory. These functions provide theability to control how the allocation and freeing <strong>of</strong> memory is performed, allowing for more efficientmemory handling than the general purpose global operator new() and operator delete()can provide. Memory management optimizations may potentially be made through the allocator anddeallocator functions, but are not recommended before managing memory is understood anddetermined to be worth while.The allocator function shall return a pointer to allocated memory <strong>of</strong> size at least the argument, orzero(0) if the allocation cannot be performed. Initialization <strong>of</strong> the memory returned is performed by theWCPtrDList class.The WCPtrDList class calls the deallocator function only on memory allocated by theallocator function. The deallocator shall free the memory pointed to by the first argument which is <strong>of</strong>size the second argument. The size passed to the deallocator function is guaranteed to be the same sizepassed to the allocator function when the memory was allocated.The allocator and deallocator functions may assume that for a list object instance, the allocator isalways called with the same first argument (the size <strong>of</strong> the memory to be allocated). TheWCValDListItemSize(Type) macro returns the size <strong>of</strong> the elements which are allocated by theallocator function.Results:See Also:The WCPtrDList public member function creates an initialized WCPtrDList object andregisters the allocator and deallocator functions.WCPtrDList, ~WCPtrDListList Containers 263
WCPtrDList::WCPtrDList()Synopsis:Semantics:#include public:WCPtrDList( const WCPtrDList & );The WCPtrDList public member function is the copy constructor for the double linked list class. All<strong>of</strong> the list elements are copied to the new list, as well as the exception trap states, and any registeredallocator and deallocator functions.If all <strong>of</strong> the elements cannot be copied and the out_<strong>of</strong>_memory is enabled in the list being copied,the exception is thrown. The new list is created in a valid state, even if all <strong>of</strong> the list elements could notbe copied.Results:See Also:The WCPtrDList public member function produces a copy <strong>of</strong> the list.WCPtrDList, ~WCPtrDList, clear, WCExcept::out_<strong>of</strong>_memory264 List Containers
WCPtrDList::~WCPtrDList()Synopsis:Semantics:Results:See Also:#include public:~WCPtrDList();The ~WCPtrDList public member function destroys the WCPtrDList object. If the list is notempty and the not_empty exception is enabled, the exception is thrown. If the not_emptyexception is not enabled and the list is not empty, the list is cleared using the clear member function.The call to the ~WCPtrDList public member function is inserted implicitly by the compiler at thepoint where the WCPtrDList object goes out <strong>of</strong> scope.The WCPtrDList object is destroyed.WCPtrDList, clear, clearAndDestroy, WCExcept::not_emptyList Containers 265
WCPtrSList::append(), WCPtrDList::append()Synopsis:Semantics:#include public:int append( Type * );The append public member function is used to append the data to the end <strong>of</strong> the list.If the out_<strong>of</strong>_memory exception is enabled and the append fails, the exception is thrown.Results:See Also:The data element is appended to the end <strong>of</strong> the list. A TRUE value (non-zero) is returned if the appendis successful. A FALSE (zero) result is returned if the append fails.insert, WCExcept::out_<strong>of</strong>_memory266 List Containers
WCPtrSList::clear(), WCPtrDList::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the list object and set it to the state <strong>of</strong> the objectjust after the initial construction. The list object is not destroyed and re-created by this operator, so theobject destructor is not invoked.The clear public member function resets the list object to the state <strong>of</strong> the object immediately after theinitial construction.See Also: ~WCPtrSList, ~WCPtrDList, clearAndDestroy, get, operator =List Containers 267
WCPtrSList,WCPtrDList::clearAndDestroy()Synopsis:Semantics:Results:See Also:#include public:void clearAndDestroy();The clearAndDestroy public member function is used to clear the list object and set it to the state<strong>of</strong> the object just after the initial construction. The list object is not destroyed and re-created by thisoperator, so the object destructor is not invoked. Before the list object is re-initialized, the the valuespointed to by the list elements are deleted.The clearAndDestroy public member function resets the list object to the initial state <strong>of</strong> the objectimmediately after the initial construction and deletes the list elements.clear, get268 List Containers
WCPtrSList::contains(), WCPtrDList::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Type * ) const;The contains public member function is used to determine if a list element object is alreadycontained in the list. Each list element is compared to the passed element using Type’s operator== to determine if the passed element is contained in the list. Note that the comparison is <strong>of</strong> the objectspointed to.Zero(0) is returned if the passed list element object is not found in the list. A non-zero result is returnedif the element is found in the list.find, indexList Containers 269
WCPtrSList::entries(), WCPtrDList::entries()Synopsis:Semantics:Results:See Also:#include public:int entries() const;The entries public member function is used to determine the number <strong>of</strong> list elements contained inthe list object.The number <strong>of</strong> entries stored in the list is returned, zero(0) is returned if there are no list elements.isEmpty270 List Containers
WCPtrSList::find(), WCPtrDList::find()Synopsis:Semantics:#include public:Type * find( int = 0 ) const;The find public member function returns the value <strong>of</strong> a list element in the list object. The optionalparameter specifies which element to locate, and defaults to the first element. Since the first element <strong>of</strong>the list is the zero’th element, the last element will be the number <strong>of</strong> list entries minus one.If the list is empty and the empty_container exception is enabled, the exception is thrown. If theindex_range exception is enabled, the exception is thrown if the index value is negative or is greaterthan the number <strong>of</strong> list entries minus one.Results:See Also:The value <strong>of</strong> the selected list element or the closest element is returned. If the index value is negative,the closest list element is the first element. The last element is the closest element if the index value isgreater than the number <strong>of</strong> list entries minus one. An uninitialized pointer is returned if there are noelements in the list.findLast, get, index, isEmpty, WCExcept::empty_container,WCExcept::index_rangeList Containers 271
WCPtrSList::findLast(), WCPtrDList::findLast()Synopsis:Semantics:#include public:Type * findLast() const;The findLast public member function returns the value <strong>of</strong> the last list element in the list object.If the list is empty, one <strong>of</strong> two exceptions can be thrown. If the empty_container exception isenabled, it is thrown. The index_range exception is thrown if it is enabled and theempty_container exception is not enabled.Results:See Also:The value <strong>of</strong> the last list element is returned. An uninitialized pointer is returned if there are noelements in the list.find, get, isEmpty, WCExcept::empty_container, WCExcept::index_range272 List Containers
WCPtrSList::forAll(), WCPtrDList::forAll()Synopsis:Semantics:#include public:void forAll( void (*)( Type *, void * ), void *) const;The forAll public member function is used to cause the function fn to be invoked for each listelement. The fn function should have the prototypevoid (*fn)( Type *, void * )The first parameter <strong>of</strong> fn shall accept the value <strong>of</strong> the list element currently active. The secondargument passed to fn is the second argument <strong>of</strong> the forAll function. This allows a callback functionto be defined which can accept data appropriate for the point at which the forAll function is invoked.See Also:WCPtrConstSListIter, WCPtrConstDListIter, WCPtrSListIter, WCPtrDListIterList Containers 273
WCPtrSList::get(), WCPtrDList::get()Synopsis:Semantics:#include public:Type * get( int = 0 );The get public member function returns the value <strong>of</strong> the list element in the list object. The list elementis also removed from the list. The optional parameter specifies which element to remove, and defaultsto the first element. Since the first element <strong>of</strong> the list is the zero’th element, the last element will be thenumber <strong>of</strong> list entries minus one.If the list is empty and the empty_container exception is enabled, the exception is thrown. If theindex_range exception trap is enabled, the exception is thrown if the index value is negative or isgreater than the number <strong>of</strong> list entries minus one.Results:See Also:The value <strong>of</strong> the selected list element or the closest element is removed and returned. If the index valueis negative, the closest list element is the first element. The last element is the closest element if theindex value is greater than the number <strong>of</strong> list entries minus one. An uninitialized pointer is returned ifthere are no elements in the list.clear, clearAndDestroy, find, index, WCExcept::empty_container,WCExcept::index_range274 List Containers
WCPtrSList::index(), WCPtrDList::index()Synopsis:Semantics:Results:See Also:#include public:int index( const Type * ) const;The index public member function is used to determine the index <strong>of</strong> the first list element equivalent tothe passed element. Each list element is compared to the passed element using Type’s operator== until the passed element is found, or all list elements have been checked. Note that the comparisonis <strong>of</strong> the objects pointed to.The index <strong>of</strong> the first element equivalent to the passed element is returned. If the passed element is notin the list, negative one (-1) is returned.contains, find, getList Containers 275
WCPtrSList::insert(), WCPtrDList::insert()Synopsis:Semantics:#include public:int insert( Type * );The insert public member function is used to insert the data as the first element <strong>of</strong> the list.If the out_<strong>of</strong>_memory exception is enabled and the insert fails, the exception is thrown.Results:See Also:The data element is inserted into the beginning <strong>of</strong> the list. A TRUE value (non-zero) is returned if theinsert is successful. A FALSE (zero) result is returned if the insert fails.append, WCExcept::out_<strong>of</strong>_memory276 List Containers
WCPtrSList::isEmpty(), WCPtrDList::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if a list object has any list elementscontained in it.A TRUE value (non-zero) is returned if the list object does not have any list elements contained withinit. A FALSE (zero) result is returned if the list contains at least one element.entriesList Containers 277
WCPtrSList::operator =(), WCPtrDList::operator =()Synopsis:Semantics:#include public:WCPtrSList & WCPtrSList::operator =( const WCPtrSList & );WCPtrDList & WCPtrDList::operator =( const WCPtrDList & );The operator = public member function is the assignment operator for the class. The left hand side<strong>of</strong> the assignment is first cleared with the clear member function. All elements in the right hand sidelist are then copied, as well as the exception trap states, and any registered allocator and deallocatorfunctions.If all <strong>of</strong> the elements cannot be copied and the out_<strong>of</strong>_memory is enabled in the right hand side list,the exception is thrown. The new list is created in a valid state, even if all <strong>of</strong> the list elements could notbe copied.Results:See Also:The operator = public member function assigns the right hand side to the left hand side and returnsa reference to the left hand side.WCPtrSList, WCPtrDList, clear, WCExcept::out_<strong>of</strong>_memory278 List Containers
WCPtrSList::operator ==(), WCPtrDList::operator ==()Synopsis:Semantics:Results:#include public:int WCPtrSList::operator ==( const WCPtrSList & ) const;int WCPtrDList::operator ==( const WCPtrDList & ) const;The operator == public member function is the equivalence operator for theWCPtrSList and WCPtrDList classes. Two list objects are equivalent if they arethe same object and share the same address.A TRUE (non-zero) value is returned if the left hand side object and the right hand side objects are thesame object. A FALSE (zero) value is returned otherwise.List Containers 279
WCSLinkDeclared:Derived by:wclcom.hWCDLinkThe WCSLink class is the building block for all <strong>of</strong> the list classes. It provides the link that is used totraverse the list elements. The double link classes use the WCSLink class to implement both links.Since no user data is stored directly with it, the WCSLink class should only be used as a base class toderive a user defined class.When creating a single linked intrusive list, the WCSLink class is used to derive the user defined classthat holds the data to be inserted into the list.The wclcom.h header file is included by the wclist.h header file. There is no need to explicitlyinclude the wclcom.h header file unless the wclist.h header file is not included. No errors willresult if it is included unnecessarily.Note that the destructor is non-virtual so that list elements are <strong>of</strong> minimum size. Objects created as aclass derived from the WCSLink class, but destroyed while typed as a WCSLink object will not invokethe destructor <strong>of</strong> the derived class.Public Member FunctionsThe following public member functions are declared:WCSLink();~WCSLink();See Also:WCDLink280 List Containers
WCSLink::WCSLink()Synopsis:Semantics:Results:See Also:#include public:WCSLink();The public WCSLink constructor creates an WCSLink object. The public WCSLink constructor isused implicitly by the compiler when it generates a constructor for a derived class.The public WCSLink constructor produces an initialized WCSLink object.~WCSLinkList Containers 281
WCSLink::~WCSLink()Synopsis:Semantics:Results:See Also:#include public:~WCSLink();The public ~WCSLink destructor does not do anything explicit. The call to the public ~WCSLinkdestructor is inserted implicitly by the compiler at the point where the object derived from WCSLinkgoes out <strong>of</strong> scope.The object derived from WCSLink is destroyed.WCSLink282 List Containers
WCValSList, WCValDListDeclared:wclist.hThe WCValSList and WCValDList classes are the templated classes used tocreate objects which are single or double linked lists. Values are copied into the list, which could beundesirable if the stored objects are complicated and copying is expensive. Value lists should not beused to store objects <strong>of</strong> a base class if any derived types <strong>of</strong> different sizes would be stored in the list, orif the destructor for a derived class must be called.In the description <strong>of</strong> each member function, the text Type is used to indicate the type value specified asthe template parameter. Type is the type <strong>of</strong> the values stored in the list.The WCExcept class is a base class <strong>of</strong> the WCValSList and WCValDList classesand provides the exceptions member function. This member function controls the exceptions whichcan be thrown by the WCValSList and WCValDList objects. No exceptions areenabled unless they are set by the exceptions member function.Requirements <strong>of</strong> TypeThe WCValSList and WCValDList classes requires Type to have:(1) a default constructor ( Type::Type() ).(2) a well defined copy constructor ( Type::Type( const Type & ) ).(3) an equivalence operator with constant parametersType::operator ==( const Type & ) constPublic Member FunctionsThe following member functions are declared in the public interface:WCValSList();WCValSList( void * (*)( size_t ), void (*)( void *, size_t ));WCValSList( const WCValSList & );~WCValSList();WCValDList();WCValDList( void * (*)( size_t ), void (*)( void *, size_t ));WCValDList( const WCValDList & );~WCValDList();int append( const Type & );void clear();void clearAndDestroy();int contains( const Type & ) const;int entries() const;Type find( int = 0 ) const;Type findLast() const;void forAll( void (*)( Type, void * ), void *) const;Type get( int = 0 );int index( const Type & ) const;int insert( const Type & );int isEmpty() const;Public Member OperatorsThe following member operators are declared in the public interface:List Containers 283
WCValSList, WCValDListWCValSList & WCValSList::operator =( const WCValSList & );WCValDList & WCValDList::operator =( const WCValDList & );int WCValSList::operator ==( const WCValSList & ) const;int WCValDList::operator ==( const WCValDList & ) const;Sample Program Using a Value List#include #include static void test1( void );void data_val_prt( int data, void * str ) {cout
WCValSList::WCValSList()Synopsis:Semantics:Results:See Also:#include public:WCValSList();The WCValSList public member function creates an empty WCValSList object.The WCValSList public member function produces an initialized WCValSList object.WCValSList, ~WCValSListList Containers 285
WCValSList::WCValSList()Synopsis:Semantics:#include public:WCValSList( void *(*allocator)( size_t ),void (*deallocator)( void *, size_t ) );The WCValSList public member function creates an empty WCValSList object. Theallocator function is registered to perform all memory allocations <strong>of</strong> the list elements, and thedeallocator function to perform all freeing <strong>of</strong> the list elements’ memory. These functions provide theability to control how the allocation and freeing <strong>of</strong> memory is performed, allowing for more efficientmemory handling than the general purpose global operator new() and operator delete()can provide. Memory management optimizations may potentially be made through the allocator anddeallocator functions, but are not recommended before managing memory is understood anddetermined to be worth while.The allocator function shall return a pointer to allocated memory <strong>of</strong> size at least the argument, orzero(0) if the allocation cannot be performed. Initialization <strong>of</strong> the memory returned is performed by theWCValSList class.The WCValSList class calls the deallocator function only on memory allocated by theallocator function. The deallocator shall free the memory pointed to by the first argument which is <strong>of</strong>size the second argument. The size passed to the deallocator function is guaranteed to be the same sizepassed to the allocator function when the memory was allocated.The allocator and deallocator functions may assume that for a list object instance, the allocator isalways called with the same first argument (the size <strong>of</strong> the memory to be allocated). TheWCValSListItemSize(Type) macro returns the size <strong>of</strong> the elements which are allocated by theallocator function.Results:See Also:The WCValSList public member function creates an initialized WCValSList object andregisters the allocator and deallocator functions.WCValSList, ~WCValSList286 List Containers
WCValSList::WCValSList()Synopsis:Semantics:#include public:void WCValSList( const WCValSList & );The WCValSList public member function is the copy constructor for the single linked list class. All<strong>of</strong> the list elements are copied to the new list, as well as the exception trap states, and any registeredallocator and deallocator functions. Type’s copy constructor is invoked to copy the values containedby the list elements.If all <strong>of</strong> the elements cannot be copied and the out_<strong>of</strong>_memory is enabled in the list being copied,the exception is thrown. The new list is created in a valid state, even if all <strong>of</strong> the list elements could notbe copied.Results:See Also:The WCValSList public member function produces a copy <strong>of</strong> the list.WCValSList, ~WCValSList, clear, WCExcept::out_<strong>of</strong>_memoryList Containers 287
WCValSList::~WCValSList()Synopsis:Semantics:Results:See Also:#include public:~WCValSList();The ~WCValSList public member function destroys the WCValSList object. If the list is notempty and the not_empty exception is enabled, the exception is thrown. If the not_emptyexception is not enabled and the list is not empty, the list is cleared using the clear member function.The call to the ~WCValSList public member function is inserted implicitly by the compiler at thepoint where the WCValSList object goes out <strong>of</strong> scope.The WCValSList object is destroyed.WCValSList, clear, clearAndDestroy, WCExcept::not_empty288 List Containers
WCValDList::WCValDList()Synopsis:Semantics:Results:See Also:#include public:WCValDList();The WCValDList public member function creates an empty WCValDList object.The WCValDList public member function produces an initialized WCValDList object.WCValDList, ~WCValDListList Containers 289
WCValDList::WCValDList()Synopsis:Semantics:#include public:WCValDList( void *(*allocator)( size_t ),void (*deallocator)( void *, size_t ) );The WCValDList public member function creates an empty WCValDList object. Theallocator function is registered to perform all memory allocations <strong>of</strong> the list elements, and thedeallocator function to perform all freeing <strong>of</strong> the list elements’ memory. These functions provide theability to control how the allocation and freeing <strong>of</strong> memory is performed, allowing for more efficientmemory handling than the general purpose global operator new() and operator delete()can provide. Memory management optimizations may potentially be made through the allocator anddeallocator functions, but are not recommended before managing memory is understood anddetermined to be worth while.The allocator function shall return a pointer to allocated memory <strong>of</strong> size at least the argument, orzero(0) if the allocation cannot be performed. Initialization <strong>of</strong> the memory returned is performed by theWCValDList class.The WCValDList class calls the deallocator function only on memory allocated by theallocator function. The deallocator shall free the memory pointed to by the first argument which is <strong>of</strong>size the second argument. The size passed to the deallocator function is guaranteed to be the same sizepassed to the allocator function when the memory was allocated.The allocator and deallocator functions may assume that for a list object instance, the allocator isalways called with the same first argument (the size <strong>of</strong> the memory to be allocated). TheWCValDListItemSize(Type) macro returns the size <strong>of</strong> the elements which are allocated by theallocator function.Results:See Also:The WCValDList public member function creates an initialized WCValDList object andregisters the allocator and deallocator functions.WCValDList, ~WCValDList290 List Containers
WCValDList::WCValDList()Synopsis:Semantics:#include public:WCValDList( const WCValDList & );The WCValDList public member function is the copy constructor for the double linked list class. All<strong>of</strong> the list elements are copied to the new list, as well as the exception trap states, and any registeredallocator and deallocator functions. Type’s copy constructor is invoked to copy the values containedby the list elements.If all <strong>of</strong> the elements cannot be copied and the out_<strong>of</strong>_memory is enabled in the list being copied,the exception is thrown. The new list is created in a valid state, even if all <strong>of</strong> the list elements could notbe copied.Results:See Also:The WCValDList public member function produces a copy <strong>of</strong> the list.WCValDList, ~WCValDList, clear, WCExcept::out_<strong>of</strong>_memoryList Containers 291
WCValDList::~WCValDList()Synopsis:Semantics:Results:See Also:#include public:~WCValDList();The ~WCValDList public member function destroys the WCValDList object. If the list is notempty and the not_empty exception is enabled, the exception is thrown. If the not_emptyexception is not enabled and the list is not empty, the list is cleared using the clear member function.The call to the ~WCValDList public member function is inserted implicitly by the compiler at thepoint where the WCValDList object goes out <strong>of</strong> scope.The WCValDList object is destroyed.WCValDList, clear, clearAndDestroy, WCExcept::not_empty292 List Containers
WCValSList::append(), WCValDList::append()Synopsis:Semantics:#include public:int append( const Type & );The append public member function is used to append the data to the end <strong>of</strong> the list. The data storedin the list is a copy <strong>of</strong> the data passed as a parameter.If the out_<strong>of</strong>_memory exception is enabled and the append fails, the exception is thrown.Results:See Also:The data element is appended to the end <strong>of</strong> the list. A TRUE value (non-zero) is returned if the appendis successful. A FALSE (zero) result is returned if the append fails.insert, WCExcept::out_<strong>of</strong>_memoryList Containers 293
WCValSList::clear(), WCValDList::clear()Synopsis:Semantics:#include public:void clear();The clear public member function is used to clear the list object and set it to the state <strong>of</strong> the objectjust after the initial construction. The list object is not destroyed and re-created by this operator, so theobject destructor is not invoked.The clear public member function has the same sematics as the clearAndDestroy memberfunction.Results:The clear public member function resets the list object to the state <strong>of</strong> the object immediately after theinitial construction.See Also: ~WCValSList, ~WCValDList, clearAndDestroy, get, operator =294 List Containers
WCValSList,WCValDList::clearAndDestroy()Synopsis:Semantics:#include public:void clearAndDestroy();The clearAndDestroy public member function is used to clear the list object and set it to the state<strong>of</strong> the object just after the initial construction. The list object is not destroyed and re-created by thisoperator, so the object destructor is not invoked.Before the list object is re-initialized, the delete operator is called for each list element.Results:See Also:The clearAndDestroy public member function resets the list object to the initial state <strong>of</strong> the objectimmediately after the initial construction.clear, getList Containers 295
WCValSList::contains(), WCValDList::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Type & ) const;The contains public member function is used to determine if a list element object is alreadycontained in the list. Each list element is compared to the passed element using Type’s operator== to determine if the passed element is contained in the list.Zero(0) is returned if the passed list element object is not found in the list. A non-zero result is returnedif the element is found in the list.find, index296 List Containers
WCValSList::entries(), WCValDList::entries()Synopsis:Semantics:Results:See Also:#include public:int entries() const;The entries public member function is used to determine the number <strong>of</strong> list elements contained inthe list object.The number <strong>of</strong> entries stored in the list is returned, zero(0) is returned if there are no list elements.isEmptyList Containers 297
WCValSList::find(), WCValDList::find()Synopsis:Semantics:#include public:Type find( int = 0 ) const;The find public member function returns the value <strong>of</strong> a list element in the list object. The optionalparameter specifies which element to locate, and defaults to the first element. Since the first element <strong>of</strong>the list is the zero’th element, the last element will be the number <strong>of</strong> list entries minus one.If the list is empty and the empty_container exception is enabled, the exception is thrown. If theindex_range exception is enabled, the exception is thrown if the index value is negative or is greaterthan the number <strong>of</strong> list entries minus one.Results:See Also:The value <strong>of</strong> the selected list element or the closest element is returned. If the index value is negative,the closest list element is the first element. The last element is the closest element if the index value isgreater than the number <strong>of</strong> list entries minus one. A default initialized value is returned if there are noelements in the list.findLast, get, index, isEmpty, WCExcept::empty_container,WCExcept::index_range298 List Containers
WCValSList::findLast(), WCValDList::findLast()Synopsis:Semantics:#include public:Type findLast() const;The findLast public member function returns the value <strong>of</strong> the last list element in the list object.If the list is empty, one <strong>of</strong> two exceptions can be thrown. If the empty_container exception isenabled, it is thrown. The index_range exception is thrown if it is enabled and theempty_container exception is not enabled.Results:See Also:The value <strong>of</strong> the last list element is returned. A default initialized value is returned if there are noelements in the list.find, get, isEmpty, WCExcept::empty_container, WCExcept::index_rangeList Containers 299
WCValSList::forAll(), WCValDList::forAll()Synopsis:Semantics:#include public:void forAll( void (*)( Type, void * ), void *) const;The forAll public member function is used to cause the function fn to be invoked for each listelement. The fn function should have the prototypevoid (*fn)( Type, void * )The first parameter <strong>of</strong> fn shall accept the value <strong>of</strong> the list element currently active. The secondargument passed to fn is the second argument <strong>of</strong> the forAll function. This allows a callback functionto be defined which can accept data appropriate for the point at which the forAll function is invoked.See Also:WCValConstSListIter, WCValConstDListIter, WCValSListIter, WCValDListIter300 List Containers
WCValSList::get(), WCValDList::get()Synopsis:Semantics:#include public:Type get( int = 0 );The get public member function returns the value <strong>of</strong> the list element in the list object. The list elementis also removed from the list. The optional parameter specifies which element to remove, and defaultsto the first element. Since the first element <strong>of</strong> the list is the zero’th element, the last element will be thenumber <strong>of</strong> list entries minus one.If the list is empty and the empty_container exception is enabled, the exception is thrown. If theindex_range exception trap is enabled, the exception is thrown if the index value is negative or isgreater than the number <strong>of</strong> list entries minus one.Results:See Also:The value <strong>of</strong> the selected list element or the closest element is removed and returned. If the index valueis negative, the closest list element is the first element. The last element is the closest element if theindex value is greater than the number <strong>of</strong> list entries minus one. A default initialized value is returned ifthere are no elements in the list.clear, clearAndDestroy, find, index, WCExcept::empty_container,WCExcept::index_rangeList Containers 301
WCValSList::index(), WCValDList::index()Synopsis:Semantics:Results:See Also:#include public:int index( const Type & ) const;The index public member function is used to determine the index <strong>of</strong> the first list element equivalent tothe passed element. Each list element is compared to the passed element using Type’s operator== until the passed element is found, or all list elements have been checked.The index <strong>of</strong> the first element equivalent to the passed element is returned. If the passed element is notin the list, negative one (-1) is returned.contains, find, get302 List Containers
WCValSList::insert(), WCValDList::insert()Synopsis:Semantics:#include public:int insert( const Type & );The insert public member function is used to insert the data as the first element <strong>of</strong> the list. The datastored in the list is a copy <strong>of</strong> the data passed as a parameter.If the out_<strong>of</strong>_memory exception is enabled and the insert fails, the exception is thrown.Results:See Also:The data element is inserted into the beginning <strong>of</strong> the list. A TRUE value (non-zero) is returned if theinsert is successful. A FALSE (zero) result is returned if the insert fails.append, WCExcept::out_<strong>of</strong>_memoryList Containers 303
WCValSList::isEmpty(), WCValDList::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if a list object has any list elementscontained in it.A TRUE value (non-zero) is returned if the list object does not have any list elements contained withinit. A FALSE (zero) result is returned if the list contains at least one element.entries304 List Containers
WCValSList::operator =(), WCValDList::operator =()Synopsis:Semantics:#include public:WCValSList & WCValSList::operator =( const WCValSList & );WCValDList & WCValDList::operator =( const WCValDList & );The operator = public member function is the assignment operator for the class. The left hand side<strong>of</strong> the assignment is first cleared with the clear member function. All elements in the right hand sidelist are then copied, as well as the exception trap states, and any registered allocator and deallocatorfunctions. Type’s copy constructor is invoked to copy the values contained by the list elements.If all <strong>of</strong> the elements cannot be copied and the out_<strong>of</strong>_memory is enabled in the right hand side list,the exception is thrown. The new list is created in a valid state, even if all <strong>of</strong> the list elements could notbe copied.Results:See Also:The operator = public member function assigns the right hand side to the left hand side and returnsa reference to the left hand side.WCValSList, WCValDList, clear, WCExcept::out_<strong>of</strong>_memoryList Containers 305
WCValSList::operator ==(), WCValDList::operator ==()Synopsis:Semantics:Results:#include public:int WCValSList::operator ==( const WCValSList & ) const;int WCValDList::operator ==( const WCValDList & ) const;The operator == public member function is the equivalence operator for theWCValSList and WCValDList classes. Two list objects are equivalent if they arethe same object and share the same address.A TRUE (non-zero) value is returned if the left hand side object and the right hand side objects are thesame object. A FALSE (zero) value is returned otherwise.306 List Containers
13 List IteratorsList iterators operate on single or double linked lists. They are used to step through a list one or moreelements at a time. The choice <strong>of</strong> which type <strong>of</strong> iterator to use is determined by the list you wish to iterateover. For example, to iterate over a non-constant WCIsvDList object, use theWCIsvDListIter class. A constant WCValSList object can be iterated using theWCValConstSListIter class. The iterators which correspond to the single link list containershave some functionality inhibited. If backward traversal is required, the double linked containers andcorresponding iterators must be used.Like all WATCOM iterators, newly constructed and reset iterators are positioned before the first element inthe list. The list may be traversed one element at a time using the pre-increment or call operator. Anincrement operation causing the iterator to be positioned after the end <strong>of</strong> the list returns zero. Furtherincrements will cause the undef_iter exception to be thrown, if it is enabled. This behaviour allowslists to be traversed simply using a while loop, and is demonstrated in the examples for the iterator classes.The classes are presented in alphabetical order. The WCIterExcept class provides the commonexception handling control interface for all <strong>of</strong> the iterators.Since the iterator classes are all template classes, deriving most <strong>of</strong> the functionality from common baseclasses was used. In the listing <strong>of</strong> class member functions, those public member functions which appear tobe in the iterator class but are actually defined in the common base class are identified as if they wereexplicitly specified in the iterator class.List Iterators 307
WCIsvConstSListIter, WCIsvConstDListIterDeclared:wclistit.hThe WCIsvConstSListIter and WCIsvConstDListIter classes are thetemplated classes used to create iterator objects for constant single and double linked list objects. Theseclasses may be used to iterate over non-constant lists, but the WCIsvDListIter andWCIsvSListIter classes provide additional functionality for only non-constant lists.In the description <strong>of</strong> each member function, the text Type is used to indicate the list element typespecified as the template parameter.The WCIterExcept class is a base class <strong>of</strong> the WCIsvConstSListIter andWCIsvConstDListIter classes and provides the exceptions member function. Thismember function controls the exceptions which can be thrown by theWCIsvConstSListIter and WCIsvConstDListIter objects. No exceptionsare enabled unless they are set by the exceptions member function.Private Member FunctionsSome functionality supported by base classes <strong>of</strong> the iterator are not appropriate for the constant listiterator classes. Setting those functions as private members in the derived class is the standardmechanism to prevent them from being invoked.int append( Type * );int insert( Type * );Public Member FunctionsThe following member functions are declared in the public interface:WCIsvConstSListIter();WCIsvConstSListIter( const WCIsvSList & );~WCIsvConstSListIter();WCIsvConstDListIter();WCIsvConstDListIter( const WCIsvDList & );~WCIsvConstDListIter();const WCIsvSList *WCIsvConstSListIter::container() const;const WCIsvDList *WCIsvConstDListIter::container() const;Type * current() const;void reset();void WCIsvConstSListIter::reset( const WCIsvSList & );void WCIsvConstDListIter::reset( const WCIsvDList & );Public Member OperatorsThe following member operators are declared in the public interface:Type * operator ()();Type * operator ++();Type * operator +=( int );In the iterators for double linked lists only:Type * operator --();Type * operator -=( int );See Also:WCIsvSList::forAll, WCIsvDList::forAll308 List Iterators
WCIsvConstSListIter::WCIsvConstSListIter()Synopsis:Semantics:Results:See Also:#include public:WCIsvConstSListIter();The WCIsvConstSListIter public member function is the default constructor for the class andinitializes the iterator with no list to operate on. The reset member function must be called to providethe iterator with a list to iterate over.The WCIsvConstSListIter public member function creates an initializedWCIsvConstSListIter object.WCIsvConstSListIter, ~WCIsvConstSListIter, resetList Iterators 309
WCIsvConstSListIter::WCIsvConstSListIter()Synopsis:Semantics:Results:See Also:#include public:WCIsvConstSListIter( const WCIsvSList & );The WCIsvConstSListIter public member function is a constructor for the class. The valuepassed as a parameter is a WCIsvSList list object. The iterator will be initialized for that list objectand positioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCIsvConstSListIter public member function creates an initializedWCIsvConstSListIter object positioned before the first element in the list.~WCIsvConstSListIter, operator (), operator ++, operator +=, reset310 List Iterators
WCIsvConstSListIter::~WCIsvConstSListIter()Synopsis:Semantics:Results:See Also:#include public:~WCIsvConstSListIter();The ~WCIsvConstSListIter public member function is the destructor for the class. The call tothe ~WCIsvConstSListIter public member function is inserted implicitly by the compiler at thepoint where the WCIsvConstSListIter object goes out <strong>of</strong> scope.The WCIsvConstSListIter object is destroyed.WCIsvConstSListIterList Iterators 311
WCIsvConstDListIter::WCIsvConstDListIter()Synopsis:Semantics:Results:See Also:#include public:WCIsvConstDListIter();The WCIsvConstDListIter public member function is the default constructor for the class andinitializes the iterator with no list to operate on. The reset member function must be called to providethe iterator with a list to iterate over.The WCIsvConstDListIter public member function creates an initializedWCIsvConstDListIter object.WCIsvConstDListIter, ~WCIsvConstDListIter, reset312 List Iterators
WCIsvConstDListIter::WCIsvConstDListIter()Synopsis:Semantics:Results:#include public:WCIsvConstDListIter( const WCIsvDList & );The WCIsvConstDListIter public member function is a constructor for the class. The valuepassed as a parameter is the WCIsvDList list object. The iterator will be initialized for that list objectand positioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCIsvConstDListIter public member function creates an initializedWCIsvConstDListIter object positioned before the first list element.See Also: WCIsvConstDListIter, ~WCIsvConstDListIter, operator (), operator ++,operator +=, resetList Iterators 313
WCIsvConstDListIter::~WCIsvConstDListIter()Synopsis:Semantics:Results:See Also:#include public:~WCIsvConstDListIter();The ~WCIsvConstDListIter public member function is the destructor for the class. The call tothe ~WCIsvConstDListIter public member function is inserted implicitly by the compiler at thepoint where the WCIsvConstDListIter object goes out <strong>of</strong> scope.The WCIsvConstDListIter object is destroyed.WCIsvConstDListIter314 List Iterators
WCIsvConstSListIter,WCIsvConstDListIter::container()Synopsis:Semantics:Results:See Also:#include public:const WCIsvSList *WCIsvConstSListIter::container() const;const WCIsvDList *WCIsvConstDListIter::container() const;The container public member function returns a pointer to the list container object. If the iteratorhas not been initialized with a list object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a list.WCIsvConstSListIter, WCIsvConstDListIter, reset, WCIterExcept::undef_iterList Iterators 315
WCIsvConstSListIter::current(), WCIsvConstDListIter::current()Synopsis:Semantics:#include public:Type * current();The current public member function returns a pointer to the list item at the current iterator position.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. In this case the undef_itemexception is thrown, if enabled.Results:See Also:A pointer to the current list element is returned. If the current element is undefined, NULL(0) isreturned.operator (), operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_item316 List Iterators
WCIsvConstSListIter,WCIsvConstDListIter::operator ()()Synopsis:Semantics:#include public:Type * operator ()();The operator () public member function is the call operator for the class. The list element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is incremented past the end <strong>of</strong> the list.operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_iterList Iterators 317
WCIsvConstSListIter,WCIsvConstDListIter::operator ++()Synopsis:Semantics:#include public:Type * operator ++();The operator ++ public member function is the pre-increment operator for the class. The listelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator ++ public member function has the same semantics as the call operator, operator().If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator +=, operator --, operator -=, reset,WCIterExcept::undef_iter318 List Iterators
WCIsvConstSListIter,WCIsvConstDListIter::operator +=()Synopsis:Semantics:#include public:Type * operator +=( int );The operator += public member function accepts an integer value that causes the iterator to movethat many elements after the current item. If the iterator was positioned before the first element in thelist, the operation will set the current item to be the given element in the list.If the current item was after the last element in the list previous to the iteration, and the undef_iterexception is enabled, the exception will be thrown. Attempting to increment the iterator position morethan element after the end <strong>of</strong> the list, or by less than one element causes the iter_range exception tobe thrown, if enabled.Results:See Also:The operator += public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator ++, operator --, operator -=, reset,WCIterExcept::iter_range, WCIterExcept::undef_iterList Iterators 319
WCIsvConstDListIter::operator --()Synopsis:Semantics:#include public:Type * operator --();The operator -- public member function is the pre-decrement operator for the class. The listelement previous to the current item is set to be the new current item. If the current item was the firstelement in the list, the iterator is positioned before the first element in the list. If the list is empty, theiterator will be positioned before the start <strong>of</strong> the list.If the iterator was positioned after the last element in the list, the current item will be set to the lastelement.If the iterator is not associated with a list or the iterator position previous to the decrement was beforethe first element the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator -- public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is decremented past the first element <strong>of</strong> the list.current, operator (), operator ++, operator +=, operator -=, reset,WCIterExcept::undef_iter320 List Iterators
WCIsvConstDListIter::operator -=()Synopsis:Semantics:#include public:Type * operator -=( int );The operator -= public member function accepts an integer value that causes the iterator to movethat many elements before the current item. If the iterator was positioned after the last element in thelist, the operation will set the current item to be the given number <strong>of</strong> elements from the end <strong>of</strong> the list.If the current item was before the first element in the list previous to the iteration, and theundef_iter exception is enabled, the exception will be thrown. Attempting to decrement the iteratorposition more than one element before the beginning <strong>of</strong> the list, or by less than one element causes theiter_range exception to be thrown, if enabled.Results:See Also:The operator -= public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is decremented past the first element in the list.current, operator (), operator ++, operator +=, operator --, reset,WCIterExcept::iter_range, WCIterExcept::undef_iterList Iterators 321
WCIsvConstSListIter::reset(), WCIsvConstDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated list.The iterator is positioned before the first list element.WCIsvConstSListIter, WCIsvConstDListIter, container322 List Iterators
WCIsvConstSListIter::reset(), WCIsvConstDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void WCIsvConstSListIter::reset( const WCIsvSList & );void WCIsvConstDListIter::reset( const WCIsvDList & );The reset public member function resets the iterator to operate on the specified list. The iterator ispositioned before the first element in the list.The iterator is positioned before the first element <strong>of</strong> the specified list.WCIsvConstSListIter, WCIsvConstDListIter, containerList Iterators 323
WCIsvSListIter, WCIsvDListIterDeclared:wclistit.hThe WCIsvSListIter and WCIsvDListIter classes are the templated classesused to create iterator objects for single and double linked list objects. These classes can be used onlyfor non-constant lists. The WCIsvDConstListIter andWCIsvSConstListIter classes are provided to iterate over constant lists.In the description <strong>of</strong> each member function, the text Type is used to indicate the list element typespecified as the template parameter.The WCIterExcept class is a base class <strong>of</strong> the WCIsvSListIter andWCIsvDListIter classes and provides the exceptions member function. This memberfunction controls the exceptions which can be thrown by the WCIsvSListIter andWCIsvDListIter objects. No exceptions are enabled unless they are set by theexceptions member function.Private Member FunctionsSome functionality supported by base classes <strong>of</strong> the iterator are not appropriate in the single linked listiterator classes. Setting those functions as private members in the derived class is the standardmechanism to prevent them from being invoked. The following member functions are declared in thesingle linked list iterator private interface:Type * operator --();Type * operator -=( int );int insert( Type * );Public Member FunctionsThe following member functions are declared in the public interface:WCIsvSListIter();WCIsvSListIter( WCIsvSList & );~WCIsvSListIter();WCIsvDListIter();WCIsvDListIter( WCIsvDList & );~WCIsvDListIter();int append( Type * );WCIsvSList *WCIsvSListIter::container() const;WCIsvDList *WCIsvDListIter::container() const;Type * current() const;void reset();void WCIsvSListIter::reset( WCIsvSList & );void WCIsvDListIter::reset( WCIsvDList & );In the iterators for double linked lists only:int insert( Type * );Public Member OperatorsThe following member operators are declared in the public interface:Type * operator ()();Type * operator ++();Type * operator +=( int );324 List Iterators
WCIsvSListIter, WCIsvDListIterIn the iterators for double linked lists only:Type * operator --();Type * operator -=( int );See Also:WCIsvSList::forAll, WCIsvDList::forAllList Iterators 325
WCIsvSListIter::WCIsvSListIter()Synopsis:Semantics:Results:See Also:#include public:WCIsvSListIter();The WCIsvSListIter public member function is the default constructor for the class and initializesthe iterator with no list to operate on. The reset member function must be called to provide theiterator with a list to iterate over.The WCIsvSListIter public member function creates an initialized WCIsvSListIter object.WCIsvSListIter, ~WCIsvSListIter, reset326 List Iterators
WCIsvSListIter::WCIsvSListIter()Synopsis:Semantics:Results:See Also:#include public:WCIsvSListIter( WCIsvSList & );The WCIsvSListIter public member function is a constructor for the class. The value passed as aparameter is a WCIsvSList list object. The iterator will be initialized for that list object andpositioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCIsvSListIter public member function creates an initialized WCIsvSListIter objectpositioned before the first element in the list.~WCIsvSListIter, operator (), operator ++, operator +=, resetList Iterators 327
WCIsvSListIter::~WCIsvSListIter()Synopsis:Semantics:Results:See Also:#include public:~WCIsvSListIter();The ~WCIsvSListIter public member function is the destructor for the class. The call to the~WCIsvSListIter public member function is inserted implicitly by the compiler at the point wherethe WCIsvSListIter object goes out <strong>of</strong> scope.The WCIsvSListIter object is destroyed.WCIsvSListIter328 List Iterators
WCIsvDListIter::WCIsvDListIter()Synopsis:Semantics:Results:See Also:#include public:WCIsvDListIter();The WCIsvDListIter public member function is the default constructor for the class and initializesthe iterator with no list to operate on. The reset member function must be called to provide theiterator with a list to iterate over.The WCIsvDListIter public member function creates an initialized WCIsvDListIter object.WCIsvDListIter, ~WCIsvDListIter, resetList Iterators 329
WCIsvDListIter::WCIsvDListIter()Synopsis:Semantics:Results:#include public:WCIsvDListIter( WCIsvDList & );The WCIsvDListIter public member function is a constructor for the class. The value passed as aparameter is the WCIsvDList list object. The iterator will be initialized for that list object andpositioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCIsvDListIter public member function creates an initialized WCIsvDListIter objectpositioned before the first list element.See Also: WCIsvDListIter, ~WCIsvDListIter, operator (), operator ++, operator +=,reset330 List Iterators
WCIsvDListIter::~WCIsvDListIter()Synopsis:Semantics:Results:See Also:#include public:~WCIsvDListIter();The ~WCIsvDListIter public member function is the destructor for the class. The call to the~WCIsvDListIter public member function is inserted implicitly by the compiler at the point wherethe WCIsvDListIter object goes out <strong>of</strong> scope.The WCIsvDListIter object is destroyed.WCIsvDListIterList Iterators 331
WCIsvSListIter::append(), WCIsvDListIter::append()Synopsis:Semantics:#include public:int append( Type * );The append public member function inserts a new element into the list container object. The newelement is inserted after the current iterator item.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. The element is not appended. Ifthe undef_iter exception is enabled, it is thrown.Results:See Also:The new element is inserted after the current iterator item. A TRUE value (non-zero) is returned if theappend is successful. A FALSE (zero) result is returned if the append fails.insert, WCExcept::out_<strong>of</strong>_memory, WCIterExcept::undef_iter332 List Iterators
WCIsvSListIter,WCIsvDListIter::container()Synopsis:Semantics:Results:See Also:#include public:WCIsvSList *WCIsvSListIter::container() const;WCIsvDList *WCIsvDListIter::container() const;The container public member function returns a pointer to the list container object. If the iteratorhas not been initialized with a list object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a list.WCIsvSListIter, WCIsvDListIter, reset, WCIterExcept::undef_iterList Iterators 333
WCIsvSListIter::current(), WCIsvDListIter::current()Synopsis:Semantics:#include public:Type * current();The current public member function returns a pointer to the list item at the current iterator position.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. In this case the undef_itemexception is thrown, if enabled.Results:See Also:A pointer to the current list element is returned. If the current element is undefined, NULL(0) isreturned.operator (), operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_item334 List Iterators
WCIsvDListIter::insert()Synopsis:Semantics:#include public:int insert( Type * );The insert public member function inserts a new element into the list container object. The newelement is inserted before the current iterator item. This process uses the previous link in the doublelinked list, so the insert public member function is not allowed with single linked lists.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. The element is not inserted. If theundef_iter exception is enabled, the exception is thrown.Results:See Also:The new element is inserted before the current iterator item. A TRUE value (non-zero) is returned if theinsert is successful. A FALSE (zero) result is returned if the insert fails.append, WCExcept::out_<strong>of</strong>_memory, WCIterExcept::undef_iterList Iterators 335
WCIsvSListIter,WCIsvDListIter::operator ()()Synopsis:Semantics:#include public:Type * operator ()();The operator () public member function is the call operator for the class. The list element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is incremented past the end <strong>of</strong> the list.operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_iter336 List Iterators
WCIsvSListIter,WCIsvDListIter::operator ++()Synopsis:Semantics:#include public:Type * operator ++();The operator ++ public member function is the pre-increment operator for the class. The listelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator ++ public member function has the same semantics as the call operator, operator().If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator +=, operator --, operator -=, reset,WCIterExcept::undef_iterList Iterators 337
WCIsvSListIter,WCIsvDListIter::operator +=()Synopsis:Semantics:#include public:Type * operator +=( int );The operator += public member function accepts an integer value that causes the iterator to movethat many elements after the current item. If the iterator was positioned before the first element in thelist, the operation will set the current item to be the given element in the list.If the current item was after the last element in the list previous to the iteration, and the undef_iterexception is enabled, the exception will be thrown. Attempting to increment the iterator position morethan element after the end <strong>of</strong> the list, or by less than one element causes the iter_range exception tobe thrown, if enabled.Results:See Also:The operator += public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator ++, operator --, operator -=, reset,WCIterExcept::iter_range, WCIterExcept::undef_iter338 List Iterators
WCIsvDListIter::operator --()Synopsis:Semantics:#include public:Type * operator --();The operator -- public member function is the pre-decrement operator for the class. The listelement previous to the current item is set to be the new current item. If the current item was the firstelement in the list, the iterator is positioned before the first element in the list. If the list is empty, theiterator will be positioned before the start <strong>of</strong> the list.If the iterator was positioned after the last element in the list, the current item will be set to the lastelement.If the iterator is not associated with a list or the iterator position previous to the decrement was beforethe first element the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator -- public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is decremented past the first element <strong>of</strong> the list.current, operator (), operator ++, operator +=, operator -=, reset,WCIterExcept::undef_iterList Iterators 339
WCIsvDListIter::operator -=()Synopsis:Semantics:#include public:Type * operator -=( int );The operator -= public member function accepts an integer value that causes the iterator to movethat many elements before the current item. If the iterator was positioned after the last element in thelist, the operation will set the current item to be the given number <strong>of</strong> elements from the end <strong>of</strong> the list.If the current item was before the first element in the list previous to the iteration, and theundef_iter exception is enabled, the exception will be thrown. Attempting to decrement the iteratorposition more than one element before the beginning <strong>of</strong> the list, or by less than one element causes theiter_range exception to be thrown, if enabled.Results:See Also:The operator -= public member function returns a pointer to the new current item. NULL(0) isreturned when the iterator is decremented past the first element in the list.current, operator (), operator ++, operator +=, operator --, reset,WCIterExcept::iter_range, WCIterExcept::undef_iter340 List Iterators
WCIsvSListIter::reset(), WCIsvDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated list.The iterator is positioned before the first list element.WCIsvSListIter, WCIsvDListIter, containerList Iterators 341
WCIsvSListIter::reset(), WCIsvDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void WCIsvSListIter::reset( WCIsvSList & );void WCIsvDListIter::reset( WCIsvDList & );The reset public member function resets the iterator to operate on the specified list. The iterator ispositioned before the first element in the list.The iterator is positioned before the first element <strong>of</strong> the specified list.WCIsvSListIter, WCIsvDListIter, container342 List Iterators
WCPtrConstSListIter, WCPtrConstDListIterDeclared:wclistit.hThe WCPtrConstSListIter and WCPtrConstDListIter classes are thetemplated classes used to create iterator objects for constant single and double linked list objects. Theseclasses may be used to iterate over non-constant lists, but the WCPtrDListIter andWCPtrSListIter classes provide additional functionality for only non-constant lists.In the description <strong>of</strong> each member function, the text Type is used to indicate the list element typespecified as the template parameter.The WCIterExcept class is a base class <strong>of</strong> the WCPtrConstSListIter andWCPtrConstDListIter classes and provides the exceptions member function. Thismember function controls the exceptions which can be thrown by theWCPtrConstSListIter and WCPtrConstDListIter objects. No exceptionsare enabled unless they are set by the exceptions member function.Private Member FunctionsSome functionality supported by base classes <strong>of</strong> the iterator are not appropriate for the constant listiterator classes. Setting those functions as private members in the derived class is the standardmechanism to prevent them from being invoked.int append( Type * );int insert( Type * );Public Member FunctionsThe following member functions are declared in the public interface:WCPtrConstSListIter();WCPtrConstSListIter( const WCPtrSList & );~WCPtrConstSListIter();WCPtrConstDListIter();WCPtrConstDListIter( const WCPtrDList & );~WCPtrConstDListIter();const WCPtrSList *WCPtrConstSListIter::container() const;const WCPtrDList *WCPtrConstDListIter::container() const;Type * current() const;void reset();void WCPtrConstSListIter::reset( const WCPtrSList & );void WCPtrConstDListIter::reset( const WCPtrDList & );Public Member OperatorsThe following member operators are declared in the public interface:int operator ()();int operator ++();int operator +=( int );In the iterators for double linked lists only:int operator --();int operator -=( int );See Also:WCPtrSList::forAll, WCPtrDList::forAllList Iterators 343
WCPtrConstSListIter::WCPtrConstSListIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrConstSListIter();The WCPtrConstSListIter public member function is the default constructor for the class andinitializes the iterator with no list to operate on. The reset member function must be called to providethe iterator with a list to iterate over.The WCPtrConstSListIter public member function creates an initializedWCPtrConstSListIter object.WCPtrConstSListIter, ~WCPtrConstSListIter, reset344 List Iterators
WCPtrConstSListIter::WCPtrConstSListIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrConstSListIter( const WCPtrSList & );The WCPtrConstSListIter public member function is a constructor for the class. The valuepassed as a parameter is a WCPtrSList list object. The iterator will be initialized for that list objectand positioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCPtrConstSListIter public member function creates an initializedWCPtrConstSListIter object positioned before the first element in the list.~WCPtrConstSListIter, operator (), operator ++, operator +=, resetList Iterators 345
WCPtrConstSListIter::~WCPtrConstSListIter()Synopsis:Semantics:Results:See Also:#include public:~WCPtrConstSListIter();The ~WCPtrConstSListIter public member function is the destructor for the class. The call tothe ~WCPtrConstSListIter public member function is inserted implicitly by the compiler at thepoint where the WCPtrConstSListIter object goes out <strong>of</strong> scope.The WCPtrConstSListIter object is destroyed.WCPtrConstSListIter346 List Iterators
WCPtrConstDListIter::WCPtrConstDListIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrConstDListIter();The WCPtrConstDListIter public member function is the default constructor for the class andinitializes the iterator with no list to operate on. The reset member function must be called to providethe iterator with a list to iterate over.The WCPtrConstDListIter public member function creates an initializedWCPtrConstDListIter object.WCPtrConstDListIter, ~WCPtrConstDListIter, resetList Iterators 347
WCPtrConstDListIter::WCPtrConstDListIter()Synopsis:Semantics:Results:#include public:WCPtrConstDListIter( const WCPtrDList & );The WCPtrConstDListIter public member function is a constructor for the class. The valuepassed as a parameter is the WCPtrDList list object. The iterator will be initialized for that list objectand positioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCPtrConstDListIter public member function creates an initializedWCPtrConstDListIter object positioned before the first list element.See Also: WCPtrConstDListIter, ~WCPtrConstDListIter, operator (), operator ++,operator +=, reset348 List Iterators
WCPtrConstDListIter::~WCPtrConstDListIter()Synopsis:Semantics:Results:See Also:#include public:~WCPtrConstDListIter();The ~WCPtrConstDListIter public member function is the destructor for the class. The call tothe ~WCPtrConstDListIter public member function is inserted implicitly by the compiler at thepoint where the WCPtrConstDListIter object goes out <strong>of</strong> scope.The WCPtrConstDListIter object is destroyed.WCPtrConstDListIterList Iterators 349
WCPtrConstSListIter,WCPtrConstDListIter::container()Synopsis:Semantics:Results:See Also:#include public:const WCPtrSList *WCPtrConstSListIter::container() const;const WCPtrDList *WCPtrConstDListIter::container() const;The container public member function returns a pointer to the list container object. If the iteratorhas not been initialized with a list object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a list.WCPtrConstSListIter, WCPtrConstDListIter, reset, WCIterExcept::undef_iter350 List Iterators
WCPtrConstSListIter::current(), WCPtrConstDListIter::current()Synopsis:Semantics:#include public:Type * current();The current public member function returns a pointer to the list item at the current iterator position.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. In this case the undef_itemexception is thrown, if enabled.Results:See Also:A pointer to the current list element is returned. If the current element is undefined, an uninitializedpointer is returned.operator (), operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_itemList Iterators 351
WCPtrConstSListIter,WCPtrConstDListIter::operator ()()Synopsis:Semantics:#include public:int operator ()();The operator () public member function is the call operator for the class. The list element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_iter352 List Iterators
WCPtrConstSListIter,WCPtrConstDListIter::operator ++()Synopsis:Semantics:#include public:int operator ++();The operator ++ public member function is the pre-increment operator for the class. The listelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator ++ public member function has the same semantics as the call operator, operator().If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator +=, operator --, operator -=, reset,WCIterExcept::undef_iterList Iterators 353
WCPtrConstSListIter,WCPtrConstDListIter::operator +=()Synopsis:Semantics:#include public:int operator +=( int );The operator += public member function accepts an integer value that causes the iterator to movethat many elements after the current item. If the iterator was positioned before the first element in thelist, the operation will set the current item to be the given element in the list.If the current item was after the last element in the list previous to the iteration, and the undef_iterexception is enabled, the exception will be thrown. Attempting to increment the iterator position morethan element after the end <strong>of</strong> the list, or by less than one element causes the iter_range exception tobe thrown, if enabled.Results:See Also:The operator += public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator ++, operator --, operator -=, reset,WCIterExcept::iter_range, WCIterExcept::undef_iter354 List Iterators
WCPtrConstDListIter::operator --()Synopsis:Semantics:#include public:int operator --();The operator -- public member function is the pre-decrement operator for the class. The listelement previous to the current item is set to be the new current item. If the current item was the firstelement in the list, the iterator is positioned before the first element in the list. If the list is empty, theiterator will be positioned before the start <strong>of</strong> the list.If the iterator was positioned after the last element in the list, the current item will be set to the lastelement.If the iterator is not associated with a list or the iterator position previous to the decrement was beforethe first element the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator -- public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is decremented past the first element <strong>of</strong> the list.current, operator (), operator ++, operator +=, operator -=, reset,WCIterExcept::undef_iterList Iterators 355
WCPtrConstDListIter::operator -=()Synopsis:Semantics:#include public:int operator -=( int );The operator -= public member function accepts an integer value that causes the iterator to movethat many elements before the current item. If the iterator was positioned after the last element in thelist, the operation will set the current item to be the given number <strong>of</strong> elements from the end <strong>of</strong> the list.If the current item was before the first element in the list previous to the iteration, and theundef_iter exception is enabled, the exception will be thrown. Attempting to decrement the iteratorposition more than one element before the beginning <strong>of</strong> the list, or by less than one element causes theiter_range exception to be thrown, if enabled.Results:See Also:The operator -= public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is decremented past the first element in the list.current, operator (), operator ++, operator +=, operator --, reset,WCIterExcept::iter_range, WCIterExcept::undef_iter356 List Iterators
WCPtrConstSListIter::reset(), WCPtrConstDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated list.The iterator is positioned before the first list element.WCPtrConstSListIter, WCPtrConstDListIter, containerList Iterators 357
WCPtrConstSListIter::reset(), WCPtrConstDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void WCPtrConstSListIter::reset( const WCPtrSList & );void WCPtrConstDListIter::reset( const WCPtrDList & );The reset public member function resets the iterator to operate on the specified list. The iterator ispositioned before the first element in the list.The iterator is positioned before the first element <strong>of</strong> the specified list.WCPtrConstSListIter, WCPtrConstDListIter, container358 List Iterators
WCPtrSListIter, WCPtrDListIterDeclared:wclistit.hThe WCPtrSListIter and WCPtrDListIter classes are the templated classesused to create iterator objects for single and double linked list objects. These classes can be used onlyfor non-constant lists. The WCPtrDConstListIter andWCPtrSConstListIter classes are provided to iterate over constant lists.In the description <strong>of</strong> each member function, the text Type is used to indicate the list element typespecified as the template parameter.The WCIterExcept class is a base class <strong>of</strong> the WCPtrSListIter andWCPtrDListIter classes and provides the exceptions member function. This memberfunction controls the exceptions which can be thrown by the WCPtrSListIter andWCPtrDListIter objects. No exceptions are enabled unless they are set by theexceptions member function.Private Member FunctionsSome functionality supported by base classes <strong>of</strong> the iterator are not appropriate in the single linked listiterator classes. Setting those functions as private members in the derived class is the standardmechanism to prevent them from being invoked. The following member functions are declared in thesingle linked list iterator private interface:int operator --();int operator -=( int );int insert( Type * );Public Member FunctionsThe following member functions are declared in the public interface:WCPtrSListIter();WCPtrSListIter( WCPtrSList & );~WCPtrSListIter();WCPtrDListIter();WCPtrDListIter( WCPtrDList & );~WCPtrDListIter();int append( Type * );WCPtrSList *WCPtrSListIter::container() const;WCPtrDList *WCPtrDListIter::container() const;Type * current() const;void reset();void WCPtrSListIter::reset( WCPtrSList & );void WCPtrDListIter::reset( WCPtrDList & );In the iterators for double linked lists only:int insert( Type * );Public Member OperatorsThe following member operators are declared in the public interface:int operator ()();int operator ++();int operator +=( int );List Iterators 359
WCPtrSListIter, WCPtrDListIterIn the iterators for double linked lists only:int operator --();int operator -=( int );See Also:WCPtrSList::forAll, WCPtrDList::forAll360 List Iterators
WCPtrSListIter::WCPtrSListIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrSListIter();The WCPtrSListIter public member function is the default constructor for the class and initializesthe iterator with no list to operate on. The reset member function must be called to provide theiterator with a list to iterate over.The WCPtrSListIter public member function creates an initialized WCPtrSListIter object.WCPtrSListIter, ~WCPtrSListIter, resetList Iterators 361
WCPtrSListIter::WCPtrSListIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrSListIter( WCPtrSList & );The WCPtrSListIter public member function is a constructor for the class. The value passed as aparameter is a WCPtrSList list object. The iterator will be initialized for that list object andpositioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCPtrSListIter public member function creates an initialized WCPtrSListIter objectpositioned before the first element in the list.~WCPtrSListIter, operator (), operator ++, operator +=, reset362 List Iterators
WCPtrSListIter::~WCPtrSListIter()Synopsis:Semantics:Results:See Also:#include public:~WCPtrSListIter();The ~WCPtrSListIter public member function is the destructor for the class. The call to the~WCPtrSListIter public member function is inserted implicitly by the compiler at the point wherethe WCPtrSListIter object goes out <strong>of</strong> scope.The WCPtrSListIter object is destroyed.WCPtrSListIterList Iterators 363
WCPtrDListIter::WCPtrDListIter()Synopsis:Semantics:Results:See Also:#include public:WCPtrDListIter();The WCPtrDListIter public member function is the default constructor for the class and initializesthe iterator with no list to operate on. The reset member function must be called to provide theiterator with a list to iterate over.The WCPtrDListIter public member function creates an initialized WCPtrDListIter object.WCPtrDListIter, ~WCPtrDListIter, reset364 List Iterators
WCPtrDListIter::WCPtrDListIter()Synopsis:Semantics:Results:#include public:WCPtrDListIter( WCPtrDList & );The WCPtrDListIter public member function is a constructor for the class. The value passed as aparameter is the WCPtrDList list object. The iterator will be initialized for that list object andpositioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCPtrDListIter public member function creates an initialized WCPtrDListIter objectpositioned before the first list element.See Also: WCPtrDListIter, ~WCPtrDListIter, operator (), operator ++, operator +=,resetList Iterators 365
WCPtrDListIter::~WCPtrDListIter()Synopsis:Semantics:Results:See Also:#include public:~WCPtrDListIter();The ~WCPtrDListIter public member function is the destructor for the class. The call to the~WCPtrDListIter public member function is inserted implicitly by the compiler at the point wherethe WCPtrDListIter object goes out <strong>of</strong> scope.The WCPtrDListIter object is destroyed.WCPtrDListIter366 List Iterators
WCPtrSListIter::append(), WCPtrDListIter::append()Synopsis:Semantics:#include public:int append( Type * );The append public member function inserts a new element into the list container object. The newelement is inserted after the current iterator item.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. The element is not appended. Ifthe undef_iter exception is enabled, it is thrown.If the append fails, the out_<strong>of</strong>_memory exception is thrown, if enabled in the list being iterated over.The list remains unchanged.Results:See Also:The new element is inserted after the current iterator item. A TRUE value (non-zero) is returned if theappend is successful. A FALSE (zero) result is returned if the append fails.insert, WCExcept::out_<strong>of</strong>_memory, WCIterExcept::undef_iterList Iterators 367
WCPtrSListIter,WCPtrDListIter::container()Synopsis:Semantics:Results:See Also:#include public:WCPtrSList *WCPtrSListIter::container() const;WCPtrDList *WCPtrDListIter::container() const;The container public member function returns a pointer to the list container object. If the iteratorhas not been initialized with a list object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a list.WCPtrSListIter, WCPtrDListIter, reset, WCIterExcept::undef_iter368 List Iterators
WCPtrSListIter::current(), WCPtrDListIter::current()Synopsis:Semantics:#include public:Type * current();The current public member function returns a pointer to the list item at the current iterator position.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. In this case the undef_itemexception is thrown, if enabled.Results:See Also:A pointer to the current list element is returned. If the current element is undefined, an uninitializedpointer is returned.operator (), operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_itemList Iterators 369
WCPtrDListIter::insert()Synopsis:Semantics:#include public:int insert( Type * );The insert public member function inserts a new element into the list container object. The newelement is inserted before the current iterator item. This process uses the previous link in the doublelinked list, so the insert public member function is not allowed with single linked lists.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. The element is not inserted. If theundef_iter exception is enabled, the exception is thrown.If the insert fails and the out_<strong>of</strong>_memory exception is enabled in the list being iterated over, theexception is thrown. The list remains unchanged.Results:See Also:The new element is inserted before the current iterator item. A TRUE value (non-zero) is returned if theinsert is successful. A FALSE (zero) result is returned if the insert fails.append, WCExcept::out_<strong>of</strong>_memory, WCIterExcept::undef_iter370 List Iterators
WCPtrSListIter,WCPtrDListIter::operator ()()Synopsis:Semantics:#include public:int operator ()();The operator () public member function is the call operator for the class. The list element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_iterList Iterators 371
WCPtrSListIter,WCPtrDListIter::operator ++()Synopsis:Semantics:#include public:int operator ++();The operator ++ public member function is the pre-increment operator for the class. The listelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator ++ public member function has the same semantics as the call operator, operator().If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator +=, operator --, operator -=, reset,WCIterExcept::undef_iter372 List Iterators
WCPtrSListIter,WCPtrDListIter::operator +=()Synopsis:Semantics:#include public:int operator +=( int );The operator += public member function accepts an integer value that causes the iterator to movethat many elements after the current item. If the iterator was positioned before the first element in thelist, the operation will set the current item to be the given element in the list.If the current item was after the last element in the list previous to the iteration, and the undef_iterexception is enabled, the exception will be thrown. Attempting to increment the iterator position morethan element after the end <strong>of</strong> the list, or by less than one element causes the iter_range exception tobe thrown, if enabled.Results:See Also:The operator += public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator ++, operator --, operator -=, reset,WCIterExcept::iter_range, WCIterExcept::undef_iterList Iterators 373
WCPtrDListIter::operator --()Synopsis:Semantics:#include public:int operator --();The operator -- public member function is the pre-decrement operator for the class. The listelement previous to the current item is set to be the new current item. If the current item was the firstelement in the list, the iterator is positioned before the first element in the list. If the list is empty, theiterator will be positioned before the start <strong>of</strong> the list.If the iterator was positioned after the last element in the list, the current item will be set to the lastelement.If the iterator is not associated with a list or the iterator position previous to the decrement was beforethe first element the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator -- public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is decremented past the first element <strong>of</strong> the list.current, operator (), operator ++, operator +=, operator -=, reset,WCIterExcept::undef_iter374 List Iterators
WCPtrDListIter::operator -=()Synopsis:Semantics:#include public:int operator -=( int );The operator -= public member function accepts an integer value that causes the iterator to movethat many elements before the current item. If the iterator was positioned after the last element in thelist, the operation will set the current item to be the given number <strong>of</strong> elements from the end <strong>of</strong> the list.If the current item was before the first element in the list previous to the iteration, and theundef_iter exception is enabled, the exception will be thrown. Attempting to decrement the iteratorposition more than one element before the beginning <strong>of</strong> the list, or by less than one element causes theiter_range exception to be thrown, if enabled.Results:See Also:The operator -= public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is decremented past the first element in the list.current, operator (), operator ++, operator +=, operator --, reset,WCIterExcept::iter_range, WCIterExcept::undef_iterList Iterators 375
WCPtrSListIter::reset(), WCPtrDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated list.The iterator is positioned before the first list element.WCPtrSListIter, WCPtrDListIter, container376 List Iterators
WCPtrSListIter::reset(), WCPtrDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void WCPtrSListIter::reset( WCPtrSList & );void WCPtrDListIter::reset( WCPtrDList & );The reset public member function resets the iterator to operate on the specified list. The iterator ispositioned before the first element in the list.The iterator is positioned before the first element <strong>of</strong> the specified list.WCPtrSListIter, WCPtrDListIter, containerList Iterators 377
WCValConstSListIter, WCValConstDListIterDeclared:wclistit.hThe WCValConstSListIter and WCValConstDListIter classes are thetemplated classes used to create iterator objects for constant single and double linked list objects. Theseclasses may be used to iterate over non-constant lists, but the WCValDListIter andWCValSListIter classes provide additional functionality for only non-constant lists.In the description <strong>of</strong> each member function, the text Type is used to indicate the list element typespecified as the template parameter.The WCIterExcept class is a base class <strong>of</strong> the WCValConstSListIter andWCValConstDListIter classes and provides the exceptions member function. Thismember function controls the exceptions which can be thrown by theWCValConstSListIter and WCValConstDListIter objects. No exceptionsare enabled unless they are set by the exceptions member function.Private Member FunctionsSome functionality supported by base classes <strong>of</strong> the iterator are not appropriate for the constant listiterator classes. Setting those functions as private members in the derived class is the standardmechanism to prevent them from being invoked.int append( Type & );int insert( Type & );Public Member FunctionsThe following member functions are declared in the public interface:WCValConstSListIter();WCValConstSListIter( const WCValSList & );~WCValConstSListIter();WCValConstDListIter();WCValConstDListIter( const WCValDList & );~WCValConstDListIter();const WCValSList *WCValConstSListIter::container() const;const WCValDList *WCValConstDListIter::container() const;Type current() const;void reset();void WCValConstSListIter::reset( const WCValSList & );void WCValConstDListIter::reset( const WCValDList & );Public Member OperatorsThe following member operators are declared in the public interface:int operator ()();int operator ++();int operator +=( int );In the iterators for double linked lists only:int operator --();int operator -=( int );See Also:WCValSList::forAll, WCValDList::forAll378 List Iterators
WCValConstSListIter::WCValConstSListIter()Synopsis:Semantics:Results:See Also:#include public:WCValConstSListIter();The WCValConstSListIter public member function is the default constructor for the class andinitializes the iterator with no list to operate on. The reset member function must be called to providethe iterator with a list to iterate over.The WCValConstSListIter public member function creates an initializedWCValConstSListIter object.WCValConstSListIter, ~WCValConstSListIter, resetList Iterators 379
WCValConstSListIter::WCValConstSListIter()Synopsis:Semantics:Results:See Also:#include public:WCValConstSListIter( const WCValSList & );The WCValConstSListIter public member function is a constructor for the class. The valuepassed as a parameter is a WCValSList list object. The iterator will be initialized for that list objectand positioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCValConstSListIter public member function creates an initializedWCValConstSListIter object positioned before the first element in the list.~WCValConstSListIter, operator (), operator ++, operator +=, reset380 List Iterators
WCValConstSListIter::~WCValConstSListIter()Synopsis:Semantics:Results:See Also:#include public:~WCValConstSListIter();The ~WCValConstSListIter public member function is the destructor for the class. The call tothe ~WCValConstSListIter public member function is inserted implicitly by the compiler at thepoint where the WCValConstSListIter object goes out <strong>of</strong> scope.The WCValConstSListIter object is destroyed.WCValConstSListIterList Iterators 381
WCValConstDListIter::WCValConstDListIter()Synopsis:Semantics:Results:See Also:#include public:WCValConstDListIter();The WCValConstDListIter public member function is the default constructor for the class andinitializes the iterator with no list to operate on. The reset member function must be called to providethe iterator with a list to iterate over.The WCValConstDListIter public member function creates an initializedWCValConstDListIter object.WCValConstDListIter, ~WCValConstDListIter, reset382 List Iterators
WCValConstDListIter::WCValConstDListIter()Synopsis:Semantics:Results:#include public:WCValConstDListIter( const WCValDList & );The WCValConstDListIter public member function is a constructor for the class. The valuepassed as a parameter is the WCValDList list object. The iterator will be initialized for that list objectand positioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCValConstDListIter public member function creates an initializedWCValConstDListIter object positioned before the first list element.See Also: WCValConstDListIter, ~WCValConstDListIter, operator (), operator ++,operator +=, resetList Iterators 383
WCValConstDListIter::~WCValConstDListIter()Synopsis:Semantics:Results:See Also:#include public:~WCValConstDListIter();The ~WCValConstDListIter public member function is the destructor for the class. The call tothe ~WCValConstDListIter public member function is inserted implicitly by the compiler at thepoint where the WCValConstDListIter object goes out <strong>of</strong> scope.The WCValConstDListIter object is destroyed.WCValConstDListIter384 List Iterators
WCValConstSListIter,WCValConstDListIter::container()Synopsis:Semantics:Results:See Also:#include public:const WCValSList *WCValConstSListIter::container() const;const WCValDList *WCValConstDListIter::container() const;The container public member function returns a pointer to the list container object. If the iteratorhas not been initialized with a list object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a list.WCValConstSListIter, WCValConstDListIter, reset, WCIterExcept::undef_iterList Iterators 385
WCValConstSListIter::current(), WCValConstDListIter::current()Synopsis:Semantics:#include public:Type current();The current public member function returns the value <strong>of</strong> the list element at the current iteratorposition.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. In this case the undef_itemexception is thrown, if enabled.Results:See Also:The value at the current iterator element is returned. If the current element is undefined, a defaultinitialized object is returned.operator (), operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_item386 List Iterators
WCValConstSListIter,WCValConstDListIter::operator ()()Synopsis:Semantics:#include public:int operator ()();The operator () public member function is the call operator for the class. The list element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_iterList Iterators 387
WCValConstSListIter,WCValConstDListIter::operator ++()Synopsis:Semantics:#include public:int operator ++();The operator ++ public member function is the pre-increment operator for the class. The listelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator ++ public member function has the same semantics as the call operator, operator().If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator +=, operator --, operator -=, reset,WCIterExcept::undef_iter388 List Iterators
WCValConstSListIter,WCValConstDListIter::operator +=()Synopsis:Semantics:#include public:int operator +=( int );The operator += public member function accepts an integer value that causes the iterator to movethat many elements after the current item. If the iterator was positioned before the first element in thelist, the operation will set the current item to be the given element in the list.If the current item was after the last element in the list previous to the iteration, and the undef_iterexception is enabled, the exception will be thrown. Attempting to increment the iterator position morethan element after the end <strong>of</strong> the list, or by less than one element causes the iter_range exception tobe thrown, if enabled.Results:See Also:The operator += public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator ++, operator --, operator -=, reset,WCIterExcept::iter_range, WCIterExcept::undef_iterList Iterators 389
WCValConstDListIter::operator --()Synopsis:Semantics:#include public:int operator --();The operator -- public member function is the pre-decrement operator for the class. The listelement previous to the current item is set to be the new current item. If the current item was the firstelement in the list, the iterator is positioned before the first element in the list. If the list is empty, theiterator will be positioned before the start <strong>of</strong> the list.If the iterator was positioned after the last element in the list, the current item will be set to the lastelement.If the iterator is not associated with a list or the iterator position previous to the decrement was beforethe first element the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator -- public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is decremented past the first element <strong>of</strong> the list.current, operator (), operator ++, operator +=, operator -=, reset,WCIterExcept::undef_iter390 List Iterators
WCValConstDListIter::operator -=()Synopsis:Semantics:#include public:int operator -=( int );The operator -= public member function accepts an integer value that causes the iterator to movethat many elements before the current item. If the iterator was positioned after the last element in thelist, the operation will set the current item to be the given number <strong>of</strong> elements from the end <strong>of</strong> the list.If the current item was before the first element in the list previous to the iteration, and theundef_iter exception is enabled, the exception will be thrown. Attempting to decrement the iteratorposition more than one element before the beginning <strong>of</strong> the list, or by less than one element causes theiter_range exception to be thrown, if enabled.Results:See Also:The operator -= public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is decremented past the first element in the list.current, operator (), operator ++, operator +=, operator --, reset,WCIterExcept::iter_range, WCIterExcept::undef_iterList Iterators 391
WCValConstSListIter::reset(), WCValConstDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated list.The iterator is positioned before the first list element.WCValConstSListIter, WCValConstDListIter, container392 List Iterators
WCValConstSListIter::reset(), WCValConstDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void WCValConstSListIter::reset( const WCValSList & );void WCValConstDListIter::reset( const WCValDList & );The reset public member function resets the iterator to operate on the specified list. The iterator ispositioned before the first element in the list.The iterator is positioned before the first element <strong>of</strong> the specified list.WCValConstSListIter, WCValConstDListIter, containerList Iterators 393
WCValSListIter, WCValDListIterDeclared:wclistit.hThe WCValSListIter and WCValDListIter classes are the templated classesused to create iterator objects for single and double linked list objects. These classes can be used onlyfor non-constant lists. The WCValDConstListIter andWCValSConstListIter classes are provided to iterate over constant lists.In the description <strong>of</strong> each member function, the text Type is used to indicate the list element typespecified as the template parameter.The WCIterExcept class is a base class <strong>of</strong> the WCValSListIter andWCValDListIter classes and provides the exceptions member function. This memberfunction controls the exceptions which can be thrown by the WCValSListIter andWCValDListIter objects. No exceptions are enabled unless they are set by theexceptions member function.Private Member FunctionsSome functionality supported by base classes <strong>of</strong> the iterator are not appropriate in the single linked listiterator classes. Setting those functions as private members in the derived class is the standardmechanism to prevent them from being invoked. The following member functions are declared in thesingle linked list iterator private interface:int operator --();int operator -=( int );int insert( Type & );Public Member FunctionsThe following member functions are declared in the public interface:WCValSListIter();WCValSListIter( WCValSList & );~WCValSListIter();WCValDListIter();WCValDListIter( WCValDList & );~WCValDListIter();int append( Type & );WCValSList *WCValSListIter::container() const;WCValDList *WCValDListIter::container() const;Type current() const;void reset();void WCValSListIter::reset( WCValSList & );void WCValDListIter::reset( WCValDList & );In the iterators for double linked lists only:int insert( Type & );Public Member OperatorsThe following member operators are declared in the public interface:int operator ()();int operator ++();int operator +=( int );394 List Iterators
WCValSListIter, WCValDListIterIn the iterators for double linked lists only:int operator --();int operator -=( int );See Also:WCValSList::forAll, WCValDList::forAllSample Program Using Value List Iterators#include #include //// insert elem after all elements in the list less than or equal to// elem//void insert_in_order( WCValDList &list, int elem ) {if( list.entries() == 0 ) {// cannot insert in an empty list using a iteratorlist.insert( elem );} else {WCValDListIter iter( list );while( ++iter ) {if( iter.current() > elem ) {// insert elem before first element in list greater// than elemiter.insert( elem );return;}}}}// iterated past the end <strong>of</strong> the list// append elem to the end <strong>of</strong> the listlist.append( elem );void main() {WCValDList list;insert_in_order( list, 5 );insert_in_order( list, 20 );insert_in_order( list, 1 );insert_in_order( list, 25 );cout
WCValSListIter::WCValSListIter()Synopsis:Semantics:Results:See Also:#include public:WCValSListIter();The WCValSListIter public member function is the default constructor for the class and initializesthe iterator with no list to operate on. The reset member function must be called to provide theiterator with a list to iterate over.The WCValSListIter public member function creates an initialized WCValSListIter object.WCValSListIter, ~WCValSListIter, reset396 List Iterators
WCValSListIter::WCValSListIter()Synopsis:Semantics:Results:See Also:#include public:WCValSListIter( WCValSList & );The WCValSListIter public member function is a constructor for the class. The value passed as aparameter is a WCValSList list object. The iterator will be initialized for that list object andpositioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCValSListIter public member function creates an initialized WCValSListIter objectpositioned before the first element in the list.~WCValSListIter, operator (), operator ++, operator +=, resetList Iterators 397
WCValSListIter::~WCValSListIter()Synopsis:Semantics:Results:See Also:#include public:~WCValSListIter();The ~WCValSListIter public member function is the destructor for the class. The call to the~WCValSListIter public member function is inserted implicitly by the compiler at the point wherethe WCValSListIter object goes out <strong>of</strong> scope.The WCValSListIter object is destroyed.WCValSListIter398 List Iterators
WCValDListIter::WCValDListIter()Synopsis:Semantics:Results:See Also:#include public:WCValDListIter();The WCValDListIter public member function is the default constructor for the class and initializesthe iterator with no list to operate on. The reset member function must be called to provide theiterator with a list to iterate over.The WCValDListIter public member function creates an initialized WCValDListIter object.WCValDListIter, ~WCValDListIter, resetList Iterators 399
WCValDListIter::WCValDListIter()Synopsis:Semantics:Results:#include public:WCValDListIter( WCValDList & );The WCValDListIter public member function is a constructor for the class. The value passed as aparameter is the WCValDList list object. The iterator will be initialized for that list object andpositioned before the first list element. To position the iterator to a valid element within the list,increment it using any <strong>of</strong> the operator ++, operator (), or operator += operators.The WCValDListIter public member function creates an initialized WCValDListIter objectpositioned before the first list element.See Also: WCValDListIter, ~WCValDListIter, operator (), operator ++, operator +=,reset400 List Iterators
WCValDListIter::~WCValDListIter()Synopsis:Semantics:Results:See Also:#include public:~WCValDListIter();The ~WCValDListIter public member function is the destructor for the class. The call to the~WCValDListIter public member function is inserted implicitly by the compiler at the point wherethe WCValDListIter object goes out <strong>of</strong> scope.The WCValDListIter object is destroyed.WCValDListIterList Iterators 401
WCValSListIter::append(), WCValDListIter::append()Synopsis:Semantics:#include public:int append( Type & );The append public member function inserts a new element into the list container object. The newelement is inserted after the current iterator item.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. The element is not appended. Ifthe undef_iter exception is enabled, it is thrown.If the append fails, the out_<strong>of</strong>_memory exception is thrown, if enabled in the list being iterated over.The list remains unchanged.Results:See Also:The new element is inserted after the current iterator item. A TRUE value (non-zero) is returned if theappend is successful. A FALSE (zero) result is returned if the append fails.insert, WCExcept::out_<strong>of</strong>_memory, WCIterExcept::undef_iter402 List Iterators
WCValSListIter,WCValDListIter::container()Synopsis:Semantics:Results:See Also:#include public:WCValSList *WCValSListIter::container() const;WCValDList *WCValDListIter::container() const;The container public member function returns a pointer to the list container object. If the iteratorhas not been initialized with a list object, and the undef_iter exception is enabled, the exception isthrown.A pointer to the list object associated with the iterator is returned, or NULL(0) if the iterator has notbeen initialized with a list.WCValSListIter, WCValDListIter, reset, WCIterExcept::undef_iterList Iterators 403
WCValSListIter::current(), WCValDListIter::current()Synopsis:Semantics:#include public:Type current();The current public member function returns the value <strong>of</strong> the list element at the current iteratorposition.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. In this case the undef_itemexception is thrown, if enabled.Results:See Also:The value at the current iterator element is returned. If the current element is undefined, a defaultinitialized object is returned.operator (), operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_item404 List Iterators
WCValDListIter::insert()Synopsis:Semantics:#include public:int insert( Type & );The insert public member function inserts a new element into the list container object. The newelement is inserted before the current iterator item. This process uses the previous link in the doublelinked list, so the insert public member function is not allowed with single linked lists.If the iterator is not associated with a list, or the iterator position is either before the first element or pastthe last element in the list, the current iterator position is undefined. The element is not inserted. If theundef_iter exception is enabled, the exception is thrown.If the insert fails and the out_<strong>of</strong>_memory exception is enabled in the list being iterated over, theexception is thrown. The list remains unchanged.Results:See Also:The new element is inserted before the current iterator item. A TRUE value (non-zero) is returned if theinsert is successful. A FALSE (zero) result is returned if the insert fails.append, WCExcept::out_<strong>of</strong>_memory, WCIterExcept::undef_iterList Iterators 405
WCValSListIter,WCValDListIter::operator ()()Synopsis:Semantics:#include public:int operator ()();The operator () public member function is the call operator for the class. The list element whichfollows the current item is set to be the new current item. If the previous current item was the lastelement in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator () public member function has the same semantics as the pre-increment operator,operator ++.If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator () public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.operator ++, operator +=, operator --, operator -=, reset,WCIterExcept::undef_iter406 List Iterators
WCValSListIter,WCValDListIter::operator ++()Synopsis:Semantics:#include public:int operator ++();The operator ++ public member function is the pre-increment operator for the class. The listelement which follows the current item is set to be the new current item. If the previous current itemwas the last element in the list, the iterator is positioned after the end <strong>of</strong> the list.The operator ++ public member function has the same semantics as the call operator, operator().If the iterator was positioned before the first element in the list, the current item will be set to the firstelement in the list. If the list is empty, the iterator will be positioned after the end <strong>of</strong> the list.If the iterator is not associated with a list or the iterator position before the increment was past the lastelement the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator ++ public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator +=, operator --, operator -=, reset,WCIterExcept::undef_iterList Iterators 407
WCValSListIter,WCValDListIter::operator +=()Synopsis:Semantics:#include public:int operator +=( int );The operator += public member function accepts an integer value that causes the iterator to movethat many elements after the current item. If the iterator was positioned before the first element in thelist, the operation will set the current item to be the given element in the list.If the current item was after the last element in the list previous to the iteration, and the undef_iterexception is enabled, the exception will be thrown. Attempting to increment the iterator position morethan element after the end <strong>of</strong> the list, or by less than one element causes the iter_range exception tobe thrown, if enabled.Results:See Also:The operator += public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is incremented past the end <strong>of</strong> the list.current, operator (), operator ++, operator --, operator -=, reset,WCIterExcept::iter_range, WCIterExcept::undef_iter408 List Iterators
WCValDListIter::operator --()Synopsis:Semantics:#include public:int operator --();The operator -- public member function is the pre-decrement operator for the class. The listelement previous to the current item is set to be the new current item. If the current item was the firstelement in the list, the iterator is positioned before the first element in the list. If the list is empty, theiterator will be positioned before the start <strong>of</strong> the list.If the iterator was positioned after the last element in the list, the current item will be set to the lastelement.If the iterator is not associated with a list or the iterator position previous to the decrement was beforethe first element the list, the undef_iter exception is thrown, if enabled.Results:See Also:The operator -- public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is decremented past the first element <strong>of</strong> the list.current, operator (), operator ++, operator +=, operator -=, reset,WCIterExcept::undef_iterList Iterators 409
WCValDListIter::operator -=()Synopsis:Semantics:#include public:int operator -=( int );The operator -= public member function accepts an integer value that causes the iterator to movethat many elements before the current item. If the iterator was positioned after the last element in thelist, the operation will set the current item to be the given number <strong>of</strong> elements from the end <strong>of</strong> the list.If the current item was before the first element in the list previous to the iteration, and theundef_iter exception is enabled, the exception will be thrown. Attempting to decrement the iteratorposition more than one element before the beginning <strong>of</strong> the list, or by less than one element causes theiter_range exception to be thrown, if enabled.Results:See Also:The operator -= public member function returns a non-zero value if the iterator is positioned on alist item. Zero(0) is returned when the iterator is decremented past the first element in the list.current, operator (), operator ++, operator +=, operator --, reset,WCIterExcept::iter_range, WCIterExcept::undef_iter410 List Iterators
WCValSListIter::reset(), WCValDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void reset();The reset public member function resets the iterator to the initial state, positioning the iterator beforethe first element in the associated list.The iterator is positioned before the first list element.WCValSListIter, WCValDListIter, containerList Iterators 411
WCValSListIter::reset(), WCValDListIter::reset()Synopsis:Semantics:Results:See Also:#include public:void WCValSListIter::reset( WCValSList & );void WCValDListIter::reset( WCValDList & );The reset public member function resets the iterator to operate on the specified list. The iterator ispositioned before the first element in the list.The iterator is positioned before the first element <strong>of</strong> the specified list.WCValSListIter, WCValDListIter, container412 List Iterators
14 Queue ContainerQueue containers maintain an ordered collection <strong>of</strong> data which is retrieved in the order in which the datawas entered into the queue. The queue class is implemented as a templated class, allowing the use <strong>of</strong> anydata type as the queue data.A second template parameter specifies the storage class used to implement the queue. The WCValSList,WCIsvSList and WCPtrSList classes are appropriate storage classes.Queue Container 413
WCQueueDeclared:wcqueue.hThe WCQueue class is a templated class used to create objects which maintain data ina queue.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type <strong>of</strong> the elements stored in the queue. The text FType is used to indicate the templateparameter defining the storage class used to maintain the queue.For example, to create a queue <strong>of</strong> integers, the WCQueue class can beused. The WCQueue class will create a queue <strong>of</strong> pointers tointegers. To create an intrusive queue <strong>of</strong> objects <strong>of</strong> type isv_link (derived from the WCSLink class), theWCQueue< isv_link *,WCIsvSList< isv_link > > class can be used.The WCExcept class is a base class <strong>of</strong> the WCQueue class and provides theexceptions member function. This member function controls the exceptions which can be thrownby the WCQueue object. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> TypeType must provide any constructors and/or operators required by the FType class.Public Member FunctionsThe following member functions are declared in the public interface:WCQueue();WCQueue( void *(*)( size_t ), void (*)( void *, size_t ) );~WCQueue();void clear();int entries() const;Type first() const;Type get();int insert( const Type & );int isEmpty() const;Type last() const;Sample Program Using a Queue#include #include main() {WCQueuequeue;queue.insert( 7 );queue.insert( 8 );queue.insert( 9 );queue.insert( 10 );}cout
WCQueue::WCQueue()Synopsis:Semantics:Results:See Also:#include public:WCQueue();The public WCQueue constructor creates an empty WCQueueobject. The FType storage class constructor performs the initialization.The public WCQueue constructor creates an initialized WCQueueobject.~WCQueueQueue Container 415
WCQueue::WCQueue()Synopsis:Semantics:#include public:WCQueue( void *(*allocator)( size_t ),void (*deallocator)( void *, size_t ) );The public WCQueue constructor creates an empty WCQueueobject. If FType is either the WCValSList or WCPtrSList class, then the allocator function isregistered to perform all memory allocations <strong>of</strong> the queue elements, and the deallocator function toperform all freeing <strong>of</strong> the queue elements’ memory. The allocator and deallocator functions areignored if FType is the WCIsvSList class. These functions provide the ability to control how theallocation and freeing <strong>of</strong> memory is performed, allowing for more efficient memory handling than thegeneral purpose global operator new() and operator delete() can provide. Memorymanagement optimizations may potentially be made through the allocator and deallocator functions,but are not recommended before managing memory is understood and determined to be worth while.The allocator function shall return a pointer to allocated memory <strong>of</strong> size at least the argument, orzero(0) if the allocation cannot be performed. Initialization <strong>of</strong> the memory returned is performed by theWCQueue class.The WCQueue class calls the deallocator function only on memory allocated by theallocator function. The deallocator shall free the memory pointed to by the first argument which is <strong>of</strong>size the second argument. The size passed to the deallocator function is guaranteed to be the same sizepassed to the allocator function when the memory was allocated.The allocator and deallocator functions may assume that for a list object instance, the allocator isalways called with the same first argument (the size <strong>of</strong> the memory to be allocated). If FType is theWCValSList class, then the WCValSListItemSize( Type ) macro returns the size <strong>of</strong>the elements which are allocated by the allocator function. Similarly, the WCPtrSListItemSize(Type ) macro returns the size <strong>of</strong> WCPtrSList elements.The FType storage class constructor performs the initialization <strong>of</strong> the queue.Results:See Also:The public WCQueue constructor creates an initialized WCQueueobject and registers the allocator and deallocator functions.WCQueue, ~WCQueue416 Queue Container
WCQueue::~WCQueue()Synopsis:Semantics:#include public:virtual ~WCQueue();The public ~WCQueue destructor destroys the WCQueue object.The FType storage class destructor performs the destruction. The call to the public~WCQueue destructor is inserted implicitly by the compiler at the point where theWCQueue object goes out <strong>of</strong> scope.If the not_empty exception is enabled, the exception is thrown if the queue is not empty <strong>of</strong> queueelements.Results:See Also:The WCQueue object is destroyed.WCQueue, clear, WCExcept::not_emptyQueue Container 417
WCQueue::clear()Synopsis:Semantics:Results:See Also:#include public:void clear();The clear public member function is used to clear the queue object and set it to the state <strong>of</strong> the objectjust after the initial construction. The queue object is not destroyed and re-created by this operator, sothe object destructor is not invoked. The queue elements are not cleared by the queue class. However,the class used to maintain the queue, FType, may clear the items as part <strong>of</strong> the clear function for thatclass. If it does not clear the items, any queue items still in the list are lost unless pointed to by somepointer object in the program code.The clear public member function resets the queue object to the state <strong>of</strong> the object immediately afterthe initial construction.~WCQueue, isEmpty418 Queue Container
WCQueue::entries()Synopsis:Semantics:Results:See Also:#include public:int entries() const;The entries public member function is used to determine the number <strong>of</strong> queue elements contained inthe list object.The number <strong>of</strong> elements in the queue is returned. Zero(0) is returned if there are no queue elements.isEmptyQueue Container 419
WCQueue::first()Synopsis:Semantics:#include public:Type first() const;The first public member function returns a queue element from the beginning <strong>of</strong> the queue object.The queue element is not removed from the queue.If the queue is empty, one <strong>of</strong> two exceptions can be thrown. If the empty_container exception isenabled, then it will be thrown. Otherwise, the index_range exception will be thrown, if enabled.Results:See Also:The first queue element is returned. If there are no elements in the queue, the return value is determinedby the find member function <strong>of</strong> the FType class.get, isEmpty, last, WCExcept::empty_container, WCExcept::index_range,FType::find420 Queue Container
WCQueue::get()Synopsis:Semantics:#include public:Type get();The get public member function returns the queue element which was first inserted into the queueobject. The queue element is also removed from the queue.If the queue is empty, one <strong>of</strong> two exceptions can be thrown. If the empty_container exception isenabled, then it will be thrown. Otherwise, the index_range exception will be thrown, if enabled.Results:See Also:The first element in the queue is removed and returned. If there are no elements in the queue, the returnvalue is determined by the get member function <strong>of</strong> the FType class.first, insert, isEmpty, WCExcept::empty_container, WCExcept::index_range,FType::getQueue Container 421
WCQueue::insert()Synopsis:Semantics:#include public:int insert( const Type & );The insert public member function is used to insert the data into the queue. It will be the lastelement in the queue, and the last to be retrieved.If the insert fails, the out_<strong>of</strong>_memory exception will be thrown, if enabled. The queue will remainunchanged.Results:See Also:The queue element is inserted at the end <strong>of</strong> the queue. A TRUE value (non-zero) is returned if the insertis successful. A FALSE (zero) result is returned if the insert fails.get, WCExcept::out_<strong>of</strong>_memory422 Queue Container
WCQueue::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if a queue object has any queue elementscontained in it.A TRUE value (non-zero) is returned if the queue object does not have any queue elements containedwithin it. A FALSE (zero) result is returned if the queue contains at least one element.entriesQueue Container 423
WCQueue::last()Synopsis:Semantics:#include public:Type last() const;The last public member function returns a queue element from the end <strong>of</strong> the queue object. Thequeue element is not removed from the queue.If the queue is empty, one <strong>of</strong> two exceptions can be thrown. If the empty_container exception isenabled, then it will be thrown. Otherwise, the index_range exception will be thrown, if enabled.Results:See Also:The last queue element is returned. If there are no elements in the queue, the return value is determinedby the find member function <strong>of</strong> the FType class.first, get, isEmpty, WCExcept::empty_container, WCExcept::index_range,FType::find424 Queue Container
15 Skip List ContainersThis chapter describes skip list containers.Skip List Containers 425
WCPtrSkipListDictDeclared:wcskip.hThe WCPtrSkipListDict class is a templated class used to store objects in adictionary. Dictionaries store values with an associated key, which may be <strong>of</strong> any type. One example<strong>of</strong> a dictionary used in everyday life is the phone book. The phone numbers are the data values, and thecustomer name is the key. The equality operator <strong>of</strong> the key’s type is used to locate the key-value pairs.In the description <strong>of</strong> each member function, the text Key is used to indicate the template parameterdefining the type <strong>of</strong> the indices pointed to by the pointers stored in the dictionary. The text Value isused to indicate the template parameter defining the type <strong>of</strong> the data pointed to by the pointers stored inthe dictionary.Note that pointers to the key values are stored in the dictionary. Destructors are not called on the keyspointed to. The key values pointed to in the dictionary should not be changed such that the equivalenceto the old value is modified.The iterator classes for skip lists have the same function and operator interface as the hash iteratorsclasses. See the chapter on hash iterators for more information.The WCExcept class is a base class <strong>of</strong> the WCPtrSkipListDict class and providesthe exceptions member function. This member function controls the exceptions which can bethrown by the WCPtrSkipListDict object. No exceptions are enabled unless theyare set by the exceptions member function.Requirements <strong>of</strong> KeyThe WCPtrSkipListDict class requires Key to have:A well defined equivalence operator with constant parameters( int operator ==( const Key & ) const ).A well defined operator less than with constant parameters( int operator
WCPtrSkipListDictPublic Member OperatorsThe following member operators are declared in the public interface:Value * & operator []( const Key * );Value * const & operator []( const Key * ) const;WCPtrSkipListDict & operator =( const WCPtrSkipListDict & );int operator ==( const WCPtrSkipListDict & ) const;Skip List Containers 427
WCPtrSkipListDict::WCPtrSkipListDict()Synopsis:Semantics:Results:See Also:#include public:WCPtrSkipListDict( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS );The public WCPtrSkipListDict constructor creates anWCPtrSkipListDict object with no entries. The first optional parameter, whichdefaults to the constant WCSKIPLIST_PROB_QUARTER, determines the probability <strong>of</strong> having acertain number <strong>of</strong> pointers in each skip list node. The second optional parameter, which defaults to theconstant WCDEFAULT_SKIPLIST_MAX_PTRS, determines the maximum number <strong>of</strong> pointers thatare allowed in any skip list node. WCDEFAULT_SKIPLIST_MAX_PTRS is the maximum effectivevalue <strong>of</strong> the second parameter. If an allocation failure occurs while creating the skip list, theout_<strong>of</strong>_memory exception is thrown if the out_<strong>of</strong>_memory exception is enabled.The public WCPtrSkipListDict constructor creates an initializedWCPtrSkipListDict object.~WCPtrSkipListDict, WCExcept::out_<strong>of</strong>_memory428 Skip List Containers
WCPtrSkipListDict::WCPtrSkipListDict()Synopsis:Semantics:#include public:WCPtrSkipListDict( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thelist dictionary. The semantics <strong>of</strong> this constructor are the same as the constructor without the memorymanagement functions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a list dictionary. To determine the size <strong>of</strong> the objects that the memorymanagement functions will be required to allocate and free, the following macro may be used:WCPtrSkipListDictItemSize( Key, Value, num_<strong>of</strong>_pointers )Results:See Also:The public WCPtrSkipListDict constructor creates an initializedWCPtrSkipListDict object.~WCPtrSkipListDict, WCExcept::out_<strong>of</strong>_memorySkip List Containers 429
WCPtrSkipListDict::WCPtrSkipListDict()Synopsis:Semantics:Results:See Also:#include public:WCPtrSkipListDict( const WCPtrSkipListDict & );The public WCPtrSkipListDict constructor is the copy constructor for theWCPtrSkipListDict class. The new skip list is created with the same probabilityand maximum pointers, all values or pointers stored in the list, and the exception trap states. If there isnot enough memory to copy all <strong>of</strong> the values, then only some will be copied, and the number <strong>of</strong> entrieswill correctly reflect the number copied. If all <strong>of</strong> the elements cannot be copied, then theout_<strong>of</strong>_memory exception is thrown if it is enabled.The public WCPtrSkipListDict constructor creates anWCPtrSkipListDict object which is a copy <strong>of</strong> the passed dictionary.operator =, WCExcept::out_<strong>of</strong>_memory430 Skip List Containers
WCPtrSkipListDict::~WCPtrSkipListDict()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCPtrSkipListDict();The public ~WCPtrSkipListDict destructor is the destructor for theWCPtrSkipListDict class. If the number <strong>of</strong> dictionary elements is not zero andthe not_empty exception is enabled, the exception is thrown. Otherwise, the dictionary elements arecleared using the clear member function. The objects which the dictionary elements point to are notdeleted unless the clearAndDestroy member function is explicitly called before the destructor iscalled. The call to the public ~WCPtrSkipListDict destructor is insertedimplicitly by the compiler at the point where the WCPtrSkipListDict object goesout <strong>of</strong> scope.The public ~WCPtrSkipListDict destructor destroys anWCPtrSkipListDict object.clear, clearAndDestroy, WCExcept::not_emptySkip List Containers 431
WCPtrSkipListDict::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the dictionary so that it has no entries. Objectspointed to by the dictionary elements are not deleted. The dictionary object is not destroyed andre-created by this function, so the object destructor is not invoked.The clear public member function clears the dictionary to have no elements.See Also: ~WCPtrSkipListDict, clearAndDestroy, operator =432 Skip List Containers
WCPtrSkipListDict::clearAndDestroy()Synopsis:Semantics:Results:See Also:#include public:void clearAndDestroy();The clearAndDestroy public member function is used to clear the dictionary and delete the objectspointed to by the dictionary elements. The dictionary object is not destroyed and re-created by thisfunction, so the dictionary object destructor is not invoked.The clearAndDestroy public member function clears the dictionary by deleting the objects pointedto by the dictionary elements.clearSkip List Containers 433
WCPtrSkipListDict::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Key * ) const;The contains public member function returns non-zero if an element with the specified key is storedin the dictionary, or zero if there is no equivalent element. Note that equivalence is based on theequivalence operator <strong>of</strong> the Key type.The contains public member function returns a non-zero value if the Key is found in the dictionary.find, findKeyAndValue434 Skip List Containers
WCPtrSkipListDict::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to return the current number <strong>of</strong> elements stored in thedictionary.The entries public member function returns the number <strong>of</strong> elements in the dictionary.isEmptySkip List Containers 435
WCPtrSkipListDict::find()Synopsis:Semantics:Results:See Also:#include public:Value * find( const Key * ) const;The find public member function is used to find an element with an equivalent key in the dictionary.If an equivalent element is found, a pointer to the element Value is returned. Zero is returned if theelement is not found. Note that equivalence is based on the equivalence operator <strong>of</strong> the Key type.The element equivalent to the passed key is located in the dictionary.findKeyAndValue436 Skip List Containers
WCPtrSkipListDict::findKeyAndValue()Synopsis:Semantics:Results:See Also:#include public:Value * findKeyAndValue( const Key *, Key * & ) const;The findKeyAndValue public member function is used to find an element in the dictionary with ankey equivalent to the first parameter. If an equivalent element is found, a pointer to the element Valueis returned. The reference to a Key passed as the second parameter is assigned the found element’s key.Zero is returned if the element is not found. Note that equivalence is based on the equivalence operator<strong>of</strong> the Key type.The element equivalent to the passed key is located in the dictionary.findKeyAndValueSkip List Containers 437
WCPtrSkipListDict::forAll()Synopsis:Semantics:#include public:void forAll(void (*user_fn)( Key *, Value *, void * ),void * );The forAll public member function causes the user supplied function to be invoked for everykey-value pair in the dictionary. The user function has the prototypevoid user_func( Key * key, Value * value, void * data );As the elements are visited, the user function is invoked with the Key and Value components <strong>of</strong> theelement passed as the first two parameters. The second parameter <strong>of</strong> the forAll function is passed asthe third parameter to the user function. This value can be used to pass any appropriate data from themain code to the user function.Results:See Also:The elements in the dictionary are all visited, with the user function being invoked for each one.find, findKeyAndValue438 Skip List Containers
WCPtrSkipListDict::insert()Synopsis:Semantics:Results:See Also:#include public:int insert( Key *, Value * );The insert public member function inserts a key and value into the dictionary. If allocation <strong>of</strong> thenode to store the key-value pair fails, then the out_<strong>of</strong>_memory exception is thrown if it is enabled.If the exception is not enabled, the insert will not be completed.The insert public member function inserts a key and value into the dictionary. If the insert issuccessful, a non-zero will returned. A zero will be returned if the insert fails.operator =, WCExcept::out_<strong>of</strong>_memorySkip List Containers 439
WCPtrSkipListDict::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if the dictionary is empty.The isEmpty public member function returns zero if it contains at least one entry, non-zero if thedictionary is empty.entries440 Skip List Containers
WCPtrSkipListDict::operator []()Synopsis:Semantics:Results:See Also:#include public:Value * & operator[]( const Key * );operator [] is the dictionary index operator. A reference to the object stored in the dictionary withthe given Key is returned. If no equivalent element is found, then a new key-value pair is created withthe specified Key value, and initialized with the default constructor. The returned reference can then beassigned to, so that insertions can be made with the operator. If an allocation error occurs whileinserting a new key-value pair, then the out_<strong>of</strong>_memory exception is thrown if it is enabled. If theexception is not enabled, then a reference to address zero will be returned. This will result in a run-timeerror on systems which trap address zero references.The operator [] public member function returns a reference to the element at the given key value.If the key does not exist, a reference to a created element is returned. The result <strong>of</strong> the operator may beassigned to.WCExcept::out_<strong>of</strong>_memorySkip List Containers 441
WCPtrSkipListDict::operator []()Synopsis:Semantics:Results:See Also:#include public:Value * const & operator[]( const Key * ) const;operator [] is the dictionary index operator. A constant reference to the object stored in thedictionary with the given Key is returned. If no equivalent element is found, then the index_rangeexception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero willbe returned. This will result in a run-time error on systems which trap address zero references.The operator [] public member function returns a constant reference to the element at the givenkey value. The result <strong>of</strong> the operator may not be assigned to.WCExcept::index_range442 Skip List Containers
WCPtrSkipListDict::operator =()Synopsis:Semantics:Results:See Also:#include public:WCPtrSkipListDict & operator =( const WCPtrSkipListDict & );The operator = public member function is the assignment operator for theWCPtrSkipListDict class. The left hand side dictionary is first cleared using theclear member function, and then the right hand side dictionary is copied. The new skip list is createdwith the same probability and maximum pointers, all values or pointers stored in the list, and theexception trap states. If there is not enough memory to copy all <strong>of</strong> the values or pointers in thedictionary, then only some will be copied, and the out_<strong>of</strong>_memory exception is thrown if it isenabled. The number <strong>of</strong> entries will correctly reflect the number copied.The operator = public member function assigns the left hand side dictionary to be a copy <strong>of</strong> theright hand side.clear, WCExcept::out_<strong>of</strong>_memorySkip List Containers 443
WCPtrSkipListDict::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCPtrSkipListDict & ) const;The operator == public member function is the equivalence operator for theWCPtrSkipListDict class. Two dictionary objects are equivalent if they are thesame object and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side dictionary are the sameobject. A FALSE (zero) value is returned otherwise.444 Skip List Containers
WCPtrSkipListDict::remove()Synopsis:Semantics:Results:#include public:Value * remove( const Key * );The remove public member function is used to remove the specified element from the dictionary. Ifan equivalent element is found, the pointer value is returned. Zero is returned if the element is notfound. Note that equivalence is based on the equivalence operator <strong>of</strong> the Key type.The element is removed from the dictionary if it found.Skip List Containers 445
WCPtrSkipList, WCPtrSkipListSetDeclared:wcskip.hWCPtrSkipList and WCPtrSkipListSet classes are templated classes used tostore objects in a skip list. A skip list is a probabilistic alternative to balanced trees, and provides areasonable performance balance to insertion, search, and deletion. A skip list allows more than onecopy <strong>of</strong> an element that is equivalent, while the skip list set allows only one copy. The equality operator<strong>of</strong> the element’s type is used to locate the value.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type <strong>of</strong> the data pointed to by the pointers stored in the list.Note that pointers to the elements are stored in the list. Destructors are not called on the elementspointed to. The data values pointed to in the list should not be changed such that the equivalence to theold value is modified.The iterator classes for skip lists have the same function and operator interface as the hash iteratorsclasses. See the chapter on hash iterators for more information.The WCExcept class is a base class <strong>of</strong> the WCPtrSkipList andWCPtrSkipListSet classes and provides the exceptions member function. Thismember function controls the exceptions which can be thrown by the WCPtrSkipList andWCPtrSkipListSet objects. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> TypeThe WCPtrSkipList and WCPtrSkipListSet classes requires Type to have:A well defined equivalence operator( int operator ==( const Type & ) const ).A well defined less than operator( int operator
WCPtrSkipList, WCPtrSkipListSetunsigned entries() const;Type * find( const Type * ) const;void forAll( void (*user_fn)( Type *, void * ) , void * );int insert( Type * );int isEmpty() const;Type * remove( const Type * );The following public member functions are available for the WCPtrSkipList class only:unsigned occurrencesOf( const Type * ) const;unsigned removeAll( const Type * );Public Member OperatorsThe following member operators are declared in the public interface:WCPtrSkipList & operator =( const WCPtrSkipList & );int operator ==( const WCPtrSkipList & ) const;WCPtrSkipListSet & operator =( const WCPtrSkipListSet & );int operator ==( const WCPtrSkipListSet & ) const;Skip List Containers 447
WCPtrSkipListSet::WCPtrSkipListSet()Synopsis:Semantics:Results:See Also:#include public:WCPtrSkipListSet( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS );The WCPtrSkipListSet constructor creates a WCPtrSkipListSet object with noentries. The first optional parameter, which defaults to the constant WCSKIPLIST_PROB_QUARTER,determines the probability <strong>of</strong> having a certain number <strong>of</strong> pointers in each skip list node. The secondoptional parameter, which defaults to the constant WCDEFAULT_SKIPLIST_MAX_PTRS, determinesthe maximum number <strong>of</strong> pointers that are allowed in any skip list node.WCDEFAULT_SKIPLIST_MAX_PTRS is the maximum effective value <strong>of</strong> the second parameter. If anallocation failure occurs while creating the skip list, the out_<strong>of</strong>_memory exception is thrown if theout_<strong>of</strong>_memory exception is enabled.The WCPtrSkipListSet constructor creates an initialized WCPtrSkipListSet object.~WCPtrSkipList, WCExcept::out_<strong>of</strong>_memory448 Skip List Containers
WCPtrSkipListSet::WCPtrSkipListSet()Synopsis:Semantics:#include public:WCPtrSkipListSet( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thelist. The semantics <strong>of</strong> this constructor are the same as the constructor without the memory managementfunctions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a skip list. To determine the size <strong>of</strong> the objects that the memory managementfunctions will be required to allocate and free, the following macro may be used:WCPtrSkipListSetItemSize( Type, num_<strong>of</strong>_pointers )Results:See Also:The WCPtrSkipListSet constructor creates an initialized WCPtrSkipListSet object.~WCPtrSkipList, WCExcept::out_<strong>of</strong>_memorySkip List Containers 449
WCPtrSkipListSet::WCPtrSkipListSet()Synopsis:Semantics:Results:See Also:#include public:WCPtrSkipListSet( const WCPtrSkipListSet & );The WCPtrSkipListSet constructor is the copy constructor for theWCPtrSkipListSet class. The new skip list is created with the same probability and maximumpointers, all values or pointers stored in the list, and the exception trap states. If there is not enoughmemory to copy all <strong>of</strong> the values, then only some will be copied, and the number <strong>of</strong> entries willcorrectly reflect the number copied. If all <strong>of</strong> the elements cannot be copied, then theout_<strong>of</strong>_memory exception is thrown if it is enabled.The WCPtrSkipListSet constructor creates a WCPtrSkipListSet object which is acopy <strong>of</strong> the passed list.operator =, WCExcept::out_<strong>of</strong>_memory450 Skip List Containers
WCPtrSkipListSet::~WCPtrSkipListSet()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCPtrSkipListSet();The WCPtrSkipListSet destructor is the destructor for the WCPtrSkipListSet class.If the number <strong>of</strong> elements is not zero and the not_empty exception is enabled, the exception isthrown. Otherwise, the list elements are cleared using the clear member function. The objects whichthe list elements point to are not deleted unless the clearAndDestroy member function is explicitlycalled before the destructor is called. The call to the WCPtrSkipListSet destructor isinserted implicitly by the compiler at the point where the WCPtrSkipListSet object goes out <strong>of</strong>scope.The call to the WCPtrSkipListSet destructor destroys a WCPtrSkipListSet object.clear, clearAndDestroy, WCExcept::not_emptySkip List Containers 451
WCPtrSkipList::WCPtrSkipList()Synopsis:Semantics:Results:See Also:#include public:WCPtrSkipList( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS );The WCPtrSkipList constructor creates a WCPtrSkipList object with no entries. Thefirst optional parameter, which defaults to the constant WCSKIPLIST_PROB_QUARTER, determinesthe probability <strong>of</strong> having a certain number <strong>of</strong> pointers in each skip list node. The second optionalparameter, which defaults to the constant WCDEFAULT_SKIPLIST_MAX_PTRS, determines themaximum number <strong>of</strong> pointers that are allowed in any skip list node.WCDEFAULT_SKIPLIST_MAX_PTRS is the maximum effective value <strong>of</strong> the second parameter. If anallocation failure occurs while creating the skip list, the out_<strong>of</strong>_memory exception is thrown if theout_<strong>of</strong>_memory exception is enabled.The WCPtrSkipList constructor creates an initialized WCPtrSkipList object.~WCPtrSkipList, WCExcept::out_<strong>of</strong>_memory452 Skip List Containers
WCPtrSkipList::WCPtrSkipList()Synopsis:Semantics:#include public:WCPtrSkipList( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thelist. The semantics <strong>of</strong> this constructor are the same as the constructor without the memory managementfunctions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a skip list. To determine the size <strong>of</strong> the objects that the memory managementfunctions will be required to allocate and free, the following macro may be used:WCPtrSkipListItemSize( Type, num_<strong>of</strong>_pointers )Results:See Also:The WCPtrSkipList constructor creates an initialized WCPtrSkipList object.~WCPtrSkipList, WCExcept::out_<strong>of</strong>_memorySkip List Containers 453
WCPtrSkipList::WCPtrSkipList()Synopsis:Semantics:Results:See Also:#include public:WCPtrSkipList( const WCPtrSkipList & );The WCPtrSkipList constructor is the copy constructor for the WCPtrSkipList class.The new skip list is created with the same probability and maximum pointers, all values or pointersstored in the list, and the exception trap states. If there is not enough memory to copy all <strong>of</strong> the values,then only some will be copied, and the number <strong>of</strong> entries will correctly reflect the number copied. If all<strong>of</strong> the elements cannot be copied, then the out_<strong>of</strong>_memory exception is thrown if it is enabled.The WCPtrSkipList constructor creates a WCPtrSkipList object which is a copy <strong>of</strong> thepassed list.operator =, WCExcept::out_<strong>of</strong>_memory454 Skip List Containers
WCPtrSkipList::~WCPtrSkipList()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCPtrSkipList();The WCPtrSkipList destructor is the destructor for the WCPtrSkipList class. If thenumber <strong>of</strong> elements is not zero and the not_empty exception is enabled, the exception is thrown.Otherwise, the list elements are cleared using the clear member function. The objects which the listelements point to are not deleted unless the clearAndDestroy member function is explicitly calledbefore the destructor is called. The call to the WCPtrSkipList destructor is insertedimplicitly by the compiler at the point where the WCPtrSkipList object goes out <strong>of</strong> scope.The call to the WCPtrSkipList destructor destroys a WCPtrSkipList object.clear, clearAndDestroy, WCExcept::not_emptySkip List Containers 455
WCPtrSkipList::clear(), WCPtrSkipListSet::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the list so that it has no entries. Objects pointed toby the list elements are not deleted. The list object is not destroyed and re-created by this function, sothe object destructor is not invoked.The clear public member function clears the list to have no elements.See Also: ~WCPtrSkipList, clearAndDestroy, operator =456 Skip List Containers
WCPtrSkipList,WCPtrSkipListSet::clearAndDestroy()Synopsis:Semantics:Results:See Also:#include public:void clearAndDestroy();The clearAndDestroy public member function is used to clear the list and delete the objectspointed to by the list elements. The list object is not destroyed and re-created by this function, so thelist object destructor is not invoked.The clearAndDestroy public member function clears the list by deleting the objects pointed to bythe list elements, and then removing the list elements from the list.clearSkip List Containers 457
WCPtrSkipList::contains(), WCPtrSkipListSet::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Type * ) const;The contains public member function returns non-zero if the element is stored in the list, or zero ifthere is no equivalent element. Note that equivalence is based on the equivalence operator <strong>of</strong> theelement type.The contains public member function returns a non-zero value if the element is found in the list.find458 Skip List Containers
WCPtrSkipList::entries(), WCPtrSkipListSet::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to return the current number <strong>of</strong> elements stored in thelist.The entries public member function returns the number <strong>of</strong> elements in the list.isEmptySkip List Containers 459
WCPtrSkipList::find(), WCPtrSkipListSet::find()Synopsis:Semantics:Results:#include public:Type * find( const Type * ) const;The find public member function is used to find an element with an equivalent value in the list. If anequivalent element is found, a pointer to the element is returned. Zero is returned if the element is notfound. Note that equivalence is based on the equivalence operator <strong>of</strong> the element type.The element equivalent to the passed value is located in the list.460 Skip List Containers
WCPtrSkipList::forAll(), WCPtrSkipListSet::forAll()Synopsis:Semantics:#include public:void forAll(void (*user_fn)( Type *, void * ),void * );The forAll public member function causes the user supplied function to be invoked for every value inthe list. The user function has the prototypevoid user_func( Type * value, void * data );As the elements are visited, the user function is invoked with the element passed as the first. Thesecond parameter <strong>of</strong> the forAll function is passed as the second parameter to the user function. Thisvalue can be used to pass any appropriate data from the main code to the user function.Results:See Also:The elements in the list are all visited, with the user function being invoked for each one.findSkip List Containers 461
WCPtrSkipList::insert(), WCPtrSkipListSet::insert()Synopsis:Semantics:#include public:int insert( Type * );The insert public member function inserts a value into the list. If allocation <strong>of</strong> the node to store thevalue fails, then the out_<strong>of</strong>_memory exception is thrown if it is enabled. If the exception is notenabled, the insert will not be completed.With a WCPtrSkipListSet, there must be only one equivalent element in the set. If an elementequivalent to the inserted element is already in the list set, the list set will remain unchanged, and thenot_unique exception is thrown if it is enabled. If the exception is not enabled, the insert will not becompleted.Results:See Also:The insert public member function inserts a value into the list. If the insert is successful, a non-zerowill returned. A zero will be returned if the insert fails.operator =, WCExcept::out_<strong>of</strong>_memory, WCExcept::not_unique462 Skip List Containers
WCPtrSkipList::isEmpty(), WCPtrSkipListSet::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if the list is empty.The isEmpty public member function returns zero if it contains at least one entry, non-zero if the listis empty.entriesSkip List Containers 463
WCPtrSkipList::occurrencesOf()Synopsis:Semantics:Results:See Also:#include public:unsigned occurrencesOf( const Type * ) const;The occurrencesOf public member function is used to return the current number <strong>of</strong> elements storedin the list which are equivalent to the passed value. Note that equivalence is based on the equivalenceoperator <strong>of</strong> the element type.The occurrencesOf public member function returns the number <strong>of</strong> elements in the list which areequivalent to the passed value.entries, find, isEmpty464 Skip List Containers
WCPtrSkipList::operator =(), WCPtrSkipListSet::operator =()Synopsis:Semantics:Results:See Also:#include public:WCPtrSkipList & operator =( const WCPtrSkipList & );WCPtrSkipListSet & operator =( const WCPtrSkipListSet & );The operator = public member function is the assignment operator for theWCPtrSkipList and WCPtrSkipListSet classes. The left hand side list is firstcleared using the clear member function, and then the right hand side list is copied. The list function,exception trap states, and all <strong>of</strong> the list elements are copied. If there is not enough memory to copy all<strong>of</strong> the values or pointers in the list, then only some will be copied, and the out_<strong>of</strong>_memory exceptionis thrown if it is enabled. The number <strong>of</strong> entries will correctly reflect the number copied.The operator = public member function assigns the left hand side list to be a copy <strong>of</strong> the right handside.clear, WCExcept::out_<strong>of</strong>_memorySkip List Containers 465
WCPtrSkipList::operator ==(), WCPtrSkipListSet::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCPtrSkipList & ) const;int operator ==( const WCPtrSkipListSet & ) const;The operator == public member function is the equivalence operator for theWCPtrSkipList and WCPtrSkipListSet classes. Two list objects areequivalent if they are the same object and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side list are the same object. AFALSE (zero) value is returned otherwise.466 Skip List Containers
WCPtrSkipList::remove(), WCPtrSkipListSet::remove()Synopsis:Semantics:Results:#include public:Type * remove( const Type * );The remove public member function is used to remove the specified element from the list. If anequivalent element is found, the pointer value is returned. Zero is returned if the element is not found.If the list is a WCPtrSkipList and there is more than one element equivalent to the specifiedelement, then the last equivalent element added to the WCPtrSkipList is removed. Note thatequivalence is based on the equivalence operator <strong>of</strong> the element type.The element is removed from the list.Skip List Containers 467
WCPtrSkipList::removeAll()Synopsis:Semantics:Results:#include public:unsigned removeAll( const Type * );The removeAll public member function is used to remove all elements equivalent to the specifiedelement from the list. Zero is returned if no equivalent elements are found. Note that equivalence isbased on the equivalence operator <strong>of</strong> the element type.All equivalent elements are removed from the list.468 Skip List Containers
WCValSkipListDictDeclared:wcskip.hThe WCValSkipListDict class is a templated class used to store objects in adictionary. Dictionaries store values with an associated key, which may be <strong>of</strong> any type. One example<strong>of</strong> a dictionary used in everyday life is the phone book. The phone numbers are the data values, and thecustomer name is the key. The equality operator <strong>of</strong> the key’s type is used to locate the key-value pairs.In the description <strong>of</strong> each member function, the text Key is used to indicate the template parameterdefining the type <strong>of</strong> the indices used to store data in the dictionary. The text Value is used to indicatethe template parameter defining the type <strong>of</strong> the data stored in the dictionary.Values are copied into the dictionary, which could be undesirable if the stored objects are complicatedand copying is expensive. Value dictionaries should not be used to store objects <strong>of</strong> a base class if anyderived types <strong>of</strong> different sizes would be stored in the dictionary, or if the destructor for a derived classmust be called.The iterator classes for skip lists have the same function and operator interface as the hash iteratorsclasses. See the chapter on hash iterators for more information.The WCExcept class is a base class <strong>of</strong> the WCValSkipListDict class and providesthe exceptions member function. This member function controls the exceptions which can bethrown by the WCValSkipListDict object. No exceptions are enabled unless theyare set by the exceptions member function.Requirements <strong>of</strong> Key and ValueThe WCValSkipListDict class requires Key to have:A default constructor ( Key::Key() ).A well defined copy constructor ( Key::Key( const Key & ) ).A well defined assignment operator ( Key & operator =( const Key & ) ).A well defined equivalence operator with constant parameters( int operator ==( const Key & ) const ).A well defined operator less than with constant parameters( int operator
WCValSkipListDictWCValSkipListDict( unsigned = WCSkipListDict_PROB_QUARTER, unsigned =WCDEFAULT_SKIPLIST_MAX_PTRS, void * (*user_alloc)( size_t size ),void (*user_dealloc)( void *old, size_t size ) );WCValSkipListDict( const WCValSkipListDict & );virtual ~WCValSkipListDict();void clear();int contains( const Key & ) const;unsigned entries() const;int find( const Key &, Value & ) const;int findKeyAndValue( const Key &, Key &, Value & ) const;void forAll( void (*user_fn)( Key, Value, void * ), void * );int insert( const Key &, const Value & );int isEmpty() const;int remove( const Key & );Public Member OperatorsThe following member operators are declared in the public interface:Value & operator []( const Key & );const Value & operator []( const Key & ) const;WCValSkipListDict & operator =( const WCValSkipListDict & );int operator ==( const WCValSkipListDict & ) const;470 Skip List Containers
WCValSkipListDict::WCValSkipListDict()Synopsis:Semantics:Results:See Also:#include public:WCValSkipListDict( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS );The public WCValSkipListDict constructor creates anWCValSkipListDict object with no entries. The first optional parameter, whichdefaults to the constant WCSKIPLIST_PROB_QUARTER, determines the probability <strong>of</strong> having acertain number <strong>of</strong> pointers in each skip list node. The second optional parameter, which defaults to theconstant WCDEFAULT_SKIPLIST_MAX_PTRS, determines the maximum number <strong>of</strong> pointers thatare allowed in any skip list node. WCDEFAULT_SKIPLIST_MAX_PTRS is the maximum effectivevalue <strong>of</strong> the second parameter. If an allocation failure occurs while creating the skip list, theout_<strong>of</strong>_memory exception is thrown if the out_<strong>of</strong>_memory exception is enabled.The public WCValSkipListDict constructor creates an initializedWCValSkipListDict object.~WCValSkipListDict, WCExcept::out_<strong>of</strong>_memorySkip List Containers 471
WCValSkipListDict::WCValSkipListDict()Synopsis:Semantics:#include public:WCValSkipListDict( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thelist dictionary. The semantics <strong>of</strong> this constructor are the same as the constructor without the memorymanagement functions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a list dictionary. To determine the size <strong>of</strong> the objects that the memorymanagement functions will be required to allocate and free, the following macro may be used:WCValSkipListDictItemSize( Key, Value, num_<strong>of</strong>_pointers )Results:See Also:The public WCValSkipListDict constructor creates an initializedWCValSkipListDict object.~WCValSkipListDict, WCExcept::out_<strong>of</strong>_memory472 Skip List Containers
WCValSkipListDict::WCValSkipListDict()Synopsis:Semantics:Results:See Also:#include public:WCValSkipListDict( const WCValSkipListDict & );The public WCValSkipListDict constructor is the copy constructor for theWCValSkipListDict class. The new skip list is created with the same probabilityand maximum pointers, all values or pointers stored in the list, and the exception trap states. If there isnot enough memory to copy all <strong>of</strong> the values, then only some will be copied, and the number <strong>of</strong> entrieswill correctly reflect the number copied. If all <strong>of</strong> the elements cannot be copied, then theout_<strong>of</strong>_memory exception is thrown if it is enabled.The public WCValSkipListDict constructor creates anWCValSkipListDict object which is a copy <strong>of</strong> the passed dictionary.operator =, WCExcept::out_<strong>of</strong>_memorySkip List Containers 473
WCValSkipListDict::~WCValSkipListDict()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCValSkipListDict();The public ~WCValSkipListDict destructor is the destructor for theWCValSkipListDict class. If the number <strong>of</strong> dictionary elements is not zero andthe not_empty exception is enabled, the exception is thrown. Otherwise, the dictionary elements arecleared using the clear member function. The call to the public~WCValSkipListDict destructor is inserted implicitly by the compiler at the pointwhere the WCValSkipListDict object goes out <strong>of</strong> scope.The public ~WCValSkipListDict destructor destroys anWCValSkipListDict object.clear, WCExcept::not_empty474 Skip List Containers
WCValSkipListDict::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the dictionary so that it has no entries. Elementsstored in the dictionary are destroyed using the destructors <strong>of</strong> Key and <strong>of</strong> Value. The dictionaryobject is not destroyed and re-created by this function, so the object destructor is not invoked.The clear public member function clears the dictionary to have no elements.See Also: ~WCValSkipListDict, operator =Skip List Containers 475
WCValSkipListDict::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Key & ) const;The contains public member function returns non-zero if an element with the specified key is storedin the dictionary, or zero if there is no equivalent element. Note that equivalence is based on theequivalence operator <strong>of</strong> the Key type.The contains public member function returns a non-zero value if the Key is found in the dictionary.find, findKeyAndValue476 Skip List Containers
WCValSkipListDict::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to return the current number <strong>of</strong> elements stored in thedictionary.The entries public member function returns the number <strong>of</strong> elements in the dictionary.isEmptySkip List Containers 477
WCValSkipListDict::find()Synopsis:Semantics:Results:See Also:#include public:int find( const Key &, Value & ) const;The find public member function is used to find an element with an equivalent key in the dictionary.If an equivalent element is found, a non-zero value is returned. The reference to a Value passed as thesecond argument is assigned the found element’s Value. Zero is returned if the element is not found.Note that equivalence is based on the equivalence operator <strong>of</strong> the Key type.The element equivalent to the passed key is located in the dictionary.findKeyAndValue478 Skip List Containers
WCValSkipListDict::findKeyAndValue()Synopsis:Semantics:Results:See Also:#include public:int findKeyAndValue( const Key &,Key &, Value & ) const;The findKeyAndValue public member function is used to find an element in the dictionary with ankey equivalent to the first parameter. If an equivalent element is found, a non-zero value is returned.The reference to a Key passed as the second parameter is assigned the found element’s key. Thereference to a Value passed as the third argument is assigned the found element’s Value. Zero isreturned if the element is not found. Note that equivalence is based on the equivalence operator <strong>of</strong> theKey type.The element equivalent to the passed key is located in the dictionary.findKeyAndValueSkip List Containers 479
WCValSkipListDict::forAll()Synopsis:Semantics:#include public:void forAll(void (*user_fn)( Key, Value, void * ),void * );The forAll public member function causes the user supplied function to be invoked for everykey-value pair in the dictionary. The user function has the prototypevoid user_func( Key key, Value value, void * data );As the elements are visited, the user function is invoked with the Key and Value components <strong>of</strong> theelement passed as the first two parameters. The second parameter <strong>of</strong> the forAll function is passed asthe third parameter to the user function. This value can be used to pass any appropriate data from themain code to the user function.Results:See Also:The elements in the dictionary are all visited, with the user function being invoked for each one.find, findKeyAndValue480 Skip List Containers
WCValSkipListDict::insert()Synopsis:Semantics:Results:See Also:#include public:int insert( const Key &, const Value & );The insert public member function inserts a key and value into the dictionary. If allocation <strong>of</strong> thenode to store the key-value pair fails, then the out_<strong>of</strong>_memory exception is thrown if it is enabled.If the exception is not enabled, the insert will not be completed.The insert public member function inserts a key and value into the dictionary. If the insert issuccessful, a non-zero will returned. A zero will be returned if the insert fails.operator =, WCExcept::out_<strong>of</strong>_memorySkip List Containers 481
WCValSkipListDict::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if the dictionary is empty.The isEmpty public member function returns zero if it contains at least one entry, non-zero if thedictionary is empty.entries482 Skip List Containers
WCValSkipListDict::operator []()Synopsis:Semantics:Results:See Also:#include public:Value & operator[]( const Key & );operator [] is the dictionary index operator. A reference to the object stored in the dictionary withthe given Key is returned. If no equivalent element is found, then a new key-value pair is created withthe specified Key value, and initialized with the default constructor. The returned reference can then beassigned to, so that insertions can be made with the operator. If an allocation error occurs whileinserting a new key-value pair, then the out_<strong>of</strong>_memory exception is thrown if it is enabled. If theexception is not enabled, then a reference to address zero will be returned. This will result in a run-timeerror on systems which trap address zero references.The operator [] public member function returns a reference to the element at the given key value.If the key does not exist, a reference to a created element is returned. The result <strong>of</strong> the operator may beassigned to.WCExcept::out_<strong>of</strong>_memorySkip List Containers 483
WCValSkipListDict::operator []()Synopsis:Semantics:Results:See Also:#include public:const Value & operator[]( const Key & ) const;operator [] is the dictionary index operator. A constant reference to the object stored in thedictionary with the given Key is returned. If no equivalent element is found, then the index_rangeexception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero willbe returned. This will result in a run-time error on systems which trap address zero references.The operator [] public member function returns a constant reference to the element at the givenkey value. The result <strong>of</strong> the operator may not be assigned to.WCExcept::index_range484 Skip List Containers
WCValSkipListDict::operator =()Synopsis:Semantics:Results:See Also:#include public:WCValSkipListDict & operator =( const WCValSkipListDict & );The operator = public member function is the assignment operator for theWCValSkipListDict class. The left hand side dictionary is first cleared using theclear member function, and then the right hand side dictionary is copied. The new skip list is createdwith the same probability and maximum pointers, all values or pointers stored in the list, and theexception trap states. If there is not enough memory to copy all <strong>of</strong> the values or pointers in thedictionary, then only some will be copied, and the out_<strong>of</strong>_memory exception is thrown if it isenabled. The number <strong>of</strong> entries will correctly reflect the number copied.The operator = public member function assigns the left hand side dictionary to be a copy <strong>of</strong> theright hand side.clear, WCExcept::out_<strong>of</strong>_memorySkip List Containers 485
WCValSkipListDict::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCValSkipListDict & ) const;The operator == public member function is the equivalence operator for theWCValSkipListDict class. Two dictionary objects are equivalent if they are thesame object and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side dictionary are the sameobject. A FALSE (zero) value is returned otherwise.486 Skip List Containers
WCValSkipListDict::remove()Synopsis:Semantics:Results:#include public:int remove( const Key & );The remove public member function is used to remove the specified element from the dictionary. Ifan equivalent element is found, a non-zero value is returned. Zero is returned if the element is notfound. Note that equivalence is based on the equivalence operator <strong>of</strong> the Key type.The element is removed from the dictionary if it found.Skip List Containers 487
WCValSkipList, WCValSkipListSetDeclared:wcskip.hWCValSkipList and WCValSkipListSet classes are templated classes used tostore objects in a skip list. A skip list is a probabilistic alternative to balanced trees, and provides areasonable performance balance to insertion, search, and deletion. A skip list allows more than onecopy <strong>of</strong> an element that is equivalent, while the skip list set allows only one copy. The equality operator<strong>of</strong> the element’s type is used to locate the value.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type <strong>of</strong> the data to be stored in the list.Values are copied into the list, which could be undesirable if the stored objects are complicated andcopying is expensive. Value skip lists should not be used to store objects <strong>of</strong> a base class if any derivedtypes <strong>of</strong> different sizes would be stored in the list, or if the destructor for a derived class must be called.The iterator classes for skip lists have the same function and operator interface as the hash iteratorsclasses. See the chapter on hash iterators for more information.The WCExcept class is a base class <strong>of</strong> the WCValSkipList andWCValSkipListSet classes and provides the exceptions member function. Thismember function controls the exceptions which can be thrown by the WCValSkipList andWCValSkipListSet objects. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> TypeThe WCValSkipList and WCValSkipListSet classes requires Type to have:A default constructor ( Type::Type() ).A well defined copy constructor ( Type::Type( const Type & ) ).A well defined equivalence operator( int operator ==( const Type & ) const ).A well defined less than operator( int operator
WCValSkipList, WCValSkipListSetvirtual ~WCValSkipListSet();void clear();int contains( const Type & ) const;unsigned entries() const;int find( const Type &, Type & ) const;void forAll( void (*user_fn)( Type, void * ), void * );int insert( const Type & );int isEmpty() const;int remove( const Type & );The following public member functions are available for the WCValSkipList class only:unsigned occurrencesOf( const Type & ) const;unsigned removeAll( const Type & );Public Member OperatorsThe following member operators are declared in the public interface:WCValSkipList & operator =( const WCValSkipList & );int operator ==( const WCValSkipList & ) const;WCValSkipListSet & operator =( const WCValSkipListSet & );int operator ==( const WCValSkipListSet & ) const;Skip List Containers 489
WCValSkipListSet::WCValSkipListSet()Synopsis:Semantics:Results:See Also:#include public:WCValSkipListSet( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS );The WCValSkipListSet constructor creates a WCValSkipListSet object with noentries. The first optional parameter, which defaults to the constant WCSKIPLIST_PROB_QUARTER,determines the probability <strong>of</strong> having a certain number <strong>of</strong> pointers in each skip list node. The secondoptional parameter, which defaults to the constant WCDEFAULT_SKIPLIST_MAX_PTRS, determinesthe maximum number <strong>of</strong> pointers that are allowed in any skip list node.WCDEFAULT_SKIPLIST_MAX_PTRS is the maximum effective value <strong>of</strong> the second parameter. If anallocation failure occurs while creating the skip list, the out_<strong>of</strong>_memory exception is thrown if theout_<strong>of</strong>_memory exception is enabled.The WCValSkipListSet constructor creates an initialized WCValSkipListSet object.~WCValSkipList, WCExcept::out_<strong>of</strong>_memory490 Skip List Containers
WCValSkipListSet::WCValSkipListSet()Synopsis:Semantics:#include public:WCValSkipListSet( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thelist. The semantics <strong>of</strong> this constructor are the same as the constructor without the memory managementfunctions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a skip list. To determine the size <strong>of</strong> the objects that the memory managementfunctions will be required to allocate and free, the following macro may be used:WCValSkipListSetItemSize( Type, num_<strong>of</strong>_pointers )Results:See Also:The WCValSkipListSet constructor creates an initialized WCValSkipListSet object.~WCValSkipList, WCExcept::out_<strong>of</strong>_memorySkip List Containers 491
WCValSkipListSet::WCValSkipListSet()Synopsis:Semantics:Results:See Also:#include public:WCValSkipListSet( const WCValSkipListSet & );The WCValSkipListSet constructor is the copy constructor for theWCValSkipListSet class. The new skip list is created with the same probability and maximumpointers, all values or pointers stored in the list, and the exception trap states. If there is not enoughmemory to copy all <strong>of</strong> the values, then only some will be copied, and the number <strong>of</strong> entries willcorrectly reflect the number copied. If all <strong>of</strong> the elements cannot be copied, then theout_<strong>of</strong>_memory exception is thrown if it is enabled.The WCValSkipListSet constructor creates a WCValSkipListSet object which is acopy <strong>of</strong> the passed list.operator =, WCExcept::out_<strong>of</strong>_memory492 Skip List Containers
WCValSkipListSet::~WCValSkipListSet()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCValSkipListSet();The WCValSkipListSet destructor is the destructor for the WCValSkipListSet class.If the number <strong>of</strong> elements is not zero and the not_empty exception is enabled, the exception isthrown. Otherwise, the list elements are cleared using the clear member function. The call to theWCValSkipListSet destructor is inserted implicitly by the compiler at the point where theWCValSkipListSet object goes out <strong>of</strong> scope.The call to the WCValSkipListSet destructor destroys a WCValSkipListSet object.clear, WCExcept::not_emptySkip List Containers 493
WCValSkipList::WCValSkipList()Synopsis:Semantics:Results:See Also:#include public:WCValSkipList( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS );The WCValSkipList constructor creates a WCValSkipList object with no entries. Thefirst optional parameter, which defaults to the constant WCSKIPLIST_PROB_QUARTER, determinesthe probability <strong>of</strong> having a certain number <strong>of</strong> pointers in each skip list node. The second optionalparameter, which defaults to the constant WCDEFAULT_SKIPLIST_MAX_PTRS, determines themaximum number <strong>of</strong> pointers that are allowed in any skip list node.WCDEFAULT_SKIPLIST_MAX_PTRS is the maximum effective value <strong>of</strong> the second parameter. If anallocation failure occurs while creating the skip list, the out_<strong>of</strong>_memory exception is thrown if theout_<strong>of</strong>_memory exception is enabled.The WCValSkipList constructor creates an initialized WCValSkipList object.~WCValSkipList, WCExcept::out_<strong>of</strong>_memory494 Skip List Containers
WCValSkipList::WCValSkipList()Synopsis:Semantics:#include public:WCValSkipList( unsigned = WCSKIPLIST_PROB_QUARTER,unsigned = WCDEFAULT_SKIPLIST_MAX_PTRS,void * (*user_alloc)( size_t ),void (*user_dealloc)( void *, size_t ) );Allocator and deallocator functions are specified for use when entries are inserted and removed from thelist. The semantics <strong>of</strong> this constructor are the same as the constructor without the memory managementfunctions.The allocation function must return a zero if it cannot perform the allocation. The deallocation functionis passed the size as well as the pointer to the data. Your allocation system may take advantage <strong>of</strong> thecharacteristic that the allocation function will always be called with the same size value for anyparticular instantiation <strong>of</strong> a skip list. To determine the size <strong>of</strong> the objects that the memory managementfunctions will be required to allocate and free, the following macro may be used:WCValSkipListItemSize( Type, num_<strong>of</strong>_pointers )Results:See Also:The WCValSkipList constructor creates an initialized WCValSkipList object.~WCValSkipList, WCExcept::out_<strong>of</strong>_memorySkip List Containers 495
WCValSkipList::WCValSkipList()Synopsis:Semantics:Results:See Also:#include public:WCValSkipList( const WCValSkipList & );The WCValSkipList constructor is the copy constructor for the WCValSkipList class.The new skip list is created with the same probability and maximum pointers, all values or pointersstored in the list, and the exception trap states. If there is not enough memory to copy all <strong>of</strong> the values,then only some will be copied, and the number <strong>of</strong> entries will correctly reflect the number copied. If all<strong>of</strong> the elements cannot be copied, then the out_<strong>of</strong>_memory exception is thrown if it is enabled.The WCValSkipList constructor creates a WCValSkipList object which is a copy <strong>of</strong> thepassed list.operator =, WCExcept::out_<strong>of</strong>_memory496 Skip List Containers
WCValSkipList::~WCValSkipList()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCValSkipList();The WCValSkipList destructor is the destructor for the WCValSkipList class. If thenumber <strong>of</strong> elements is not zero and the not_empty exception is enabled, the exception is thrown.Otherwise, the list elements are cleared using the clear member function. The call to theWCValSkipList destructor is inserted implicitly by the compiler at the point where theWCValSkipList object goes out <strong>of</strong> scope.The call to the WCValSkipList destructor destroys a WCValSkipList object.clear, WCExcept::not_emptySkip List Containers 497
WCValSkipList::clear(), WCValSkipListSet::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the list so that it has no entries. Elements stored inthe list are destroyed using the destructors <strong>of</strong> Type. The list object is not destroyed and re-created bythis function, so the object destructor is not invoked.The clear public member function clears the list to have no elements.See Also: ~WCValSkipList, operator =498 Skip List Containers
WCValSkipList::contains(), WCValSkipListSet::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Type & ) const;The contains public member function returns non-zero if the element is stored in the list, or zero ifthere is no equivalent element. Note that equivalence is based on the equivalence operator <strong>of</strong> theelement type.The contains public member function returns a non-zero value if the element is found in the list.findSkip List Containers 499
WCValSkipList::entries(), WCValSkipListSet::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to return the current number <strong>of</strong> elements stored in thelist.The entries public member function returns the number <strong>of</strong> elements in the list.isEmpty500 Skip List Containers
WCValSkipList::find(), WCValSkipListSet::find()Synopsis:Semantics:Results:#include public:int find( const Type &, Type & ) const;The find public member function is used to find an element with an equivalent value in the list. If anequivalent element is found, a non-zero value is returned. The reference to the element passed as thesecond argument is assigned the found element’s value. Zero is returned if the element is not found.Note that equivalence is based on the equivalence operator <strong>of</strong> the element type.The element equivalent to the passed value is located in the list.Skip List Containers 501
WCValSkipList::forAll(), WCValSkipListSet::forAll()Synopsis:Semantics:#include public:void forAll(void (*user_fn)( Type, void * ),void * );The forAll public member function causes the user supplied function to be invoked for every value inthe list. The user function has the prototypevoid user_func( Type & value, void * data );As the elements are visited, the user function is invoked with the element passed as the first. Thesecond parameter <strong>of</strong> the forAll function is passed as the second parameter to the user function. Thisvalue can be used to pass any appropriate data from the main code to the user function.Results:See Also:The elements in the list are all visited, with the user function being invoked for each one.find502 Skip List Containers
WCValSkipList::insert(), WCValSkipListSet::insert()Synopsis:Semantics:#include public:int insert( const Type & );The insert public member function inserts a value into the list. If allocation <strong>of</strong> the node to store thevalue fails, then the out_<strong>of</strong>_memory exception is thrown if it is enabled. If the exception is notenabled, the insert will not be completed.With a WCValSkipListSet, there must be only one equivalent element in the set. If an elementequivalent to the inserted element is already in the list set, the list set will remain unchanged, and thenot_unique exception is thrown if it is enabled. If the exception is not enabled, the insert will not becompleted.Results:See Also:The insert public member function inserts a value into the list. If the insert is successful, a non-zerowill returned. A zero will be returned if the insert fails.operator =, WCExcept::out_<strong>of</strong>_memory, WCExcept::not_uniqueSkip List Containers 503
WCValSkipList::isEmpty(), WCValSkipListSet::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if the list is empty.The isEmpty public member function returns zero if it contains at least one entry, non-zero if the listis empty.entries504 Skip List Containers
WCValSkipList::occurrencesOf()Synopsis:Semantics:Results:See Also:#include public:unsigned occurrencesOf( const Type & ) const;The occurrencesOf public member function is used to return the current number <strong>of</strong> elements storedin the list which are equivalent to the passed value. Note that equivalence is based on the equivalenceoperator <strong>of</strong> the element type.The occurrencesOf public member function returns the number <strong>of</strong> elements in the list which areequivalent to the passed value.entries, find, isEmptySkip List Containers 505
WCValSkipList::operator =(), WCValSkipListSet::operator =()Synopsis:Semantics:Results:See Also:#include public:WCValSkipList & operator =( const WCValSkipList & );WCValSkipListSet & operator =( const WCValSkipListSet & );The operator = public member function is the assignment operator for theWCValSkipList and WCValSkipListSet classes. The left hand side list is firstcleared using the clear member function, and then the right hand side list is copied. The list function,exception trap states, and all <strong>of</strong> the list elements are copied. If there is not enough memory to copy all<strong>of</strong> the values or pointers in the list, then only some will be copied, and the out_<strong>of</strong>_memory exceptionis thrown if it is enabled. The number <strong>of</strong> entries will correctly reflect the number copied.The operator = public member function assigns the left hand side list to be a copy <strong>of</strong> the right handside.clear, WCExcept::out_<strong>of</strong>_memory506 Skip List Containers
WCValSkipList::operator ==(), WCValSkipListSet::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCValSkipList & ) const;int operator ==( const WCValSkipListSet & ) const;The operator == public member function is the equivalence operator for theWCValSkipList and WCValSkipListSet classes. Two list objects areequivalent if they are the same object and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side list are the same object. AFALSE (zero) value is returned otherwise.Skip List Containers 507
WCValSkipList::remove(), WCValSkipListSet::remove()Synopsis:Semantics:Results:#include public:int remove( const Type & );The remove public member function is used to remove the specified element from the list. If anequivalent element is found, a non-zero value is returned. Zero is returned if the element is not found.If the list is a WCValSkipList and there is more than one element equivalent to the specifiedelement, then the last equivalent element added to the WCValSkipList is removed. Note thatequivalence is based on the equivalence operator <strong>of</strong> the element type.The element is removed from the list.508 Skip List Containers
WCValSkipList::removeAll()Synopsis:Semantics:Results:#include public:unsigned removeAll( const Type & );The removeAll public member function is used to remove all elements equivalent to the specifiedelement from the list. Zero is returned if no equivalent elements are found. Note that equivalence isbased on the equivalence operator <strong>of</strong> the element type.All equivalent elements are removed from the list.Skip List Containers 509
WCValSkipList::removeAll()510 Skip List Containers
16 Stack ContainerStack containers maintain an ordered collection <strong>of</strong> data which is retrieved in the reverse order to which thedata was entered into the stack. The stack class is implemented as a templated class, allowing the stacking<strong>of</strong> any data type.A second template parameter specifies the storage class used to implement the stack. The WCValSList,WCIsvSList and WCPtrSList classes are appropriate storage classes.Stack Container 511
WCStackDeclared:wcstack.hThe WCStack class is a templated class used to create objects which maintain data ina stack.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type <strong>of</strong> the elements stored in the stack. The text FType is used to indicate the templateparameter defining the storage class used to maintain the stack.For example, to create a stack <strong>of</strong> integers, the WCStack class can beused. The WCStack class will create a stack <strong>of</strong> pointers tointegers. To create an intrusive stack <strong>of</strong> objects <strong>of</strong> type isv_link (derived from the WCSLink class), theWCStack< isv_link *,WCIsvSList< isv_link > > class can be used.The WCExcept class is a base class <strong>of</strong> the WCStack class and provides theexceptions member function. This member function controls the exceptions which can be thrownby the WCStack object. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> TypeType must provide any constructors and/or operators required by the FType class.Public Member FunctionsThe following member functions are declared in the public interface:WCStack();WCStack( void *(*)( size_t ), void (*)( void *, size_t ) );~WCStack();void clear();int entries() const;int isEmpty() const;Type pop();int push( const Type & );Type top() const;Sample Program Using a Stack#include #include void main() {WCStackstack;stack.push( 7 );stack.push( 8 );stack.push( 9 );stack.push( 10 );}cout
WCStack::WCStack()Synopsis:Semantics:Results:See Also:#include public:WCStack();The public WCStack constructor creates an empty WCStackobject. The FType storage class constructor performs the initialization.The public WCStack constructor creates an initialized WCStackobject.~WCStackStack Container 513
WCStack::WCStack()Synopsis:Semantics:#include public:WCStack( void *(*allocator)( size_t ),void (*deallocator)( void *, size_t ) );The public WCStack constructor creates an empty WCStackobject. If FType is either the WCValSList or WCPtrSList class, then the allocator function isregistered to perform all memory allocations <strong>of</strong> the stack elements, and the deallocator function toperform all freeing <strong>of</strong> the stack elements’ memory. The allocator and deallocator functions are ignoredif FType is the WCIsvSList class. These functions provide the ability to control how the allocationand freeing <strong>of</strong> memory is performed, allowing for more efficient memory handling than the generalpurpose global operator new() and operator delete() can provide. Memory managementoptimizations may potentially be made through the allocator and deallocator functions, but are notrecommended before managing memory is understood and determined to be worth while.The allocator function shall return a pointer to allocated memory <strong>of</strong> size at least the argument, orzero(0) if the allocation cannot be performed. Initialization <strong>of</strong> the memory returned is performed by theWCStack class.The WCStack class calls the deallocator function only on memory allocated by theallocator function. The deallocator shall free the memory pointed to by the first argument which is <strong>of</strong>size the second argument. The size passed to the deallocator function is guaranteed to be the same sizepassed to the allocator function when the memory was allocated.The allocator and deallocator functions may assume that for a list object instance, the allocator isalways called with the same first argument (the size <strong>of</strong> the memory to be allocated). If FType is theWCValSList class, then the WCValSListItemSize(Type) macro returns the size <strong>of</strong> theelements which are allocated by the allocator function. Similarly, the WCPtrSListItemSize(Type ) macro returns the size <strong>of</strong> WCPtrSList elements.The FType storage class constructor performs the initialization <strong>of</strong> the stack.Results:See Also:The public WCStack constructor creates an initialized WCStackobject and registers the allocator and deallocator functions.WCStack, ~WCStack514 Stack Container
WCStack::~WCStack()Synopsis:Semantics:#include public:virtual ~WCStack();The public ~WCStack destructor destroys the WCStack object.The FType storage class destructor performs the destruction. The call to the public~WCStack destructor is inserted implicitly by the compiler at the point where theWCStack object goes out <strong>of</strong> scope.If the not_empty exception is enabled, the exception is thrown if the stack is not empty <strong>of</strong> stackelements.Results:See Also:The WCStack object is destroyed.WCStack, clear, WCExcept::not_emptyStack Container 515
WCStack::clear()Synopsis:Semantics:Results:See Also:#include public:void clear();The clear public member function is used to clear the stack object and set it to the state <strong>of</strong> the objectjust after the initial construction. The stack object is not destroyed and re-created by this operator, sothe object destructor is not invoked. The stack elements are not cleared by the stack class. However,the class used to maintain the stack, FType, may clear the items as part <strong>of</strong> the clear memberfunction for that class. If it does not clear the items, any stack items still in the list are lost unlesspointed to by some pointer object in the program code.The clear public member function resets the stack object to the state <strong>of</strong> the object immediately afterthe initial construction.~WCStack, isEmpty516 Stack Container
WCStack::entries()Synopsis:Semantics:Results:See Also:#include public:int entries() const;The entries public member function is used to determine the number <strong>of</strong> stack elements contained inthe list object.The number <strong>of</strong> elements on the stack is returned. Zero(0) is returned if there are no stack elements.isEmptyStack Container 517
WCStack::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if a stack object has any stack elementscontained in it.A TRUE value (non-zero) is returned if the stack object does not have any stack elements containedwithin it. A FALSE (zero) result is returned if the stack contains at least one element.entries518 Stack Container
WCStack::pop()Synopsis:Semantics:#include public:Type pop();The pop public member function returns the top stack element from the stack object. The top stackelement is the last element pushed onto the stack. The stack element is also removed from the stack.If the stack is empty, one <strong>of</strong> two exceptions can be thrown. If the empty_container exception isenabled, then it will be thrown. Otherwise, the index_range exception will be thrown, if enabled.Results:See Also:The top stack element is removed and returned. The return value is determined by the get memberfunction <strong>of</strong> the FType class if there are no elements on the stack.isEmpty, push, top, WCExcept::empty_container, WCExcept::index_range,FType::getStack Container 519
WCStack::push()Synopsis:Semantics:#include public:int push( const Type & );The push public member function is used to push the data onto the top <strong>of</strong> the stack. It will be the firstelement on the stack to be popped.If the push fails, the out_<strong>of</strong>_memory exception will be thrown, if enabled, and the stack will remainunchanged.Results:See Also:The stack element is pushed onto the top <strong>of</strong> the stack. A TRUE value (non-zero) is returned if the pushis successful. A FALSE (zero) result is returned if the push fails.pop, WCExcept::out_<strong>of</strong>_memory520 Stack Container
WCStack::top()Synopsis:Semantics:#include public:Type top() const;The top public member function returns the top stack element from the stack object. The top stackelement is the last element pushed onto the stack. The stack element is not removed from the stack.If the stack is empty, one <strong>of</strong> two exceptions can be thrown. If the empty_container exception isenabled, then it will be thrown. Otherwise, the index_range exception will be thrown, if enabled.Results:See Also:The top stack element is returned. The return value is determined by the find member function <strong>of</strong> theFType class if there are no elements on the stack.isEmpty, pop, WCExcept::empty_container, WCExcept::index_range,FType::findStack Container 521
WCStack::top()522 Stack Container
17 Vector ContainersThis chapter describes vector containers.Vector Containers 523
WCPtrSortedVector, WCPtrOrderedVectorDeclared:wcvector.hThe WCPtrSortedVector and WCPtrOrderedVector classes are templatedclasses used to store objects in a vector. Ordered and Sorted vectors are powerful arrays which can beresized and provide an abstract interface to insert, find and remove elements. An ordered vectormaintains the order in which elements are added, and allows more than one copy <strong>of</strong> an element that isequivalent. The sorted vector allow only one copy <strong>of</strong> an equivalent element, and inserts them in asorted order. The sorted vector is less efficient when inserting elements, but can provide a fasterretrieval time.Elements cannot be inserted into these vectors by assigning to a vector index. Vectors automaticallygrow when necessary to insert an element if the resize_required exception is not enabled.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type pointed to by the pointers stored in the vector.Note that lookups are performed on the types pointed to, not just by comparing pointers. Two pointerelements are equivalent if the values they point to are equivalent. The values pointed to do not need tobe the same object.The WCPtrOrderedVector class stores elements in the order which they are inserted using theinsert, append, prepend and insertAt member functions. Linear searches are performedto locate entries, and the less than operator is not required.The WCPtrSortedVector class stores elements in ascending order. This requires that Typeprovides a less than operator. Insertions are more expensive than inserting or appending into an orderedvector, since entries must be moved to make room for the new element. A binary search is used tolocate elements in a sorted vector, making searches quicker than in the ordered vector.Care must be taken when using the WCPtrSortedVector class not to change the ordering <strong>of</strong> thevector elements. An object pointed to by a vector element must not be changed so that it is notequivalent to the value when the pointer was inserted into the vector. The index operator and themember functions find, first, and last all return pointers the elements pointed to by the vectorelements. Lookups assume elements are in sorted order, so you should not use the returned pointers tochange the ordering <strong>of</strong> the value pointed to.The WCPtrVector class is also available. It provides a resizable and boundary safe vector similar tostandard arrays.The WCExcept class is a base class <strong>of</strong> the WCPtrSortedVector andWCPtrOrderedVector classes and provides the exceptions member function. Thismember function controls the exceptions which can be thrown by the WCPtrSortedVectorand WCPtrOrderedVector objects. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> TypeBoth the WCPtrSortedVector and WCPtrOrderedVector classes requireType to have:A well defined equivalence operator with constant parameters( int operator ==( const Type & ) const ).Additionally the WCPtrSortedVector class requires Type to have:524 Vector Containers
WCPtrSortedVector, WCPtrOrderedVectorA well defined less than operator with constant parameters( int operator
WCPtrOrderedVector::WCPtrOrderedVector()Synopsis:Semantics:#include public:WCPtrOrderedVector( size_t = WCDEFAULT_VECTOR_LENGTH,unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );The WCPtrOrderedVector constructor creates an empty WCPtrOrderedVector objectable to store the number <strong>of</strong> elements specified in the first optional parameter, which defaults to theconstant WCDEFAULT_VECTOR_LENGTH (currently defined as 10). If the resize_requiredexception is not enabled, then the second optional parameter is used to specify the value to increase thevector size when an element is inserted into a full vector. If zero(0) is specified as the secondparameter, any attempt to insert into a full vector fails. This parameter defaults to the constantWCDEFAULT_VECTOR_RESIZE_GROW (currently defined as 5).If the vector object cannot be fully initialized, the vector is created with length zero.Results:See Also:The WCPtrOrderedVector constructor creates an empty initializedWCPtrOrderedVector object.WCExcept::resize_required526 Vector Containers
WCPtrOrderedVector::WCPtrOrderedVector()Synopsis:Semantics:#include public:WCPtrOrderedVector( const WCPtrOrderedVector & );The WCPtrOrderedVector constructor is the copy constructor for theWCPtrOrderedVector class. The new vector is created with the same length and resize value as thepassed vector. All <strong>of</strong> the vector elements and exception trap states are copied.If the new vector cannot be fully created, it will have length zero. The out_<strong>of</strong>_memory exception isthrown if enabled in the vector being copied.Results:See Also:The WCPtrOrderedVector creates a WCPtrOrderedVector object which is a copy <strong>of</strong>the passed vector.operator =, WCExcept::out_<strong>of</strong>_memoryVector Containers 527
WCPtrOrderedVector::~WCPtrOrderedVector()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCPtrOrderedVector();The WCPtrOrderedVector destructor is the destructor for the WCPtrOrderedVectorclass. If the vector is not length zero and the not_empty exception is enabled, the exception isthrown. Otherwise, the vector entries are cleared using the clear member function. The objectswhich the vector entries point to are not deleted unless the clearAndDestroy member function isexplicitly called before the destructor is called. The call to the WCPtrOrderedVectordestructor is inserted implicitly by the compiler at the point where the WCPtrOrderedVector objectgoes out <strong>of</strong> scope.The WCPtrOrderedVector destructor destroys an WCPtrOrderedVector object.clear, clearAndDestroy, WCExcept::not_empty528 Vector Containers
WCPtrSortedVector::WCPtrSortedVector()Synopsis:Semantics:#include public:WCPtrSortedVector( size_t = WCDEFAULT_VECTOR_LENGTH,unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );The WCPtrSortedVector constructor creates an empty WCPtrSortedVector objectable to store the number <strong>of</strong> elements specified in the first optional parameter, which defaults to theconstant WCDEFAULT_VECTOR_LENGTH (currently defined as 10). If the resize_requiredexception is not enabled, then the second optional parameter is used to specify the value to increase thevector size when an element is inserted into a full vector. If zero(0) is specified as the secondparameter, any attempt to insert into a full vector fails. This parameter defaults to the constantWCDEFAULT_VECTOR_RESIZE_GROW (currently defined as 5).If the vector object cannot be fully initialized, the vector is created with length zero.Results:See Also:The WCPtrSortedVector constructor creates an empty initializedWCPtrSortedVector object.WCExcept::resize_requiredVector Containers 529
WCPtrSortedVector::WCPtrSortedVector()Synopsis:Semantics:#include public:WCPtrSortedVector( const WCPtrSortedVector & );The WCPtrSortedVector constructor is the copy constructor for theWCPtrSortedVector class. The new vector is created with the same length and resize value as thepassed vector. All <strong>of</strong> the vector elements and exception trap states are copied.If the new vector cannot be fully created, it will have length zero. The out_<strong>of</strong>_memory exception isthrown if enabled in the vector being copied.Results:See Also:The WCPtrSortedVector constructor creates a WCPtrSortedVector object which is acopy <strong>of</strong> the passed vector.operator =, WCExcept::out_<strong>of</strong>_memory530 Vector Containers
WCPtrSortedVector::~WCPtrSortedVector()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCPtrSortedVector();The WCPtrSortedVector destructor is the destructor for the WCPtrSortedVectorclass. If the vector is not length zero and the not_empty exception is enabled, the exception isthrown. Otherwise, the vector entries are cleared using the clear member function. The objectswhich the vector entries point to are not deleted unless the clearAndDestroy member function isexplicitly called before the destructor is called. The call to the WCPtrSortedVectordestructor is inserted implicitly by the compiler at the point where the WCPtrSortedVector objectgoes out <strong>of</strong> scope.The WCPtrSortedVector destructor destroys an WCPtrSortedVector object.clear, clearAndDestroy, WCExcept::not_emptyVector Containers 531
WCPtrOrderedVector::append()Synopsis:Semantics:#include public:int append( Type * );The append public member function appends the passed element to be the last element in the vector.This member function has the same semantics as the WCPtrOrderedVector::insert memberfunction.This function is not provided by the WCPtrSortedVector class, since all elements must be insertedin sorted order by the insert member function.Several different results can occur if the vector is not large enough for the new element. If theresize_required exception is enabled, the exception is thrown. If the exception is not enabled,the append fails if the amount the vector is to be grown (the second parameter to the constructor) iszero(0). Otherwise, the vector is automatically grown by the number <strong>of</strong> elements specified to theconstructor, using the resize member function. If resize fails, the element is not appended to thevector and the out_<strong>of</strong>_memory exception is thrown, if enabled.Results:See Also:The append public member function appends an element to the WCPtrOrderedVector object. ATRUE (non-zero) value is returned if the append is successful. If the append fails, a FALSE (zero)value is returned.insert, insertAt, prepend, WCExcept::out_<strong>of</strong>_memory,WCExcept::resize_required532 Vector Containers
WCPtrSortedVector::clear(), WCPtrOrderedVector::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the vector so that it contains no entries, and is zerosize. Objects pointed to by the vector elements are not deleted. The vector object is not destroyed andre-created by this function, so the object destructor is not invoked.The clear public member function clears the vector to have zero length and no entries.See Also: ~WCPtrOrderedVector, clearAndDestroy, operator =Vector Containers 533
WCPtrSortedVector,WCPtrOrderedVector::clearAndDestroy()Synopsis:Semantics:Results:See Also:#include public:void clearAndDestroy();The clearAndDestroy public member function is used to clear the vector to have zero length anddelete the objects pointed to by the vector elements. The vector object is not destroyed and re-createdby this function, so the vector object destructor is not invoked.The clearAndDestroy public member function clears the vector by deleting the objects pointed toby the vector elements and makes the vector zero length.clear534 Vector Containers
WCPtrSortedVector,WCPtrOrderedVector::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Type * ) const;The contains public member function is used to determine if a value is contained by a vector. Notethat comparisons are done on the objects pointed to, not the pointers themselves. A linear search is usedby the WCPtrOrderedVector class to find the value. The WCPtrSortedVector class uses abinary search.The contains public member function returns a TRUE (non-zero) value if the element is found in thevector. A FALSE (zero) value is returned if the vector does not contain the element.index, findVector Containers 535
WCPtrSortedVector::entries(), WCPtrOrderedVector::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to find the number <strong>of</strong> elements which are stored in thevector.The entries public member function returns the number <strong>of</strong> elements in the vector.isEmpty536 Vector Containers
WCPtrSortedVector::find(), WCPtrOrderedVector::find()Synopsis:Semantics:Results:See Also:#include public:Type * find( const Type * ) const;The find public member function is used to find an element equivalent to the element passed. Notethat comparisons are done on the objects pointed to, not the pointers themselves. TheWCPtrOrderedVector class uses a linear search to find the element, and theWCPtrSortedVector class uses a binary search.A pointer to the first equivalent element is returned. NULL(0) is returned if the element is not in thevector.contains, first, index, last, occurrencesOf, removeVector Containers 537
WCPtrSortedVector::first(), WCPtrOrderedVector::first()Synopsis:Semantics:#include public:Type * first() const;The first public member function returns the first element in the vector. The element is not removedfrom the vector.If the vector is empty, one <strong>of</strong> two exceptions can be thrown. The empty_container exception isthrown if it is enabled. Otherwise, if the index_range exception is enabled, it is thrown. If neitherexception is enabled, a first element <strong>of</strong> the vector is added with a NULL value.Results:See Also:The first public member function returns the value <strong>of</strong> the first element in the vector.last, removeFirst, WCExcept::index_range, WCExcept::resize_required538 Vector Containers
WCPtrSortedVector::index(), WCPtrOrderedVector::index()Synopsis:Semantics:Results:See Also:#include public:int index( const Type * ) const;The index public member function is used find the index <strong>of</strong> the first element equivalent to the passedelement. Note that comparisons are done on the objects pointed to, not the pointers themselves. Alinear search is used by the WCPtrOrderedVector class to find the element. TheWCPtrSortedVector class uses a binary search.The index public member function returns the index <strong>of</strong> the first element equivalent to the parameter.If the passed value is not contained in the vector, negative one (-1) is returned.contains, find, insertAt, operator [], removeAtVector Containers 539
WCPtrSortedVector::insert(), WCPtrOrderedVector::insert()Synopsis:Semantics:#include public:int insert( Type * );The insert public member function inserts the value into the vector.The WCPtrOrderedVector::insert function inserts the value as the last element <strong>of</strong> the vector,and has the same semantics as the WCPtrOrderedVector::append member function.A binary search is performed to determine where the value should be inserted for theWCPtrSortedVector::insert function. Note that comparisons are done on the objects pointedto, not the pointers themselves. Any elements greater than the inserted value are copied up one index sothat the new element is after all elements with value less than or equal to it.Several different results can occur if the vector is not large enough for the new element. If theresize_required exception is enabled, the exception is thrown. If the exception is not enabled,the insert fails if the amount the vector is to be grown (the second parameter to the constructor) iszero(0). Otherwise, the vector is automatically grown by the number <strong>of</strong> elements specified to theconstructor, using the resize member function. If resize fails, the element is not inserted to thevector and the out_<strong>of</strong>_memory exception is thrown, if enabled.Results:See Also:The insert public member function inserts an element in to the vector. A TRUE (non-zero) value isreturned if the insert is successful. If the insert fails, a FALSE (zero) value is returned.append, insertAt, prepend, WCExcept::out_<strong>of</strong>_memory,WCExcept::resize_required540 Vector Containers
WCPtrOrderedVector::insertAt()Synopsis:Semantics:#include public:int insertAt( int, Type * );The insertAt public member function inserts the second argument into the vector before the elementat index given by the first argument. If the passed index is equal to the number <strong>of</strong> entries in the vector,the new value is appended to the vector as the last element. All vector elements with indexes greaterthan or equal to the first parameter are copied up one index.This function is not provided by the WCPtrSortedVector class, since all elements must be insertedin sorted order by the insert member function.If the passed index is negative or greater than the number <strong>of</strong> entries in the vector and theindex_range exception is enabled, the exception is thrown. If the exception is not enabled, the newelement is inserted as the first element when the index is negative, or as the last element when the indexis too large.Several different results can occur if the vector is not large enough for the new element. If theresize_required exception is enabled, the exception is thrown. If the exception is not enabled,the insert fails if the amount the vector is to be grown (the second parameter to the constructor) iszero(0). Otherwise, the vector is automatically grown by the number <strong>of</strong> elements specified to theconstructor, using the resize member function. If resize fails, the element is not inserted into thevector and the out_<strong>of</strong>_memory exception is thrown, if enabled.Results:See Also:The insertAt public member function inserts an element into the WCPtrOrderedVector objectbefore the element at the given index. A TRUE (non-zero) value is returned if the insert is successful.If the insert fails, a FALSE (zero) value is returned.append, insert, prepend, operator [], removeAt, WCExcept::index_range,WCExcept::out_<strong>of</strong>_memory, WCExcept::resize_requiredVector Containers 541
WCPtrSortedVector,WCPtrOrderedVector::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if a vector object has any entries containedin it.A TRUE value (non-zero) is returned if the vector object does not have any vector elements containedwithin it. A FALSE (zero) result is returned if the vector contains at least one element.entries542 Vector Containers
WCPtrSortedVector::last(), WCPtrOrderedVector::last()Synopsis:Semantics:#include public:Type * last() const;The last public member function returns the last element in the vector. The element is not removedfrom the vector.If the vector is empty, one <strong>of</strong> two exceptions can be thrown. The empty_container exception isthrown if it is enabled. Otherwise, if the index_range exception is enabled, it is thrown. If neitherexception is enabled, a first element <strong>of</strong> the vector is added with a NULL value.Results:See Also:The last public member function returns the value <strong>of</strong> the last element in the vector.first, removeLast, WCExcept::index_range, WCExcept::resize_requiredVector Containers 543
WCPtrSortedVector,WCPtrOrderedVector::occurrencesOf()Synopsis:Semantics:Results:See Also:#include public:int occurrencesOf( const Type * ) const;The occurrencesOf public member function returns the number <strong>of</strong> elements contained in the vectorthat are equivalent to the passed value. Note that comparisons are done on the objects pointed to, notthe pointers themselves. A linear search is used by the WCPtrOrderedVector class to find thevalue. The WCPtrSortedVector class uses a binary search.The occurrencesOf public member function returns the number <strong>of</strong> elements equivalent to thepassed value.contains, find, index, operator [], removeAll544 Vector Containers
WCPtrSortedVector,WCPtrOrderedVector::operator []()Synopsis:Semantics:#include public:Type * & operator []( int );Type * const & operator []( int ) const;operator [] is the vector index operator. A reference to the object stored in the vector at the givenindex is returned. If a constant vector is indexed, a reference to a constant element is returned.The append, insert, insertAt and prepend member functions are used to insert a newelement into a vector, and the remove, removeAll, removeAt, removeFirst andremoveLast member functions remove elements. The index operator cannot be used to change thenumber <strong>of</strong> entries in the vector. Searches may be performed using the find and index memberfunctions.If the vector is empty, one <strong>of</strong> two exceptions can be thrown. The empty_container exception isthrown if it is enabled. Otherwise, if the index_range exception is enabled, it is thrown. If neitherexception is enabled, a first element <strong>of</strong> the vector is added with a NULL value. This element is addedso that a reference to a valid vector element can be returned.If the index value is negative and the index_range exception is enabled, the exception is thrown.An attempt to index an element with index greater than or equal to the number <strong>of</strong> entries in the vectorwill also cause the index_range exception to be thrown if enabled. If the exception is not enabled,attempting to index a negative element will index the first element in the vector, and attempting to indexan element after the last entry will index the last element.Care must be taken when using the WCPtrSortedVector class not to change the ordering <strong>of</strong> thevector elements. The result returned by the index operator must not be assigned to or modified in sucha way that it is no longer equivalent (by Type’s equivalence operator) to the value inserted into thevector. Failure to comply may cause lookups to work incorrectly, since the binary search algorithmassumes elements are in sorted order.Results:See Also:The operator [] public member function returns a reference to the element at the given index. Ifthe index is invalid, a reference to the closest valid element is returned. The result <strong>of</strong> the non-constantindex operator may be assigned to.append, find, first, index, insert, insertAt, isEmpty, last, prepend, remove,removeAt, removeAll, removeFirst, removeLast, WCExcept::empty_container,WCExcept::index_rangeVector Containers 545
WCPtrSortedVector,WCPtrOrderedVector::operator =()Synopsis:Semantics:#include public:WCPtrOrderedVector & WCPtrOrderedVector::operator =( constWCPtrOrderedVector & );WCPtrSortedVector & WCPtrSortedVector::operator =( constWCPtrSortedVector & );The operator = public member function is the assignment operator for the class. The left hand sidevector is first cleared using the clear member function, and then the right hand side vector is copied.The left hand side vector is made to have the same length and growth amount as the right hand side (thegrowth amount is the second argument passed to the right hand side vector constructor). All <strong>of</strong> thevector elements and exception trap states are copied.If the left hand side vector cannot be fully created, it will have zero length. The out_<strong>of</strong>_memoryexception is thrown if enabled in the right hand side vector.Results:See Also:The operator = public member function assigns the left hand side vector to be a copy <strong>of</strong> the righthand side.clear, clearAndDestroy, WCExcept::out_<strong>of</strong>_memory546 Vector Containers
WCPtrSortedVector,WCPtrOrderedVector::operator ==()Synopsis:Semantics:Results:#include public:int WCPtrOrderedVector::operator ==( const WCPtrOrderedVector & )const;int WCPtrSortedVector::operator ==( const WCPtrSortedVector & )const;The operator == public member function is the equivalence operator for the class. Two vectorobjects are equivalent if they are the same object and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the sameobject. A FALSE (zero) value is returned otherwise.Vector Containers 547
WCPtrOrderedVector::prepend()Synopsis:Semantics:#include public:int prepend( Type * );The prepend public member function inserts the passed element to be the first element in the vector.All vector elements contained in the vector are copied up one index.This function is not provided by the WCPtrSortedVector class, since all elements must be insertedin sorted order by the insert member function.Several different results can occur if the vector is not large enough for the new element. If theresize_required exception is enabled, the exception is thrown. If the exception is not enabled,the prepend fails if the amount the vector is to be grown (the second parameter to the constructor) iszero(0). Otherwise, the vector is automatically grown by the number <strong>of</strong> elements specified to theconstructor, using the resize member function. If resize fails, the element is not inserted to thevector and the out_<strong>of</strong>_memory exception is thrown, if enabled.Results:See Also:The prepend public member function prepends an element to the WCPtrOrderedVector object.A TRUE (non-zero) value is returned if the insert is successful. If the insert fails, a FALSE (zero) valueis returned.append, insert, insertAt, WCExcept::out_<strong>of</strong>_memory,WCExcept::resize_required548 Vector Containers
WCPtrSortedVector::remove(), WCPtrOrderedVector::remove()Synopsis:Semantics:#include public:Type * remove( const Type * );The remove public member function removes the first element in the vector which is equivalent to thepassed value. Note that comparisons are done on the objects pointed to, not the pointers themselves.All vector elements stored after the removed elements are copied down one index.A linear search is used by the WCPtrOrderedVector class to find the element being removed. TheWCPtrSortedVector class uses a binary search.Results:See Also:The remove public member function removes the first element in the vector which is equivalent to thepassed value. The removed pointer is returned. If the vector did not contain an equivalent value,NULL(0) is returned.clear, clearAndDestroy, find, removeAll, removeAt, removeFirst, removeLastVector Containers 549
WCPtrSortedVector,WCPtrOrderedVector::removeAll()Synopsis:Semantics:#include public:unsigned removeAll( const Type * );The removeAll public member function removes all elements in the vector which are equivalent tothe passed value. Note that comparisons are done on the objects pointed to, not the pointers themselves.All vector elements stored after the removed elements are copied down one or more indexes to take theplace <strong>of</strong> the removed elements.A linear search is used by the WCPtrOrderedVector class to find the elements being removed. TheWCPtrSortedVector class uses a binary search.Results:See Also:The removeAll public member function removes all elements in the vector which are equivalent tothe passed value. The number <strong>of</strong> elements removed is returned.clear, clearAndDestroy, find, occurrencesOf, remove, removeAt, removeFirst,removeLast550 Vector Containers
WCPtrSortedVector,WCPtrOrderedVector::removeAt()Synopsis:Semantics:#include public:Type * removeAt( int );The removeAt public member function removes the element at the given index. All vector elementsstored after the removed elements are copied down one index.If the vector is empty and the empty_container exception is enabled, the exception is thrown.If an attempt to remove an element with a negative index is made and the index_range exception isenabled, the exception is thrown. If the exception is not enabled, the first element is removed from thevector. Attempting to remove an element with index greater or equal to the number <strong>of</strong> entries in thevector also causes the index_range exception to be thrown if enabled. The last element in the vectoris removed if the exception is not enabled.Results:See Also:The removeAt public member function removes the element with the given index. If the index isinvalid, the closest element to the given index is removed. The removed pointer is returned. If thevector was empty, NULL(0) is returned.clear, clearAndDestroy, insertAt, operator [], remove, removeAll,removeFirst, removeLastVector Containers 551
WCPtrSortedVector,WCPtrOrderedVector::removeFirst()Synopsis:Semantics:#include public:Type * removeFirst();The removeFirst public member function removes the first element from a vector. All other vectorelements are copied down one index.If the vector is empty and the empty_container exception is enabled, the exception is thrown.Results:See Also:The removeFirst public member function removes the first element from the vector. The removedpointer is returned. If the vector was empty, NULL(0) is returned.clear, clearAndDestroy, first, remove, removeAt, removeAll, removeLast552 Vector Containers
WCPtrSortedVector,WCPtrOrderedVector::removeLast()Synopsis:Semantics:Results:See Also:#include public:Type * removeLast();The removeLast public member function removes the last element from a vector. If the vector isempty and the empty_container exception is enabled, the exception is thrown.The removeLast public member function removes the last element from the vector. The removedpointer is returned. If the vector was empty, NULL(0) is returned.clear, clearAndDestroy, last, remove, removeAt, removeAll, removeFirstVector Containers 553
WCPtrSortedVector::resize(), WCPtrOrderedVector::resize()Synopsis:Semantics:#include public:int resize( size_t new_size );The resize public member function is used to change the vector size to be able to store new_sizeelements. If new_size is larger than the previous vector size, all elements are copied into the newlysized vector, and new elements can be added using the append, insert, insertAt, andprepend member functions. If the vector is resized to a smaller size, the first new_size elements arecopied (all vector elements if the vector contained new_size or fewer elements). The objects pointed toby the remaining elements are not deleted.If the resize cannot be performed and the out_<strong>of</strong>_memory exception is enabled, the exception isthrown.Results:See Also:The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. AFALSE (zero) result is returned if the resize fails.WCExcept::out_<strong>of</strong>_memory554 Vector Containers
WCPtrVectorDeclared:wcvector.hThe WCPtrVector class is a templated class used to store objects in a vector. Vectors aresimilar to arrays, but vectors perform bounds checking and can be resized. Elements are inserted intothe vector by assigning to a vector index.The WCPtrOrderedVector and WCPtrSortedVector classes are also available. They provide amore abstract view <strong>of</strong> the vector and additional functionality, including finding and removing elements.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type pointed to by the pointers stored in the vector.The WCExcept class is a base class <strong>of</strong> the WCPtrVector class and provides theexceptions member function. This member function controls the exceptions which can be thrownby the WCPtrVector object. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> TypeThe WCPtrVector class requires nothing from Type.Public Member FunctionsThe following member functions are declared in the public interface:WCPtrVector( size_t = 0 );WCPtrVector( size_t, const Type * );WCPtrVector( const WCPtrVector & );virtual ~WCPtrVector();void clear();void clearAndDestroy();size_t length() const;int resize( size_t );Public Member OperatorsThe following member operators are declared in the public interface:Type * & operator []( int );Type * const & operator []( int ) const;WCPtrVector & operator =( const WCPtrVector & );int operator ==( const WCPtrVector & ) const;Vector Containers 555
WCPtrVector::WCPtrVector()Synopsis:Semantics:#include public:WCPtrVector( size_t = 0 );The public WCPtrVector constructor creates a WCPtrVector object able to storethe number <strong>of</strong> elements specified in the optional parameter, which defaults to zero. All vector elementsare initialized to NULL(0).If the vector object cannot be fully initialized, the vector is created with length zero.Results:See Also:The public WCPtrVector constructor creates an initialized WCPtrVector objectwith the specified length.WCPtrVector, ~WCPtrVector556 Vector Containers
WCPtrVector::WCPtrVector()Synopsis:Semantics:#include public:WCPtrVector( size_t, const Type * );The public WCPtrVector constructor creates a WCPtrVector object able to storethe number <strong>of</strong> elements specified by the first parameter. All vector elements are initialized to thepointer value given by the second parameter.If the vector object cannot be fully initialized, the vector is created with length zero.Results:See Also:The public WCPtrVector constructor creates an initialized WCPtrVector objectwith the specified length and elements set to the given value.WCPtrVector, ~WCPtrVectorVector Containers 557
WCPtrVector::WCPtrVector()Synopsis:Semantics:#include public:WCPtrVector( const WCPtrVector & );The public WCPtrVector constructor is the copy constructor for theWCPtrVector class. The new vector is created with the same length as the given vector. All<strong>of</strong> the vector elements and exception trap states are copied.If the new vector cannot be fully created, it will have length zero. The out_<strong>of</strong>_memory exception isthrown if enabled in the vector being copied.Results:See Also:The public WCPtrVector constructor creates a WCPtrVector object which is acopy <strong>of</strong> the passed vector.operator =, WCExcept::out_<strong>of</strong>_memory558 Vector Containers
WCPtrVector::~WCPtrVector()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCPtrVector();The public ~WCPtrVector destructor is the destructor for the WCPtrVectorclass. If the vector is not length zero and the not_empty exception is enabled, the exception isthrown. Otherwise, the vector elements are cleared using the clear member function. The objectswhich the vector elements point to are not deleted unless the clearAndDestroy member function isexplicitly called before the destructor is called. The call to the public ~WCPtrVectordestructor is inserted implicitly by the compiler at the point where the WCPtrVector objectgoes out <strong>of</strong> scope.The public ~WCPtrVector destructor destroys an WCPtrVector object.clear, clearAndDestroy, WCExcept::not_emptyVector Containers 559
WCPtrVector::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the vector so that it is <strong>of</strong> zero length. Objectspointed to by the vector elements are not deleted. The vector object is not destroyed and re-created bythis function, so the object destructor is not invoked.The clear public member function clears the vector to have zero length and no vector elements.See Also: ~WCPtrVector, clearAndDestroy, operator =560 Vector Containers
WCPtrVector::clearAndDestroy()Synopsis:Semantics:Results:See Also:#include public:void clearAndDestroy();The clearAndDestroy public member function is used to clear the vector to have zero length anddelete the objects pointed to by the vector elements. The vector object is not destroyed and re-createdby this function, so the vector object destructor is not invoked.The clearAndDestroy public member function clears the vector by deleting the objects pointed toby the vector elements and makes the vector zero length.clearVector Containers 561
WCPtrVector::length()Synopsis:Semantics:Results:See Also:#include public:size_t length() const;The length public member function is used to find the number <strong>of</strong> elements which can be stored in theWCPtrVector object.The length public member function returns the length <strong>of</strong> the vector.resize562 Vector Containers
WCPtrVector::operator []()Synopsis:Semantics:#include public:Type * & operator []( int );Type * const & operator []( int ) const;operator [] is the vector index operator. A reference to the object stored in the vector at the givenindex is returned. If a constant vector is indexed, a reference to a constant element is returned. Theindex operator <strong>of</strong> a non-constant vector is the only way to insert an element into the vector.If an attempt to access an element with index greater than or equal to the length <strong>of</strong> a non-constant vectoris made and the resize_required exception is enabled, the exception is thrown. If the exception isnot enabled, the vector is automatically resized using the resize member function to have length theindex value plus one. New vector elements are initialized to NULL(0). If the resize failed, and theout_<strong>of</strong>_memory exception is enabled, the exception is thrown. If the exception is not enabled andthe resize failed, the last element is indexed (a new element if the vector was zero length). If a negativevalue is used to index the non-constant vector and the index_range exception is enabled, theexception is thrown. If the exception is not enabled and the vector is empty, the resize_requiredexception may be thrown.An attempt to index an empty constant vector may cause one <strong>of</strong> two exceptions to be thrown. If theempty_container exception is enabled, it is thrown. Otherwise, the index_range exception isthrown, if enabled. If neither exception is enabled, a first vector element is added and indexed (so that areference to a valid element can be returned).Indexing with a negative value or a value greater than or equal to the length <strong>of</strong> a constant vector causesthe index_range exception to be thrown, if enabled.Results:See Also:The operator [] public member function returns a reference to the element at the given index. Ifthe index is invalid, a reference to the closest valid element is returned. The result <strong>of</strong> the non-constantindex operator may be assigned to.resize, WCExcept::empty_container, WCExcept::index_range,WCExcept::out_<strong>of</strong>_memory, WCExcept::resize_requiredVector Containers 563
WCPtrVector::operator =()Synopsis:Semantics:#include public:WCPtrVector & operator =( const WCPtrVector & );The operator = public member function is the assignment operator for the WCPtrVectorclass. The left hand side vector is first cleared using the clear member function, and then the righthand side vector is copied. The left hand side vector is made to have the same length as the right handside. All <strong>of</strong> the vector elements and exception trap states are copied.If the left hand side vector cannot be fully created, it will have zero length. The out_<strong>of</strong>_memoryexception is thrown if enabled in the right hand side vector.Results:See Also:The operator = public member function assigns the left hand side vector to be a copy <strong>of</strong> the righthand side.clear, clearAndDestroy, WCExcept::out_<strong>of</strong>_memory564 Vector Containers
WCPtrVector::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCPtrVector & ) const;The operator == public member function is the equivalence operator for theWCPtrVector class. Two vector objects are equivalent if they are the same object and sharethe same address.A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the sameobject. A FALSE (zero) value is returned otherwise.Vector Containers 565
WCPtrVector::resize()Synopsis:Semantics:#include public:int resize( size_t new_size );The resize public member function is used to change the vector size to be able to store new_sizeelements. If new_size is larger than the previous vector size, all elements will be copied into the newlysized vector, and new elements are initialized to NULL(0). If the vector is resized to a smaller size, thefirst new_size elements are copied. The objects pointed to by the remaining elements are not deleted.If the resize cannot be performed and the out_<strong>of</strong>_memory exception is enabled, the exception isthrown.Results:See Also:The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. AFALSE (zero) result is returned if the resize fails.WCExcept::out_<strong>of</strong>_memory566 Vector Containers
WCValSortedVector, WCValOrderedVectorDeclared:wcvector.hThe WCValSortedVector and WCValOrderedVector classes are templatedclasses used to store objects in a vector. Ordered and Sorted vectors are powerful arrays which can beresized and provide an abstract interface to insert, find and remove elements. An ordered vectormaintains the order in which elements are added, and allows more than one copy <strong>of</strong> an element that isequivalent. The sorted vector allow only one copy <strong>of</strong> an equivalent element, and inserts them in asorted order. The sorted vector is less efficient when inserting elements, but can provide a fasterretrieval time.Elements cannot be inserted into these vectors by assigning to a vector index. Vectors automaticallygrow when necessary to insert an element if the resize_required exception is not enabled.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type <strong>of</strong> the elements stored in the vector.Values are copied into the vector, which could be undesirable if the stored objects are complicated andcopying is expensive. Value vectors should not be used to store objects <strong>of</strong> a base class if any derivedtypes <strong>of</strong> different sizes would be stored in the vector, or if the destructor for a derived class must becalled.The WCValOrderedVector class stores elements in the order which they are inserted using theinsert, append, prepend and insertAt member functions. Linear searches are performedto locate entries, and the less than operator is not required.The WCValSortedVector class stores elements in ascending order. This requires that Typeprovides a less than operator. Insertions are more expensive than inserting or appending into an orderedvector, since entries must be moved to make room for the new element. A binary search is used tolocate elements in a sorted vector, making searches quicker than in the ordered vector.Care must be taken when using the WCValSortedVector class not to change the ordering <strong>of</strong> thevector elements. The result returned by the index operator must not be assigned to or modified in sucha way that it is no longer equivalent to the value inserted into the vector. Lookups assume elements arein sorted order.The WCValVector class is also available. It provides a resizable and boundary safe vector similar tostandard arrays.The WCExcept class is a base class <strong>of</strong> the WCValSortedVector andWCValOrderedVector classes and provides the exceptions member function. Thismember function controls the exceptions which can be thrown by the WCValSortedVectorand WCValOrderedVector objects. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> TypeBoth the WCValSortedVector and WCValOrderedVector classes requireType to have:A default constructor ( Type::Type() ).A well defined copy constructor ( Type::Type( const Type & ) ).A well defined assignment operatorVector Containers 567
WCValSortedVector, WCValOrderedVector( Type & operator =( const Type & ) ).The following override <strong>of</strong> operator new() if Type overrides the global operator new():void * operator new( size_t, void *ptr ) { return( ptr ); }A well defined equivalence operator with constant parameters( int operator ==( const Type & ) const ).Additionally the WCValSortedVector class requires Type to have:A well defined less than operator with constant parameters( int operator
WCValSortedVector, WCValOrderedVectorWCValSortedVector & WCValSortedVector::operator =( constWCValSortedVector & );int WCValOrderedVector::operator ==( const WCValOrderedVector & )const;int WCValSortedVector::operator ==( const WCValSortedVector & )const;Vector Containers 569
WCValOrderedVector::WCValOrderedVector()Synopsis:Semantics:#include public:WCValOrderedVector( size_t = WCDEFAULT_VECTOR_LENGTH,unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );The WCValOrderedVector constructor creates an empty WCValOrderedVector objectable to store the number <strong>of</strong> elements specified in the first optional parameter, which defaults to theconstant WCDEFAULT_VECTOR_LENGTH (currently defined as 10). If the resize_requiredexception is not enabled, then the second optional parameter is used to specify the value to increase thevector size when an element is inserted into a full vector. If zero(0) is specified as the secondparameter, any attempt to insert into a full vector fails. This parameter defaults to the constantWCDEFAULT_VECTOR_RESIZE_GROW (currently defined as 5).If the vector object cannot be fully initialized, the vector is created with length zero.Results:See Also:The WCValOrderedVector constructor creates an empty initializedWCValOrderedVector object.WCExcept::resize_required570 Vector Containers
WCValOrderedVector::WCValOrderedVector()Synopsis:Semantics:#include public:WCValOrderedVector( const WCValOrderedVector & );The WCValOrderedVector constructor is the copy constructor for theWCValOrderedVector class. The new vector is created with the same length and resize value as thepassed vector. All <strong>of</strong> the vector elements and exception trap states are copied.If the new vector cannot be fully created, it will have length zero. The out_<strong>of</strong>_memory exception isthrown if enabled in the vector being copied.Results:See Also:The WCValOrderedVector creates a WCValOrderedVector object which is a copy <strong>of</strong>the passed vector.operator =, WCExcept::out_<strong>of</strong>_memoryVector Containers 571
WCValOrderedVector::~WCValOrderedVector()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCValOrderedVector();The WCValOrderedVector destructor is the destructor for the WCValOrderedVectorclass. If the vector is not length zero and the not_empty exception is enabled, the exception isthrown. Otherwise, the vector entries are cleared using the clear member function. The call to theWCValOrderedVector destructor is inserted implicitly by the compiler at the point wherethe WCValOrderedVector object goes out <strong>of</strong> scope.The WCValOrderedVector destructor destroys an WCValOrderedVector object.clear, WCExcept::not_empty572 Vector Containers
WCValSortedVector::WCValSortedVector()Synopsis:Semantics:#include public:WCValSortedVector( size_t = WCDEFAULT_VECTOR_LENGTH,unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );The WCValSortedVector constructor creates an empty WCValSortedVector objectable to store the number <strong>of</strong> elements specified in the first optional parameter, which defaults to theconstant WCDEFAULT_VECTOR_LENGTH (currently defined as 10). If the resize_requiredexception is not enabled, then the second optional parameter is used to specify the value to increase thevector size when an element is inserted into a full vector. If zero(0) is specified as the secondparameter, any attempt to insert into a full vector fails. This parameter defaults to the constantWCDEFAULT_VECTOR_RESIZE_GROW (currently defined as 5).If the vector object cannot be fully initialized, the vector is created with length zero.Results:See Also:The WCValSortedVector constructor creates an empty initializedWCValSortedVector object.WCExcept::resize_requiredVector Containers 573
WCValSortedVector::WCValSortedVector()Synopsis:Semantics:#include public:WCValSortedVector( const WCValSortedVector & );The WCValSortedVector constructor is the copy constructor for theWCValSortedVector class. The new vector is created with the same length and resize value as thepassed vector. All <strong>of</strong> the vector elements and exception trap states are copied.If the new vector cannot be fully created, it will have length zero. The out_<strong>of</strong>_memory exception isthrown if enabled in the vector being copied.Results:See Also:The WCValSortedVector constructor creates a WCValSortedVector object which is acopy <strong>of</strong> the passed vector.operator =, WCExcept::out_<strong>of</strong>_memory574 Vector Containers
WCValSortedVector::~WCValSortedVector()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCValSortedVector();The WCValSortedVector destructor is the destructor for the WCValSortedVectorclass. If the vector is not length zero and the not_empty exception is enabled, the exception isthrown. Otherwise, the vector entries are cleared using the clear member function. The call to theWCValSortedVector destructor is inserted implicitly by the compiler at the point wherethe WCValSortedVector object goes out <strong>of</strong> scope.The WCValSortedVector destructor destroys an WCValSortedVector object.clear, WCExcept::not_emptyVector Containers 575
WCValOrderedVector::append()Synopsis:Semantics:#include public:int append( const Type & );The append public member function appends the passed element to be the last element in the vector.The data stored in the vector is a copy <strong>of</strong> the data passed as a parameter. This member function has thesame semantics as the WCValOrderedVector::insert member function.This function is not provided by the WCValSortedVector class, since all elements must be insertedin sorted order by the insert member function.Several different results can occur if the vector is not large enough for the new element. If theresize_required exception is enabled, the exception is thrown. If the exception is not enabled,the append fails if the amount the vector is to be grown (the second parameter to the constructor) iszero(0). Otherwise, the vector is automatically grown by the number <strong>of</strong> elements specified to theconstructor, using the resize member function. If resize fails, the element is not appended to thevector and the out_<strong>of</strong>_memory exception is thrown, if enabled.Results:See Also:The append public member function appends an element to the WCValOrderedVector object. ATRUE (non-zero) value is returned if the append is successful. If the append fails, a FALSE (zero)value is returned.insert, insertAt, prepend, WCExcept::out_<strong>of</strong>_memory,WCExcept::resize_required576 Vector Containers
WCValSortedVector::clear(), WCValOrderedVector::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the vector so that it contains no entries, and is zerosize. Elements stored in the vector are destroyed using Type’s destructor. The vector object is notdestroyed and re-created by this function, so the object destructor is not invoked.The clear public member function clears the vector to have zero length and no entries.See Also: ~WCValOrderedVector, operator =Vector Containers 577
WCValSortedVector,WCValOrderedVector::contains()Synopsis:Semantics:Results:See Also:#include public:int contains( const Type & ) const;The contains public member function is used to determine if a value is contained by a vector. Alinear search is used by the WCValOrderedVector class to find the value. TheWCValSortedVector class uses a binary search.The contains public member function returns a TRUE (non-zero) value if the element is found in thevector. A FALSE (zero) value is returned if the vector does not contain the element.index, find578 Vector Containers
WCValSortedVector::entries(), WCValOrderedVector::entries()Synopsis:Semantics:Results:See Also:#include public:unsigned entries() const;The entries public member function is used to find the number <strong>of</strong> elements which are stored in thevector.The entries public member function returns the number <strong>of</strong> elements in the vector.isEmptyVector Containers 579
WCValSortedVector::find(), WCValOrderedVector::find()Synopsis:Semantics:Results:See Also:#include public:int find( const Type &, Type & ) const;The find public member function is used to find an element equivalent to the first argument. TheWCValOrderedVector class uses a linear search to find the element, and theWCValSortedVector class uses a binary search.If an equivalent element is found, a TRUE (non-zero) value is returned, and the second parameter isassigned the first equivalent value. A FALSE (zero) value is returned and the second parameter isunchanged if the element is not in the vector.contains, first, index, last, occurrencesOf, remove580 Vector Containers
WCValSortedVector::first(), WCValOrderedVector::first()Synopsis:Semantics:#include public:Type first() const;The first public member function returns the first element in the vector. The element is not removedfrom the vector.If the vector is empty, one <strong>of</strong> two exceptions can be thrown. The empty_container exception isthrown if it is enabled. Otherwise, if the index_range exception is enabled, it is thrown. If neitherexception is enabled, a first element <strong>of</strong> the vector is added with a default value.Results:See Also:The first public member function returns the value <strong>of</strong> the first element in the vector.last, removeFirst, WCExcept::index_range, WCExcept::resize_requiredVector Containers 581
WCValSortedVector::index(), WCValOrderedVector::index()Synopsis:Semantics:Results:See Also:#include public:int index( const Type & ) const;The index public member function is used find the index <strong>of</strong> the first element equivalent to the passedelement. A linear search is used by the WCValOrderedVector class to find the element. TheWCValSortedVector class uses a binary search.The index public member function returns the index <strong>of</strong> the first element equivalent to the parameter.If the passed value is not contained in the vector, negative one (-1) is returned.contains, find, insertAt, operator [], removeAt582 Vector Containers
WCValSortedVector::insert(), WCValOrderedVector::insert()Synopsis:Semantics:#include public:int insert( const Type & );The insert public member function inserts the value into the vector. The data stored in the vector is acopy <strong>of</strong> the data passed as a parameter.The WCValOrderedVector::insert function inserts the value as the last element <strong>of</strong> the vector,and has the same semantics as the WCValOrderedVector::append member function.A binary search is performed to determine where the value should be inserted for theWCValSortedVector::insert function. Any elements greater than the inserted value are copiedup one index (using Type’s assignment operator), so that the new element is after all elements withvalue less than or equal to it.Several different results can occur if the vector is not large enough for the new element. If theresize_required exception is enabled, the exception is thrown. If the exception is not enabled,the insert fails if the amount the vector is to be grown (the second parameter to the constructor) iszero(0). Otherwise, the vector is automatically grown by the number <strong>of</strong> elements specified to theconstructor, using the resize member function. If resize fails, the element is not inserted to thevector and the out_<strong>of</strong>_memory exception is thrown, if enabled.Results:See Also:The insert public member function inserts an element in to the vector. A TRUE (non-zero) value isreturned if the insert is successful. If the insert fails, a FALSE (zero) value is returned.append, insertAt, prepend, WCExcept::out_<strong>of</strong>_memory,WCExcept::resize_requiredVector Containers 583
WCValOrderedVector::insertAt()Synopsis:Semantics:#include public:int insertAt( int, const Type & );The insertAt public member function inserts the second argument into the vector before the elementat index given by the first argument. If the passed index is equal to the number <strong>of</strong> entries in the vector,the new value is appended to the vector as the last element. The data stored in the vector is a copy <strong>of</strong>the data passed as a parameter. All vector elements with indexes greater than or equal to the firstparameter are copied (using Type’s assignment operator) up one index.This function is not provided by the WCValSortedVector class, since all elements must be insertedin sorted order by the insert member function.If the passed index is negative or greater than the number <strong>of</strong> entries in the vector and theindex_range exception is enabled, the exception is thrown. If the exception is not enabled, the newelement is inserted as the first element when the index is negative, or as the last element when the indexis too large.Several different results can occur if the vector is not large enough for the new element. If theresize_required exception is enabled, the exception is thrown. If the exception is not enabled,the insert fails if the amount the vector is to be grown (the second parameter to the constructor) iszero(0). Otherwise, the vector is automatically grown by the number <strong>of</strong> elements specified to theconstructor, using the resize member function. If resize fails, the element is not inserted into thevector and the out_<strong>of</strong>_memory exception is thrown, if enabled.Results:See Also:The insertAt public member function inserts an element into the WCValOrderedVector objectbefore the element at the given index. A TRUE (non-zero) value is returned if the insert is successful.If the insert fails, a FALSE (zero) value is returned.append, insert, prepend, operator [], removeAt, WCExcept::index_range,WCExcept::out_<strong>of</strong>_memory, WCExcept::resize_required584 Vector Containers
WCValSortedVector,WCValOrderedVector::isEmpty()Synopsis:Semantics:Results:See Also:#include public:int isEmpty() const;The isEmpty public member function is used to determine if a vector object has any entries containedin it.A TRUE value (non-zero) is returned if the vector object does not have any vector elements containedwithin it. A FALSE (zero) result is returned if the vector contains at least one element.entriesVector Containers 585
WCValSortedVector::last(), WCValOrderedVector::last()Synopsis:Semantics:#include public:Type last() const;The last public member function returns the last element in the vector. The element is not removedfrom the vector.If the vector is empty, one <strong>of</strong> two exceptions can be thrown. The empty_container exception isthrown if it is enabled. Otherwise, if the index_range exception is enabled, it is thrown. If neitherexception is enabled, a first element <strong>of</strong> the vector is added with a default value.Results:See Also:The last public member function returns the value <strong>of</strong> the last element in the vector.first, removeLast, WCExcept::index_range, WCExcept::resize_required586 Vector Containers
WCValSortedVector,WCValOrderedVector::occurrencesOf()Synopsis:Semantics:Results:See Also:#include public:int occurrencesOf( const Type & ) const;The occurrencesOf public member function returns the number <strong>of</strong> elements contained in the vectorthat are equivalent to the passed value. A linear search is used by the WCValOrderedVector classto find the value. The WCValSortedVector class uses a binary search.The occurrencesOf public member function returns the number <strong>of</strong> elements equivalent to thepassed value.contains, find, index, operator [], removeAllVector Containers 587
WCValSortedVector,WCValOrderedVector::operator []()Synopsis:Semantics:#include public:Type & operator []( int );const Type & operator []( int ) const;operator [] is the vector index operator. A reference to the object stored in the vector at the givenindex is returned. If a constant vector is indexed, a reference to a constant element is returned.The append, insert, insertAt and prepend member functions are used to insert a newelement into a vector, and the remove, removeAll, removeAt, removeFirst andremoveLast member functions remove elements. The index operator cannot be used to change thenumber <strong>of</strong> entries in the vector. Searches may be performed using the find and index memberfunctions.If the vector is empty, one <strong>of</strong> two exceptions can be thrown. The empty_container exception isthrown if it is enabled. Otherwise, if the index_range exception is enabled, it is thrown. If neitherexception is enabled, a first element <strong>of</strong> the vector is added with a default value. This element is addedso that a reference to a valid vector element can be returned.If the index value is negative and the index_range exception is enabled, the exception is thrown.An attempt to index an element with index greater than or equal to the number <strong>of</strong> entries in the vectorwill also cause the index_range exception to be thrown if enabled. If the exception is not enabled,attempting to index a negative element will index the first element in the vector, and attempting to indexan element after the last entry will index the last element.Care must be taken when using the WCValSortedVector class not to change the ordering <strong>of</strong> thevector elements. The result returned by the index operator must not be assigned to or modified in sucha way that it is no longer equivalent (by Type’s equivalence operator) to the value inserted into thevector. Failure to comply may cause lookups to work incorrectly, since the binary search algorithmassumes elements are in sorted order.Results:See Also:The operator [] public member function returns a reference to the element at the given index. Ifthe index is invalid, a reference to the closest valid element is returned. The result <strong>of</strong> the non-constantindex operator may be assigned to.append, find, first, index, insert, insertAt, isEmpty, last, prepend, remove,removeAt, removeAll, removeFirst, removeLast, WCExcept::empty_container,WCExcept::index_range588 Vector Containers
WCValSortedVector,WCValOrderedVector::operator =()Synopsis:Semantics:#include public:WCValOrderedVector & WCValOrderedVector::operator =( constWCValOrderedVector & );WCValSortedVector & WCValSortedVector::operator =( constWCValSortedVector & );The operator = public member function is the assignment operator for the class. The left hand sidevector is first cleared using the clear member function, and then the right hand side vector is copied.The left hand side vector is made to have the same length and growth amount as the right hand side (thegrowth amount is the second argument passed to the right hand side vector constructor). All <strong>of</strong> thevector elements and exception trap states are copied.If the left hand side vector cannot be fully created, it will have zero length. The out_<strong>of</strong>_memoryexception is thrown if enabled in the right hand side vector.Results:See Also:The operator = public member function assigns the left hand side vector to be a copy <strong>of</strong> the righthand side.clear, WCExcept::out_<strong>of</strong>_memoryVector Containers 589
WCValSortedVector,WCValOrderedVector::operator ==()Synopsis:Semantics:Results:#include public:int WCValOrderedVector::operator ==( const WCValOrderedVector & )const;int WCValSortedVector::operator ==( const WCValSortedVector & )const;The operator == public member function is the equivalence operator for the class. Two vectorobjects are equivalent if they are the same object and share the same address.A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the sameobject. A FALSE (zero) value is returned otherwise.590 Vector Containers
WCValOrderedVector::prepend()Synopsis:Semantics:#include public:int prepend( const Type & );The prepend public member function inserts the passed element to be the first element in the vector.The data stored in the vector is a copy <strong>of</strong> the data passed as a parameter. All vector elements containedin the vector are copied (using Type’s assignment operator) up one index.This function is not provided by the WCValSortedVector class, since all elements must be insertedin sorted order by the insert member function.Several different results can occur if the vector is not large enough for the new element. If theresize_required exception is enabled, the exception is thrown. If the exception is not enabled,the prepend fails if the amount the vector is to be grown (the second parameter to the constructor) iszero(0). Otherwise, the vector is automatically grown by the number <strong>of</strong> elements specified to theconstructor, using the resize member function. If resize fails, the element is not inserted to thevector and the out_<strong>of</strong>_memory exception is thrown, if enabled.Results:See Also:The prepend public member function prepends an element to the WCValOrderedVector object.A TRUE (non-zero) value is returned if the insert is successful. If the insert fails, a FALSE (zero) valueis returned.append, insert, insertAt, WCExcept::out_<strong>of</strong>_memory,WCExcept::resize_requiredVector Containers 591
WCValSortedVector::remove(), WCValOrderedVector::remove()Synopsis:Semantics:#include public:int remove( const Type & );The remove public member function removes the first element in the vector which is equivalent to thepassed value. All vector elements stored after the removed elements are copied (using Type’sassignment operator) down one index.A linear search is used by the WCValOrderedVector class to find the element being removed. TheWCValSortedVector class uses a binary search.Results:See Also:The remove public member function removes the first element in the vector which is equivalent to thepassed value. A TRUE (non-zero) value is returned if an equivalent element was contained in thevector and removed. If the vector did not contain an equivalent value, a FALSE (zero) value isreturned.clear, find, removeAll, removeAt, removeFirst, removeLast592 Vector Containers
WCValSortedVector,WCValOrderedVector::removeAll()Synopsis:Semantics:#include public:unsigned removeAll( const Type & );The removeAll public member function removes all elements in the vector which are equivalent tothe passed value. All vector elements stored after the removed elements are copied (using Type’sassignment operator) down one or more indexes to take the place <strong>of</strong> the removed elements.A linear search is used by the WCValOrderedVector class to find the elements being removed. TheWCValSortedVector class uses a binary search.Results:See Also:The removeAll public member function removes all elements in the vector which are equivalent tothe passed value. The number <strong>of</strong> elements removed is returned.clear, find, occurrencesOf, remove, removeAt, removeFirst, removeLastVector Containers 593
WCValSortedVector,WCValOrderedVector::removeAt()Synopsis:Semantics:#include public:int removeAt( int );The removeAt public member function removes the element at the given index. All vector elementsstored after the removed elements are copied (using Type’s assignment operator) down one index.If the vector is empty and the empty_container exception is enabled, the exception is thrown.If an attempt to remove an element with a negative index is made and the index_range exception isenabled, the exception is thrown. If the exception is not enabled, the first element is removed from thevector. Attempting to remove an element with index greater or equal to the number <strong>of</strong> entries in thevector also causes the index_range exception to be thrown if enabled. The last element in the vectoris removed if the exception is not enabled.Results:See Also:The removeAt public member function removes the element with the given index. If the index isinvalid, the closest element to the given index is removed. A TRUE (non-zero) value is returned if anelement was removed. If the vector was empty, FALSE (zero) value is returned.clear, insertAt, operator [], remove, removeAll, removeFirst, removeLast594 Vector Containers
WCValSortedVector,WCValOrderedVector::removeFirst()Synopsis:Semantics:#include public:int removeFirst();The removeFirst public member function removes the first element from a vector. All other vectorelements are copied (using Type’s assignment operator) down one index.If the vector is empty and the empty_container exception is enabled, the exception is thrown.Results:See Also:The removeFirst public member function removes the first element from the vector. A TRUE(non-zero) value is returned if an element was removed. If the vector was empty, FALSE (zero) valueis returned.clear, first, remove, removeAt, removeAll, removeLastVector Containers 595
WCValSortedVector,WCValOrderedVector::removeLast()Synopsis:Semantics:Results:See Also:#include public:int removeLast();The removeLast public member function removes the last element from a vector. If the vector isempty and the empty_container exception is enabled, the exception is thrown.The removeLast public member function removes the last element from the vector. A TRUE(non-zero) value is returned if an element was removed. If the vector was empty, FALSE (zero) valueis returned.clear, last, remove, removeAt, removeAll, removeFirst596 Vector Containers
WCValSortedVector::resize(), WCValOrderedVector::resize()Synopsis:Semantics:#include public:int resize( size_t new_size );The resize public member function is used to change the vector size to be able to store new_sizeelements. If new_size is larger than the previous vector size, all elements are copied (using Type’scopy constructor) into the newly sized vector, and new elements can be added using the append,insert, insertAt, and prepend member functions. If the vector is resized to a smaller size,the first new_size elements are copied (all vector elements if the vector contained new_size or fewerelements). The remaining elements are destroyed using Type’s destructor.If the resize cannot be performed and the out_<strong>of</strong>_memory exception is enabled, the exception isthrown.Results:See Also:The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. AFALSE (zero) result is returned if the resize fails.WCExcept::out_<strong>of</strong>_memoryVector Containers 597
WCValVectorDeclared:wcvector.hThe WCValVector class is a templated class used to store objects in a vector. Vectors aresimilar to arrays, but vectors perform bounds checking and can be resized. Elements are inserted intothe vector by assigning to a vector index.The WCValOrderedVector and WCValSortedVector classes are also available. They provide amore abstract view <strong>of</strong> the vector and additional functionality, including finding and removing elements.Values are copied into the vector, which could be undesirable if the stored objects are complicated andcopying is expensive. Value vectors should not be used to store objects <strong>of</strong> a base class if any derivedtypes <strong>of</strong> different sizes would be stored in the vector, or if the destructor for a derived class must becalled.In the description <strong>of</strong> each member function, the text Type is used to indicate the template parameterdefining the type <strong>of</strong> the elements stored in the vector.The WCExcept class is a base class <strong>of</strong> the WCValVector class and provides theexceptions member function. This member function controls the exceptions which can be thrownby the WCValVector object. No exceptions are enabled unless they are set by theexceptions member function.Requirements <strong>of</strong> TypeThe WCValVector class requires Type to have:A default constructor ( Type::Type() ).A well defined copy constructor ( Type::Type( const Type & ) ).The following override <strong>of</strong> operator new() only if Type overrides the global operatornew():void * operator new( size_t, void *ptr ) { return( ptr ); }Public Member FunctionsThe following member functions are declared in the public interface:WCValVector( size_t = 0 );WCValVector( size_t, const Type & );WCValVector( const WCValVector & );virtual ~WCValVector();void clear();size_t length() const;int resize( size_t );Public Member OperatorsThe following member operators are declared in the public interface:Type & operator []( int );const Type & operator []( int ) const;WCValVector & operator =( const WCValVector & );int operator ==( const WCValVector & ) const;598 Vector Containers
WCValVector::WCValVector()Synopsis:Semantics:#include public:WCValVector( size_t = 0 );The public WCValVector constructor creates a WCValVector object able to storethe number <strong>of</strong> elements specified in the optional parameter, which defaults to zero. All vector elementsare initialized with Type’s default constructor.If the vector object cannot be fully initialized, the vector is created with length zero.Results:See Also:The public WCValVector constructor creates an initialized WCValVector objectwith the specified length.WCValVector, ~WCValVectorVector Containers 599
WCValVector::WCValVector()Synopsis:Semantics:#include public:WCValVector( size_t, const Type & );The public WCValVector constructor creates a WCValVector object able to storethe number <strong>of</strong> elements specified by the first parameter. All vector elements are initialized to the value<strong>of</strong> the second parameter using Type’s copy constructor.If the vector object cannot be fully initialized, the vector is created with length zero.Results:See Also:The public WCValVector constructor creates an initialized WCValVector objectwith the specified length and elements set to the given value.WCValVector, ~WCValVector600 Vector Containers
WCValVector::WCValVector()Synopsis:Semantics:#include public:WCValVector( const WCValVector & );The public WCValVector constructor is the copy constructor for theWCValVector class. The new vector is created with the same length as the given vector. All<strong>of</strong> the vector elements and exception trap states are copied.If the new vector cannot be fully created, it will have length zero. The out_<strong>of</strong>_memory exception isthrown if enabled in the vector being copied.Results:See Also:The public WCValVector constructor creates a WCValVector object which is acopy <strong>of</strong> the passed vector.operator =, WCExcept::out_<strong>of</strong>_memoryVector Containers 601
WCValVector::~WCValVector()Synopsis:Semantics:Results:See Also:#include public:virtual ~WCValVector();The public ~WCValVector destructor is the destructor for the WCValVectorclass. If the vector is not length zero and the not_empty exception is enabled, the exception isthrown. Otherwise, the vector elements are cleared using the clear member function. The call to thepublic ~WCValVector destructor is inserted implicitly by the compiler at the point where theWCValVector object goes out <strong>of</strong> scope.The public ~WCValVector destructor destroys an WCValVector object.clear, WCExcept::not_empty602 Vector Containers
WCValVector::clear()Synopsis:Semantics:Results:#include public:void clear();The clear public member function is used to clear the vector so that it is <strong>of</strong> zero length. Elementsstored in the vector are destroyed using Type’s destructor. The vector object is not destroyed andre-created by this function, so the object destructor is not invoked.The clear public member function clears the vector to have zero length and no vector elements.See Also: ~WCValVector, operator =Vector Containers 603
WCValVector::length()Synopsis:Semantics:Results:See Also:#include public:size_t length() const;The length public member function is used to find the number <strong>of</strong> elements which can be stored in theWCValVector object.The length public member function returns the length <strong>of</strong> the vector.resize604 Vector Containers
WCValVector::operator []()Synopsis:Semantics:#include public:Type & operator []( int );const Type & operator []( int ) const;operator [] is the vector index operator. A reference to the object stored in the vector at the givenindex is returned. If a constant vector is indexed, a reference to a constant element is returned. Theindex operator <strong>of</strong> a non-constant vector is the only way to insert an element into the vector.If an attempt to access an element with index greater than or equal to the length <strong>of</strong> a non-constant vectoris made and the resize_required exception is enabled, the exception is thrown. If the exception isnot enabled, the vector is automatically resized using the resize member function to have length theindex value plus one. New vector elements are initialized using Type’s default constructor. If theresize failed, and the out_<strong>of</strong>_memory exception is enabled, the exception is thrown. If the exceptionis not enabled and the resize failed, the last element is indexed (a new element if the vector was zerolength). If a negative value is used to index the non-constant vector and the index_range exceptionis enabled, the exception is thrown. If the exception is not enabled and the vector is empty, theresize_required exception may be thrown.An attempt to index an empty constant vector may cause one <strong>of</strong> two exceptions to be thrown. If theempty_container exception is enabled, it is thrown. Otherwise, the index_range exception isthrown, if enabled. If neither exception is enabled, a first vector element is added and indexed (so that areference to a valid element can be returned).Indexing with a negative value or a value greater than or equal to the length <strong>of</strong> a constant vector causesthe index_range exception to be thrown, if enabled.Results:See Also:The operator [] public member function returns a reference to the element at the given index. Ifthe index is invalid, a reference to the closest valid element is returned. The result <strong>of</strong> the non-constantindex operator may be assigned to.resize, WCExcept::empty_container, WCExcept::index_range,WCExcept::out_<strong>of</strong>_memory, WCExcept::resize_requiredVector Containers 605
WCValVector::operator =()Synopsis:Semantics:#include public:WCValVector & operator =( const WCValVector & );The operator = public member function is the assignment operator for the WCValVectorclass. The left hand side vector is first cleared using the clear member function, and then the righthand side vector is copied. The left hand side vector is made to have the same length as the right handside. All <strong>of</strong> the vector elements and exception trap states are copied.If the left hand side vector cannot be fully created, it will have zero length. The out_<strong>of</strong>_memoryexception is thrown if enabled in the right hand side vector.Results:See Also:The operator = public member function assigns the left hand side vector to be a copy <strong>of</strong> the righthand side.clear, WCExcept::out_<strong>of</strong>_memory606 Vector Containers
WCValVector::operator ==()Synopsis:Semantics:Results:#include public:int operator ==( const WCValVector & ) const;The operator == public member function is the equivalence operator for theWCValVector class. Two vector objects are equivalent if they are the same object and sharethe same address.A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the sameobject. A FALSE (zero) value is returned otherwise.Vector Containers 607
WCValVector::resize()Synopsis:Semantics:#include public:int resize( size_t new_size );The resize public member function is used to change the vector size to be able to store new_sizeelements. If new_size is larger than the previous vector size, all elements will be copied (usingType’s copy constructor) into the newly sized vector, and new elements are initialized with Type’sdefault constructor. If the vector is resized to a smaller size, the first new_size elements are copied. Theremaining elements are destroyed using Type’s destructor.If the resize cannot be performed and the out_<strong>of</strong>_memory exception is enabled, the exception isthrown.Results:See Also:The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. AFALSE (zero) result is returned if the resize fails.WCExcept::out_<strong>of</strong>_memory608 Vector Containers
18 Input/Output ClassesThe input/output stream classes provide program access to the file system. In addition, various options forformatting <strong>of</strong> output and reading <strong>of</strong> input are provided.Input/Output Classes 609
filebufDeclared:fstream.hDerived from: streambufThe filebuf class is derived from the streambuf class, and provides additional functionalityrequired to communicate with external files. Seek operations are supported when the underlying filesupports seeking. Both input and output operations may be performed using a filebuf object, againwhen the underlying file supports read/write access.filebuf objects are buffered by default, so the reserve area is allocated automatically unless one isspecified when the filebuf object is created. The get area and put area pointers operate as if theywere tied together. There is only one current position in a filebuf object.The filebuf class allows only the get area or the put area, but not both, to be active at a time. Thisfollows from the capability <strong>of</strong> files opened for both reading and writing to have operations <strong>of</strong> each typeperformed at arbitrary locations in the file. When writing is occurring, the characters are buffered in theput area. If a seek or read operation is done, the put area must be flushed before the next operation inorder to ensure that the characters are written to the proper location in the file. Similarly, if reading isoccurring, characters are buffered in the get area. If a write operation is done, the get area must beflushed and synchronized before the write operation in order to ensure the write occurs at the properlocation in the file. If a seek operation is done, the get area does not have to be synchronized, but isdiscarded. When the get area is empty and a read is done, the underflow virtual member functionreads more characters and fills the get area again. When the put area is full and a write is done, theoverflow virtual member function writes the characters and makes the put area empty again.C++ programmers who wish to use files without deriving new objects do not need to explicitly create oruse a filebuf object.Public Data MembersThe following data member is declared in the public interface. Its value is the default file protectionthat is used when creating new files. It is primarily referenced as a default argument in memberfunctions.static int const openprot;Public Member FunctionsThe following member functions are declared in the public interface:filebuf();filebuf( filedesc );filebuf( filedesc, char *, int );~filebuf();int is_open() const;filedesc fd() const;filebuf *attach( filedesc );filebuf *open( char const *,ios::openmode,int = filebuf::openprot );filebuf *close();virtual int pbackfail( int );virtual int overflow( int = EOF );virtual int underflow();virtual streambuf *setbuf( char *, int );610 Input/Output Classes
filebufvirtual streampos seek<strong>of</strong>f( stream<strong>of</strong>f,ios::seekdir,ios::openmode );virtual int sync();See Also:fstreambase, streambufInput/Output Classes 611
filebuf::attach()Synopsis:Semantics:Results:See Also:#include public:filebuf *filebuf::attach( filedesc hdl );The attach public member function connects an existing filebuf object to an open file via thefile’s descriptor or handle specified by hdl. If the filebuf object is already connected to a file, theattach public member function fails. Otherwise, the attach public member function extractsinformation from the file system to determine the capabilities <strong>of</strong> the file and hence the filebufobject.The attach public member function returns a pointer to the filebuf object on success, otherwiseNULL is returned.filebuf, fd, open612 Input/Output Classes
filebuf::close()Synopsis:Semantics:Results:See Also:#include public:filebuf *filebuf::close();The close public member function disconnects the filebuf object from a connected file and closesthe file. Any buffered output is flushed before the file is closed.The close public member function returns a pointer to the filebuf object on success, otherwiseNULL is returned.filebuf, fd, is_openInput/Output Classes 613
filebuf::fd()Synopsis:Semantics:Results:See Also:#include public:filedesc filebuf::fd() const;The fd public member function queries the state <strong>of</strong> the filebuf object file handle.The fd public member function returns the file descriptor or handle <strong>of</strong> the file to which the filebufobject is currently connected. If the filebuf object is not currently connected to a file, EOF isreturned.filebuf::attach, is_open614 Input/Output Classes
filebuf::filebuf()Synopsis:Semantics:Results:See Also:#include public:filebuf::filebuf();This form <strong>of</strong> the public filebuf constructor creates a filebuf object that is not currently connectedto any file. A call to the fd member function for this created filebuf object returns EOF, unless afile is connected using the attach member function.The public filebuf constructor produces a filebuf object that is not currently connected to anyfile.~filebuf, attach, openInput/Output Classes 615
filebuf::filebuf()Synopsis:Semantics:#include public:filebuf::filebuf( filedesc hdl );This form <strong>of</strong> the public filebuf constructor creates a filebuf object that is connected to an openfile. The file is specified via the hdl parameter, which is a file descriptor or handle.This form <strong>of</strong> the public filebuf constructor is similar to using the default constructor, and calling theattach member function. A call to the fd member function for this created filebuf object returnshdl.Results:See Also:The public filebuf constructor produces a filebuf object that is connected to hdl.~filebuf, attach, open616 Input/Output Classes
filebuf::filebuf()Synopsis:Semantics:#include public:filebuf::filebuf( filedesc hdl, char *buf, int len );This form <strong>of</strong> the public filebuf constructor creates a filebuf object that is connected to an openfile and that uses the buffer specified by buf and len. The file is specified via the hdl parameter, whichis a file descriptor or handle. If buf is NULL and/or len is less than or equal to zero, the filebufobject is unbuffered, so that reading and/or writing take place one character at a time.This form <strong>of</strong> the public filebuf constructor is similar to using the default constructor, and calling theattach and setbuf member functions.Results:See Also:The public filebuf constructor constructor produces a filebuf object that is connected to hdl.~filebuf, attach, open, setbufInput/Output Classes 617
filebuf::~filebuf()Synopsis:Semantics:Results:See Also:#include public:filebuf::~filebuf();The public ~filebuf destructor closes the file if it was explicitly opened using the open memberfunction. Otherwise, the destructor takes no explicit action. The streambuf destructor is called todestroy that portion <strong>of</strong> the filebuf object. The call to the public ~filebuf destructor is insertedimplicitly by the compiler at the point where the filebuf object goes out <strong>of</strong> scope.The filebuf object is destroyed.~filebuf, close618 Input/Output Classes
filebuf::is_open()Synopsis:Semantics:Results:See Also:#include public:int filebuf::is_open();The is_open public member function queries the filebuf object state.The is_open public member function returns a non-zero value if the filebuf object is currentlyconnected to a file. Otherwise, zero is returned.filebuf::attach, close, fd, openInput/Output Classes 619
filebuf::open()Synopsis:Semantics:Results:See Also:#include public:filebuf *filebuf::open( const char *name,ios::openmode mode,int prot = filebuf::openprot );The open public member function is used to connect the filebuf object to a file specified by thename parameter. The file is opened using the specified mode. For details about the mode parameter,see the description <strong>of</strong> ios::openmode. The prot parameter specifies the file protection attributes touse when creating a file.The open public member function returns a pointer to the filebuf object on success, otherwiseNULL is returned.filebuf, close, is_open, openprot620 Input/Output Classes
filebuf::openprotSynopsis:Semantics:#include public:static int const filebuf::openprot;The openprot public member data is used to specify the default file protection to be used whencreating new files. This value is used as the default if no user specified value is provided.The default value is octal 0644. This is generally interpreted as follows:• Owner: read/write• Group: read• World: readNote that not all operating systems support all bits.See Also:filebuf, openInput/Output Classes 621
filebuf::overflow()Synopsis:Semantics:#include public:virtual int filebuf::overflow( int ch = EOF );The overflow public virtual member function provides the output communication to the file to whichthe filebuf object is connected. Member functions in the streambuf class call the overflowpublic virtual member function for the derived class when the put area is full.The overflow public virtual member function performs the following steps:1. If no buffer is present, a buffer is allocated with the streambuf::allocate memberfunction, which may call the doallocate virtual member function. The put area is thenset up. If, after calling streambuf::allocate, no buffer is present, the filebufobject is unbuffered and ch (if not EOF) is written directly to the file without buffering, andno further action is taken.2. If the get area is present, it is flushed with a call to the sync virtual member function. Notethat the get area won’t be present if a buffer was set up in step 1.3. If ch is not EOF, it is added to the put area, if possible.4. Any characters in the put area are written to the file.5. The put area pointers are updated to reflect the new state <strong>of</strong> the put area. If the write did notcomplete, the unwritten portion <strong>of</strong> the put area is still present. If the put area was full beforethe write, ch (if not EOF) is placed at the start <strong>of</strong> the put area. Otherwise, the put area isempty.Results:See Also:The overflow public virtual member function returns __NOT_EOF on success, otherwiseEOF isreturned.streambuf::overflowfilebuf::underflow622 Input/Output Classes
filebuf::pbackfail()Synopsis:Semantics:Results:See Also:#include public:virtual int filebuf::pbackfail( int ch );The pbackfail public virtual member function handles an attempt to put back a character when thereis no room at the beginning <strong>of</strong> the get area. The pbackfail public virtual member function first callsthe sync virtual member function to flush the put area and then it attempts to seek backwards over chin the associated file.The pbackfail public virtual member function returns ch on success, otherwise EOF is returned.streambuf::pbackfailInput/Output Classes 623
filebuf::seek<strong>of</strong>f()Synopsis:Semantics:#include public:virtual streampos filebuf::seek<strong>of</strong>f( stream<strong>of</strong>f <strong>of</strong>fset,ios::seekdir dir,ios::openmode mode );The seek<strong>of</strong>f public virtual member function is used to position the filebuf object (and hence thefile) to a particular <strong>of</strong>fset so that subsequent input or output operations commence from that point. The<strong>of</strong>fset is specified by the <strong>of</strong>fset and dir parameters.Since the get area and put area pointers are tied together for the filebuf object, the mode parameteris ignored.Before the actual seek occurs, the get area and put area <strong>of</strong> the filebuf object are flushed via thesync virtual member function. Then, the new position in the file is calculated and the seek takes place.The dir parameter may be ios::beg, ios::cur, or ios::end and is interpreted in conjunctionwith the <strong>of</strong>fset parameter as follows:ios::beg the <strong>of</strong>fset is relative to the start and should be a positive value.ios::cur the <strong>of</strong>fset is relative to the current position and may be positive(seek towards end) or negative (seek towards start).ios::end the <strong>of</strong>fset is relative to the end and should be a negative value.If the dir parameter has any other value, or the <strong>of</strong>fset parameter does not have an appropriate sign, theseek<strong>of</strong>f public virtual member function fails.Results:See Also:The seek<strong>of</strong>f public virtual member function returns the new position in the file on success, otherwiseEOF is returned.streambuf::seek<strong>of</strong>f624 Input/Output Classes
filebuf::setbuf()Synopsis:Semantics:#include public:virtual streambuf *filebuf::setbuf( char *buf, int len );The setbuf public virtual member function is used to <strong>of</strong>fer a buffer, specified by buf and len to thefilebuf object. If the buf parameter is NULL or the len is less than or equal to zero, the request is tomake the filebuf object unbuffered.If the filebuf object is already connected to a file and has a buffer, the <strong>of</strong>fer is rejected. In otherwords, a call to the setbuf public virtual member function after the filebuf object has started to beused usually fails because the filebuf object has set up a buffer.If the request is to make the filebuf object unbuffered, the <strong>of</strong>fer succeeds.If the buf is too small (less than five characters), the <strong>of</strong>fer is rejected. Five characters are required tosupport the default putback area.Otherwise, the buf is acceptable and the <strong>of</strong>fer succeeds.If the <strong>of</strong>fer succeeds, the streambuf::setb member function is called to set up the pointers to thebuffer. The streambuf::setb member function releases the old buffer (if present), depending onhow that buffer was allocated.Calls to the setbuf public virtual member function are usually made by a class derived from thefstream class, not directly by a user program.Results:See Also:The setbuf public virtual member function returns a pointer to the filebuf object on success,otherwise NULL is returned.streambuf::setbufInput/Output Classes 625
filebuf::sync()Synopsis:Semantics:#include public:virtual int filebuf::sync();The sync public virtual member function synchronizes the filebuf object with the external file ordevice. If the put area contains characters it is flushed. This leaves the file positioned after the lastwritten character. If the get area contains buffered (unread) characters, file is backed up to bepositioned after the last read character.Note that the get area and put area never both contain characters.Results:See Also:The sync public virtual member function returns __NOT_EOF on success, otherwiseEOF is returned.streambuf::sync626 Input/Output Classes
filebuf::underflow()Synopsis:Semantics:#include public:virtual int filebuf::underflow();The underflow public virtual member function provides the input communication from the file towhich the filebuf object is connected. Member functions in the streambuf class call theunderflow public virtual member function for the derived class when the get area is empty.The underflow public virtual member function performs the following steps:1. If no reserve area is present, a buffer is allocated with the streambuf::allocatemember function, which may call the doallocate virtual member function. If, aftercalling allocate, no reserve area is present, the filebuf object is unbuffered and aone-character reserve area (plus putback area) is set up to do unbuffered input. This buffer isembedded in the filebuf object. The get area is set up as empty.2. If the put area is present, it is flushed using the sync virtual member function.3. The unused part <strong>of</strong> the get area is used to read characters from the file connected to thefilebuf object. The get area pointers are then set up to reflect the new get area.Results:See Also:The underflow public virtual member function returns the first unread character <strong>of</strong> the get area, onsuccess, otherwise EOF is returned. Note that the get pointer is not advanced on success.streambuf::underflowfilebuf::overflowInput/Output Classes 627
fstreamDeclared:fstream.hDerived from: fstreambase, iostreamThe fstream class is used to access files for reading and writing. The file can be opened and closed,and read, write and seek operations can be performed.The fstream class provides very little <strong>of</strong> its own functionality. It is derived from both thefstreambase and iostream classes. The fstream constructors, destructor and member functionprovide simplified access to the appropriate equivalents in the base classes.Of the available I/O stream classes, creating an fstream object is the preferred method <strong>of</strong> accessing afile for both input and output.Public Member FunctionsThe following public member functions are declared:fstream();fstream( char const *,ios::openmode = ios::in|ios::out,int = filebuf::openprot );fstream( filedesc );fstream( filedesc, char *, int );~fstream();void open( char const *,ios::openmode = ios::in|ios::out,int = filebuf::openprot );See Also:fstreambase, ifstream, iostream, <strong>of</strong>stream628 Input/Output Classes
fstream::fstream()Synopsis:Semantics:Results:See Also:#include public:fstream::fstream();This form <strong>of</strong> the public fstream constructor creates an fstream object that is not connected to afile. The open or attach member functions should be used to connect the fstream object to a file.The public fstream constructor produces an fstream object that is not connected to a file.~fstream, open, fstreambase::attachInput/Output Classes 629
fstream::fstream()Synopsis:Semantics:Results:See Also:#include public:fstream::fstream( const char *name,ios::openmode mode = ios::in|ios::out,int prot = filebuf::openprot );This form <strong>of</strong> the public fstream constructor creates an fstream object that is connected to the filespecified by the name parameter, using the specified mode and prot parameters. The connection ismade via the C library open function.The public fstream constructor produces an fstream object that is connected to the file specifiedby name. If the open fails, ios::failbit and ios::badbit are set in the error state in theinherited ios object.~fstream, open, openmode, openprot630 Input/Output Classes
fstream::fstream()Synopsis:Semantics:Results:See Also:#include public:fstream::fstream( filedesc hdl );This form <strong>of</strong> the public fstream constructor creates an fstream object that is attached to the filespecified by the hdl parameter.The public fstream constructor produces an fstream object that is attached to hdl. If the attachfails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.~fstream, fstreambase::attach, fstreambase::fdInput/Output Classes 631
fstream::fstream()Synopsis:Semantics:Results:See Also:#include public:fstream::fstream( filedesc hdl, char *buf, int len );This form <strong>of</strong> the public fstream constructor creates an fstream object that is connected to the filespecified by the hdl parameter. The buffer specified by the buf and len parameters is <strong>of</strong>fered to theassociated filebuf object via the setbuf member function. If the buf parameter is NULL or the lenis less than or equal to zero, the filebuf is unbuffered, so that each read or write operation reads orwrites a single character at a time.The public fstream constructor produces an fstream object that is attached to hdl. If theconnection to hdl fails, ios::failbit and ios::badbit are set in the error state in the inheritedios object. If the setbuf fails, ios::failbit is set in the error state in the inherited ios object.~fstream, filebuf::setbuf, fstreambase::attach632 Input/Output Classes
fstream::~fstream()Synopsis:Semantics:Results:See Also:#include public:fstream::~fstream();The public ~fstream destructor does not do anything explicit. The call to the public ~fstreamdestructor is inserted implicitly by the compiler at the point where the fstream object goes out <strong>of</strong>scope.The public ~fstream destructor destroys the fstream object.fstreamInput/Output Classes 633
fstream::open()Synopsis:Semantics:Results:See Also:#include public:void fstream::open( const char *name,ios::openmode mode = ios::in|ios::out,int prot = filebuf::openprot );The open public member function connects the fstream object to the file specified by the nameparameter, using the specified mode and prot parameters. The mode parameter is optional and usuallyis not specified unless additional bits (such as ios::binary or ios::text) are to be specified.The connection is made via the C library open function.If the open fails, ios::failbit is set in the error state in the inherited ios object.fstreambase::attach, fstreambase::close, fstreambase::fd,fstreambase::is_openfstream::openmode, openprot634 Input/Output Classes
fstreambaseDeclared:fstream.hDerived from: iosDerived by:ifstream, <strong>of</strong>stream, fstreamThe fstreambase class is a base class that provides common functionality for the three file-basedclasses, ifstream, <strong>of</strong>stream and fstream. The fstreambase class is derived from the iosclass, providing the stream state information, plus it provides member functions for opening and closingfiles. The actual file manipulation work is performed by the filebuf class.It is not intended that fstreambase objects be created. Instead, the user should create anifstream, <strong>of</strong>stream or fstream object.Protected Member FunctionsThe following member functions are declared in the protected interface:fstreambase();fstreambase( char const *,ios::openmode,int = filebuf::openprot );fstreambase( filedesc );fstreambase( filedesc, char *, int );~fstreambase();Public Member FunctionsThe following member functions are declared in the public interface:void attach( filedesc );void close();filedesc fd() const;int is_open() const;void open( char const *,ios::openmode,int = filebuf::openprot );filebuf *rdbuf() const;void setbuf( char *, int );See Also:filebuf, fstream, ifstream, <strong>of</strong>streamInput/Output Classes 635
fstreambase::attach()Synopsis:Semantics:Results:See Also:#include public:void fstreambase::attach( filedesc hdl );The attach public member function connects the fstreambase object to the file specified by thehdl parameter.If the attach public member function fails, ios::failbit bit is set in the error state in theinherited ios object. The error state in the inherited ios object is cleared on success.fstreambase::fd, is_open, open636 Input/Output Classes
fstreambase::close()Synopsis:Semantics:Results:See Also:#include public:void fstreambase::close();The close public member function disconnects the fstreambase object from the file with which itis associated. If the fstreambase object is not associated with a file, the close public memberfunction fails.If the close public member function fails, ios::failbit is set in the error state in the inheritedios object.fstreambase::fd, is_open, openInput/Output Classes 637
fstreambase::fstreambase()Synopsis:Semantics:Results:See Also:#include protected:fstreambase::fstreambase();The protected fstreambase constructor creates an fstreambase object that is initialized, but notconnected to anything. The open or attach member function should be used to connect thefstreambase object to a file.The protected fstreambase constructor produces an fstreambase object.~fstreambase, attach, open638 Input/Output Classes
fstreambase::fstreambase()Synopsis:Semantics:Results:See Also:#include protected:fstreambase::fstreambase( char const *name,ios::openmode mode,int prot = filebuf::openprot );This protected fstreambase constructor creates an fstreambase object that is initialized andconnected to the file indicated by name using the specified mode and prot. The fstreambase objectis connected to the specified file via the open C library function.The protected fstreambase constructor produces an fstreambase object. If the call to open forthe file fails, ios::failbit and ios::badbit are set in the error state in the inherited iosobject.~fstreambase, open, openmode, openprotInput/Output Classes 639
fstreambase::fstreambase()Synopsis:Semantics:Results:See Also:#include protected:fstreambase::fstreambase( filedesc hdl );This protected fstreambase constructor creates an fstreambase object that is initialized andconnected to the open file specified by the hdl parameter.The protected fstreambase constructor produces an fstreambase object. If the attach to the filefails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.~fstreambase, attach640 Input/Output Classes
fstreambase::fstreambase()Synopsis:Semantics:Results:See Also:#include protected:fstreambase::fstreambase( filedesc hdl, char *buf, int len );This protected fstreambase constructor creates an fstreambase object that is initialized andconnected to the open file specified by the hdl parameter. The buffer, specified by the buf and lenparameters, is <strong>of</strong>fered via the setbuf virtual member function to be used as the reserve area for thefilebuf associated with the fstreambase object.The protected fstreambase constructor produces an fstreambase object. If the attach to the filefails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.~fstreambase, attach, setbufInput/Output Classes 641
fstreambase::~fstreambase()Synopsis:Semantics:Results:See Also:#include protected:fstreambase::~fstreambase();The protected ~fstreambase destructor does not do anything explicit. The filebuf objectassociated with the fstreambase object is embedded within the fstreambase object, so thefilebuf destructor is called. The ios destructor is called for that portion <strong>of</strong> the fstreambaseobject. The call to the protected ~fstreambase destructor is inserted implicitly by the compiler atthe point where the fstreambase object goes out <strong>of</strong> scope.The fstreambase object is destroyed.fstreambase, close642 Input/Output Classes
fstreambase::is_open()Synopsis:Semantics:Results:See Also:#include public:int fstreambase::is_open() const;The is_open public member function queries the current state <strong>of</strong> the file associated with thefstreambase object. Calling the is_open public member function is equivalent to calling the fdmember function and testing for EOF.The is_open public member function returns a non-zero value if the fstreambase object iscurrently connected to a file, otherwise zero is returned.fstreambase::attach, fd, openInput/Output Classes 643
fstreambase::fd()Synopsis:Semantics:Results:See Also:#include public:filedesc fstreambase::fd() const;The fd public member function returns the file descriptor for the file to which the fstreambaseobject is connected.The fd public member function returns the file descriptor for the file to which the fstreambaseobject is connected. If the fstreambase object is not currently connected to a file, EOF is returned.fstreambase::attach, is_open, open644 Input/Output Classes
fstreambase::open()Synopsis:Semantics:Results:See Also:#include public:void fstreambase::open( const char *name,ios::openmode mode,int prot = filebuf::openprot );The open public member function connects the fstreambase object to the file specified by name,using the specified mode and prot. The connection is made via the C library open function.If the open fails, ios::failbit is set in the error state in the inherited ios object. The error state inthe inherited ios object is cleared on success.fstreambase::attach, close, fd, is_open, openmode, openprotInput/Output Classes 645
fstreambase::rdbuf()Synopsis:Semantics:Results:See Also:#include public:filebuf *fstreambase::rdbuf() const;The rdbuf public member function returns the address <strong>of</strong> the filebuf object currently associatedwith the fstreambase object.The rdbuf public member function returns a pointer to the filebuf object currently associated withthe fstreambase object If there is no associated filebuf, NULL is returned.ios::rdbuf646 Input/Output Classes
fstreambase::setbuf()Synopsis:Semantics:Results:See Also:#include public:void fstreambase::setbuf( char *buf, int len );The setbuf public member function <strong>of</strong>fers the specified buffer to the filebuf object associatedwith the fstreambase object. The filebuf may or may not reject the <strong>of</strong>fer, depending upon itsstate.If the <strong>of</strong>fer is rejected, ios::failbit is set in the error state in the inherited ios object.filebuf::setbufInput/Output Classes 647
ifstreamDeclared:fstream.hDerived from: fstreambase, istreamThe ifstream class is used to access existing files for reading. Such files can be opened and closed,and read and seek operations can be performed.The ifstream class provides very little <strong>of</strong> its own functionality. Derived from both thefstreambase and istream classes, its constructors, destructor and member functions providesimplified access to the appropriate equivalents in those base classes.Of the available I/O stream classes, creating an ifstream object is the preferred method <strong>of</strong> accessinga file for input only operations.Public Member FunctionsThe following public member functions are declared:ifstream();ifstream( char const *,ios::openmode = ios::in,int = filebuf::openprot );ifstream( filedesc );ifstream( filedesc, char *, int );~ifstream();void open( char const *,ios::openmode = ios::in,int = filebuf::openprot );See Also:fstream, fstreambase, istream, <strong>of</strong>stream648 Input/Output Classes
ifstream::ifstream()Synopsis:Semantics:Results:See Also:#include public:ifstream::ifstream();This form <strong>of</strong> the public ifstream constructor creates an ifstream object that is not connected to afile. The open or attach member functions should be used to connect the ifstream object to afile.The public ifstream constructor produces an ifstream object that is not connected to a file.~ifstream, open, fstreambase::attachInput/Output Classes 649
ifstream::ifstream()Synopsis:Semantics:Results:See Also:#include public:ifstream::ifstream( const char *name,ios::openmode mode = ios::in,int prot = filebuf::openprot );This form <strong>of</strong> the public ifstream constructor creates an ifstream object that is connected to thefile specified by the name parameter, using the specified mode and prot parameters. The connection ismade via the C library open function.The public ifstream constructor produces an ifstream object that is connected to the filespecified by name. If the open fails, ios::failbit and ios::badbit are set in the error state inthe inherited ios object.~ifstream, open, openmode, openprot, fstreambase::attach, fstreambase::fd,fstreambase::is_open650 Input/Output Classes
ifstream::ifstream()Synopsis:Semantics:Results:See Also:#include public:ifstream::ifstream( filedesc hdl );This form <strong>of</strong> the public ifstream constructor creates an ifstream object that is attached to the filespecified by the hdl parameter.The public ifstream constructor produces an ifstream object that is attached to hdl. If the attachfails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.fstreambase::attach~ifstream, openInput/Output Classes 651
ifstream::ifstream()Synopsis:Semantics:Results:See Also:#include public:ifstream::ifstream( filedesc hdl, char *buf, int len );This form <strong>of</strong> the public ifstream constructor creates an ifstream object that is connected to thefile specified by the hdl parameter. The buffer specified by the buf and len parameters is <strong>of</strong>fered to theassociated filebuf object via the setbuf member function. If the buf parameter is NULL or the lenis less than or equal to zero, the filebuf is unbuffered, so that each read or write operation reads orwrites a single character at a time.The public ifstream constructor produces an ifstream object that is attached to hdl. If theconnection to hdl fails, ios::failbit and ios::badbit are set in the error state in the inheritedios object. If the setbuf fails, ios::failbit is set in the error state in the inherited ios object.fstreambase::attach, fstreambase::setbuf~ifstream, open652 Input/Output Classes
ifstream::~ifstream()Synopsis:Semantics:Results:See Also:#include public:ifstream::~ifstream();The public ~ifstream destructor does not do anything explicit. The call to the public ~ifstreamdestructor is inserted implicitly by the compiler at the point where the ifstream object goes out <strong>of</strong>scope.The public ~ifstream destructor destroys the ifstream object.ifstreamInput/Output Classes 653
ifstream::open()Synopsis:Semantics:Results:See Also:#include public:void ifstream::open( const char *name,ios::openmode mode = ios::in,int prot = filebuf::openprot );The open public member function connects the ifstream object to the file specified by the nameparameter, using the specified mode and prot parameters. The mode parameter is optional and usuallyis not specified unless additional bits (such as ios::binary or ios::text) are to be specified.The connection is made via the C library open function.If the open fails, ios::failbit is set in the error state in the inherited ios object.fstreambase::attach, fstreambase::close, fstreambase::fd,fstreambase::is_openifstream::openmode, openprot654 Input/Output Classes
iosDeclared:Derived by:iostream.histream, ostreamThe ios class is used to group together common functionality needed for other derived stream classes.It is not intended that objects <strong>of</strong> type ios be created.This class maintains state information about the stream. (the ios name can be thought <strong>of</strong> as ashort-form for I/O State). Error flags, formatting flags, and values and the connection to the buffersused for the input and output are all maintained by the ios class. No information about the buffer itselfis stored in an ios object, merely the pointer to the buffer information.Protected Member FunctionsThe following member functions are declared in the protected interface:ios();void init( streambuf * );void setstate( ios::iostate );Public EnumerationsThe following enumeration typedefs are declared in the public interface:typedef int iostate;typedef long fmtflags;typedef int openmode;typedef int seekdir;Public Member FunctionsThe following member functions are declared in the public interface:ios( streambuf * );virtual ~ios();ostream *tie() const;ostream *tie( ostream * );streambuf *rdbuf() const;ios::iostate rdstate() const;ios::iostate clear( ios::iostate = 0 );int good() const;int bad() const;int fail() const;int e<strong>of</strong>() const;ios::iostate exceptions( ios::iostate );ios::iostate exceptions() const;ios::fmtflags setf( ios::fmtflags, ios::fmtflags );ios::fmtflags setf( ios::fmtflags );ios::fmtflags unsetf( ios::fmtflags );ios::fmtflags flags( ios::fmtflags );ios::fmtflags flags() const;char fill( char );char fill() const;int precision( int );int precision() const;int width( int );int width() const;Input/Output Classes 655
ioslong &iword( int );void *&pword( int );static void sync_with_stdio();static ios::fmtflags bitalloc();static int xalloc();Public Member OperatorsThe following member operators are declared in the public interface:operator void *() const;int operator !() const;See Also:iostream, istream, ostream, streambuf656 Input/Output Classes
ios::bad()Synopsis:Semantics:Results:See Also:#include public:int ios::bad() const;The bad public member function queries the state <strong>of</strong> the ios object.The bad public member function returns a non-zero value if ios::badbit is set in the error state inthe inherited ios object, otherwise zero is returned.ios::clear, e<strong>of</strong>, fail, good, iostate, operator !, operator void *, rdstate,setstateInput/Output Classes 657
ios::bitalloc()Synopsis:Semantics:#include public:static ios::fmtflags ios::bitalloc();The bitalloc public static member function is used to allocate a new ios::fmtflags bit for useby user derived classes.Because the bitalloc public static member function manipulates static member data, its behavioris not tied to any one object but affects the entire class <strong>of</strong> objects. The value that is returned by thebitalloc public static member function is valid for all objects <strong>of</strong> all classes derived from the iosclass. No subsequent call to the bitalloc public static member function will return the same value asa previous call.The bit value allocated may be used with the member functions that query and affectios::fmtflags. In particular, the bit can be set with the setf or flags member functions or thesetiosflags manipulator, and reset with the unsetf or flags member functions or theresetiosflags manipulator.There are two constants defined in which indicate the number <strong>of</strong> bits available whena program starts. _LAST_FORMAT_FLAG indicates the last bit used by the built-in format flagsdescribed by ios::fmtflags. _LAST_FLAG_BIT indicates the last bit that is available for thebitalloc public static member function to allocate. The difference between the bit positionsindicates how many bits are available.Results:See Also:The bitalloc public static member function returns the next available ios::fmtflags bit for useby user derived classes. If no more bits are available, zero is returned.ios::fmtflags658 Input/Output Classes
ios::clear()Synopsis:Semantics:Results:See Also:#include public:iostate ios::clear( ios::iostate flags = 0 );The clear public member function is used to change the current value <strong>of</strong> ios::iostate in theios object. ios::iostate is cleared, all bits specified in flags are set.The clear public member function returns the previous value <strong>of</strong> ios::iostate.ios::bad, e<strong>of</strong>, fail, good, iostate, operator !, operator void *, rdstate,setstateInput/Output Classes 659
ios::e<strong>of</strong>()Synopsis:Semantics:Results:See Also:#include public:int ios::e<strong>of</strong>() const;The e<strong>of</strong> public member function queries the state <strong>of</strong> the ios object.The e<strong>of</strong> public member function returns a non-zero value if ios::e<strong>of</strong>bit is set in the error state inthe inherited ios object, otherwise zero is returned.ios::bad, clear, fail, good, iostate, rdstate, setstate660 Input/Output Classes
ios::exceptions()Synopsis:Semantics:#include public:ios::iostate ios::exceptions() const;ios::iostate ios::exceptions( int enable );The exceptions public member function queries and/or sets the bits that control which exceptionsare enabled. ios::iostate within the ios object is used to enable and disable exceptions.When a condition arises that sets a bit in ios::iostate, a check is made to see if the same bit is alsoset in the exception bits. If so, an exception is thrown. Otherwise, no exception is thrown.The first form <strong>of</strong> the exceptions public member function looks up the current setting <strong>of</strong> theexception bits. The bit values are those described by ios::iostate.The second form <strong>of</strong> the exceptions public member function sets the exceptions bits to thosespecified in the enable parameter, and returns the current settings.Results:See Also:The exceptions public member function returns the previous setting <strong>of</strong> the exception bits.ios::clear, iostate, rdstate, setstateInput/Output Classes 661
ios::fail()Synopsis:Semantics:Results:See Also:#include public:int ios::fail() const;The fail public member function queries the state <strong>of</strong> the ios object.The fail public member function returns a non-zero value if ios::failbit or ios::badbit isset in the error state in the inherited ios object, otherwise zero is returned.ios::bad, clear, e<strong>of</strong>, good, iostate, operator !, operator void *, rdstate,setstate662 Input/Output Classes
ios::fill()Synopsis:Semantics:#include public:char ios::fill() const;char ios::fill( char fillchar );The fill public member function queries and/or sets the fill character used when the size <strong>of</strong> aformatted object is smaller than the format width specified.The first form <strong>of</strong> the fill public member function looks up the current value <strong>of</strong> the fill character.The second form <strong>of</strong> the fill public member function sets the fill character to fillchar.By default, the fill character is a space.Results:See Also:The fill public member function returns the previous value <strong>of</strong> the fill character.ios::fmtflags, manipulator setfillInput/Output Classes 663
ios::flags()Synopsis:Semantics:#include public:ios::fmtflags ios::flags() const;ios::fmtflags ios::flags( ios::fmtflags setbits );The flags public member function is used to query and/or set the value <strong>of</strong> ios::fmtflags in theios object.The first form <strong>of</strong> the flags public member function looks up the current ios::fmtflags value.The second form <strong>of</strong> the flags public member function sets ios::fmtflags to the value specifiedin the setbits parameter.Note that the setf public member function only turns bits on, while the flags public memberfunction turns some bits on and some bits <strong>of</strong>f.Results:See Also:The flags public member function returns the previous ios::fmtflags value.ios::fmtflags, setf, unsetf, manipulator dec, manipulator hex, manipulator oct,manipulator resetiosflags, manipulator setbase, manipulator setiosflags664 Input/Output Classes
ios::fmtflagsSynopsis:#include public:enum fmt_flags {skipws = 0x0001, // skip whitespaceleft = 0x0002, // align field to left edgeright = 0x0004, // align field to right edgeinternal = 0x0008, // sign at left, value at rightdec = 0x0010, // decimal conversion for integersoct = 0x0020, // octal conversion for integershex = 0x0040, // hexadecimal conversion for integersshowbase = 0x0080, // show dec/octal/hex base on outputshowpoint = 0x0100, // show decimal and digits on outputuppercase = 0x0200, // use uppercase for format charactersshowpos = 0x0400, // use + for output positive numbersscientific = 0x0800, // use scientific notation for outputfixed = 0x1000, // use floating notation for outputunitbuf = 0x2000, // flush stream after outputstdio = 0x4000, // flush stdout/stderr after outputbasefield = dec | oct | hex,adjustfield= left | right | internal,floatfield = scientific | fixed};typedef long fmtflags;Semantics:The type ios::fmt_flags is a set <strong>of</strong> bits representing methods <strong>of</strong> formatting objects written to thestream and interpreting objects read from the stream. The ios::fmtflags member typedefrepresents the same set <strong>of</strong> bits, but uses a long to represent the values, thereby avoiding problemsmade possible by the compiler’s ability to use smaller types for enumerations. All uses <strong>of</strong> these bitsshould use the ios::fmtflags member typedef.The bit values defined by the ios::fmtflags member typedef are set and read by the memberfunctions setf, unsetf and flags, as well as the manipulators setiosflags andresetiosflags.Because one field is used to store all <strong>of</strong> these bits, there are three special values used to mask variousgroups <strong>of</strong> bits. These values are named ios::basefield, ios::adjustfield andios::floatfield, and are discussed with the bits that they are used to mask.ios::skipws controls whether or not whitespace characters are automatically skipped when using anoperator >> extractor. If ios::skipws is on, any use <strong>of</strong> the operator >> extractor skipswhitespace characters before inputting the next item. Otherwise, skipping <strong>of</strong> whitespace charactersmust be handled by the program.ios::left, ios::right and ios::internal control the alignment <strong>of</strong> items written using anoperator
ios::fmtflagsportion. If ios::internal is in effect, any sign character or base indicator is written in the leftportion, the digits are written in the right portion, and fill characters are written in between.If no alignment is specified, ios::right is assumed.If the item to be written is as big as or bigger than the format width specified, no fill characters arewritten and the alignment is ignored.ios::dec, ios::oct and ios::hex control the base used to format integers being written to thestream, and also control the interpretation <strong>of</strong> integers being read from the stream.ios::basefield can be used to mask the base bits returned by the member functions setf,unsetf and flags, and for setting new values to ensure that no other bits are accidentally affected.When an integer is being read from the stream, these bits control the base used for the interpretation <strong>of</strong>the digits. If none <strong>of</strong> these bits is set, a number that starts with 0x or 0X is interpreted as hexadecimal(digits 0123456789, plus the letters abcdef or ABCDEF), a number that starts with 0 (zero) isinterpreted as octal (digits 01234567), otherwise the number is interpreted as decimal (digits0123456789). If one <strong>of</strong> the bits is set, then the prefix is not necessary and the number is interpretedaccording to the bit.When any one <strong>of</strong> the integer types is being written to the stream, it can be written in decimal, octal orhexadecimal. If none <strong>of</strong> these bits is set, ios::dec is assumed.If ios::dec is set (or assumed), the integer is written in decimal (digits 0123456789). No prefix isincluded.If ios::oct is set, the integer is written in octal (digits 01234567). No sign character is written, asthe number is treated as an unsigned quantity upon conversion to octal.If ios::hex is set, the integer is written in hexadecimal (digits 0123456789, plus the lettersabcdef or ABCDEF, depending on the setting <strong>of</strong> ios::uppercase). No sign character is written,as the number is treated as an unsigned quantity upon conversion to hexadecimal.ios::showbase controls whether or not integers written to the stream in octal or hexadecimal formhave a prefix that indicates the base <strong>of</strong> the number. If the bit is set, decimal numbers are writtenwithout a prefix, octal numbers are written with the prefix 0 (zero) and hexadecimal numbers arewritten with the prefix 0x or 0X depending on the setting <strong>of</strong> ios::uppercase. If theios::showbase is not set, no prefixes are written.ios::showpoint is used to control whether or not the decimal point and trailing zeroes are trimmedwhen floating-point numbers are written to the stream. If the bit is set, no trimming is done, causing thenumber to appear with the specified format precision. If the bit is not set, any trailing zeroes after thedecimal point are trimmed, and if not followed by any digits, the decimal point is removed as well.ios::uppercase is used to force to upper-case all letters used in formatting numbers, including theletter-digits abcdef, the x hexadecimal prefix, and the e used for the exponents in floating-pointnumbers.ios::showpos controls whether or not a + is added to the front <strong>of</strong> positive integers being written tothe stream. If the bit is set, the number is positive and the number is being written in decimal, a + iswritten before the first digit.666 Input/Output Classes
ios::fmtflagsios::scientific and ios::fixed controls the form used for writing floating-point numbers tothe stream. Floating-point numbers can be written in scientific notation (also called exponentialnotation) or in fixed-point notation.ios::floatfield can be used to mask the floating-format bits returned by the member functionssetf, unsetf and flags, and for setting new values to ensure that no other bits are accidentallyaffected.If ios::scientific is set, the floating-point number is written with a leading - sign (for negativenumbers), a digit, a decimal point, more digits, an e (or E if ios::uppercase is set), a + or - sign,and two or three digits representing the exponent. The digit before the decimal is not zero unless thenumber is zero. The total number <strong>of</strong> digits before and after the decimal is equal to the specified formatprecision. If ios::showpoint is not set, trimming <strong>of</strong> the decimal and digits following the decimalmay occur.If ios::fixed is set, the floating-point number is written with a - sign (for negative numbers), atleast one digit, the decimal point, and as many digits following the decimal as specified by the formatprecision. If ios::showpoint is not set, trimming <strong>of</strong> the decimal and digits following the decimalmay occur.If neither ios::scientific nor ios::fixed is specified, the floating-point number is formattedusing scientific notation provided one or both <strong>of</strong> the following conditions are met:• the exponent is less than -4, or,• the exponent is greater than the format precision.Otherwise, fixed-point notation is used.ios::unitbuf controls whether or not the stream is flushed after each item is written. If the bit isset, every item that is written to the stream is followed by a flush operation, which ensures that the I/Ostream buffer associated with the stream is kept empty, immediately transferring the data to its finaldestination.ios::stdio controls whether or not the stream is synchronized after each item is written. If the bit isset, every item that is written to the stream causes the stream to be synchronized, which means any inputor output buffers are flushed so that an I/O operation performed using C (not C++) I/O behaves in anunderstandable way. If the output buffer was not flushed, writing using C++ and then C I/O functionscould cause the output from the C functions to appear before the output from the C++ functions, sincethe characters might be sitting in the C++ output buffer. Similarly, after the C output operations aredone, a call should be made to the C library fflush function on the appropriate stream beforeresuming C++ output operations.See Also:ios::flags, setf, unsetf, manipulator dec, manipulator hex, manipulator oct, manipulatorresetiosflags, manipulator setbase, manipulator setiosflagsInput/Output Classes 667
ios::good()Synopsis:Semantics:Results:See Also:#include public:int ios::good() const;The good public member function queries the state <strong>of</strong> the ios object.The good public member function returns a non-zero value if none <strong>of</strong> ios::iostate is clear,otherwise zero is returned.ios::bad, clear, e<strong>of</strong>, fail, iostate, rdstate, setstate668 Input/Output Classes
ios::init()Synopsis:Semantics:#include protected:void ios::init( streambuf *sb );The init public protected member function is used by derived classes to explicitly initialize the iosportion <strong>of</strong> the derived object, and to associate a streambuf with the ios object. The init publicprotected member function performs the following steps:1. The default fill character is set to a space.2. The format precision is set to six.3. The streambuf pointer (returned by the rdbuf member function) is set to sb.4. The remaining fields <strong>of</strong> the ios object are initialized to zero.Results:See Also:If sb is NULL the ios::badbit is set in the error state in the inherited ios object.ios, rdbufInput/Output Classes 669
ios::ios()Synopsis:Semantics:Results:See Also:#include protected:ios::ios();This form <strong>of</strong> the protected ios constructor creates a default ios object that is initialized, but does nothave an associated streambuf. Initialization <strong>of</strong> an ios object is handled by the init protectedmember function.This protected ios constructor creates an ios object and sets ios::badbit in the error state in theinherited ios object.~ios, init670 Input/Output Classes
ios::ios()Synopsis:Semantics:Results:See Also:#include public:ios::ios( streambuf *sb );This form <strong>of</strong> the public ios constructor creates an ios object that is initialized and has an associatedstreambuf. Initialization <strong>of</strong> an ios object is handled by the init protected member function.Once the init protected member function is completed, the ios object’s streambuf pointer is setto sb. If sb is not NULL, ios::badbit is cleared from the error state in the inherited ios object.This public ios constructor creates an ios object and, if sb is NULL, sets ios::badbit in the errorstate in the inherited ios object.~ios, initInput/Output Classes 671
ios::~ios()Synopsis:Semantics:Results:See Also:#include public:virtual ios::~ios();The public virtual ~ios destructor destroys an ios object. The call to the public virtual ~iosdestructor is inserted implicitly by the compiler at the point where the ios object goes out <strong>of</strong> scope.The ios object is destroyed.ios672 Input/Output Classes
ios::iostateSynopsis:Semantics:#include public:enum io_state {goodbit = 0x00, // no errorsbadbit = 0x01, // operation failed, may not proceedfailbit = 0x02, // operation failed, may proceede<strong>of</strong>bit = 0x04 // end <strong>of</strong> file encountered};typedef int iostate;The type ios::io_state is a set <strong>of</strong> bits representing the current state <strong>of</strong> the stream. Theios::iostate member typedef represents the same set <strong>of</strong> bits, but uses an int to represent thevalues, thereby avoiding problems made possible by the compiler’s ability to use smaller types forenumerations. All uses <strong>of</strong> these bits should use the ios::iostate member typedef.The bit values defined by the ios::iostate member typedef can be read and set by the memberfunctions rdstate and clear, and can be used to control exception handling with the memberfunction exceptions.ios::badbit represents the state where the stream is no longer usable because <strong>of</strong> some errorcondition.ios::failbit represents the state where the previous operation on the stream failed, but the streamis still usable. Subsequent operations on the stream are possible, but the state must be cleared using theclear member function.ios::e<strong>of</strong>bit represents the state where the end-<strong>of</strong>-file condition has been encountered. The streammay still be used, but the state must be cleared using the clear member function.Even though ios::goodbit is not a bit value (because its value is zero, which has no bits on), it isprovided for completeness.See Also:ios::bad, clear, e<strong>of</strong>, fail, good, operator !, operator void *, rdstate,setstateInput/Output Classes 673
ios::iword()Synopsis:Semantics:#include public:long &ios::iword( int index );The iword public member function creates a reference to a long int, which may be used to storeand retrieve any suitable integer value. The index parameter specifies which long int is to bereferenced and must be obtained from a call to the xalloc static member function.Note that the iword and pword public member functions return references to the same storage with adifferent type. Therefore, each index obtained from the xalloc static member function can be usedonly for an integer or a pointer, not both.Since the iword public member function returns a reference and the ios class cannot predict howmany such items will be required by a program, it should be assumed that each call to the xallocstatic member function invalidates all previous references returned by the iword public memberfunction. Therefore, the iword public member function should be called each time the reference isneeded.Results:See Also:The iword public member function returns a reference to a long int.ios::pword, xalloc674 Input/Output Classes
ios::openmodeSynopsis:#include public:enum open_mode {in = 0x0001, // open for inputout = 0x0002, // open for outputatend = 0x0004, // seek to end after openingappend = 0x0008, // open for output, append to the endtruncate = 0x0010, // discard contents after openingnocreate = 0x0020, // open only an existing filenoreplace = 0x0040, // open only a new filetext = 0x0080, // open as text filebinary = 0x0100, // open as binary fileapp = append, // synonymate = atend, // synonymtrunc = truncate // synonym};typedef int openmode;Semantics:The type ios::open_mode is a set <strong>of</strong> bits representing ways <strong>of</strong> opening a stream. Theios::openmode member typedef represents the same set <strong>of</strong> bits, but uses an int to represent thevalues, thereby avoiding problems made possible by the compiler’s ability to use smaller types forenumerations. All uses <strong>of</strong> these bits should use the ios::openmode member typedef.The bit values defined by ios::openmode member typedef can be specified in the constructors forstream objects, as well as in various member functions.ios::in is specified in a stream for which input operations may be performed. ios::out isspecified in a stream for which output operations may be performed. A stream for which onlyios::in is specified is referred to as an input stream. A stream for which only ios::out isspecified is referred to as an output stream. A stream where both ios::in and ios::out arespecified is referred to as an input/output stream.ios::atend and ios::ate are equivalent, and either one is specified for streams that are to bepositioned to the end before the first operation takes place. ios:ate is provided for historicalpurposes and compatibility with other implementations <strong>of</strong> I/O streams. Note that this bit positions thestream to the end exactly once, when the stream is opened.ios::append and ios::app are equivalent, and either one is specified for streams that are to bepositioned to the end before any and all output operations take place. ios::app is provided forhistorical purposes and compatibility with other implementations <strong>of</strong> I/O streams. Note that this bitcauses the stream to be positioned to the end before each output operation, while ios::atend causesthe stream to be positioned to the end only when first opened.ios::truncate and ios::trunc are equivalent, and either one is specified for streams that are tobe truncated to zero length before the first operation takes place. ios::trunc is provided forhistorical purposes and compatibility with other implementations <strong>of</strong> I/O streams.ios::nocreate is specified if the file must exist before it is opened. If the file does not exist, anerror occurs.ios::noreplace is specified if the file must not exist before it is opened. That is, the file must be anew file. If the file exists, an error occurs.Input/Output Classes 675
ios::openmodeios::text is specified if the file is to be treated as a text file. A text file is divided into records, andeach record is terminated by a new-line character, usually represented as ’\n’. The new-linecharacter is translated into a form that is compatible with the underlying file system’s concept <strong>of</strong> textfiles. This conversion happens automatically whenever the new-line is written to the file, and theinverse conversion (to the new-line character) happens automatically whenever the end <strong>of</strong> a record isread from the file system.ios::binary is specified if the file is to be treated as a binary file. Binary files are streams <strong>of</strong>characters. No character has a special meaning. No grouping <strong>of</strong> characters into records is apparent tothe program, although the underlying file system may cause such a grouping to occur.The following default behaviors are defined:If ios::out is specified and none <strong>of</strong> ios::in, ios::append or ios::atend are specified,ios::truncate is assumed.If ios::append is specified, ios::out is assumed.If ios::truncate is specified, ios::out is assumed.If neither ios::text nor ios::binary is specified, ios::text is assumed.676 Input/Output Classes
ios::operator !()Synopsis:Semantics:Results:See Also:#include public:int ios::operator !() const;The operator ! public member function tests the error state in the inherited ios object <strong>of</strong> the iosobject.The operator ! public member function returns a non-zero value if either <strong>of</strong> ios::failbit orios::badbit bits are set in the error state in the inherited ios object, otherwise zero is returned.ios::bad, clear, fail, good, iostate, operator void *, rdstate, setstateInput/Output Classes 677
ios::operator void *()Synopsis:Semantics:Results:See Also:#include public:ios::operator void *() const;The operator void * public member function converts the ios object into a pointer to void.The actual pointer value returned is meaningless and intended only for comparison with NULL todetermine the error state in the inherited ios object <strong>of</strong> the ios object.The operator void * public member function returns a NULL pointer if either <strong>of</strong>ios::failbit or ios::badbit bits are set in the error state in the inherited ios object,otherwise a non- NULL pointer is returned.ios::bad, clear, fail, good, iostate, operator !, rdstate, setstate678 Input/Output Classes
ios::precision()Synopsis:Semantics:#include public:int ios::precision() const;int ios::precision( int prec );The precision public member function is used to query and/or set the format precision. The formatprecision is used to control the number <strong>of</strong> digits <strong>of</strong> precision used when formatting floating-pointnumbers. For scientific notation, the format precision describes the total number <strong>of</strong> digits before andafter the decimal point, but not including the exponent. For fixed-point notation, the format precisiondescribes the number <strong>of</strong> digits after the decimal point.The first form <strong>of</strong> the precision public member function looks up the current format precision.The second form <strong>of</strong> the precision public member function sets the format precision to prec.By default, the format precision is six. If prec is specified to be less than zero, the format precision isset to six. Otherwise, the specified format precision is used. For scientific notation, a format precision<strong>of</strong> zero is treated as a precision <strong>of</strong> one.Results:See Also:The precision public member function returns the previous format precision setting.ios::fmtflags, manipulator setprecInput/Output Classes 679
ios::pword()Synopsis:Semantics:#include public:void * &ios::pword( int index );The pword public member function creates a reference to a void pointer, which may be used to storeand retrieve any suitable pointer value. The index parameter specifies which void pointer is to bereferenced and must be obtained from a call to the xalloc static member function.Note that the iword and pword public member functions return references to the same storage with adifferent type. Therefore, each index obtained from the xalloc static member function can be usedonly for an integer or a pointer, not both.Since the pword public member function returns a reference and the ios class cannot predict howmany such items will be required by a program, it should be assumed that each call to the xallocstatic member function invalidates all previous references returned by the pword public memberfunction. Therefore, the pword public member function should be called each time the reference isneeded.Results:See Also:The pword public member function returns a reference to a void pointer.ios::iword, xalloc680 Input/Output Classes
ios::rdbuf()Synopsis:Semantics:Results:#include public:streambuf *ios::rdbuf() const;The rdbuf public member function looks up the pointer to the streambuf object which maintainsthe buffer associated with the ios object.The rdbuf public member function returns the pointer to the streambuf object associated with theios object. If there is no associated streambuf object, NULL is returned.Input/Output Classes 681
ios::rdstate()Synopsis:Semantics:Results:#include public:iostate ios::rdstate() const;The rdstate public member function is used to query the current value <strong>of</strong> ios::iostate in theios object without modifying it.The rdstate public member function returns the current value <strong>of</strong> ios::iostate.See Also: ios::bad, clear, e<strong>of</strong>, fail, good, iostate, operator !, operator void *,setstate682 Input/Output Classes
ios::seekdirSynopsis:Semantics:#include public:enum seek_dir {beg, // seek from beginningcur, // seek from current positionend // seek from end};typedef int seekdir;The type ios::seek_dir is a set <strong>of</strong> bits representing different methods <strong>of</strong> seeking within a stream.The ios::seekdir member typedef represents the same set <strong>of</strong> bits, but uses an int to represent thevalues, thereby avoiding problems made possible by the compiler’s ability to use smaller types forenumerations. All uses <strong>of</strong> these bits should use the ios::seekdir member typedef.The bit values defined by ios::seekdir member typedef are used by the member functions seekgand seekp, as well the seek<strong>of</strong>f and seekpos member functions in classes derived from thestreambuf class.ios::beg causes the seek <strong>of</strong>fset to be interpreted as an <strong>of</strong>fset from the beginning <strong>of</strong> the stream. The<strong>of</strong>fset is specified as a positive value.ios::cur causes the seek <strong>of</strong>fset to be interpreted as an <strong>of</strong>fset from the current position <strong>of</strong> the stream.If the <strong>of</strong>fset is a negative value, the seek is towards the start <strong>of</strong> the stream. Otherwise, the seek istowards the end <strong>of</strong> the stream.ios::end causes the seek <strong>of</strong>fset to be interpreted as an <strong>of</strong>fset from the end <strong>of</strong> the stream. The <strong>of</strong>fsetis specified as a negative value.Input/Output Classes 683
ios::setf()Synopsis:Semantics:#include public:ios::fmtflags ios::setf( ios::fmtflags onbits );ios::fmtflags ios::setf( ios::fmtflags setbits,ios::fmtflags mask );The setf public member function is used to set bits in ios::fmtflags in the ios object.The first form is used to turn on the bits that are on in the onbits parameter. ( onbits is or’ed intoios::fmtflags).The second form is used to turn <strong>of</strong>f the bits specified in the mask parameter and turn on the bitsspecified in the setbits parameter. This form is particularly useful for setting the bits described by theios::basefield, ios::adjustfield and ios::floatfield values, where only one bitshould be on at a time.Results:See Also:Both forms <strong>of</strong> the setf public member function return the previous ios::fmtflags value.ios::fmtflags, setf, unsetf, manipulator dec, manipulator hex, manipulator oct,manipulator setbase, manipulator setiosflags, manipulator resetiosflags684 Input/Output Classes
ios::setstate()Synopsis:Semantics:Results:#include protected:void ios::setstate( int or_bits );The setstate protected member function is provided as a convenience for classes derived from theios class. It turns on the error state in the inherited ios object bits that are set in the or_bitsparameter, and leaves the other error state in the inherited ios object bits unchanged.The setstate protected member function sets the bits specified by or_bits in the error state in theinherited ios object.See Also: ios::bad, clear, e<strong>of</strong>, fail, good, iostate, operator !, operator void *,rdstateInput/Output Classes 685
ios::sync_with_stdio()Synopsis:Semantics:Results:#include public:static void ios::sync_with_stdio();The sync_with_stdio public static member function is obsolete. It is provided for compatibility.The sync_with_stdio public static member function has no return value.686 Input/Output Classes
ios::tie()Synopsis:Semantics:#include public:ostream *ios::tie() const;ostream *ios::tie( ostream *ostrm );The tie public member function is used to query and/or set up a connection between the ios objectand another stream. The connection causes the output stream specified by ostrm to be flushed wheneverthe ios object is about to read characters from a device or is about to write characters to an outputbuffer or device.The first form <strong>of</strong> the tie public member function is used to query the current tie.The second form <strong>of</strong> the tie public member function is used to set the tied stream to ostrm.Normally, the predefined streams cin and cerr set up ties to cout so that any input from theterminal flushes any buffered output, and any writes to cerr flush cout before the characters arewritten. cout does not set up a tie to cerr because cerr has the flag ios::unitbuf set, so itflushes itself after every write operation.Results:See Also:Both forms <strong>of</strong> the tie public member function return the previous tie value.ios::fmtflagsInput/Output Classes 687
ios::unsetf()Synopsis:Semantics:Results:See Also:#include public:ios::fmtflags ios::unsetf( ios::fmtflags <strong>of</strong>fbits );The unsetf public member function is used to turn <strong>of</strong>f bits in ios::fmtflags that are set in the<strong>of</strong>fbits parameter. All other bits in ios::fmtflags are unchanged.The unsetf public member function returns the old ios::fmtflags value.ios::fmtflags, setf, unsetf, manipulator dec, manipulator hex, manipulator oct,manipulator setbase, manipulator setiosflags, manipulator resetiosflags688 Input/Output Classes
ios::width()Synopsis:Semantics:#include public:int ios::width() const;int ios::width( int wid );The width public member function is used to query and/or set the format width used to format the nextitem. A format width <strong>of</strong> zero indicates that the item is to be written using exactly the number <strong>of</strong>positions required. Other values indicate that the item must occupy at least that many positions. If theformatted item is larger than the specified format width, the format width is ignored and the item isformatted using the required number <strong>of</strong> positions.The first form <strong>of</strong> the width public member function is used to query the format width that is to be usedfor the next item.The second form <strong>of</strong> the width public member function is used to set the format width to wid for thenext item to be formatted.After an item has been formatted, the format width is reset to zero. Therefore, any non-zero formatwidth must be set before each item that is to be formatted.Results:See Also:The width public member function returns the previous format width.ios::fmtflags, manipulator setw, manipulator setwidthInput/Output Classes 689
ios::xalloc()Synopsis:Semantics:#include public:static int ios::xalloc();The xalloc public static member function returns an index into an array <strong>of</strong> items that the programmay use for any purpose. Each item can be either a long int or a pointer to void. The index canbe used with the iword and pword member functions.Because the xalloc public static member function manipulates static member data, its behavior isnot tied to any one object but affects the entire class <strong>of</strong> objects. The value that is returned by thexalloc public static member function is valid for all objects <strong>of</strong> all classes derived from the ios class.No subsequent call to the xalloc public static member function will return the same value as aprevious call.Results:See Also:The xalloc public static member function returns an index for use with the iword and pwordmember functions.ios::iword, pword690 Input/Output Classes
iostreamDeclared:iostream.hDerived from: istream, ostreamDerived by:fstream, strstreamThe iostream class supports reading and writing <strong>of</strong> characters from and to the standard input/outputdevices, usually the keyboard and screen. The iostream class provides formatted conversion <strong>of</strong>characters to and from other types (e.g. integers and floating-point numbers). The associatedstreambuf class provides the methods for communicating with the actual device, while theiostream class provides the interpretation <strong>of</strong> the characters.Generally, an iostream object won’t be created by a program, since there is no mechanism at thislevel to "open" a device. No instance <strong>of</strong> an iostream object is created by default, since it is usuallynot possible to perform both input and output on the standard input/output devices. The iostreamclass is provided as a base class for other derived classes that can provide both input and outputcapabilities through the same object. The fstream and strstream classes are examples <strong>of</strong> classesderived from the iostream class.Protected Member FunctionsThe following protected member functions are declared:iostream();Public Member FunctionsThe following public member functions are declared:iostream( ios const & );iostream( streambuf * );virtual ~iostream();Public Member OperatorsThe following public member operators are declared:iostream & operator =( streambuf * );iostream & operator =( ios const & );See Also:ios, istream, ostreamInput/Output Classes 691
iostream::iostream()Synopsis:Semantics:#include protected:iostream::iostream();This form <strong>of</strong> the protected iostream constructor creates an iostream object without an attachedstreambuf object.This form <strong>of</strong> the protected iostream constructor is only used implicitly by the compiler when itgenerates a constructor for a derived class.Results:See Also:The protected iostream constructor produces an initialized iostream object. ios::badbit isset in the error state in the inherited ios object.~iostream692 Input/Output Classes
iostream::iostream()Synopsis:Semantics:Results:See Also:#include public:iostream::iostream( ios const &strm );This form <strong>of</strong> the public iostream constructor creates an iostream object associated with thestreambuf object currently associated with the strm parameter. The iostream object is initializedand will use the strm streambuf object for subsequent operations. strm will continue to use thestreambuf object.The public iostream constructor produces an initialized iostream object. If there is nostreambuf object currently associated with the strm parameter, ios::badbit is set in the errorstate in the inherited ios object.~iostreamInput/Output Classes 693
iostream::iostream()Synopsis:Semantics:#include public:iostream::iostream( streambuf *sb );This form <strong>of</strong> the public iostream constructor creates an iostream object with an attachedstreambuf object.Since a user program usually will not create an iostream object, this form <strong>of</strong> the public iostreamconstructor is unlikely to be explicitly used, except in the member initializer list for the constructor <strong>of</strong> aderived class. The sb parameter is a pointer to a streambuf object, which should be connected to thesource and sink <strong>of</strong> characters for the stream.Results:See Also:The public iostream constructor produces an initialized iostream object. If the sb parameter isNULL, ios::badbit is set in the error state in the inherited ios object.~iostream694 Input/Output Classes
iostream::~iostream()Synopsis:Semantics:Results:See Also:#include public:virtual iostream::~iostream();The public ~iostream destructor does not do anything explicit. The ios destructor is called for thatportion <strong>of</strong> the iostream object. The call to the public ~iostream destructor is inserted implicitlyby the compiler at the point where the iostream object goes out <strong>of</strong> scope.The iostream object is destroyed.iostreamInput/Output Classes 695
iostream::operator =()Synopsis:Semantics:Results:#include public:iostream &iostream::operator =( streambuf *sb );This form <strong>of</strong> the operator = public member function initializes the target iostream object andsets up an association between the iostream object and the streambuf object specified by the sbparameter.The operator = public member function returns a reference to the iostream object that is thetarget <strong>of</strong> the assignment. If the sb parameter is NULL, ios::badbit is set in the error state in theinherited ios object.696 Input/Output Classes
iostream::operator =()Synopsis:Semantics:Results:#include public:iostream &iostream::operator =( const ios &strm );This form <strong>of</strong> the operator = public member function initializes the iostream object and sets upan association between the iostream object and the streambuf object currently associated with thestrm parameter.The operator = public member function returns a reference to the iostream object that is thetarget <strong>of</strong> the assignment. If there is no streambuf object currently associated with the strmparameter, ios::badbit is set in the error state in the inherited ios object.Input/Output Classes 697
istreamDeclared:iostream.hDerived from: iosDerived by:iostream, ifstream, istrstreamThe istream class supports reading characters from a class derived from streambuf, and providesformatted conversion <strong>of</strong> characters into other types (such as integers and floating-point numbers). Thestreambuf class provides the methods for communicating with the external device (keyboard, disk),while the istream class provides the interpretation <strong>of</strong> the resulting characters.Generally, an istream object won’t be explicitly created by a program, since there is no mechanism atthis level to open a device. The only default istream object in a program is cin, which reads fromstandard input (usually the keyboard).The istream class supports two basic concepts <strong>of</strong> input: formatted and unformatted. The overloadedoperator >> member functions are called extractors and they provide the support for formattedinput. The rest <strong>of</strong> the member functions deal with unformatted input, managing the state <strong>of</strong> the iosobject and providing a friendlier interface to the associated streambuf object.Protected Member FunctionsThe following protected member functions are declared:istream();eatwhite();Public Member FunctionsThe following public member functions are declared:istream( istream const & );istream( streambuf * );virtual ~istream();int ipfx( int = 0 );void isfx();int get();istream &get( char *, int, char = ’\n’ );istream &get( signed char *, int, char = ’\n’ );istream &get( unsigned char *, int, char = ’\n’ );istream &get( char & );istream &get( signed char & );istream &get( unsigned char & );istream &get( streambuf &, char = ’\n’ );istream &getline( char *, int, char = ’\n’ );istream &getline( signed char *, int, char = ’\n’ );istream &getline( unsigned char *, int, char = ’\n’ );istream &ignore( int = 1, int = EOF );istream &read( char *, int );istream &read( signed char *, int );istream &read( unsigned char *, int );istream &seekg( streampos );istream &seekg( stream<strong>of</strong>f, ios::seekdir );istream &putback( char );streampos tellg();int gcount() const;698 Input/Output Classes
istreamint peek();int sync();Public Member OperatorsThe following public member operators are declared:istream &operator =( streambuf * );istream &operator =( istream const & );istream &operator >>( char * );istream &operator >>( signed char * );istream &operator >>( unsigned char * );istream &operator >>( char & );istream &operator >>( signed char & );istream &operator >>( unsigned char & );istream &operator >>( signed short & );istream &operator >>( unsigned short & );istream &operator >>( signed int & );istream &operator >>( unsigned int & );istream &operator >>( signed long & );istream &operator >>( unsigned long & );istream &operator >>( float & );istream &operator >>( double & );istream &operator >>( long double & );istream &operator >>( streambuf & );istream &operator >>( istream &(*)( istream & ) );istream &operator >>( ios &(*)( ios & ) );See Also:ios, iostream, ostreamInput/Output Classes 699
istream::eatwhite()Synopsis:Semantics:Results:See Also:#include protected:void istream::eatwhite();The eatwhite protected member function extracts and discards whitespace characters from theistream object, until a non-whitespace character is found. The non-whitespace character is notextracted.The eatwhite protected member function sets ios::e<strong>of</strong>bit in the error state in the inherited iosobject if end-<strong>of</strong>-file is encountered as the first character while extracting whitespace characters.istream::ignore, ios::fmtflags700 Input/Output Classes
istream::gcount()Synopsis:Semantics:Results:See Also:#include public:int istream::gcount() const;The gcount public member function determines the number <strong>of</strong> characters extracted by the lastunformatted input member function.The gcount public member function returns the number <strong>of</strong> characters extracted by the lastunformatted input member function.istream::get, getline, readInput/Output Classes 701
istream::get()Synopsis:Semantics:Results:See Also:#include public:int istream::get();This form <strong>of</strong> the get public member function performs an unformatted read <strong>of</strong> a single character fromthe istream object.This form <strong>of</strong> the get public member function returns the character read from the istream object. Ifthe istream object is positioned at end-<strong>of</strong>-file before the read, EOF is returned and ios::e<strong>of</strong>bitbit is set in the error state in the inherited ios object. ios::failbit bit is not set by this form <strong>of</strong>the get public member function.istream::putback702 Input/Output Classes
istream::get()Synopsis:Semantics:Results:#include public:istream &istream::get( char &ch );istream &istream::get( signed char &ch );istream &istream::get( unsigned char &ch );These forms <strong>of</strong> the get public member function perform an unformatted read <strong>of</strong> a single character fromthe istream object and store the character in the ch parameter.These forms <strong>of</strong> the get public member function return a reference to the istream object.ios::e<strong>of</strong>bit is set in the error state in the inherited ios object if the istream object is positionedat end-<strong>of</strong>-file before the attempt to read the character. ios::failbit is set in the error state in theinherited ios object if no character is read.See Also: istream::read, operator >>Input/Output Classes 703
istream::get()Synopsis:#include public:istream &istream::get( char *buf, int len,char delim = ’\n’ );istream &istream::get( signed char *buf, int len,char delim = ’\n’ );istream &istream::get( unsigned char *buf, int len,char delim = ’\n’ );Semantics: These forms <strong>of</strong> the get public member function perform an unformatted read <strong>of</strong> at most len -1characters from the istream object and store them starting at the memory location specified by thebuf parameter. If the character specified by the delim parameter is encountered in the istream objectbefore len -1 characters have been read, the read terminates without extracting the delimiting character.After the read terminates, whether or not an error occurred, a null character is stored in buf followingthe last character read from the istream object.If the delim parameter is not specified, the new-line character is assumed.Results:These forms <strong>of</strong> the get public member function return a reference to the istream object. Ifend-<strong>of</strong>-file is encountered as the first character, ios::e<strong>of</strong>bit is set in the error state in the inheritedios object. If no characters are stored into buf, ios::failbit is set in the error state in theinherited ios object.See Also: istream::getline, read, operator >>704 Input/Output Classes
istream::get()Synopsis:Semantics:#include public:istream &istream::get( streambuf &sb, char delim = ’\n’ );This form <strong>of</strong> the get public member function performs an unformatted read <strong>of</strong> characters from theistream object and transfers them to the streambuf object specified in the sb parameter. Thetransfer stops if end-<strong>of</strong>-file is encountered, the delimiting character specified in the delim parameter isfound, or if the store into the sb parameter fails. If the delim character is found, it is not extracted fromthe istream object and is not transferred to the sb object.If the delim parameter is not specified, the new-line character is assumed.Results:The get public member function returns a reference to the istream object. ios::failbit is setin the error state in the inherited ios object if the store into the streambuf object fails.See Also: istream::getline, read, operator >>Input/Output Classes 705
istream::getline()Synopsis:Semantics:#include public:istream &istream::getline( char *buf, int len,char delim = ’\n’ );istream &istream::getline( signed char *buf, int len,char delim = ’\n’ );istream &istream::getline( unsigned char *buf, int len,char delim = ’\n’ );The getline public member function performs an unformatted read <strong>of</strong> at most len -1 characters fromthe istream object and stores them starting at the memory location specified by the buf parameter. Ifthe delimiting character, specified by the delim parameter, is encountered in the istream object beforelen -1 characters have been read, the read terminates after extracting the delim character.If len -1 characters have been read and the next character is the delim character, it is not extracted.After the read terminates, whether or not an error occurred, a null character is stored in the bufferfollowing the last character read from the istream object.If the delim parameter is not specified, the new-line character is assumed.Results:The getline public member function returns a reference to the istream object. If end-<strong>of</strong>-file isencountered as the first character, ios::e<strong>of</strong>bit is set in the error state in the inherited ios object.If end-<strong>of</strong>-file is encountered before len characters are transferred or the delim character is reached,ios::failbit is set in the error state in the inherited ios object.See Also: istream::get, read, operator >>706 Input/Output Classes
istream::ignore()Synopsis:Semantics:#include public:istream &istream::ignore( int num = 1, int delim = EOF );The ignore public member function extracts and discards up to num characters from the istreamobject. If the num parameter is not specified, the ignore public member function extracts anddiscards one character. If the delim parameter is not EOF and it is encountered before num charactershave been extracted, the extraction ceases after discarding the delimiting character. The extractionstops if end-<strong>of</strong>-file is encountered.If the num parameter is specified as a negative number, no limit is imposed on the number <strong>of</strong> charactersextracted and discarded. The operation continues until the delimiting character is found and discarded,or until end-<strong>of</strong>-file. This behavior is a WATCOM extension.Results:See Also:The ignore public member function returns a reference to the istream object. If end-<strong>of</strong>-file isencountered as the first character, ios::e<strong>of</strong>bit is set in the error state in the inherited ios object.istream::eatwhiteInput/Output Classes 707
istream::ipfx()Synopsis:Semantics:#include public:int istream::ipfx( int noskipws = 0 );The ipfx public member function is a prefix function executed before each <strong>of</strong> the formatted andunformatted read operations. If any bits are set in ios::iostate, the ipfx public member functionimmediately returns 0, indicating that the prefix function failed. Failure in the prefix function causesthe input operation to fail.If the noskipws parameter is 0 or unspecified and the ios::skipws bit is on in ios::fmtflags,whitespace characters are discarded and the istream object is positioned so that the next characterread is the first character after the discarded whitespace. Otherwise, no whitespace skipping takesplace.The formatted input functions that read specific types <strong>of</strong> objects (such as integers and floating-pointnumbers) call the ipfx public member function with the noskipws parameter set to zero, allowingleading whitespaces to be discarded if the ios::skipws bit is on in ios::fmtflags. Theunformatted input functions that read characters without interpretation call the ipfx public memberfunction with a the noskipws parameter set to 1 so that no whitespace characters are discarded.If the istream object is tied to an output stream, the output stream is flushed.Results:See Also:If the istream object is not in an error state in the inherited ios object when the above processing iscompleted, the ipfx public member function returns a non-zero value to indicate success. Otherwise,zero is returned to indicate failure.istream::isfx708 Input/Output Classes
istream::isfx()Synopsis:Semantics:#include public:void istream::isfx();The isfx public member function is a suffix function executed just before the end <strong>of</strong> each <strong>of</strong> theformatted and unformatted read operations.As currently implemented, the isfx public member function does not do anything.See Also:istream::ipfxInput/Output Classes 709
istream::istream()Synopsis:Semantics:#include protected:istream::istream();This form <strong>of</strong> the protected istream constructor creates an istream object without an associatedstreambuf object.This form <strong>of</strong> the protected istream constructor is only used implicitly by the compiler when itgenerates a constructor for a derived class.Results:See Also:This form <strong>of</strong> the protected istream constructor creates an initialized istream object.ios::badbit is set in the error state in the inherited ios object.~istream710 Input/Output Classes
istream::istream()Synopsis:Semantics:Results:See Also:#include public:istream::istream( istream const &istrm );This form <strong>of</strong> the public istream constructor creates an istream object associated with thestreambuf object currently associated with the istrm parameter. The istream object is initializedand will use the istrm streambuf object for subsequent operations. istrm will continue to use thestreambuf object.This form <strong>of</strong> the public istream constructor creates an initialized istream object. If there is nostreambuf object currently associated with the istrm parameter, ios::badbit is set in the errorstate in the inherited ios object.~istreamInput/Output Classes 711
istream::istream()Synopsis:Semantics:#include public:istream::istream( streambuf *sb );This form <strong>of</strong> the public istream constructor creates an istream object with an associatedstreambuf object specified by the sb parameter.This function is likely to be used for the creation <strong>of</strong> an istream object that is associated with the samestreambuf object as another istream object.Results:See Also:This form <strong>of</strong> the public istream constructor creates an initialized istream object. If the sbparameter is NULL, ios::badbit is set in the error state in the inherited ios object.~istream712 Input/Output Classes
istream::~istream()Synopsis:Semantics:Results:See Also:#include public:virtual istream::~istream();The public virtual ~istream destructor does not do anything explicit. The ios destructor is calledfor that portion <strong>of</strong> the istream object. The call to the public virtual ~istream destructor is insertedimplicitly by the compiler at the point where the istream object goes out <strong>of</strong> scope.The istream object is destroyed.istreamInput/Output Classes 713
istream::operator =()Synopsis:Semantics:Results:#include public:istream &istream::operator =( streambuf *sb );This form <strong>of</strong> the operator = public member function is used to associate a streambuf object,specified by the sb parameter, with an existing istream object. The istream object is initializedand will use the specified streambuf object for subsequent operations.This form <strong>of</strong> the operator = public member function returns a reference to the istream object thatis the target <strong>of</strong> the assignment. If the sb parameter is NULL, ios::badbit is set in the error state inthe inherited ios object.714 Input/Output Classes
istream::operator =()Synopsis:Semantics:Results:#include public:istream &istream::operator =( istream const &istrm );This form <strong>of</strong> the operator = public member function is used to associate the istream object withthe streambuf object currently associated with the istrm parameter. The istream object isinitialized and will use the istrm’s streambuf object for subsequent operations. The istrm object willcontinue to use the streambuf object.This form <strong>of</strong> the operator = public member function returns a reference to the istream object thatis the target <strong>of</strong> the assignment. If there is no streambuf object currently associated with the istrmparameter, ios::badbit is set in the error state in the inherited ios object.Input/Output Classes 715
istream::operator >>()Synopsis:Semantics:#include public:istream &istream::operator >>( char *buf );istream &istream::operator >>( signed char *buf );istream &istream::operator >>( unsigned char *buf );These forms <strong>of</strong> the operator >> public member function perform a formatted read <strong>of</strong> charactersfrom the istream object and place them in the buffer specified by the buf parameter. Characters areread until a whitespace character is found or the maximum size has been read. If a whitespace characteris found, it is not transferred to the buffer and remains in the istream object.If a non-zero format width has been specified, it is interpreted as the maximum number <strong>of</strong> charactersthat may be placed in buf. No more than format width-1 characters are read from the istream objectand transferred to buf. If format width is zero, characters are transferred until a whitespace character isfound.Since these forms <strong>of</strong> the operator >> public member function use format width, it is reset to zeroafter each use. It must be set before each input operation that requires a non-zero format width.A null character is added following the last transferred character, even if the transfer fails because <strong>of</strong> anerror.Results:See Also:These forms <strong>of</strong> the operator >> public member function return a reference to the istream objectso that further extraction operations may be specified in the same statement. If no characters aretransferred to buf, ios::failbit is set in the error state in the inherited ios object. If the firstcharacter read yielded end-<strong>of</strong>-file, ios::e<strong>of</strong>bit is set in the error state in the inherited ios object.istream::get, getline, read716 Input/Output Classes
istream::operator >>()Synopsis:Semantics:Results:See Also:#include public:istream &istream::operator >>( char &ch );istream &istream::operator >>( signed char &ch );istream &istream::operator >>( unsigned char &ch );These forms <strong>of</strong> the operator >> public member function perform a formatted read <strong>of</strong> a singlecharacter from the istream object and place it in the ch parameter.These forms <strong>of</strong> the operator >> public member function return a reference to the istream objectso that further extraction operations may be specified in the same statement. If the character readyielded end-<strong>of</strong>-file, ios::e<strong>of</strong>bit is set in the error state in the inherited ios object.istream::getInput/Output Classes 717
istream::operator >>()Synopsis:Semantics:#include public:istream &istream::operator >>( signed int &num );istream &istream::operator >>( unsigned int &num );istream &istream::operator >>( signed long &num );istream &istream::operator >>( unsigned long &num );istream &istream::operator >>( signed short &num );istream &istream::operator >>( unsigned short &num );These forms the operator >> public member function perform a formatted read <strong>of</strong> an integral valuefrom the istream object and place it in the num parameter.The number may be preceded by a + or - sign.If ios::dec is the only bit set in the ios::basefield bits <strong>of</strong> ios::fmtflags, the number isinterpreted as a decimal (base 10) integer, composed <strong>of</strong> the digits 0123456789.If ios::oct is the only bit set in the ios::basefield bits <strong>of</strong> ios::fmtflags, the number isinterpreted as an octal (base 8) integer, composed <strong>of</strong> the digits 01234567.If ios::hex is the only bit set in the ios::basefield bits <strong>of</strong> ios::fmtflags, the number isinterpreted as a hexadecimal (base 16) integer, composed <strong>of</strong> the digits 0123456789 and the lettersabcdef or ABCDEF.If no bits are set in the ios::basefield bits <strong>of</strong> ios::fmtflags, the operator looks for a prefixto determine the base <strong>of</strong> the number. If the first two characters are 0x or 0X, the number is interpretedas a hexadecimal number. If the first character is a 0 (and the second is not an x or X), the number isinterpreted as an octal integer. Otherwise, no prefix is expected and the number is interpreted as adecimal integer.If more than one bit is set in the ios::basefield bits <strong>of</strong> ios::fmtflags, the number isinterpreted as a decimal integer.Results:See Also:These forms <strong>of</strong> the operator >> public member function return a reference to the istream objectso that further extraction operations may be specified in the same statement. If end-<strong>of</strong>-file isencountered as the first character, ios::e<strong>of</strong>bit is set in the error state in the inherited ios object.If an overflow occurs while converting to the required integer type, the ios::failbit is set in theerror state in the inherited ios object.ios::fmtflags718 Input/Output Classes
istream::operator >>()Synopsis:Semantics:#include public:istream &istream::operator >>( float &num );istream &istream::operator >>( double &num );istream &istream::operator >>( long double &num );These forms <strong>of</strong> the operator >> public member function perform a formatted read <strong>of</strong> afloating-point value from the istream object and place it in the num parameter.The floating-point value may be specified in any form that is acceptable to the C++ compiler.Results:These forms <strong>of</strong> the operator >> public member function return a reference to the istream objectso that further extraction operations may be specified in the same statement. If end-<strong>of</strong>-file isencountered as the first character, ios::e<strong>of</strong>bit is set in the error state in the inherited ios object.If an overflow occurs while converting to the required type, the ios::failbit is set in the errorstate in the inherited ios object.Input/Output Classes 719
istream::operator >>()Synopsis:Semantics:Results:#include public:istream &istream::operator >>( streambuf &sb );This form <strong>of</strong> the operator >> public member function transfers all the characters from theistream object into the sb parameter. Reading continues until end-<strong>of</strong>-file is encountered.This form <strong>of</strong> the operator >> public member function return a reference to the istream object sothat further extraction operations may be specified in the same statement.720 Input/Output Classes
istream::operator >>()Synopsis:Semantics:Results:#include public:istream &istream::operator >>( istream &(*fn)( istream & ) );istream &istream::operator >>( ios &(*fn)( ios & ) );These forms <strong>of</strong> the operator >> public member function are used to implement thenon-parameterized manipulators for the istream class. The function specified by the fn parameter iscalled with the istream object as its parameter.These forms <strong>of</strong> the operator >> public member function return a reference to the istream objectso that further extraction operations may be specified in the same statement.Input/Output Classes 721
istream::peek()Synopsis:Semantics:Results:See Also:#include public:int istream::peek();The peek public member function looks up the next character to be extracted from the istreamobject, without extracting the character.The peek public member function returns the next character to be extracted from the istream object.If the istream object is positioned at end-<strong>of</strong>-file, EOF is returned.istream::get722 Input/Output Classes
istream::putback()Synopsis:Semantics:#include public:istream &istream::putback( char ch );The putback public member function attempts to put the extracted character specified by the chparameter back into the istream object. The ch character must be the same as the character beforethe current position <strong>of</strong> the istream object, usually the last character extracted from the stream. If it isnot the same character, the result <strong>of</strong> the next character extraction is undefined.The number <strong>of</strong> characters that can be put back is defined by the istream object, but is usually at least4. Depending on the status <strong>of</strong> the buffers used for input, it may be possible to put back more than 4characters.Results:See Also:The putback public member function returns a reference to the istream object. If the putbackpublic member function is unable to put back the ch parameter, ios::failbit is set in the error statein the inherited ios object.istream::getInput/Output Classes 723
istream::read()Synopsis:Semantics:#include public:istream &istream::read( char *buf, int len );istream &istream::read( signed char *buf, int len );istream &istream::read( unsigned char *buf, int len );The read public member function performs an unformatted read <strong>of</strong> at most len characters from theistream object and stores them in the memory locations starting at buf. If end-<strong>of</strong>-file is encounteredbefore len characters have been transferred, the transfer stops and ios::failbit is set in the errorstate in the inherited ios object.The number <strong>of</strong> characters extracted can be determined with the gcount member function.Results:See Also:The read public member function returns a reference to the istream object. If end-<strong>of</strong>-file isencountered as the first character, ios::e<strong>of</strong>bit is set in the error state in the inherited ios object.If end-<strong>of</strong>-file is encountered before len characters are transferred, ios::failbit is set in the errorstate in the inherited ios object.istream::gcount, get, getline724 Input/Output Classes
istream::seekg()Synopsis:Semantics:Results:See Also:#include public:istream &istream::seekg( streampos pos );The seekg public member function positions the istream object to the position specified by the posparameter so that the next input operation commences from that position.The seekg public member function returns a reference to the istream object. If the seek operationfails, ios::failbit is set in the error state in the inherited ios object.istream::tellg, ostream::tellp, ostream::seekpInput/Output Classes 725
istream::seekg()Synopsis:Semantics:#include public:istream &istream::seekg( stream<strong>of</strong>f <strong>of</strong>fset, ios::seekdir dir );The seekg public member function positions the istream object to the specified position so that thenext input operation commences from that position.The dir parameter may be ios::beg, ios::cur, or ios::end and is interpreted in conjunctionwith the <strong>of</strong>fset parameter as follows:ios::beg the <strong>of</strong>fset is relative to the start and should be a positive value.ios::cur the <strong>of</strong>fset is relative to the current position and may be positive(seek towards end) or negative (seek towards start).ios::end the <strong>of</strong>fset is relative to the end and should be a negative value.If the dir parameter has any other value, or the <strong>of</strong>fset parameter does not have an appropriate sign, theseekg public member function fails.Results:See Also:The seekg public member function returns a reference to the istream object. If the seek operationfails, ios::failbit is set in the error state in the inherited ios object.ostream::tellp, ostream::seekpistream::tellg726 Input/Output Classes
istream::sync()Synopsis:Semantics:Results:#include public:int istream::sync();The sync public member function synchronizes the input buffer and the istream object withwhatever source <strong>of</strong> characters is being used. The sync public member function uses the streambufclass’s sync virtual member function to carry out the synchronization. The specific behavior isdependent on what type <strong>of</strong> streambuf derived object is associated with the istream object.The sync public member function returns __NOT_EOF on success, otherwiseEOF is returned.Input/Output Classes 727
istream::tellg()Synopsis:Semantics:Results:See Also:#include public:streampos istream::tellg();The tellg public member function determines the position in the istream object <strong>of</strong> the nextcharacter available for reading. The first character in an istream object is at <strong>of</strong>fset zero.The tellg public member function returns the position <strong>of</strong> the next character available for reading.ostream::tellp, ostream::seekpistream::seekg728 Input/Output Classes
istrstreamDeclared:strstrea.hDerived from: strstreambase, istreamThe istrstream class is used to create and read from string stream objects.The istrstream class provides little <strong>of</strong> its own functionality. Derived from the strstreambaseand istream classes, its constructors and destructor provide simplified access to the appropriateequivalents in those base classes.Of the available I/O stream classes, creating an istrstream object is the preferred method <strong>of</strong>performing read operations from a string stream.Public Member FunctionsThe following member functions are declared in the public interface:istrstream( char * );istrstream( signed char * );istrstream( unsigned char * );istrstream( char *, int );istrstream( signed char *, int );istrstream( unsigned char *, int );~istrstream();See Also:istream, ostrstream, strstream, strstreambaseInput/Output Classes 729
istrstream::istrstream()Synopsis:Semantics:Results:See Also:#include public:istrstream::istrstream( char *str );istrstream::istrstream( signed char *str );istrstream::istrstream( unsigned char *str );This form <strong>of</strong> the public istrstream constructor creates an istrstream object consisting <strong>of</strong> thenull terminated C string specified by the str parameter. The inherited istream member functions canbe used to read from the istrstream object.This form <strong>of</strong> the public istrstream constructor creates an initialized istrstream object.~istrstream730 Input/Output Classes
istrstream::istrstream()Synopsis:Semantics:Results:See Also:#include public:istrstream::istrstream( char *str, int len );istrstream::istrstream( signed char *str, int len );istrstream::istrstream( unsigned char *str, int len );This form <strong>of</strong> the public istrstream constructor creates an istrstream object consisting <strong>of</strong> thecharacters starting at str and ending at str + len - 1. The inherited istream member functions can beused to read from the istrstream object.This form <strong>of</strong> the public istrstream constructor creates an initialized istrstream object.~istrstreamInput/Output Classes 731
istrstream::~istrstream()Synopsis:Semantics:Results:See Also:#include public:istrstream::~istrstream();The public ~istrstream destructor does not do anything explicit. The call to the public~istrstream destructor is inserted implicitly by the compiler at the point where the istrstreamobject goes out <strong>of</strong> scope.The istrstream object is destroyed.istrstream732 Input/Output Classes
ManipulatorsDeclared:iostream.h and iomanip.hManipulators are designed to be inserted into or extracted from a stream. Manipulators come in tw<strong>of</strong>orms, non-parameterized and parameterized. The non-parameterized manipulators are simpler and aredeclared in . The parameterized manipulators require more complexity and aredeclared in . defines two macros SMANIP_define and SMANIP_make to implementparameterized manipulators. The workings <strong>of</strong> the SMANIP_define and SMANIP_make macros aredisclosed in the header file and are not discussed here.Non-parameterized ManipulatorsThe following non-parameterized manipulators are declared in :ios &dec( ios & );ios &hex( ios & );ios &oct( ios & );istream &ws( istream & );ostream &endl( ostream & );ostream &ends( ostream & );ostream &flush( ostream & );Parameterized ManipulatorsThe following parameterized manipulators are declared in :SMANIP_define( long ) resetiosflags( long );SMANIP_define( int ) setbase( int );SMANIP_define( int ) setfill( int );SMANIP_define( long ) setiosflags( long );SMANIP_define( int ) setprecision( int );SMANIP_define( int ) setw( int );SMANIP_define( int ) setwidth( int );Input/Output Classes 733
manipulator dec()Synopsis:Semantics:See Also:#include ios &dec( ios &strm );The dec manipulator sets the ios::basefield bits for decimal formatting in ios::fmtflags inthe strm ios object.ios::fmtflags734 Input/Output Classes
manipulator endl()Synopsis:Semantics:See Also:#include ostream &endl( ostream &ostrm );The endl manipulator writes a new-line character to the stream specified by the ostrm parameter andperforms a flush.ostream::flushInput/Output Classes 735
manipulator ends()Synopsis:Semantics:#include ostream &ends( ostream &ostrm );The ends manipulator writes a null character to the stream specified by the ostrm parameter.736 Input/Output Classes
manipulator flush()Synopsis:Semantics:See Also:#include ostream &flush( ostream &ostrm );The flush manipulator flushes the stream specified by the ostrm parameter. The flush is performed inthe same manner as the flush member function.ostream::flushInput/Output Classes 737
manipulator hex()Synopsis:Semantics:See Also:#include ios &hex( ios &strm );The hex manipulator sets the ios::basefield bits for hexadecimal formatting inios::fmtflags in the strm ios object.ios::fmtflags738 Input/Output Classes
manipulator oct()Synopsis:Semantics:See Also:#include ios &oct( ios &strm );The oct manipulator sets the ios::basefield bits for octal formatting in ios::fmtflags inthe strm ios object.ios::fmtflagsInput/Output Classes 739
manipulator resetiosflags()Synopsis:Semantics:See Also:#include SMANIP_define( long ) resetiosflags( long flags )The resetiosflags manipulator turns <strong>of</strong>f the bits in ios::fmtflags that correspond to the bitsthat are on in the flags parameter. No other bits are affected.ios::flags, ios::fmtflags, ios::setf, ios::unsetf740 Input/Output Classes
manipulator setbase()Synopsis:Semantics:See Also:#include SMANIP_define( int ) setbase( int base );The setbase manipulator sets the ios::basefield bits in ios::fmtflags to the valuespecified by the base parameter within the stream that the setbase manipulator is operating upon.ios::fmtflagsInput/Output Classes 741
manipulator setfill()Synopsis:Semantics:See Also:#include SMANIP_define( int ) setfill( int fill )The setfill manipulator sets the fill character to the value specified by the fill parameter within thestream that the setfill manipulator is operating upon.ios::fill742 Input/Output Classes
manipulator setiosflags()Synopsis:Semantics:See Also:#include SMANIP_define( long ) setiosflags( long flags );The setiosflags manipulator turns on the bits in ios::fmtflags that correspond to the bits thatare on in the flags parameter. No other bits are affected.ios::flags, ios::fmtflags, ios::setf, ios::unsetfInput/Output Classes 743
manipulator setprecision()Synopsis:Semantics:See Also:#include SMANIP_define( int ) setprecision( int prec );The setprecision manipulator sets the format precision to the value specified by the precparameter within the stream that the setprecision manipulator is operating upon.ios::precision744 Input/Output Classes
manipulator setw()Synopsis:Semantics:See Also:#include SMANIP_define( int ) setw( int wid );The setw manipulator sets the format width to the value specified by the wid parameter within thestream that the setw manipulator is operating upon.ios::width, manipulator setwidthInput/Output Classes 745
manipulator setwidth()Synopsis:Semantics:#include SMANIP_define( int ) setwidth( int wid );The setwidth manipulator sets the format width to the value specified by the wid parameter withinthe stream that the setwidth manipulator is operating upon.This function is a WATCOM extension.See Also:ios::width, manipulator setw746 Input/Output Classes
manipulator ws()Synopsis:Semantics:#include istream &ws( istream &istrm );The ws manipulator extracts and discards whitespace characters from the istrm parameter, leaving thestream positioned at the next non-whitespace character.The ws manipulator is needed particularly when the ios::skipws bit is not set inios::fmtflags in the istrm object. In this case, whitespace characters must be explicitly removedfrom the stream, since the formatted input operations will not automatically remove them.See Also:istream::eatwhite, istream::ignoreInput/Output Classes 747
<strong>of</strong>streamDeclared:fstream.hDerived from: fstreambase, ostreamThe <strong>of</strong>stream class is used to create new files or access existing files for writing. The file can beopened and closed, and write and seek operations can be performed.The <strong>of</strong>stream class provides very little <strong>of</strong> its own functionality. Derived from both thefstreambase and ostream classes, its constructors, destructor and member function providesimplified access to the appropriate equivalents in those base classes.Of the available I/O stream classes, creating an <strong>of</strong>stream object is the preferred method <strong>of</strong> accessinga file for output operations.Public Member FunctionsThe following public member functions are declared:<strong>of</strong>stream();<strong>of</strong>stream( char const *,ios::openmode = ios::out,int = filebuf::openprot );<strong>of</strong>stream( filedesc );<strong>of</strong>stream( filedesc, char *, int );~<strong>of</strong>stream();void open( char const *,ios::openmode = ios::out,int = filebuf::openprot );See Also:fstream, fstreambase, ifstream, ostream748 Input/Output Classes
<strong>of</strong>stream::<strong>of</strong>stream()Synopsis:Semantics:Results:See Also:#include public:<strong>of</strong>stream::<strong>of</strong>stream();This form <strong>of</strong> the public <strong>of</strong>stream constructor creates an <strong>of</strong>stream object that is not connected to afile. The open or attach member functions should be used to connect the <strong>of</strong>stream object to afile.The public <strong>of</strong>stream constructor produces an <strong>of</strong>stream object that is not connected to a file.~<strong>of</strong>streamInput/Output Classes 749
<strong>of</strong>stream::<strong>of</strong>stream()Synopsis:Semantics:Results:See Also:#include public:<strong>of</strong>stream::<strong>of</strong>stream( const char *name,ios::openmode mode = ios::out,int prot = filebuf::openprot );This form <strong>of</strong> the public <strong>of</strong>stream constructor creates an <strong>of</strong>stream object that is connected to thefile specified by the name parameter, using the specified mode and prot parameters. The connection ismade via the C library open function.The public <strong>of</strong>stream constructor produces an <strong>of</strong>stream object that is connected to the filespecified by name. If the open fails, ios::failbit and ios::badbit are set in the error state inthe inherited ios object.~<strong>of</strong>stream, open, fstreambase::close, openmode, openprot750 Input/Output Classes
<strong>of</strong>stream::<strong>of</strong>stream()Synopsis:Semantics:Results:See Also:#include public:<strong>of</strong>stream::<strong>of</strong>stream( filedesc hdl );This form <strong>of</strong> the public <strong>of</strong>stream constructor creates an <strong>of</strong>stream object that is attached to the filespecified by the hdl parameter.The public <strong>of</strong>stream constructor produces an <strong>of</strong>stream object that is attached to hdl. If the attachfails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.~<strong>of</strong>stream, fstreambase::attach, fstreambase::fdInput/Output Classes 751
<strong>of</strong>stream::<strong>of</strong>stream()Synopsis:Semantics:Results:See Also:#include public:<strong>of</strong>stream::<strong>of</strong>stream( filedesc hdl, char *buf, int len );This form <strong>of</strong> the public <strong>of</strong>stream constructor creates an <strong>of</strong>stream object that is connected to thefile specified by the hdl parameter. The buffer specified by the buf and len parameters is <strong>of</strong>fered to theassociated filebuf object via the setbuf member function. If the buf parameter is NULL or the lenis less than or equal to zero, the filebuf is unbuffered, so that each read or write operation reads orwrites a single character at a time.The public <strong>of</strong>stream constructor produces an <strong>of</strong>stream object that is attached to hdl. If theconnection to hdl fails, ios::failbit and ios::badbit are set in the error state in the inheritedios object. If the setbuf fails, ios::failbit is set in the error state in the inherited ios object.~<strong>of</strong>stream, fstreambase::attach, fstreambase::fd, fstreambase::setbuf752 Input/Output Classes
<strong>of</strong>stream::~<strong>of</strong>stream()Synopsis:Semantics:Results:See Also:#include public:<strong>of</strong>stream::~<strong>of</strong>stream();The public ~<strong>of</strong>stream destructor does not do anything explicit. The call to the public ~<strong>of</strong>streamdestructor is inserted implicitly by the compiler at the point where the <strong>of</strong>stream object goes out <strong>of</strong>scope.The public ~<strong>of</strong>stream destructor destroys the <strong>of</strong>stream object.<strong>of</strong>streamInput/Output Classes 753
<strong>of</strong>stream::open()Synopsis:Semantics:Results:See Also:#include public:void <strong>of</strong>stream::open( const char *name,ios::openmode mode = ios::out,int prot = filebuf::openprot );The open public member function connects the <strong>of</strong>stream object to the file specified by the nameparameter, using the specified mode and prot parameters. The mode parameter is optional and usuallyis not specified unless additional bits (such as ios::binary or ios::text) are to be specified.The connection is made via the C library open function.If the open fails, ios::failbit is set in the error state in the inherited ios object.<strong>of</strong>stream, openmode, openprot, fstreambase::attach, fstreambase::close,fstreambase::fd, fstreambase::is_open754 Input/Output Classes
ostreamDeclared:iostream.hDerived from: iosDerived by:iostream, <strong>of</strong>stream, ostrstreamThe ostream class supports writing characters to a class derived from the streambuf class, andprovides formatted conversion <strong>of</strong> types (such as integers and floating-point numbers) into characters.The class derived from the streambuf class provides the methods for communicating with theexternal device (screen, disk), while the ostream class provides the conversion <strong>of</strong> the types intocharacters.Generally, ostream objects won’t be explicitly created by a program, since there is no mechanism atthis level to open a device. The only default ostream objects in a program are cout, cerr, andclog which write to the standard output and error devices (usually the screen).The ostream class supports two basic concepts <strong>of</strong> output: formatted and unformatted. Theoverloaded operator
ostreamostream &operator
ostream::flush()Synopsis:Semantics:Results:See Also:#include public:ostream &ostream::flush();The flush public member function causes the ostream object’s buffers to be flushed, forcing thecontents to be written to the actual device connected to the ostream object.The flush public member function returns a reference to the ostream object. On failure,ios::failbit is set in the error state in the inherited ios object.ostream::osfxInput/Output Classes 757
ostream::operator
ostream::operator
ostream::operator
ostream::operator
ostream::operator
ostream::operator
ostream::operator
ostream::operator =()Synopsis:Semantics:Results:#include public:ostream &ostream::operator =( streambuf *sb );This form <strong>of</strong> the operator = public member function is used to associate a streambuf object,specified by the sb parameter, with an existing ostream object. The ostream object is initializedand will use the specified streambuf object for subsequent operations.This form <strong>of</strong> the operator = public member function returns a reference to the ostream object thatis the target <strong>of</strong> the assignment. If the sb parameter is NULL, ios::badbit is set in the error state inthe inherited ios object.Input/Output Classes 765
ostream::operator =()Synopsis:Semantics:Results:#include public:ostream &ostream::operator =( const ostream &ostrm );This form <strong>of</strong> the operator = public member function is used to associate the ostream object withthe streambuf object currently associated with the ostrm parameter. The ostream object isinitialized and will use the ostrm’s streambuf object for subsequent operations. The ostrm objectwill continue to use the streambuf object.This form <strong>of</strong> the operator = public member function returns a reference to the ostream object thatis the target <strong>of</strong> the assignment. If there is no streambuf object currently associated with the ostrmparameter, ios::badbit is set in the error state in the inherited ios object.766 Input/Output Classes
ostream::opfx()Synopsis:Semantics:#include public:int ostream::opfx();If opfx public member function is a prefix function executed before each <strong>of</strong> the formatted andunformatted output operations. If any bits are set in ios::iostate, the opfx public memberfunction immediately returns zero, indicating that the prefix function failed. Failure in the prefixfunction causes the output operation to fail.If the ostream object is tied to another ostream object, the other ostream object is flushed.Results:See Also:The opfx public member function returns a non-zero value on success, otherwise zero is returned.ostream::osfx, flush, ios::tieInput/Output Classes 767
ostream::osfx()Synopsis:Semantics:#include public:void ostream::osfx();The osfx public member function is a suffix function executed at the end <strong>of</strong> each <strong>of</strong> the formatted andunformatted output operations.If the ios::unitbuf bit is set in ios::fmtflags, the flush member function is called. If theios::stdio bit is set in ios::fmtflags, the C library fflush function is invoked on thestdout and stderr file streams.See Also:ostream::osfx, flush768 Input/Output Classes
ostream::ostream()Synopsis:Semantics:#include protected:ostream::ostream();This form <strong>of</strong> the protected ostream constructor creates an ostream object without an attachedstreambuf object.This form <strong>of</strong> the protected ostream constructor is only used implicitly by the compiler when itgenerates a constructor for a derived class.Results:See Also:This form <strong>of</strong> the protected ostream constructor creates an initialized ostream object.ios::badbit is set in the error state in the inherited ios object.~ostreamInput/Output Classes 769
ostream::ostream()Synopsis:Semantics:Results:See Also:#include public:ostream::ostream( ostream const &ostrm );This form <strong>of</strong> the public ostream constructor creates an ostream object associated with thestreambuf object currently associated with the ostrm parameter. The ostream object is initializedand will use the ostrm’s streambuf object for subsequent operations. The ostrm object will continueto use the streambuf object.This form <strong>of</strong> the public ostream constructor creates an initialized ostream object. If there is nostreambuf object currently associated with the ostrm parameter, ios::badbit is set in the errorstate in the inherited ios object.~ostream770 Input/Output Classes
ostream::ostream()Synopsis:Semantics:#include public:ostream::ostream( streambuf *sb );This form <strong>of</strong> the public ostream constructor creates an ostream object with an associatedstreambuf object specified by the sb parameter.This function is likely to be used for the creation <strong>of</strong> an ostream object that is associated with the samestreambuf object as another ostream object.Results:See Also:This form <strong>of</strong> the public ostream constructor creates an initialized ostream object. If the sbparameter is NULL, ios::badbit is set in the error state in the inherited ios object.~ostreamInput/Output Classes 771
ostream::~ostream()Synopsis:Semantics:Results:See Also:#include public:virtual ostream::~ostream();The public virtual ~ostream destructor does not do anything explicit. The ios destructor is calledfor that portion <strong>of</strong> the ostream object. The call to the public virtual ~ostream destructor is insertedimplicitly by the compiler at the point where the ostream object goes out <strong>of</strong> scope.The ostream object is destroyed.ostream772 Input/Output Classes
ostream::put()Synopsis:Semantics:Results:See Also:#include public:ostream &ostream::put( char ch );ostream &ostream::put( signed char ch );ostream &ostream::put( unsigned char ch );These forms <strong>of</strong> the put public member function write the ch character to the ostream object.These forms <strong>of</strong> the put public member function return a reference to the ostream object. If an erroroccurs, ios::failbit is set in the error state in the inherited ios object.ostream::operator
ostream::seekp()Synopsis:Semantics:#include public:ostream &ostream::seekp( streampos pos );This from <strong>of</strong> the seekp public member function positions the ostream object to the positionspecified by the pos parameter so that the next output operation commences from that position.The pos value is an absolute position within the stream. It may be obtained via a call to the tellpmember function.Results:See Also:This from <strong>of</strong> the seekp public member function returns a reference to the ostream object. If theseek operation fails, ios::failbit is set in the error state in the inherited ios object.ostream::tellp, istream::tellg, istream::seekg774 Input/Output Classes
ostream::seekp()Synopsis:Semantics:#include public:ostream &ostream::seekp( stream<strong>of</strong>f <strong>of</strong>fset, ios::seekdir dir );This from <strong>of</strong> the seekp public member function positions the ostream object to the specifiedposition so that the next output operation commences from that position.The dir parameter may be ios::beg, ios::cur, or ios::end and is interpreted in conjunctionwith the <strong>of</strong>fset parameter as follows:ios::beg the <strong>of</strong>fset is relative to the start and should be a positive value.ios::cur the <strong>of</strong>fset is relative to the current position and may be positive(seek towards end) or negative (seek towards start).ios::end the <strong>of</strong>fset is relative to the end and should be a negative value.If the dir parameter has any other value, or the <strong>of</strong>fset parameter does not have an appropriate sign, theseekp public member function fails.Results:See Also:This from <strong>of</strong> the seekp public member function returns a reference to the ostream object. If theseek operation fails, ios::failbit is set in the error state in the inherited ios object.ostream::tellp, istream::tellg, istream::seekgInput/Output Classes 775
ostream::tellp()Synopsis:Semantics:Results:See Also:#include public:streampos ostream::tellp();The tellp public member function returns the position in the ostream object at which the nextcharacter will be written. The first character in an ostream object is at <strong>of</strong>fset zero.The tellp public member function returns the position in the ostream object at which the nextcharacter will be written.ostream::seekp, istream::tellg, istream::seekg776 Input/Output Classes
ostream::write()Synopsis:Semantics:Results:#include public:ostream &ostream::write( char const *buf, int len );ostream &ostream::write( signed char const *buf, int len );ostream &ostream::write( unsigned char const *buf, int len );The write public member function performs an unformatted write <strong>of</strong> the characters specified by thebuf and len parameters into the ostream object.These member functions return a reference to the ostream object. If an error occurs,ios::failbit is set in the error state in the inherited ios object.Input/Output Classes 777
ostrstreamDeclared:strstrea.hDerived from: strstreambase, ostreamThe ostrstream class is used to create and write to string stream objects.The ostrstream class provides little <strong>of</strong> its own functionality. Derived from the strstreambaseand ostream classes, its constructors and destructor provide simplified access to the appropriateequivalents in those base classes. The member functions provide specialized access to the string streamobject.Of the available I/O stream classes, creating an ostrstream object is the preferred method <strong>of</strong>performing write operations to a string stream.Public Member FunctionsThe following member functions are declared in the public interface:ostrstream();ostrstream( char *, int, ios::openmode = ios::out );ostrstream( signed char *, int, ios::openmode = ios::out );ostrstream( unsigned char *, int, ios::openmode = ios::out );~ostrstream();int pcount() const;char *str();See Also:istrstream, ostream, ostrstream, strstreambase778 Input/Output Classes
ostrstream::ostrstream()Synopsis:Semantics:Results:See Also:#include public:ostrstream::ostrstream();This form <strong>of</strong> the public ostrstream constructor creates an empty ostrstream object. Dynamicallocation is used. The inherited stream member functions can be used to access the ostrstreamobject.This form <strong>of</strong> the public ostrstream constructor creates an initialized, empty ostrstream object.~ostrstreamInput/Output Classes 779
ostrstream::ostrstream()Synopsis:Semantics:Results:See Also:#include public:ostrstream::ostrstream( char *str,int len,ios::openmode mode = ios::out );ostrstream::ostrstream( signed char *str,int len,ios::openmode mode = ios::out );ostrstream::ostrstream( unsigned char *str,int len,ios::openmode mode = ios::out );These forms <strong>of</strong> the public ostrstream constructor create an initialized ostrstream object.Dynamic allocation is not used. The buffer is specified by the str and len parameters. If theios::append or ios::atend bits are set in the mode parameter, the str parameter is assumed tocontain a C string terminated by a null character, and writing commences at the null character.Otherwise, writing commences at str.This form <strong>of</strong> the public ostrstream constructor creates an initialized ostrstream object.~ostrstream780 Input/Output Classes
ostrstream::~ostrstream()Synopsis:Semantics:Results:See Also:#include public:ostrstream::~ostrstream();The public ~ostrstream destructor does not do anything explicit. The call to the public~ostrstream destructor is inserted implicitly by the compiler at the point where the ostrstreamobject goes out <strong>of</strong> scope.The ostrstream object is destroyed.ostrstreamInput/Output Classes 781
ostrstream::pcount()Synopsis:Semantics:Results:#include public:int ostrstream::pcount() const;The pcount public member function computes the number <strong>of</strong> characters that have been written to theostrstream object. This value is particularly useful if the ostrstream object does not contain a Cstring (terminated by a null character), so that the number <strong>of</strong> characters cannot be determined with the Clibrary strlen function. If the ostrstream object was created by appending to a C string in a staticbuffer, the length <strong>of</strong> the original string is included in the character count.The pcount public member function returns the number <strong>of</strong> characters contained in the ostrstreamobject.782 Input/Output Classes
ostrstream::str()Synopsis:Semantics:#include public:char *ostrstream::str();The str public member function creates a pointer to the buffer being used by the ostrstreamobject. If the ostrstream object was created without dynamic allocation (static mode), the pointer isthe same as the buffer pointer passed in the constructor.For ostrstream objects using dynamic allocation, the str public member function makes animplicit call to the strstreambuf::freeze member function. If nothing has been written to theostrstream object, the returned pointer will be NULL.Note that the buffer does not necessarily end with a null character. If the pointer returned by the strpublic member function is to be interpreted as a C string, it is the program’s responsibility to ensure thatthe null character is present.Results:The str public member function returns a pointer to the buffer being used by the ostrstreamobject.Input/Output Classes 783
stdiobufDeclared:stdiobuf.hDerived from: streambufThe stdiobuf class specializes the streambuf class and is used to implement the standardinput/output buffering required for the cin, cout, cerr and clog predefined objects.The stdiobuf class behaves in a similar way to the filebuf class, but does not need to switchbetween the get area and put area, since no stdiobuf object can be created for both reading andwriting. When the get area is empty and a read is done, the underflow virtual member functionreads more characters and fills the get area again. When the put area is full and a write is done, theoverflow virtual member function writes the characters and makes the put area empty again.C++ programmers who wish to use the standard input/output streams without deriving new objects donot need to explicitly create or use a stdiobuf object.Public Member FunctionsThe following member functions are declared in the public interface:stdiobuf();stdiobuf( FILE * );~stdiobuf();virtual int overflow( int = EOF );virtual int underflow();virtual int sync();See Also:streambuf, ios784 Input/Output Classes
stdiobuf::overflow()Synopsis:Semantics:#include public:virtual int stdiobuf::overflow( int ch = EOF );The overflow public virtual member function provides the output communication to the standardoutput and standard error devices to which the stdiobuf object is connected. Member functions inthe streambuf class call the overflow public virtual member function for the derived class whenthe put area is full.The overflow public virtual member function performs the following steps:1. If no buffer is present, a buffer is allocated with the streambuf::allocate memberfunction, which may call the doallocate virtual member function. The put area is thenset up. If, after calling streambuf::allocate, no buffer is present, the stdiobufobject is unbuffered and ch (if not EOF) is written directly to the file without buffering, andno further action is taken.2. If the get area is present, it is flushed with a call to the sync virtual member function. Notethat the get area won’t be present if a buffer was set up in step 1.3. If ch is not EOF, it is added to the put area, if possible.4. Any characters in the put area are written to the file.5. The put area pointers are updated to reflect the new state <strong>of</strong> the put area. If the write did notcomplete, the unwritten portion <strong>of</strong> the put area is still present. If the put area was full beforethe write, ch (if not EOF) is placed at the start <strong>of</strong> the put area. Otherwise, the put area isempty.Results:See Also:The overflow public virtual member function returns __NOT_EOF on success, otherwiseEOF isreturned.stdiobuf::underflow, streambuf::overflowInput/Output Classes 785
stdiobuf::stdiobuf()Synopsis:Semantics:Results:See Also:#include public:stdiobuf::stdiobuf();This form <strong>of</strong> the public stdiobuf constructor creates a stdiobuf object that is initialized but notyet connected to a file.This form <strong>of</strong> the public stdiobuf constructor creates a stdiobuf object.~stdiobuf786 Input/Output Classes
stdiobuf::stdiobuf()Synopsis:Semantics:Results:See Also:#include public:stdiobuf::stdiobuf( FILE *fptr );This form <strong>of</strong> the public stdiobuf constructor creates a stdiobuf object that is initialized andconnected to a C library FILE stream. Usually, one <strong>of</strong> stdin, stdout or stderr is specified for thefptr parameter.This form <strong>of</strong> the public stdiobuf constructor creates a stdiobuf object that is initialized andconnected to a C library FILE stream.~stdiobufInput/Output Classes 787
stdiobuf::~stdiobuf()Synopsis:Semantics:Results:See Also:#include public:stdiobuf::~stdiobuf();The public ~stdiobuf destructor does not do anything explicit. The streambuf destructor iscalled for that portion <strong>of</strong> the stdiobuf object. The call to the public ~stdiobuf destructor isinserted implicitly by the compiler at the point where the stdiobuf object goes out <strong>of</strong> scope.The stdiobuf object is destroyed.stdiobuf788 Input/Output Classes
stdiobuf::sync()Synopsis:Semantics:Results:See Also:#include public:virtual int stdiobuf::sync();The sync public virtual member function synchronizes the stdiobuf object with the associateddevice. If the put area contains characters, it is flushed. If the get area contains buffered characters,the sync public virtual member function fails.The sync public virtual member function returns __NOT_EOF on success, otherwise,EOF is returned.streambuf::syncInput/Output Classes 789
stdiobuf::underflow()Synopsis:Semantics:#include public:virtual int stdiobuf::underflow();The underflow public virtual member function provides the input communication from the standardinput device to which the stdiobuf object is connected. Member functions in the streambuf classcall the underflow public virtual member function for the derived class when the get area is empty.The underflow public virtual member function performs the following steps:1. If no reserve area is present, a buffer is allocated with the streambuf::allocatemember function, which may call the doallocate virtual member function. If, aftercalling allocate, no reserve area is present, the stdiobuf object is unbuffered and aone-character reserve area (plus putback area) is set up to do unbuffered input. This buffer isembedded in the stdiobuf object. The get area is set up as empty.2. The unused part <strong>of</strong> the get area is used to read characters from the file connected to thestdiobuf object. The get area pointers are then set up to reflect the new get area.Results:See Also:The underflow public virtual member function returns the first unread character <strong>of</strong> the get area, onsuccess, otherwise EOF is returned. Note that the get pointer is not advanced on success.stdiobuf::overflow, streambuf::underflow790 Input/Output Classes
streambufDeclared:Derived by:streambu.hfilebuf, stdiobuf, strstreambufThe streambuf class is responsible for maintaining the buffer used to create an efficientimplementation <strong>of</strong> the stream classes. Through its pure virtual functions, it is also responsible for theactual communication with the device associated with the stream.The streambuf class is abstract, due to the presence <strong>of</strong> pure virtual member functions. Abstractclasses may not be instantiated, only inherited. Hence, streambuf objects will not be created by userprograms.Stream objects maintain a pointer to an associated streambuf object and present the interface that theuser deals with most <strong>of</strong>ten. Whenever a stream member function wishes to read or write characters, ituses the rdbuf member function to access the associated streambuf object and its memberfunctions. Through judicious use <strong>of</strong> inline functions, most reads and writes <strong>of</strong> characters access thebuffer directly without even doing a function call. Whenever the buffer gets filled (writing) orexhausted (reading), these inline functions invoke the function required to rectify the situation so thatthe proper action can take place.A streambuf object can be unbuffered, but most <strong>of</strong>ten has one buffer which can be used for bothinput and output operations. The buffer (called the reserve area) is divided into two areas, called theget area and the put area. For a streambuf object being used exclusively to write, the get area isempty or not present. Likewise, a streambuf object being used exclusively for reading has an emptyor non-existent put area.The use <strong>of</strong> the get area and put area differs among the various classes derived from the streambufclass.The filebuf class allows only the get area or the put area, but not both, to be active at a time. Thisfollows from the capability <strong>of</strong> files opened for both reading and writing to have operations <strong>of</strong> each typeperformed at arbitrary locations in the file. When writing is occurring, the characters are buffered in theput area. If a seek or read operation is done, the put area must be flushed before the next operation inorder to ensure that the characters are written to the proper location in the file. Similarly, if reading isoccurring, characters are buffered in the get area. If a write operation is done, the get area must beflushed and synchronized before the write operation in order to ensure the write occurs at the properlocation in the file. If a seek operation is done, the get area does not have to be synchronized, but isdiscarded. When the get area is empty and a read is done, the underflow virtual member functionreads more characters and fills the get area again. When the put area is full and a write is done, theoverflow virtual member function writes the characters and makes the put area empty again.The stdiobuf class behaves in a similar way to the filebuf class, but does not need to switchbetween the get area and put area, since no stdiobuf object can be created for both reading andwriting. When the get area is empty and a read is done, the underflow virtual member functionreads more characters and fills the get area again. When the put area is full and a write is done, theoverflow virtual member function writes the characters and makes the put area empty again.The strstreambuf class differs quite markedly from the filebuf and stdiobuf classes. Sincethere is no actual source or destination for the characters in strstream objects, the buffer itself takeson that role. When writing is occurring and the put area is full, the overflow virtual memberfunction reallocates the buffer to a larger size (if possible), the put area is extended and the writingcontinues. If reading is occurring and the get area is empty, the underflow virtual member functionchecks to see if the put area is present and not empty. If so, the get area is extended to overlap the putarea.Input/Output Classes 791
streambufThe reserve area is marked by two pointer values. The base member function returns the pointer tothe start <strong>of</strong> the buffer. The ebuf member function returns the pointer to the end <strong>of</strong> the buffer (lastcharacter + 1). The setb protected member function is used to set both pointers.Within the reserve area, the get area is marked by three pointer values. The eback member functionreturns a pointer to the start <strong>of</strong> the get area. The egptr member function returns a pointer to the end<strong>of</strong> the get area (last character + 1). The gptr member function returns the get pointer. The get pointeris a pointer to the next character to be extracted from the get area. Characters before the get pointerhave already been consumed by the program, while characters at and after the get pointer have beenread from their source and are buffered and waiting to be read by the program. The setg memberfunction is used to set all three pointer values. If any <strong>of</strong> these pointers are NULL, there is no get area.Also within the reserve area, the put area is marked by three pointer values. The pbase memberfunction returns a pointer to the start <strong>of</strong> the put area. The epptr member function returns a pointer tothe end <strong>of</strong> the put area (last character + 1 ). The pptr member function returns the put pointer. Theput pointer is a pointer to the next available position into which a character may be stored. Charactersbefore the put pointer are buffered and waiting to be written to their final destination, while characterpositions at and after the put pointer have yet to be written by the program. The setp memberfunction is used to set all three pointer values. If any <strong>of</strong> these pointers are NULL, there is no put area.Unbuffered I/O is also possible. If unbuffered, the overflow virtual member function is used to writesingle characters directly to their final destination without using the put area. Similarly, theunderflow virtual member function is used to read single characters directly from their sourcewithout using the get area.Protected Member FunctionsThe following member functions are declared in the protected interface:streambuf();streambuf( char *, int );virtual ~streambuf();int allocate();char *base() const;char *ebuf() const;int blen() const;void setb( char *, char *, int );char *eback() const;char *gptr() const;char *egptr() const;void gbump( stream<strong>of</strong>f );void setg( char *, char *, char *);char *pbase() const;char *pptr() const;char *epptr() const;void pbump( stream<strong>of</strong>f );void setp( char *, char *);int unbuffered( int );int unbuffered() const;virtual int doallocate();Public Member FunctionsThe following member functions are declared in the public interface:int in_avail() const;792 Input/Output Classes
streambufint out_waiting() const;int snextc();int sgetn( char *, int );int speekc();int sgetc();int sgetchar();int sbumpc();void stossc();int sputbackc( char );int sputc( int );int sputn( char const *, int );void dbp();virtual int do_sgetn( char *, int );virtual int do_sputn( char const *, int );virtual int pbackfail( int );virtual int overflow( int = EOF ) = 0;virtual int underflow() = 0;virtual streambuf *setbuf( char *, int );virtual streampos seek<strong>of</strong>f( stream<strong>of</strong>f, ios::seekdir,ios::openmode = ios::in|ios::out );virtual streampos seekpos( streampos,ios::openmode = ios::in|ios::out );virtual int sync();See Also:filebuf, stdiobuf, strstreambufInput/Output Classes 793
streambuf::allocate()Synopsis:Semantics:Results:See Also:#include protected:int streambuf::allocate();The allocate protected member function works in tandem with the doallocate protected virtualmember function to manage allocation <strong>of</strong> the streambuf object reserve area. Classes derived fromthe streambuf class should call the allocate protected member function, rather than thedoallocate protected virtual member function. The allocate protected member functiondetermines whether or not the streambuf object is allowed to allocate a buffer for use as the reservearea. If a reserve area already exists or if the streambuf object unbuffering state is non-zero, theallocate protected member function fails. Otherwise, it calls the doallocate protected virtualmember function.The allocate protected member function returns __NOT_EOF on success, otherwiseEOF isreturned.streambuf::doallocate, underflow, overflow794 Input/Output Classes
streambuf::base()Synopsis:Semantics:#include protected:char *streambuf::base() const;The base protected member function returns a pointer to the start <strong>of</strong> the reserve area that thestreambuf object is using.The reserve area, get area, and put area pointer functions return the following values:base()ebuf()blen()eback()gptr()egptr()pbase()pptr()epptr()start <strong>of</strong> the reserve area.end <strong>of</strong> the reserve area.length <strong>of</strong> the reserve area.start <strong>of</strong> the get area.the get pointer.end <strong>of</strong> the get area.start <strong>of</strong> the put area.the put pointer.end <strong>of</strong> the put area.From eback to gptr are characters buffered and read. From gptr to egptr are characters bufferedbut not yet read. From pbase to pptr are characters buffered and not yet written. From pptr toepptr is unused buffer area.Results:See Also:The base protected member function returns a pointer to the start <strong>of</strong> the reserve area that thestreambuf object is using. If the streambuf object currently does not have a reserve area, NULLis returned.streambuf::blen, ebuf, setbInput/Output Classes 795
streambuf::blen()Synopsis:Semantics:#include protected:int streambuf::blen() const;The blen protected member function reports the length <strong>of</strong> the reserve area that the streambufobject is using.The reserve area, get area, and put area pointer functions return the following values:base()ebuf()blen()eback()gptr()egptr()pbase()pptr()epptr()start <strong>of</strong> the reserve area.end <strong>of</strong> the reserve area.length <strong>of</strong> the reserve area.start <strong>of</strong> the get area.the get pointer.end <strong>of</strong> the get area.start <strong>of</strong> the put area.the put pointer.end <strong>of</strong> the put area.From eback to gptr are characters buffered and read. From gptr to egptr are characters bufferedbut not yet read. From pbase to pptr are characters buffered and not yet written. From pptr toepptr is unused buffer area.Results:See Also:The blen protected member function returns the length <strong>of</strong> the reserve area that the streambufobject is using. If the streambuf object currently does not have a reserve area, zero is returned.streambuf::base, ebuf, setb796 Input/Output Classes
streambuf::dbp()Synopsis:Semantics:#include public:void streambuf::dbp();The dbp public member function dumps information about the streambuf object directly tostdout, and is used for debugging classes derived from the streambuf class.The following is an example <strong>of</strong> what the dbp public member function dumps:STREAMBUF Debug Info:this = 00030679, unbuffered = 0, delete_reserve = 1base = 00070010, ebuf = 00070094eback = 00000000, gptr = 00000000, egptr = 00000000pbase = 00070010, pptr = 00070010, epptr = 00070094Input/Output Classes 797
streambuf::do_sgetn()Synopsis:Semantics:#include public:virtual int do_sgetn( char *buf, int len );The do_sgetn public virtual member function works in tandem with the sgetn member function totransfer len characters from the get area into buf.Classes derived from the streambuf class should call the sgetn member function, rather than thedo_sgetn public virtual member function.Derived Implementation Protocol:Classes derived from the streambuf class that implement the do_sgetn public virtual memberfunction should support copying up to len characters from the source through the get area and into buf.Default Implementation:The default do_sgetn public virtual member function provided with the streambuf class calls theunderflow virtual member function to fetch more characters and then copies the characters from theget area into buf.Results:See Also:The do_sgetn public virtual member function returns the number <strong>of</strong> characters successfullytransferred.streambuf::sgetn798 Input/Output Classes
streambuf::do_sputn()Synopsis:Semantics:#include public:virtual int do_sputn( char const *buf, int len );The do_sputn public virtual member function works in tandem with the sputn member function totransfer len characters from buf to the end <strong>of</strong> the put area and advances the put pointer.Classes derived from the streambuf class should call the sputn member function, rather than thedo_sputn public virtual member function.Derived Implementation Protocol:Classes derived from the streambuf class that implement the do_sputn public virtual memberfunction should support copying up to len characters from buf through the put area and out to thedestination device.Default Implementation:The default do_sputn public virtual member function provided with the streambuf class calls theoverflow virtual member function to flush the put area and then copies the rest <strong>of</strong> the charactersfrom buf into the put area.Results:See Also:The do_sputn public virtual member function returns the number <strong>of</strong> characters successfully written.If an error occurs, this number may be less than len.streambuf::sputnInput/Output Classes 799
streambuf::doallocate()Synopsis:Semantics:#include protected:virtual int streambuf::doallocate();The doallocate protected virtual member function manages allocation <strong>of</strong> the streambuf object’sreserve area in tandem with the allocate protected member function.Classes derived from the streambuf class should call the allocate protected member functionrather than the doallocate protected virtual member function.The doallocate protected virtual member function does the actual memory allocation, and can bedefined for each class derived from the streambuf class.Derived Implementation Protocol:Classes derived from the streambuf class should implement the doallocate protected virtualmember function such that it does the following:1. attempts to allocate an area <strong>of</strong> memory,2. calls the setb protected member function to initialize the reserve area pointers,3. performs any class specific operations required.Default Implementation:The default doallocate protected virtual member function provided with the streambuf classattempts to allocate a buffer area with the operator new intrinsic function. It then calls the setbprotected member function to set up the pointers to the reserve area.Results:See Also:The doallocate protected virtual member function returns __NOT_EOF on success, otherwiseEOFis returned.streambuf::allocate800 Input/Output Classes
streambuf::eback()Synopsis:Semantics:#include protected:char *streambuf::eback() const;The eback protected member function returns a pointer to the start <strong>of</strong> the get area within the reservearea used by the streambuf object.The reserve area, get area, and put area pointer functions return the following values:base()ebuf()blen()eback()gptr()egptr()pbase()pptr()epptr()start <strong>of</strong> the reserve area.end <strong>of</strong> the reserve area.length <strong>of</strong> the reserve area.start <strong>of</strong> the get area.the get pointer.end <strong>of</strong> the get area.start <strong>of</strong> the put area.the put pointer.end <strong>of</strong> the put area.From eback to gptr are characters buffered and read. From gptr to egptr are characters bufferedbut not yet read. From pbase to pptr are characters buffered and not yet written. From pptr toepptr is unused buffer area.Results:See Also:The eback protected member function returns a pointer to the start <strong>of</strong> the get area. If thestreambuf object currently does not have a get area, NULL is returned.streambuf::egptr, gptr, setgInput/Output Classes 801
streambuf::ebuf()Synopsis:Semantics:#include protected:char *streambuf::ebuf() const;The ebuf protected member function returns a pointer to the end <strong>of</strong> the reserve area that thestreambuf object is using. The character pointed at is actually the first character past the end <strong>of</strong> thereserve area.The reserve area, get area, and put area pointer functions return the following values:base()ebuf()blen()eback()gptr()egptr()pbase()pptr()epptr()start <strong>of</strong> the reserve area.end <strong>of</strong> the reserve area.length <strong>of</strong> the reserve area.start <strong>of</strong> the get area.the get pointer.end <strong>of</strong> the get area.start <strong>of</strong> the put area.the put pointer.end <strong>of</strong> the put area.From eback to gptr are characters buffered and read. From gptr to egptr are characters bufferedbut not yet read. From pbase to pptr are characters buffered and not yet written. From pptr toepptr is unused buffer area.Results:See Also:The ebuf protected member function returns a pointer to the end <strong>of</strong> the reserve area. If thestreambuf object currently does not have a reserve area, NULL is returned.streambuf::base, blen, setb802 Input/Output Classes
streambuf::egptr()Synopsis:Semantics:#include protected:char *streambuf::egptr() const;The egptr protected member function returns a pointer to the end <strong>of</strong> the get area within the reservearea used by the streambuf object. The character pointed at is actually the first character past theend <strong>of</strong> the get area.The reserve area, get area, and put area pointer functions return the following values:base()ebuf()blen()eback()gptr()egptr()pbase()pptr()epptr()start <strong>of</strong> the reserve area.end <strong>of</strong> the reserve area.length <strong>of</strong> the reserve area.start <strong>of</strong> the get area.the get pointer.end <strong>of</strong> the get area.start <strong>of</strong> the put area.the put pointer.end <strong>of</strong> the put area.From eback to gptr are characters buffered and read. From gptr to egptr are characters bufferedbut not yet read. From pbase to pptr are characters buffered and not yet written. From pptr toepptr is unused buffer area.Results:See Also:The egptr protected member function returns a pointer to the end <strong>of</strong> the get area. If the streambufobject currently does not have a get area, NULL is returned.streambuf::eback, gptr, setgInput/Output Classes 803
streambuf::epptr()Synopsis:Semantics:#include protected:char *streambuf::epptr() const;The epptr protected member function returns a pointer to the end <strong>of</strong> the put area within the reservearea used by the streambuf object. The character pointed at is actually the first character past theend <strong>of</strong> the put area.The reserve area, get area, and put area pointer functions return the following values:base()ebuf()blen()eback()gptr()egptr()pbase()pptr()epptr()start <strong>of</strong> the reserve area.end <strong>of</strong> the reserve area.length <strong>of</strong> the reserve area.start <strong>of</strong> the get area.the get pointer.end <strong>of</strong> the get area.start <strong>of</strong> the put area.the put pointer.end <strong>of</strong> the put area.From eback to gptr are characters buffered and read. From gptr to egptr are characters bufferedbut not yet read. From pbase to pptr are characters buffered and not yet written. From pptr toepptr is unused buffer area.Results:See Also:The epptr protected member function returns a pointer to the end <strong>of</strong> the put area. If the streambufobject currently does not have a put area, NULL is returned.streambuf::pbase, pptr, setp804 Input/Output Classes
streambuf::gbump()Synopsis:Semantics:Results:See Also:#include protected:void streambuf::gbump( stream<strong>of</strong>f <strong>of</strong>fset );The gbump protected member function increments the get pointer by the specified <strong>of</strong>fset, withoutregard for the boundaries <strong>of</strong> the get area. The <strong>of</strong>fset parameter may be positive or negative.The gbump protected member function returns nothing.streambuf::gptr, pbump, sbumpc, sputbackcInput/Output Classes 805
streambuf::gptr()Synopsis:Semantics:#include protected:char *streambuf::gptr() const;The gptr protected member function returns a pointer to the next available character in the get areawithin the reserve area used by the streambuf object. This pointer is called the get pointer.If the get pointer points beyond the end <strong>of</strong> the get area, all characters in the get area have been read bythe program and a subsequent read causes the underflow virtual member function to be called t<strong>of</strong>etch more characters from the source to which the streambuf object is attached.The reserve area, get area, and put area pointer functions return the following values:base()ebuf()blen()eback()gptr()egptr()pbase()pptr()epptr()start <strong>of</strong> the reserve area.end <strong>of</strong> the reserve area.length <strong>of</strong> the reserve area.start <strong>of</strong> the get area.the get pointer.end <strong>of</strong> the get area.start <strong>of</strong> the put area.the put pointer.end <strong>of</strong> the put area.From eback to gptr are characters buffered and read. From gptr to egptr are characters bufferedbut not yet read. From pbase to pptr are characters buffered and not yet written. From pptr toepptr is unused buffer area.Results:See Also:The gptr protected member function returns a pointer to the next available character in the get area.If the streambuf object currently does not have a get area, NULL is returned.streambuf::eback, egptr, setg806 Input/Output Classes
streambuf::in_avail()Synopsis:Semantics:Results:See Also:#include public:int streambuf::in_avail() const;The in_avail public member function computes the number <strong>of</strong> input characters buffered in the getarea that have not yet been read by the program. These characters can be read with a guarantee that noerrors will occur.The in_avail public member function returns the number <strong>of</strong> buffered input characters.streambuf::egptr, gptrInput/Output Classes 807
streambuf::out_waiting()Synopsis:Semantics:Results:See Also:#include public:int streambuf::out_waiting() const;The out_waiting public member function computes the number <strong>of</strong> characters that have beenbuffered in the put area and not yet been written to the output device.The out_waiting public member function returns the number <strong>of</strong> buffered output characters.streambuf::pbase, pptr808 Input/Output Classes
streambuf::overflow()Synopsis:Semantics:#include public:virtual int streambuf::overflow( int ch = EOF ) = 0;The overflow public virtual member function is used to flush the put area when it is full.Derived Implementation Protocol:Classes derived from the streambuf class should implement the overflow public virtual memberfunction so that it performs the following:1. if no reserve area is present and the streambuf object is not unbuffered, allocate a reservearea using the allocate member function and set up the reserve area pointers using thesetb protected member function,2. flush any other uses <strong>of</strong> the reserve area,3. write any characters in the put area to the streambuf object’s destination,4. set up the put area pointers to reflect the characters that were written,5. return __NOT_EOF on success, otherwise returnEOF.Default Implementation:There is no default streambuf class implementation <strong>of</strong> the overflow public virtual memberfunction. The overflow public virtual member function must be defined for all classes derived fromthe streambuf class.Results:See Also:The overflow public virtual member function returns __NOT_EOF on success, otherwiseEOF isreturned.filebuf::overflow, stdiobuf::overflow, strstreambuf::overflowInput/Output Classes 809
streambuf::pbackfail()Synopsis:Semantics:#include public:virtual int streambuf::pbackfail( int ch );The pbackfail public virtual member function is called by the sputbackc member function whenthe get pointer is at the beginning <strong>of</strong> the get area, and so there is no place to put the ch parameter.Derived Implementation Protocol:Classes derived from the streambuf class should implement the pbackfail public virtual memberfunction such that it attempts to put ch back into the source <strong>of</strong> the stream.Default Implementation:The default streambuf class implementation <strong>of</strong> the pbackfail public virtual member function isto return EOF.Results:If the pbackfail public virtual member function succeeds, it returns ch. Otherwise, EOF is returned.810 Input/Output Classes
streambuf::pbase()Synopsis:Semantics:#include protected:char *streambuf::pbase() const;The pbase protected member function returns a pointer to the start <strong>of</strong> the put area within the reservearea used by the streambuf object.The reserve area, get area, and put area pointer functions return the following values:base()ebuf()blen()eback()gptr()egptr()pbase()pptr()epptr()start <strong>of</strong> the reserve area.end <strong>of</strong> the reserve area.length <strong>of</strong> the reserve area.start <strong>of</strong> the get area.the get pointer.end <strong>of</strong> the get area.start <strong>of</strong> the put area.the put pointer.end <strong>of</strong> the put area.From eback to gptr are characters buffered and read. From gptr to egptr are characters bufferedbut not yet read. From pbase to pptr are characters buffered and not yet written. From pptr toepptr is unused buffer area.Results:See Also:The pbase protected member function returns a pointer to the start <strong>of</strong> the put area. If thestreambuf object currently does not have a put area, NULL is returned.streambuf::epptr, pptr, setpInput/Output Classes 811
streambuf::pbump()Synopsis:Semantics:Results:See Also:#include protected:void streambuf::pbump( stream<strong>of</strong>f <strong>of</strong>fset );The pbump protected member function increments the put pointer by the specified <strong>of</strong>fset, withoutregard for the boundaries <strong>of</strong> the put area. The <strong>of</strong>fset parameter may be positive or negative.The pbump protected member function returns nothing.streambuf::gbump, pbase, pptr812 Input/Output Classes
streambuf::pptr()Synopsis:Semantics:#include protected:char *streambuf::pptr() const;The pptr protected member function returns a pointer to the next available space in the put area withinthe reserve area used by the streambuf object. This pointer is called the put pointer.If the put pointer points beyond the end <strong>of</strong> the put area, the put area is full and a subsequent writecauses the overflow virtual member function to be called to empty the put area to the device towhich the streambuf object is attached.The reserve area, get area, and put area pointer functions return the following values:base()ebuf()blen()eback()gptr()egptr()pbase()pptr()epptr()start <strong>of</strong> the reserve area.end <strong>of</strong> the reserve area.length <strong>of</strong> the reserve area.start <strong>of</strong> the get area.the get pointer.end <strong>of</strong> the get area.start <strong>of</strong> the put area.the put pointer.end <strong>of</strong> the put area.From eback to gptr are characters buffered and read. From gptr to egptr are characters bufferedbut not yet read. From pbase to pptr are characters buffered and not yet written. From pptr toepptr is unused buffer area.Results:See Also:The pptr protected member function returns a pointer to the next available space in the put area. Ifthe streambuf object currently does not have a put area, NULL is returned.streambuf::epptr, pbase, setpInput/Output Classes 813
streambuf::sbumpc()Synopsis:Semantics:#include public:int streambuf::sbumpc();The sbumpc public member function extracts the next available character from the get area andadvances the get pointer. If no character is available, it calls the underflow virtual member functionto fetch more characters from the source into the get area.Due to the sbumpc member functions’s awkward name, the sgetchar member function was addedto take its place in the WATCOM implementation.Results:See Also:The sbumpc public member function returns the next available character in the get area. If nocharacter is available, EOF is returned.streambuf::gbump, sgetc, sgetchar, sgetn, snextc, sputbackc814 Input/Output Classes
streambuf::seek<strong>of</strong>f()Synopsis:Semantics:#include public:virtual streampos streambuf::seek<strong>of</strong>f( stream<strong>of</strong>f <strong>of</strong>fset,ios::seekdir dir,ios::openmode mode );The seek<strong>of</strong>f public virtual member function is used for positioning to a relative location within thestreambuf object, and hence within the device that is connected to the streambuf object. The<strong>of</strong>fset and dir parameters specify the relative change in position. The mode parameter controls whetherthe get pointer and/or the put pointer are repositioned.Derived Implementation Protocol:Classes derived from the streambuf class should implement the seek<strong>of</strong>f virtual member functionso that it uses its parameters in the following way.The mode parameter may be ios::in, ios::out, or ios::in|ios::out and should beinterpreted as follows, provided the interpretation is meaningful:ios::inios::outios::in|ios::outthe get pointer should be moved.the put pointer should be moved.both the get pointer and the put pointer should be moved.If mode has any other value, the seek<strong>of</strong>f public virtual member function fails.The dir parameter may be ios::beg, ios::cur, or ios::end and is interpreted in conjunctionwith the <strong>of</strong>fset parameter as follows:ios::beg the <strong>of</strong>fset is relative to the start and should be a positive value.ios::cur the <strong>of</strong>fset is relative to the current position and may be positive(seek towards end) or negative (seek towards start).ios::end the <strong>of</strong>fset is relative to the end and should be a negative value.If the dir parameter has any other value, or the <strong>of</strong>fset parameter does not have an appropriate sign, theseek<strong>of</strong>f public virtual member function fails.Default Implementation:The default implementation <strong>of</strong> the seek<strong>of</strong>f public virtual member function provided by thestreambuf class returns EOF.Results:See Also:The seek<strong>of</strong>f public virtual member function returns the new position in the stream on success,otherwise EOF is returned.streambuf::seekposInput/Output Classes 815
streambuf::seekpos()Synopsis:Semantics:#include public:virtual streampos streambuf::seekpos( streampos pos,ios::openmode mode = ios::in|ios::out );The seekpos public virtual member function is used for positioning to an absolute location within thestreambuf object, and hence within the device that is connected to the streambuf object. The posparameter specifies the absolute position. The mode parameter controls whether the get pointer and/orthe put pointer are repositioned.Derived Implementation Protocol:Classes derived from the streambuf class should implement the seekpos public virtual memberfunction so that it uses its parameters in the following way.The mode parameter may be ios::in, ios::out, or ios::in|ios::out and should beinterpreted as follows, provided the interpretation is meaningful:ios::inios::outios::in|ios::outthe get pointer should be moved.the put pointer should be moved.both the get pointer and the put pointer should be moved.If mode has any other value, the seekpos public virtual member function fails.In general the seekpos public virtual member function is equivalent to calling the seek<strong>of</strong>f virtualmember function with the <strong>of</strong>fset set to pos, the direction set to ios::beg and the mode set to mode.Default Implementation:The default implementation <strong>of</strong> the seekpos public virtual member function provided by thestreambuf class calls the seek<strong>of</strong>f virtual member function with the <strong>of</strong>fset set to pos, the directionset to ios::beg, and the mode set to mode.Results:See Also:The seekpos public virtual member function returns the new position in the stream on success,otherwise EOF is returned.streambuf::seek<strong>of</strong>f816 Input/Output Classes
streambuf::setb()Synopsis:Semantics:#include protected:void streambuf::setb( char *base, char *ebuf, int autodel );The setb protected member function is used to set the pointers to the reserve area that thestreambuf object is using.The base parameter is a pointer to the start <strong>of</strong> the reserve area and corresponds to the value that thebase member function returns.The ebuf parameter is a pointer to the end <strong>of</strong> the reserve area and corresponds to the value that theebuf member function returns.The autodel parameter indicates whether or not the streambuf object can free the reserve area whenthe streambuf object is destroyed or when a new reserve area is set up in a subsequent call to thesetb protected member function. If the autodel parameter is non-zero, the streambuf object candelete the reserve area, using the operator delete intrinsic function. Otherwise, a zero valueindicates that the buffer will be deleted elsewhere.If either <strong>of</strong> the base or ebuf parameters are NULL or if ebuf
streambuf::setbuf()Synopsis:Semantics:#include public:virtual streambuf *streambuf::setbuf( char *buf, int len );The setbuf public virtual member function is used to <strong>of</strong>fer a buffer specified by the buf and lenparameters to the streambuf object for use as its reserve area. Note that the setbuf public virtualmember function is used to <strong>of</strong>fer a buffer, while the setb protected member function is used to set thereserve area pointers once a buffer has been accepted.Derived Implementation Protocol:Classes derived from the streambuf class may implement the setbuf public virtual memberfunction if the default behavior is not suitable.Derived classes that provide their own implementations <strong>of</strong> the setbuf public virtual member functionmay accept or reject the <strong>of</strong>fered buffer. Often, if a buffer is already allocated, the <strong>of</strong>fered buffer isrejected, as it may be difficult to transfer the information from the current buffer.Default Implementation:The default setbuf public virtual member function provided by the streambuf class rejects thebuffer if one is already present.If no buffer is present and either buf is NULL or len is zero, the <strong>of</strong>fer is accepted and the streambufobject is unbuffered.Otherwise, no buffer is present and one is specified. If len is less than five characters the buffer is toosmall and it is rejected. Otherwise, the buffer is accepted.Results:See Also:The setbuf public virtual member function returns the address <strong>of</strong> the streambuf object if the<strong>of</strong>fered buffer is accepted, otherwise NULL is returned.streambuf::setb818 Input/Output Classes
streambuf::setg()Synopsis:Semantics:#include protected:void streambuf::setg( char *eback, char *gptr, char *egptr );The setg protected member function is used to set the three get area pointers.The eback parameter is a pointer to the start <strong>of</strong> the get area and corresponds to the value that theeback member function returns.The gptr parameter is a pointer to the first available character in the get area, that is, the get pointer, andusually is greater than the eback parameter in order to accommodate a putback area. The gptrparameter corresponds to the value that the gptr member function returns.The egptr parameter is a pointer to the end <strong>of</strong> the get area and corresponds to the value that the egptrmember function returns.If any <strong>of</strong> the three parameters are NULL, there is no get area.See Also:streambuf::eback, egptr, gptrInput/Output Classes 819
streambuf::setp()Synopsis:Semantics:#include protected:void streambuf::setp( char *pbase, char *epptr );The setp protected member function is used to set the three put area pointers.The pbase parameter is a pointer to the start <strong>of</strong> the put area and corresponds to the value that thepbase member function returns.The epptr parameter is a pointer to the end <strong>of</strong> the put area and corresponds to the value that the epptrmember function returns.The put pointer is set to the pbase parameter value and corresponds to the value that the pptr memberfunction returns.If either parameter is NULL, there is no put area.See Also:streambuf::epptr, pbase, pptr820 Input/Output Classes
streambuf::sgetc()Synopsis:Semantics:#include public:int streambuf::sgetc();The sgetc public member function returns the next available character in the get area. The getpointer is not advanced. If the get area is empty, the underflow virtual member function is called t<strong>of</strong>etch more characters from the source into the get area.Due to the sgetc member function’s confusing name (the C library getc function does advance thepointer), the speekc member function was added to take its place in the WATCOM implementation.Results:See Also:The sgetc public member function returns the next available character in the get area. If no characteris available, EOF is returned.streambuf::sbumpc, sgetchar, sgetn, snextc, speekcInput/Output Classes 821
streambuf::sgetchar()Synopsis:Semantics:#include public:int streambuf::sgetchar();The sgetchar public member function extracts the next available character from the get area andadvances the get pointer. If no character is available, it calls the underflow virtual member functionto fetch more characters from the source into the get area.Due to the sbumpc member functions’s awkward name, the sgetchar member function was addedto take its place in the WATCOM implementation.Results:See Also:The sgetchar public member function returns the next available character in the get area. If nocharacter is available, EOF is returned.streambuf::gbump, sgetc, sgetchar, sgetn, snextc, speekc, sputbackc822 Input/Output Classes
streambuf::sgetn()Synopsis:Semantics:#include public:int streambuf::sgetn( char *buf, int len );The sgetn public member function transfers up to len characters from the get area into buf. If thereare not enough characters in the get area, the do_sgetn virtual member function is called to fetchmore.Classes derived from the streambuf class should call the sgetn public member function, rather thanthe do_sgetn virtual member function.Results:See Also:The sgetn public member function returns the number <strong>of</strong> characters transferred from the get area intobuf.streambuf::do_sgetn, sbumpc, sgetc, sgetchar, speekcInput/Output Classes 823
streambuf::snextc()Synopsis:Semantics:#include public:int streambuf::snextc();The snextc public member function advances the get pointer and then returns the character followingthe get pointer. The get pointer is left pointing at the returned character.If the get pointer cannot be advanced, the underflow virtual member function is called to fetch morecharacters from the source into the get area.Results:See Also:The snextc public member function advances the get pointer and returns the next available characterin the get area. If there is no next available character, EOF is returned.streambuf::sbumpc, sgetc, sgetchar, sgetn, speekc824 Input/Output Classes
streambuf::speekc()Synopsis:Semantics:#include public:int streambuf::speekc();The speekc public member function returns the next available character in the get area. The getpointer is not advanced. If the get area is empty, the underflow virtual member function is called t<strong>of</strong>etch more characters from the source into the get area.Due to the sgetc member function’s confusing name (the C library getc function does advance thepointer), the speekc member function was added to take its place in the WATCOM implementation.Results:See Also:The speekc public member function returns the next available character in the get area. If nocharacter is available, EOF is returned.streambuf::sbumpc, sgetc, sgetchar, sgetn, snextcInput/Output Classes 825
streambuf::sputbackc()Synopsis:Semantics:Results:See Also:#include public:int streambuf::sputbackc( char ch );The sputbackc public member function is used to put a character back into the get area. The chcharacter specified must be the same as the character before the get pointer, otherwise the behavior isundefined. The get pointer is backed up by one position. At least four characters may be put backwithout any intervening reads.The sputbackc public member function returns ch on success, otherwise EOF is returned.streambuf::gbump, sbumpc, sgetchar826 Input/Output Classes
streambuf::sputc()Synopsis:Semantics:Results:See Also:#include public:int streambuf::sputc( int ch );The sputc public member function adds the character ch to the end <strong>of</strong> the put area and advances theput pointer. If the put area is full before the character is added, the overflow virtual memberfunction is called to empty the put area and write the character.The sputc public member function returns ch on success, otherwise EOF is returned.streambuf::sgetc, sputnInput/Output Classes 827
streambuf::sputn()Synopsis:Semantics:#include public:int streambuf::sputn( char const *buf, int len );The sputn public member function transfers up to len characters from buf to the end <strong>of</strong> the put areaand advance the put pointer. If the put area is full or becomes full and more characters are to bewritten, the do_sputn virtual member function is called to empty the put area and finish writing thecharacters.Classes derived from the streambuf class should call the sputn public member function, rather thanthe do_sputn virtual member function.Results:See Also:The sputn public member function returns the number <strong>of</strong> characters successfully written. If an erroroccurs, this number may be less than len.streambuf::do_sputn, sputc828 Input/Output Classes
streambuf::stossc()Synopsis:Semantics:See Also:#include public:void streambuf::stossc();The stossc public member function advances the get pointer by one without returning a character. Ifthe get area is empty, the underflow virtual member function is called to fetch more characters andthen the get pointer is advanced.streambuf::gbump, sbumpc, sgetchar, snextcInput/Output Classes 829
streambuf::streambuf()Synopsis:Semantics:Results:See Also:#include protected:streambuf::streambuf();This form <strong>of</strong> the protected streambuf constructor creates an empty streambuf object with allfields initialized to zero. No reserve area is yet allocated, but the streambuf object is bufferedunless a subsequent call to the setbuf or unbuffered member functions dictate otherwise.This form <strong>of</strong> the protected streambuf constructor creates an initialized streambuf object with noassociated reserve area.~streambuf830 Input/Output Classes
streambuf::streambuf()Synopsis:Semantics:Results:See Also:#include protected:streambuf::streambuf( char *buf, int len );This form <strong>of</strong> the protected streambuf constructor creates an empty streambuf object with allfields initialized to zero. The buf and len parameters are passed to the setbuf member function,which sets up the buffer (if specified), or makes the streambuf object unbuffered (if the bufparameter is NULL or the len parameter is not positive).This form <strong>of</strong> the protected streambuf constructor creates an initialized streambuf object with anassociated reserve area.~streambuf, setbufInput/Output Classes 831
streambuf::~streambuf()Synopsis:Semantics:Results:See Also:#include protected:virtual streambuf::~streambuf();The streambuf object is destroyed. If the buffer was allocated by the streambuf object, it is freed.Otherwise, the buffer is not freed and must be freed by the user <strong>of</strong> the streambuf object. The call tothe protected ~streambuf destructor is inserted implicitly by the compiler at the point where thestreambuf object goes out <strong>of</strong> scope.The streambuf object is destroyed.streambuf832 Input/Output Classes
streambuf::sync()Synopsis:Semantics:#include public:virtual int streambuf::sync();The sync public virtual member function is used to synchronize the streambuf object’s get areaand put area with the associated device.Derived Implementation Protocol:Classes derived from the streambuf class should implement the sync public virtual memberfunction such that it attempts to perform the following:1. flush the put area,2. discard the contents <strong>of</strong> the get area and reposition the stream device so that the discardedcharacters may be read again.Default Implementation:The default implementation <strong>of</strong> the sync public virtual member function provided by the streambufclass takes no action. It succeeds if the get area and the put area are empty, otherwise it fails.Results:The sync public virtual member function returns __NOT_EOF on success, otherwiseEOF is returned.Input/Output Classes 833
streambuf::unbuffered()Synopsis:Semantics:#include protected:int ios::unbuffered() const;int ios::unbuffered( int unbuf );The unbuffered protected member function is used to query and/or set the unbuffering state <strong>of</strong> thestreambuf object. A non-zero unbuffered state indicates that the streambuf object is unbuffered.An unbuffered state <strong>of</strong> zero indicates that the streambuf object is buffered.The first form <strong>of</strong> the unbuffered protected member function is used to query the current unbufferingstate.The second form <strong>of</strong> the unbuffered protected member function is used to set the unbuffering state tounbuf.Note that the unbuffering state only affects the allocate protected member function, which doesnothing if the unbuffering state is non-zero. Setting the unbuffering state to a non-zero value does notmean that future I/O operations will be unbuffered.To determine if current I/O operations are unbuffered, use the base protected member function. Areturn value <strong>of</strong> NULL from the base protected member function indicates that unbuffered I/Ooperations will be used.Results:See Also:The unbuffered protected member function returns the previous unbuffered state.streambuf::allocate, pbase, setbuf834 Input/Output Classes
streambuf::underflow()Synopsis:Semantics:#include public:virtual int streambuf::underflow() = 0;The underflow public virtual member function is used to fill the get area when it is empty.Derived Implementation Protocol:Classes derived from the streambuf class should implement the underflow public virtual memberfunction so that it performs the following:1. if no reserve area is present and the streambuf object is buffered, allocate the reservearea using the allocate member function and set up the reserve area pointers using thesetb protected member function,2. flush any other uses <strong>of</strong> the reserve area,3. read some characters from the streambuf object’s source into the get area,4. set up the get area pointers to reflect the characters that were read,5. return the first character <strong>of</strong> the get area, or EOF if no characters could be read.Default Implementation:There is no default streambuf class implementation <strong>of</strong> the underflow public virtual memberfunction. The underflow public virtual member function must be defined for all classes derived fromthe streambuf class.Results:See Also:The underflow public virtual member function returns the first character read into the get area, orEOF if no characters could be read.filebuf::underflow, stdiobuf::underflow, strstreambuf::underflowInput/Output Classes 835
strstreamDeclared:strstrea.hDerived from: strstreambase, iostreamThe strstream class is used to create and write to string stream objects.The strstream class provides little <strong>of</strong> its own functionality. Derived from the strstreambaseand iostream classes, its constructors and destructor provide simplified access to the appropriateequivalents in those base classes. The member functions provide specialized access to the string streamobject.Of the available I/O stream classes, creating a strstream object is the preferred method <strong>of</strong>performing read and write operations on a string stream.Public Member FunctionsThe following member functions are declared in the public interface:strstream();strstream( char *,int,ios::openmode = ios::in|ios::out );strstream( signed char *,int,ios::openmode = ios::in|ios::out );strstream( unsigned char *,int,ios::openmode = ios::in|ios::out );~strstream();char *str();See Also:istrstream, ostrstream, strstreambase836 Input/Output Classes
strstream::str()Synopsis:Semantics:#include public:char *strstream::str();The str public member function creates a pointer to the buffer being used by the strstream object.If the strstream object was created without dynamic allocation (static mode), the pointer is the sameas the buffer pointer passed in the constructor.For strstream objects using dynamic allocation, the str public member function makes an implicitcall to the strstreambuf::freeze member function. If nothing has been written to thestrstream object, the returned pointer will be NULL.Note that the buffer does not necessarily end with a null character. If the pointer returned by the strpublic member function is to be interpreted as a C string, it is the program’s responsibility to ensure thatthe null character is present.Results:See Also:The str public member function returns a pointer to the buffer being used by the strstream object.strstreambuf::str, strstreambuf::freezeInput/Output Classes 837
strstream::strstream()Synopsis:Semantics:Results:See Also:#include public:strstream::strstream();This form <strong>of</strong> the public strstream constructor creates an empty strstream object. Dynamicallocation is used. The inherited stream member functions can be used to access the strstreamobject. Note that the get pointer and put pointer are not necessarily pointing at the same location, somoving one pointer (e.g. by doing a write) does not affect the location <strong>of</strong> the other pointer.This form <strong>of</strong> the public strstream constructor creates an initialized, empty strstream object.~strstream838 Input/Output Classes
strstream::strstream()Synopsis:Semantics:Results:See Also:#include public:strstream::strstream( char *str,int len,ios::openmode mode );strstream::strstream( signed char *str,int len,ios::openmode mode );strstream::strstream( unsigned char *str,int len,ios::openmode mode );These forms <strong>of</strong> the public strstream constructor create an initialized strstream object. Dynamicallocation is not used. The buffer is specified by the str and len parameters. If the ios::append orios::atend bits are set in the mode parameter, the str parameter is assumed to contain a C stringterminated by a null character, and writing commences at the null character. Otherwise, writingcommences at str. Reading commences at str.This form <strong>of</strong> the public strstream constructor creates an initialized strstream object.~strstreamInput/Output Classes 839
strstream::~strstream()Synopsis:Semantics:Results:See Also:#include public:strstream::~strstream();The public ~strstream destructor does not do anything explicit. The call to the public~strstream destructor is inserted implicitly by the compiler at the point where the strstreamobject goes out <strong>of</strong> scope.The strstream object is destroyed.strstream840 Input/Output Classes
strstreambaseDeclared:strstrea.hDerived from: iosDerived by:istrstream, ostrstream, strstreamThe strstreambase class is a base class that provides common functionality for the three stringstream-based classes, istrstream, ostrstream and strstream. The strstreambase classis derived from the ios class which provides the stream state information. The strstreambaseclass provides constructors for string stream objects and one member function.Protected Member FunctionsThe following member functions are declared in the protected interface:strstreambase();strstreambase( char *, int, char * = 0 );~strstreambase();Public Member FunctionsThe following member function is declared in the public interface:strstreambuf *rdbuf() const;See Also:istrstream, ostrstream, strstream, strstreambufInput/Output Classes 841
strstreambase::rdbuf()Synopsis:Semantics:Results:#include public:strstreambuf *strstreambase::rdbuf() const;The rdbuf public member function creates a pointer to the strstreambuf associated with thestrstreambase object. Since the strstreambuf object is embedded within thestrstreambase object, this function never returns NULL.The rdbuf public member function returns a pointer to the strstreambuf associated with thestrstreambase object.842 Input/Output Classes
strstreambase::strstreambase()Synopsis:Semantics:#include protected:strstreambase::strstreambase();This form <strong>of</strong> the protected strstreambase constructor creates a strstreambase object that isinitialized, but empty. Dynamic allocation is used to store characters. No buffer is allocated. A bufferis be allocated when data is first written to the strstreambase object.This form <strong>of</strong> the protected strstreambase constructor is only used implicitly by the compiler whenit generates a constructor for a derived class.Results:See Also:The protected strstreambase constructor creates an initialized strstreambase object.~strstreambaseInput/Output Classes 843
strstreambase::strstreambase()Synopsis:Semantics:#include protected:strstreambase::strstreambase( char *str,int len,char *pstart );This form <strong>of</strong> the protected strstreambase constructor creates a strstreambase object that isinitialized and uses the buffer specified by the str and len parameters as its reserve area within theassociated strstreambuf object. Dynamic allocation is not used.This form <strong>of</strong> the protected strstreambase constructor is unlikely to be explicitly used, except in themember initializer list for the constructor <strong>of</strong> a derived class.The str, len and pstart parameters are interpreted as follows:1. The buffer starts at str.2. If len is positive, the buffer is len characters long.3. If len is zero, str is a pointer to a C string which is terminated by a null character, and thelength <strong>of</strong> the buffer is the length <strong>of</strong> the string.4. If len is negative, the buffer is unbounded. This last form should be used with extremecaution, since no buffer is truly unlimited in size and it would be easy to write beyond theavailable space.5. If the pstart parameter is NULL, the strstreambase object is read-only.6. Otherwise, pstart divides the buffer into two regions. The get area starts at str and ends atpstart-1. The put area starts at pstart and goes to the end <strong>of</strong> the buffer.Results:See Also:The protected strstreambase constructor creates an initialized strstreambase object.~strstreambase844 Input/Output Classes
strstreambase::~strstreambase()Synopsis:Semantics:Results:See Also:#include protected:strstreambase::~strstreambase();The protected ~strstreambase destructor does not do anything explicit. The call to the protected~strstreambase destructor is inserted implicitly by the compiler at the point where thestrstreambase object goes out <strong>of</strong> scope.The strstreambase object is destroyed.strstreambaseInput/Output Classes 845
strstreambufDeclared:strstrea.hDerived from: streambufThe strstreambuf class is derived from the streambuf class and provides additionalfunctionality required to write characters to and read characters from a string buffer. Read and writeoperations can occur at different positions in the string buffer, since the get pointer and put pointer arenot necessarily connected. Seek operations are also supported.The reserve area used by the strstreambuf object may be either fixed in size or dynamic.Generally, input strings are <strong>of</strong> a fixed size, while output streams are dynamic, since the final size maynot be predictable. For dynamic buffers, the strstreambuf object automatically grows the bufferwhen necessary.The strstreambuf class differs quite markedly from the filebuf and stdiobuf classes. Sincethere is no actual source or destination for the characters in strstream objects, the buffer itself takeson that role. When writing is occurring and the put area is full, the overflow virtual memberfunction reallocates the buffer to a larger size (if possible), the put area is extended and the writingcontinues. If reading is occurring and the get area is empty, the underflow virtual member functionchecks to see if the put area is present and not empty. If so, the get area is extended to overlap the putarea.C++ programmers who wish to use string streams without deriving new objects will probably neverexplicitly create or use a strstreambuf object.Protected Member FunctionsThe following member function is declared in the protected interface:virtual int doallocate();Public Member FunctionsThe following member functions are declared in the public interface:strstreambuf();strstreambuf( int );strstreambuf( void *(*)( long ), void (*)( void * ) );strstreambuf( char *, int, char * = 0 );~strstreambuf();int alloc_size_increment( int );void freeze( int = 1 );char *str();virtual int overflow( int = EOF );virtual int underflow();virtual streambuf *setbuf( char *, int );virtual streampos seek<strong>of</strong>f( stream<strong>of</strong>f,ios::seekdir,ios::openmode );virtual int sync();See Also:streambuf, strstreambase846 Input/Output Classes
strstreambuf::alloc_size_increment()Synopsis:Semantics:#include public:int strstreambuf::alloc_size_increment( int increment );The alloc_size_increment public member function modifies the allocation size used when thebuffer is first allocated or reallocated by dynamic allocation. The increment parameter is added to theprevious allocation size for future use.This function is a WATCOM extension.Results:See Also:The alloc_size_increment public member function returns the previous value <strong>of</strong> the allocationsize.strstreambuf::doallocate, setbufInput/Output Classes 847
strstreambuf::doallocate()Synopsis:Semantics:#include protected:virtual int strstreambuf::doallocate();The doallocate protected virtual member function is called by the allocate member functionwhen it is determined that the put area is full and needs to be extended.The doallocate protected virtual member function performs the following steps:1. If dynamic allocation is not being used, the doallocate protected virtual member functionfails.2. A new size for the buffer is determined. If the allocation size is bigger than the current size,the allocation size is used. Otherwise, the buffer size is increased byDEFAULT_MAINBUF_SIZE, which is 512.3. A new buffer is allocated. If an allocation function was specified in the constructor for thestrstreambuf object, that allocation function is used, otherwise the operator newintrinsic function is used. If the allocation fails, the doallocate protected virtual memberfunction fails.4. If necessary, the contents <strong>of</strong> the get area are copied to the newly allocated buffer and the getarea pointers are adjusted accordingly.5. The contents <strong>of</strong> the put area are copied to the newly allocated buffer and the put areapointers are adjusted accordingly, extending the put area to the end <strong>of</strong> the new buffer.6. The old buffer is freed. If a free function was specified in the constructor for thestrstreambuf object, that free function is used, otherwise the operator deleteintrinsic function is used.Results:See Also:The doallocate protected virtual member function returns __NOT_EOF on success, otherwiseEOFis returned.strstreambuf::alloc_size_increment, setbuf848 Input/Output Classes
strstreambuf::freeze()Synopsis:Semantics:#include public:void strstreambuf::freeze( int frozen = 1 );The freeze public member function enables and disables automatic deletion <strong>of</strong> the reserve area. Ifthe freeze public member function is called with no parameter or a non-zero parameter, thestrstreambuf object is frozen. If the freeze public member function is called with a zeroparameter, the strstreambuf object is unfrozen.A frozen strstreambuf object does not free the reserve area in the destructor. If thestrstreambuf object is destroyed while it is frozen, it is the program’s responsibility to also free thereserve area.If characters are written to the strstreambuf object while it is frozen, the effect is undefined sincethe reserve area may be reallocated and therefore may move. However, if the strstreambuf objectis frozen and then unfrozen, characters may be written to it.Results:See Also:The freeze public member function returns the previous frozen state.strstreambuf::str, ~strstreambufInput/Output Classes 849
strstreambuf::overflow()Synopsis:Semantics:#include public:virtual int strstreambuf::overflow( int ch = EOF );The overflow public virtual member function provides the output communication between thestreambuf member functions and the strstreambuf object. Member functions in thestreambuf class call the overflow public virtual member function when the put area is full. Theoverflow public virtual member function attempts to grow the put area so that writing may continue.The overflow public virtual member function performs the following steps:1. If dynamic allocation is not being used, the put area cannot be extended, so the overflowpublic virtual member function fails.2. If dynamic allocation is being used, a new buffer is allocated using the doallocatemember function. It handles copying the contents <strong>of</strong> the old buffer to the new buffer anddiscarding the old buffer.3. If the ch parameter is not EOF, it is added to the end <strong>of</strong> the extended put area and the putpointer is advanced.Results:See Also:The overflow public virtual member function returns __NOT_EOF when it successfully extends theput area, otherwise EOF is returned.streambuf::overflowstrstreambuf::underflow850 Input/Output Classes
strstreambuf::seek<strong>of</strong>f()Synopsis:Semantics:#include public:virtual streampos strstreambuf::seek<strong>of</strong>f( stream<strong>of</strong>f <strong>of</strong>fset,ios::seekdir dir,ios::openmode mode );The seek<strong>of</strong>f public virtual member function positions the get pointer and/or put pointer to thespecified position in the reserve area. If the get pointer is moved, it is moved to a position relative tothe start <strong>of</strong> the reserve area (which is also the start <strong>of</strong> the get area). If a position is specified that isbeyond the end <strong>of</strong> the get area but is in the put area, the get area is extended to include the put area. Ifthe put pointer is moved, it is moved to a position relative to the start <strong>of</strong> the put area, not relative to thestart <strong>of</strong> the reserve area.The seek<strong>of</strong>f public virtual member function seeks <strong>of</strong>fset bytes from the position specified by the dirparameter.The mode parameter may be ios::in, ios::out, or ios::in|ios::out and should beinterpreted as follows, provided the interpretation is meaningful:ios::inios::outios::in|ios::outthe get pointer should be moved.the put pointer should be moved.both the get pointer and the put pointer should be moved.If mode has any other value, the seek<strong>of</strong>f public virtual member function fails.ios::in|ios::out is not valid if the dir parameter is ios::cur.The dir parameter may be ios::beg, ios::cur, or ios::end and is interpreted in conjunctionwith the <strong>of</strong>fset parameter as follows:ios::beg the <strong>of</strong>fset is relative to the start and should be a positive value.ios::cur the <strong>of</strong>fset is relative to the current position and may be positive(seek towards end) or negative (seek towards start).ios::end the <strong>of</strong>fset is relative to the end and should be a negative value.If the dir parameter has any other value, or the <strong>of</strong>fset parameter does not have an appropriate sign, theseek<strong>of</strong>f public virtual member function fails.Results:The seek<strong>of</strong>f public virtual member function returns the new position in the file on success, otherwiseEOF is returned. If both or ios::in|ios::out are specified and the dir parameter is ios::curthe returned position refers to the put pointer.Input/Output Classes 851
strstreambuf::setbuf()Synopsis:Semantics:#include public:virtual streambuf *strstreambuf::setbuf( char *, int size );The setbuf public virtual member function is used to control the size <strong>of</strong> the allocations when thestrstreambuf object is using dynamic allocation. The first parameter is ignored. The next time anallocation is required, at least the number <strong>of</strong> characters specified in the size parameter is allocated. Ifthe specified size is not sufficient, the allocation reverts to its default behavior, which is to extend thebuffer by DEFAULT_MAINBUF_SIZE, which is 512 characters.If a program is going to write a large number <strong>of</strong> characters to the strstreambuf object, it should callthe setbuf public virtual member function to indicate the size <strong>of</strong> the next allocation, to preventmultiple allocations as the buffer gets larger.Results:See Also:The setbuf public virtual member function returns a pointer to the strstreambuf object.strstreambuf::alloc_size_increment, doallocate852 Input/Output Classes
strstreambuf::str()Synopsis:Semantics:#include public:char *strstreambuf::str();The str public member function freezes the strstreambuf object and returns a pointer to thereserve area. This pointer remains valid after the strstreambuf object is destroyed provided thestrstreambuf object remains frozen, since the destructor does not free the reserve area if it isfrozen.The returned pointer may be NULL if the strstreambuf object is using dynamic allocation but hasnot yet had anything written to it.If the strstreambuf object is not using dynamic allocation, the pointer returned by the str publicmember function is the same buffer pointer provided to the constructor. For a strstreambuf objectusing dynamic allocation, the pointer points to a dynamically allocated area.Note that the reserve area does not necessarily end with a null character. If the pointer returned by thestr public member function is to be interpreted as a C string, it is the program’s responsibility toensure that the null character is present.Results:See Also:The str public member function returns a pointer to the reserve area and freezes the strstreambufobject.strstreambuf::freezeInput/Output Classes 853
strstreambuf::strstreambuf()Synopsis:Semantics:Results:See Also:#include public:strstreambuf::strstreambuf();This form <strong>of</strong> the public strstreambuf constructor creates an empty strstreambuf object thatuses dynamic allocation. No reserve area is allocated to start. Whenever characters are written toextend the strstreambuf object, the reserve area is reallocated and copied as required. The size <strong>of</strong>allocation is determined by the strstreambuf object unless the setbuf oralloc_size_increment member functions are called to change the allocation size. The defaultallocation size is determined by the constant DEFAULT_MAINBUF_SIZE, which is 512.This form <strong>of</strong> the public strstreambuf constructor creates a strstreambuf object.strstreambuf::doallocate, ~strstreambuf854 Input/Output Classes
strstreambuf::strstreambuf()Synopsis:Semantics:#include public:strstreambuf::strstreambuf( int alloc_size );This form <strong>of</strong> the public strstreambuf constructor creates an empty strstreambuf object thatuses dynamic allocation. No buffer is allocated to start. Whenever characters are written to extend thestrstreambuf object, the reserve area is reallocated and copied as required. The size <strong>of</strong> the firstallocation is determined by the alloc_size parameter, unless changed by a call to the setbuf oralloc_size_increment member functions.Note that the alloc_size parameter is the starting reserve area size. When the reserve area isreallocated, the strstreambuf object uses DEFAULT_MAINBUF_SIZE to increase the reserve areasize, unless the setbuf or alloc_size_increment member functions have been called to specifya new allocation size.Results:See Also:This form <strong>of</strong> the public strstreambuf constructor creates a strstreambuf object.strstreambuf::alloc_size_increment, doallocate, setbuf, ~strstreambufInput/Output Classes 855
strstreambuf::strstreambuf()Synopsis:Semantics:#include public:strstreambuf::strstreambuf( void * (*alloc_fn)( long ),void (*free_fn)( void * ) );This form <strong>of</strong> the public strstreambuf constructor creates an empty strstreambuf object thatuses dynamic allocation. No buffer is allocated to start. Whenever characters are written to extend thestrstreambuf object, the reserve area is reallocated and copied as required, using the specifiedalloc_fn and free_fn functions. The size <strong>of</strong> allocation is determined by the class unless the setbuf oralloc_size_increment member functions are called to change the allocation size. The defaultallocation size is determined by the constant DEFAULT_MAINBUF_SIZE, which is 512.When a new reserve area is allocated, the function specified by the alloc_fn parameter is called with along integer value indicating the number <strong>of</strong> bytes to allocate. If alloc_fn is NULL, theoperator new intrinsic function is used. Likewise, when the reserve area is freed, the functionspecified by the free_fn parameter is called with the pointer returned by the alloc_fn function as theparameter. If free_fn is NULL, the operator delete intrinsic function is used.Results:See Also:This form <strong>of</strong> the public strstreambuf constructor creates a strstreambuf object.strstreambuf::alloc_size_increment, doallocate, setbuf, ~strstreambuf856 Input/Output Classes
strstreambuf::strstreambuf()Synopsis:Semantics:#include public:strstreambuf::strstreambuf( char *str,int len,char *pstart = NULL );strstreambuf::strstreambuf( signed char *str,int len,signed char *pstart = NULL );strstreambuf::strstreambuf( unsigned char *str,int len,unsigned char *pstart = NULL );This form <strong>of</strong> the public strstreambuf constructor creates a strstreambuf object that does notuse dynamic allocation (unless str is NULL). The strstreambuf object is said to be using staticallocation. The str and len parameters specify the bounds <strong>of</strong> the reserve area.The str, len and pstart parameters are interpreted as follows:1. The buffer starts at str.2. If len is positive, the buffer is len characters long.3. If len is zero, str is a pointer to a C string which is terminated by a null character, and thelength <strong>of</strong> the buffer is the length <strong>of</strong> the string.4. If len is negative, the buffer is unbounded. This last form should be used with extremecaution, since no buffer is truly unlimited in size and it would be easy to write beyond theavailable space.5. If the pstart parameter is NULL, the strstreambuf object is read-only.6. Otherwise, pstart divides the buffer into two regions. The get area starts at str and ends atpstart-1. The put area starts at pstart and goes to the end <strong>of</strong> the buffer.If the get area is exhausted and characters have been written to the put area, the get area is extended toinclude the put area.The get pointer and put pointer do not necessarily point at the same position in the reserve area, so aread followed by a write does not imply that the write stores following the last character read. The getpointer is positioned following the last read operation, and the put pointer is positioned following thelast write operation, unless the seek<strong>of</strong>f member function has been used to reposition the pointer(s).Note that if str is NULL the effect is to create an empty dynamic strstreambuf object.Results:See Also:This form <strong>of</strong> the public strstreambuf constructor creates a strstreambuf object.~strstreambufInput/Output Classes 857
strstreambuf::~strstreambuf()Synopsis:Semantics:Results:See Also:#include public:strstreambuf::~strstreambuf();The public ~strstreambuf destructor destroys the strstreambuf object after discarding thereserve area. The reserve area is discarded only if the strstreambuf object is using dynamicallocation and is not frozen. The reserve area is freed using the free function specified by the form <strong>of</strong>the constructor that allows specification <strong>of</strong> the allocate and free functions, or using theoperator delete intrinsic function. If the strstreambuf object is frozen or using staticallocation, the user <strong>of</strong> the strstreambuf object must have a pointer to the reserve area and isresponsible for freeing it. The call to the public ~strstreambuf destructor is inserted implicitly bythe compiler at the point where the strstreambuf object goes out <strong>of</strong> scope.The strstreambuf object is destroyed.strstreambuf858 Input/Output Classes
strstreambuf::sync()Synopsis:Semantics:Results:#include public:virtual int strstreambuf::sync();The sync public virtual member function does nothing because there is no external device with whichto synchronize.The sync public virtual member function returns __NOT_EOF.Input/Output Classes 859
strstreambuf::underflow()Synopsis:Semantics:#include public:virtual int strstreambuf::underflow();The underflow public virtual member function provides the input communication between thestreambuf member functions and the strstreambuf object. Member functions in thestreambuf class call the underflow public virtual member function when the get area is empty.If there is a non-empty put area present following the get area, the get area is extended to include theput area, allowing the input operation to continue using the put area. Otherwise the get area cannot beextended.Results:See Also:The underflow public virtual member function returns the first available character in the get area onsuccessful extension, otherwise EOF is returned.streambuf::underflowstrstreambuf::overflow860 Input/Output Classes
19 String ClassThis class is used to store arbitrarily long sequences <strong>of</strong> characters in memory. Objects <strong>of</strong> this type may beconcatenated, substringed, compared and searched without the need for memory management by the user.Unlike a C string, this object has no delimiting character, so any character in the collating sequence, orcharacter set, may be stored in an object.The class documented here is the Open Watcom legacy string class. It is not related to thestd::basic_string class template nor to its corresponding specialization std::string.String Class 861
StringDeclared:string.hppThe String class is used to store arbitrarily long sequences <strong>of</strong> characters in memory. Objects <strong>of</strong> thistype may be concatenated, substringed, compared and searched without the need for memorymanagement by the user. Unlike a C string, a String object has no delimiting character, so anycharacter in the collating sequence, or character set, may be stored in a String object.Public FunctionsThe following constructors and destructors are declared:String();String( size_t, capacity );String( String const &, size_t = 0, size_t = NPOS );String( char const *, size_t = NPOS );String( char, size_t = 1 );~String();The following member functions are declared:operator char const *();operator char() const;String &operator =( String const & );String &operator =( char const * );String &operator +=( String const & );String &operator +=( char const * );String operator ()( size_t, size_t ) const;char &operator ()( size_t );char const &operator []( size_t ) const;char &operator []( size_t );int operator !() const;size_t length() const;char const &get_at( size_t ) const;void put_at( size_t, char );int match( String const & ) const;int match( char const * ) const;int index( String const &, size_t = 0 ) const;int index( char const *, size_t = 0 ) const;String upper() const;String lower() const;int valid() const;int alloc_mult_size() const;int alloc_mult_size( int );The following friend functions are declared:friend int operator ==( String const &, String const & );friend int operator ==( String const &, char const * );friend int operator ==( char const *, String const & );friend int operator ==( String const &, char );friend int operator ==( char , String const & );friend int operator !=( String const &, String const & );friend int operator !=( String const &, char const * );friend int operator !=( char const *, String const & );friend int operator !=( String const &, char );friend int operator !=( char , String const & );friend int operator
Stringfriend int operator =( String const &, char );friend int operator >=( char , String const & );friend String operator +( String &, String const & );friend String operator +( String &, char const * );friend String operator +( char const *, String const & );friend String operator +( String &, char );friend String operator +( char , String const & );friend int valid( String const & );The following I/O Stream inserter and extractor functions are declared:friend istream &operator >>( istream &, String & );friend ostream &operator
String::alloc_mult_size()Synopsis:Semantics:#include public:int String::alloc_mult_size() const;int String::alloc_mult_size( int mult );The alloc_mult_size public member function is used to query and/or change the allocationmultiple size.The first form <strong>of</strong> the alloc_mult_size public member function queries the current setting.The second form <strong>of</strong> the alloc_mult_size public member function sets the value to a multiple <strong>of</strong> 8based on the mult parameter. The value <strong>of</strong> mult is rounded down to a multiple <strong>of</strong> 8 characters. If multis less than 8, the new multiple size is 1 and allocation sizes are exact.The scheme used to store a String object allocates the memory for the characters in multiples <strong>of</strong> somesize. By default, this size is 8 characters. A String object with a length <strong>of</strong> 10 actually has 16characters <strong>of</strong> storage allocated for it. Concatenating more characters on the end <strong>of</strong> the String objectonly allocates a new storage block if more than 6 (16-10) characters are appended. This scheme tries t<strong>of</strong>ind a balance between reallocating frequently (multiples <strong>of</strong> a small value) and creating a large amount<strong>of</strong> unused space (multiples <strong>of</strong> a large value).Results:The alloc_mult_size public member function returns the previous allocation multiple size.864 String Class
String::get_at()Synopsis:Semantics:#include public:char const &String::get_at( size_t pos );The get_at public member function creates a const reference to the character at <strong>of</strong>fset pos within theString object. This reference may not be used to modify that character. The first character <strong>of</strong> aString object is at position zero.If pos is greater than or equal to the length <strong>of</strong> the String object, and the resulting reference is used,the behavior is undefined.The reference is associated with the String object, and therefore has meaning only as long as theString object is not modified (or destroyed). If the String object has been modified and an oldreference is used, the behavior is undefined.Results:The get_at public member function returns a const reference to a character.See Also: String::put_at, operator [], operator ()String Class 865
String::index()Synopsis:Semantics:#include public:int String::index( String const &str, size_t pos = 0 ) const;int String::index( char const *pch, size_t pos = 0 ) const;The index public member function computes the <strong>of</strong>fset at which a sequence <strong>of</strong> characters in theString object is found.The first form searches the String object for the contents <strong>of</strong> the str String object.The second form searches the String object for the sequence <strong>of</strong> characters pointed at by pch.If pos is specified, the search begins at that <strong>of</strong>fset from the start <strong>of</strong> the String object. Otherwise, thesearch begins at <strong>of</strong>fset zero (the first character).The index public member function treats upper and lower case letters as not equal.Results:See Also:The index public member function returns the <strong>of</strong>fset at which the sequence <strong>of</strong> characters is found. Ifthe substring is not found, -1 is returned.String::lower, operator !=, operator ==, match, upper866 String Class
String::length()Synopsis:Semantics:Results:#include public:size_t String::length() const;The length public member function computes the number <strong>of</strong> characters contained in the Stringobject.The length public member function returns the number <strong>of</strong> characters contained in the Stringobject.String Class 867
String::lower()Synopsis:Semantics:Results:See Also:#include public:String String::lower() const;The lower public member function creates a String object whose value is the same as the originalobject’s value, except that all upper-case letters have been converted to lower-case.The lower public member function returns a lower-case String object.String::upper868 String Class
String::match()Synopsis:Semantics:#include public:int String::match( String const &str ) const;int String::match( char const *pch ) const;The match public member function compares two character sequences to find the <strong>of</strong>fset where theydiffer.The first form compares the String object to the str String object.The second form compares the String object to the pch C string.The first character is at <strong>of</strong>fset zero. The match public member function treats upper and lower caseletters as not equal.Results:See Also:The match public member function returns the <strong>of</strong>fset at which the two character sequences differ. Ifthe character sequences are equal, -1 is returned.String::index, lower, operator !=, operator ==, upperString Class 869
String::operator !()Synopsis:Semantics:Results:See Also:#include public:int String::operator !() const;The operator ! public member function tests the validity <strong>of</strong> the String object.The operator ! public member function returns a non-zero value if the String object is invalid,otherwise zero is returned.String::valid, valid870 String Class
String operator !=()Synopsis:Semantics:#include public:friend int operator !=( String const &lft, String const &rht );friend int operator !=( String const &lft, char const *rht );friend int operator !=( char const *lft, String const &rht );friend int operator !=( String const &lft, char rht );friend int operator !=( char lft, String const &rht );The operator != function compares two sequences <strong>of</strong> characters in terms <strong>of</strong> an inequalityrelationship.A String object is different from another String object if the lengths are different or they containdifferent sequences <strong>of</strong> characters. A String object and a C string are different if their lengths aredifferent or they contain a different sequence <strong>of</strong> characters. A C string is terminated by a null character.A String object and a character are different if the String object does not contain only thecharacter. Upper-case and lower-case characters are considered different.Results:The operator != function returns a non-zero value if the lengths or sequences <strong>of</strong> characters in the lftand rht parameter are different, otherwise zero is returned.See Also: String::operator ==, operator =String Class 871
String::operator ()()Synopsis:Semantics:#include public:char &String::operator ()( size_t pos );The operator () public member function creates a reference to the character at <strong>of</strong>fset pos within theString object. This reference may be used to modify that character. The first character <strong>of</strong> a Stringobject is at position zero.If pos is greater than or equal to the length <strong>of</strong> the String object, and the resulting reference is used,the behavior is undefined.If the reference is used to modify other characters within the String object, the behavior is undefined.The reference is associated with the String object, and therefore has meaning only as long as theString object is not modified (or destroyed). If the String object has been modified and an oldreference is used, the behavior is undefined.Results:The operator () public member function returns a reference to a character.See Also: String::operator [], operator char, operator char const *872 String Class
String::operator ()()Synopsis:Semantics:#include public:String String::operator ()( size_t pos, size_t len ) const;This form <strong>of</strong> the operator () public member function extracts a sub-sequence <strong>of</strong> characters fromthe String object. A new String object is created that contains the sub-sequence <strong>of</strong> characters.The sub-sequence begins at <strong>of</strong>fset pos within the String object and continues for len characters. Thefirst character <strong>of</strong> a String object is at position zero.If pos is greater than or equal to the length <strong>of</strong> the String object, the result is empty.If len is such that pos + len exceeds the length <strong>of</strong> the object, the result is the sub-sequence <strong>of</strong> charactersfrom the String object starting at <strong>of</strong>fset pos and running to the end <strong>of</strong> the String object.Results:The operator () public member function returns a String object.See Also: String::operator [], operator char, operator char const *String Class 873
String operator +()Synopsis:Semantics:#include public:friend String operator +( String &lft, String const &rht );friend String operator +( String &lft, char const *rht );friend String operator +( char const *lft, String const &rht );friend String operator +( String &lft, char rht );friend String operator +( char lft, String const &rht );The operator + function concatenates two sequences <strong>of</strong> characters into a new String object. Thenew String object contains the sequence <strong>of</strong> characters from the lft parameter followed by thesequence <strong>of</strong> characters from the rht parameter.A NULL pointer to a C string is treated as a pointer to an empty C string.Results:The operator + function returns a new String object that contains the characters from the lftparameter followed by the characters from the rht parameter.See Also: String::operator +=874 String Class
String::operator +=()Synopsis:Semantics:#include public:String &String::operator +=( String const &str );String &String::operator +=( char const *pch );The operator += public member function appends the contents <strong>of</strong> the parameter to the end <strong>of</strong> theString object.The first form <strong>of</strong> the operator += public member function appends the contents <strong>of</strong> the str Stringobject to the String object.The second form appends the null-terminated sequence <strong>of</strong> characters stored at pch to the Stringobject. If the pch parameter is NULL, nothing is appended.Results:The operator += public member function returns a reference to the String object that was thetarget <strong>of</strong> the assignment.See Also: String::operator =String Class 875
String operator
String operator
String operator
String::operator =()Synopsis:Semantics:#include public:String &String::operator =( String const &str );String &String::operator =( char const *pch );The operator = public member function sets the contents <strong>of</strong> the String object to be the same asthe parameter.The first form <strong>of</strong> the operator = public member function sets the value <strong>of</strong> the String object to bethe same as the value <strong>of</strong> the str String object.The second form sets the value <strong>of</strong> the String object to the null-terminated sequence <strong>of</strong> charactersstored at pch. If the pch parameter is NULL, the String object is empty.Results:See Also:The operator = public member function returns a reference to the String object that was thetarget <strong>of</strong> the assignment.String::operator +=, StringString Class 879
String operator ==()Synopsis:Semantics:#include public:friend int operator ==( String const &lft, String const &rht );friend int operator ==( String const &lft, char const *rht );friend int operator ==( char const *lft, String const &rht );friend int operator ==( String const &lft, char rht );friend int operator ==( char lft, String const &rht );The operator == function compares two sequences <strong>of</strong> characters in terms <strong>of</strong> an equalityrelationship.A String object is equal to another String object if they have the same length and they contain thesame sequence <strong>of</strong> characters. A String object and a C string are equal if their lengths are the sameand they contain the same sequence <strong>of</strong> characters. The C string is terminated by a null character. AString object and a character are equal if the String object contains only that character.Upper-case and lower-case characters are considered different.Results:The operator == function returns a non-zero value if the lengths and sequences <strong>of</strong> characters in thelft and rht parameter are identical, otherwise zero is returned.See Also: String::operator !=, operator =880 String Class
String operator >()Synopsis:Semantics:#include public:friend int operator >( String const &lft, String const &rht );friend int operator >( String const &lft, char const *rht );friend int operator >( char const *lft, String const &rht );friend int operator >( String const &lft, char rht );friend int operator >( char lft, String const &rht );The operator > function compares two sequences <strong>of</strong> characters in terms <strong>of</strong> a greater-thanrelationship.lft is greater-than rht if the characters <strong>of</strong> lft occur after the characters <strong>of</strong> rht in the collating sequence.Upper-case and lower-case characters are considered different.Results:The operator > function returns a non-zero value if the lft sequence <strong>of</strong> characters is greater than therht sequence, otherwise zero is returned.See Also: String::operator !=, operator ==, operator
String operator >=()Synopsis:Semantics:#include public:friend int operator >=( String const &lft, String const &rht );friend int operator >=( String const &lft, char const *rht );friend int operator >=( char const *lft, String const &rht );friend int operator >=( String const &lft, char rht );friend int operator >=( char lft, String const &rht );The operator >= function compares two sequences <strong>of</strong> characters in terms <strong>of</strong> a greater-than or equalrelationship.lft is greater-than or equal to rht if the characters <strong>of</strong> lft are equal to or occur after the characters <strong>of</strong> rht inthe collating sequence. Upper-case and lower-case characters are considered different.Results:The operator >= function returns a non-zero value if the lft sequence <strong>of</strong> characters is greater than orequal to the rht sequence, otherwise zero is returned.See Also: String::operator !=, operator ==, operator
String operator >>()Synopsis:Semantics:Results:See Also:#include public:friend istream &operator >>( istream &strm, String &str );The operator >> function is used to read a sequence <strong>of</strong> characters from the strm istream objectinto the str String object. Like C strings, the gathering <strong>of</strong> characters for a str String object ends atthe first whitespace encountered, so that the last character placed in str is the character before thewhitespace.The operator >> function returns a reference to the strm parameter.istreamString Class 883
String::operator []()Synopsis:Semantics:#include public:char const &String::operator []( size_t pos ) const;char &String::operator []( size_t pos );The operator [] public member function creates either a const or a non-const reference to thecharacter at <strong>of</strong>fset pos within the String object. The non-const reference may be used to modify thatcharacter. The first character <strong>of</strong> a String object is at position zero.If pos is greater than or equal to the length <strong>of</strong> the String object, and the resulting reference is used,the behavior is undefined.If the non-const reference is used to modify other characters within the String object, the behavior isundefined.The reference is associated with the String object, and therefore has meaning only as long as theString object is not modified (or destroyed). If the String object has been modified and an oldreference is used, the behavior is undefined.Results:The operator [] public member function returns either a const or a non-const reference to acharacter.See Also: String::operator (), operator char, operator char const *884 String Class
String::operator char()Synopsis:Semantics:Results:#include public:String::operator char();The operator char public member function converts a String object into the first character itcontains. If the String object is empty, the result is the null character.The operator char public member function returns the first character contained in the Stringobject. If the String object is empty, the null character is returned.See Also: String::operator (), operator [], operator char const *String Class 885
String::operator char const *()Synopsis:Semantics:#include public:String::operator char const *();The operator char const * public member function converts a String object into a C stringcontaining the same length and sequence <strong>of</strong> characters, terminated by a null character. If the Stringobject contains a null character the resulting C string is terminated by that null character.The returned pointer is associated with the String object, and therefore has meaning only as long asthe String object is not modified. If the intention is to be able to refer to the C string after theString object has been modified, a copy <strong>of</strong> the string should be made, perhaps by using the C librarystrdup function.The returned pointer is a pointer to a constant C string. If the pointer is used in some way to modify theC string, the behavior is undefined.Results:See Also:The operator char const * public member function returns a pointer to a null-terminatedconstant C string that contains the same characters as the String object.String::operator (), operator [], operator char886 String Class
String::put_at()Synopsis:Semantics:Results:#include public:void String::put_at( size_t pos, char chr );The put_at public member function modifies the character at <strong>of</strong>fset pos within the String object.The character at the specified <strong>of</strong>fset is set to the value <strong>of</strong> chr. If pos is greater than the number <strong>of</strong>characters within the String object, chr is appended to the String object.The put_at public member function has no return value.See Also: String::get_at, operator [], operator (), operator +=, operator +String Class 887
String::String()Synopsis:Semantics:Results:See Also:#include public:String::String();This form <strong>of</strong> the public String constructor creates a default String object containing no characters.The created String object has length zero.This form <strong>of</strong> the public String constructor produces a String object.String::operator =, operator +=, ~String888 String Class
String::String()Synopsis:Semantics:Results:See Also:#include public:String::String( size_t size, String::capacity cap );This form <strong>of</strong> the public String constructor creates a String object. The function constructs aString object <strong>of</strong> length size if cap is equal to the enumerated default_size. The function reserves sizebytes <strong>of</strong> memory and sets the length <strong>of</strong> the String object to be zero if cap is equal to the enumeratedreserve.This form <strong>of</strong> the public String constructor produces a String object <strong>of</strong> size size.String::operator =, ~StringString Class 889
String::String()Synopsis:Semantics:Results:See Also:#include public:String::String( String const &str, size_t pos = 0, size_t num = NPOS);This form <strong>of</strong> the public String constructor creates a String object which contains a sub-string <strong>of</strong>the str parameter. The sub-string starts at position pos within str and continues for num characters oruntil the end <strong>of</strong> the str parameter, whichever comes first.This form <strong>of</strong> the public String constructor produces a sub-string or duplicate <strong>of</strong> the str parameter.String::operator =, operator (), operator [], ~String890 String Class
String::String()Synopsis:Semantics:Results:#include public:String::String( char const *pch, size_t num = NPOS );This form <strong>of</strong> the public String constructor creates a String object from a C string. The Stringobject contains the sequence <strong>of</strong> characters located at the pch parameter. Characters are included up tonum or the end <strong>of</strong> the C string pointed at by pch. Note that C strings are terminated by a null characterand that the value <strong>of</strong> the created String object does not contain that character, nor any following it.This form <strong>of</strong> the public String constructor produces a String object <strong>of</strong> at most length n containingthe characters in the C string starting at the pch parameter.See Also: String::operator =, operator char const *, operator (), operator [],~StringString Class 891
String::String()Synopsis:Semantics:Results:See Also:#include public:String::String( char ch, size_t rep = 1 );This form <strong>of</strong> the public String constructor creates a String object containing rep copies <strong>of</strong> the chparameter.This form <strong>of</strong> the public String constructor produces a String object <strong>of</strong> length rep containing onlythe character specified by the ch parameter.String::operator =, operator char, ~String892 String Class
String::~String()Synopsis:Semantics:Results:See Also:#include public:String::~String();The public ~String destructor destroys the String object. The call to the public ~Stringdestructor is inserted implicitly by the compiler at the point where the String object goes out <strong>of</strong>scope.The String object is destroyed.StringString Class 893
String::upper()Synopsis:Semantics:Results:See Also:#include public:String String::upper() const;The upper public member function creates a new String object whose value is the same as theoriginal String object, except that all lower-case letters have been converted to upper-case.The upper public member function returns a new upper-case String object.String::lower894 String Class
String valid()Synopsis:Semantics:Results:See Also:#include public:friend int valid( String const &str );The valid function tests the validity <strong>of</strong> the str String object.The valid function returns a non-zero value if the str String object is valid, otherwise zero isreturned.String::operator !, validString Class 895
String::valid()Synopsis:Semantics:Results:See Also:#include public:int String::valid() const;The valid public member function tests the validity <strong>of</strong> the String object.The valid public member function returns a non-zero value if the String object is valid, otherwisezero is returned.String::operator !, valid896 String Class
IndexWCValDListIter 394, 402WCValOrderedVector 568, 576_ WCValSList 283, 293WCValSListIter 394, 402WCValSortedVector 568, 576__NOT_EOF 7arg, related functionComplex 19, 23asin, related functionComplex 19, 24Aasinh, related functionComplex 19, 25atan, related functionComplex 19, 26abs, related functionatanh, related functionComplex 19-20Complex 19, 27acos, related functionate, member enumerationComplex 19, 21ios 675acosh, related functionatend, member enumerationComplex 19, 22ios 675adjustfield, member enumerationattach, member functionios 665all_fine, member enumerationWCExcept 70WCIterExcept 75alloc_mult_size, member functionString 862, 864alloc_size_increment, member functionstrstreambuf 846-847allocate, member functionstreambuf 792, 794allocatorfunction 259, 263, 286, 290, 416, 514app, member enumerationios 675append, member enumerationios 675append, member functionWCIsvConstDListIter 308WCIsvConstSListIter 308WCIsvDList 233, 241WCIsvDListIter 324, 332WCIsvSList 233, 241WCIsvSListIter 324, 332WCPtrConstDListIter 343WCPtrConstSListIter 343WCPtrDList 256, 266WCPtrDListIter 359, 367WCPtrOrderedVector 525, 532WCPtrSList 256, 266WCPtrSListIter 359, 367WCPtrSortedVector 525, 532WCValConstDListIter 378WCValConstSListIter 378WCValDList 283, 293filebuf 610, 612fstreambase 635-636Bbad, member functionios 655, 657badbit, member enumerationios 673base, member functionstreambuf 792, 795basefield, member enumerationios 665beg, member enumerationios 683binary, member enumerationios 675bitalloc, member functionios 656, 658bitHash, member functionWCPtrHashDict 82, 88WCPtrHashSet 106, 115WCPtrHash<strong>Table</strong> 106, 115WCValHashDict 132, 137WCValHashSet 154, 163WCValHash<strong>Table</strong> 154, 163blen, member functionstreambuf 792, 796buckets, member functionWCPtrHashDict 82, 89897
IndexWCPtrHashSet 106, 116 WCPtrHash<strong>Table</strong> 106, 118WCPtrHash<strong>Table</strong> 106, 116 WCPtrOrderedVector 525, 534WCValHashDict 132, 138 WCPtrSkipList 446, 457WCValHashSet 154, 164 WCPtrSkipListDict 426, 433WCValHash<strong>Table</strong> 154, 164 WCPtrSkipListSet 446, 457WCPtrSList 256, 268WCPtrSortedVector 525, 534WCPtrVector 555, 561CWCValDList 283, 295WCValSList 283, 295clog 9close, member functioncerr 9 filebuf 610, 613check_all, member enumeration fstreambase 635, 637WCExcept 70 common types 7WCIterExcept 75 Complex class 17check_none, member enumerationComplex related functionsWCExcept 70 abs 19-20WCIterExcept 75 acos 19, 21cin 9 acosh 19, 22clear, member function arg 19, 23ios 655, 659 asin 19, 24WCIsvDList 233, 242 asinh 19, 25WCIsvSList 233, 242 atan 19, 26WCPtrDList 256, 267 atanh 19, 27WCPtrHashDict 83, 90 conj 19, 32WCPtrHashSet 106, 117 cos 19, 33WCPtrHash<strong>Table</strong> 106, 117 cosh 19, 34WCPtrOrderedVector 525, 533 exp 19, 35WCPtrSkipList 446, 456 imag 19, 37WCPtrSkipListDict 426, 432 log 19WCPtrSkipListSet 446, 456 log10 19, 39WCPtrSList 256, 267 norm 19, 40WCPtrSortedVector 525, 533 num 38WCPtrVector 555, 560 operator != 19, 41WCQueue 414, 418 operator * 18, 42WCStack 512, 516 operator + 18, 45WCValDList 283, 294 operator - 18, 48WCValHashDict 132, 139 operator / 18, 50WCValHashSet 154, 165 operator > 18, 55WCValSkipList 489, 498 polar 19, 56WCValSkipListDict 470, 475 pow 19, 57WCValSkipListSet 489, 498 real 19, 59WCValSList 283, 294 sin 19, 60WCValSortedVector 568, 577 sinh 19, 61WCValVector 598, 603 sqrt 19, 62clearAndDestroy, member function tan 19, 63WCIsvDList 233, 243 tanh 19, 64WCIsvSList 233, 243 Complex::Complex 18, 28-30WCPtrDList 256, 268 Complex::imag 18, 36WCPtrHashDict 83, 91 Complex::operator *= 18, 43WCPtrHashSet 106, 118 Complex::operator + 18, 44898
IndexComplex::operator += 18, 46 WCValSkipListDict 471-473Complex::operator - 18, 47 WCValSList 283Complex::operator -= 18, 49 WCValSListIter 394Complex::operator /= 18, 51 WCValSortedVector 570-571,Complex::operator = 18, 53 573-574Complex::real 18, 58 WCValVector 598-601Complex::~Complex 18, 31container, member functionconj, related function WCIsvConstDListIter 308, 315Complex 19, 32 WCIsvConstSListIter 308, 315constructor WCIsvDListIter 324, 333Complex 18, 28-30 WCIsvSListIter 324, 333filebuf 610, 615-617 WCPtrConstDListIter 343, 350fstream 628-632 WCPtrConstSListIter 343, 350fstreambase 635, 638-641 WCPtrDListIter 359, 368ifstream 648-652 WCPtrHashDictIter 180, 184ios 655, 670-671 WCPtrHashSetIter 202, 209iostream 691-694 WCPtrHash<strong>Table</strong>Iter 202, 209istream 698, 710-712 WCPtrSListIter 359, 368istrstream 729-731 WCValConstDListIter 378, 385<strong>of</strong>stream 748-752 WCValConstSListIter 378, 385ostream 755, 769-771 WCValDListIter 394, 403ostrstream 778-780 WCValHashDictIter 191, 195stdiobuf 784, 786-787 WCValHashSetIter 215, 222streambuf 792, 830-831 WCValHash<strong>Table</strong>Iter 215, 222String 862, 888-892 WCValSListIter 394, 403strstream 836, 838-839contains, member functionstrstreambase 841, 843-844 WCIsvDList 233, 244strstreambuf 846, 854-857 WCIsvSList 233, 244WCDLink 230-231 WCPtrDList 256, 269WCExcept 66-67 WCPtrHashDict 83, 92WCIsvConstSListIter 308 WCPtrHashSet 106, 119WCIsvSList 233 WCPtrHash<strong>Table</strong> 106, 119WCIsvSListIter 324 WCPtrOrderedVector 525, 535WCIterExcept 71-72 WCPtrSkipList 447, 458WCPtrConstSListIter 343 WCPtrSkipListDict 426, 434WCPtrHashDict 84-86 WCPtrSkipListSet 447, 458WCPtrHashDictIter 180 WCPtrSList 256, 269WCPtrHashSetIter 202 WCPtrSortedVector 525, 535WCPtrHash<strong>Table</strong> 107-109, 111-113 WCValDList 283, 296WCPtrSkipList 448-450, 452-454 WCValHashDict 132, 140WCPtrSkipListDict 428-430 WCValHashSet 154, 166WCPtrSList 256 WCValHash<strong>Table</strong> 154, 166WCPtrSListIter 359 WCValOrderedVector 568, 578WCPtrSortedVector 526-527, 529-530 WCValSkipList 489, 499WCPtrVector 555-558 WCValSkipListDict 470, 476WCQueue 414-416 WCValSkipListSet 489, 499WCSLink 280-281 WCValSList 283, 296WCStack 512-514 WCValSortedVector 568, 578WCValConstSListIter 378cos, related functionWCValHashDict 133-135 Complex 19, 33WCValHashDictIter 191cosh, related functionWCValHashSetIter 215 Complex 19, 34WCValHash<strong>Table</strong> 155-157, 159-161 cout 9WCValSkipList 490-492, 494-496cur, member enumeration899
Indexios 683 WCIsvSList 233current, member function WCIsvSListIter 324WCIsvConstDListIter 308, 316 WCIterExcept 71, 73WCIsvConstSListIter 308, 316 WCPtrConstSListIter 343WCIsvDListIter 324, 334 WCPtrHashDict 87WCIsvSListIter 324, 334 WCPtrHashDictIter 180WCPtrConstDListIter 343, 351 WCPtrHashSetIter 202WCPtrConstSListIter 343, 351 WCPtrHash<strong>Table</strong> 110, 114WCPtrDListIter 359, 369 WCPtrSkipList 451, 455WCPtrHashSetIter 202, 210 WCPtrSkipListDict 431WCPtrHash<strong>Table</strong>Iter 202, 210 WCPtrSList 256WCPtrSListIter 359, 369 WCPtrSListIter 359WCValConstDListIter 378, 386 WCPtrSortedVector 528, 531WCValConstSListIter 378, 386 WCPtrVector 555, 559WCValDListIter 394, 404 WCQueue 414, 417WCValHashSetIter 215, 223 WCSLink 280, 282WCValHash<strong>Table</strong>Iter 215, 223 WCStack 512, 515WCValSListIter 394, 404 WCValConstSListIter 378WCValHashDict 136WCValHashDictIter 191DWCValHashSetIter 215WCValHash<strong>Table</strong> 158, 162WCValSkipList 493, 497WCValSkipListDict 474WCValSList 283dbp, member function WCValSListIter 394streambuf 793, 797 WCValSortedVector 572, 575dealloctor WCValVector 598, 602function 259, 263, 286, 290, 416, 514do_sgetn, member functiondec, manipulator 733-734 streambuf 793, 798dec, member enumerationdo_sputn, member functionios 665 streambuf 793, 799destructordoallocate, member functionComplex 18, 31 streambuf 792, 800filebuf 610, 618 strstreambuf 846, 848fstream 628, 633fstreambase 635, 642ifstream 648, 653ios 655, 672iostream 691, 695Eistream 698, 713istrstream 729, 732<strong>of</strong>stream 748, 753eatwhite, member functionostream 755, 772 istream 698, 700ostrstream 778, 781eback, member functionstdiobuf 784, 788 streambuf 792, 801streambuf 792, 832ebuf, member functionString 862, 893 streambuf 792, 802strstream 836, 840egptr, member functionstrstreambase 841, 845 streambuf 792, 803strstreambuf 846, 858empty_containerWCDLink 230, 232 exception 70, 246-247, 249, 271-272, 274,WCExcept 66, 68 298-299, 301, 420-421, 424, 519, 521,WCIsvConstSListIter 308900
Index538, 543, 545, 551-553, 563, 581, 586,588, 594-596, 605empty_container, member enumerationWCExcept 70end, member enumerationios 683endl, manipulator 733, 735ends, manipulator 733, 736entries, member functionWCIsvDList 233, 245WCIsvSList 233, 245WCPtrDList 256, 270WCPtrHashDict 83, 93WCPtrHashSet 106, 120WCPtrHash<strong>Table</strong> 106, 120WCPtrOrderedVector 525, 536WCPtrSkipList 447, 459WCPtrSkipListDict 426, 435WCPtrSkipListSet 447, 459WCPtrSList 256, 270WCPtrSortedVector 525, 536WCQueue 414, 419WCStack 512, 517WCValDList 283, 297WCValHashDict 132, 141WCValHashSet 154, 167WCValHash<strong>Table</strong> 154, 167WCValOrderedVector 568, 579WCValSkipList 489, 500WCValSkipListDict 470, 477WCValSkipListSet 489, 500WCValSList 283, 297WCValSortedVector 568, 579EOF 7e<strong>of</strong>, member functionios 655, 660e<strong>of</strong>bit, member enumerationios 673epptr, member functionstreambuf 792, 804exception handling 3exceptions 70function 75exceptions, member functionios 655, 661WCExcept 66, 69WCIterExcept 71, 74exp, related functionComplex 19, 35extractor 11, 698Ffail, member functionios 655, 662failbit, member enumerationios 673fd, member functionfilebuf 610, 614fstreambase 635, 644filebuf 791filebuf::attach 610, 612filebuf::close 610, 613filebuf::fd 610, 614filebuf::filebuf 610, 615-617filebuf::is_open 610, 619filebuf::open 610, 620filebuf::openprot 610, 621filebuf::overflow 610, 622filebuf::pbackfail 610, 623filebuf::seek<strong>of</strong>f 611, 624filebuf::setbuf 611, 625filebuf::sync 611, 626filebuf::underflow 610, 627filebuf::~filebuf 610, 618filedesc 7fill character 663fill, member functionios 655, 663find, member functionWCIsvDList 233, 246WCIsvSList 233, 246WCPtrDList 256, 271WCPtrHashDict 83, 94WCPtrHashSet 106, 121WCPtrHash<strong>Table</strong> 106, 121WCPtrOrderedVector 525, 537WCPtrSkipList 447, 460WCPtrSkipListDict 426, 436WCPtrSkipListSet 447, 460WCPtrSList 256, 271WCPtrSortedVector 525, 537WCValDList 283, 298WCValHashDict 132, 142WCValHashSet 154, 168WCValHash<strong>Table</strong> 154, 168WCValOrderedVector 568, 580WCValSkipList 489, 501WCValSkipListDict 470, 478WCValSkipListSet 489, 501WCValSList 283, 298WCValSortedVector 568, 580901
IndexfindKeyAndValue, member function fstream 635, 691WCPtrHashDict 83, 95 fstream::fstream 628-632WCPtrSkipListDict 426, 437 fstream::open 628, 634WCValHashDict 132, 143 fstream::~fstream 628, 633WCValSkipListDict 470, 479 fstreambase 628, 648, 748findLast, member function fstreambase::attach 635-636WCIsvDList 233, 247 fstreambase::close 635, 637WCIsvSList 233, 247 fstreambase::fd 635, 644WCPtrDList 256, 272 fstreambase::fstreambase 635, 638-641WCPtrSList 256, 272 fstreambase::is_open 635, 643WCValDList 283, 299 fstreambase::open 635, 645WCValSList 283, 299 fstreambase::rdbuf 635, 646first, member function fstreambase::setbuf 635, 647WCPtrOrderedVector 525, 538 fstreambase::~fstreambase 635, 642WCPtrSortedVector 525, 538 functions and types 15WCQueue 414, 420WCValOrderedVector 568, 581WCValSortedVector 568, 581fixed, member enumerationGios 665flags, member functionios 655, 664floatfield, member enumerationgbump, member functionios 665streambuf 792, 805flush, manipulator 733, 737gcount, member functionflush, member functionistream 699, 701ostream 755, 757get area 791fmtflags, member enumerationget pointer 806ios 655, 665get, member functionforall, member functionistream 698, 702-705WCIsvDList 233, 248WCIsvDList 233, 249WCIsvSList 233, 248WCIsvSList 233, 249WCPtrDList 256, 273WCPtrDList 256, 274WCPtrHashDict 83, 96WCPtrSList 256, 274WCPtrHashSet 106, 122WCQueue 414, 421WCPtrHash<strong>Table</strong> 106, 122WCValDList 283, 301WCPtrSkipList 447, 461WCValSList 283, 301WCPtrSkipListDict 426, 438get_at, member functionWCPtrSkipListSet 447, 461String 862, 865WCPtrSList 256, 273getline, member functionWCValDList 283, 300istream 698, 706WCValHashDict 132, 144good, member functionWCValHashSet 154, 169ios 655, 668WCValHash<strong>Table</strong> 154, 169goodbit, member enumerationWCValSkipList 489, 502ios 673WCValSkipListDict 470, 480gptr, member functionWCValSkipListSet 489, 502streambuf 792, 806WCValSList 283, 300format precision 679format width 689formatted input 11Hformatted output 13freeze, member functionstrstreambuf 846, 849header files902
Indexalgorithm 3 ios 675complex 3in_avail, member functionexception 3 streambuf 793, 807fstream 4index, member functionfunctional 3 String 862, 866generic 4 WCIsvDList 233, 250-251iomanip 4 WCIsvSList 233, 250-251ios 4 WCPtrDList 256, 275iosfwd 4 WCPtrOrderedVector 525, 539iostream 4 WCPtrSList 256, 275istream 4 WCPtrSortedVector 525, 539iterator 4 WCValDList 283, 302limits 4 WCValOrderedVector 568, 582list 4 WCValSList 283, 302map 4 WCValSortedVector 568, 582memory 4index_rangenew 5 exception 70, 100, 148, 247, 272, 299,numeric 5 420-421, 424, 442, 484, 519, 521, 538,ostream 5 541, 543, 545, 563, 581, 584, 586, 588,set 5 605stdiobuf 5index_range, member enumerationstreambuf 5 WCExcept 70string 5init, member functionstrstream 5 ios 655, 669vector 5insert, member functionwcdefs 5 WCIsvConstDListIter 308wclbase 5 WCIsvConstSListIter 308wclcom 5 WCIsvDList 233, 252wclibase 5 WCIsvDListIter 324, 335wclist 5 WCIsvSList 233, 252wclistit 5 WCIsvSListIter 324, 335wcqueue 6 WCPtrConstDListIter 343wcstack 6 WCPtrConstSListIter 343hex, manipulator 733, 738 WCPtrDList 256, 276hex, member enumeration WCPtrDListIter 359, 370ios 665 WCPtrHashDict 83, 97WCPtrHashSet 106, 123WCPtrHash<strong>Table</strong> 106, 123IWCPtrOrderedVector 525, 540WCPtrSkipList 447, 462WCPtrSkipListDict 426, 439WCPtrSkipListSet 447, 462WCPtrSList 256, 276ifstream 635, 698 WCPtrSListIter 359, 370ifstream::ifstream 648-652 WCPtrSortedVector 525, 540ifstream::open 648, 654 WCQueue 414, 422ifstream::~ifstream 648, 653 WCValConstDListIter 378ignore, member function WCValConstSListIter 378istream 698, 707 WCValDList 283, 303imag, member function WCValDListIter 394, 405Complex 18, 36 WCValHashDict 132, 145imag, related function WCValHashSet 154, 170Complex 19, 37 WCValHash<strong>Table</strong> 154, 170in, member enumeration WCValOrderedVector 568, 583903
IndexWCValSkipList 489, 503 ios::oct 665WCValSkipListDict 470, 481 ios::openmode 655, 675WCValSkipListSet 489, 503 ios::operator ! 656, 677WCValSList 283, 303 ios::operator void * 656, 678WCValSListIter 394, 405 ios::out 675WCValSortedVector 568, 583 ios::precision 655, 679insertAt, member function ios::pword 656, 680WCPtrOrderedVector 525, 541 ios::rdbuf 655, 681WCPtrSortedVector 525, 541 ios::rdstate 655, 682WCValOrderedVector 568, 584 ios::right 665WCValSortedVector 568, 584 ios::scientific 665inserter 13, 755 ios::seekdir 655, 683internal, member enumeration ios::setf 655, 684ios 665 ios::setstate 655, 685intrusive ios::showbase 665classes 233 ios::showpoint 665ios 635, 698, 755, 841 ios::showpos 665ios::adjustfield 665 ios::skipws 665ios::app 675 ios::stdio 665ios::append 675 ios::sync_with_stdio 656, 686ios::ate 675 ios::text 675ios::atend 675 ios::tie 655, 687ios::bad 655, 657 ios::trunc 675ios::badbit 673 ios::truncate 675ios::basefield 665 ios::unitbuf 665ios::beg 683 ios::unsetf 655, 688ios::binary 675 ios::uppercase 665ios::bitalloc 656, 658 ios::width 655-656, 689ios::clear 655, 659 ios::xalloc 656, 690ios::cur 683 ios::~ios 655, 672ios::dec 665iostate, member enumerationios::end 683 ios 655, 673ios::e<strong>of</strong> 655, 660 iostream 628, 698, 755, 836ios::e<strong>of</strong>bit 673 iostream::iostream 691-694ios::exceptions 655, 661 iostream::operator = 691, 696-697ios::fail 655, 662 iostream::~iostream 691, 695ios::failbit 673ipfx, member functionios::fill 655, 663 istream 698, 708ios::fixed 665is_open, member functionios::flags 655, 664 filebuf 610, 619ios::floatfield 665 fstreambase 635, 643ios::fmtflags 655, 665isEmpty, member functionios::good 655, 668 WCIsvDList 233, 253ios::goodbit 673 WCIsvSList 233, 253ios::hex 665 WCPtrDList 256, 277ios::in 675 WCPtrHashDict 83, 98ios::init 655, 669 WCPtrHashSet 106, 124ios::internal 665 WCPtrHash<strong>Table</strong> 106, 124ios::ios 655, 670-671 WCPtrOrderedVector 525, 542ios::iostate 655, 673 WCPtrSkipList 447, 463ios::iword 656, 674 WCPtrSkipListDict 426, 440ios::left 665 WCPtrSkipListSet 447, 463ios::nocreate 675 WCPtrSList 256, 277ios::noreplace 675 WCPtrSortedVector 525, 542904
IndexWCQueue 414, 423WCStack 512, 518WCValDList 283, 304LWCValHashDict 132, 146WCValHashSet 154, 171WCValHash<strong>Table</strong> 154, 171last, member functionWCValOrderedVector 568, 585WCPtrOrderedVector 525, 543WCValSkipList 489, 504WCPtrSortedVector 525, 543WCValSkipListDict 470, 482WCQueue 414, 424WCValSkipListSet 489, 504WCValOrderedVector 568, 586WCValSList 283, 304WCValSortedVector 568, 586WCValSortedVector 568, 585left, member enumerationisfx, member functionios 665istream 698, 709length, member functionistream 648, 655, 691, 729String 862, 867istream input 11WCPtrVector 555, 562istream::eatwhite 698, 700WCValVector 598, 604istream::gcount 699, 701list containers 5istream::get 698, 702-705log, related functionistream::getline 698, 706Complex 19istream::ignore 698, 707log10, related functionistream::ipfx 698, 708Complex 19, 39istream::isfx 698, 709lower, member functionistream::istream 698, 710-712String 862, 868istream::operator = 699, 714-715istream::operator >> 699, 716-721istream::peek 699, 722istream::putback 698, 723Mistream::read 698, 724istream::seekg 698, 725-726istream::sync 699, 727istream::tellg 698, 728manipulator manipulatorsistream::~istream 698, 713 dec 733-734istrstream 698, 841 endl 733, 735istrstream::istrstream 729-731 ends 733, 736istrstream::~istrstream 729, 732 flush 733, 737iter_range hex 733, 738exception 75, 319, 321, 338, 340, 354, 356, oct 733, 739373, 375, 389, 391, 408, 410 resetiosflags 733, 740iter_range, member enumeration setbase 733, 741WCIterExcept 75 setfill 733, 742iterator classes 5 setiosflags 733, 743iword, member function setprecision 733, 744ios 656, 674 setw 733, 745setwidth 733, 746ws 733, 747manipulatorsK dec 733-734endl 733, 735ends 733, 736flush 733, 737key, member functionhex 733, 738WCPtrHashDictIter 180, 185oct 733, 739WCValHashDictIter 191, 196resetiosflags 733, 740905
Indexsetbase 733, 741 oct, manipulator 733, 739setfill 733, 742oct, member enumerationsetiosflags 733, 743 ios 665setprecision 733, 744 <strong>of</strong>stream 635, 755setw 733, 745 <strong>of</strong>stream::<strong>of</strong>stream 748-752setwidth 733, 746 <strong>of</strong>stream::open 748, 754ws 733, 747 <strong>of</strong>stream::~<strong>of</strong>stream 748, 753match, member functionopen, member functionString 862, 869 filebuf 610, 620fstream 628, 634fstreambase 635, 645ifstream 648, 654N<strong>of</strong>stream 748, 754openmode, member enumerationios 655, 675openprot, member datanocreate, member enumeration filebuf 621ios 675openprot, member functionnoreplace, member enumeration filebuf 610ios 675operator !, member functionnorm, related function ios 656, 677Complex 19, 40 String 862, 870not_emptyoperator !=, related functionexception 70, 87, 110, 114, 136, 158, 162, 237, Complex 19, 41240, 261, 265, 288, 292, 417, 431, 451, String 862, 871455, 474, 493, 497, 515, 528, 531, 559, operator (), member function572, 575, 602 String 862, 872-873not_empty, member enumeration WCIsvConstDListIter 308, 317WCExcept 70 WCIsvConstSListIter 308, 317not_unique WCIsvDListIter 324, 336exception 70, 123, 170, 462, 503 WCIsvSListIter 324, 336not_unique, member enumeration WCPtrConstDListIter 343, 352WCExcept 70 WCPtrConstSListIter 343, 352num, related function WCPtrDListIter 359, 371Complex 38 WCPtrHashDictIter 180, 186WCPtrHashSetIter 202, 211WCPtrHash<strong>Table</strong>Iter 202, 211WCPtrSListIter 359, 371O WCValConstDListIter 378, 387WCValConstSListIter 378, 387WCValDListIter 394, 406occurrencesOf, member functionWCValHashDictIter 191, 197WCPtrHashSet 106, 125WCValHashSetIter 215, 224WCPtrHash<strong>Table</strong> 106, 125WCValHash<strong>Table</strong>Iter 215, 224WCPtrOrderedVector 525, 544WCValSListIter 394, 406WCPtrSkipList 447, 464operator *, related functionWCPtrSkipListSet 447, 464Complex 18, 42WCPtrSortedVector 525, 544operator *=, member functionWCValHashSet 154, 172Complex 18, 43WCValHash<strong>Table</strong> 154, 172operator ++, member functionWCValOrderedVector 568, 587WCIsvConstDListIter 308, 318WCValSkipList 489, 505WCIsvConstSListIter 308, 318WCValSkipListSet 489, 505WCIsvDListIter 324, 337WCValSortedVector 568, 587WCIsvSListIter 324, 337906
IndexWCPtrConstDListIter 343, 353 WCIsvConstSListIter 308, 321WCPtrConstSListIter 343, 353 WCIsvDListIter 324-325, 340WCPtrDListIter 359, 372 WCIsvSListIter 324-325, 340WCPtrHashDictIter 180, 187 WCPtrConstDListIter 343, 356WCPtrHashSetIter 202, 212 WCPtrConstSListIter 343, 356WCPtrHash<strong>Table</strong>Iter 202, 212 WCPtrDListIter 359-360, 375WCPtrSListIter 359, 372 WCPtrSListIter 359-360, 375WCValConstDListIter 378, 388 WCValConstDListIter 378, 391WCValConstSListIter 378, 388 WCValConstSListIter 378, 391WCValDListIter 394, 407 WCValDListIter 394-395, 410WCValHashDictIter 191, 198 WCValSListIter 394-395, 410WCValHashSetIter 215, 225operator /, related functionWCValHash<strong>Table</strong>Iter 215, 225 Complex 18, 50WCValSListIter 394, 407operator /=, member functionoperator +, member function Complex 18, 51Complex 18, 44operator
Indexoperator ==, member functionoperator void *, member functionWCIsvDList 234, 255 ios 656, 678WCIsvSList 234, 255opfx, member functionWCPtrDList 256, 279 ostream 755, 767WCPtrHashDict 83, 102osfx, member functionWCPtrHashSet 106, 127 ostream 755, 768WCPtrHash<strong>Table</strong> 106, 127 ostream 655, 691, 748, 778WCPtrOrderedVector 525, 547 ostream output 13WCPtrSkipList 447, 466 ostream::flush 755, 757WCPtrSkipListDict 427, 444 ostream::operator , related function 109, 111, 113, 123, 126, 130, 133, 135,String 863, 881 145, 147, 149, 152, 155, 157, 159, 161,operator >=, related function 170, 173, 177, 260, 264, 266, 276, 278,String 863, 882 287, 291, 293, 303, 305, 422, 428, 430,operator >>, member function 439, 441, 443, 448, 450, 452, 454, 462,istream 699, 716-721 465, 471, 473, 481, 483, 485, 490, 492,operator >>, related function 494, 496, 503, 506, 520, 527, 530, 532,Complex 18, 55 540-541, 546, 548, 554, 558, 563-564,String 863, 883 566, 571, 574, 576, 583-584, 589, 591,operator [], member function 597, 601, 605-606, 608String 862, 884out_<strong>of</strong>_memory, member enumerationWCPtrHashDict 83, 99-100 WCExcept 70WCPtrOrderedVector 525, 545out_waiting, member functionWCPtrSkipListDict 427, 441-442 streambuf 793, 808WCPtrSortedVector 525, 545overflow, member functionWCPtrVector 555, 563 filebuf 610, 622WCValHashDict 132, 147-148 stdiobuf 784-785WCValOrderedVector 568, 588 streambuf 793, 809WCValSkipListDict 470, strstreambuf 846, 850483-484WCValSortedVector 568, 588WCValVector 598, 605operator char const *, member functionString 862, 886operator char, member functionString 862, 885908
Indexfstreambase 635, 646ios 655, 681P strstreambase 841-842rdstate, member functionios 655, 682pbackfail, member functionread, member functionfilebuf 610, 623istream 698, 724streambuf 793, 810real, member functionpbase, member functionComplex 18, 58streambuf 792, 811real, related functionpbump, member functionComplex 19, 59streambuf 792, 812remove, member functionpcount, member functionWCPtrHashDict 83, 103ostrstream 778, 782WCPtrHashSet 106, 128peek, member functionWCPtrHash<strong>Table</strong> 106, 128istream 699, 722WCPtrOrderedVector 525, 549pointerWCPtrSkipList 447, 467lists 229WCPtrSkipListDict 426, 445polar, related functionWCPtrSkipListSet 447, 467Complex 19, 56WCPtrSortedVector 525, 549pop, member functionWCValHashDict 132, 151WCStack 512, 519WCValHashSet 154, 175pow, related functionWCValHash<strong>Table</strong> 154, 175Complex 19, 57WCValOrderedVector 568, 592pptr, member functionWCValSkipList 489, 508streambuf 792, 813WCValSkipListDict 470, 487precision, member functionWCValSkipListSet 489, 508ios 655, 679WCValSortedVector 568, 592predefined objects 9removeAll, member functionprepend, member functionWCPtrHashSet 106, 129WCPtrOrderedVector 525, 548WCPtrHash<strong>Table</strong> 106, 129WCPtrSortedVector 525, 548WCPtrOrderedVector 525, 550WCValOrderedVector 568, 591WCPtrSkipList 447, 468WCValSortedVector 568, 591WCPtrSkipListSet 447, 468push, member functionWCPtrSortedVector 525, 550WCStack 512, 520WCValHashSet 154, 176put area 791WCValHash<strong>Table</strong> 154, 176put pointer 813WCValOrderedVector 568, 593put, member functionWCValSkipList 489, 509ostream 755, 773WCValSkipListSet 489, 509put_at, member functionWCValSortedVector 568, 593String 862, 887removeAt, member functionputback, member functionWCPtrOrderedVector 525, 551istream 698, 723WCPtrSortedVector 525, 551pword, member functionWCValOrderedVector 568, 594ios 656, 680WCValSortedVector 568, 594removeFirst, member functionWCPtrOrderedVector 525, 552WCPtrSortedVector 525, 552RWCValOrderedVector 568, 595WCValSortedVector 568, 595removeLast, member functionWCPtrOrderedVector 525, 553rdbuf, member functionWCPtrSortedVector 525, 553909
IndexWCValOrderedVector 568, 596scientific, member enumerationWCValSortedVector 568, 596 ios 665reserve area 791seekdir, member enumerationreset, member function ios 655, 683WCIsvConstDListIter 308, 322-323seekg, member functionWCIsvConstSListIter 308, 322-323 istream 698, 725-726WCIsvDListIter 324, 341-342seek<strong>of</strong>f, member functionWCIsvSListIter 324, 341-342 filebuf 611, 624WCPtrConstDListIter 343, 357-358 streambuf 793, 815WCPtrConstSListIter 343, 357-358 strstreambuf 846, 851WCPtrDListIter 359, 376-377seekp, member functionWCPtrHashDictIter 180, 188-189 ostream 755, 774-775WCPtrHashSetIter 202, 213-214seekpos, member functionWCPtrHash<strong>Table</strong>Iter 202, 213-214 streambuf 793, 816WCPtrSListIter 359, 376-377setb, member functionWCValConstDListIter 378, 392-393 streambuf 792, 817WCValConstSListIter 378, 392-393 setbase, manipulator 733, 741WCValDListIter 394, 411-412setbuf, member functionWCValHashDictIter 191, filebuf 611, 625199-200 fstreambase 635, 647WCValHashSetIter 215, 226-227 streambuf 793, 818WCValHash<strong>Table</strong>Iter 215, 226-227 strstreambuf 846, 852WCValSListIter 394, 411-412setf, member functionresetiosflags, manipulator 733, 740 ios 655, 684resize, member function setfill, manipulator 733, 742WCPtrHashDict 83, 104setg, member functionWCPtrHashSet 106, 130 streambuf 792, 819WCPtrHash<strong>Table</strong> 106, 130 setiosflags, manipulator 733, 743WCPtrOrderedVector 525, 554setp, member functionWCPtrSortedVector 525, 554 streambuf 792, 820WCPtrVector 555, 566 setprecision, manipulator 733, 744WCValHashDict 132, 152setstate, member functionWCValHashSet 154, 177 ios 655, 685WCValHash<strong>Table</strong> 154, 177 setw, manipulator 733, 745WCValOrderedVector 568, 597 setwidth, manipulator 733, 746WCValSortedVector 568, 597sgetc, member functionWCValVector 598, 608 streambuf 793, 821resize_requiredsgetchar, member functionexception 70, 524, 526, 529, 532, 540-541, streambuf 793, 822548, 563, 567, 570, 573, 576, 583-584, sgetn, member function591, 605 streambuf 793, 823resize_required, member enumerationshowbase, member enumerationWCExcept 70 ios 665right, member enumerationshowpoint, member enumerationios 665 ios 665showpos, member enumerationios 665Ssin, related functionComplex 19, 60sinh, related functionComplex 19, 61skipws, member enumerationsbumpc, member function ios 665streambuf 793, 814snextc, member function910
Indexstreambuf 793, 824 streambuf::sgetchar 793, 822speekc, member function streambuf::sgetn 793, 823streambuf 793, 825 streambuf::snextc 793, 824sputbackc, member function streambuf::speekc 793, 825streambuf 793, 826 streambuf::sputbackc 793, 826sputc, member function streambuf::sputc 793, 827streambuf 793, 827 streambuf::sputn 793, 828sputn, member function streambuf::stossc 793, 829streambuf 793, 828 streambuf::streambuf 792, 830-831sqrt, related function streambuf::sync 793, 833Complex 19, 62 streambuf::unbuffered 792, 834stdio, member enumeration streambuf::underflow 793, 835ios 665 streambuf::~streambuf 792, 832stdiobuf 791 stream<strong>of</strong>f 7stdiobuf::overflow 784-785 streampos 7stdiobuf::stdiobuf 784, 786-787String related functionsstdiobuf::sync 784, 789 operator != 862, 871stdiobuf::underflow 784, 790 operator + 863, 874stdiobuf::~stdiobuf 784, 788 operator < 862-863, 876stossc, member function operator = 863, 882strstreambuf 846, 853 operator >> 863, 883streambuf 610, 784, 846 valid 863, 895streambuf::allocate 792, 794 String::alloc_mult_size 862, 864streambuf::base 792, 795 String::get_at 862, 865streambuf::blen 792, 796 String::index 862, 866streambuf::dbp 793, 797 String::length 862, 867streambuf::do_sgetn 793, 798 String::lower 862, 868streambuf::do_sputn 793, 799 String::match 862, 869streambuf::doallocate 792, 800 String::operator ! 862, 870streambuf::eback 792, 801 String::operator () 862, 872-873streambuf::ebuf 792, 802 String::operator += 862, 875streambuf::egptr 792, 803 String::operator = 862, 879streambuf::epptr 792, 804 String::operator [] 862, 884streambuf::gbump 792, 805 String::operator char 862, 885streambuf::gptr 792, 806 String::operator char const * 862, 886streambuf::in_avail 793, 807 String::put_at 862, 887streambuf::out_waiting 793, 808 String::String 862, 888-892streambuf::overflow 793, 809 String::upper 862, 894streambuf::pbackfail 793, 810 String::valid 862, 896streambuf::pbase 792, 811 String::~String 862, 893streambuf::pbump 792, 812 strstream 691, 841streambuf::pptr 792, 813 strstream::str 836-837streambuf::sbumpc 793, 814 strstream::strstream 836, 838-839streambuf::seek<strong>of</strong>f 793, 815 strstream::~strstream 836, 840streambuf::seekpos 793, 816 strstreambase 729, 778, 836streambuf::setb 792, 817 strstreambase::rdbuf 841-842streambuf::setbuf 793, 818 strstreambase::strstreambase 841, 843-844streambuf::setg 792, 819 strstreambase::~strstreambase 841, 845streambuf::setp 792, 820 strstreambuf 791streambuf::sgetc 793, 821 strstreambuf::alloc_size_increment 846-847911
Indexstrstreambuf::doallocate 846, 848undef_item, member enumerationstrstreambuf::freeze 846, 849 WCIterExcept 75strstreambuf::overflow 846, 850undef_iterstrstreambuf::seek<strong>of</strong>f 846, 851 exception 75, 184, 186-187, 195, 197-198,strstreambuf::setbuf 846, 852 209, 211-212, 222, 224-225, 315,strstreambuf::str 846, 853 317-321, 332-333, 335-340, 350,strstreambuf::strstreambuf 846, 854-857 352-356, 367-368, 370-375, 385,strstreambuf::sync 846, 859 387-391, 402-403, 405-410strstreambuf::underflow 846, 860undef_iter, member enumerationstrstreambuf::~strstreambuf 846, 858 WCIterExcept 75sync, member functionunderflow, member functionfilebuf 611, 626 filebuf 610, 627istream 699, 727 stdiobuf 784, 790stdiobuf 784, 789 streambuf 793, 835streambuf 793, 833 strstreambuf 846, 860strstreambuf 846, 859undex_itersync_with_stdio, member function exception 179, 307ios 656, 686 unformatted input 11unformatted output 13unitbuf, member enumerationTios 665unsetf, member functionios 655, 688upper, member functionString 862, 894tan, related functionuppercase, member enumerationComplex 19, 63 ios 665tanh, related functionComplex 19, 64tellg, member functionistream 698, 728tellp, member functionVostream 755, 776text, member enumerationios 675valid, member functiontie, member function String 862, 896ios 655, 687valid, related functiontop, member function String 863, 895WCStack 512, 521valuetrunc, member enumeration lists 229ios 675value, member functiontruncate, member enumeration WCPtrHashDictIter 180, 190ios 675 WCValHashDictIter 191, 201UWunbuffered, member functionwc_state, member enumerationstreambuf 792, 834 WCExcept 66, 70undef_item 185, 190, 196, 201, 210, 223, 316, WCDLink 280334, 351, 369, 386, 404 WCDLink::WCDLink 230-231exception 75 WCDLink::~WCDLink 230, 232912
IndexWCExcept::all_fine 70 WCIsvConstSListIter::operator -- 308,WCExcept::check_all 70 320WCExcept::check_none 70 WCIsvConstSListIter::operator -= 308,WCExcept::empty_container 70 321WCExcept::exceptions 66, 69 WCIsvConstSListIter::reset 308, 322-323WCExcept::index_range 70WCIsvConstSListIter::WCIsvConstDListIWCExcept::not_empty 70 ter 312-313WCExcept::not_unique 70WCIsvConstSListIter::WCIsvConstSListItWCExcept::out_<strong>of</strong>_memory 70 er 309-310WCExcept::resize_required 70WCIsvConstSListIter::WCIsvConstSListItWCExcept::wc_state 66, 70 er 308WCExcept::WCExcept 66-67WCIsvConstSListIter::~WCIsvConstDLisWCExcept::zero_buckets 70 tIter 314WCExcept::~WCExcept 66, 68WCIsvConstSListIter::~WCIsvConstSListWCIsvConstDListIter, member function Iter 311WCIsvConstDListIter 312-313WCIsvConstSListIter::~WCIsvConstSListWCIsvConstSListIter 312-313 Iter 308WCIsvConstDListIter::append 308WCIsvDList, member functionWCIsvConstDListIter::container 308, 315 WCIsvDList 233, 236, 238-240WCIsvConstDListIter::current 308, 316 WCIsvSList 233, 236, 238-240WCIsvConstDListIter::insert 308 WCIsvDList::append 233, 241WCIsvConstDListIter::operator () 308, WCIsvDList::clear 233, 242317 WCIsvDList::clearAndDestroy 233, 243WCIsvConstDListIter::operator ++ 308, WCIsvDList::contains 233, 244318 WCIsvDList::entries 233, 245WCIsvConstDListIter::operator += 308, WCIsvDList::find 233, 246319 WCIsvDList::findLast 233, 247WCIsvConstDListIter::operator -- 308, WCIsvDList::forAll 233, 248320 WCIsvDList::get 233, 249WCIsvConstDListIter::operator -= 308, WCIsvDList::index 233, 250-251321 WCIsvDList::insert 233, 252WCIsvConstDListIter::reset 308, 322-323 WCIsvDList::isEmpty 233, 253WCIsvConstDListIter::WCIsvConstDListI WCIsvDList::operator = 233, 254ter 312-313 WCIsvDList::operator == 234, 255WCIsvConstDListIter::WCIsvConstSListI WCIsvDList::WCIsvDList 233, 236,ter 309-310 238-240WCIsvConstDListIter::~WCIsvConstDLis WCIsvDList::WCIsvSList 233, 235, 237tIter 314WCIsvDListIter, member functionWCIsvConstDListIter::~WCIsvConstSLis WCIsvDListIter 329-330tIter 311 WCIsvSListIter 329-330WCIsvConstSListIter, member function WCIsvDListIter::append 324, 332WCIsvConstDListIter 309-310 WCIsvDListIter::container 324, 333WCIsvConstSListIter 309-310 WCIsvDListIter::current 324, 334WCIsvConstSListIter::append 308 WCIsvDListIter::insert 324, 335WCIsvConstSListIter::container 308, 315 WCIsvDListIter::operator () 324, 336WCIsvConstSListIter::current 308, 316 WCIsvDListIter::operator ++ 324, 337WCIsvConstSListIter::insert 308 WCIsvDListIter::operator += 324, 338WCIsvConstSListIter::operator () 308, WCIsvDListIter::operator -- 324-325, 339317 WCIsvDListIter::operator -= 324-325,WCIsvConstSListIter::operator ++ 308, 340318 WCIsvDListIter::reset 324, 341-342WCIsvConstSListIter::operator += 308,WCIsvDListIter::WCIsvDListIter319 329-330913
IndexWCIsvDListIter::WCIsvSListIter WCIterExcept::exceptions 71, 74326-327 WCIterExcept::iter_range 75WCIsvDListIter::~WCIsvDListIter 331 WCIterExcept::undef_item 75WCIsvDListIter::~WCIsvSListIter 328 WCIterExcept::undef_iter 75WCIsvSList, member function WCIterExcept::wciter_state 71, 75WCIsvDList 233, 235, 237 WCIterExcept::WCIterExcept 71-72WCIsvSList 233, 235, 237 WCIterExcept::~WCIterExcept 71, 73WCIsvSList::append 233, 241WCListExceptWCIsvSList::clear 233, 242 class 66WCIsvSList::clearAndDestroy 233, 243WCPtrConstDListIter, member functionWCIsvSList::contains 233, 244 WCPtrConstDListIter 347-348WCIsvSList::entries 233, 245 WCPtrConstSListIter 347-348WCIsvSList::find 233, 246 WCPtrConstDListIter::append 343WCIsvSList::findLast 233, 247 WCPtrConstDListIter::container 343, 350WCIsvSList::forAll 233, 248 WCPtrConstDListIter::current 343, 351WCIsvSList::get 233, 249 WCPtrConstDListIter::insert 343WCIsvSList::index 233, 250-251 WCPtrConstDListIter::operator () 343,WCIsvSList::insert 233, 252 352WCIsvSList::isEmpty 233, 253 WCPtrConstDListIter::operator ++ 343,WCIsvSList::operator = 233, 254 353WCIsvSList::operator == 234, 255 WCPtrConstDListIter::operator += 343,WCIsvSList::WCIsvDList 233, 236, 354238-240 WCPtrConstDListIter::operator -- 343,WCIsvSList::WCIsvSList 233, 235, 237 355WCIsvSList::WCIsvSList 233 WCPtrConstDListIter::operator -= 343,WCIsvSList::~WCIsvSList 233 356WCIsvSListIter, member function WCPtrConstDListIter::reset 343, 357-358WCIsvDListIter 326-327WCPtrConstDListIter::WCPtrConstDListIWCIsvSListIter 326-327 ter 347-348WCIsvSListIter::append 324, 332WCPtrConstDListIter::WCPtrConstSListItWCIsvSListIter::container 324, 333 er 344-345WCIsvSListIter::current 324, 334WCPtrConstDListIter::~WCPtrConstDLisWCIsvSListIter::insert 324, 335 tIter 349WCIsvSListIter::operator () 324, 336WCPtrConstDListIter::~WCPtrConstSListWCIsvSListIter::operator ++ 324, 337 Iter 346WCIsvSListIter::operator += 324, 338WCPtrConstSListIter, member functionWCIsvSListIter::operator -- 324-325, 339 WCPtrConstDListIter 344-345WCIsvSListIter::operator -= 324-325, WCPtrConstSListIter 344-345340 WCPtrConstSListIter::append 343WCIsvSListIter::reset 324, 341-342 WCPtrConstSListIter::container 343, 350WCIsvSListIter::WCIsvDListIter WCPtrConstSListIter::current 343, 351329-330 WCPtrConstSListIter::insert 343WCIsvSListIter::WCIsvSListIter 326-327 WCPtrConstSListIter::operator () 343,WCIsvSListIter::WCIsvSListIter 352324 WCPtrConstSListIter::operator ++ 343,WCIsvSListIter::~WCIsvDListIter 331 353WCIsvSListIter::~WCIsvSListIter 328 WCPtrConstSListIter::operator += 343,WCIsvSListIter::~WCIsvSListIter 354324 WCPtrConstSListIter::operator -- 343,wciter_state, member enumeration 355WCIterExcept 71, 75 WCPtrConstSListIter::operator -= 343,WCIterExcept::all_fine 75 356WCIterExcept::check_all 75 WCPtrConstSListIter::reset 343, 357-358WCIterExcept::check_none 75914
IndexWCPtrConstSListIter::WCPtrConstDListIt WCPtrHashDict::clear 83, 90er 347-348WCPtrHashDict::clearAndDestroyWCPtrConstSListIter::WCPtrConstSListIt 83, 91er 344-345 WCPtrHashDict::contains 83, 92WCPtrConstSListIter::WCPtrConstSListIt WCPtrHashDict::entries 83, 93er 343 WCPtrHashDict::find 83, 94WCPtrConstSListIter::~WCPtrConstDListWCPtrHashDict::findKeyAndValueIter 349 83, 95WCPtrConstSListIter::~WCPtrConstSList WCPtrHashDict::forall 83, 96Iter 346 WCPtrHashDict::insert 83, 97WCPtrConstSListIter::~WCPtrConstSList WCPtrHashDict::isEmpty 83, 98Iter 343 WCPtrHashDict::operator = 83, 101WCPtrDList, member function WCPtrHashDict::operator == 83,WCPtrDList 260, 262-265 102WCPtrSList 260, 262-265 WCPtrHashDict::operator [] 83,WCPtrDList::append 256, 266 99-100WCPtrDList::clear 256, 267 WCPtrHashDict::remove 83, 103WCPtrDList::clearAndDestroy 256, 268 WCPtrHashDict::resize 83, 104WCPtrDList::contains 256, 269WCPtrHashDict::WCPtrHashDictWCPtrDList::entries 256, 270 82WCPtrDList::find 256, 271WCPtrHashDict::WCPtrHashDict 84-86WCPtrDList::forAll 256, 273WCPtrHashDict::~WCPtrHashDictWCPtrDList::get 256, 274 82WCPtrDList::index 256, 275WCPtrHashDict::~WCPtrHashDict 87WCPtrDList::isEmpty 256, 277WCPtrHashDictIter, member functionWCPtrDList::operator = 256, 278 WCPtrHashDictIter 181-182WCPtrDList::operator == 256, 279 WCPtrHashDictIter::container 180,WCPtrDList::WCPtrDList 260, 262-265 184WCPtrDList::WCPtrSList 258-259, 261 WCPtrHashDictIter::key 180, 185WCPtrDListIter, member function WCPtrHashDictIter::operator ()WCPtrDListIter 364-365 180, 186WCPtrSListIter 364-365 WCPtrHashDictIter::operator ++WCPtrDListIter::append 359, 367 180, 187WCPtrDListIter::container 359, 368 WCPtrHashDictIter::reset 180,WCPtrDListIter::current 359, 369 188-189WCPtrDListIter::insert 359, 370 WCPtrHashDictIter::value 180, 190WCPtrDListIter::operator () 359, 371WCPtrHashDictIter::WCPtrHashDicWCPtrDListIter::operator ++ 359, 372 tIter 181-182WCPtrDListIter::operator += 359, 373WCPtrHashDictIter::WCPtrHashDicWCPtrDListIter::operator -- 359-360, 374 tIter 180WCPtrDListIter::operator -= 359-360,WCPtrHashDictIter::~WCPtrHashDi375 ctIter 183WCPtrDListIter::reset 359, 376-377WCPtrHashDictIter::~WCPtrHashDiWCPtrDListIter::WCPtrDListIter ctIter 180364-365 WCPtrHashSet, member functionWCPtrDListIter::WCPtrSListIter 361-362 WCPtrHashSet 105WCPtrDListIter::~WCPtrDListIter 366 WCPtrHash<strong>Table</strong> 105WCPtrDListIter::~WCPtrSListIter 363 WCPtrHashSet::bitHash 106, 115WCPtrHashDict, member function WCPtrHashSet::buckets 106, 116WCPtrHashDict 82 WCPtrHashSet::clear 106, 117WCPtrHashDict::bitHash 82, 88 WCPtrHashSet::clearAndDestroy 106,WCPtrHashDict::buckets 82, 89 118915
IndexWCPtrHashSet::contains 106, 119 WCPtrHash<strong>Table</strong>::remove 106, 128WCPtrHashSet::entries 106, 120 WCPtrHash<strong>Table</strong>::removeAll 106, 129WCPtrHashSet::find 106, 121 WCPtrHash<strong>Table</strong>::resize 106, 130WCPtrHashSet::forall 106, 122 WCPtrHash<strong>Table</strong>::WCPtrHashSet 105WCPtrHashSet::insert 106, 123 WCPtrHash<strong>Table</strong>::WCPtrHash<strong>Table</strong> 105WCPtrHashSet::isEmpty 106, 124WCPtrHash<strong>Table</strong>::WCPtrHash<strong>Table</strong> 107-109, 111-113WCPtrHashSet::operator = 106, 126 WCPtrHash<strong>Table</strong>::~WCPtrHashSet 105WCPtrHashSet::operator == 106, 127WCPtrHash<strong>Table</strong>::~WCPtrHash<strong>Table</strong>WCPtrHashSet::remove 106, 128 106WCPtrHashSet::removeAll 106, 129WCPtrHash<strong>Table</strong>::~WCPtrHash<strong>Table</strong> 110, 114WCPtrHashSet::WCPtrHashSet 105WCPtrHash<strong>Table</strong>Iter, member functionWCPtrHashSet::WCPtrHash<strong>Table</strong> 105 WCPtrHashSetIter 206-207WCPtrHashSet::~WCPtrHashSet 105 WCPtrHash<strong>Table</strong>Iter 206-207WCPtrHashSet::~WCPtrHash<strong>Table</strong> 106 WCPtrHash<strong>Table</strong>Iter::container 202, 209WCPtrHashSetIter, member function WCPtrHash<strong>Table</strong>Iter::current 202, 210WCPtrHashSetIter 203-204 WCPtrHash<strong>Table</strong>Iter::operator () 202,WCPtrHash<strong>Table</strong>Iter 203-204 211WCPtrHashSetIter::container 202, 209 WCPtrHash<strong>Table</strong>Iter::operator ++ 202,WCPtrHashSetIter::current 202, 210 212WCPtrHashSetIter::operator () 202, 211 WCPtrHash<strong>Table</strong>Iter::reset 202, 213-214WCPtrHashSetIter::operator ++ 202, 212WCPtrHash<strong>Table</strong>Iter::WCPtrHashSetIterWCPtrHashSetIter::reset 202, 213-214 203-204WCPtrHashSetIter::WCPtrHashSetIterWCPtrHash<strong>Table</strong>Iter::WCPtrHash<strong>Table</strong>It203-204 er 206-207WCPtrHashSetIter::WCPtrHashSetIter 202 205WCPtrHashSetIter::WCPtrHash<strong>Table</strong>IterWCPtrHash<strong>Table</strong>Iter::~WCPtrHash<strong>Table</strong>I206-207 ter 208WCPtrHashSetIter::~WCPtrHashSetIterWCPtrOrderedVector, member function205 WCPtrOrderedVector 525WCPtrHashSetIter::~WCPtrHashSetIter< WCPtrSortedVector 525Type> 202 WCPtrOrderedVector::append 525, 532WCPtrHashSetIter::~WCPtrHash<strong>Table</strong>Iter WCPtrOrderedVector::clear 525, 533208 WCPtrOrderedVector::clearAndDestroyWCPtrHash<strong>Table</strong>, member function 525, 534WCPtrHashSet 105 WCPtrOrderedVector::contains 525, 535WCPtrHash<strong>Table</strong> 105 WCPtrOrderedVector::entries 525, 536WCPtrHash<strong>Table</strong>::bitHash 106, 115 WCPtrOrderedVector::find 525, 537WCPtrHash<strong>Table</strong>::buckets 106, 116 WCPtrOrderedVector::first 525, 538WCPtrHash<strong>Table</strong>::clear 106, 117 WCPtrOrderedVector::index 525, 539WCPtrHash<strong>Table</strong>::clearAndDestroy 106, WCPtrOrderedVector::insert 525, 540118 WCPtrOrderedVector::insertAt 525, 541WCPtrHash<strong>Table</strong>::contains 106, 119 WCPtrOrderedVector::isEmpty 525, 542WCPtrHash<strong>Table</strong>::entries 106, 120 WCPtrOrderedVector::last 525, 543WCPtrHash<strong>Table</strong>::find 106, 121WCPtrOrderedVector::occurrencesOfWCPtrHash<strong>Table</strong>::forall 106, 122 525, 544WCPtrHash<strong>Table</strong>::insert 106, 123 WCPtrOrderedVector::operator = 525,WCPtrHash<strong>Table</strong>::isEmpty 106, 124 546WCPtrHash<strong>Table</strong>::occurrencesOf 106, WCPtrOrderedVector::operator == 525,125 547WCPtrHash<strong>Table</strong>::operator = 106, 126 WCPtrOrderedVector::operator [] 525,WCPtrHash<strong>Table</strong>::operator == 106, 127 545916
IndexWCPtrOrderedVector::prepend 525, 548WCPtrSkipListDict::findKeyAndValWCPtrOrderedVector::remove 525, 549 ue 426, 437WCPtrOrderedVector::removeAll 525, WCPtrSkipListDict::forall 426, 438550 WCPtrSkipListDict::insert 426, 439WCPtrOrderedVector::removeAt 525, WCPtrSkipListDict::isEmpty 426,551 440WCPtrOrderedVector::removeFirst 525, WCPtrSkipListDict::operator = 427,552 443WCPtrOrderedVector::removeLast 525, WCPtrSkipListDict::operator ==553 427, 444WCPtrOrderedVector::resize 525, 554 WCPtrSkipListDict::operator []WCPtrOrderedVector::WCPtrOrderedVec 427, 441-442tor 525 WCPtrSkipListDict::remove 426,WCPtrOrderedVector::WCPtrSortedVecto 445r 525WCPtrSkipListDict::WCPtrSkipListWCPtrOrderedVector::~WCPtrOrderedVe Dict 426ctor 525WCPtrSkipListDict::WCPtrSkipListWCPtrOrderedVector::~WCPtrSortedVect Dict 428-430or 525WCPtrSkipListDict::~WCPtrSkipLisWCPtrSkipList, member function tDict 426WCPtrSkipList 446WCPtrSkipListDict::~WCPtrSkipLisWCPtrSkipListSet 446 tDict 431WCPtrSkipList::clear 446, 456WCPtrSkipListSet, member functionWCPtrSkipList::clearAndDestroy 446, WCPtrSkipList 446457 WCPtrSkipListSet 446WCPtrSkipList::contains 447, 458 WCPtrSkipListSet::clear 446, 456WCPtrSkipList::entries 447, 459 WCPtrSkipListSet::clearAndDestroy 446,WCPtrSkipList::find 447, 460 457WCPtrSkipList::forall 447, 461 WCPtrSkipListSet::contains 447, 458WCPtrSkipList::insert 447, 462 WCPtrSkipListSet::entries 447, 459WCPtrSkipList::isEmpty 447, 463 WCPtrSkipListSet::find 447, 460WCPtrSkipList::occurrencesOf 447, 464 WCPtrSkipListSet::forall 447, 461WCPtrSkipList::operator = 447, 465 WCPtrSkipListSet::insert 447, 462WCPtrSkipList::operator == 447, 466 WCPtrSkipListSet::isEmpty 447, 463WCPtrSkipList::remove 447, 467 WCPtrSkipListSet::occurrencesOf 447,WCPtrSkipList::removeAll 447, 468 464WCPtrSkipList::WCPtrSkipList 446 WCPtrSkipListSet::operator = 447, 465WCPtrSkipList::WCPtrSkipList WCPtrSkipListSet::operator == 447, 466448-450, 452-454 WCPtrSkipListSet::remove 447, 467WCPtrSkipList::WCPtrSkipListSet 446 WCPtrSkipListSet::removeAll 447, 468WCPtrSkipList::~WCPtrSkipList 446 WCPtrSkipListSet::WCPtrSkipList 446WCPtrSkipList::~WCPtrSkipListWCPtrSkipListSet::WCPtrSkipListSet451, 455 446WCPtrSkipList::~WCPtrSkipListSet 446 WCPtrSkipListSet::~WCPtrSkipList 446WCPtrSkipListDict, member functionWCPtrSkipListSet::~WCPtrSkipListSetWCPtrSkipListDict 426 446WCPtrSkipListDict::clear 426, 432WCPtrSList, member functionWCPtrSkipListDict::clearAndDestro WCPtrDList 258-259, 261y 426, 433 WCPtrSList 258-259, 261WCPtrSkipListDict::contains 426, WCPtrSList::append 256, 266434 WCPtrSList::clear 256, 267WCPtrSkipListDict::entries 426, WCPtrSList::clearAndDestroy 256, 268435 WCPtrSList::contains 256, 269WCPtrSkipListDict::find 426, 436 WCPtrSList::entries 256, 270917
IndexWCPtrSList::find 256, 271 WCPtrSortedVector::operator = 525, 546WCPtrSList::findLast 256, 272 WCPtrSortedVector::operator == 525,WCPtrSList::forAll 256, 273 547WCPtrSList::get 256, 274 WCPtrSortedVector::operator [] 525, 545WCPtrSList::index 256, 275 WCPtrSortedVector::prepend 525, 548WCPtrSList::insert 256, 276 WCPtrSortedVector::remove 525, 549WCPtrSList::isEmpty 256, 277 WCPtrSortedVector::removeAll 525, 550WCPtrSList::operator = 256, 278 WCPtrSortedVector::removeAt 525, 551WCPtrSList::operator == 256, 279 WCPtrSortedVector::removeFirst 525,WCPtrSList::WCPtrDList 260, 262-265 552WCPtrSList::WCPtrSList 258-259, 261 WCPtrSortedVector::removeLast 525,WCPtrSList::WCPtrSList 256 553WCPtrSList::~WCPtrSList 256 WCPtrSortedVector::resize 525, 554WCPtrSListItemSizeWCPtrSortedVector::WCPtrOrderedVectomacro 416, 514 r 525WCPtrSListIter, member functionWCPtrSortedVector::WCPtrSortedVectorWCPtrDListIter 361-362 525WCPtrSListIter 361-362WCPtrSortedVector::WCPtrSortedVectorWCPtrSListIter::append 359, 367 526-527, 529-530WCPtrSListIter::container 359, 368WCPtrSortedVector::~WCPtrOrderedVectWCPtrSListIter::current 359, 369 or 525WCPtrSListIter::insert 359, 370WCPtrSortedVector::~WCPtrSortedVectoWCPtrSListIter::operator () 359, 371 r 525WCPtrSListIter::operator ++ 359, 372WCPtrSortedVector::~WCPtrSortedVectoWCPtrSListIter::operator += 359, 373 r 528, 531WCPtrSListIter::operator -- 359-360, 374 WCPtrVector::clear 555, 560WCPtrSListIter::operator -= 359-360, 375 WCPtrVector::clearAndDestroy 555, 561WCPtrSListIter::reset 359, 376-377 WCPtrVector::length 555, 562WCPtrSListIter::WCPtrDListIter 364-365 WCPtrVector::operator = 555, 564WCPtrSListIter::WCPtrSListIter 361-362 WCPtrVector::operator == 555, 565WCPtrSListIter::WCPtrSListIter WCPtrVector::operator [] 555, 563359 WCPtrVector::resize 555, 566WCPtrSListIter::~WCPtrDListIter 366WCPtrVector::WCPtrVectorWCPtrSListIter::~WCPtrSListIter 363 555-558WCPtrSListIter::~WCPtrSListIterWCPtrVector::~WCPtrVector359 555, 559WCPtrSortedVector, member function WCQueue::clear 414, 418WCPtrOrderedVector 525 WCQueue::entries 414, 419WCPtrSortedVector 525 WCQueue::first 414, 420WCPtrSortedVector::append 525, 532 WCQueue::get 414, 421WCPtrSortedVector::clear 525, 533 WCQueue::insert 414, 422WCPtrSortedVector::clearAndDestroy WCQueue::isEmpty 414, 423525, 534 WCQueue::last 414, 424WCPtrSortedVector::contains 525, 535WCQueue::WCQueue 414-416WCPtrSortedVector::find 525, 537WCQueue::~WCQueue 414, 417WCPtrSortedVector::index 525, 539 WCSLink 230WCPtrSortedVector::insert 525, 540 WCSLink::WCSLink 280-281WCPtrSortedVector::insertAt 525, 541 WCSLink::~WCSLink 280, 282WCPtrSortedVector::isEmpty 525, 542 WCStack::clear 512, 516WCPtrSortedVector::last 525, 543 WCStack::entries 512, 517WCPtrSortedVector::occurrencesOf 525, WCStack::isEmpty 512, 518544 WCStack::pop 512, 519918
IndexWCStack::push 512, 520WCValConstSListIter::WCValConstSListWCStack::top 512, 521 Iter 379-380WCStack::WCStackWCValConstSListIter::WCValConstSList512-514 Iter 378WCStack::~WCStack 512, 515 stIter 384WCValConstDListIter, member functionWCValConstSListIter::~WCValConstSLiWCValConstDListIter 382-383 stIter 381WCValConstSListIter 382-383WCValConstSListIter::~WCValConstSLiWCValConstDListIter::append 378 stIter 378WCValConstDListIter::container 378,WCValDList, member function385 WCValDList 287, 289-292WCValConstDListIter::current 378, 386 WCValSList 287, 289-292WCValConstDListIter::insert 378 WCValDList::append 283, 293WCValConstDListIter::operator () 378, WCValDList::clear 283, 294387 WCValDList::clearAndDestroy 283, 295WCValConstDListIter::operator ++ 378, WCValDList::contains 283, 296388 WCValDList::entries 283, 297WCValConstDListIter::operator += 378, WCValDList::find 283, 298389 WCValDList::findLast 283, 299WCValConstDListIter::operator -- 378, WCValDList::forAll 283, 300390 WCValDList::get 283, 301WCValConstDListIter::operator -= 378, WCValDList::index 283, 302391 WCValDList::insert 283, 303WCValConstDListIter::reset 378, WCValDList::isEmpty 283, 304392-393 WCValDList::operator = 284, 305WCValConstDListIter::WCValConstDLis WCValDList::operator == 284, 306tIter 382-383 WCValDList::WCValDList 287, 289-292WCValConstDListIter::WCValConstSList WCValDList::WCValSList 285-286, 288Iter 379-380WCValDListItemSizeWCValConstDListIter::~WCValConstDLi macro 263, 290stIter 384WCValDListIter, member functionWCValConstDListIter::~WCValConstSLi WCValDListIter 399-400stIter 381 WCValSListIter 399-400WCValConstSListIter, member function WCValDListIter::append 394, 402WCValConstDListIter 379-380 WCValDListIter::container 394, 403WCValConstSListIter 379-380 WCValDListIter::current 394, 404WCValConstSListIter::append 378 WCValDListIter::insert 394, 405WCValConstSListIter::container 378, 385 WCValDListIter::operator () 394, 406WCValConstSListIter::current 378, 386 WCValDListIter::operator ++ 394, 407WCValConstSListIter::insert 378 WCValDListIter::operator += 394, 408WCValConstSListIter::operator () 378, WCValDListIter::operator -- 394-395,387 409WCValConstSListIter::operator ++ 378, WCValDListIter::operator -= 394-395,388 410WCValConstSListIter::operator += 378, WCValDListIter::reset 394, 411-412389 WCValDListIter::WCValDListIterWCValConstSListIter::operator -- 378, 399-400390 WCValDListIter::WCValSListIterWCValConstSListIter::operator -= 378, 396-397391 WCValDListIter::~WCValDListIter 401WCValConstSListIter::reset 378, 392-393 WCValDListIter::~WCValSListIter 398WCValConstSListIter::WCValConstDListWCValHashDict, member functionIter 382-383 WCValHashDict 132919
IndexWCValHashDict::bitHash 132, 137 WCValHashSet::contains 154, 166WCValHashDict::buckets 132, 138 WCValHashSet::entries 154, 167WCValHashDict::clear 132, 139 WCValHashSet::find 154, 168WCValHashDict::contains 132, 140 WCValHashSet::forall 154, 169WCValHashDict::entries 132, 141 WCValHashSet::insert 154, 170WCValHashDict::find 132, 142 WCValHashSet::isEmpty 154, 171WCValHashDict::findKeyAndValue WCValHashSet::occurrencesOf 154, 172132, 143 WCValHashSet::operator = 154, 173WCValHashDict::forall 132, 144 WCValHashSet::operator == 154, 174WCValHashDict::insert 132, 145 WCValHashSet::remove 154, 175WCValHashDict::isEmpty 132, 146 WCValHashSet::removeAll 154, 176WCValHashDict::operator = 132, WCValHashSet::resize 154, 177149 WCValHashSet::WCValHashSet 153WCValHashDict::operator == 132, WCValHashSet::WCValHash<strong>Table</strong> 154150 WCValHashSet::~WCValHashSet 154WCValHashDict::operator [] 132, WCValHashSet::~WCValHash<strong>Table</strong> 154147-148 WCValHashSetIter, member functionWCValHashDict::remove 132, 151 WCValHashSetIter 216-217WCValHashDict::resize 132, 152 WCValHash<strong>Table</strong>Iter 216-217WCValHashDict::WCValHashDict WCValHashSetIter::container 215, 222132 WCValHashSetIter::current 215, 223WCValHashDict::WCValHashDict< WCValHashSetIter::operator () 215, 224Key,Value> 133-135 WCValHashSetIter::operator ++ 215, 225WCValHashDict::~WCValHashDict WCValHashSetIter::reset 215, 226-227132 WCValHashSetIter::WCValHashSetIterWCValHashDict::~WCValHashDict 216-217 136WCValHashSetIter::WCValHashSetIter 215WCValHashDictIter 192-193WCValHashSetIter::WCValHash<strong>Table</strong>IterWCValHashDictIter::container 191, 219-220195 WCValHashSetIter::~WCValHashSetIterWCValHashDictIter::key 191, 196 218WCValHashDictIter::operator ()WCValHashSetIter::~WCValHashSetIter191, 197 215WCValHashDictIter::operator ++WCValHashSetIter::~WCValHash<strong>Table</strong>It191, 198 er 221WCValHashDictIter::reset 191,WCValHash<strong>Table</strong>, member function199-200 WCValHashSet 154WCValHashDictIter::value 191, WCValHash<strong>Table</strong> 154201 WCValHash<strong>Table</strong>::bitHash 154, 163WCValHashDictIter::WCValHashDi WCValHash<strong>Table</strong>::buckets 154, 164ctIter 192-193 WCValHash<strong>Table</strong>::clear 154, 165WCValHashDictIter::WCValHashDi WCValHash<strong>Table</strong>::contains 154, 166ctIter 191 WCValHash<strong>Table</strong>::entries 154, 167WCValHashDictIter::~WCValHash WCValHash<strong>Table</strong>::find 154, 168DictIter 194 WCValHash<strong>Table</strong>::forall 154, 169WCValHashDictIter::~WCValHash WCValHash<strong>Table</strong>::insert 154, 170DictIter 191 WCValHash<strong>Table</strong>::isEmpty 154, 171WCValHashSet, member function WCValHash<strong>Table</strong>::occurrencesOf 154,WCValHashSet 153 172WCValHash<strong>Table</strong> 153 WCValHash<strong>Table</strong>::operator = 154, 173WCValHashSet::bitHash 154, 163 WCValHash<strong>Table</strong>::operator == 154, 174WCValHashSet::buckets 154, 164 WCValHash<strong>Table</strong>::remove 154, 175WCValHashSet::clear 154, 165 WCValHash<strong>Table</strong>::removeAll 154, 176920
IndexWCValHash<strong>Table</strong>::resize 154, 177 WCValOrderedVector::removeAll 568,WCValHash<strong>Table</strong>::WCValHashSet 153 593WCValHash<strong>Table</strong>::WCValHash<strong>Table</strong> WCValOrderedVector::removeAt 568,154 594WCValHash<strong>Table</strong>::WCValHash<strong>Table</strong> 155-157, 159-161 595WCValHash<strong>Table</strong>::~WCValHashSet 154 WCValOrderedVector::removeLast 568,WCValHash<strong>Table</strong>::~WCValHash<strong>Table</strong> 596154 WCValOrderedVector::resize 568, 597WCValHash<strong>Table</strong>::~WCValHash<strong>Table</strong> 158, 162 ctor 568WCValHash<strong>Table</strong>Iter, member functionWCValOrderedVector::WCValSortedVectWCValHashSetIter 219-220 or 568WCValHash<strong>Table</strong>Iter 219-220WCValOrderedVector::~WCValOrderedWCValHash<strong>Table</strong>Iter::container 215, 222 Vector 568WCValHash<strong>Table</strong>Iter::current 215, 223WCValOrderedVector::~WCValSortedVeWCValHash<strong>Table</strong>Iter::operator () 215, ctor 568224 WCValSkipList, member functionWCValHash<strong>Table</strong>Iter::operator ++ 215, WCValSkipList 488225 WCValSkipListSet 488WCValHash<strong>Table</strong>Iter::reset 215, 226-227 WCValSkipList::clear 489, 498WCValHash<strong>Table</strong>Iter::WCValHashSetIter WCValSkipList::contains 489, 499216-217 WCValSkipList::entries 489, 500WCValHash<strong>Table</strong>Iter::WCValHash<strong>Table</strong>I WCValSkipList::find 489, 501ter 219-220 WCValSkipList::forall 489, 502WCValHash<strong>Table</strong>Iter::~WCValHashSetIt WCValSkipList::insert 489, 503er 218 WCValSkipList::isEmpty 489, 504WCValHash<strong>Table</strong>Iter::~WCValHashTabl WCValSkipList::occurrencesOf 489, 505eIter 221 WCValSkipList::operator = 489, 506WCValOrderedVector, member function WCValSkipList::operator == 489, 507WCValOrderedVector 568 WCValSkipList::remove 489, 508WCValSortedVector 568 WCValSkipList::removeAll 489, 509WCValOrderedVector::append 568, 576 WCValSkipList::WCValSkipList 488WCValOrderedVector::clear 568, 577WCValSkipList::WCValSkipListWCValOrderedVector::contains 568, 578 490-492, 494-496WCValOrderedVector::entries 568, 579WCValSkipList::WCValSkipListSetWCValOrderedVector::find 568, 580 488-489WCValOrderedVector::first 568, 581 WCValSkipList::~WCValSkipList 488WCValOrderedVector::index 568, 582WCValSkipList::~WCValSkipListWCValOrderedVector::insert 568, 583 493, 497WCValOrderedVector::insertAt 568, 584WCValSkipList::~WCValSkipListSetWCValOrderedVector::isEmpty 568, 585 489WCValOrderedVector::last 568, 586WCValSkipListDict, member functionWCValOrderedVector::occurrencesOf WCValSkipListDict 470568, 587 WCValSkipListDict::clear 470, 475WCValOrderedVector::operator = 569, WCValSkipListDict::contains 470,589 476WCValOrderedVector::operator == 569, WCValSkipListDict::entries 470,590 477WCValOrderedVector::operator [] 568, WCValSkipListDict::find 470, 478588 WCValSkipListDict::findKeyAndVaWCValOrderedVector::prepend 568, 591 lue 470, 479WCValOrderedVector::remove 568, 592 WCValSkipListDict::forall 470, 480921
IndexWCValSkipListDict::insert 470, WCValSList::get 283, 301481 WCValSList::index 283, 302WCValSkipListDict::isEmpty 470, WCValSList::insert 283, 303482 WCValSList::isEmpty 283, 304WCValSkipListDict::operator = WCValSList::operator = 284, 305470, 485 WCValSList::operator == 284, 306WCValSkipListDict::operator == WCValSList::WCValDList 287, 289-292470, 486 WCValSList::WCValSList 285-286, 288WCValSkipListDict::operator [] WCValSList::WCValSList 283470, 483-484 WCValSList::~WCValSList 283WCValSkipListDict::remove 470,WCValSListItemSize487 macro 259, 286, 416, 514WCValSkipListDict::WCValSkipLisWCValSListIter, member functiontDict 470 WCValDListIter 396-397WCValSkipListDict::WCValSkipLis WCValSListIter 396-397tDict 471-473 WCValSListIter::append 394, 402WCValSkipListDict::~WCValSkipL WCValSListIter::container 394, 403istDict 470 WCValSListIter::current 394, 404WCValSkipListDict::~WCValSkipL WCValSListIter::insert 394, 405istDict 474 WCValSListIter::operator () 394, 406WCValSkipListSet, member function WCValSListIter::operator ++ 394, 407WCValSkipList 488-489 WCValSListIter::operator += 394, 408WCValSkipListSet 488-489 WCValSListIter::operator -- 394-395,WCValSkipListSet::clear 489, 498 409WCValSkipListSet::contains 489, 499 WCValSListIter::operator -= 394-395,WCValSkipListSet::entries 489, 500 410WCValSkipListSet::find 489, 501 WCValSListIter::reset 394, 411-412WCValSkipListSet::forall 489, 502WCValSListIter::WCValDListIterWCValSkipListSet::insert 489, 503 399-400WCValSkipListSet::isEmpty 489, 504WCValSListIter::WCValSListIterWCValSkipListSet::occurrencesOf 489, 396-397505 WCValSListIter::WCValSListIterWCValSkipListSet::operator = 489, 506 394WCValSkipListSet::operator == 489, 507 WCValSListIter::~WCValDListIter 401WCValSkipListSet::remove 489, 508 WCValSListIter::~WCValSListIter 398WCValSkipListSet::removeAll 489, 509WCValSListIter::~WCValSListIter 394WCValSkipListSet::WCValSkipListSetWCValSortedVector, member function488-489 WCValOrderedVector 568WCValSkipListSet::~WCValSkipList WCValSortedVector 568488 WCValSortedVector::append 568, 576WCValSkipListSet::~WCValSkipListSet WCValSortedVector::clear 568, 577489 WCValSortedVector::contains 568, 578WCValSList, member function WCValSortedVector::entries 568, 579WCValDList 285-286, 288 WCValSortedVector::find 568, 580WCValSList 285-286, 288 WCValSortedVector::first 568, 581WCValSList::append 283, 293 WCValSortedVector::index 568, 582WCValSList::clear 283, 294 WCValSortedVector::insert 568, 583WCValSList::clearAndDestroy 283, 295 WCValSortedVector::insertAt 568, 584WCValSList::contains 283, 296 WCValSortedVector::isEmpty 568, 585WCValSList::entries 283, 297 WCValSortedVector::last 568, 586WCValSList::find 283, 298 WCValSortedVector::occurrencesOf 568,WCValSList::findLast 283, 299 587WCValSList::forAll 283, 300 WCValSortedVector::operator = 569, 589922
IndexWCValSortedVector::operator == 569,590WCValSortedVector::operator [] 568,Z588WCValSortedVector::prepend 568, 591WCValSortedVector::remove 568, 592zero_bucketsWCValSortedVector::removeAll 568,exception 70, 104, 130, 152, 177593zero_buckets, member enumerationWCValSortedVector::removeAt 568, 594WCExcept 70WCValSortedVector::removeFirst 568,595WCValSortedVector::removeLast 568,596~WCValSortedVector::resize 568, 597WCValSortedVector::WCValOrderedVector 568WCValSortedVector::WCValSortedVecto~WCIsvConstDListIter, member functionr 568 WCIsvConstDListIter 314WCValSortedVector::WCValSortedVecto WCIsvConstSListIter 314r 570-571, 573-574~WCIsvConstSListIter, member functionWCValSortedVector::~WCValOrderedVe WCIsvConstDListIter 311ctor 568 WCIsvConstSListIter 311WCValSortedVector::~WCValSortedVect~WCIsvDListIter, member functionor 568 WCIsvDListIter 331WCValSortedVector::~WCValSortedVect WCIsvSListIter 331or 572, 575~WCIsvSListIter, member functionWCValVector::clear 598, 603 WCIsvDListIter 328WCValVector::length 598, 604 WCIsvSListIter 328WCValVector::operator = 598, 606~WCPtrConstDListIter, member functionWCValVector::operator == 598, 607 WCPtrConstDListIter 349WCValVector::operator [] 598, 605 WCPtrConstSListIter 349WCValVector::resize 598, 608~WCPtrConstSListIter, member functionWCValVector::WCValVector WCPtrConstDListIter 346598-601 WCPtrConstSListIter 346WCValVector::~WCValVector~WCPtrDListIter, member function598, 602 WCPtrDListIter 366width, member function WCPtrSListIter 366ios 655-656, 689~WCPtrHashDict, member functionwrite, member function WCPtrHashDict 82ostream 755, 777~WCPtrHashDictIter, member functionws, manipulator 733, 747 WCPtrHashDictIter 183~WCPtrHashSet, member functionWCPtrHashSet 105WCPtrHash<strong>Table</strong> 105X~WCPtrHashSetIter, member functionWCPtrHashSetIter 205WCPtrHash<strong>Table</strong>Iter 205~WCPtrHash<strong>Table</strong>, member functionxalloc, member functionWCPtrHashSet 106ios 656, 690WCPtrHash<strong>Table</strong> 106~WCPtrHash<strong>Table</strong>Iter, member functionWCPtrHashSetIter 208WCPtrHash<strong>Table</strong>Iter 208~WCPtrOrderedVector, member function923
IndexWCPtrOrderedVector 525 WCValSListIter 398WCPtrSortedVector 525~WCValSortedVector, member function~WCPtrSkipList, member function WCValOrderedVector 568WCPtrSkipList 446 WCValSortedVector 568WCPtrSkipListSet 446~WCPtrSkipListDict, member functionWCPtrSkipListDict 426~WCPtrSkipListSet, member functionWCPtrSkipList 446WCPtrSkipListSet 446~WCPtrSListIter, member functionWCPtrDListIter 363WCPtrSListIter 363~WCPtrSortedVector, member functionWCPtrOrderedVector 525WCPtrSortedVector 525~WCValConstDListIter, member functionWCValConstDListIter 384WCValConstSListIter 384~WCValConstSListIter, member functionWCValConstDListIter 381WCValConstSListIter 381~WCValDListIter, member functionWCValDListIter 401WCValSListIter 401~WCValHashDict, member functionWCValHashDict 132~WCValHashDictIter, member functionWCValHashDictIter 194~WCValHashSet, member functionWCValHashSet 154WCValHash<strong>Table</strong> 154~WCValHashSetIter, member functionWCValHashSetIter 218WCValHash<strong>Table</strong>Iter 218~WCValHash<strong>Table</strong>, member functionWCValHashSet 154WCValHash<strong>Table</strong> 154~WCValHash<strong>Table</strong>Iter, member functionWCValHashSetIter 221WCValHash<strong>Table</strong>Iter 221~WCValOrderedVector, member functionWCValOrderedVector 568WCValSortedVector 568~WCValSkipList, member functionWCValSkipList 488WCValSkipListSet 488~WCValSkipListDict, member functionWCValSkipListDict 470~WCValSkipListSet, member functionWCValSkipList 489WCValSkipListSet 489~WCValSListIter, member functionWCValDListIter 398924
Change language