home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / VSCPPv4.zip / VACPP / IBMCPP / HELP / CPPCLRF.INF (.txt) < prev    next >
OS/2 Help File  |  1995-05-16  |  523KB  |  18,438 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About this Online Reference ΓòÉΓòÉΓòÉ
  3.  
  4. This reference describes the classes and class members that are included in IBM 
  5. Open Class Library. 
  6.  
  7.       Notices 
  8.       Trade/Service Marks 
  9.       What is IBM Open Class? 
  10.       About Examples 
  11.       Using this Book 
  12.       Contextual Help 
  13.       Finding Descriptions 
  14.       Using the TOC 
  15.       Getting More Information 
  16.       Action Bar Choices 
  17.       Cutting and Pasting 
  18.       Other Helpful Information 
  19.       Sending Comments to IBM 
  20.  
  21.  
  22. ΓòÉΓòÉΓòÉ 1.1. Notices ΓòÉΓòÉΓòÉ
  23.  
  24. Copyright International Business Machines Corporation, 1992, 1995. All rights 
  25. reserved. 
  26.  
  27. Note to U.S. Government Users - Documentation related to restricted rights - 
  28. Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP 
  29. Schedule Contract with IBM Corp. 
  30.  
  31. First Edition, May 1995 
  32.  
  33. This edition applies to Version 3.0 of IBM VisualAge C ++ for OS/2 ( 30H1664, 
  34. 30H1665, 30H1666) and to all subsequent releases and modifications until 
  35. otherwise indicated in new editions.  Make sure you are using the correct 
  36. edition for the level of the product. 
  37.  
  38. This publication could include technical inaccuracies or typographical errors. 
  39. Changes are periodically made to the information herein; any such changes will 
  40. be reported in subsequent revisions. 
  41.  
  42. Requests for publications and for technical information about IBM products 
  43. should be made to your IBM Authorized Dealer or your IBM Marketing 
  44. Representative. 
  45.  
  46. When you send information to IBM, you grant IBM a nonexclusive right to use or 
  47. distribute the information in any ways it believes appropriate without 
  48. incurring any obligation to you. 
  49.  
  50. Any reference to an IBM licensed program in this publication is not intended to 
  51. state or imply that only IBM's licensed program may be used. Any functionally 
  52. equivalent product, program, or service that does not infringe any of IBM's 
  53. intellectual property rights may be used instead of the IBM product, program, 
  54. or service. Evaluation and verification of operation in conjunction with other 
  55. products, except  those expressly designated by IBM, is the user's 
  56. responsibility. 
  57.  
  58. IBM may have patents or pending patent applications covering subject matter in 
  59. this document.  The furnishing of this document does not give you any license 
  60. to these patents.  You can send license inquiries, in writing, to the IBM 
  61. Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY, 
  62. 10594, USA. 
  63.  
  64.  
  65. ΓòÉΓòÉΓòÉ 1.2. Trademarks and Service Marks ΓòÉΓòÉΓòÉ
  66.  
  67. The following terms used in this publication are trademarks or service marks of 
  68. IBM Corporation in the United States or other countries: 
  69.  
  70.       AIX 
  71.       BookManager 
  72.       C/2 
  73.       C Set/2 
  74.       C Set ++ 
  75.       Common User Access 
  76.       CUA 
  77.       IBM 
  78.       Open Class 
  79.       Operating System/2 
  80.       OS/2 
  81.       Personal System/2 
  82.       Presentation Manager 
  83.       PS/2 
  84.       VisualAge 
  85.       WorkFrame 
  86.  
  87.  Windows is a trademark of Microsoft Corporation. 
  88.  
  89.  UNIX is a registered trademark in the United States and other countries 
  90.  licensed exclusively through X/Open Company Limited. 
  91.  
  92.  Other company, product, and service names, which may be denoted by a double 
  93.  asterisk(**), may be trademarks or service marks of others. 
  94.  
  95.  
  96. ΓòÉΓòÉΓòÉ 1.3. What is IBM Open Class Library? ΓòÉΓòÉΓòÉ
  97.  
  98. IBM Open Class Library (or IBM Open Class) consists of classes in the following 
  99. categories: 
  100.  
  101.      Complex Mathematics 
  102.      I/O Streams 
  103.      Collections 
  104.      Data Types 
  105.      Exceptions 
  106.      Database Access Builder 
  107.      User Interface, including the following: 
  108.         -  Windows, Menus, Handlers, and Events 
  109.         -  Advanced Controls, Dialogs, and their Handlers 
  110.         -  Direct Manipulation Classes 
  111.         -  Dynamic Data Exchange (DDE) Classes 
  112.         -  2-Dimensional Graphic Classes 
  113.         -  Multimedia Classes 
  114.  
  115.  This book is intended for skilled C++ programmers who understand the concept 
  116.  of classes and who are familiar with using C++ templates when working with 
  117.  individual class libraries. Use this book if you want to do any of the 
  118.  following in your C++ programs: 
  119.  
  120.      Manipulate complex numbers (numbers with both a real and an imaginary 
  121.       part) 
  122.      Perform input and output to console or files using a typesafe, 
  123.       object-oriented programming approach 
  124.      Implement commonly used abstract data types, including sets, maps, 
  125.       sequences, trees, stacks, queues, and sorted or keyed collections 
  126.      Manipulate strings with greater ease and flexibility than the standard 
  127.       C++ method of using character pointers and the string functions of the C 
  128.       string.h library 
  129.      Use date and time information and apply member functions to date and time 
  130.       objects 
  131.      Use Data Access Builder generated source code in conjunction with the 
  132.       Data Access Builder class library to access a DB2/2 relational database. 
  133.      Simplify the development of portable applications containing graphical 
  134.       user interfaces (GUI). 
  135.      Simulate Common User Access (CUA) workplace look and feel and take 
  136.       advantage of Presentation Manager features. 
  137.  
  138.  Before you begin to use this information, it would be helpful to understand 
  139.  how to navigate through it. You can use the Table of Contents and Index 
  140.  facility to locate topics and the Search facility to search the text of this 
  141.  document. You can use hypertext links to acquire related information on the 
  142.  current topic.  Hypertext links appear in a different color (which you can 
  143.  customize using the OS/2 Scheme Palette). For example, here is a link to 
  144.  another panel: Communicating Your Comments to IBM. By double-clicking on the 
  145.  text of the link or by pressing Enter on a highlighted link, you will open a 
  146.  panel of related information. When you open a panel, the first link has the 
  147.  focus; to shift the focus to other links, use the Tab key. 
  148.  
  149.  You should also understand: 
  150.  
  151.      How to Use the Contents 
  152.      How to Obtain Additional Information 
  153.      How to Use Action Bar Choices 
  154.      How to Cut and Paste Examples 
  155.  
  156.  
  157. ΓòÉΓòÉΓòÉ 1.4. A Note about Examples ΓòÉΓòÉΓòÉ
  158.  
  159. The examples in this book explain elements of the C++ class libraries. They are 
  160. coded in a simple style. They do not try to conserve storage, check for errors, 
  161. achieve fast run times, or demonstrate all possible uses of a library, class, 
  162. or member function. 
  163.  
  164. Source Files for Samples 
  165.  
  166. This online reference contains links to the runnable sample programs that are 
  167. shipped as separate files with IBM Open Class. There can be up to five links 
  168. for each member function. Functions with multiple overloads may have links to 
  169. the samples for each overload. When you select a sample, the sample is loaded 
  170. into the editor defined in your WorkFrame profile at the function's line and 
  171. column. 
  172.  
  173. Collection Class Library samples are included in this online document as well. 
  174. All of these sample source files are located in the following directory: 
  175.  
  176. \ibmcpp\samples\ioc
  177.  
  178. Examples are code excerpts or runnable programs that are not shipped as 
  179. separate files with IBM Open Class; they exist only in this reference. 
  180.  
  181.  
  182. ΓòÉΓòÉΓòÉ 1.5. How to Use the Features of this Book ΓòÉΓòÉΓòÉ
  183.  
  184. The IBM Open Class Library classes are grouped into major categories. These 
  185. groups comprise the majority of this document. You can use this information as 
  186. a guide when choosing classes. 
  187.  
  188. You can quickly locate and learn more about any class using the alphabetical 
  189. reference in Classes by Name. 
  190.  
  191. The header file on many class description panels is a link that brings up your 
  192. WorkFrame editor and loads the appropriate .HPP file. You can link to the .HPP 
  193. for all classes from the Class to Header File Cross-Reference found at the end 
  194. of this book. 
  195.  
  196. Also in this book, classes, member functions, and enumerations might have the 
  197. following sections: 
  198.  
  199.       Portability Considerations 
  200.       Motif Information 
  201.       Presentation Manager Information 
  202.  
  203.  These sections contain information that is specific to a particular platform 
  204.  or suggestions for developing portable applications. 
  205.  
  206.  Note that some members have a Platform Support Table. If a member function is 
  207.  overloaded, one overload might have one condition, while a second overload has 
  208.  a different condition. For example, in IBaseSpinButton::initialize, one 
  209.  implementation is for both AIX and OS/2, while another implementation is for 
  210.  OS/2 only. 
  211.  
  212.  This table lists each platform in the heading and the table entries explain if 
  213.  the function is supported, not supported, or silently ignored. 
  214.  
  215.  
  216. ΓòÉΓòÉΓòÉ 1.6. The Contextual Help Feature ΓòÉΓòÉΓòÉ
  217.  
  218. IBM Open Class provides contextual help for each class and member function. To 
  219. access contextual help: 
  220.  
  221.      Install the CPP*.INF and CPP.NDX and CPPBRS.NDX files 
  222.      Use the VisualAge Editor or the Enhanced System Editor provided by OS/2 
  223.  
  224.  Access contextual help by positioning the cursor over the name of a class or 
  225.  member function in the text you are editing, and then pressing Ctrl-H. This 
  226.  opens the online version of the IBM Open Class Library Reference and displays 
  227.  information about that class or member function. 
  228.  
  229.  Refer to the product installation instructions for complete details on setting 
  230.  the environment variables needed to use the contextual help feature. 
  231.  
  232.  
  233. ΓòÉΓòÉΓòÉ 1.7. How to Find Class or Function Descriptions ΓòÉΓòÉΓòÉ
  234.  
  235. You can use this online reference to find individual class or member function 
  236. documentation.  If you know what library or group a class is in, expand the 
  237. table of contents entry for that library or group, and select the class from 
  238. there.  When you select a class entry from the table of contents, the lefthand 
  239. panel contains a list of hypertext links including one for member functions. 
  240. Select that link and a list of member functions is displayed.  You can then 
  241. select the member function you want information on. 
  242.  
  243. You can also search on a member function name, or on a fully qualified name: 
  244. Class::function. For flat collections, search only on the function name if you 
  245. want information on a particular function; the Class::function syntax will not 
  246. work for these functions. 
  247.  
  248. You can also use the Source Code Browser or an editor to find information on 
  249. any function, if you use the CPPBRS.NDX help index file. 
  250.  
  251.  
  252. ΓòÉΓòÉΓòÉ 1.8. How to Use the Contents ΓòÉΓòÉΓòÉ
  253.  
  254. When the Contents window first appears, some topics have a plus (+) sign beside 
  255. them. The plus sign indicates that additional topics are available. 
  256.  
  257. To expand the Contents if you are using a mouse, click on the plus sign.  If 
  258. you are using the keyboard, use the Up or Down Arrow key to highlight the 
  259. topic, and press the plus (+) key. For example, How to Use the Contents has a 
  260. plus sign beside it.  To see additional topics for that heading, click on the 
  261. plus sign or highlight that topic and press the plus (+) key. 
  262.  
  263. To view a topic, double-click on the topic (or press the Up or Down Arrow key 
  264. to highlight the topic, and then press the Enter key). 
  265.  
  266.  
  267. ΓòÉΓòÉΓòÉ 1.9. How to Obtain Additional Information ΓòÉΓòÉΓòÉ
  268.  
  269. After you select a topic, the information for that topic appears in a window. 
  270. Highlighted words or phrases indicate that additional information is available. 
  271. Certain words and phrases are highlighted in a different color from the 
  272. surrounding text. These are called hypertext terms. 
  273.  
  274. If you are using a mouse, double-click on the highlighted word.  If you are 
  275. using a keyboard, press the Tab key to move to the highlighted word, and then 
  276. press the Enter key.  Additional information then appears in a window. 
  277.  
  278.  
  279. ΓòÉΓòÉΓòÉ 1.10. How to Use Action Bar Choices ΓòÉΓòÉΓòÉ
  280.  
  281. Several choices are available for managing the information presented in this 
  282. document. There are three menus on the action bar:  the Services menu, the 
  283. Options menu, and the Help menu. 
  284.  
  285. The actions that are selectable from the Services menu operate on the active 
  286. window currently displayed on the screen. These actions include the following: 
  287.  
  288.  Placing Bookmarks 
  289.    You can set a placeholder so you can retrieve information of interest to 
  290.    you. 
  291.  
  292.  Searching for Information 
  293.    You can find occurrences of a word or phrase in the current topic, 
  294.    selected topics, or all topics. 
  295.  
  296.  Printing Information 
  297.    You can print one or more topics. You can also print a set of topics by 
  298.    first marking the topics in the Contents list. 
  299.  
  300.  Copying Information to a File 
  301.    You can copy a topic that you are viewing to the System Clipboard or to a 
  302.    file that you can edit. This method is particularly useful for copying 
  303.    syntax definitions and program samples into the application that you are 
  304.    developing. 
  305.  
  306.  Using the actions that are selectable from the Options menu, you can change 
  307.  the way your Contents list is displayed. To expand the Contents and show all 
  308.  levels for all topics, choose Expand all from the Options pull-down. You can 
  309.  also press the Ctrl and * keys together. 
  310.  
  311.  The actions that are selectable from the Help menu allow you to select 
  312.  different types of help information. 
  313.  
  314.  For information about any of the menu choices, highlight the choice in the 
  315.  menu and press F1. 
  316.  
  317.  
  318. ΓòÉΓòÉΓòÉ 1.10.1. Placing Bookmarks ΓòÉΓòÉΓòÉ
  319.  
  320. When you place a bookmark on a topic, it is added to a list of bookmarks you 
  321. have previously set.  You can view the list, and you can remove one or all 
  322. bookmarks from the list.  If you have not set any bookmarks, the list is empty. 
  323.  
  324. To set a bookmark, do the following: 
  325.  
  326.    1. Select a topic from the Contents. 
  327.    2. When that topic appears, select the Bookmark option from the Services 
  328.       menu. 
  329.    3. If you want to change the name used for the bookmark, type the new name 
  330.       in the field. 
  331.    4. Click on the Place radio button (or press the Up or Down Arrow key to 
  332.       select it). 
  333.    5. Click on OK (or select it and press Enter). The bookmark is then added to 
  334.       the bookmark list. 
  335.  
  336.  
  337. ΓòÉΓòÉΓòÉ 1.10.2. Searching for Information ΓòÉΓòÉΓòÉ
  338.  
  339. You can specify a word or phrase to be searched.  You can also limit the search 
  340. to a set of topics by first marking the topics in the Contents list. 
  341.  
  342. To search for a word or phrase in all topics, do the following: 
  343.  
  344.    1. Select the Search option from the Services menu. 
  345.    2. Type the word or words to be searched for. 
  346.    3. Click on All sections (or press the Up or Down Arrow keys to select it). 
  347.    4. Click on Search (or select it and press Enter) to begin the search. 
  348.    5. The list of topics where the word or phrase appears is displayed. 
  349.  
  350.  
  351. ΓòÉΓòÉΓòÉ 1.10.3. Printing Information ΓòÉΓòÉΓòÉ
  352.  
  353. You can print one or more topics, the index, or the table of contents.  Make 
  354. sure that your printer is connected to the serial port, configured correctly, 
  355. and ready for input. To print: 
  356.  
  357.    1. Select Print from the Services pull-down. 
  358.    2. Select what you want to print. Note that the This section and Marked 
  359.       sections choices are only available if you are viewing a topic or if you 
  360.       have marked topics, respectively.  To mark topics in the table of 
  361.       contents, press the Ctrl key and click on the topics, or use the arrow 
  362.       keys. 
  363.    3. Select Print to print what you've chosen on your printer. 
  364.  
  365.  
  366. ΓòÉΓòÉΓòÉ 1.10.4. Copying Information to a File ΓòÉΓòÉΓòÉ
  367.  
  368. You can copy a topic that you are viewing in two ways: 
  369.  
  370.      Copy copies the topic that you are viewing into the System Clipboard.  If 
  371.       you are using a Presentation Manager (PM) editor (for example, the 
  372.       Enhanced Editor) that copies or cuts (or both) to the System Clipboard, 
  373.       and pastes to the System Clipboard, you can easily add the copied 
  374.       information to your program source module. 
  375.  
  376.      Copy to file copies the topic that you are viewing into a temporary file 
  377.       named TEXT.TMP.  You can later edit that file by using any editor. 
  378.       TEXT.TMP is placed in the directory where your viewable document resides. 
  379.  
  380.  To copy a topic, do the following: 
  381.  
  382.    1. Expand the Contents list and select a topic. 
  383.    2. When the topic appears, select Copy to file from the Services menu. 
  384.    3. The system puts the text pertaining to that topic into the temporary file 
  385.       TEXT.TMP. 
  386.  
  387.  
  388. ΓòÉΓòÉΓòÉ 1.11. How to Cut and Paste Examples ΓòÉΓòÉΓòÉ
  389.  
  390. You can copy examples (or information) from this reference/guide/book to 
  391. compile, link, and run them, or to paste them into your own code. 
  392.  
  393. To copy an example or information: 
  394.  
  395.    1. Make the topic you want to copy the active window. 
  396.  
  397.    2. From the Services menu, select Copy to file. The text in that topic is 
  398.       placed in the temporary file TEXT.TMP, in the same directory as this 
  399.       reference. 
  400.  
  401.    3. You can then modify or use TEXT.TMP as you want. 
  402.  
  403.  Note:  Because the system copies the entire contents of the topic to the file, 
  404.  you may need to edit it to remove additional text. Examples in this reference 
  405.  that have a main function are ready to compile, link, and run as they appear, 
  406.  and do not require any editing. 
  407.  
  408.  
  409. ΓòÉΓòÉΓòÉ 1.12. Other Information You Might Find Helpful ΓòÉΓòÉΓòÉ
  410.  
  411. This product provides a number of online guides and references that we hope 
  412. you'll find helpful as you develop applications. This information includes 
  413. User's Guides, References, and How Do I help that gives you specific 
  414. instructions for performing common tasks. You can get to this online 
  415. information from the Information folder inside the main product folder.  You 
  416. can also get to it from the Help menu in any of the components of the product. 
  417.  
  418.  
  419. ΓòÉΓòÉΓòÉ 1.13. Communicating Your Comments to IBM ΓòÉΓòÉΓòÉ
  420.  
  421. If there is something you like, or dislike, about this book, please let us 
  422. know.  You can use one of the methods listed below to send your comments to 
  423. IBM.  Please be sure to include the complete title of the publication that you 
  424. are commenting on. 
  425.  
  426. The comments you send should only pertain to the information in this document 
  427. and its presentation.  To request additional publications or to ask questions 
  428. or make comments about the functions of IBM products or systems, you should 
  429. talk to your IBM representative or you authorized IBM remarketer. 
  430.  
  431. When you send comments to IBM, you grant IBM a nonexclusive right to use or 
  432. distribute your comments in any way it believes appropriate without incurring 
  433. any obligation to you. 
  434.  
  435. You can send your comments to IBM in the following ways: 
  436.  
  437.      By mail to the following address: 
  438.  
  439.             IBM Canada Ltd. Laboratory
  440.             Information Development
  441.             2G/345/1150/TOR
  442.             1150 EGLINTON AVENUE EAST
  443.             NORTH YORK, ONTARIO
  444.             CANADA M3C 1H7
  445.  
  446.      By FAX to the following number: 
  447.  
  448.         -  United States and Canada: (416) 448-6161 
  449.         -  Other countries (+1) 416-448-6161 
  450.  
  451.      By electronic mail to one of the following IDs.  Be sure to include your 
  452.       entire network address if you wish to get a reply. 
  453.  
  454.         -  Internet: torrcf@vnet.ibm.com 
  455.         -  IBMLink: toribm(torrcf) 
  456.         -  IBM/PROFS: torolab4(torrcf) 
  457.         -  IBMMAIL: ibmmail(caibmwt9 
  458.  
  459.  
  460. ΓòÉΓòÉΓòÉ 2. Classes by Name ΓòÉΓòÉΓòÉ
  461.  
  462. I0String
  463. I3StateCheckBox::Style
  464. I3StateCheckBox
  465. IAccelTblHandle
  466. IAccelerator
  467. IAccessError
  468. IAnchorBlockHandle
  469. IAnimatedButton::Style
  470. IAnimatedButton
  471. IApplication
  472. IAssertionFailure
  473. IAutoElemPointer
  474. IAutoPointer
  475. Bag
  476. IBase::Version
  477. IBase
  478. IBaseComboBox::Cursor
  479. IBaseComboBox::Style
  480. IBaseComboBox
  481. IBaseListBox::Cursor
  482. IBaseListBox::Style
  483. IBaseListBox
  484. IBaseSpinButton::Style
  485. IBaseSpinButton
  486. IBitFlag
  487. IBitmapControl::Style
  488. IBitmapControl
  489. IBitmapHandle
  490. IBuffer
  491. IButton::Style
  492. IButton
  493. IButtonNotifyHandler
  494. c_exception
  495. ICLibErrorInfo
  496. ICanvas::Style
  497. ICanvas
  498. ICheckBox::Style
  499. ICheckBox
  500. ICircularSlider::Style
  501. ICircularSlider
  502. ICircularSliderNotifyHandler
  503. IClipboard::Cursor
  504. IClipboard
  505. IClipboardHandler
  506. ICnrAllocator
  507. ICnrBeginEditEvent
  508. ICnrControlList
  509. ICnrDrawBackgroundEvent
  510. ICnrDrawHandler
  511. ICnrDrawItemEvent
  512. ICnrEditEvent
  513. ICnrEditHandler
  514. ICnrEmphasisEvent
  515. ICnrEndEditEvent
  516. ICnrEnterEvent
  517. ICnrEvent
  518. ICnrHandler
  519. ICnrHelpEvent
  520. ICnrMenuHandler
  521. ICnrObjectSet
  522. ICnrQueryDeltaEvent
  523. ICnrReallocStringEvent
  524. ICnrScrollEvent
  525. Collection
  526. ICollectionViewComboBox
  527. ICollectionViewConstants
  528. ICollectionViewListBox
  529. IColor
  530. IComboBox::Style
  531. IComboBox
  532. IComboBoxNotifyHandler
  533. ICommandEvent
  534. ICommandHandler
  535. complex
  536. Constant Iterator
  537. IContainerColumn
  538. IContainerControl::Attribute
  539. IContainerControl::ColumnCursor
  540. IContainerControl::CompareFn
  541. IContainerControl::FilterFn
  542. IContainerControl::Iterator
  543. IContainerControl::ObjectCursor
  544. IContainerControl::Style
  545. IContainerControl::TextCursor
  546. IContainerControl
  547. IContainerControlNotifyHandler
  548. IContainerObject
  549. IContextHandle
  550. IControl::Style
  551. IControl
  552. IControlEvent
  553. ICoordinateSystem
  554. ICritSec
  555. ICurrentApplication
  556. ICurrentThread
  557. Cursor
  558. ICustomButton::Style
  559. ICustomButton
  560. ICustomButtonDrawEvent
  561. ICustomButtonDrawHandler
  562. IDBCSBuffer
  563. IDDE
  564. IDDEAcknowledgeEvent
  565. IDDEAcknowledgeExecuteEvent
  566. IDDEAcknowledgePokeEvent
  567. IDDEActiveServer
  568. IDDEActiveServerSet
  569. IDDEBeginEvent
  570. IDDEClientAcknowledgeEvent
  571. IDDEClientConversation
  572. IDDEClientEndEvent
  573. IDDEClientHotLinkEvent
  574. IDDEClientHotLinkSet
  575. IDDEDataEvent
  576. IDDEEndEvent
  577. IDDEEvent
  578. IDDEExecuteEvent
  579. IDDEPokeEvent
  580. IDDERequestDataEvent
  581. IDDEServerAcknowledgeEvent
  582. IDDEServerHotLinkEvent
  583. IDDESetAcknowledgeInfoEvent
  584. IDDETopicServer
  585. IDM
  586. IDMCnrItem
  587. IDMEFItem
  588. IDMEvent
  589. IDMHandler
  590. IDMImage::Style
  591. IDMImage
  592. IDMItem
  593. IDMItemProvider
  594. IDMItemProviderFor
  595. IDMMLEItem
  596. IDMMenuItem
  597. IDMOperation
  598. IDMRenderer
  599. IDMSourceBeginEvent
  600. IDMSourceDiscardEvent
  601. IDMSourceEndEvent
  602. IDMSourceHandler
  603. IDMSourceOperation
  604. IDMSourcePrepareEvent
  605. IDMSourcePrintEvent
  606. IDMSourceRenderEvent
  607. IDMSourceRenderer
  608. IDMTBarButtonItem
  609. IDMTargetDropEvent
  610. IDMTargetEndEvent
  611. IDMTargetEnterEvent
  612. IDMTargetEvent
  613. IDMTargetHandler
  614. IDMTargetHelpEvent
  615. IDMTargetLeaveEvent
  616. IDMTargetOperation
  617. IDMTargetRenderer
  618. IDMToolBarItem
  619. IDate
  620. Deque
  621. IDeviceColor
  622. IDeviceError
  623. IDisplayHandle
  624. IDrawItemEvent
  625. IDrawingCanvas::Style
  626. IDrawingCanvas
  627. IDynamicLinkLibrary
  628. IEditHandler
  629. IElemPointer
  630. IEntryField::Style
  631. IEntryField
  632. IEntryFieldNotifyHandler
  633. IEnumHandle
  634. Equality Collection
  635. Equality Key Collection
  636. Equality Key Sorted Collection
  637. Equality Sequence
  638. Equality Sorted Collection
  639. IErrorInfo
  640. IEvent
  641. IEventData
  642. IEventParameter1
  643. IEventParameter2
  644. IEventResult
  645. IException::TraceFn
  646. IException
  647. IExceptionLocation
  648. filebuf
  649. IFileDialog::Settings
  650. IFileDialog::Style
  651. IFileDialog
  652. IFileDialogEvent
  653. IFileDialogHandler
  654. IFlyOverHelpHandler
  655. IFlyText
  656. IFocusHandler
  657. IFont::FaceNameCursor
  658. IFont::PointSizeCursor
  659. IFont
  660. IFontDialog::Settings
  661. IFontDialog::Style
  662. IFontDialog
  663. IFontDialogHandler
  664. IFrameEvent
  665. IFrameExtension
  666. IFrameExtensions
  667. IFrameFormatEvent
  668. IFrameHandler
  669. IFrameWindow::Style
  670. IFrameWindow
  671. IFrameWindowNotifyHandler
  672. fstream
  673. fstreambase
  674. IG3PointArc
  675. IGArc
  676. IGBitmap
  677. IGChord
  678. IGEllipse
  679. IGLine
  680. IGList::Cursor
  681. IGList
  682. IGPie
  683. IGPolygon
  684. IGPolyline
  685. IGRectangle
  686. IGRegion
  687. IGString
  688. IGUIColor
  689. IGUIErrorInfo
  690. IGraphic
  691. IGraphicBundle
  692. IGraphicContext
  693. IGraphicPushButton::Style
  694. IGraphicPushButton
  695. IGroupBox::Style
  696. IGroupBox
  697. IHandle
  698. IHandler
  699. Heap
  700. IHelpErrorEvent
  701. IHelpHandler
  702. IHelpHyperlinkEvent
  703. IHelpMenuBarEvent
  704. IHelpNotifyEvent
  705. IHelpSubitemNotFoundEvent
  706. IHelpTutorialEvent
  707. IHelpWindow::Settings
  708. IHelpWindow
  709. IHighEventParameter
  710. IIconControl::Style
  711. IIconControl
  712. ifstream
  713. IInfoArea
  714. IInvalidParameter
  715. IInvalidRequest
  716. ios
  717. iostream
  718. iostream_withassign
  719. istream
  720. istream_withassign
  721. istrstream
  722. Iterator
  723. Key Bag
  724. Key Collection
  725. Key Set
  726. Key Sorted Bag
  727. Key Sorted Collection
  728. Key Sorted Set
  729. IKeyboardEvent
  730. IKeyboardHandler
  731. IListBox::Style
  732. IListBox
  733. IListBoxDrawItemEvent
  734. IListBoxDrawItemHandler
  735. IListBoxNotifyHandler
  736. IListBoxSizeItemEvent
  737. ILowEventParameter
  738. IMM24FramesPerSecondTime
  739. IMM25FramesPerSecondTime
  740. IMM30FramesPerSecondTime
  741. IMMAmpMixer
  742. IMMAudioBuffer
  743. IMMAudioCD
  744. IMMAudioCDContents::Cursor
  745. IMMAudioCDContents
  746. IMMCDXA
  747. IMMConfigurableAudio
  748. IMMCuePointEvent
  749. IMMDevice
  750. IMMDeviceEvent
  751. IMMDeviceHandler
  752. IMMDigitalVideo
  753. IMMErrorInfo
  754. IMMFileMedia
  755. IMMHourMinSecFrameTime
  756. IMMHourMinSecTime
  757. IMMMasterAudio
  758. IMMMillisecondTime
  759. IMMMinSecFrameTime
  760. IMMNotifyEvent
  761. IMMPassDeviceEvent
  762. IMMPlayableDevice
  763. IMMPlayerPanel
  764. IMMPlayerPanelHandler
  765. IMMPositionChangeEvent
  766. IMMRecordable
  767. IMMRemovableMedia
  768. IMMRemovableMediaHandler
  769. IMMSequencer
  770. IMMSpeed
  771. IMMTime
  772. IMMTrackMinSecFrameTime
  773. IMMWaveAudio
  774. Manipulators
  775. Map
  776. IMenu::Cursor
  777. IMenu::Style
  778. IMenu
  779. IMenuBar::Style
  780. IMenuBar
  781. IMenuDrawItemEvent
  782. IMenuDrawItemHandler::DrawFlag
  783. IMenuDrawItemHandler
  784. IMenuEvent
  785. IMenuHandle
  786. IMenuHandler
  787. IMenuItem::Attribute
  788. IMenuItem::Style
  789. IMenuItem
  790. IMenuNotifyHandler
  791. IMessageBox::Style
  792. IMessageBox
  793. IMessageQueueHandle
  794. IMessageText
  795. IMngElemPointer
  796. IMngPointer
  797. IModuleHandle
  798. IMouseClickEvent
  799. IMouseEvent
  800. IMouseHandler
  801. IMousePointerEvent
  802. IMousePointerHandler
  803. IMultiCellCanvas::Style
  804. IMultiCellCanvas
  805. IMultiLineEdit::Style
  806. IMultiLineEdit
  807. IMultiLineEditNotifyHandler
  808. INotebook::Cursor
  809. INotebook::PageSettings::Attribute
  810. INotebook::PageSettings
  811. INotebook::Style
  812. INotebook
  813. INotebookDrawItemEvent
  814. INotebookNotifyHandler
  815. INotificationEvent
  816. INotifier
  817. INumericSpinButton::Style
  818. INumericSpinButton
  819. INumericSpinButtonNotifyHandler
  820. IObjectWindow
  821. IObserver
  822. IObserverList::Cursor
  823. IObserverList
  824. ofstream
  825. Ordered Collection
  826. ostream
  827. ostream_withassign
  828. ostrstream
  829. IOutOfMemory
  830. IOutOfSystemResource
  831. IOutOfWindowResource
  832. IOutlineBox::Style
  833. IOutlineBox
  834. IPageEvent
  835. IPageHandle
  836. IPageHandler
  837. IPageHelpEvent
  838. IPageRemoveEvent
  839. IPageSelectEvent
  840. IPaintEvent
  841. IPaintHandler
  842. IPair
  843. IPoint
  844. IPointArray
  845. Pointer Classes
  846. IPointerHandle
  847. IPopUpMenu
  848. IPresSpaceHandle
  849. Priority Queue
  850. IPrivateResource
  851. IProcedureAddress
  852. IProcessId
  853. IProfile::Cursor
  854. IProfile
  855. IProfileHandle
  856. IProgressIndicator::Style
  857. IProgressIndicator
  858. IProgressIndicatorNotifyHandler
  859. IPushButton::Style
  860. IPushButton
  861. Queue
  862. IRadioButton::Style
  863. IRadioButton
  864. IRange
  865. IRectangle
  866. IRefCounted
  867. IReference
  868. IRegionHandle
  869. Relation
  870. IResizeEvent
  871. IResizeHandler
  872. IResource
  873. IResourceExhausted
  874. IResourceId
  875. IResourceLibrary
  876. IResourceLock
  877. ISWP
  878. ISWPArray
  879. IScrollBar::Style
  880. IScrollBar
  881. IScrollBarNotifyHandler
  882. IScrollEvent
  883. IScrollHandler
  884. ISelectHandler
  885. ISemaphoreHandle
  886. Sequence
  887. Sequential Collection
  888. Set
  889. ISetCanvas::Style
  890. ISetCanvas
  891. ISettingButton
  892. ISettingButtonNotifyHandler
  893. ISharedResource
  894. IShowListHandler
  895. ISize
  896. ISlider::Style
  897. ISlider
  898. ISliderArmHandler
  899. ISliderDrawHandler
  900. Sorted Bag
  901. Sorted Collection
  902. Sorted Map
  903. Sorted Relation
  904. Sorted Set
  905. ISpinHandler
  906. ISplitCanvas::Style
  907. ISplitCanvas
  908. Stack
  909. IStandardNotifier
  910. IStaticText::Style
  911. IStaticText
  912. stdiobuf
  913. stdiostream
  914. streambuf
  915. IString
  916. IStringEnum
  917. IStringGenerator
  918. IStringGeneratorFn
  919. IStringGeneratorMemberFn
  920. IStringGeneratorRefMemberFn
  921. IStringHandle
  922. IStringParser::SkipWords
  923. IStringParser
  924. IStringTest
  925. IStringTestMemberFn
  926. strstream
  927. strstreambase
  928. strstreambuf
  929. ISubmenu::Cursor
  930. ISubmenu
  931. ISystemBitmapHandle
  932. ISystemErrorInfo
  933. ISystemMenu
  934. ISystemPointerHandle
  935. ITextControl
  936. ITextControlNotifyHandler
  937. ITextSpinButton::Cursor
  938. ITextSpinButton::Style
  939. ITextSpinButton
  940. ITextSpinButtonNotifyHandler
  941. IThread::Cursor
  942. IThread
  943. IThreadFn
  944. IThreadId
  945. IThreadMemberFn
  946. ITime
  947. ITimer::Cursor
  948. ITimer
  949. ITimerFn
  950. ITimerMemberFn0
  951. ITimerMemberFn
  952. ITitle
  953. ITitleNotifyHandler
  954. IToolBar::FrameCursor
  955. IToolBar::Style
  956. IToolBar::WindowCursor
  957. IToolBar
  958. IToolBarButton::Style
  959. IToolBarButton
  960. IToolBarContainer::Style
  961. IToolBarContainer
  962. IToolBarFrameWindow
  963. ITrace
  964. ITransformMatrix
  965. Tree
  966. Tree Cursor
  967. IVBase
  968. IViewPort::Style
  969. IViewPort
  970. IWindow::BidiSettings
  971. IWindow::ChildCursor
  972. IWindow::ExceptionFn
  973. IWindow::Style
  974. IWindow
  975. IWindowHandle
  976. IWindowNotifyHandler
  977. IXLibErrorInfo
  978.  
  979.  
  980. ΓòÉΓòÉΓòÉ 3. Complex Mathematics Classes ΓòÉΓòÉΓòÉ
  981.  
  982. The Complex Mathematics Library contains two classes: 
  983.  
  984.  complex Class  The class you can use to manipulate complex numbers. 
  985.  
  986.  c_exception Class The class that provides runtime error-handling facilities 
  987.                 for the functions and operations in the complex class. 
  988.  
  989.  
  990. ΓòÉΓòÉΓòÉ 3.1. complex Class ΓòÉΓòÉΓòÉ
  991.  
  992. Description 
  993.  
  994. Derivation 
  995.  
  996. Header File 
  997.  
  998. Constructors 
  999.  
  1000. Members 
  1001.  
  1002. To close all the panels in a chapter, double-click on this panel's system menu. 
  1003.  
  1004.  
  1005. ΓòÉΓòÉΓòÉ 3.1.1. Class Description - complex ΓòÉΓòÉΓòÉ
  1006.  
  1007. This chapter describes the member functions of the complex class, the class 
  1008. that provides you with the facilities to manipulate complex numbers. 
  1009.  
  1010.  
  1011. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  1012.  
  1013. complex does not derive from any class. 
  1014.  
  1015.  
  1016. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  1017.  
  1018. complex is declared in complex.h 
  1019.  
  1020.  
  1021. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  1022.  
  1023. The following members are provided for complex: 
  1024.  
  1025.      Constructors for complex 
  1026.      Addition 
  1027.      Mathematical Assignment Operators 
  1028.      Inequality 
  1029.      Multiplication 
  1030.      Negation 
  1031.      Subtraction 
  1032.      Division 
  1033.      Input Operator 
  1034.      Output Operator 
  1035.      Equality 
  1036.      abs 
  1037.      arg 
  1038.      conj 
  1039.      cos 
  1040.      cosh 
  1041.      exp 
  1042.      imag 
  1043.      log 
  1044.      norm 
  1045.      polar 
  1046.      pow 
  1047.      real 
  1048.      sin 
  1049.      sinh 
  1050.      sqrt 
  1051.  
  1052.  complex also defines a set of mathematical constants. 
  1053.  
  1054.  
  1055. ΓòÉΓòÉΓòÉ 3.1.2. Constants Defined in complex.h ΓòÉΓòÉΓòÉ
  1056.  
  1057. The following table lists the mathematical constants that the Complex 
  1058. Mathematics Library defines (if they have not been previously defined): 
  1059.  
  1060. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  1061. Γöé Table 1. Constants Defined in complex.h                         Γöé
  1062. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1063. Γöé CONSTANT NAME            Γöé DESCRIPTION                          Γöé
  1064. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1065. Γöé M_E                      Γöé The constant e                       Γöé
  1066. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1067. Γöé M_LOG2E                  Γöé The logarithm of e to the base of 2  Γöé
  1068. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1069. Γöé M_LOG10E                 Γöé The logarithm of e to the base of 10 Γöé
  1070. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1071. Γöé M_LN2                    Γöé The natural logarithm of 2           Γöé
  1072. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1073. Γöé M_LN10                   Γöé The natural logarithm of 10          Γöé
  1074. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1075. Γöé M_PI                     Γöé pi                                   Γöé
  1076. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1077. Γöé M_PI_2                   Γöé pi  / 2                              Γöé
  1078. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1079. Γöé M_PI_4                   Γöé pi  / 4                              Γöé
  1080. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1081. Γöé M_1_PI                   Γöé 1 / pi                               Γöé
  1082. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1083. Γöé M_2_PI                   Γöé 2 / pi                               Γöé
  1084. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1085. Γöé M_2_SQRTPI               Γöé 2 divided by the square root of pi   Γöé
  1086. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1087. Γöé M_SQRT2                  Γöé The square root of 2                 Γöé
  1088. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  1089. Γöé M_SQRT1_2                Γöé The square root of 1 / 2             Γöé
  1090. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  1091.  
  1092.  
  1093. ΓòÉΓòÉΓòÉ 3.1.3. Constructors for complex ΓòÉΓòÉΓòÉ
  1094.  
  1095. See also Initializing complex Arrays (next panel). 
  1096.  
  1097. There are two versions of the complex constructor: 
  1098.  
  1099. complex();
  1100. complex(double r, double i=0.0);
  1101.  
  1102. If you declare a complex object without specifying any values for the real or 
  1103. imaginary part of the complex value, the constructor that takes no arguments is 
  1104. used and the complex value is initialized to (0, 0). For example, the following 
  1105. declaration gives the object comp the value (0, 0): 
  1106.  
  1107.    complex comp;
  1108.  
  1109. If you give either one or two values in your declaration, the constructor that 
  1110. takes two arguments is used. If you only give one value, the real part of the 
  1111. complex object is initialized to that value, and the imaginary part is 
  1112. initialized to 0. 
  1113.  
  1114. For example, the following declaration gives the object comp2 the value 
  1115. (3.14, 0): 
  1116.  
  1117.    complex comp2(3.14);
  1118.  
  1119. If you give two values in the declaration, the real part of the complex object 
  1120. is initialized to the first value and the imaginary part is initialized to the 
  1121. second value. For example, the following declaration gives the object comp3 the 
  1122. value (3.14, 6.44): 
  1123.  
  1124.    complex comp3(3.14, 6.44);
  1125.  
  1126. There is no explicit complex destructor. 
  1127.  
  1128.  
  1129. ΓòÉΓòÉΓòÉ 3.1.3.1. Initializing complex Arrays ΓòÉΓòÉΓòÉ
  1130.  
  1131. You can use the complex constructor to initialize arrays of complex numbers. 
  1132. If the list of initial values is made up of complex values, each array element 
  1133. is initialized to the corresponding value in the list of initial values. If the 
  1134. list of initial values is not made up of complex values, the real parts of the 
  1135. array elements are initialized to these initial values and the imaginary parts 
  1136. of the array elements are initialized to 0.  In the following example, the 
  1137. elements of array b are initialized to the values in the initial value list, 
  1138. but only the real parts of elements of array a are initialized to the values in 
  1139. the initial value list. 
  1140.  
  1141.    #include <complex.h>
  1142.  
  1143.    void main() {
  1144.      complex a[3] = {1.0, 2.0, 3.0};
  1145.      complex b[3] = {complex(1.0, 1.0), complex(2.0, 2.0),
  1146.                     complex(3.0, 3.0)};
  1147.      cout << "Here is the first element of a: " << a[0] << endl;
  1148.      cout << "Here is the first element of b: " << b[0] << endl;
  1149.    }
  1150.  
  1151. This example produces the following output: 
  1152.  
  1153.    Here is the first element of a: ( 1, 0)
  1154.    Here is the first element of b: ( 1, 1)
  1155.  
  1156.  
  1157. ΓòÉΓòÉΓòÉ 3.1.4. Mathematical Operators for complex ΓòÉΓòÉΓòÉ
  1158.  
  1159. The complex operators described in this section have the same precedence as the 
  1160. corresponding real operators. 
  1161.  
  1162. The following operators are described: 
  1163.  
  1164.      Addition operator 
  1165.      Subtraction operator 
  1166.      Negation operator 
  1167.      Multiplication operator 
  1168.      Division operator 
  1169.      Equality operator 
  1170.      Inequality operator 
  1171.      Mathematical assignment operators 
  1172.  
  1173.  
  1174. ΓòÉΓòÉΓòÉ 3.1.4.1. Addition ΓòÉΓòÉΓòÉ
  1175.  
  1176. friend complex operator+(complex x, complex y);
  1177.  
  1178. The addition operator returns the sum of x and y. 
  1179.  
  1180.  
  1181. ΓòÉΓòÉΓòÉ 3.1.4.2. Subtraction ΓòÉΓòÉΓòÉ
  1182.  
  1183. friend complex operator-(complex x, complex y);
  1184.  
  1185. The subtraction operator returns the difference between x and y. 
  1186.  
  1187.  
  1188. ΓòÉΓòÉΓòÉ 3.1.4.3. Negation ΓòÉΓòÉΓòÉ
  1189.  
  1190. friend complex operator-(complex x);
  1191.  
  1192. The negation operator returns (- a, - b) when its argument is (a, b). 
  1193.  
  1194.  
  1195. ΓòÉΓòÉΓòÉ 3.1.4.4. Multiplication ΓòÉΓòÉΓòÉ
  1196.  
  1197. friend complex operator*(complex x, complex y);
  1198.  
  1199. The multiplication operator returns the product of x and y. 
  1200.  
  1201.  
  1202. ΓòÉΓòÉΓòÉ 3.1.4.5. Division ΓòÉΓòÉΓòÉ
  1203.  
  1204. friend complex operator/(complex x, complex y);
  1205.  
  1206. The division operator returns the quotient of x divided by y. 
  1207.  
  1208.  
  1209. ΓòÉΓòÉΓòÉ 3.1.4.6. Equality ΓòÉΓòÉΓòÉ
  1210.  
  1211. friend int operator==(complex x, complex y);
  1212.  
  1213. The  equality operator "==" returns a nonzero value if x equals y.  This 
  1214. operator tests for equality by testing that the two real components are equal 
  1215. and that the two imaginary components are equal. 
  1216.  
  1217. Because both components are double values, the equality operator tests for an 
  1218. exact match between the two sets of values.  If you want an equality operator 
  1219. that can test for an absolute difference within a certain tolerance between the 
  1220. two pairs of corresponding components, you can use a function such as the 
  1221. isequal function. 
  1222.  
  1223.  
  1224. ΓòÉΓòÉΓòÉ 3.1.4.7. Inequality ΓòÉΓòÉΓòÉ
  1225.  
  1226. friend int operator!=(complex x, complex y);
  1227.  
  1228. The inequality operator "! =" returns a nonzero value if x does not equal y. 
  1229. This operator tests for inequality by testing that the two real components are 
  1230. not equal and that the two imaginary components are not equal. 
  1231.  
  1232. Because both components are double values, the inequality operator returns 
  1233. false only when both the real and imaginary components of the two values are 
  1234. identical. If you want an inequality operator that can test for an absolute 
  1235. difference within a certain tolerance between the two pairs of corresponding 
  1236. components, you can use a function such as the is_not_equal function. 
  1237.  
  1238.  
  1239. ΓòÉΓòÉΓòÉ 3.1.4.8. Mathematical Assignment Operators ΓòÉΓòÉΓòÉ
  1240.  
  1241. void operator+=(complex x);
  1242. void operator-=(complex x);
  1243. void operator*=(complex x);
  1244. void operator/=(complex x);
  1245.  
  1246. The following list describes the functions of the mathematical assignment 
  1247. operators: 
  1248.  
  1249.      x += y assigns the value of x + y to x. 
  1250.      x -= y assigns the value of x - y to x. 
  1251.      x *= y assigns the value of x * y to x. 
  1252.      x /= y assigns the value of x / y to x. 
  1253.  
  1254.  Note:  The assignment operators do not produce a value that can be used in an 
  1255.  expression. The following code, for example, produces a compile-time error: 
  1256.  
  1257.      complex x, y, z;     // valid declaration
  1258.      x = (y += z);        // invalid assignment causes a
  1259.                           // compile-time error
  1260.      y += z;              // correct method involves splitting
  1261.      x = y;               // expression into separate statements
  1262.  
  1263.  
  1264. ΓòÉΓòÉΓòÉ 3.1.5. Input and Output Operators for complex ΓòÉΓòÉΓòÉ
  1265.  
  1266. The following topics are described: 
  1267.  
  1268.      The input operator 
  1269.      The output operator. 
  1270.  
  1271.  You can also view the Open Class Library User's Guide section on complex input 
  1272.  and output operators for an example of using them. 
  1273.  
  1274.  
  1275. ΓòÉΓòÉΓòÉ 3.1.5.1. Input Operator ΓòÉΓòÉΓòÉ
  1276.  
  1277. istream& operator>>(istream& is, complex& c);
  1278.  
  1279. The input (or extraction) operator >> takes complex value c from the stream is 
  1280. in the form (a,b).  The parentheses and comma are mandatory delimiters for 
  1281. input when the imaginary part of the complex number being read is nonzero. 
  1282. Otherwise, they are optional. In both cases, white space is optional. 
  1283.  
  1284.  
  1285. ΓòÉΓòÉΓòÉ 3.1.5.2. Output Operator ΓòÉΓòÉΓòÉ
  1286.  
  1287. ostream& operator<<(ostream& os, complex c);
  1288.  
  1289. The output (or insertion) operator <<  writes complex value c to the stream os 
  1290. in the form (a,b). 
  1291.  
  1292.  
  1293. ΓòÉΓòÉΓòÉ 3.1.6. Mathematical Functions for complex ΓòÉΓòÉΓòÉ
  1294.  
  1295. The following mathematical functions are described: 
  1296.  
  1297.      exp - Exponent 
  1298.      log - Logarithm 
  1299.      pow - Power 
  1300.      sqrt - Square Root 
  1301.  
  1302.  You can also the Open Class Library User's Guide information on the complex 
  1303.  mathematical functions for an example of using them. 
  1304.  
  1305.  
  1306. ΓòÉΓòÉΓòÉ 3.1.6.1. exp ΓòÉΓòÉΓòÉ
  1307.  
  1308. friend complex exp(complex x);
  1309.  
  1310. exp() returns the complex value equal to e to the power of x where x is the 
  1311. argument. Results of the Default Error-Handling Procedures shows the values 
  1312. returned by the default error-handling procedure for exp(). 
  1313.  
  1314.  
  1315. ΓòÉΓòÉΓòÉ 3.1.6.2. log ΓòÉΓòÉΓòÉ
  1316.  
  1317. friend complex log(complex x);
  1318.  
  1319. log() returns the natural logarithm of the argument x. Results of the Default 
  1320. Error-Handling Procedures shows the values returned by the default 
  1321. error-handling procedure for log(). 
  1322.  
  1323.  
  1324. ΓòÉΓòÉΓòÉ 3.1.6.3. pow ΓòÉΓòÉΓòÉ
  1325.  
  1326. friend complex pow(double d, complex z);
  1327. friend complex pow(complex c, int i);
  1328. friend complex pow(complex c, double d);
  1329. friend complex pow(complex c, complex z);
  1330.  
  1331. Note:  Exponents in the following text are shown in square brackets. 
  1332.  
  1333. pow() returns the complex value x[y], where x is the first argument and y is 
  1334. the second argument.  pow() is overloaded four times. If d is a double value, i 
  1335. is an integer value, and c and z are complex values, then pow() can produce any 
  1336. of the following results: 
  1337.  
  1338.      d[z] 
  1339.      c[i] 
  1340.      c[d] 
  1341.      c[z] 
  1342.  
  1343.  
  1344. ΓòÉΓòÉΓòÉ 3.1.6.4. sqrt ΓòÉΓòÉΓòÉ
  1345.  
  1346. friend complex sqrt(complex x);
  1347.  
  1348. sqrt() returns the square root of its argument. If c and d are real values, 
  1349. then every complex number (a,b), where: 
  1350.  
  1351.      a = c  - d 
  1352.      b = 2cd 
  1353.  
  1354.  has two square roots: 
  1355.  
  1356.      (c,d) 
  1357.      (-c,-d ) 
  1358.  
  1359.  sqrt() returns the square root that has a positive real part, that is, the 
  1360.  square root that is contained in the first or fourth quadrants of the complex 
  1361.  plane. 
  1362.  
  1363.  
  1364. ΓòÉΓòÉΓòÉ 3.1.7. Trigonometric Functions for complex ΓòÉΓòÉΓòÉ
  1365.  
  1366. The following trigonometric functions are described: 
  1367.  
  1368.      cos - Cosine 
  1369.      cosh - Hyperbolic cosine 
  1370.      sin - Sine 
  1371.      sinh - Hyperbolic sine 
  1372.  
  1373.  You can also view the Open Class Library User's Guide section on complex 
  1374.  trigonometric functions for an example of using them. 
  1375.  
  1376.  
  1377. ΓòÉΓòÉΓòÉ 3.1.7.1. cos ΓòÉΓòÉΓòÉ
  1378.  
  1379. friend complex cos(complex x);
  1380.  
  1381. cos() returns the cosine of x. 
  1382.  
  1383.  
  1384. ΓòÉΓòÉΓòÉ 3.1.7.2. cosh ΓòÉΓòÉΓòÉ
  1385.  
  1386. friend complex cosh(complex x);
  1387.  
  1388. cosh() returns the hyperbolic cosine of x. Results of the Default 
  1389. Error-Handling Procedures shows the values returned by the default 
  1390. error-handling procedure for cosh(). 
  1391.  
  1392.  
  1393. ΓòÉΓòÉΓòÉ 3.1.7.3. sin ΓòÉΓòÉΓòÉ
  1394.  
  1395. friend complex sin(complex x);
  1396.  
  1397. sin() returns the sine of x. 
  1398.  
  1399.  
  1400. ΓòÉΓòÉΓòÉ 3.1.7.4. sinh ΓòÉΓòÉΓòÉ
  1401.  
  1402. friend complex sinh(complex x);
  1403.  
  1404. sinh() returns the hyperbolic sine of x. Results of the Default Error-Handling 
  1405. Procedures shows the values returned by the default error-handling procedure 
  1406. for sinh(). 
  1407.  
  1408.  
  1409. ΓòÉΓòÉΓòÉ 3.1.8. Magnitude Functions for complex ΓòÉΓòÉΓòÉ
  1410.  
  1411. The following magnitude functions are described: 
  1412.  
  1413.      abs - Absolute value 
  1414.      norm - Square magnitude 
  1415.  
  1416.  
  1417. ΓòÉΓòÉΓòÉ 3.1.8.1. abs ΓòÉΓòÉΓòÉ
  1418.  
  1419. friend double abs(complex x);
  1420.  
  1421. abs() returns the absolute value or magnitude of its argument. The absolute 
  1422. value of a complex value (a,b) is the positive square root of a +b . 
  1423.  
  1424.  
  1425. ΓòÉΓòÉΓòÉ 3.1.8.2. norm ΓòÉΓòÉΓòÉ
  1426.  
  1427. friend double norm(complex x);
  1428.  
  1429. norm() returns the square of the magnitude of its argument. If the argument x 
  1430. is equal to the complex number (a,b), norm() returns the value a +b . norm() is 
  1431. faster than  abs(), but it is more likely to cause overflow errors. 
  1432.  
  1433.  
  1434. ΓòÉΓòÉΓòÉ 3.1.9. Conversion Functions for complex ΓòÉΓòÉΓòÉ
  1435.  
  1436. You can use the conversion functions in the Complex Mathematics Library to 
  1437. convert between the polar and standard complex representations of a value and 
  1438. to extract the real and imaginary parts of a complex value. 
  1439.  
  1440. The following conversion functions are described: 
  1441.  
  1442.      arg - Angle in radians 
  1443.      conj - Conjugation 
  1444.      polar - Polar to complex 
  1445.      real - Extract real part 
  1446.      imag - Extract imaginary part 
  1447.  
  1448.  You can also view the Open Class Library User's Guide section on complex 
  1449.  conversion functions for an example of using them. 
  1450.  
  1451.  
  1452. ΓòÉΓòÉΓòÉ 3.1.9.1. arg ΓòÉΓòÉΓòÉ
  1453.  
  1454. friend double arg(complex x);
  1455.  
  1456. arg() returns the angle (in radians) of the polar representation of its 
  1457. argument. If the argument x is equal to the complex number (a,b), the angle 
  1458. returned is the angle in radians on the complex plane between the real axis and 
  1459. the vector (a,b). The return value has a range of -pi  to pi . Click here for 
  1460. an illustration of the polar representation of complex numbers. 
  1461.  
  1462.  
  1463. ΓòÉΓòÉΓòÉ 3.1.9.2. conj ΓòÉΓòÉΓòÉ
  1464.  
  1465. friend complex conj(complex x);
  1466.  
  1467. conj() returns the complex value equal to (a,-b) if the input argument x is 
  1468. equal to (a,b). 
  1469.  
  1470.  
  1471. ΓòÉΓòÉΓòÉ 3.1.9.3. polar ΓòÉΓòÉΓòÉ
  1472.  
  1473. friend complex polar(double a, double b= 0);
  1474.  
  1475. polar() returns the standard complex representation of the complex number that 
  1476. has a polar representation (a,b). 
  1477.  
  1478.  
  1479. ΓòÉΓòÉΓòÉ 3.1.9.4. real ΓòÉΓòÉΓòÉ
  1480.  
  1481. friend double real(const complex& x);
  1482.  
  1483. real() extracts the real part of the complex number x. 
  1484.  
  1485.  
  1486. ΓòÉΓòÉΓòÉ 3.1.9.5. imag ΓòÉΓòÉΓòÉ
  1487.  
  1488. friend double imag(const complex& x);
  1489.  
  1490. imag() extracts the imaginary part of the complex number x. 
  1491.  
  1492.  
  1493. ΓòÉΓòÉΓòÉ 3.2. c_exception Class ΓòÉΓòÉΓòÉ
  1494.  
  1495. Description 
  1496.  
  1497. Derivation 
  1498.  
  1499. Header File 
  1500.  
  1501. Constructors 
  1502.  
  1503. Members 
  1504.  
  1505. To close all the panels in a chapter, double-click on this panel's system menu. 
  1506.  
  1507.  
  1508. ΓòÉΓòÉΓòÉ 3.2.1. Class Description - c_exception ΓòÉΓòÉΓòÉ
  1509.  
  1510. Use the c_exception class to handle errors that are created by the functions 
  1511. and operations in the complex class. 
  1512.  
  1513. In addition to topics shown in the lefthand panel, the following topics are 
  1514. discussed in this chapter: 
  1515.  
  1516.      Errors handled by the Complex Mathematics Library 
  1517.      Errors handled outside the library 
  1518.  
  1519.  Note:  The c_exception class is not related to the C++ exception handling 
  1520.  mechanism that uses the try, catch, and throw statements. 
  1521.  
  1522.  
  1523. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  1524.  
  1525. c_exception is not derived from any other class. 
  1526.  
  1527.  
  1528. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  1529.  
  1530. c_exception is declared in complex.h. 
  1531.  
  1532.  
  1533. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  1534.  
  1535. The following members are provided for c_exception: 
  1536.  
  1537.      Constructor for c_exception 
  1538.      arg1, arg2 
  1539.      name 
  1540.      retval 
  1541.      type 
  1542.  
  1543.  
  1544. ΓòÉΓòÉΓòÉ 3.2.2. Constructor for c_exception ΓòÉΓòÉΓòÉ
  1545.  
  1546. c_exception(char *n, const complex& a1,
  1547.                      const complex& a2 = complex_zero);
  1548.  
  1549. The c_exception constructor creates a c_exception object with name member equal 
  1550. to n, arg1 member equal to a1, and arg2 member equal to a2. 
  1551.  
  1552.  
  1553. ΓòÉΓòÉΓòÉ 3.2.3. Data Members of c_exception ΓòÉΓòÉΓòÉ
  1554.  
  1555. The following data members are described: 
  1556.  
  1557.      arg1, arg2 - Arguments of the function that caused the error 
  1558.      name - Name of the function that caused the error 
  1559.      retval - Value returned by the default definition of the error handling 
  1560.       function 
  1561.      type - Type of error that has occurred 
  1562.  
  1563.  
  1564. ΓòÉΓòÉΓòÉ 3.2.3.1. arg1, arg2 ΓòÉΓòÉΓòÉ
  1565.  
  1566. complex arg1;
  1567. complex arg2;
  1568.  
  1569. arg1 and arg2 are the arguments with which the function that caused the error 
  1570. was called. 
  1571.  
  1572.  
  1573. ΓòÉΓòÉΓòÉ 3.2.3.2. name ΓòÉΓòÉΓòÉ
  1574.  
  1575. char *name;
  1576.  
  1577. name is a string that contains the name of the function where the error 
  1578. occurred. 
  1579.  
  1580.  
  1581. ΓòÉΓòÉΓòÉ 3.2.3.3. retval ΓòÉΓòÉΓòÉ
  1582.  
  1583. complex retval;
  1584.  
  1585. retval is the value that the default definition if the error handling function 
  1586. complex_error() returns. You can make your own definition of complex_error() 
  1587. return a different value. 
  1588.  
  1589.  
  1590. ΓòÉΓòÉΓòÉ 3.2.3.4. type ΓòÉΓòÉΓòÉ
  1591.  
  1592. int type;
  1593.  
  1594. type describes the type of error that has occurred. It can take the following 
  1595. values that are defined in the complex.h header file: 
  1596.  
  1597.      SING argument singularity 
  1598.      OVERFLOW overflow range error 
  1599.      UNDERFLOW underflow range error 
  1600.  
  1601.  
  1602. ΓòÉΓòÉΓòÉ 3.2.4. Errors Handled by the Complex Mathematics Library ΓòÉΓòÉΓòÉ
  1603.  
  1604. The following topics are discussed: 
  1605.  
  1606.      complex_error 
  1607.      Default Error-Handling Procedures 
  1608.  
  1609.  
  1610. ΓòÉΓòÉΓòÉ 3.2.4.1. complex_error ΓòÉΓòÉΓòÉ
  1611.  
  1612. friend int complex_error(c_exception& ce);
  1613.  
  1614. complex_error() is invoked by member functions of the Complex Mathematics 
  1615. Library when errors are detected. The argument ce refers to the c_exception 
  1616. object that contains information about the error. You can define your own 
  1617. procedures for handling errors by defining a function called complex_error() 
  1618. with return type int and a single parameter of type c_exception&. 
  1619.  
  1620. If you define your own complex_error() function and this function returns a 
  1621. nonzero value, no error message will be generated and the external variable 
  1622. errno will not be set. If this function returns zero, errno is given the value 
  1623. of one of the following constants: 
  1624.  
  1625.      ERANGE if the result is too large or too small 
  1626.      EDOM if there is a domain error within a mathematical function 
  1627.  
  1628.  These constants are defined in errno.h. 
  1629.  
  1630.  If you define your own version of complex_error(), when you compile your 
  1631.  program you must use the /NOE option. 
  1632.  
  1633.  For example, if the source file containing your definition of complex_error() 
  1634.  is source1.cpp, then you would invoke the compiler like this: 
  1635.  
  1636.      icc source1.cpp /B"/NOE"
  1637.  
  1638.  
  1639. ΓòÉΓòÉΓòÉ 3.2.4.2. Default Error-Handling Procedures ΓòÉΓòÉΓòÉ
  1640.  
  1641. If you do not define your own complex_error(), the default error-handling 
  1642. procedures will be invoked when an error occurs. The results for a given input 
  1643. complex value (a, b) depend on the kind of error and the sign of the cosine and 
  1644. sine of b. The following table shows the return value of the default 
  1645. error-handling procedure and the value given to errno for each function with 
  1646. input equal to the complex value (a, b). 
  1647.  
  1648. Note:  The following symbols appear in this table: 
  1649.  
  1650.    1. NA - not applicable. The result of the error depends on the sign of the 
  1651.       cosine and sine of b (the imaginary part of the argument) unless "NA" 
  1652.       appears in the Cosine b or Sine b columns. 
  1653.  
  1654.    2. HUGE - the maximum double value. This value is defined in math.h. 
  1655.  
  1656.   Function Error        Cosine b  Sine b   Return Value   errno Value
  1657.  
  1658.   cosh     a too large  nonneg.   nonneg.  (+HUGE,+HUGE)  ERANGE
  1659.   cosh     a too large  nonneg.   nenneg.  (+HUGE,-HUGE)  ERANGE
  1660.   cosh     a too small  nonneg.   nonneg.  (+HUGE,-HUGE)  ERANGE
  1661.   cosh     a too small  nonneg.   nenneg.  (+HUGE,+HUGE)  ERANGE
  1662.   cosh     a too small  negative  nonneg.  (-HUGE,-HUGE)  ERANGE
  1663.   cosh     a too small  negative  nenneg.  (-HUGE,+HUGE)  ERANGE
  1664.   cosh     b too large  negative  nonneg.  (-HUGE,+HUGE)  ERANGE
  1665.   cosh     b too large  negative  nenneg.  (-HUGE,-HUGE)  ERANGE
  1666.   cosh     b too small  NA        NA       (0,0)          ERANGE
  1667.   exp      a too large  positive  positive (+HUGE,+HUGE)  ERANGE
  1668.   exp      a too large  positive  positive (+HUGE,-HUGE)  ERANGE
  1669.   exp      a too large  nonpos.   positive (-HUGE,+HUGE)  ERANGE
  1670.   exp      a too large  nonpos.   positive (-HUGE,-HUGE)  ERANGE
  1671.   exp      a too small  NA        NA       (0,0)          ERANGE
  1672.   exp      b too large  NA        NA       (0,0)          ERANGE
  1673.   exp      b too small  NA        NA       (0,0)          ERANGE
  1674.   log      a too large  positive  positive (+HUGE,0)      EDOM
  1675.                                     (a message is also produced)
  1676.   sinh     a too large  nonneg.   nonneg.  (+HUGE,+HUGE)  ERANGE
  1677.   sinh     a too large  nonneg.   negative (+HUGE,-HUGE)  ERANGE
  1678.   sinh     a too large  negative  nonneg.  (-HUGE,+HUGE)  ERANGE
  1679.   sinh     a too large  negative  negative (-HUGE,-HUGE)  ERANGE
  1680.   sinh     a too small  nonneg.   nonneg.  (-HUGE,+HUGE)  ERANGE
  1681.   sinh     a too small  nonneg.   negative (-HUGE,-HUGE)  ERANGE
  1682.   sinh     a too small  negative  nonneg.  (+HUGE,+HUGE)  ERANGE
  1683.   sinh     a too small  negative  negative (+HUGE,-HUGE)  ERANGE
  1684.   sinh     b too large  NA        NA       (0,0)          ERANGE
  1685.   sinh     b too small  NA        NA       (0,0)          ERANGE
  1686.  
  1687.  Note:  errno is set to EDOM when the error for log() is detected. The message 
  1688.  is stored in DDE4.MSG. The message number in DDE4.MSG is 90. When this message 
  1689.  is displayed by the C/C++ Runtime Library, it is changed to 5090. For 
  1690.  information on binding this message, see "Binding Runtime Messages" in the IBM 
  1691.  VisualAge C++ for OS/2 User's Guide and Reference. 
  1692.  
  1693.  
  1694. ΓòÉΓòÉΓòÉ 3.2.5. Errors Not Handled by the Complex Mathematics Library ΓòÉΓòÉΓòÉ
  1695.  
  1696. There are some cases where member functions of the Complex Mathematics Library 
  1697. call functions in the math library. These calls can cause underflow and 
  1698. overflow conditions that are handled by the matherr() function that is declared 
  1699. in the math.h header file. For example, the overflow conditions that are caused 
  1700. by the following calls are handled by matherr(): 
  1701.  
  1702.      exp(complex(DBL_MAX, DBL_MAX)) 
  1703.      pow(complex(DBL_MAX, DBL_MAX), INT_MAX) 
  1704.      norm(complex(DBL_MAX, DBL_MAX)) 
  1705.  
  1706.  DBL_MAX is the maximum valid double value.  INT_MAX is the maximum int value. 
  1707.  Both these constants are defined in float.h. 
  1708.  
  1709.  If you do not want the default error-handling defined by matherr(), you should 
  1710.  define your own version of matherr(). 
  1711.  
  1712.  
  1713. ΓòÉΓòÉΓòÉ 4. I/O Stream Classes ΓòÉΓòÉΓòÉ
  1714.  
  1715. With the I/O Stream Library you can perform input and output to console or 
  1716. files using a typesafe, object-oriented programming approach.  The following 
  1717. classes or groups of classes are described in this section: 
  1718.  
  1719.  filebuf Class Describes filebuf, the class that is used to associate stream 
  1720.              buffers with files. 
  1721.  
  1722.  fstream, ifstream, and ofstream Classes Describes fstream, ifstream, and 
  1723.              ofstream, the classes that specialize istream, ostream, and 
  1724.              iostream for use with files. 
  1725.  
  1726.  ios Class   Describes ios, the base class for the classes that format data 
  1727.              that is extracted from or inserted into stream buffers. 
  1728.  
  1729.  iostream and iostream_withassign Classes Describes iostream, the class derived 
  1730.              from istream and ostream, and iostream_withassign, the class 
  1731.              derived from istream_withassign and ostream_withassign. 
  1732.  
  1733.  istream and istream_withassign Classes Describes istream, the class you can 
  1734.              use to extract data from a stream buffer, and istream_withassign, 
  1735.              a class derived from istream that includes an assignment operator. 
  1736.  
  1737.  Manipulators Describes the parameterized manipulators you can use to use the 
  1738.              input or operator to change the state of a stream. 
  1739.  
  1740.  ostream and ostream_withassign Classes Describes ostream, the class you can 
  1741.              use to insert data into a stream buffer, and ostream_withassign, a 
  1742.              class derived from ostream that includes an assignment operator. 
  1743.  
  1744.  stdiobuf and stdiostream Classes Describes stdiobuf, the class you can use to 
  1745.              mix standard C input and output functions with C++ I/O Stream 
  1746.              Library functions, and stdiostream, the class that uses stdiobuf 
  1747.              objects as stream buffers. 
  1748.  
  1749.  streambuf Class Describes streambuf, a class you can use to manipulate objects 
  1750.              of its derived classes filebuf, stdiobuf, and strstreambuf, or 
  1751.              derive other classes from it. 
  1752.  
  1753.  strstream, istrstream, and ostrstream Classes Describes istrstream, ostrsteam, 
  1754.              and strstream, the classes that specialize istream, ostream, and 
  1755.              iostream (respectively) to use strstreambuf objects for stream 
  1756.              buffers. These classes are called the array stream buffer classes 
  1757.              because their stream buffers are arrays of bytes in memory. You 
  1758.              can use these classes to perform input and output with strings in 
  1759.              memory. 
  1760.  
  1761.  strstreambuf Class Describes strstreambuf, the class that specializes 
  1762.              streambuf to use an array of bytes in memory as the source or 
  1763.              target of data. 
  1764.  
  1765.  
  1766. ΓòÉΓòÉΓòÉ 4.1. filebuf Class ΓòÉΓòÉΓòÉ
  1767.  
  1768. Description 
  1769.  
  1770. Derivation 
  1771.  
  1772. Header File 
  1773.  
  1774. Members 
  1775.  
  1776. To close all the panels in a chapter, double-click on this panel's system menu. 
  1777.  
  1778.  
  1779. ΓòÉΓòÉΓòÉ 4.1.1. Class Description - filebuf ΓòÉΓòÉΓòÉ
  1780.  
  1781. This chapter describes the filebuf class, the class that specializes streambuf 
  1782. for using files as the ultimate producer or the ultimate consumer. 
  1783.  
  1784. In a filebuf object, characters are cleared out of the put area by doing write 
  1785. operations to the file, and characters are put into the get area by doing read 
  1786. operations from that file.  The filebuf class supports seek operations on files 
  1787. that allow seek operations.  A filebuf object that is attached to a file 
  1788. descriptor is said to be open. 
  1789.  
  1790. The stream buffer is allocated automatically if one is not specified explicitly 
  1791. with a constructor or a call to setbuf().  You can also create an unbuffered 
  1792. filebuf object by calling the constructor or setbuf() with the appropriate 
  1793. arguments.  If the filebuf objec is unbuffered, a system call is made for each 
  1794. character that is read or written. 
  1795.  
  1796. The get and put pointers for a filebuf object behave as a single pointer.  This 
  1797. single pointer is referred to as the get/put pointer.  The file that is 
  1798. attached to the filebuf object also has a single pointer that indicates the 
  1799. current position where information is being read or written.  In this chapter, 
  1800. this pointer is called the file get/put pointer. 
  1801.  
  1802.  
  1803. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  1804.  
  1805. streambuf 
  1806.  
  1807.   filebuf
  1808.  
  1809.  
  1810. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  1811.  
  1812. filebuf is declared in fstream.h. 
  1813.  
  1814.  
  1815. ΓòÉΓòÉΓòÉ 4.1.2. Public Members of filebuf ΓòÉΓòÉΓòÉ
  1816.  
  1817. See Using filebuf Functions to Move Through a File for an example of using the 
  1818. filebuf class. 
  1819.  
  1820. Note:  The following descriptions assume that the functions are called as part 
  1821. of a filebuf object called fb. 
  1822.  
  1823. The following member functions are described: 
  1824.  
  1825.      Constructors for filebuf 
  1826.      Destructor for filebuf 
  1827.      attach - attach filebuf object to file 
  1828.      close - disconnect filebuf 
  1829.      detach - detach filebuf object from file 
  1830.      fd - return file descriptor 
  1831.      is_open - return status of filebuf 
  1832.      open - open file and attach to filebuf 
  1833.      seekoff - move the file get/put pointer 
  1834.      seekpos - move the file get/put pointer 
  1835.      setbuf - set up stream buffer 
  1836.      sync - synchronize file and stream buffer 
  1837.  
  1838.  
  1839. ΓòÉΓòÉΓòÉ 4.1.2.1. Constructors for filebuf ΓòÉΓòÉΓòÉ
  1840.  
  1841. filebuf();
  1842. filebuf(int d);
  1843. filebuf(int d, char* p, int len);
  1844.  
  1845. The filebuf() constructor with no arguments constructs an initially closed 
  1846. filebuf object. 
  1847.  
  1848. The filebuf() constructor with one argument constructs a filebuf object that is 
  1849. attached to file descriptor d. 
  1850.  
  1851. The filebuf() constructor with three arguments constructs a filebuf object that 
  1852. is attached to file descriptor d. The object is initialized to use the stream 
  1853. buffer starting at the position pointed to by p with length equal to len. 
  1854.  
  1855.  
  1856. ΓòÉΓòÉΓòÉ 4.1.2.2. Destructor for filebuf ΓòÉΓòÉΓòÉ
  1857.  
  1858. ~filebuf();
  1859.  
  1860. The filebuf destructor calls fb.close(). 
  1861.  
  1862.  
  1863. ΓòÉΓòÉΓòÉ 4.1.2.3. attach ΓòÉΓòÉΓòÉ
  1864.  
  1865. filebuf* attach(int d);
  1866.  
  1867. attach() attaches fb to the file descriptor d. fb is the filebuf object 
  1868. returned by attach(). If fb is already open or if d is not open, attach() 
  1869. returns NULL. Otherwise, attach() returns a pointer to fb. 
  1870.  
  1871.  
  1872. ΓòÉΓòÉΓòÉ 4.1.2.4. detach ΓòÉΓòÉΓòÉ
  1873.  
  1874. int detach();
  1875.  
  1876. fb.detach() disconnects fb from the file without closing the file.  If fb is 
  1877. not open, detach() returns -1.  Otherwise, detach() flushes any output that is 
  1878. waiting in fb to be sent to the file, disconnects fb from the file, and returns 
  1879. the file descriptor. 
  1880.  
  1881.  
  1882. ΓòÉΓòÉΓòÉ 4.1.2.5. close ΓòÉΓòÉΓòÉ
  1883.  
  1884. filebuf* close();
  1885.  
  1886. close() does the following: 
  1887.  
  1888.    1. Flushes any output that is waiting in fb to be sent to the file 
  1889.    2. Disconnects fb from the file 
  1890.    3. Closes the file that was attached to fb 
  1891.  
  1892.  If an error occurs, close() returns 0. Otherwise, close() returns a pointer to 
  1893.  fb. Even if an error occurs, close() performs the second and third steps 
  1894.  listed above. 
  1895.  
  1896.  
  1897. ΓòÉΓòÉΓòÉ 4.1.2.6. fd ΓòÉΓòÉΓòÉ
  1898.  
  1899. int fd();
  1900.  
  1901. fd() returns the file descriptor that is attached to fb. If fb is closed, fd() 
  1902. returns EOF. 
  1903.  
  1904.  
  1905. ΓòÉΓòÉΓòÉ 4.1.2.7. is_open ΓòÉΓòÉΓòÉ
  1906.  
  1907. int is_open();
  1908.  
  1909. is_open() returns a nonzero value if fb is attached to a file descriptor. 
  1910. Otherwise, is_open() returns zero. 
  1911.  
  1912.  
  1913. ΓòÉΓòÉΓòÉ 4.1.2.8. open ΓòÉΓòÉΓòÉ
  1914.  
  1915. filebuf* open(const char* fname, int omode, int prot=openprot);
  1916.  
  1917. open() opens the file with the name fname and attaches fb to it. If fname does 
  1918. not already exist and omode does not equal ios::nocreate, open() tries to 
  1919. create it with protection mode equal to prot. The default value of prot is 
  1920. filebuf::openprot. An error occurs if fb is already open. If an error occurs, 
  1921. open() returns 0. Otherwise, open() returns a pointer to fb. 
  1922.  
  1923. The default protection mode for the filebuf class is S_IREAD | S_IWRITE. If you 
  1924. create a file with both S_IREAD and S_IWRITE set, the file is created with both 
  1925. read and write permission. If you create a file with only S_IREAD set, the file 
  1926. is created with read-only permission, and cannot be deleted later with the 
  1927. stdio.h library function remove(). S_IREAD and S_IWRITE are defined in 
  1928. sys\stat.h. 
  1929.  
  1930.  
  1931. ΓòÉΓòÉΓòÉ 4.1.2.9. seekoff ΓòÉΓòÉΓòÉ
  1932.  
  1933. streampos seekoff(streamoff so, seek_dir sd, int omode);
  1934.  
  1935. seekoff() moves the file get/put pointer to the position specified by sd with 
  1936. the offset so. sd can have the following values: 
  1937.  
  1938.      ios::beg: the beginning of the file 
  1939.      ios::cur: the current position of the file get/put pointer 
  1940.      ios::end: the end of the file 
  1941.  
  1942.  seekoff() changes the position of the file get/put pointer to the position 
  1943.  specified by the value sd + so. The offset so can be either positive or 
  1944.  negative. seekoff() ignores the value of omode. 
  1945.  
  1946.  If fb is attached to a file that does not support seeking, or if the value sd 
  1947.  + so specifies a position before the beginning of the file, seekoff() returns 
  1948.  EOF and the position of the file get/put pointer is undefined. Otherwise, 
  1949.  seekoff() returns the new position of the file get/put pointer. 
  1950.  
  1951.  
  1952. ΓòÉΓòÉΓòÉ 4.1.2.10. seekpos ΓòÉΓòÉΓòÉ
  1953.  
  1954. The filebuf class inherits the default definition of seekpos() from the 
  1955. streambuf class. The default definition defines seekpos() as a call to 
  1956. seekoff(). Thus, the following call to seekpos(): 
  1957.  
  1958. seekpos(pos, mode);
  1959.  
  1960. is converted to a call to seekoff(): 
  1961.  
  1962. seekoff(streamoff(pos), ios::beg, mode);
  1963.  
  1964.  
  1965. ΓòÉΓòÉΓòÉ 4.1.2.11. setbuf ΓòÉΓòÉΓòÉ
  1966.  
  1967. streambuf* setbuf(char* pbegin, int len);
  1968.  
  1969. setbuf() sets up a stream buffer with length in bytes equal to len, beginning 
  1970. at the position pointed to by pbegin. setbuf() does the following: 
  1971.  
  1972.      If pbegin is 0 or len is nonpositive, setbuf() makes fb unbuffered. 
  1973.      If fb is open and a stream buffer has been allocated, no changes are made 
  1974.       to this stream buffer, and setbuf() returns NULL. 
  1975.      If neither of these cases is true, setbuf() returns a pointer to fb. 
  1976.  
  1977.  
  1978. ΓòÉΓòÉΓòÉ 4.1.2.12. sync ΓòÉΓòÉΓòÉ
  1979.  
  1980. int sync();
  1981.  
  1982. sync() attempts to synchronize the get/put pointer and the file get/put 
  1983. pointer. sync() may cause bytes that are waiting in the stream buffer to be 
  1984. written to the file, or it may reposition the file get/put pointer if 
  1985. characters that have been read from the file are waiting in the stream buffer. 
  1986. If it is not possible to synchronize the get/put pointer and the file get/put 
  1987. pointer, sync() returns EOF. If they can be synchronized, sync() returns zero. 
  1988.  
  1989.  
  1990. ΓòÉΓòÉΓòÉ 4.2. fstream, ifstream, and ofstream Classes ΓòÉΓòÉΓòÉ
  1991.  
  1992. Description 
  1993.  
  1994. Derivation 
  1995.  
  1996. Header File 
  1997.  
  1998. Members 
  1999.  
  2000. To close all the panels in a chapter, double-click on this panel's system menu. 
  2001.  
  2002.  
  2003. ΓòÉΓòÉΓòÉ 4.2.1. Class Description - fstream, ifstream, and ofstream ΓòÉΓòÉΓòÉ
  2004.  
  2005. The fstream, ifstream, and ofstream classes specialize istream, ostream, and 
  2006. iostream for use with files. 
  2007.  
  2008.  
  2009. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  2010.  
  2011. ios 
  2012.  
  2013.   istream
  2014.    ifstream
  2015.   ostream
  2016.    ofstream
  2017.   istream and ostream
  2018.    iostream
  2019.      fstream
  2020.  
  2021.  
  2022. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  2023.  
  2024. fstream, ifstream, and ofstream are declared in fstream.h. 
  2025.  
  2026.  
  2027. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  2028.  
  2029. The following members are provided for fstream, ifstream, ofstream, and 
  2030. fstreambase: 
  2031.  
  2032.      fstreambase: 
  2033.            attach 
  2034.            close 
  2035.            detach 
  2036.            setbuf 
  2037.      fstream: 
  2038.            Constructors for fstream 
  2039.            open 
  2040.            rdbuf 
  2041.      ifstream: 
  2042.            Constructors for ifstream 
  2043.            open 
  2044.            rdbuf 
  2045.      ofstream: 
  2046.            Constructors for ofstream 
  2047.            open 
  2048.            rdbuf 
  2049.  
  2050.  
  2051. ΓòÉΓòÉΓòÉ 4.2.2. fstreambase ΓòÉΓòÉΓòÉ
  2052.  
  2053. Description 
  2054.  
  2055. Members 
  2056.  
  2057. To close all the panels in a chapter, double-click on this panel's system menu. 
  2058.  
  2059.  
  2060. ΓòÉΓòÉΓòÉ 4.2.3. Class Description - fstreambase ΓòÉΓòÉΓòÉ
  2061.  
  2062. Note: 
  2063.  
  2064.    1. The fstreambase class is an internal class that provides common functions 
  2065.       for the classes that are derived from it. Do not use the fstreambase 
  2066.       class directly. The following descriptions are provided so that you can 
  2067.       use the functions as part of fstream, ifstream, and ofstream objects. 
  2068.  
  2069.    2. The following descriptions assume that the functions are called as part 
  2070.       of an fstream, ifstream, or ofstream object called fb. 
  2071.  
  2072.  
  2073. ΓòÉΓòÉΓòÉ 4.2.3.1. Members ΓòÉΓòÉΓòÉ
  2074.  
  2075. The following functions are described: 
  2076.  
  2077.      attach - connect fstream object to file descriptor 
  2078.      close - close associated filebuf object 
  2079.      detach - detach associated filebuf object 
  2080.      setbuf - set up stream buffer 
  2081.  
  2082.  
  2083. ΓòÉΓòÉΓòÉ 4.2.3.1.1. attach ΓòÉΓòÉΓòÉ
  2084.  
  2085. void attach(int filedesc);
  2086.  
  2087. attach() attaches fb to the file descriptor filedesc. If fb is already attached 
  2088. to a file descriptor, an error occurs and ios::failbit is set in the format 
  2089. state of fb. 
  2090.  
  2091.  
  2092. ΓòÉΓòÉΓòÉ 4.2.3.1.2. close ΓòÉΓòÉΓòÉ
  2093.  
  2094. void close();
  2095.  
  2096. close() closes the filebuf object, breaking the connection between fb and the 
  2097. file descriptor. close() calls fb.rdbuf()->close(). If this call fails, the 
  2098. error state of fb is not cleared. 
  2099.  
  2100.  
  2101. ΓòÉΓòÉΓòÉ 4.2.3.1.3. detach ΓòÉΓòÉΓòÉ
  2102.  
  2103. int detach();
  2104.  
  2105. detach detaches the filebuf object by calling fb.rdbuf()->detach(), and returns 
  2106. the value returned by fb.rdbuf()->detach(). 
  2107.  
  2108.  
  2109. ΓòÉΓòÉΓòÉ 4.2.3.1.4. setbuf ΓòÉΓòÉΓòÉ
  2110.  
  2111. void setbuf(char* pbegin, int len);
  2112.  
  2113. setbuf() sets up a stream buffer with length in bytes equal to len beginning at 
  2114. the position pointed to by pbegin. If pbegin is equal to 0 or len is 
  2115. nonpositive, fb will be unbuffered. If fb is open, or the call to 
  2116. fb.rdbuf()->setbuf() fails, setbuf() sets ios::failbit in the object's state. 
  2117.  
  2118.  
  2119. ΓòÉΓòÉΓòÉ 4.2.4. fstream Class ΓòÉΓòÉΓòÉ
  2120.  
  2121. Description 
  2122.  
  2123. Members 
  2124.  
  2125. To close all the panels in a chapter, double-click on this panel's system menu. 
  2126.  
  2127.  
  2128. ΓòÉΓòÉΓòÉ 4.2.5. Class Description - fstream ΓòÉΓòÉΓòÉ
  2129.  
  2130. The fstream class specializes iostream for use with files. Once an fstream 
  2131. object is associated with a file, you can either read to it or write to it, 
  2132. depending on the mode with which the file was opened.  Once the file is closed, 
  2133. you can open another file (or the same file again) in a different mode using 
  2134. the same fstream object. 
  2135.  
  2136. The descriptions for fstream member functions assume that the functions are 
  2137. called as part of an fstream object called fs. 
  2138.  
  2139.  
  2140. ΓòÉΓòÉΓòÉ 4.2.5.1. Members ΓòÉΓòÉΓòÉ
  2141.  
  2142. The following functions are described: 
  2143.  
  2144.      Constructors for fstream 
  2145.      open - open file and connect to fstream object 
  2146.      rdbuf - return pointer to filebuf object 
  2147.  
  2148.  
  2149. ΓòÉΓòÉΓòÉ 4.2.5.1.1. Constructors for fstream ΓòÉΓòÉΓòÉ
  2150.  
  2151. fstream();
  2152.  
  2153. This version of the fstream constructor takes no arguments and constructs an 
  2154. unopened fstream object. 
  2155.  
  2156. fstream(int filedesc);
  2157.  
  2158. This version takes one argument and constructs an fstream object that is 
  2159. attached to the file descriptor filedesc. If filedesc is not open, ios::failbit 
  2160. is set in the format state of fs. 
  2161.  
  2162. fstream(const char* fname, int mode, int prot=filebuf::openprot);
  2163.  
  2164. This version constructs an fstream object and opens the file fname with open 
  2165. mode equal to mode and protection mode equal to prot. The default value for the 
  2166. argument prot is filebuf::openprot. If the file cannot be opened, the error 
  2167. state of the constructed fstream object is set. 
  2168.  
  2169. fstream(int filedesc, char* bufpos, int len);
  2170.  
  2171. This version constructs an fstream object that is attached to the file 
  2172. descriptor filedesc. If filedesc is not open, ios::failbit is set in the format 
  2173. state of fs. This constructor also sets up an associated filebuf object with a 
  2174. stream buffer that has length len bytes and begins at the position pointed to 
  2175. by bufpos. If bufpos is equal to 0 or len is equal to 0, the associated filebuf 
  2176. object is unbuffered. 
  2177.  
  2178.  
  2179. ΓòÉΓòÉΓòÉ 4.2.5.1.2. open ΓòÉΓòÉΓòÉ
  2180.  
  2181. void open(const char* fname, int mode, int prot=filebuf::openprot);
  2182.  
  2183. open() opens the file with the name fname and attaches it to fs. If fname does 
  2184. not already exist, open() tries to create it with protection mode equal to 
  2185. prot, unless ios::nocreate is set. 
  2186.  
  2187. The default value for prot is filebuf::openprot. If fs is already attached to a 
  2188. file or if the call to fs.rdbuf()->open() fails, ios::failbit is set in the 
  2189. error state for fs. 
  2190.  
  2191. The members of the ios::open_mode enumeration are bits that can be ORed 
  2192. together. The value of mode is the result of such an OR operation. This result 
  2193. is an int value, and for this reason, mode has type int rather than open_mode. 
  2194.  
  2195. The elements of the open_mode enumeration have the following meanings: 
  2196.  
  2197.  ios::app       open() performs a seek to the end of the file. Data that is 
  2198.                 written is appended to the end of the file. This value implies 
  2199.                 that the file is open for output. 
  2200.  
  2201.  ios::ate       open() performs a seek to the end of the file. Setting ios::ate 
  2202.                 does not open the file for input or output. If you set 
  2203.                 ios::ate, you should explicitly set ios::in, ios::out, or both. 
  2204.  
  2205.  ios::bin       See ios::binary below. 
  2206.  
  2207.  ios::binary    The file is opened in binary mode. In the default (text) mode, 
  2208.                 carriage returns are discarded on input, as is an end-of-file 
  2209.                 (0x1a) character if it is the last character in the file. This 
  2210.                 means that a carriage return without an accompanying line feed 
  2211.                 causes the characters on either side of the carriage return to 
  2212.                 become adjacent. On output, a line feed is expanded to a 
  2213.                 carriage return and line feed. If you specify ios::binary, 
  2214.                 carriage returns and terminating end-of-file characters are not 
  2215.                 removed on input, and a line feed is not expanded to a carriage 
  2216.                 return and line feed on output. ios::binary and ios::bin 
  2217.                 provide identical functionality. 
  2218.  
  2219.  ios::in        The file is opened for input. If the file that is being opened 
  2220.                 for input does not exist, the open operation will fail. 
  2221.                 ios::noreplace is ignored if ios::in is set. 
  2222.  
  2223.  ios::out       The file is opened for output. 
  2224.  
  2225.  ios::trunc     If the file already exists, its contents will be discarded. If 
  2226.                 you specify ios::out and neither ios::ate nor ios::app, you are 
  2227.                 implicitly specifying ios::trunc. If you set ios::trunc, you 
  2228.                 should explicitly set ios::in, ios::out, or both. 
  2229.  
  2230.  ios::nocreate  If the file does not exist, the call to open() fails. 
  2231.  
  2232.  ios::noreplace If the file already exists and ios::out is set, the call to 
  2233.                 open() fails. If ios::out is not set, ios::noreplace is 
  2234.                 ignored. 
  2235.  
  2236.  
  2237. ΓòÉΓòÉΓòÉ 4.2.5.1.3. rdbuf ΓòÉΓòÉΓòÉ
  2238.  
  2239. filebuf* rdbuf();
  2240.  
  2241. rdbuf() returns a pointer to the filebuf object that is attached to fs. 
  2242.  
  2243.  
  2244. ΓòÉΓòÉΓòÉ 4.2.6. ifstream Class ΓòÉΓòÉΓòÉ
  2245.  
  2246. Description 
  2247.  
  2248. Members 
  2249.  
  2250. To close all the panels in a chapter, double-click on this panel's system menu. 
  2251.  
  2252.  
  2253. ΓòÉΓòÉΓòÉ 4.2.7. Class Description - ifstream ΓòÉΓòÉΓòÉ
  2254.  
  2255. The ifstream class specializes istream for use with files.  When you create an 
  2256. ifstream object and associate it with a file, the file is opened for input. 
  2257. The advantage of using ifstream over fstream is that attempts to write data to 
  2258. an ifstream object are flagged as errors at compilation. 
  2259.  
  2260. For an example of using the ifstream class, click here. 
  2261.  
  2262. Note:  The following descriptions assume that the functions are called as part 
  2263. of an ifstream object called ifs. 
  2264.  
  2265.  
  2266. ΓòÉΓòÉΓòÉ 4.2.7.1. Members ΓòÉΓòÉΓòÉ
  2267.  
  2268.      Constructors for ifstream 
  2269.      open - open file and connect to ifstream object 
  2270.      rdbuf - return pointer to filebuf object 
  2271.  
  2272.  
  2273. ΓòÉΓòÉΓòÉ 4.2.7.1.1. Constructors for ifstream ΓòÉΓòÉΓòÉ
  2274.  
  2275. ifstream();
  2276.  
  2277. This version of the ifstream constructor takes no arguments and constructs an 
  2278. unopened ifstream object. 
  2279.  
  2280. ifstream(int filedesc);
  2281.  
  2282. This version takes one argument and constructs an ifstream object that is 
  2283. attached to the file descriptor filedesc. If filedesc is not open, ios::failbit 
  2284. is set in the format state of ifs. 
  2285.  
  2286. ifstream(const char* fname,
  2287.          int mode=ios::in,
  2288.          int prot=filebuf::openprot);
  2289.  
  2290. The third version constructs an ifstream object and opens the file fname with 
  2291. open mode equal to mode and protection mode equal to prot. The default value 
  2292. for mode is ios::in, and the default value for prot is filebuf::openprot. If 
  2293. the file cannot be opened, the error state of the constructed ifstream object 
  2294. is set. 
  2295.  
  2296. ifstream(int filedesc, char* bufpos, int len);
  2297.  
  2298. This version constructs an ifstream object that is attached to the file 
  2299. descriptor filedesc. If filedesc is not open, ios::failbit is set in the format 
  2300. state of ifs. This constructor also sets up an associated filebuf object with a 
  2301. stream buffer that has length len bytes and begins at the position pointed to 
  2302. by bufpos. If bufpos is equal to 0 or len is equal to 0, the associated filebuf 
  2303. object is unbuffered. 
  2304.  
  2305.  
  2306. ΓòÉΓòÉΓòÉ 4.2.7.1.2. open ΓòÉΓòÉΓòÉ
  2307.  
  2308. void open(const char* fname,
  2309.           int mode=ios::in,
  2310.           int prot=filebuf::openprot);
  2311.  
  2312. open() opens the file with the name fname and attaches it to ifs. If fname does 
  2313. not already exist, open() tries to create it with protection mode equal to 
  2314. prot, unless ios::nocreate is set in mode. 
  2315.  
  2316. The default value for mode is ios::in. The default value for prot is 
  2317. filebuf::openprot. If ifs is already attached to a file, or if the call to 
  2318. ifs.rdbuf()->open() fails, ios::failbit is set in the error status for ifs. 
  2319.  
  2320. The members of the ios::open_mode enumeration are bits that can be ORed 
  2321. together. The value of mode is the result of such an OR operation. This result 
  2322. is an int value, and for this reason mode has type int rather than type 
  2323. open_mode. See open for a list of the possible values for mode. 
  2324.  
  2325.  
  2326. ΓòÉΓòÉΓòÉ 4.2.7.1.3. rdbuf ΓòÉΓòÉΓòÉ
  2327.  
  2328. filebuf* rdbuf();
  2329.  
  2330. rdbuf() returns a pointer to the filebuf object that is attached to ifs. 
  2331.  
  2332.  
  2333. ΓòÉΓòÉΓòÉ 4.2.8. ofstream Class ΓòÉΓòÉΓòÉ
  2334.  
  2335. Description 
  2336.  
  2337. Members 
  2338.  
  2339. To close all the panels in a chapter, double-click on this panel's system menu. 
  2340.  
  2341.  
  2342. ΓòÉΓòÉΓòÉ 4.2.9. Class Description - ofstream ΓòÉΓòÉΓòÉ
  2343.  
  2344. The ofstream class specializes ostream for use with files.  When you create an 
  2345. ofstream object and associate it with a file, the file is opened for output. 
  2346. The advantage of using ofstream over fstream is that attempts to read data from 
  2347. an ofstream object are flagged as errors at compilation. 
  2348.  
  2349. For an example of using the ofstream class, select this hypertext link. 
  2350.  
  2351. Note:  The following descriptions assume that the functions are called as part 
  2352. of an ofstream object called ofs. 
  2353.  
  2354.  
  2355. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  2356.  
  2357.      Constructors for ofstream 
  2358.      open - open file and connect to ofstream object 
  2359.      rdbuf - return pointer to filebuf object 
  2360.  
  2361.  
  2362. ΓòÉΓòÉΓòÉ 4.2.9.1. Constructors for ofstream ΓòÉΓòÉΓòÉ
  2363.  
  2364. ofstream();
  2365.  
  2366. This version of the ofstream constructor takes no arguments and constructs an 
  2367. unopened ofstream object. 
  2368.  
  2369. ofstream(int filedesc);
  2370.  
  2371. This version takes one argument and constructs an ofstream object that is 
  2372. attached to the file descriptor filedesc. If filedesc is not open, ios::failbit 
  2373. is set in the format state of ofs. 
  2374.  
  2375. ofstream(const char* fname,
  2376.          int mode=ios::out,
  2377.          int prot=filebuf::openprot);
  2378.  
  2379. This version constructs an ofstream object and opens the file fname with open 
  2380. mode equal to mode and protection mode equal to prot. The default value for 
  2381. mode is ios::out, and the default value for prot is filebuf::openprot. If the 
  2382. file cannot be opened, the error state of the constructed ofstream object is 
  2383. set. 
  2384.  
  2385. ofstream(int filedesc, char* bufpos, int len);
  2386.  
  2387. This version constructs an ofstream object that is attached to the file 
  2388. descriptor filedesc. If filedesc is not open, ios::failbit is set in the format 
  2389. state of ofs. This constructor also sets up an associated filebuf object with a 
  2390. stream buffer that has length len bytes and begins at the position pointed to 
  2391. by bufpos. If p is equal to 0 or len is equal to 0, the associated filebuf 
  2392. object is unbuffered. 
  2393.  
  2394.  
  2395. ΓòÉΓòÉΓòÉ 4.2.9.2. open ΓòÉΓòÉΓòÉ
  2396.  
  2397. void open(const char* fname, int mode, int prot=filebuf::openprot);
  2398.  
  2399. open() opens the file with the name fname and attaches it to ofs. If fname does 
  2400. not already exist, open() tries to create it with protection mode equal to 
  2401. prot, unless ios::nocreate is set. 
  2402.  
  2403. The default value for mode is ios::out. The default value for the argument prot 
  2404. is filebuf::openprot. If ofs is already attached to a file, or if the call to 
  2405. the function ofs.rdbuf()->open() fails, ios::failbit is set in the error state 
  2406. for ofs. 
  2407.  
  2408. The members of the ios::open_mode enumeration are bits that can be ORed 
  2409. together. The value of mode is the result of such an OR operation. This result 
  2410. is an int value, and for this reason, mode has type int rather than open_mode. 
  2411. See open for a list of the possible values for mode. 
  2412.  
  2413.  
  2414. ΓòÉΓòÉΓòÉ 4.2.9.3. rdbuf ΓòÉΓòÉΓòÉ
  2415.  
  2416. filebuf* rdbuf();
  2417.  
  2418. rdbuf() returns a pointer to the filebuf object that is attached to ofs. 
  2419.  
  2420.  
  2421. ΓòÉΓòÉΓòÉ 4.3. ios Class ΓòÉΓòÉΓòÉ
  2422.  
  2423. Description 
  2424.  
  2425. Derivation 
  2426.  
  2427. Header File 
  2428.  
  2429. Constructors 
  2430.  
  2431. Members 
  2432.  
  2433. To close all the panels in a chapter, double-click on this panel's system menu. 
  2434.  
  2435.  
  2436. ΓòÉΓòÉΓòÉ 4.3.1. Class Description - ios ΓòÉΓòÉΓòÉ
  2437.  
  2438. The ios class maintains the error and format state information for the classes 
  2439. that are derived from it. The derived classes support the movement of formatted 
  2440. and unformatted data to and from the stream buffer. This chapter describes the 
  2441. members of the ios class, and thus describes the operations that are common to 
  2442. all the classes that are derived from ios. 
  2443.  
  2444. You can view the topics in this chapter either through the panel on the left, 
  2445. or by selecting from among the following: 
  2446.  
  2447.      Format State Variables 
  2448.      Format State Flags: 
  2449.         -  White Space and Padding 
  2450.         -  Base Conversion 
  2451.         -  Integral Formatting 
  2452.         -  Floating-Point Formatting 
  2453.         -  Uppercase and Lowercase 
  2454.         -  Buffer Flushing 
  2455.         -  Mutually Exclusive Format Flags 
  2456.      Format State Members 
  2457.      User-Defined Format Flags 
  2458.      ios Error State 
  2459.      Other ios Members 
  2460.      Built-In Manipulators 
  2461.  
  2462.  
  2463. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  2464.  
  2465. ios 
  2466.  
  2467.  
  2468. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  2469.  
  2470. ios is declared in iostream.h. 
  2471.  
  2472.  
  2473. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  2474.  
  2475. The following members are provided for ios. Italicized members are flags or 
  2476. variables used to maintain the format state information for streams. 
  2477.  
  2478.      ios constructor 
  2479.      bad 
  2480.      bitalloc 
  2481.      clear 
  2482.      dec 
  2483.      dec manipulator 
  2484.      endl manipulator 
  2485.      ends manipulator 
  2486.      eof 
  2487.      fail 
  2488.      fill 
  2489.      fixed 
  2490.      flags 
  2491.      flush manipulator 
  2492.      good 
  2493.      hex 
  2494.      hex manipulator 
  2495.      internal 
  2496.      iword 
  2497.      left 
  2498.      oct 
  2499.      oct manipulator 
  2500.      operator void* 
  2501.      operator= 
  2502.      precision 
  2503.      pword 
  2504.      rdbuf 
  2505.      rdstate 
  2506.      right 
  2507.      scientific 
  2508.      setf 
  2509.      showbase 
  2510.      showpoint 
  2511.      showpos 
  2512.      skip 
  2513.      skipws 
  2514.      stdio 
  2515.      sync_with_stdio 
  2516.      tie 
  2517.      unitbuf 
  2518.      unsetf 
  2519.      uppercase 
  2520.      width 
  2521.      ws manipulator 
  2522.      x_fill 
  2523.      x_precision 
  2524.      x_width 
  2525.      xalloc 
  2526.  
  2527.  
  2528. ΓòÉΓòÉΓòÉ 4.3.2. Constructors and Assignment Operator for ios ΓòÉΓòÉΓòÉ
  2529.  
  2530. public:
  2531.      ios(streambuf* sb);
  2532. protected:
  2533.      ios();
  2534.      init(streambuf* isb);
  2535. private:
  2536.      ios(ios& ioa);
  2537.      void operator=(ios& iob);
  2538.  
  2539. There are three versions of the ios constructor. The version that is declared 
  2540. public takes a single argument that is a pointer to the streambuf object that 
  2541. becomes associated with the constructed ios object. If this pointer is equal to 
  2542. 0, the result is undefined. 
  2543.  
  2544. The version of the ios constructor that is declared protected takes no 
  2545. arguments. This version is needed because ios is used as a virtual base class 
  2546. for iostream, and therefore the ios class must have a constructor that takes no 
  2547. arguments. If you use this constructor in a derived class, you must use the 
  2548. init() function to associate the constructed ios object with the streambuf 
  2549. object pointed to by the argument isb. 
  2550.  
  2551. Copying of ios objects is not well defined, and for this reason, both the 
  2552. assignment operator and the copy constructor are declared private. Assignment 
  2553. between streams is supported by the istream_withassign, ostream_withassign, and 
  2554. iostream_withassign classes. See Assignment Operator for istream_withassign and 
  2555. Assignment Operator for ostream_withassign for more details. Except for the 
  2556. ..._withassign classes, none of the predefined classes derived from ios has a 
  2557. copy constructor or an assignment operator. Unless you define your own copy 
  2558. constructor or assignment operator for a class that you derive from ios, your 
  2559. class will have neither a copy constructor nor an assignment operator. 
  2560.  
  2561.  
  2562. ΓòÉΓòÉΓòÉ 4.3.3. Format State Variables ΓòÉΓòÉΓòÉ
  2563.  
  2564. The format state is a collection of format flags and format variables that 
  2565. control the details of formatting for input and output operations. This section 
  2566. describes the format variables. 
  2567.  
  2568.  
  2569. ΓòÉΓòÉΓòÉ 4.3.3.1. x_fill ΓòÉΓòÉΓòÉ
  2570.  
  2571. char x_fill;
  2572.  
  2573. x_fill is the character that is used to pad values that do not require the 
  2574. width of an entire field for their representation. Its default value is a space 
  2575. character. 
  2576.  
  2577.  
  2578. ΓòÉΓòÉΓòÉ 4.3.3.2. x_precision ΓòÉΓòÉΓòÉ
  2579.  
  2580. short x_precision;
  2581.  
  2582. x_precision is the number of significant digits in the representation of 
  2583. floating-point values. Its default value is 6. 
  2584.  
  2585.  
  2586. ΓòÉΓòÉΓòÉ 4.3.3.3. x_width ΓòÉΓòÉΓòÉ
  2587.  
  2588. short x_width;
  2589.  
  2590. x_width is the minimum width of a field. Its default value is 0. 
  2591.  
  2592.  
  2593. ΓòÉΓòÉΓòÉ 4.3.4. Format State Flags ΓòÉΓòÉΓòÉ
  2594.  
  2595. The following list shows the formatting features and the format flags that 
  2596. control them: 
  2597.  
  2598.      White space and padding: ios::skipws, ios::left, ios::right, 
  2599.       ios::internal 
  2600.      Base conversion: ios::dec, ios::hex, ios::oct, ios::showbase 
  2601.      Integral formatting: ios::showpos 
  2602.      Floating-point formatting: ios::fixed, ios::scientific, ios::showpoint 
  2603.      Uppercase and lowercase: ios::uppercase 
  2604.      Buffer flushing: ios::stdio, ios::unitbuf 
  2605.  
  2606.  Mutually Exclusive Format Flags describes the flags that produce unpredictable 
  2607.  results if they are set at the same time. 
  2608.  
  2609.  
  2610. ΓòÉΓòÉΓòÉ 4.3.4.1. White Space and Padding ΓòÉΓòÉΓòÉ
  2611.  
  2612. The following format state flags control white space and padding characters. 
  2613. skipws and right are set by default. 
  2614.  
  2615.  
  2616. ΓòÉΓòÉΓòÉ 4.3.4.1.1. skipws ΓòÉΓòÉΓòÉ
  2617.  
  2618. If ios::skipws is set, white space will be skipped on input. If it is not set, 
  2619. white space is not skipped. If ios::skipws is not set, the arithmetic 
  2620. extractors will signal an error if you attempt to read an integer or 
  2621. floating-point value that is preceded by white space. ios::failbit is set, and 
  2622. extraction ceases until it is cleared. This is done to avoid looping problems. 
  2623. If the following program is run with an input file that contains integer values 
  2624. separated by spaces, ios::failbit is set after the first integer value is read, 
  2625. and the program halts. If the program did not call fail() at the beginning of 
  2626. the while loop to test if ios::failbit is set, it would loop indefinitely. 
  2627.  
  2628.    #include <fstream.h>
  2629.  
  2630.    void main()
  2631.    {
  2632.       fstream f("spadina.dat", ios::in);
  2633.       f.unsetf(ios::skipws);
  2634.       int i;
  2635.       while (!f.eof() && !f.fail()) {
  2636.          f >> i;
  2637.          cout << i;
  2638.       }
  2639.    }
  2640.  
  2641.  
  2642. ΓòÉΓòÉΓòÉ 4.3.4.1.2. left ΓòÉΓòÉΓòÉ
  2643.  
  2644. If ios::left is set, the value is left-justified. Fill characters are added 
  2645. after the value. 
  2646.  
  2647.  
  2648. ΓòÉΓòÉΓòÉ 4.3.4.1.3. right ΓòÉΓòÉΓòÉ
  2649.  
  2650. If ios::right is set, the value is right-justified. Fill characters are added 
  2651. before the value. 
  2652.  
  2653.  
  2654. ΓòÉΓòÉΓòÉ 4.3.4.1.4. internal ΓòÉΓòÉΓòÉ
  2655.  
  2656. If ios::internal is set, the fill characters are added after any leading sign 
  2657. or base notation, but before the value itself. 
  2658.  
  2659.  
  2660. ΓòÉΓòÉΓòÉ 4.3.4.2. Base Conversion ΓòÉΓòÉΓòÉ
  2661.  
  2662. The manipulators ios::dec, ios::oct, and ios::hex (see Built-In Manipulators 
  2663. for ios for more details) have the same effect as the flags ios::dec, ios::oct, 
  2664. and ios::hex, respectively.  dec is set by default. 
  2665.  
  2666.  
  2667. ΓòÉΓòÉΓòÉ 4.3.4.2.1. dec ΓòÉΓòÉΓòÉ
  2668.  
  2669. If ios::dec is set, the conversion base is 10. 
  2670.  
  2671.  
  2672. ΓòÉΓòÉΓòÉ 4.3.4.2.2. oct ΓòÉΓòÉΓòÉ
  2673.  
  2674. If ios::oct is set, the conversion base is 8. 
  2675.  
  2676.  
  2677. ΓòÉΓòÉΓòÉ 4.3.4.2.3. hex ΓòÉΓòÉΓòÉ
  2678.  
  2679. If ios::hex is set, the conversion base is 16. 
  2680.  
  2681.  
  2682. ΓòÉΓòÉΓòÉ 4.3.4.2.4. showbase ΓòÉΓòÉΓòÉ
  2683.  
  2684. If ios::showbase is set, the operation that inserts values converts them to an 
  2685. external form that can be read according to the C++ lexical conventions for 
  2686. integral constants. By default, ios::showbase is unset. 
  2687.  
  2688.  
  2689. ΓòÉΓòÉΓòÉ 4.3.4.3. Integral Formatting ΓòÉΓòÉΓòÉ
  2690.  
  2691. :link auto dependent reftype=hd refid=iosshop. 
  2692.  
  2693. The following manipulator affects integral formatting: 
  2694.  
  2695.  
  2696. ΓòÉΓòÉΓòÉ 4.3.4.3.1. showpos ΓòÉΓòÉΓòÉ
  2697.  
  2698. If ios::showpos is set, the operation that inserts values places a positive 
  2699. sign "+" into decimal conversions of positive integral values. By default, 
  2700. showpos is not set. 
  2701.  
  2702.  
  2703. ΓòÉΓòÉΓòÉ 4.3.4.4. Floating-Point Formatting ΓòÉΓòÉΓòÉ
  2704.  
  2705. The following format flags control the formatting of floating-point values: 
  2706. :link auto dependent reftype=hd refid=iosshpt. 
  2707.  
  2708.  
  2709. ΓòÉΓòÉΓòÉ 4.3.4.4.1. showpoint ΓòÉΓòÉΓòÉ
  2710.  
  2711. If ios::showpoint is set, trailing zeros and a decimal point appear in the 
  2712. result of a floating-point conversion. This flag has no effect if either 
  2713. ios::scientific or ios::fixed is set. showpoint is not set by default. 
  2714.  
  2715.  
  2716. ΓòÉΓòÉΓòÉ 4.3.4.4.2. scientific ΓòÉΓòÉΓòÉ
  2717.  
  2718. If ios::scientific is set, the value is converted using scientific notation. In 
  2719. scientific notation, there is one digit before the decimal point and the number 
  2720. of digits following the decimal point depends on the value of ios::x_precision. 
  2721. The default value for ios::x_precision is 6. If ios::uppercase is set, an 
  2722. uppercase "E" precedes the exponent. Otherwise, a lowercase "e" precedes the 
  2723. exponent. By default, uppercase is not set. See uppercase for more information. 
  2724.  
  2725.  
  2726. ΓòÉΓòÉΓòÉ 4.3.4.4.3. fixed ΓòÉΓòÉΓòÉ
  2727.  
  2728. If ios::fixed is set, floating-point values are converted to fixed notation 
  2729. with the number of digits after the decimal point equal to the value of 
  2730. ios::x_precision (or 6 by default). ios::fixed is not set by default. 
  2731.  
  2732.  
  2733. ΓòÉΓòÉΓòÉ 4.3.4.4.4. Default Representation of Floating-Point Values ΓòÉΓòÉΓòÉ
  2734.  
  2735. If neither ios::fixed nor ios::scientific is set, the representation of 
  2736. floating-point values depends on their values and the number of significant 
  2737. digits in the representation equals ios::x_precision. Floating-point values are 
  2738. converted to scientific notation if the exponent resulting from a conversion to 
  2739. scientific notation is less than -4 or greater than or equal to the value of 
  2740. ios::x_precision. Otherwise, floating-point values are converted to fixed 
  2741. notation. If ios::showpoint is not set, trailing zeros are removed from the 
  2742. result and a decimal point appears only if it is followed by a digit. 
  2743. ios::scientific and ios::fixed are collectively identified by the static member 
  2744. ios::floatfield. 
  2745.  
  2746.  
  2747. ΓòÉΓòÉΓòÉ 4.3.4.5. Uppercase and Lowercase ΓòÉΓòÉΓòÉ
  2748.  
  2749. :link auto dependent reftype=hd refid=iosuppr. 
  2750.  
  2751. The following enumeration member determines whether alphabetic characters used 
  2752. in floating-point numbers appear in upper- or lowercase: 
  2753.  
  2754.  
  2755. ΓòÉΓòÉΓòÉ 4.3.4.5.1. uppercase ΓòÉΓòÉΓòÉ
  2756.  
  2757. If ios::uppercase is set, the operation that inserts values uses an uppercase 
  2758. "E" for floating-point values in scientific notation. In addition, the 
  2759. operation that inserts values stores hexadecimal digits "A" to "F" in uppercase 
  2760. and places an uppercase "X" before hexadecimal values when ios::showbase is 
  2761. set. If ios::uppercase is not set, a lowercase "e" introduces the exponent in 
  2762. floating-point values, hexadecimal digits "a" to "f" are stored in lowercase, 
  2763. and a lowercase "x" is inserted before hexadecimal values when ios::showbase is 
  2764. set. 
  2765.  
  2766. The setting of uppercase also determines whether special numbers such as inf or 
  2767. infinity are inserted in uppercase. 
  2768.  
  2769.  
  2770. ΓòÉΓòÉΓòÉ 4.3.4.6. Buffer Flushing ΓòÉΓòÉΓòÉ
  2771.  
  2772. :link auto dependent reftype=hd refid=iosunbf . 
  2773.  
  2774. The following enumeration members affect buffer flushing behavior: 
  2775.  
  2776.  
  2777. ΓòÉΓòÉΓòÉ 4.3.4.6.1. unitbuf ΓòÉΓòÉΓòÉ
  2778.  
  2779. If ios::unitbuf is set, ostream::osfx() performs a flush after each insertion. 
  2780. The attached stream buffer is unit buffered. ios::unitbuf is not set by 
  2781. default. 
  2782.  
  2783.  
  2784. ΓòÉΓòÉΓòÉ 4.3.4.6.2. stdio ΓòÉΓòÉΓòÉ
  2785.  
  2786. This flag is used internally by sync_with_stdio(). Do not use ios::stdio 
  2787. directly. If you want to combine I/O Stream Library input and output with 
  2788. stdio.h input and output, use sync_with_stdio(). See sync_with_stdio for more 
  2789. details on sync_with_stdio(). ios::stdio is not set by default. 
  2790.  
  2791.  
  2792. ΓòÉΓòÉΓòÉ 4.3.4.7. Mutually Exclusive Format Flags ΓòÉΓòÉΓòÉ
  2793.  
  2794. If you specify conflicting flags, the results are unpredictable. For example, 
  2795. the results will be unpredictable if you set both ios::left and ios::right in 
  2796. the format state of iosobj. Set only one flag in each set of the following 
  2797. three sets: 
  2798.  
  2799.      ios::left, ios::right, ios::internal 
  2800.      ios::dec, ios::oct, ios::hex 
  2801.      ios::scientific, ios::fixed 
  2802.  
  2803.  
  2804. ΓòÉΓòÉΓòÉ 4.3.5. Public Members of ios for the Format State ΓòÉΓòÉΓòÉ
  2805.  
  2806. You can use the member functions listed below to control the format state of an 
  2807. ios object. 
  2808.  
  2809. Note:  The following descriptions assume that the functions are called as part 
  2810. of an ios object called iosobj. 
  2811.  
  2812. The following functions are described: 
  2813.  
  2814.      fill - Set the fill character 
  2815.      flags - Set format flags 
  2816.      precision - Set the precision 
  2817.      setf - Set specific format flags 
  2818.      skip - Set ios::skipws format flag 
  2819.      unsetf - Turn off format flags 
  2820.      width - Set field width 
  2821.  
  2822.  
  2823. ΓòÉΓòÉΓòÉ 4.3.5.1. fill ΓòÉΓòÉΓòÉ
  2824.  
  2825. char fill() const;
  2826. char fill(char fillchar);
  2827.  
  2828. fill() with no arguments returns the value of ios::x_fill in the format state 
  2829. of iosobj. fill() with an argument fillchar sets ios::x_fill to be equal to 
  2830. fillchar.  It returns the value of ios::x_fill. 
  2831.  
  2832. ios::x_fill is the character used as padding if the field is wider than the 
  2833. representation of a value. The default value for ios::x_fill is a space. The 
  2834. ios::left, ios::right, and ios::internal flags determine the position of the 
  2835. fill character. 
  2836.  
  2837. You can also use the parameterized manipulator setfill to set the value of 
  2838. ios::x_fill. 
  2839.  
  2840.  
  2841. ΓòÉΓòÉΓòÉ 4.3.5.2. flags ΓòÉΓòÉΓòÉ
  2842.  
  2843. long flags() const;
  2844. long flags(long flagset);
  2845.  
  2846. flags() with no arguments returns the value of the flags that make up the 
  2847. current format state. flags() with one argument sets the flags in the format 
  2848. state to the settings specified in flagset and returns the value of the 
  2849. previous settings of the format flags. 
  2850.  
  2851.  
  2852. ΓòÉΓòÉΓòÉ 4.3.5.3. precision ΓòÉΓòÉΓòÉ
  2853.  
  2854. int precision() const;
  2855. int precision(int prec);
  2856.  
  2857. precision() with no arguments returns the value of ios::x_precision. 
  2858. precision() with one argument sets the value of ios::x_precision to prec and 
  2859. returns the previous value. The value of prec must be greater than 0. If the 
  2860. value is nonpositive, the value of ios::x_precision is set to the default 
  2861. value, 6. ios::x_precision controls the number of significant digits when 
  2862. floating-point values are inserted. 
  2863.  
  2864. The format state in effect when precision() is called affects the behavior of 
  2865. precision(). If neither ios::scientific nor ios::fixed is set, ios::x_precision 
  2866. specifies the number of significant digits in the floating-point value that is 
  2867. being inserted. If, in addition, ios::showpoint is not set, all trailing zeros 
  2868. are removed and a decimal point only appears if it is followed by digits. 
  2869.  
  2870. If either ios::scientific or ios::fixed is set, ios::x_precision specifies the 
  2871. number of digits following the decimal point. 
  2872.  
  2873. You can also use the parameterized manipulator setprecision to set 
  2874. ios::x_precision. 
  2875.  
  2876.  
  2877. ΓòÉΓòÉΓòÉ 4.3.5.4. setf ΓòÉΓòÉΓòÉ
  2878.  
  2879. long setf(long newset);
  2880. long setf(long newset, long field);
  2881.  
  2882. setf() with one argument is accumulative. It sets the format flags that are 
  2883. marked in newset, without affecting flags that are not marked in newset, and 
  2884. returns the previous value of the format state. You can also use the 
  2885. parameterized manipulator setiosflags to set the format flags to a specific 
  2886. setting. 
  2887.  
  2888. setf() with two arguments clears the format flags specified in field, sets the 
  2889. format flags specified in newset, and returns the previous value of the format 
  2890. state. For example, to change the conversion base in the format state to 
  2891. ios::hex, you could use a statement like this: 
  2892.  
  2893. s.setf(ios::hex, ios::basefield);
  2894.  
  2895. In this statement, ios::basefield specifies the conversion base as the format 
  2896. flag that is going to be changed, and ios::hex specifies the new value for the 
  2897. conversion base. If newset equals 0, all of the format flags specified in field 
  2898. are cleared. You can also use the parameterized manipulator resetiosflags to 
  2899. clear format flags. 
  2900.  
  2901. Note:  If you set conflicting flags the results are unpredictable. 
  2902.  
  2903.  
  2904. ΓòÉΓòÉΓòÉ 4.3.5.5. skip ΓòÉΓòÉΓòÉ
  2905.  
  2906. int skip(int i);
  2907.  
  2908. skip() sets the format flag ios::skipws if the value of the argument i does not 
  2909. equal 0. If i does equal 0, ios::skipws is cleared. skip() returns a value of 1 
  2910. if ios::skipws was set prior to the call to skip(), and returns 0 otherwise. 
  2911.  
  2912.  
  2913. ΓòÉΓòÉΓòÉ 4.3.5.6. unsetf ΓòÉΓòÉΓòÉ
  2914.  
  2915. long unsetf(long oflags);
  2916.  
  2917. unsetf() turns off the format flags specified in oflags and returns the 
  2918. previous format state. 
  2919.  
  2920.  
  2921. ΓòÉΓòÉΓòÉ 4.3.5.7. width ΓòÉΓòÉΓòÉ
  2922.  
  2923. int width() const;
  2924. int width(int fwidth);
  2925.  
  2926. width() with no arguments returns the value of the current setting of the 
  2927. format state field width variable, ios::x_width. If the value of ios::x_width 
  2928. is smaller than the space needed for the representation of the value, the full 
  2929. value is still inserted. 
  2930.  
  2931. width() with one argument, fwidth, sets ios::x_width to the value of fwidth and 
  2932. returns the previous value. The default field width is 0. When the value of 
  2933. ios::x_width is 0, the operations that insert values only insert the characters 
  2934. needed to represent a value. 
  2935.  
  2936. If the value of ios::x_width is greater than 0, the characters needed to 
  2937. represent the value are inserted. Then fill characters are inserted, if 
  2938. necessary, so that the representation of the value takes up the entire field. 
  2939. ios::x_width only specifies a minimum width, not a maximum width. If the number 
  2940. of characters needed to represent a value is greater than the field width, none 
  2941. of the characters is truncated. After every insertion of a value of a numeric 
  2942. or string type (including char*, unsigned char*, signed char*, and wchar_t*, 
  2943. but excluding char, unsigned char, signed char, and wchar_t), the value of 
  2944. ios::x_width is reset to 0. After every extraction of a value of type char*, 
  2945. unsigned char*, signed char*, or wchar_t*, the value of ios::x_width is reset 
  2946. to 0. 
  2947.  
  2948. You can also use the parameterized manipulator setw to set the field width. 
  2949.  
  2950.  
  2951. ΓòÉΓòÉΓòÉ 4.3.6. Public Members of ios for User-Defined Format Flags ΓòÉΓòÉΓòÉ
  2952.  
  2953. In addition to the flags described in Format State Flags, you can also use the 
  2954. ios member functions listed in this section to define additional format flags 
  2955. or variables in classes that you derive from ios. 
  2956.  
  2957. The following member functions are described: 
  2958.  
  2959.      bitalloc - Create bit set 
  2960.      iword - Return reference to user-defined flag 
  2961.      pword - Return reference to user-defined flag 
  2962.      xalloc - Return index to format state variables. 
  2963.  
  2964.  
  2965. ΓòÉΓòÉΓòÉ 4.3.6.1. bitalloc ΓòÉΓòÉΓòÉ
  2966.  
  2967. static long bitalloc();
  2968.  
  2969. bitalloc() is a static function that returns a long value with a previously 
  2970. unallocated bit set. You can use this long value as an additional flag, and 
  2971. pass it as an argument to the format state member functions. When all the bits 
  2972. are exhausted, bitalloc() returns 0. 
  2973.  
  2974.  
  2975. ΓòÉΓòÉΓòÉ 4.3.6.2. iword ΓòÉΓòÉΓòÉ
  2976.  
  2977. long& iword(int i);
  2978.  
  2979. iword() returns a reference to the ith user-defined flag, where i is an index 
  2980. returned by xalloc(). iword() allocates space for the user-defined flag. If the 
  2981. allocation fails, iword() sets ios::failbit. 
  2982.  
  2983.  
  2984. ΓòÉΓòÉΓòÉ 4.3.6.3. pword ΓòÉΓòÉΓòÉ
  2985.  
  2986. void* & pword(int i);
  2987.  
  2988. pword() returns a reference to a pointer to the ith user-defined flag, where i 
  2989. is an index returned by xalloc(). pword() allocates space for the user-defined 
  2990. flag. If the allocation fails, pword() sets ios::failbit. pword() is the same 
  2991. as iword(), except that the two functions return different types. 
  2992.  
  2993.  
  2994. ΓòÉΓòÉΓòÉ 4.3.6.4. xalloc ΓòÉΓòÉΓòÉ
  2995.  
  2996. static int xalloc();
  2997.  
  2998. xalloc() is a static function that returns an unused index into an array of 
  2999. words available for use as format state variables by classes derived from ios. 
  3000.  
  3001. xalloc() simply returns a new index; it does not do any allocation.  iword() 
  3002. and pword() do the allocation, and if the allocation fails, they set 
  3003. ios::failbit. You should check ios::failbit after calling iword() or pword(). 
  3004.  
  3005.  
  3006. ΓòÉΓòÉΓòÉ 4.3.7. Public Members of ios for the Error State ΓòÉΓòÉΓòÉ
  3007.  
  3008. The error state is an enumeration that records the errors that take place in 
  3009. the processing of ios objects. It has the following declaration: 
  3010.  
  3011. enum io_state { goodbit, eofbit, failbit, badbit, hardfail };
  3012.  
  3013. The error state is manipulated using the ios member functions described in this 
  3014. section. 
  3015.  
  3016. Note: 
  3017.  
  3018.    1. hardfail is a flag used internally by the I/O Stream Library. Do not use 
  3019.       it. 
  3020.  
  3021.    2. The following descriptions assume that the functions are called as part 
  3022.       of an ios object called iosobj. 
  3023.  
  3024.  The following member functions are described: 
  3025.  
  3026.      bad - Check ios::badbit 
  3027.      clear - Clear or Set Error State 
  3028.      eof - Check ios::eofbit 
  3029.      fail - Check ios::failbit and ios::badbit 
  3030.      good - Are Any Bits Set 
  3031.      rdstate - Return Error State 
  3032.      Convert ios Object to Pointer Operator void*() 
  3033.      Check ios::failbit and ios::badbit Operator ! 
  3034.  
  3035.  
  3036. ΓòÉΓòÉΓòÉ 4.3.7.1. bad ΓòÉΓòÉΓòÉ
  3037.  
  3038. int bad() const;
  3039.  
  3040. bad() returns a nonzero value if ios::badbit is set in the error state of 
  3041. iosobj. Otherwise, it returns 0. ios::badbit is usually set when some operation 
  3042. on the streambuf object that is associated with the ios object has failed. It 
  3043. will probably not be possible to continue input and output operations on the 
  3044. ios object. 
  3045.  
  3046.  
  3047. ΓòÉΓòÉΓòÉ 4.3.7.2. clear ΓòÉΓòÉΓòÉ
  3048.  
  3049. void clear(int state=0);
  3050.  
  3051. clear() changes the error state of iosobj to state. If state equals 0 (its 
  3052. default), all of the bits in the error state are cleared. If you want to set 
  3053. one of the bits without clearing or setting the other bits in the error state, 
  3054. you can perform a bitwise OR between the bit you want to set and the current 
  3055. error state. For example, the following statement sets ios::badbit in iosobj 
  3056. and leaves all the other error state bits unchanged: 
  3057.  
  3058.    iosobj.clear(ios::badbit|iosobj.rdstate());
  3059.  
  3060.  
  3061. ΓòÉΓòÉΓòÉ 4.3.7.3. eof ΓòÉΓòÉΓòÉ
  3062.  
  3063. int eof() const;
  3064.  
  3065. eof() returns a nonzero value if ios::eofbit is set in the error state of 
  3066. iosobj. Otherwise, it returns 0. ios::eofbit is usually set when an EOF has 
  3067. been encountered during an extraction operation. 
  3068.  
  3069.  
  3070. ΓòÉΓòÉΓòÉ 4.3.7.4. fail ΓòÉΓòÉΓòÉ
  3071.  
  3072. int fail() const;
  3073.  
  3074. fail() returns a nonzero value if either ios::badbit or ios::failbit is set in 
  3075. the error state. Otherwise, it returns 0. 
  3076.  
  3077.  
  3078. ΓòÉΓòÉΓòÉ 4.3.7.5. good ΓòÉΓòÉΓòÉ
  3079.  
  3080. int good() const;
  3081.  
  3082. good() returns a nonzero value if no bits are set in the error state of iosobj. 
  3083. Otherwise, it returns 0. 
  3084.  
  3085.  
  3086. ΓòÉΓòÉΓòÉ 4.3.7.6. rdstate ΓòÉΓòÉΓòÉ
  3087.  
  3088. int rdstate() const;
  3089.  
  3090. rdstate() returns the current value of the error state of iosobj. 
  3091.  
  3092.  
  3093. ΓòÉΓòÉΓòÉ 4.3.7.7. operator void* ΓòÉΓòÉΓòÉ
  3094.  
  3095. operator void*();
  3096. operator const void*() const;
  3097.  
  3098. The void* operator converts iosobj to a pointer so that it can be compared to 
  3099. 0. The conversion returns 0 if ios::failbit or ios::badbit is set in the error 
  3100. state of iosobj. Otherwise, a pointer value is returned. This value is not 
  3101. meant to be manipulated as a pointer; the purpose of the operator is to allow 
  3102. you to write statements such as the following: 
  3103.  
  3104. if (cin)
  3105.      cout << "ios::badbit and ios::failbit are not set" << endl;
  3106. if (cin >> x)
  3107.      cout << "ios::badbit and ios::failbit are not set "
  3108.           << x << " was input" << endl;
  3109.  
  3110.  
  3111. ΓòÉΓòÉΓòÉ 4.3.7.8. operator! ΓòÉΓòÉΓòÉ
  3112.  
  3113. int operator!() const;
  3114.  
  3115. The ! operator returns a nonzero value if ios::failbit or ios::badbit is set in 
  3116. the error state of iosobj. You can use this operator to write statements like 
  3117. the following: 
  3118.  
  3119.    if (!cin)
  3120.       cout << "either ios::failbit or ios::badbit is set" << endl;
  3121.    else
  3122.       cout << "neither ios::failbit nor ios::badbit is set"
  3123.            << endl;
  3124.  
  3125.  
  3126. ΓòÉΓòÉΓòÉ 4.3.8. Other Members of ios ΓòÉΓòÉΓòÉ
  3127.  
  3128. This section describes the ios member functions that do not deal with the error 
  3129. state or the format state. These descriptions assume that the functions are 
  3130. called as part of an ios object called iosobj. 
  3131.  
  3132. The following functions are described: 
  3133.  
  3134.      rdbuf - Return pointer to associated streambuf object 
  3135.      sync_with_stdio - Attach stdiobuf object to predefined streams 
  3136.      tie - Set the tie variable 
  3137.  
  3138.  
  3139. ΓòÉΓòÉΓòÉ 4.3.8.1. rdbuf ΓòÉΓòÉΓòÉ
  3140.  
  3141. streambuf* rdbuf();
  3142.  
  3143. rdbuf() returns a pointer to the streambuf object that is associated with 
  3144. iosobj. This is the streambuf object that was passed as an argument to the ios 
  3145. constructor. 
  3146.  
  3147.  
  3148. ΓòÉΓòÉΓòÉ 4.3.8.2. sync_with_stdio ΓòÉΓòÉΓòÉ
  3149.  
  3150. static void sync_with_stdio();
  3151.  
  3152. sync_with_stdio() is a static function that solves the problems that occur when 
  3153. you call functions declared in stdio.h and I/O Stream Library functions in the 
  3154. same program. The first time that you call sync_with_stdio(), it attaches 
  3155. stdiobuf objects to the predefined streams cin, cout, and cerr. After that, 
  3156. input and output using these predefined streams can be mixed with input and 
  3157. output using the corresponding FILE objects (stdin, stdout, and stderr). This 
  3158. input and output are correctly synchronized. 
  3159.  
  3160. If you switch between the I/O Stream Library formatted extraction functions and 
  3161. stdio.h functions, you may find that a byte is "lost". The reason is that the 
  3162. formatted extraction functions for integers and floating-point values keep 
  3163. extracting characters until a nondigit character is encountered. This nondigit 
  3164. character acts as a delimiter for the value that preceded it.  Because it is 
  3165. not part of the value, putback() is called to return it to the stream buffer. 
  3166. If a C stdio library function, such as getchar(), performs the next input 
  3167. operation, it will begin input at the character after this nondigit character. 
  3168. Thus, this nondigit character is not part of the value extracted by the 
  3169. formatted extraction function, and it is not the character extracted by the C 
  3170. stdio library function. It is "lost". Therefore, you should avoid switching 
  3171. between the I/O Stream Library formatted extraction functions and C stdio 
  3172. library functions whenever possible. 
  3173.  
  3174. sync_with_stdio() makes cout and clog unit buffered. After you call 
  3175. sync_with_stdio(), the performance of your program could diminish. The 
  3176. performance of your program depends on the length of strings, with performance 
  3177. diminishing most when the strings are shortest. 
  3178.  
  3179. Note:  You should use I/O Stream Library functions exclusively for all new 
  3180. code. 
  3181.  
  3182.  
  3183. ΓòÉΓòÉΓòÉ 4.3.8.3. tie ΓòÉΓòÉΓòÉ
  3184.  
  3185. ostream* tie();
  3186. ostream* tie(ostream* os);
  3187.  
  3188. There are two versions of tie(). The version that takes no arguments returns 
  3189. the value of ios::x_tie, the tie variable. (The tie variable points to the 
  3190. ostream object that is tied to the ios object.) The version that takes one 
  3191. argument os makes the tie variable, ios::x_tie, equal to os and returns the 
  3192. previous value. 
  3193.  
  3194. You can use ios::x_tie to automatically flush the stream buffer attached to an 
  3195. ios object. If ios::x_tie for an ios object is not equal to 0 and the ios 
  3196. object needs more characters or has characters to be consumed, the ostream 
  3197. object pointed to by ios::x_tie is flushed. 
  3198.  
  3199. By default, the tie variables of the predefined streams cin, cerr, and clog all 
  3200. point to the predefined stream cout. The following example illustrates how 
  3201. these streams are tied: 
  3202.  
  3203. // Tying two streams together
  3204.    #include <iostream.h>
  3205.    #include <fstream.h>
  3206.  
  3207.    void main() {
  3208.       float f;
  3209.  
  3210.       cout << "Enter a number: ";         // cin is tied to cout, so
  3211.       cin >> f;                           // cout is flushed before input
  3212.       cout << "The number was " << f << ".\n" << endl;
  3213.  
  3214.       ofstream myFile;
  3215.       myFile.open("testfile",ios::out);
  3216.       cin.tie(&myFile);                   // now tie cin to a different ostream
  3217.  
  3218.       cout << "Enter a number: ";         // cout is not flushed by cin,
  3219.       cin >> f;                           // so prompt appears after input.
  3220.       cout << "The number was " << f << ".\n" << endl;
  3221.    }
  3222.  
  3223. Initially, the program displays a prompt, requests input, and then displays 
  3224. output. After cin is tied to the ofstream myFile, however, the output is not 
  3225. flushed by the request for input, so no prompt is displayed until after the 
  3226. input is received.  The output is flushed only by the endl manipulator at the 
  3227. end of the program. The following shows sample output for this program: 
  3228.  
  3229. Enter a number: 5
  3230. The number was 5.
  3231.  
  3232. 6
  3233. Enter a number: The number was 6.
  3234.  
  3235.  
  3236. ΓòÉΓòÉΓòÉ 4.3.9. Built-In Manipulators for ios ΓòÉΓòÉΓòÉ
  3237.  
  3238. The I/O Stream Library provides you with a set of built-in manipulators for ios 
  3239. and the classes derived from it. These manipulators have a specific effect on a 
  3240. stream other than inserting or extracting a value. Manipulators implicitly 
  3241. invoke functions that modify the state of the stream, and they allow you to 
  3242. modify the state of a stream at the same time as you are doing input and 
  3243. output. The syntax for manipulators is consistent with the syntax for input and 
  3244. output. 
  3245.  
  3246. The following is a list of the manipulators and the classes that they apply to: 
  3247.  
  3248.  dec       istream and ostream 
  3249.  hex       istream and ostream 
  3250.  oct       istream and ostream 
  3251.  ws        istream 
  3252.  endl      ostream 
  3253.  ends      ostream 
  3254.  flush     ostream 
  3255.  
  3256.  See Built-In Manipulators for istream for more details on the built-in 
  3257.  manipulators for istream. See Built-In Manipulators for ostream for more 
  3258.  details on the manipulators for ostream. 
  3259.  
  3260.  
  3261. ΓòÉΓòÉΓòÉ 4.4. iostream and iostream_withassign Classes ΓòÉΓòÉΓòÉ
  3262.  
  3263. Description 
  3264.  
  3265. Derivation 
  3266.  
  3267. Header File 
  3268.  
  3269. To close all the panels in a chapter, double-click on this panel's system menu. 
  3270.  
  3271.  
  3272. ΓòÉΓòÉΓòÉ 4.4.1. Class Description - iostream ΓòÉΓòÉΓòÉ
  3273.  
  3274. The iostream class combines the input capabilities of the istream class with 
  3275. the output capabilities of the ostream class.  It is the base class for three 
  3276. other classes that also provide both input and output capabilities: 
  3277.  
  3278.      iostream_withassign, also described in this chapter, which you can use to 
  3279.       assign another stream (such as an fstream for a file) to an iostream 
  3280.       object. 
  3281.      strstream, which is a stream of characters stored in memory. 
  3282.      fstream, which is a stream that supports input and output. 
  3283.  
  3284.  
  3285. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  3286.  
  3287. ios 
  3288.  
  3289.    istream
  3290.    ostream
  3291.      iostream
  3292.         iostream_withassign
  3293.  
  3294.  
  3295. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  3296.  
  3297. iostream and iostream_withassign are declared in iostream.h. 
  3298.  
  3299.  
  3300. ΓòÉΓòÉΓòÉ 4.4.2. Public Members of iostream and iostream_withassign ΓòÉΓòÉΓòÉ
  3301.  
  3302. The following public member functions are described: 
  3303.  
  3304.      iostream constructor 
  3305.      iostream_withassign constructor 
  3306.      iostream_withassign assignment operator 
  3307.  
  3308.  
  3309. ΓòÉΓòÉΓòÉ 4.4.2.1. Constructor for iostream ΓòÉΓòÉΓòÉ
  3310.  
  3311. iostream(streambuf* sb);
  3312.  
  3313. The iostream constructor takes a single argument sb. The constructor creates an 
  3314. iostream object that is attached to the streambuf object that is pointed to by 
  3315. sb. The constructor also initializes the format variables to their defaults. 
  3316.  
  3317.  
  3318. ΓòÉΓòÉΓòÉ 4.4.2.2. Constructor for iostream_withassign ΓòÉΓòÉΓòÉ
  3319.  
  3320. iostream_withassign();
  3321.  
  3322. The iostream_withassign constructor creates an iostream_withassign object. It 
  3323. does not do any initialization of this object. 
  3324.  
  3325.  
  3326. ΓòÉΓòÉΓòÉ 4.4.2.3. Assignment Operator for iostream_withassign ΓòÉΓòÉΓòÉ
  3327.  
  3328. iostream_withassign& operator=(ios& is);
  3329. iostream_withassign& operator=(streambuf* sb);
  3330.  
  3331. There are two versions of the iostream_withassign assignment operator. The 
  3332. first version takes a reference to an ios object, is, as its argument. It 
  3333. associates the stream buffer attached to is with the iostream_withassign object 
  3334. that is on the left side of the assignment operator. 
  3335.  
  3336. The second version of the iostream_withassign assignment operator takes a 
  3337. pointer to a streambuf object, sb, as its argument. It associates this 
  3338. streambuf object with the iostream_withassign object that is on the left side 
  3339. of the assignment operator. 
  3340.  
  3341.  
  3342. ΓòÉΓòÉΓòÉ 4.5. istream and istream_withassign Classes ΓòÉΓòÉΓòÉ
  3343.  
  3344. Description 
  3345.  
  3346. Derivation 
  3347.  
  3348. Header File 
  3349.  
  3350. Constructors 
  3351.  
  3352. Members 
  3353.  
  3354. To close all the panels in a chapter, double-click on this panel's system menu. 
  3355.  
  3356.  
  3357. ΓòÉΓòÉΓòÉ 4.5.1. Class Description - istream ΓòÉΓòÉΓòÉ
  3358.  
  3359. This chapter describes the istream class and its derived class 
  3360. istream_withassign. You can use the istream member functions to take characters 
  3361. out of the stream buffer that is associated with an istream object. 
  3362. istream_withassign is derived from istream and includes an assignment operator. 
  3363.  
  3364. You can view the topics in this chapter either through the panel on the left, 
  3365. or by selecting from among the following: 
  3366.  
  3367.      Input prefix function 
  3368.      istream members for formatted input 
  3369.      istream members for unformatted input 
  3370.      istream members for positioning 
  3371.      Other public members 
  3372.      Built-in manipulators 
  3373.      istream_withassign class 
  3374.  
  3375.  
  3376. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  3377.  
  3378. ios 
  3379.  
  3380.    istream
  3381.      istream_withassign
  3382.  
  3383.  
  3384. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  3385.  
  3386. istream and istream_withassign are declared in iostream.h. 
  3387.  
  3388.  
  3389. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  3390.  
  3391. The following members are provided for istream and istream_withassign: 
  3392.  
  3393.      Input Prefix Function 
  3394.      Constructors for istream 
  3395.      Public Members of istream for Formatted Input 
  3396.      get 
  3397.      getline 
  3398.      ignore 
  3399.      read 
  3400.      seekg 
  3401.      tellg 
  3402.      gcount 
  3403.      peek 
  3404.      putback 
  3405.      sync 
  3406.      Constructor for istream_withassign 
  3407.      Assignment Operator for istream_withassign 
  3408.  
  3409.  
  3410. ΓòÉΓòÉΓòÉ 4.5.2. Constructors for istream ΓòÉΓòÉΓòÉ
  3411.  
  3412. istream(streambuf* sb);
  3413.  
  3414. The istream constructor takes a single argument sb. The constructor creates an 
  3415. istream object that is attached to the streambuf object that is pointed to by 
  3416. sb. The constructor also initializes the format variables to their defaults. 
  3417.  
  3418. The other istream constructor declarations in iostream.h are obsolete; do not 
  3419. use them. 
  3420.  
  3421.  
  3422. ΓòÉΓòÉΓòÉ 4.5.3. Input Prefix Function ΓòÉΓòÉΓòÉ
  3423.  
  3424. int ipfx(int need=0);
  3425.  
  3426. ipfx() checks the stream buffer attached to an istream object to determine if 
  3427. it is capable of satisfying requests for characters. It returns a nonzero value 
  3428. if the stream buffer is ready, and 0 if it is not. 
  3429.  
  3430. The formatted input operator calls ipfx(0), while the unformatted input 
  3431. functions call ipfx(1). 
  3432.  
  3433. If the error state of the istream object is nonzero, ipfx() returns 0. 
  3434. Otherwise, the stream buffer attached to the istream object is flushed if 
  3435. either of the following conditions is true: 
  3436.  
  3437.      need has a value of 0. 
  3438.      The number of characters available in the stream buffer is fewer than the 
  3439.       value of need. 
  3440.  
  3441.  If ios::skipws is set in the format state of the istream object and need has a 
  3442.  value of 0, leading white-space characters are extracted from the stream 
  3443.  buffer and discarded. If ios::hardfail is set or EOF is encountered, ipfx() 
  3444.  returns 0. Otherwise, it returns a nonzero value. 
  3445.  
  3446.  
  3447. ΓòÉΓòÉΓòÉ 4.5.4. Public Members of istream for Formatted Input ΓòÉΓòÉΓòÉ
  3448.  
  3449. You can use the istream class to perform formatted input from a stream buffer 
  3450. using the input operator >>. Consider the following statement, where ins is a 
  3451. reference to an istream object and x is a variable of a built-in type: 
  3452.  
  3453.    ins >> x;
  3454.  
  3455. The input operator >> calls ipfx(0). If ipfx() returns a nonzero value, the 
  3456. input operator extracts characters from the streambuf object that is associated 
  3457. with ins. It converts these characters to the type of x and stores the result 
  3458. in x. The input operator sets ios::failbit if the characters extracted from the 
  3459. stream buffer cannot be converted to the type of x. If the attempt to extract 
  3460. characters fails because EOF is encountered, the input operator sets 
  3461. ios::eofbit and ios::failbit. If the attempt to extract characters fails for 
  3462. another reason, the input operator sets ios::badbit. Even if an error occurs, 
  3463. the input operator always returns ins. 
  3464.  
  3465. The details of conversion depend on the format state of the istream object and 
  3466. the type of the variable x. The input operator may set the width variable 
  3467. ios::x_width to 0, but it does not change anything else in the format state. 
  3468.  
  3469. The input operator is defined for the following types: 
  3470.  
  3471.      Arrays of character values (including signed char and unsigned char) 
  3472.      Other integral values: short, int, long 
  3473.      float, double, and long double values. 
  3474.  
  3475.  In addition, the input operator is defined for streambuf objects. 
  3476.  
  3477.  You can also define input operators for your own types. 
  3478.  
  3479.  The following sections describe the input operator for these types. 
  3480.  
  3481.  Note:  The following descriptions assume that the input operator is called 
  3482.  with the istream object ins on the left side of the operator. 
  3483.  
  3484.  
  3485. ΓòÉΓòÉΓòÉ 4.5.4.1. Input Operator for Arrays of Characters ΓòÉΓòÉΓòÉ
  3486.  
  3487. istream& operator>>(char* pc);
  3488. istream& operator>>(signed char* pc);
  3489. istream& operator>>(unsigned char* pc);
  3490. istream& operator>>(wchar_t* pwc);
  3491.  
  3492. For pointers to char, signed char, and unsigned char, the input operator stores 
  3493. characters from the stream buffer attached to ins in the array pointed to by 
  3494. pc. The input operator stores characters until a white-space character is 
  3495. found. This white-space character is left in the stream buffer, and the 
  3496. extraction stops. If ios::x_width does not equal zero, a maximum of 
  3497. ios::x_width - 1 characters are extracted. The input operator calls 
  3498. ins.width(0) to reset ios::x_width to 0. 
  3499.  
  3500. For pointers to wchar_t, the input operator stores characters from the stream 
  3501. buffer attached to ins in the array pointed to by pwc. The input operator 
  3502. stores characters until a white-space character or a wchar_t blank is found. If 
  3503. the terminating character is a white-space character, it is left in the stream 
  3504. buffer. If it is a wchar_t blank, it is discarded to avoid returning two bytes 
  3505. to the input stream. 
  3506.  
  3507. For wchar_t* arrays, if ios::width does not equal zero, a maximum of 
  3508. ios::width-1 characters (at 2 bytes each) are extracted. A 2-character space is 
  3509. reserved for the wchar_t terminating null character. 
  3510.  
  3511. Note:  The input operators for these types also reset ios::x_width to 0. None 
  3512. of the other input operators affects ios::x_width. All of the output operators 
  3513. except those for the char types and wchar_t, on the other hand, reset 
  3514. ios::x_width to 0. 
  3515.  
  3516. The input operator always stores a terminating null character in the array 
  3517. pointed to by pc or pwc, even if an error occurs. For arrays of wchar_t*, this 
  3518. terminating null character is a wchar_t terminating null character. 
  3519.  
  3520.  
  3521. ΓòÉΓòÉΓòÉ 4.5.4.2. Input Operator for char ΓòÉΓòÉΓòÉ
  3522.  
  3523. istream& operator>>(char& rc);
  3524. istream& operator>>(signed char& rc);
  3525. istream& operator>>(unsigned char& rc);
  3526. istream& operator>>(wchar_t& rc);
  3527.  
  3528. For char, signed char, and unsigned char, the input operator extracts a 
  3529. character from the stream buffer attached to ins and stores it in rc. 
  3530.  
  3531. For references to wchar_t, the input operator extracts a wchar_t character from 
  3532. the stream buffer and stores it in wc. If ios::skipws is set, the input 
  3533. operator skips leading wchar_t spaces as well as leading char white spaces. 
  3534.  
  3535.  
  3536. ΓòÉΓòÉΓòÉ 4.5.4.3. Input Operator for Other Integral Values ΓòÉΓòÉΓòÉ
  3537.  
  3538. istream& operator>>(short& ir);
  3539. istream& operator>>(unsigned short& ir);
  3540. istream& operator>>(int& ir);
  3541. istream& operator>>(unsigned int& ir);
  3542. istream& operator>>(long& ir);
  3543. istream& operator>>(unsigned long& ir);
  3544.  
  3545. This section describes how the input operator works for references to the 
  3546. integral types: short, unsigned short, int, unsigned int, long, and unsigned 
  3547. long. For these integral types, the input operator extracts characters from the 
  3548. stream buffer associated with ins and converts them according to the format 
  3549. state of ins. The converted characters are then stored in ir. There is no 
  3550. overflow detection on conversion of integral types. 
  3551.  
  3552. The first character extracted from the stream buffer may be a sign (+ or -). 
  3553. The subsequent characters are converted until a nondigit character is 
  3554. encountered. This nondigit character is left in the stream buffer. Which 
  3555. characters are treated as digits depends on the setting of the following format 
  3556. flags: 
  3557.  
  3558.      ios::oct: the characters are converted to an octal value. Characters are 
  3559.       extracted from the stream buffer until a character that is not an octal 
  3560.       digit (a digit from 0 to 7) is encountered. If ios::oct is set and a 
  3561.       signed value is encountered, the value is converted into a decimal value. 
  3562.       For example, if the characters "- 45" are encountered in the input stream 
  3563.       and ios::oct is set, the decimal value - 37 is actually extracted. 
  3564.  
  3565.      ios::dec: the characters are converted to a decimal value. Characters are 
  3566.       extracted from the stream buffer until a character that is not a decimal 
  3567.       digit (a digit from 0 to 9) is encountered. 
  3568.  
  3569.      ios::hex: the characters are converted to a hexadecimal value. Characters 
  3570.       are extracted from the stream buffer until a character that is not a 
  3571.       hexadecimal digit (a digit from 0 to 9 or a letter from "A" to "F", upper 
  3572.       or lower case) is encountered. If ios::hex is set and a signed value is 
  3573.       encountered, the value is converted into a decimal value. For example, if 
  3574.       the characters "-12" are encountered in the input stream and ios::hex is 
  3575.       set, the decimal value -18 is actually extracted. 
  3576.  
  3577.  If none of these format flags is set, the characters are converted according 
  3578.  to the C++ lexical conventions. This conversion depends on the characters that 
  3579.  follow the optional sign: 
  3580.  
  3581.      If these characters are "0x" or "0X", the subsequent characters are 
  3582.       converted to a hexadecimal value. 
  3583.      If the first character is "0" and the second character is not "x" or "X", 
  3584.       the subsequent characters are converted to an octal value. 
  3585.      If neither of these cases is true, the characters are converted to a 
  3586.       decimal value. 
  3587.  
  3588.  If no digits are available in the stream buffer (other than the "0" in "0X" or 
  3589.  "0x" preceding a hexadecimal value), the input operator sets ios::failbit in 
  3590.  the error state of ins. 
  3591.  
  3592.  
  3593. ΓòÉΓòÉΓòÉ 4.5.4.4. Input Operator for float and double Values ΓòÉΓòÉΓòÉ
  3594.  
  3595. istream& operator>>(float& ref);
  3596. istream& operator>>(double& ref);
  3597. istream& operator>>(long double& ref);
  3598.  
  3599. For float, double, and long double values, the input operator converts 
  3600. characters from the stream buffer attached to ins according to the C++ lexical 
  3601. conventions. 
  3602.  
  3603. The following conversions occur for certain string values: 
  3604.  
  3605.      If the value consists of the character strings "inf" or "infinity" in any 
  3606.       combination of uppercase and lowercase letters, the string is converted 
  3607.       to the appropriate type's representation of infinity. 
  3608.      If the value consists of the character string "nan" in any combination of 
  3609.       uppercase and lowercase letters, the string is converted to the 
  3610.       appropriate type's representation of a NaN. 
  3611.  
  3612.  The resulting value is stored in ref. The input operator sets ios::failbit if 
  3613.  no digits are available in the stream buffer or if the digits that are 
  3614.  available do not begin a floating-point number. 
  3615.  
  3616.  
  3617. ΓòÉΓòÉΓòÉ 4.5.4.5. Input Operator for streambuf Objects ΓòÉΓòÉΓòÉ
  3618.  
  3619. istream& operator>>(streambuf* sb);
  3620.  
  3621. For pointers to streambuf objects, the input operator calls ipfx(0). If ipfx(0) 
  3622. returns a nonzero value, the input operator extracts characters from the stream 
  3623. buffer attached to ins and inserts them in sb. Extraction stops when an EOF 
  3624. character is encountered. The input operator always returns ins. 
  3625.  
  3626.  
  3627. ΓòÉΓòÉΓòÉ 4.5.5. Public Members of istream for Unformatted Input ΓòÉΓòÉΓòÉ
  3628.  
  3629. You can use the functions listed in this section to extract characters from a 
  3630. stream buffer as a sequence of bytes. All of these functions call ipfx(1). They 
  3631. only proceed with their processing if ipfx(1) returns a nonzero value. 
  3632.  
  3633. Note:  The following descriptions assume that the functions are called as part 
  3634. of an  istream object called ins. The following functions are described: 
  3635.  
  3636.      get - Extract characters and store in array 
  3637.      get - Extract characters and store in stream buffer 
  3638.      get - Extract character and store in char 
  3639.      get - Extract character and return it 
  3640.      getline - Extract characters and store in array 
  3641.      ignore - Extract characters and discard them 
  3642.      read - Extract characters and store in array 
  3643.  
  3644.  
  3645. ΓòÉΓòÉΓòÉ 4.5.5.1. get ΓòÉΓòÉΓòÉ
  3646.  
  3647. istream& get(char* ptr, int len, char delim='\n');
  3648. istream& get(signed char* ptr, int len, char delim='\n');
  3649. istream& get(unsigned char* ptr, int len, char delim='\n');
  3650.  
  3651. get() with three arguments extracts characters from the stream buffer attached 
  3652. to ins and stores them in the byte array beginning at the location pointed to 
  3653. by ptr and extending for len bytes. The default value of the delim argument is 
  3654. '\n'. Extraction stops when either of the following conditions is true: 
  3655.  
  3656.      delim or EOF is encountered before len-1 characters have been stored in 
  3657.       the array. delim is left in the stream buffer and not stored in the 
  3658.       array. 
  3659.      len-1 characters are extracted without delim or EOF being encountered. 
  3660.  
  3661.  get() always stores a terminating null character in the array, even if it does 
  3662.  not extract any characters from the stream buffer. get() sets the ios::failbit 
  3663.  if it encounters an EOF character before it stores any characters. 
  3664.  
  3665.  
  3666. ΓòÉΓòÉΓòÉ 4.5.5.2. get ΓòÉΓòÉΓòÉ
  3667.  
  3668. istream& get(streambuf& sb, char delim='\n');
  3669.  
  3670. get() with two arguments extracts characters from the stream buffer attached to 
  3671. ins and stores them in sb. The default value of the delim argument is "\n". 
  3672. Extraction stops when any of the following conditions is true: 
  3673.  
  3674.      An EOF character is encountered. 
  3675.      An attempt to store a character in sb fails. ios::failbit is set in the 
  3676.       error state of ins. 
  3677.      delim is encountered.  delim is left in the stream buffer attached to 
  3678.       ins. 
  3679.  
  3680.  
  3681. ΓòÉΓòÉΓòÉ 4.5.5.3. get ΓòÉΓòÉΓòÉ
  3682.  
  3683. istream& get(char& cref);
  3684. istream& get(signed char& cref);
  3685. istream& get(unsigned char& cref);
  3686. istream& get(wchar_t& cref);
  3687.  
  3688. get() with a single argument extracts a single character or wchar_t from the 
  3689. stream buffer attached to ins and stores this character in cref. 
  3690.  
  3691.  
  3692. ΓòÉΓòÉΓòÉ 4.5.5.4. get ΓòÉΓòÉΓòÉ
  3693.  
  3694. int get();
  3695.  
  3696. get() with no arguments extracts a character from the stream buffer attached to 
  3697. ins and returns it. This version of get() returns EOF if EOF is extracted. 
  3698. ios::failbit is never set. 
  3699.  
  3700.  
  3701. ΓòÉΓòÉΓòÉ 4.5.5.5. getline ΓòÉΓòÉΓòÉ
  3702.  
  3703. istream& getline(char* ptr, int len, char delim='\n');
  3704. istream& getline(signed char* ptr, int len, char delim='\n');
  3705. istream& getline(unsigned char* ptr, int len, char delim='\n');
  3706.  
  3707. getline() extracts characters from the stream buffer attached to ins and stores 
  3708. them in the byte array beginning at the location pointed to by ptr and 
  3709. extending for len bytes. The default value of the delim argument is "\n". 
  3710. Extraction stops when any one of the following conditions is true: 
  3711.  
  3712.      delim or EOF is encountered before len-1 characters have been stored in 
  3713.       the array. getline() extracts delim from the stream buffer, but it does 
  3714.       not store delim in the array. 
  3715.      len-1 characters are extracted before delim or EOF is encountered. 
  3716.  
  3717.  getline() always stores a terminating null character in the array, even if it 
  3718.  does not extract any characters from the stream buffer. getline() sets the 
  3719.  ios::failbit for ins if it encounters an EOF character before it stores any 
  3720.  characters. 
  3721.  
  3722.  getline() is like get() with three arguments, except that get() does not 
  3723.  extract the delim character from the stream buffer, while getline() does. 
  3724.  
  3725.  See White Space in String Input in the Open Class Library User's Guide for an 
  3726.  example of using the getline() function. 
  3727.  
  3728.  
  3729. ΓòÉΓòÉΓòÉ 4.5.5.6. ignore ΓòÉΓòÉΓòÉ
  3730.  
  3731. istream& ignore(int num=1, int delim=EOF);
  3732.  
  3733. ignore() extracts up to num character from the stream buffer attached to ins 
  3734. and discards them.  ignore() will extract fewer than num characters if it 
  3735. encounters delim or EOF. 
  3736.  
  3737.  
  3738. ΓòÉΓòÉΓòÉ 4.5.5.7. read ΓòÉΓòÉΓòÉ
  3739.  
  3740. istream& read(char* s, int n);
  3741. istream& read(signed char* s, int n);
  3742. istream& read(unsigned char* s, int n);
  3743.  
  3744. read() extracts n characters from the stream buffer attached to ins and stores 
  3745. them in an array beginning at the position pointed to by s. If EOF is 
  3746. encountered before read() extracts n characters, read() sets the ios::failbit 
  3747. in the error state of ins. You can determine the number of characters that 
  3748. read() extracted by calling gcount() immediately after the call to read(). 
  3749.  
  3750.  
  3751. ΓòÉΓòÉΓòÉ 4.5.6. Public Members of istream for Positioning ΓòÉΓòÉΓòÉ
  3752.  
  3753. The following functions are described: 
  3754.  
  3755.      seekg - reposition get pointer of ultimate producer 
  3756.      tellg - return position of get pointer of ultimate producer 
  3757.  
  3758.  
  3759. ΓòÉΓòÉΓòÉ 4.5.6.1. seekg ΓòÉΓòÉΓòÉ
  3760.  
  3761. istream& seekg(streampos sp);
  3762. istream& seekg(streamoff so, ios::seek_dir dir);
  3763.  
  3764. seekg() repositions the get pointer of the ultimate producer. seekg() with one 
  3765. argument sets the get pointer to the position sp. seekg() with two arguments 
  3766. sets the get pointer to the position specified by dir with the offset so. dir 
  3767. can have the following values: 
  3768.  
  3769.      ios::beg: the beginning of the stream 
  3770.      ios::cur: the current position of the get pointer 
  3771.      ios::end: the end of the stream 
  3772.  
  3773.  If you attempt to set the get pointer to a position that is not valid, seekg() 
  3774.  sets ios::badbit. 
  3775.  
  3776.  
  3777. ΓòÉΓòÉΓòÉ 4.5.6.2. tellg ΓòÉΓòÉΓòÉ
  3778.  
  3779. streampos tellg();
  3780.  
  3781. tellg() returns the current position of the get pointer of the ultimate 
  3782. producer. 
  3783.  
  3784.  
  3785. ΓòÉΓòÉΓòÉ 4.5.7. Other Public Members of istream ΓòÉΓòÉΓòÉ
  3786.  
  3787. Note:  The following descriptions assume that the functions are called as part 
  3788. of an  istream object called ins. 
  3789.  
  3790. The following member functions are described: 
  3791.  
  3792.      gcount - Return number of characters extracted 
  3793.      peek - Return next character without extracting it 
  3794.      putback - Put extracted characters back into stream buffer 
  3795.      sync - Synchronize stream buffer and ultimate producer 
  3796.  
  3797.  
  3798. ΓòÉΓòÉΓòÉ 4.5.7.1. gcount ΓòÉΓòÉΓòÉ
  3799.  
  3800. int gcount();
  3801.  
  3802. gcount() returns the number of characters extracted from the stream buffer 
  3803. attached to ins by the last call to an unformatted input function. The input 
  3804. operator >> may call unformatted input functions, and thus formatted input may 
  3805. affect the value returned by gcount(). 
  3806.  
  3807.  
  3808. ΓòÉΓòÉΓòÉ 4.5.7.2. peek ΓòÉΓòÉΓòÉ
  3809.  
  3810. int peek();
  3811.  
  3812. peek() calls ipfx(1). If ipfx() returns zero, or if no more input is available 
  3813. from the ultimate producer, peek() returns EOF. Otherwise, it returns the next 
  3814. character in the stream buffer attached to ins without extracting the 
  3815. character. 
  3816.  
  3817.  
  3818. ΓòÉΓòÉΓòÉ 4.5.7.3. putback ΓòÉΓòÉΓòÉ
  3819.  
  3820. istream& putback(char c);
  3821.  
  3822. putback() attempts to put a character that was extracted from the stream buffer 
  3823. attached to ins back into the stream buffer.  c must equal the character before 
  3824. the get pointer of the stream buffer. Unless some other activity is modifying 
  3825. the stream buffer, this is the last character extracted from the stream buffer. 
  3826. If c is not equal to the character before the get pointer, the result of 
  3827. putback() is undefined, and the error state of ins may be set. putback() does 
  3828. not call ipfx(), but if the error state of ins is nonzero, putback() returns 
  3829. without putting back the character or setting the error state. 
  3830.  
  3831.  
  3832. ΓòÉΓòÉΓòÉ 4.5.7.4. sync ΓòÉΓòÉΓòÉ
  3833.  
  3834. int sync();
  3835.  
  3836. sync() establishes consistency between the ultimate producer and the stream 
  3837. buffer attached to ins. sync() calls ins.rdbuf()->sync(), which is a virtual 
  3838. function, so the details of its operation depend on the way the function is 
  3839. defined in a given derived class. If an error occurs, sync() returns EOF. 
  3840.  
  3841.  
  3842. ΓòÉΓòÉΓòÉ 4.5.8. Built-In Manipulators for istream ΓòÉΓòÉΓòÉ
  3843.  
  3844. istream&      ws(istream&);
  3845. ios&          dec(ios&);
  3846. ios&          hex(ios&);
  3847. ios&          oct(ios&);
  3848.  
  3849. The I/O Stream Library provides you with a set of built-in manipulators that 
  3850. can be used with the istream class. These manipulators have a specific effect 
  3851. on an istream object beyond extracting their own values. The built-in 
  3852. manipulators are accepted by the following versions of the input operator: 
  3853.  
  3854. istream& operator>> (istream& (*f) (istream&));
  3855. istream& operator>> (ios& (*f) (ios&));
  3856.  
  3857. If ins is a reference to an istream object, this statement extracts white-space 
  3858. characters from the stream buffer attached to ins: 
  3859.  
  3860.    ins >> ws;
  3861.  
  3862. This statement sets ios::dec: 
  3863.  
  3864.    ins >> dec;
  3865.  
  3866. This statement sets ios::hex: 
  3867.  
  3868.    ins >> hex;
  3869.  
  3870. This statement sets ios::oct: 
  3871.  
  3872.    ins >> oct;
  3873.  
  3874.  
  3875. ΓòÉΓòÉΓòÉ 4.5.9. Public Members of istream_withassign ΓòÉΓòÉΓòÉ
  3876.  
  3877. Description 
  3878.  
  3879. To close all the panels in a chapter, double-click on this panel's system menu. 
  3880.  
  3881.  
  3882. ΓòÉΓòÉΓòÉ 4.5.10. Class Description - istream_withassign ΓòÉΓòÉΓòÉ
  3883.  
  3884. There are two public member functions of istream_withassign: 
  3885.  
  3886.      istream_withassign constructor 
  3887.      istream_withassign assignment operator 
  3888.  
  3889.  
  3890. ΓòÉΓòÉΓòÉ 4.5.10.1. Constructor for istream_withassign ΓòÉΓòÉΓòÉ
  3891.  
  3892. istream_withassign();
  3893.  
  3894. The istream_withassign constructor creates an istream_withassign object. It 
  3895. does not do any initialization of this object. 
  3896.  
  3897.  
  3898. ΓòÉΓòÉΓòÉ 4.5.10.2. Assignment Operator for istream_withassign ΓòÉΓòÉΓòÉ
  3899.  
  3900. istream_withassign& operator=(istream& is);
  3901. istream_withassign& operator=(streambuf* sb);
  3902.  
  3903. There are two versions of the istream_withassign assignment operator. The first 
  3904. version takes a reference to an istream object, is, as its argument. It 
  3905. associates the stream buffer attached to is with the istream_withassign object 
  3906. that is on the left side of the assignment operator. 
  3907.  
  3908. The second version of the assignment operator takes a pointer to a streambuf 
  3909. object, sb, as its argument. It associates this streambuf object with the 
  3910. istream_withassign object that is on the left side of the assignment operator. 
  3911.  
  3912.  
  3913. ΓòÉΓòÉΓòÉ 4.6. Manipulators ΓòÉΓòÉΓòÉ
  3914.  
  3915. Description 
  3916.  
  3917. Derivation 
  3918.  
  3919. Header File 
  3920.  
  3921. Members 
  3922.  
  3923. To close all the panels in a chapter, double-click on this panel's system menu. 
  3924.  
  3925.  
  3926. ΓòÉΓòÉΓòÉ 4.6.1. Class Description - IOMANIP ΓòÉΓòÉΓòÉ
  3927.  
  3928. This chapter describes the parameterized manipulators provided by the I/O 
  3929. Stream Library and the facilities you can use to declare your own manipulators. 
  3930.  
  3931.  
  3932. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  3933.  
  3934. The manipulator classes are defined by a set of macros, and take names as 
  3935. defined when you use the macros.  See the section on manipulators in the Open 
  3936. Class Library User's Guide for further information. 
  3937.  
  3938.  
  3939. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  3940.  
  3941. The parameterized manipulator classes are declared in iomanip.h. 
  3942.  
  3943.  
  3944. ΓòÉΓòÉΓòÉ 4.6.2. Parameterized Manipulators for the Format State ΓòÉΓòÉΓòÉ
  3945.  
  3946. The iomanip.h header file also contains calls to the IOMANIPdeclare() macro for 
  3947. types int and long. These calls create classes that are used to create the 
  3948. parameterized manipulators that control the format state of ios objects. 
  3949.  
  3950. The call to IOMANIPdeclare(int) creates classes with names that are expanded 
  3951. from the following macros: 
  3952.  
  3953.      SMANIP(int) 
  3954.      SAPP(int) 
  3955.      IMANIP(int) 
  3956.      IAPP(int) 
  3957.      OMANIP(int) 
  3958.      OAPP(int) 
  3959.      IOMANIP(int) 
  3960.      IOAPP(int) 
  3961.  
  3962.  All of these macros expand to names that include the string "int". Similarly, 
  3963.  IOMANIPdeclare(long) creates eight classes whose names include the string 
  3964.  "long". 
  3965.  
  3966.  The following manipulators are declared using the classes created by the calls 
  3967.  to IOMANIPdeclare(int) and IOMANIPdeclare(long). 
  3968.  
  3969.  Note:  All of the parameterized manipulators described below are defined for 
  3970.  both istream and ostream objects. In the following descriptions, is is a 
  3971.  reference to an istream object and os is a reference to an ostream object. 
  3972.  
  3973.  The following manipulators are described: 
  3974.  
  3975.      resetiosflags - clear format flags 
  3976.      setbase - set conversion base 
  3977.      setfill - set fill character 
  3978.      setiosflags - set format flags 
  3979.      setprecision - set precision 
  3980.      setw - set field width 
  3981.  
  3982.  
  3983. ΓòÉΓòÉΓòÉ 4.6.2.1. resetiosflags ΓòÉΓòÉΓòÉ
  3984.  
  3985. SMANIP(long) resetiosflags(long flags);
  3986.  
  3987. resetiosflags() clears the format flags specified in flags. It can appear in an 
  3988. input stream: 
  3989.  
  3990.    is >> resetiosflags(flags);
  3991.  
  3992. In this case, resetiosflags() calls is.setf(0,flags). 
  3993.  
  3994. resetiosflags() can also appear in an output stream: 
  3995.  
  3996.    os << resetiosflags(flags);
  3997.  
  3998. In this case, resetiosflags calls os.setf(0,flags). 
  3999.  
  4000.  
  4001. ΓòÉΓòÉΓòÉ 4.6.2.2. setbase ΓòÉΓòÉΓòÉ
  4002.  
  4003. SMANIP(int) setbase(int base);
  4004.  
  4005. setbase() sets the conversion base to be equal to the value of the argument 
  4006. base. If base equals 10, the conversion base is set to 10. If base equals 8, 
  4007. the conversion base is set to 8. If base equals 16, the conversion base is set 
  4008. to 16. Otherwise, the conversion base is set to 0. If the conversion base is 0, 
  4009. output is treated the same as if the base were 10, but input is interpreted 
  4010. according to the C++ lexical conventions. This means that input values that 
  4011. begin with "0" are interpreted as octal values, and values that begin with "0x" 
  4012. or "0X" are interpreted as hexadecimal values. 
  4013.  
  4014.  
  4015. ΓòÉΓòÉΓòÉ 4.6.2.3. setfill ΓòÉΓòÉΓòÉ
  4016.  
  4017. SMANIP(int) setfill(int fill);
  4018.  
  4019. setfill() sets the fill character, ios::x_fill, to fill. The fill character is 
  4020. the character that appears in values that need to be padded to fill the field 
  4021. width. setfill() can appear in either an input stream or an output stream: 
  4022.  
  4023.    is >> setfill(fill);
  4024.    os << setfill(fill);
  4025.  
  4026. setfill() performs the same task as the function fill(). 
  4027.  
  4028.  
  4029. ΓòÉΓòÉΓòÉ 4.6.2.4. setiosflags ΓòÉΓòÉΓòÉ
  4030.  
  4031. SMANIP(long) setiosflags(long flags);
  4032.  
  4033. setiosflags() sets the format flags specified in flags. setiosflags() can 
  4034. appear in an input stream: 
  4035.  
  4036.    is >> setiosflags(flags);
  4037.  
  4038. If it appears in an input stream, setiosflags() calls is.setf.(flags) 
  4039.  
  4040. If it appears in an output stream, setiosflags() calls os.setf(flags): 
  4041.  
  4042.    os << setiosflags(flags);
  4043.  
  4044.  
  4045. ΓòÉΓòÉΓòÉ 4.6.2.5. setprecision ΓòÉΓòÉΓòÉ
  4046.  
  4047. SMANIP(int) setprecision(int prec);
  4048.  
  4049. setprecision() sets the precision format state variable, ios::x_prec, to the 
  4050. value of prec. The value of prec must be greater than zero. If the value of 
  4051. prec is negative, the precision format state variable is set to 6. 
  4052.  
  4053. setprecision() can appear in either an input stream or an output stream: 
  4054.  
  4055.    is >> setprecision(prec);
  4056.    os << setprecision(prec);
  4057.  
  4058.  
  4059. ΓòÉΓòÉΓòÉ 4.6.2.6. setw ΓòÉΓòÉΓòÉ
  4060.  
  4061. SMANIP(int) setw(int width);
  4062.  
  4063. setw() sets the width format state variable, ios::x_width, to the value of 
  4064. width. 
  4065.  
  4066. setw() can appear in either an input stream or an output stream: 
  4067.  
  4068.    is >> setw(width);
  4069.    os << setw(width);
  4070.  
  4071.  
  4072. ΓòÉΓòÉΓòÉ 4.7. ostream and ostream_withassign Classes ΓòÉΓòÉΓòÉ
  4073.  
  4074. Description 
  4075.  
  4076. Derivation 
  4077.  
  4078. Header File 
  4079.  
  4080. Constructors 
  4081.  
  4082. Members 
  4083.  
  4084. To close all the panels in a chapter, double-click on this panel's system menu. 
  4085.  
  4086.  
  4087. ΓòÉΓòÉΓòÉ 4.7.1. Class Description - ostream ΓòÉΓòÉΓòÉ
  4088.  
  4089. This chapter describes the ostream class and its derived class 
  4090. ostream_withassign. You can use the ostream member functions to put characters 
  4091. into the streambuf object that is associated with an ostream object. 
  4092. ostream_withassign is derived from ostream and includes an assignment operator. 
  4093.  
  4094. You can view the topics in this chapter either through the panel on the left, 
  4095. or by selecting from among the following: 
  4096.  
  4097.      Output prefix and suffix functions 
  4098.      Members for formatted output 
  4099.      Members for unformatted output 
  4100.      Members for positioning 
  4101.      Other public members 
  4102.      Built-in manipulators 
  4103.      ostream_withassign class 
  4104.  
  4105.  
  4106. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  4107.  
  4108. ios 
  4109.  
  4110.    ostream
  4111.      ostream_withassign
  4112.  
  4113.  
  4114. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  4115.  
  4116. ostream and ostream_withassign are declared in iostream.h. 
  4117.  
  4118.  
  4119. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  4120.  
  4121. The following members are provided for ostream and ostream_withassign: 
  4122.  
  4123.      Constructors for ostream 
  4124.      Output Operator for Arrays of Characters and char Values 
  4125.      Constructor for ostream_withassign 
  4126.      Assignment Operator for ostream_withassign 
  4127.      flush 
  4128.      opfx 
  4129.      osfx 
  4130.      put 
  4131.      seekp 
  4132.      tellp 
  4133.      write 
  4134.  
  4135.  
  4136. ΓòÉΓòÉΓòÉ 4.7.2. Constructors for ostream ΓòÉΓòÉΓòÉ
  4137.  
  4138. Class: ostream 
  4139.  
  4140. ostream(streambuf* sb);
  4141.  
  4142. The ostream constructor takes a single argument, sb, which is a pointer to a 
  4143. streambuf object. The constructor creates an ostream object that is attached to 
  4144. the streambuf object pointed to by sb. The constructor also initializes the 
  4145. format variables to their defaults. 
  4146.  
  4147. The other declarations for the ostream constructor in iostream.h are obsolete; 
  4148. do not use them. 
  4149.  
  4150.  
  4151. ΓòÉΓòÉΓòÉ 4.7.3. Output Prefix and Suffix Functions ΓòÉΓòÉΓòÉ
  4152.  
  4153. The output operator calls the output prefix function opfx() before inserting 
  4154. characters into a stream buffer, and calls the output suffix function osfx() 
  4155. after inserting characters. The following descriptions assume the functions are 
  4156. called as part of an ostream object called os. 
  4157.  
  4158.  
  4159. ΓòÉΓòÉΓòÉ 4.7.3.1. opfx ΓòÉΓòÉΓòÉ
  4160.  
  4161. int opfx();
  4162.  
  4163. opfx() is called by the output operator before inserting characters into a 
  4164. stream buffer. opfx() checks the error state of os. If the internal flag 
  4165. ios::hardfail is set, opfx() returns 0. Otherwise, opfx() flushes the stream 
  4166. buffer attached to the ios object pointed to by os.tie(), if one exists, and 
  4167. returns the value returned by ios::good(). ios::good() returns 0 if 
  4168. ios::failbit, ios::badbit, or ios::eofbit is set. Otherwise, ios::good() 
  4169. returns a nonzero value. 
  4170.  
  4171.  
  4172. ΓòÉΓòÉΓòÉ 4.7.3.2. osfx ΓòÉΓòÉΓòÉ
  4173.  
  4174. void osfx();
  4175.  
  4176. osfx() is called before a formatted output function returns. osfx() flushes the 
  4177. streambuf object attached to os if ios::unitbuf is set. 
  4178.  
  4179. osfx() is called by the output operator. If you overload the output operator to 
  4180. handle your own classes, you should ensure that osfx() is called after any 
  4181. direct manipulation of a streambuf object. Binary output functions do not call 
  4182. osfx(). 
  4183.  
  4184.  
  4185. ΓòÉΓòÉΓòÉ 4.7.4. Public Members of ostream for Formatted Output ΓòÉΓòÉΓòÉ
  4186.  
  4187. The ostream class lets you use the output operator << to perform formatted 
  4188. output (or insertion) to a stream buffer. Consider the following statement, 
  4189. where outs is a reference to an ostream object and x is a variable of a 
  4190. built-in type: 
  4191.  
  4192.    outs << x;
  4193.  
  4194. The output operator << calls opfx() before beginning insertion. If opfx() 
  4195. returns a nonzero value, the output operator converts x into a series of 
  4196. characters and inserts these characters into the stream buffer attached to 
  4197. outs. If an error occurs, the output operator sets ios::failbit. 
  4198.  
  4199. The details of the conversion of x depend on the format state of the ostream 
  4200. object and the type of x. For numeric and string values, including the char* 
  4201. types and wchar_t*, but excluding the char types and wchar_t, the output 
  4202. operator resets the width variable ios::x_width of the format state of an 
  4203. ostream object to 0, but it does not affect anything else in the format state. 
  4204.  
  4205. The output operator is defined for the following types: 
  4206.  
  4207.      Arrays of characters and char values, including arrays of wchar_t and 
  4208.       wchar_t values. 
  4209.      Other integral values: short, int, long 
  4210.      float, double and long double values 
  4211.      Pointers to void 
  4212.  
  4213.  The following sections describe the output operators for these types. The 
  4214.  output operator is also defined for streambuf objects. 
  4215.  
  4216.  You can also define output operators for your own types. 
  4217.  
  4218.  Note:  The following descriptions assume that the output operator is called 
  4219.  with the ostream object outs on the left side of the operator. 
  4220.  
  4221.  
  4222. ΓòÉΓòÉΓòÉ 4.7.4.1. Output Operator for Arrays of Characters and char Values ΓòÉΓòÉΓòÉ
  4223.  
  4224. ostream& operator<<(const char* cp);
  4225. ostream& operator<<(const signed char* cp);
  4226. ostream& operator<<(const unsigned char* cp);
  4227. ostream& operator<<(wchar_t);
  4228. ostream& operator<<(char ch);
  4229. ostream& operator<<(signed char ch);
  4230. ostream& operator<<(unsigned char ch);
  4231. ostream& operator<<(const wchar_t *);
  4232.  
  4233. For a pointer to a char, signed char, or unsigned char value, the output 
  4234. operator inserts all the characters in the string into the stream buffer with 
  4235. the exception of the null character that terminates the string. For a pointer 
  4236. to a wchar_t, the output operator converts the wchar_t string to its equivalent 
  4237. multibyte character string, and then inserts it into the stream buffer except 
  4238. for the null character that terminates the string. 
  4239.  
  4240. If ios::x_width is greater than zero and the representation of the value to be 
  4241. inserted is less than ios::x_width, the output operator inserts enough fill 
  4242. characters to ensure that the representation occupies an entire field in the 
  4243. stream buffer. 
  4244.  
  4245. The output operator does not perform any conversion on char, signed char, 
  4246. unsigned char, or wchar_t values. 
  4247.  
  4248.  
  4249. ΓòÉΓòÉΓòÉ 4.7.4.2. Output Operator for Other Integral Values ΓòÉΓòÉΓòÉ
  4250.  
  4251. ostream& operator<<(short iv);
  4252. ostream& operator<<(unsigned short iv);
  4253. ostream& operator<<(int iv);
  4254. ostream& operator<<(unsigned int iv);
  4255. ostream& operator<<(long iv);
  4256. ostream& operator<<(unsigned long iv);
  4257. ostream& operator<<(long long iv);
  4258. ostream& operator<<(unsigned long long iv);
  4259.  
  4260. Note:  The last two operators above are only available when the compiler is in 
  4261. a mode that supports the long long data type. 
  4262.  
  4263. For the integral types (short, unsigned short, int, unsigned int, long, and 
  4264. unsigned long), the output operator converts the integral value iv according to 
  4265. the format state of outs and inserts characters into the stream buffer 
  4266. associated with outs. There is no overflow detection on conversion of integral 
  4267. types. 
  4268.  
  4269. The conversion that takes place on iv depends, in part, on the settings of the 
  4270. following format flags: 
  4271.  
  4272.      If ios::oct is set, iv is converted to a series of octal digits. If 
  4273.       ios::showbase is set, "0" is inserted into the stream buffer before the 
  4274.       octal digits. If the value being inserted is equal to 0, a single "0" is 
  4275.       inserted, not "00". 
  4276.      If ios::dec is set, iv is converted to a series of decimal digits. 
  4277.      If ios::hex is set, iv is converted to a series of hexadecimal digits. If 
  4278.       ios::showbase is set, "0x" (or "0X" if ios::uppercase is set) is inserted 
  4279.       into the stream buffer before the hexadecimal digits. 
  4280.  
  4281.  If none of these format flags is set, iv is converted to a series of decimal 
  4282.  digits. If iv is converted to a series of decimal digits, its sign also 
  4283.  affects the conversion: 
  4284.  
  4285.      If iv is negative, a negative sign "-" is inserted before the decimal 
  4286.       digits. 
  4287.      If iv is equal to 0, the single digit 0 is inserted. 
  4288.      If iv is positive and ios::showpos is set, a positive sign "+" is 
  4289.       inserted before the decimal digits. 
  4290.  
  4291.  
  4292. ΓòÉΓòÉΓòÉ 4.7.4.3. Output Operator for float and double Values ΓòÉΓòÉΓòÉ
  4293.  
  4294. ostream& operator<<(float val);
  4295. ostream& operator<<(double val);
  4296. ostream& operator<<(long double val);
  4297.  
  4298. The output operator performs a conversion operation on the value val and 
  4299. inserts it into the stream buffer attached to outs. The conversion depends on 
  4300. the values returned by the following functions: 
  4301.  
  4302.      outs.precision(): returns the number of significant digits that appear 
  4303.       after the decimal. The default value is 6. 
  4304.      outs.width(): if this returns 0, val is inserted without any fill 
  4305.       characters. If the return value is greater than the number of characters 
  4306.       needed to represent val, extra fill characters are inserted so that the 
  4307.       total number of characters inserted is equal to the return value. 
  4308.  
  4309.  The conversion also depends on the values of the following format flags: 
  4310.  
  4311.      If ios::scientific is set, val is converted to scientific notation, with 
  4312.       one digit before the decimal, and the number of digits after the decimal 
  4313.       equal to the value returned by outs.precision(). The exponent begins with 
  4314.       a lowercase "e" unless ios::uppercase is set, in which case the exponent 
  4315.       begins with an uppercase "E". 
  4316.      If ios::fixed is set, val is converted to fixed notation, with the number 
  4317.       of digits after the decimal point equal to the value returned by 
  4318.       outs.precision(). If neither ios::fixed nor ios::scientific is set, the 
  4319.       conversion depends upon the value of val. See Floating-Point Formatting 
  4320.       for more details. 
  4321.      If ios::uppercase is set, the exponents of values in scientific notation 
  4322.       begin with an uppercase "E". 
  4323.  
  4324.  See Format State Flags for more details on the format state. 
  4325.  
  4326.  
  4327. ΓòÉΓòÉΓòÉ 4.7.4.4. Output Operator for Pointers to void ΓòÉΓòÉΓòÉ
  4328.  
  4329. ostream& operator<<(void* vp);
  4330.  
  4331. The output operator converts pointers to void to integral values and then 
  4332. converts them to hexadecimal values as if ios::showbase were set. This version 
  4333. of the output operator is used to print out the values of pointers. 
  4334.  
  4335.  
  4336. ΓòÉΓòÉΓòÉ 4.7.4.5. Output Operator for streambuf Objects ΓòÉΓòÉΓòÉ
  4337.  
  4338. ostream& operator<<(streambuf* sb);
  4339.  
  4340. If opfx() returns a nonzero value, the output operator inserts all of the 
  4341. characters that can be taken from sb into the stream buffer attached to outs. 
  4342. Insertion stops when no more characters can be fetched from sb. No padding is 
  4343. performed. The return value is outs. 
  4344.  
  4345.  
  4346. ΓòÉΓòÉΓòÉ 4.7.5. Public Members of ostream for Unformatted Output ΓòÉΓòÉΓòÉ
  4347.  
  4348. You can use the functions listed in this section to insert characters into a 
  4349. stream buffer without regard to the type of the values that the characters 
  4350. represent. 
  4351.  
  4352. Note:  The following descriptions assume that the functions are called as part 
  4353. of an ostream object called outs. 
  4354.  
  4355. The following functions are described: 
  4356.  
  4357.      put - insert a single character 
  4358.      write - insert an array of characters 
  4359.  
  4360.  
  4361. ΓòÉΓòÉΓòÉ 4.7.5.1. put ΓòÉΓòÉΓòÉ
  4362.  
  4363. ostream& put(char c);
  4364.  
  4365. put() inserts c in the stream buffer attached to outs. put() sets the error 
  4366. state of outs if the insertion fails. 
  4367.  
  4368.  
  4369. ΓòÉΓòÉΓòÉ 4.7.5.2. write ΓòÉΓòÉΓòÉ
  4370.  
  4371. ostream& write(const char* cp, int n);
  4372. ostream& write(const signed char* cp, int n);
  4373. ostream& write(const unsigned char* cp, int n);
  4374.  
  4375. write() inserts the n characters that begin at the position pointed to by cp. 
  4376. This array of characters does not need to end with a null character. 
  4377.  
  4378.  
  4379. ΓòÉΓòÉΓòÉ 4.7.6. Public Members of ostream for Positioning ΓòÉΓòÉΓòÉ
  4380.  
  4381. Note:  The following descriptions assume that the functions are called as part 
  4382. of an ostream object called outs. 
  4383.  
  4384. The following functions are described: 
  4385.  
  4386.      seekp - reposition put pointer of ultimate consumer 
  4387.      tellp - return position of put pointer of associated stream buffer 
  4388.  
  4389.  
  4390. ΓòÉΓòÉΓòÉ 4.7.6.1. seekp ΓòÉΓòÉΓòÉ
  4391.  
  4392. ostream& seekp(streampos sp);
  4393. ostream& seekp(streamoff so, ios::seek_dir dir);
  4394.  
  4395. seekp() repositions the put pointer of the ultimate consumer. seekp() with one 
  4396. argument sets the put pointer to the position sp. seekp() with two arguments 
  4397. sets the put pointer to the position specified by dir with the offset so. dir 
  4398. can have the following values: 
  4399.  
  4400.      ios::beg: the beginning of the stream 
  4401.      ios::cur: the current position of the put pointer 
  4402.      ios::end: the end of the stream 
  4403.  
  4404.  The new position of the put pointer is equal to the position specified by dir 
  4405.  offset by the value of so. If you attempt to move the put pointer to a 
  4406.  position that is not valid, seekp() sets ios::badbit. 
  4407.  
  4408.  
  4409. ΓòÉΓòÉΓòÉ 4.7.6.2. tellp ΓòÉΓòÉΓòÉ
  4410.  
  4411. streampos tellp();
  4412.  
  4413. tellp() returns the current position of the put pointer of the stream buffer 
  4414. that is attached to outs. 
  4415.  
  4416.  
  4417. ΓòÉΓòÉΓòÉ 4.7.7. Other Public Members of ostream ΓòÉΓòÉΓòÉ
  4418.  
  4419. :link auto dependent refid=cscl066 reftype=hd . 
  4420.  
  4421. In this section, the following function is described: 
  4422.  
  4423. flush - clear associated stream buffer 
  4424.  
  4425.  
  4426. ΓòÉΓòÉΓòÉ 4.7.7.1. flush ΓòÉΓòÉΓòÉ
  4427.  
  4428. ostream& flush();
  4429.  
  4430. The ultimate consumer of characters that are stored in a stream buffer may not 
  4431. necessarily consume them immediately. flush() causes any characters that are 
  4432. stored in the stream buffer attached to outs to be consumed. It calls 
  4433. outs.rdbuf()->sync() to accomplish this action. 
  4434.  
  4435.  
  4436. ΓòÉΓòÉΓòÉ 4.7.8. Built-In Manipulators for ostream ΓòÉΓòÉΓòÉ
  4437.  
  4438. ostream&     endl(ostream& i);
  4439. ostream&     ends(ostream& i);
  4440. ostream&     flush(ostream&);
  4441. ios&         dec(ios&);
  4442. ios&         hex(ios&);
  4443. ios&         oct(ios&);
  4444.  
  4445. The I/O Stream Library provides you with a set of built-in manipulators that 
  4446. can be used with the ostream class. These manipulators have a specific effect 
  4447. on an ostream object beyond extracting their own values. The built-in 
  4448. manipulators are accepted by the following versions of the output operators: 
  4449.  
  4450. ostream&     operator<<(ostream& (*f)(ostream&));
  4451. ostream&     operator<<(ios& (*f)(ios&) );
  4452.  
  4453. If outs is a reference to an ostream object, then this statement inserts a 
  4454. newline character and calls flush(). 
  4455.  
  4456.    outs << endl;
  4457.  
  4458. This statement inserts a null character: 
  4459.  
  4460.    outs << ends;
  4461.  
  4462. This statement flushes the stream buffer attached to outs. It is equivalent to 
  4463. flush() 
  4464.  
  4465.    outs << flush;
  4466.  
  4467. This statement sets ios::dec: 
  4468.  
  4469.    outs << dec;
  4470.  
  4471. This statement sets ios::hex: 
  4472.  
  4473.    outs << hex;
  4474.  
  4475. This statement sets ios::oct: 
  4476.  
  4477.    outs << oct;
  4478.  
  4479.  
  4480. ΓòÉΓòÉΓòÉ 4.7.9. Public Members of ostream_withassign ΓòÉΓòÉΓòÉ
  4481.  
  4482. Description 
  4483.  
  4484. To close all the panels in a chapter, double-click on this panel's system menu. 
  4485.  
  4486.  
  4487. ΓòÉΓòÉΓòÉ 4.7.10. Class Description - ostream_withassign ΓòÉΓòÉΓòÉ
  4488.  
  4489. There are two public members of ostream_withassign: 
  4490.  
  4491.      ostream_withassign constructor 
  4492.      ostream_withassign assignment operator 
  4493.  
  4494.  
  4495. ΓòÉΓòÉΓòÉ 4.7.10.1. Constructor for ostream_withassign ΓòÉΓòÉΓòÉ
  4496.  
  4497. ostream_withassign();
  4498.  
  4499. The ostream_withassign constructor creates an ostream_withassign object. It 
  4500. does not do any initialization on the object. 
  4501.  
  4502.  
  4503. ΓòÉΓòÉΓòÉ 4.7.10.2. Assignment Operator for ostream_withassign ΓòÉΓòÉΓòÉ
  4504.  
  4505. ostream_withassign& operator=(ostream& os);
  4506. ostream_withassign& operator=(streambuf* sb);
  4507.  
  4508. There are two versions of the ostream_withassign assignment operator. The first 
  4509. version takes a reference to an ostream object, os, as its argument. It 
  4510. associates the streambuf attached to os with the ostream_withassign object that 
  4511. is on the left side of the assignment operator. 
  4512.  
  4513. The second version of the assignment operator takes a pointer to a streambuf 
  4514. object, sb, as its argument. It associates sb with the ostream_withassign 
  4515. object that is on the left side of the assignment operator. 
  4516.  
  4517.  
  4518. ΓòÉΓòÉΓòÉ 4.8. stdiobuf and stdiostream Classes ΓòÉΓòÉΓòÉ
  4519.  
  4520. Description 
  4521.  
  4522. Derivation 
  4523.  
  4524. Header File 
  4525.  
  4526. Members 
  4527.  
  4528. Examples 
  4529.  
  4530. To close all the panels in a chapter, double-click on this panel's system menu. 
  4531.  
  4532.  
  4533. ΓòÉΓòÉΓòÉ 4.8.1. Class Description - stdiobuf ΓòÉΓòÉΓòÉ
  4534.  
  4535. This chapter describes the stdiobuf class and stdiostream, the class that uses 
  4536. stdiobuf objects as stream buffers. Operations on an stdiobuf are mirrored on 
  4537. the associated FILE structure (defined in the C header file stdio.h). 
  4538.  
  4539. Note:  The classes described in this chapter are meant to be used when you have 
  4540. to mix C code with C++ code. If you are writing new C++ code, use filebuf, 
  4541. fstream, ifstream, and ofstream instead of stdiobuf and stdiostream. See 
  4542. sync_with_stdio for information on synchronizing stdio.h input and output with 
  4543. I/O Stream Library input and output. 
  4544.  
  4545.  
  4546. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  4547.  
  4548. ios 
  4549.  
  4550.   stdiostream
  4551.  
  4552.  
  4553. streambuf 
  4554.  
  4555.   stdiobuf
  4556.  
  4557.  
  4558. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  4559.  
  4560. stdiobuf and stdiostream are declared in stdiostr.h. 
  4561.  
  4562.  
  4563. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  4564.  
  4565. The following members are provided for stdiobuf and stdiostream: 
  4566.  
  4567.      Constructor for stdiobuf 
  4568.      Destructor for stdiobuf 
  4569.      stdiofile 
  4570.      Constructor for stdiostream 
  4571.      rdbuf 
  4572.  
  4573.  
  4574. ΓòÉΓòÉΓòÉ 4.8.2. Public Members of stdiobuf ΓòÉΓòÉΓòÉ
  4575.  
  4576. The following members are described: 
  4577.  
  4578.      Constructor for stdiobuf 
  4579.      Destructor for stdiobuf 
  4580.      stdiofile 
  4581.  
  4582.  
  4583. ΓòÉΓòÉΓòÉ 4.8.2.1. Constructor for stdiobuf ΓòÉΓòÉΓòÉ
  4584.  
  4585. stdiobuf(FILE* f);
  4586.  
  4587. The stdiobuf constructor creates an stdiobuf object that is associated with the 
  4588. FILE pointed to by f. Changes that are made to the stream buffer in an stdiobuf 
  4589. object are also made to the associated FILE pointed to by f. 
  4590.  
  4591. Note:  If ios::stdio is set in the format state of an ostream object, a call to 
  4592. osfx() flushes stdout and stderr. 
  4593.  
  4594.  
  4595. ΓòÉΓòÉΓòÉ 4.8.2.2. Destructor for stdiobuf ΓòÉΓòÉΓòÉ
  4596.  
  4597. ~stdiobuf();
  4598.  
  4599. The stdiobuf destructor frees space allocated by the stdiobuf constructor and 
  4600. flushes the file that this stdiobuf object is associated with. 
  4601.  
  4602.  
  4603. ΓòÉΓòÉΓòÉ 4.8.2.3. stdiofile ΓòÉΓòÉΓòÉ
  4604.  
  4605. FILE* stdiofile();
  4606.  
  4607. stdiofile() returns a pointer to the FILE object that the stdiobuf object is 
  4608. associated with. 
  4609.  
  4610.  
  4611. ΓòÉΓòÉΓòÉ 4.8.3. Public Members of stdiostream ΓòÉΓòÉΓòÉ
  4612.  
  4613.      Constructor for stdiostream 
  4614.      rdbuf 
  4615.  
  4616.  
  4617. ΓòÉΓòÉΓòÉ 4.8.3.1. Constructor for stdiostream ΓòÉΓòÉΓòÉ
  4618.  
  4619. stdiostream(FILE* file);
  4620.  
  4621. The stdiostream constructor creates a stdiostream object that is attached to 
  4622. the FILE pointed to by file. 
  4623.  
  4624.  
  4625. ΓòÉΓòÉΓòÉ 4.8.3.2. rdbuf ΓòÉΓòÉΓòÉ
  4626.  
  4627. stdiobuf* rdbuf();
  4628.  
  4629. rdbuf() returns a pointer to the stdiobuf object that is attached to the 
  4630. stdiostream object. 
  4631.  
  4632.  
  4633. ΓòÉΓòÉΓòÉ 4.8.3.3. Example of Using stdiostream ΓòÉΓòÉΓòÉ
  4634.  
  4635. The following example shows how you can use the stdiostream class. Two files 
  4636. are opened using fopen(). The pointers to the FILE structures are then used to 
  4637. create stdiostream objects. Finally, the contents of one of these stdiostream 
  4638. objects are copied into the other stdiostream object. 
  4639.  
  4640.    #include <stdiostr.h>
  4641.    #include <stdio.h>
  4642.    #include <stdlib.h>
  4643.  
  4644.    void main()
  4645.    {
  4646.       FILE *in = fopen("in.dat", "r");
  4647.       FILE *out = fopen("out.dat", "w");
  4648.       int c;
  4649.       if (in == NULL)
  4650.       {
  4651.            cerr << "Cannot open file 'in.dat' for reading."
  4652.                 << endl;
  4653.            exit(1);
  4654.       }
  4655.       if (out == NULL)
  4656.       {
  4657.            cerr << "Cannot open file 'out.dat' for writing."
  4658.                 << endl;
  4659.            exit(1);
  4660.       }
  4661.       //
  4662.       // Create a stdiostream object attached to "f"
  4663.       //
  4664.       stdiostream sin(in);
  4665.       stdiostream sout(out);
  4666.       cout << "The data contained in the file is: " << endl;
  4667.       //
  4668.       // Now read data from "sin" and copy it to
  4669.       // "cout" and "sout"
  4670.       //
  4671.       while ((c = sin.rdbuf()->sbumpc()) != EOF)
  4672.       {
  4673.          cout << char(c);
  4674.          sout.rdbuf()->sputc(c);
  4675.       }
  4676.       cout << endl;
  4677.    }
  4678.  
  4679. If you run this example with an input file containing the following: 
  4680.  
  4681.    input input input input
  4682.  
  4683. The following output is produced: 
  4684.  
  4685. The data contained in the file is:
  4686.    input input input input
  4687.  
  4688.  
  4689. ΓòÉΓòÉΓòÉ 4.9. streambuf Class ΓòÉΓòÉΓòÉ
  4690.  
  4691. Description 
  4692.  
  4693. Derivation 
  4694.  
  4695. Header File 
  4696.  
  4697. Members 
  4698.  
  4699. To close all the panels in a chapter, double-click on this panel's system menu. 
  4700.  
  4701.  
  4702. ΓòÉΓòÉΓòÉ 4.9.1. Class Description - streambuf ΓòÉΓòÉΓòÉ
  4703.  
  4704. You can use the streambuf class to manipulate objects of its derived classes 
  4705. filebuf, stdiobuf, and strstreambuf, or to derive other classes from it. 
  4706.  
  4707. You can view the topics in this chapter either through the panel on the left, 
  4708. or by selecting from among the following: 
  4709.  
  4710.      streambuf Public and protected interfaces 
  4711.      Public members 
  4712.      Functions that return pointers 
  4713.      Functions that set pointers 
  4714.      Other nonvirtual functions 
  4715.      Virtual functions 
  4716.  
  4717.  
  4718. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  4719.  
  4720. streambuf is the base class for strstream, stdiobuf, and filebuf.  It is not 
  4721. derived from any class. 
  4722.  
  4723.  
  4724. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  4725.  
  4726. streambuf is declared in iostream.h. 
  4727.  
  4728.  
  4729. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  4730.  
  4731. The following members are provided for streambuf: 
  4732.  
  4733.      Constructors for streambuf 
  4734.      Destructor for streambuf 
  4735.      allocate 
  4736.      base 
  4737.      blen 
  4738.      dbp 
  4739.      doallocate 
  4740.      eback 
  4741.      ebuf 
  4742.      egptr 
  4743.      epptr 
  4744.      gbump 
  4745.      gptr 
  4746.      in_avail 
  4747.      out_waiting 
  4748.      overflow 
  4749.      pbackfail 
  4750.      pbase 
  4751.      pbump 
  4752.      pptr 
  4753.      sbumpc 
  4754.      seekoff 
  4755.      seekpos 
  4756.      setb 
  4757.      setbuf 
  4758.      setg 
  4759.      setp 
  4760.      sgetc 
  4761.      sgetn 
  4762.      snextc 
  4763.      sputbackc 
  4764.      sputc 
  4765.      sputn 
  4766.      stossc 
  4767.      sync 
  4768.      unbuffered 
  4769.      underflow 
  4770.  
  4771.  
  4772. ΓòÉΓòÉΓòÉ 4.9.2. streambuf Public and Protected Interfaces ΓòÉΓòÉΓòÉ
  4773.  
  4774. streambuf has both a public interface and a protected interface. You should 
  4775. think of these two interfaces as being two separate classes, because the 
  4776. interfaces are used for different purposes.  You should also treat streambuf as 
  4777. if it were defined as a virtual base class.  Do not create objects of the 
  4778. streambuf class itself. This section describes the ways you can use the two 
  4779. interfaces of streambuf. 
  4780.  
  4781. Although most virtual functions are declared public, you should overload them 
  4782. in the classes that you derive from streambuf, and consider them part of the 
  4783. protected interface. 
  4784.  
  4785.       What is the streambuf public interface? 
  4786.       What is the streambuf protected interface? 
  4787.  
  4788.  
  4789. ΓòÉΓòÉΓòÉ 4.9.2.1. What is the streambuf Public Interface? ΓòÉΓòÉΓòÉ
  4790.  
  4791. You should not create objects of the streambuf public interface directly. 
  4792. Instead, you should use streambuf through one of the predefined classes derived 
  4793. from streambuf.  You can use objects of filebuf, strstreambuf and stdiobuf (the 
  4794. predefined classes derived from streambuf) directly as implementations of 
  4795. stream buffers.  The public interface consists of the streambuf public member 
  4796. functions that can be called on objects of these predefined classes.  streambuf 
  4797. itself does not have any facilities for taking characters from the ultimate 
  4798. producer or sending them to the ultimate consumer.  The specialized member 
  4799. functions that handle the interface with the ultimate producer and the ultimate 
  4800. consumer are defined in filebuf, strstreambuf and stdiobuf. 
  4801.  
  4802. Except for the destructor of the streambuf class, the virtual functions are 
  4803. described as part of the protected interface. 
  4804.  
  4805.  
  4806. ΓòÉΓòÉΓòÉ 4.9.2.2. What is the streambuf Protected Inteface? ΓòÉΓòÉΓòÉ
  4807.  
  4808. Use the streambuf protected interface in the following ways: 
  4809.  
  4810.      As a base class to implement your own specialized stream buffers.  In 
  4811.       this sense you can think of streambuf as a virtual base class.  The 
  4812.       streambuf class only provides the basic functions needed to manipulate 
  4813.       characters in a stream buffer.  The filebuf, strstreambuf and stdiobuf 
  4814.       classes contain functions that handle the interface with the standard 
  4815.       ultimate consumers and producers.  If you want to perform more 
  4816.       sophisticated operations, or if you want to use other ultimate consumers 
  4817.       and ultimate producers, you will have to create your own class derived 
  4818.       from streambuf.  You need to know about the protected interface if you 
  4819.       want to create a class derived from streambuf. 
  4820.  
  4821.      Through a predefined class derived from streambuf. 
  4822.  
  4823.  There are two kinds of functions in the protected interface: 
  4824.  
  4825.      Nonvirtual member functions, which manipulate streambuf objects at a 
  4826.       level of detail that would be inappropriate in the public interface. 
  4827.      Virtual member functions, which permit classes that you derive from 
  4828.       streambuf to customize their operations depending on the ultimate 
  4829.       producer or ultimate consumer.  When you define the virtual functions in 
  4830.       your derived classes, you must ensure that these definitions fulfill the 
  4831.       conditions stated in the descriptions of the virtual functions. If your 
  4832.       definitions of the virtual functions do not fulfill these conditions, 
  4833.       objects of the derived class may have unspecified behavior. Although most 
  4834.       virtual functions are declared as public members, they are described with 
  4835.       the protected interface (with the exception of the destructor for the 
  4836.       streambuf class) because they are meant to be overridden in the classes 
  4837.       that you derive from streambuf. 
  4838.  
  4839.  
  4840. ΓòÉΓòÉΓòÉ 4.9.3. Public Members of the streambuf Public Interface ΓòÉΓòÉΓòÉ
  4841.  
  4842. Note:  The following descriptions assume that the functions are called as part 
  4843. of an object fb of a class derived from streambuf.  fb could, for example, be 
  4844. an object of the class filebuf. It could also be an strstreambuf object or an 
  4845. stdiobuf object. 
  4846.  
  4847. The following member functions are described: 
  4848.  
  4849.      Constructors for streambuf 
  4850.      Destructor for streambuf 
  4851.      in_avail - Return Number of Characters in Get Area 
  4852.      out_waiting - Return Number of Characters in Put Area 
  4853.      sbumpc - Move Get Pointer One Character 
  4854.      sgetc - Return Character After Get Pointer 
  4855.      sgetn - Return Characters Following Get Pointer 
  4856.      snextc - Return Character Following Get Pointer 
  4857.      sputbackc - Move Get Pointer Back One Character 
  4858.      sputc - Store Character After Put Pointer 
  4859.      sputn - Store Characters After Put Pointer 
  4860.      stossc - Move Get Pointer Forward One Character 
  4861.  
  4862.  
  4863. ΓòÉΓòÉΓòÉ 4.9.3.1. Constructors for streambuf ΓòÉΓòÉΓòÉ
  4864.  
  4865. streambuf();
  4866. streambuf(char* buffer, int len);
  4867. streambuf(char* buffer, int len, int c); // obsolete
  4868.  
  4869. There are three versions of the constructor for streambuf. The version with no 
  4870. arguments constructs an empty stream buffer corresponding to an empty sequence. 
  4871. The values returned by base(), eback(), ebuf(), egptr(), epptr(), pptr(), 
  4872. gptr(), and pbase() are initially all zero for this stream buffer. 
  4873.  
  4874. The version with two arguments constructs an empty stream buffer of length len 
  4875. starting at the position pointed to by buffer. 
  4876.  
  4877. The version of the constructor with three arguments is obsolete. It is included 
  4878. in the I/O Stream Library for compatibility with the AT&T C++ Language System 
  4879. Release 1.2. 
  4880.  
  4881.  
  4882. ΓòÉΓòÉΓòÉ 4.9.3.2. Destructor for streambuf ΓòÉΓòÉΓòÉ
  4883.  
  4884. virtual ~streambuf();
  4885.  
  4886. The destructor for streambuf calls sync(). If a stream buffer has been set up 
  4887. and ios::alloc is set, sync() deletes the stream buffer. 
  4888.  
  4889.  
  4890. ΓòÉΓòÉΓòÉ 4.9.3.3. in_avail ΓòÉΓòÉΓòÉ
  4891.  
  4892. int in_avail();
  4893.  
  4894. in_avail() returns the number of characters that are available to be extracted 
  4895. from the get area of fb. You can extract the number of characters equal to the 
  4896. value that in_avail() returns without causing an error. 
  4897.  
  4898.  
  4899. ΓòÉΓòÉΓòÉ 4.9.3.4. out_waiting ΓòÉΓòÉΓòÉ
  4900.  
  4901. int out_waiting();
  4902.  
  4903. out_waiting() returns the number of characters that are in the put area waiting 
  4904. to be sent to the ultimate consumer. 
  4905.  
  4906.  
  4907. ΓòÉΓòÉΓòÉ 4.9.3.5. sbumpc ΓòÉΓòÉΓòÉ
  4908.  
  4909. int sbumpc();
  4910.  
  4911. sbumpc() moves the get pointer past one character and returns the character 
  4912. that it moved past.  sbumpc() returns EOF if the get pointer is already at the 
  4913. end of the get area. 
  4914.  
  4915.  
  4916. ΓòÉΓòÉΓòÉ 4.9.3.6. sgetc ΓòÉΓòÉΓòÉ
  4917.  
  4918. int sgetc();
  4919.  
  4920. sgetc() returns the character after the get pointer without moving the get 
  4921. pointer itself. If no character is available, sgetc() returns EOF. 
  4922.  
  4923. Note:  sgetc() does not change the position of the get pointer. 
  4924.  
  4925.  
  4926. ΓòÉΓòÉΓòÉ 4.9.3.7. sgetn ΓòÉΓòÉΓòÉ
  4927.  
  4928. int sgetn(char* ptr, int n);
  4929.  
  4930. sgetn() extracts the n characters following the get pointer, and copies them to 
  4931. the area starting at the position pointed to by ptr. If there are fewer than n 
  4932. characters following the get pointer, sgetn() takes the characters that are 
  4933. available and stores them in the position pointed to by ptr.  sgetn() 
  4934. repositions the get pointer following the extracted characters and returns the 
  4935. number of extracted characters. 
  4936.  
  4937.  
  4938. ΓòÉΓòÉΓòÉ 4.9.3.8. snextc ΓòÉΓòÉΓòÉ
  4939.  
  4940. int snextc();
  4941.  
  4942. snextc() moves the get pointer forward one character and returns the character 
  4943. following the new position of the get pointer.  snextc() returns EOF if the get 
  4944. pointer is at the end of the get area either before or after it is moved 
  4945. forward. 
  4946.  
  4947.  
  4948. ΓòÉΓòÉΓòÉ 4.9.3.9. sputbackc ΓòÉΓòÉΓòÉ
  4949.  
  4950. int sputbackc(char c);
  4951.  
  4952. sputbackc() moves the get pointer back one character. The get pointer may 
  4953. simply move, or the ultimate producer may rearrange the internal data 
  4954. structures so that the character c is saved. The argument c must equal the 
  4955. character that precedes the get pointer in the stream buffer. The effect of 
  4956. sputbackc() is undefined if c is not equal to the character before the get 
  4957. pointer.  sputbackc() returns EOF if an error occurs. The conditions that cause 
  4958. errors depend on the derived class. 
  4959.  
  4960.  
  4961. ΓòÉΓòÉΓòÉ 4.9.3.10. sputc ΓòÉΓòÉΓòÉ
  4962.  
  4963. int sputc(int c);
  4964.  
  4965. sputc() stores the argument c after the put pointer and moves the put pointer 
  4966. past the stored character. If there is enough space in the stream buffer, this 
  4967. will extend the size of the put area.  sputc() returns EOF if an error occurs. 
  4968. The conditions that cause errors depend on the derived class. 
  4969.  
  4970.  
  4971. ΓòÉΓòÉΓòÉ 4.9.3.11. sputn ΓòÉΓòÉΓòÉ
  4972.  
  4973. int sputn(const char* s, int n);
  4974.  
  4975. sputn() stores the n characters starting at s after the put pointer and moves 
  4976. the put pointer to the end of the series.  sputn() returns the number of 
  4977. characters successfully stored. If an error occurs, sputn() returns a value 
  4978. less than n. 
  4979.  
  4980.  
  4981. ΓòÉΓòÉΓòÉ 4.9.3.12. stossc ΓòÉΓòÉΓòÉ
  4982.  
  4983. void stossc();
  4984.  
  4985. stossc() moves the get pointer forward one character. If the get pointer is 
  4986. already at the end of the get area, stossc() does not move it. 
  4987.  
  4988.  
  4989. ΓòÉΓòÉΓòÉ 4.9.4. Protected Functions That Return Pointers ΓòÉΓòÉΓòÉ
  4990.  
  4991. This section describes the functions in the protected interface of streambuf 
  4992. that return pointers to boundaries of areas in a stream buffer. 
  4993.  
  4994. Note:  The following descriptions assume that the functions are called as part 
  4995. of an object called dsb, which is an object of a class that is derived from 
  4996. streambuf. 
  4997.  
  4998. The following functions are described: 
  4999.  
  5000.      base - Return pointer to beginning of stream buffer 
  5001.      eback - Return pointer to beginning of putback area 
  5002.      ebuf - Return pointer to end of stream buffer 
  5003.      egptr - Return pointer to end of get area 
  5004.      epptr - Return pointer to end of put area 
  5005.      gptr - Return pointer to beginning of get area 
  5006.      pbase - Return pointer to beginning of space available for put area 
  5007.      pptr - Return pointer to beginning of put area 
  5008.  
  5009.  
  5010. ΓòÉΓòÉΓòÉ 4.9.4.1. base ΓòÉΓòÉΓòÉ
  5011.  
  5012. char* base();
  5013.  
  5014. base() returns a pointer to the first byte of the stream buffer. The stream 
  5015. buffer consists of the space between the pointer returned by base() and the 
  5016. pointer returned by ebuf(). 
  5017.  
  5018.  
  5019. ΓòÉΓòÉΓòÉ 4.9.4.2. eback ΓòÉΓòÉΓòÉ
  5020.  
  5021. char* eback();
  5022.  
  5023. eback() returns a pointer to the lower bound of the space available for the get 
  5024. area of dsb. The space between the pointer returned by eback() and the pointer 
  5025. returned by gptr() is available for putback. 
  5026.  
  5027.  
  5028. ΓòÉΓòÉΓòÉ 4.9.4.3. ebuf ΓòÉΓòÉΓòÉ
  5029.  
  5030. char* ebuf();
  5031.  
  5032. ebuf() returns a pointer to the byte after the last byte of the stream buffer. 
  5033.  
  5034.  
  5035. ΓòÉΓòÉΓòÉ 4.9.4.4. egptr ΓòÉΓòÉΓòÉ
  5036.  
  5037. char* egptr();
  5038.  
  5039. egptr() returns a pointer to the byte after the last byte of the get area of 
  5040. dsb. 
  5041.  
  5042.  
  5043. ΓòÉΓòÉΓòÉ 4.9.4.5. epptr ΓòÉΓòÉΓòÉ
  5044.  
  5045. char* epptr();
  5046.  
  5047. epptr() returns a pointer to the byte after the last byte of the put area of 
  5048. dsb. 
  5049.  
  5050.  
  5051. ΓòÉΓòÉΓòÉ 4.9.4.6. gptr ΓòÉΓòÉΓòÉ
  5052.  
  5053. char* gptr();
  5054.  
  5055. gptr() returns a pointer to the first byte of the get area of dsb. The get area 
  5056. consists of the space between the pointer returned by gptr() and the pointer 
  5057. returned by egptr(). Characters are extracted from the stream buffer beginning 
  5058. at the character pointed to by gptr(). 
  5059.  
  5060.  
  5061. ΓòÉΓòÉΓòÉ 4.9.4.7. pbase ΓòÉΓòÉΓòÉ
  5062.  
  5063. char* pbase();
  5064.  
  5065. pbase() returns a pointer to the beginning of the space available for the put 
  5066. area of dsb. Characters between the pointer returned by pbase() and the pointer 
  5067. returned by pptr() have been stored in the stream buffer, but they have not 
  5068. been consumed by the ultimate consumer. 
  5069.  
  5070.  
  5071. ΓòÉΓòÉΓòÉ 4.9.4.8. pptr ΓòÉΓòÉΓòÉ
  5072.  
  5073. char* pptr();
  5074.  
  5075. pptr() returns a pointer to the beginning of the put area of dsb. The put area 
  5076. consists of the space between the pointer returned by pptr() and the pointer 
  5077. returned by epptr(). 
  5078.  
  5079.  
  5080. ΓòÉΓòÉΓòÉ 4.9.5. Protected Functions That Set Pointers ΓòÉΓòÉΓòÉ
  5081.  
  5082. This section describes the functions in the protected interface of streambuf 
  5083. that set the boundaries of areas in a stream buffer. The values of these 
  5084. boundaries are returned by the functions described in Protected Functions That 
  5085. Return Pointers. 
  5086.  
  5087. Note:  The following descriptions assume that the functions are called as part 
  5088. of an object called dsb which is an object of a class that is derived from 
  5089. streambuf. 
  5090.  
  5091. The following functions are described: 
  5092.  
  5093.      setb - Set boundaries of stream buffer 
  5094.      setp - Set boundaries of put area 
  5095.      setg - Set boundaries of get area 
  5096.  
  5097.  
  5098. ΓòÉΓòÉΓòÉ 4.9.5.1. setb ΓòÉΓòÉΓòÉ
  5099.  
  5100. void setb(char* startbuf, char* endbuf, int delbuf = 0);
  5101.  
  5102. setb() sets the beginning of the existing stream buffer (the pointer returned 
  5103. by dsb.base()) to the position pointed to by startbuf, and sets the end of the 
  5104. stream buffer (the pointer returned by dsb.ebuf()) to the position pointed to 
  5105. by endbuf. 
  5106.  
  5107. If delbuf is a nonzero value, the stream buffer will be deleted when setb() is 
  5108. called again. If startbuf and endbuf are both equal to 0, no stream buffer is 
  5109. established. If startbuf is not equal to 0, a stream buffer is established, 
  5110. even if endbuf is less than startbuf. If this is the case, the stream buffer 
  5111. has length zero. 
  5112.  
  5113.  
  5114. ΓòÉΓòÉΓòÉ 4.9.5.2. setg ΓòÉΓòÉΓòÉ
  5115.  
  5116. void setg(char* startpbk, char* startget, char* endget);
  5117.  
  5118. setg() sets the beginning of the get area of dsb (the pointer returned by 
  5119. dsb.gptr()) to startget, and sets the end of the get area (the pointer returned 
  5120. by dsb.egptr()) to endget. setg() also sets the beginning of the area available 
  5121. for putback (the pointer returned by dsb.eback()) to startpbk. 
  5122.  
  5123.  
  5124. ΓòÉΓòÉΓòÉ 4.9.5.3. setp ΓòÉΓòÉΓòÉ
  5125.  
  5126. void setp(char* startput, char* endput);
  5127.  
  5128. setp()sets the spaces available for the put area. Both the start (pbase()) and 
  5129. the beginning (pptr()) of the put area are set to the value startput. See 
  5130. figure The Structure of Stream Buffers for details on where each of these 
  5131. functions points to within the stream buffer. 
  5132.  
  5133. setp() sets the beginning of the put area of dsb (the pointer returned by 
  5134. dsb.pptr()) to the position pointed to by startput, and sets the end of the put 
  5135. area (the pointer returned by dsb.epptr()) to the position pointed to by 
  5136. endput. 
  5137.  
  5138.  
  5139. ΓòÉΓòÉΓòÉ 4.9.6. Other Nonvirtual Protected Member Functions ΓòÉΓòÉΓòÉ
  5140.  
  5141. This section describes the remaining nonvirtual member functions that make up 
  5142. the protected interface of streambuf. 
  5143.  
  5144. Note:  The following descriptions assume that the functions are called as part 
  5145. of an object called dsb which is an object of a class that is derived from 
  5146. streambuf. 
  5147.  
  5148. The following functions are described: 
  5149.  
  5150.      allocate - Set up a stream buffer 
  5151.      blen - Return length of stream buffer 
  5152.      dbp - Record stream buffer status 
  5153.      gbump - Move beginning of get area 
  5154.      pbump - Move beginning of put area 
  5155.      unbuffered - Buffering state 
  5156.  
  5157.  
  5158. ΓòÉΓòÉΓòÉ 4.9.6.1. allocate ΓòÉΓòÉΓòÉ
  5159.  
  5160. int allocate();
  5161.  
  5162. allocate() attempts to set up a stream buffer. allocate() returns the following 
  5163. values: 
  5164.  
  5165.      0, if dsb already has a stream buffer set up (that is, dsb->base() 
  5166.       returns a nonzero value), or if unbuffered() returns a nonzero value. 
  5167.       allocate() does not do any further processing if it returns 0. 
  5168.      1, if allocate() does set up a stream buffer. 
  5169.      EOF, if the attempt to allocate space for the stream buffer fails. 
  5170.  
  5171.  allocate() is not called by any other nonvirtual member function of streambuf. 
  5172.  
  5173.  
  5174. ΓòÉΓòÉΓòÉ 4.9.6.2. blen ΓòÉΓòÉΓòÉ
  5175.  
  5176. int blen() const;
  5177.  
  5178. blen() returns the length (in bytes) of the stream buffer. 
  5179.  
  5180.  
  5181. ΓòÉΓòÉΓòÉ 4.9.6.3. dbp ΓòÉΓòÉΓòÉ
  5182.  
  5183. void dbp();
  5184.  
  5185. dbp() writes to standard output the values returned by the following functions: 
  5186.  
  5187.      base() 
  5188.      eback() 
  5189.      ebuf() 
  5190.      egptr() 
  5191.      epptr() 
  5192.      gptr() 
  5193.      pptr() 
  5194.  
  5195.  dbp() is intended for debugging. streambuf does not specify anything about the 
  5196.  form of the output. dbp() is considered part of the protected interface 
  5197.  because the information that it prints can only be understood in relation to 
  5198.  that interface. It is declared as a public function so that it can be called 
  5199.  anywhere during debugging. 
  5200.  
  5201.  The following example shows the output produced by dbp() when it is called as 
  5202.  part of a filebuf object: 
  5203.  
  5204.      #include <iostream.h>
  5205.      void main()
  5206.      {
  5207.         cout << "Here is some sample output." << endl;
  5208.         cout.rdbuf()->dbp();
  5209.      }
  5210.  
  5211.  If you compile and run this example, your output will look like this: 
  5212.  
  5213.      Here is some sample output.
  5214.      buf at 0x90210, base=0x91010, ebuf=0x91410,
  5215.      pptr=0x91010, epptr=0x91410, eback=0, gptr=0, egptr=0
  5216.  
  5217.  
  5218. ΓòÉΓòÉΓòÉ 4.9.6.4. gbump ΓòÉΓòÉΓòÉ
  5219.  
  5220. void gbump(int offset);
  5221.  
  5222. gbump() offsets the beginning of the get area by the value of offset. The value 
  5223. of offset can be positive or negative. gbump() does not check to see if the new 
  5224. value returned by gptr() is valid. 
  5225.  
  5226. The beginning of the get area is equal to the value returned by gptr(). 
  5227.  
  5228.  
  5229. ΓòÉΓòÉΓòÉ 4.9.6.5. pbump ΓòÉΓòÉΓòÉ
  5230.  
  5231. void pbump(int offset);
  5232.  
  5233. pbump() offsets the beginning of the put area by the value of offset. The value 
  5234. of offset can be positive or negative. pbump() does not check to see if the new 
  5235. value returned by pptr() is valid. 
  5236.  
  5237. The beginning of the put area is equal to the value returned by pptr(). 
  5238.  
  5239.  
  5240. ΓòÉΓòÉΓòÉ 4.9.6.6. unbuffered ΓòÉΓòÉΓòÉ
  5241.  
  5242. int unbuffered() const;
  5243. void unbuffered(int buffstate);
  5244.  
  5245. unbuffered() manipulates the private streambuf variable called the buffering 
  5246. state. If the buffering state is nonzero, a call to allocate() does not set up 
  5247. a stream buffer. 
  5248.  
  5249. There are two versions of unbuffered(). The version that takes no arguments 
  5250. returns the current value of the buffering state. The version that takes an 
  5251. argument, buffstate, changes the value of the buffering state to buffstate. 
  5252.  
  5253.  
  5254. ΓòÉΓòÉΓòÉ 4.9.7. Protected Virtual Member Functions ΓòÉΓòÉΓòÉ
  5255.  
  5256. This section describes the virtual functions in the protected interface of 
  5257. streambuf. Although these virtual functions have default definitions in 
  5258. streambuf, they can be overridden in classes that are derived from streambuf. 
  5259. The following descriptions state the default definition of each function and 
  5260. the expected behavior for these functions in classes where they are overridden. 
  5261.  
  5262. Note:  The following descriptions assume that the functions are called as part 
  5263. of an object called dsb, which is an object of a class that is derived from 
  5264. streambuf. 
  5265.  
  5266. The following functions are described: 
  5267.  
  5268.      doallocate - Allocate space for a stream buffer 
  5269.      overflow -  Clear put area 
  5270.      pbackfail - Deal with full putback area 
  5271.      seekoff - Reposition external get or put pointer 
  5272.      seekpos - Reposition external get or put pointer 
  5273.      setbuf - Set up stream buffer 
  5274.      sync - Synchronize stream buffer and ultimate producer or ultimate 
  5275.       consumer 
  5276.      underflow - Fill get area. 
  5277.  
  5278.  
  5279. ΓòÉΓòÉΓòÉ 4.9.7.1. doallocate ΓòÉΓòÉΓòÉ
  5280.  
  5281. virtual int doallocate();
  5282.  
  5283. doallocate() is called when allocate() determines that space is needed for a 
  5284. stream buffer. 
  5285.  
  5286. The default definition of doallocate() attempts to allocate space for a stream 
  5287. buffer using the operator new. 
  5288.  
  5289. If you define your own version of doallocate(), it must call setb() to provide 
  5290. space for a stream buffer or return EOF if it cannot allocate space. 
  5291. doallocate() should only be called if unbuffered() and base() return zero. 
  5292.  
  5293. In your own version of doallocate(), you provide the size of the buffer for 
  5294. your constructor.  Assign the buffer size you want to to a variable using a 
  5295. #define statement.  This variable can then be used in the constructor for your 
  5296. doallocate() function to define the size of the buffer. 
  5297.  
  5298.  
  5299. ΓòÉΓòÉΓòÉ 4.9.7.2. overflow ΓòÉΓòÉΓòÉ
  5300.  
  5301. virtual int overflow(int c = EOF);
  5302.  
  5303. overflow() is called when the put area is full, and an attempt is made to store 
  5304. another character in it. overflow() may be called at other times. 
  5305.  
  5306. The default definition of overflow() is compatible with the AT&T C++ Language 
  5307. System Release 1.2 version of the stream package, but it is not considered part 
  5308. of the current I/O Stream Library. Thus, the default definition of overflow() 
  5309. should not be used, and every class derived from streambuf should define 
  5310. overflow() itself. 
  5311.  
  5312. The definition of overflow() in your classes derived from streambuf should 
  5313. cause the ultimate consumer to consume the characters in the put area, call 
  5314. setp() to establish a new put area, and store the argument c in the put area if 
  5315. c does not equal EOF. overflow() should return EOF if an error occurs, and it 
  5316. should return a value not equal to EOF otherwise. 
  5317.  
  5318.  
  5319. ΓòÉΓòÉΓòÉ 4.9.7.3. pbackfail ΓòÉΓòÉΓòÉ
  5320.  
  5321. virtual int pbackfail(int c);
  5322.  
  5323. pbackfail() is called when both of the following conditions are true: 
  5324.  
  5325.      An attempt has been made to put back a character. 
  5326.      There is no room in the putback area. The pointer returned by eback() 
  5327.       equals the pointer returned by gptr(). 
  5328.  
  5329.  The default definition of pbackfail() returns EOF. 
  5330.  
  5331.  If you define pbackfail() in your own classes, your definition of pbackfail() 
  5332.  should attempt to deal with the full putback area by, for instance, 
  5333.  repositioning the get pointer of the ultimate producer. If this is possible, 
  5334.  pbackfail() should return the argument c. If not, pbackfail() should return 
  5335.  EOF. 
  5336.  
  5337.  
  5338. ΓòÉΓòÉΓòÉ 4.9.7.4. seekoff ΓòÉΓòÉΓòÉ
  5339.  
  5340. virtual streampos seekoff(streamoff so, seek_dir dir,
  5341.           int mode = ios::in|ios::out);
  5342.  
  5343. seekoff() repositions the get or put pointer of the ultimate producer or 
  5344. ultimate consumer. seekoff() does not change the values returned by dsb.gptr() 
  5345. or dsb.pptr(). 
  5346.  
  5347. The default  definition of seekoff() returns EOF. 
  5348.  
  5349. If you define your own seekoff() function, it should return EOF if the derived 
  5350. class does not support repositioning. If the class does support repositioning, 
  5351. seekoff() should return the new position of the affected pointer, or EOF if an 
  5352. error occurs. so is an offset from a position in the ultimate producer or 
  5353. ultimate consumer. dir is a position in the ultimate producer or ultimate 
  5354. consumer. dir can have the following values: 
  5355.  
  5356.      ios::beg: the beginning of the ultimate producer or ultimate consumer 
  5357.      ios::cur: the current position in the ultimate producer or ultimate 
  5358.       consumer 
  5359.      ios::end: the end of the ultimate producer or ultimate consumer 
  5360.  
  5361.  The new position of the affected pointer is the position specified by dir 
  5362.  offset by the value of so. If you derive your own classes from streambuf, 
  5363.  certain values of dir may not be valid depending on the nature of the ultimate 
  5364.  consumer or producer. 
  5365.  
  5366.  If ios::in is set in mode, the seekoff() should modify the get pointer. If 
  5367.  ios::out is set in mode, the put pointer should be modified. If both ios::in 
  5368.  and ios::out are set, both the get pointer and the put pointer should be 
  5369.  modified. 
  5370.  
  5371.  
  5372. ΓòÉΓòÉΓòÉ 4.9.7.5. seekpos ΓòÉΓòÉΓòÉ
  5373.  
  5374. virtual streampos seekpos(streampos pos,
  5375.           int mode = ios::in|ios::out);
  5376.  
  5377. seekpos() repositions the get or put pointer of the ultimate producer or 
  5378. ultimate consumer to the position pos. If ios::in is set in mode, the get 
  5379. pointer is repositioned. If ios::out is set in mode, the put pointer is 
  5380. repositioned. If both ios::in and ios::out are set, both the get pointer and 
  5381. the put pointer are affected. seekpos() does not change the values returned by 
  5382. dsb.gptr() or dsb.pptr(). 
  5383.  
  5384. The default definition of seekpos() returns the return value of the function 
  5385. seekoff(streamoff(pos), ios::beg, mode). Thus, if you want to define seeking 
  5386. operations in a class derived from streambuf, you can define seekoff() and use 
  5387. the default definition of seekpos(). 
  5388.  
  5389. If you define seekpos() in a class derived from streambuf, seekpos() should 
  5390. return EOF if the class does not support repositioning or if pos points to a 
  5391. position equal to or greater than the end of the stream. If not, seekpos() 
  5392. should return pos. 
  5393.  
  5394.  
  5395. ΓòÉΓòÉΓòÉ 4.9.7.6. setbuf ΓòÉΓòÉΓòÉ
  5396.  
  5397. virtual streambuf* setbuf(char* ptr, int len);
  5398. streambuf* setbuf(unsigned char* ptr, int len);
  5399. streambuf* setbuf(char* ptr, int len, int count); // obsolete
  5400.  
  5401. There are three versions of setbuf(). The two versions that take two arguments 
  5402. set up a stream buffer consisting of the array of bytes starting at ptr with 
  5403. length len. 
  5404.  
  5405. This function is different from setb().  setb() sets pointers to an existing 
  5406. stream buffer.  setbuf(), however, creates the stream buffer. The version of 
  5407. setbuf() that takes three arguments is obsolete. The I/O Stream Library 
  5408. includes it to be compatible with AT&T C++ Language System Release 1.2. 
  5409.  
  5410. The default definition of setbuf() sets up the stream buffer if the streambuf 
  5411. object does not already have a stream buffer. 
  5412.  
  5413. If you define setbuf() in a class derived from streambuf, setbuf() can either 
  5414. accept or ignore a request for an unbuffered streambuf object. The call to 
  5415. setbuf() is a request for an unbuffered streambuf object if ptr equals 0 or len 
  5416. equals 0. setbuf() should return a pointer to sb if it accepts the request, and 
  5417. 0 otherwise. 
  5418.  
  5419.  
  5420. ΓòÉΓòÉΓòÉ 4.9.7.7. sync ΓòÉΓòÉΓòÉ
  5421.  
  5422. virtual int sync();
  5423.  
  5424. sync() synchronizes the stream buffer with the ultimate producer or the 
  5425. ultimate consumer. 
  5426.  
  5427. The default definition of sync() returns 0 if either of the following 
  5428. conditions is true: 
  5429.  
  5430.      The get area is empty and there are no characters waiting to go to the 
  5431.       ultimate consumer 
  5432.      No stream buffer has been allocated for sb. 
  5433.  
  5434.  Otherwise, sync() returns EOF. 
  5435.  
  5436.  If you define sync() in a class derived from streambuf, it should send any 
  5437.  characters that are stored in the put area to the ultimate consumer, and (if 
  5438.  possible) send any characters that are waiting in the get area back to the 
  5439.  ultimate producer. When sync() returns, both the put area and the get area 
  5440.  should be empty. sync() should return EOF if an error occurs. 
  5441.  
  5442.  
  5443. ΓòÉΓòÉΓòÉ 4.9.7.8. underflow ΓòÉΓòÉΓòÉ
  5444.  
  5445. virtual int underflow();
  5446.  
  5447. underflow() takes characters from the ultimate producer and puts them in the 
  5448. get area. 
  5449.  
  5450. The default definition of underflow() is compatible with the AT&T C++ Language 
  5451. System Release 1.2 version version of the stream package, but it is not 
  5452. considered part of the current I/O Stream Library. Thus, the default definition 
  5453. of underflow() should not be used, and every class derived from streambuf 
  5454. should define underflow() itself. 
  5455.  
  5456. If you define underflow() in a class derived from streambuf, it should return 
  5457. the first character in the get area if the get area is not empty. If the get 
  5458. area is empty, underflow() should create a get area that is not empty and 
  5459. return the next character. If no more characters are available in the ultimate 
  5460. producer, underflow() should return EOF and leave the get area empty. 
  5461.  
  5462.  
  5463. ΓòÉΓòÉΓòÉ 4.10. strstream, istrstream, and ostrstream Classes ΓòÉΓòÉΓòÉ
  5464.  
  5465. Description 
  5466.  
  5467. Derivation 
  5468.  
  5469. Header File 
  5470.  
  5471. Members 
  5472.  
  5473. To close all the panels in a chapter, double-click on this panel's system menu. 
  5474.  
  5475.  
  5476. ΓòÉΓòÉΓòÉ 4.10.1. Class Description - strstream, istrstream, and ostrstream ΓòÉΓòÉΓòÉ
  5477.  
  5478. This chapter describes istrstream, ostrsteam, and strstream, the classes that 
  5479. specialize istream, ostream, and iostream (respectively) to use strstreambuf 
  5480. objects for stream buffers. These classes are called the array stream buffer 
  5481. classes because their stream buffers are arrays of bytes in memory. You can use 
  5482. these classes to perform input and output with strings in memory. 
  5483.  
  5484. This chapter also describes strstreambase, the class from which the array 
  5485. stream buffer classes are derived. 
  5486.  
  5487. You can view the topics in this chapter either through the panel on the left, 
  5488. or by selecting the information for a specific class from the list below: 
  5489.  
  5490.      strstreambase class 
  5491.      strstream class 
  5492.      istrstream class 
  5493.      ostrstream class 
  5494.  
  5495.  
  5496. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  5497.  
  5498. ios 
  5499.  
  5500.    istream
  5501.    ostream
  5502.      iostream
  5503.         strstream
  5504.  
  5505. ios 
  5506.  
  5507.    istream
  5508.      istrstream
  5509.  
  5510. ios 
  5511.  
  5512.    ostream
  5513.      ostrstream
  5514.  
  5515.  
  5516. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  5517.  
  5518. strstream, istrstream, and ostrstream are declared in iostream.h. 
  5519.  
  5520.  
  5521. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  5522.  
  5523. The following members are provided for strstream, istrstream, and ostrstream: 
  5524.  
  5525.      Constructors for istrstream 
  5526.      Destructor for istrstream 
  5527.      Constructors for ostrstream 
  5528.      Destructor for ostrstream 
  5529.      Constructor for strstream 
  5530.      Destructor for strstream 
  5531.      pcount 
  5532.      rdbuf 
  5533.      str 
  5534.      str 
  5535.  
  5536.  
  5537. ΓòÉΓòÉΓòÉ 4.10.2. strstreambase ΓòÉΓòÉΓòÉ
  5538.  
  5539. Description 
  5540.  
  5541. Members 
  5542.  
  5543. To close all the panels in a chapter, double-click on this panel's system menu. 
  5544.  
  5545.  
  5546. ΓòÉΓòÉΓòÉ 4.10.3. Class Description - strstreambase ΓòÉΓòÉΓòÉ
  5547.  
  5548. Note:  The strstreambase class is an internal class that provides common 
  5549. functions for the classes that are derived from it. Do not use the 
  5550. strstreambase class directly. The following description is provided so that you 
  5551. can use the function as part of istrstream, ostrsteam, and strstream objects. 
  5552.  
  5553.  
  5554. ΓòÉΓòÉΓòÉ 4.10.3.1. Public Members of strstreambase ΓòÉΓòÉΓòÉ
  5555.  
  5556. strstreambase implements the rdbuf function. 
  5557.  
  5558.  
  5559. ΓòÉΓòÉΓòÉ 4.10.3.1.1. rdbuf ΓòÉΓòÉΓòÉ
  5560.  
  5561. strstreambuf* rdbuf();
  5562.  
  5563. rdbuf() returns a pointer to the stream buffer that the strstreambase object is 
  5564. attached to. 
  5565.  
  5566.  
  5567. ΓòÉΓòÉΓòÉ 4.10.4. strstream ΓòÉΓòÉΓòÉ
  5568.  
  5569. Description 
  5570.  
  5571. Members 
  5572.  
  5573. To close all the panels in a chapter, double-click on this panel's system menu. 
  5574.  
  5575.  
  5576. ΓòÉΓòÉΓòÉ 4.10.5. Class Description - strstream ΓòÉΓòÉΓòÉ
  5577.  
  5578. strstream is the class that specializes iostream for input and output with 
  5579. arrays of characters in memory. You can create an strstream object by 
  5580. associating the object with a previously allocated array of characters.  You 
  5581. can then write output to it, read input from it, and apply other operations to 
  5582. it just as you would to another type of stream. 
  5583.  
  5584.  
  5585. ΓòÉΓòÉΓòÉ 4.10.5.1. Public Members ΓòÉΓòÉΓòÉ
  5586.  
  5587.      Constructor for strstream 
  5588.      Destructor for strstream 
  5589.      str - return pointer to stream buffer array 
  5590.  
  5591.  You can view an example of using the strstream class in the Open Class Library 
  5592.  User's Guide. 
  5593.  
  5594.  
  5595. ΓòÉΓòÉΓòÉ 4.10.5.1.1. Constructor for strstream ΓòÉΓòÉΓòÉ
  5596.  
  5597. strstream();
  5598. strstream(char* cp, int len, int mode);
  5599. strstream(signed char* cp, int len, int mode);
  5600. strstream(unsigned char* cp, int len, int mode);
  5601.  
  5602. There are two versions of the strstream constructor. The version that takes no 
  5603. arguments specifies that space is allocated dynamically for the stream buffer 
  5604. that is attached to the strstream object. 
  5605.  
  5606. The version of the strstream constructor that takes three arguments specifies 
  5607. that characters should be extracted and inserted into the array of bytes that 
  5608. starts at the position pointed to by cp with a length of len bytes. If ios::ate 
  5609. or ios::app is set in mode, cp points to a null-terminated string and 
  5610. insertions begin at the null character. Otherwise, insertions begin at the 
  5611. position pointed to by cp. You can use the istream::seekg() function to 
  5612. reposition the get pointer anywhere in this array. 
  5613.  
  5614.  
  5615. ΓòÉΓòÉΓòÉ 4.10.5.1.2. Destructor for strstream ΓòÉΓòÉΓòÉ
  5616.  
  5617. ~strstream();
  5618.  
  5619. The strstream destructor frees the space allocated by the strstream 
  5620. constructor. 
  5621.  
  5622.  
  5623. ΓòÉΓòÉΓòÉ 4.10.5.1.3. str ΓòÉΓòÉΓòÉ
  5624.  
  5625. char* str();
  5626.  
  5627. str() returns a pointer to the stream buffer attached to the strstream and 
  5628. calls freeze() with a nonzero value to prevent the stream buffer from being 
  5629. deleted. If the stream buffer was constructed with an explicit array, the value 
  5630. returned is a pointer to that array. If the stream buffer was constructed in 
  5631. dynamic mode, cp points to the dynamically allocated area. 
  5632.  
  5633. Until you call str(), deleting the dynamically allocated stream buffer is the 
  5634. responsibility of the strstream object. After str() has been called, the 
  5635. calling application has responsibility for the dynamically allocated stream 
  5636. buffer. 
  5637.  
  5638. Note:  If your application calls str() without calling freeze() with a nonzero 
  5639. argument (to unfreeze the strstream), or without explicitly deleting the array 
  5640. of characters returned by the call to str(), the array of characters will not 
  5641. be deallocated by the strstream when it is destroyed. This situation is a 
  5642. potential source of a memory leak. 
  5643.  
  5644.  
  5645. ΓòÉΓòÉΓòÉ 4.10.6. istrstream ΓòÉΓòÉΓòÉ
  5646.  
  5647. Description 
  5648.  
  5649. To close all the panels in a chapter, double-click on this panel's system menu. 
  5650.  
  5651.  
  5652. ΓòÉΓòÉΓòÉ 4.10.7. Class Description - istrstream ΓòÉΓòÉΓòÉ
  5653.  
  5654. The following functions are described: 
  5655.  
  5656.      Constructors for istrstream 
  5657.      Destructor for istrstream 
  5658.  
  5659.  
  5660. ΓòÉΓòÉΓòÉ 4.10.7.1. Constructors for istrstream ΓòÉΓòÉΓòÉ
  5661.  
  5662. istrstream(char* cp);
  5663. istrstream(signed char* cp);
  5664. istrstream(unsigned char* cp);
  5665. istrstream(const char* cp);
  5666. istrstream(const signed char* cp);
  5667. istrstream(const unsigned char* cp);
  5668. istrstream(char* cp, int len);
  5669. istrstream(signed char* cp, int len);
  5670. istrstream(unsigned char* cp, int len);
  5671. istrstream(const char* cp, int len);
  5672. istrstream(const signed char* cp, int len);
  5673. istrstream(const unsigned char* cp, int len);
  5674.  
  5675. The versions of the istrstream constructor that take one argument specify that 
  5676. characters should be extracted from the null-terminated string that is pointed 
  5677. to by cp. You can use the istream::seekg() function to reposition the get 
  5678. pointer in this string. 
  5679.  
  5680. The versions of the istrstream constructor that take two arguments specify that 
  5681. characters should be extracted from the array of bytes that starts at the 
  5682. position pointed to by cp and has a length of len bytes. You can use 
  5683. istream::seekg() to reposition the get pointer anywhere in this array. 
  5684.  
  5685.  
  5686. ΓòÉΓòÉΓòÉ 4.10.7.2. Destructor for istrstream ΓòÉΓòÉΓòÉ
  5687.  
  5688. ~istrstream();
  5689.  
  5690. The istrstream destructor frees space that was allocated by the istrstream 
  5691. constructor. 
  5692.  
  5693.  
  5694. ΓòÉΓòÉΓòÉ 4.10.8. ostrstream ΓòÉΓòÉΓòÉ
  5695.  
  5696. Description 
  5697.  
  5698. To close all the panels in a chapter, double-click on this panel's system menu. 
  5699.  
  5700.  
  5701. ΓòÉΓòÉΓòÉ 4.10.9. Class Description - ostrstream ΓòÉΓòÉΓòÉ
  5702.  
  5703. The following functions are described: 
  5704.  
  5705.      Constructors for ostrstream 
  5706.      Destructor for ostrstream 
  5707.      str - return pointer to stream buffer array 
  5708.      pcount - return number of characters in stream buffer 
  5709.  
  5710.  
  5711. ΓòÉΓòÉΓòÉ 4.10.9.1. Constructors for ostrstream ΓòÉΓòÉΓòÉ
  5712.  
  5713. ostrstream();
  5714. ostrstream(char* cp, int len, int mode = ios::out);
  5715. ostrstream(signed char* cp, int len, int mode = ios::out);
  5716. ostrstream(unsigned char* cp, int len, int mode = ios::out);
  5717.  
  5718. The version of the ostrsteam constructor that takes no arguments specifies that 
  5719. space is allocated dynamically for the stream buffer that is attached to the 
  5720. ostrsteam object. 
  5721.  
  5722. The versions of the ostrsteam constructor that take three arguments specify 
  5723. that the stream buffer that is attached to the ostrsteam object consists of an 
  5724. array that starts at the position pointed to by cp with a length of len bytes. 
  5725. If ios::ate or ios::app is set in mode, cp points to a null-terminated string 
  5726. and insertions begin at the null character. Otherwise, insertions begin at the 
  5727. position pointed to by cp. You can use the ostream::seekp() function to 
  5728. reposition the put pointer. 
  5729.  
  5730.  
  5731. ΓòÉΓòÉΓòÉ 4.10.9.2. Destructor for ostrstream ΓòÉΓòÉΓòÉ
  5732.  
  5733. ~ostrstream();
  5734.  
  5735. The ostrsteam destructor frees space allocated by the ostrsteam constructor. 
  5736. The destructor also writes a null byte to the stream buffer to terminate the 
  5737. stream. 
  5738.  
  5739.  
  5740. ΓòÉΓòÉΓòÉ 4.10.9.3. str ΓòÉΓòÉΓòÉ
  5741.  
  5742. char* str();
  5743.  
  5744. str() returns a pointer to the stream buffer attached to the ostrsteam and 
  5745. calls freeze() with a nonzero value to prevent the stream buffer from being 
  5746. deleted. If the stream buffer was constructed with an explicit array, the value 
  5747. returned is a pointer to that array. If the stream buffer was constructed in 
  5748. dynamic mode, cp points to the dynamically allocated area. 
  5749.  
  5750. Until you call str(), deleting the dynamically allocated stream buffer is the 
  5751. responsibility of the ostrsteam object. After str() has been called, the 
  5752. calling application has responsibility for the dynamically allocated stream 
  5753. buffer. 
  5754.  
  5755.  
  5756. ΓòÉΓòÉΓòÉ 4.10.9.4. pcount ΓòÉΓòÉΓòÉ
  5757.  
  5758. int pcount();
  5759.  
  5760. pcount() returns the number of bytes that have been stored in the stream 
  5761. buffer. pcount() is mainly useful when binary data has been stored and the 
  5762. stream buffer attached to the ostrsteam object is not a null-terminated string. 
  5763. pcount() returns the total number of bytes, not just the number of bytes up to 
  5764. the first null character. 
  5765.  
  5766.  
  5767. ΓòÉΓòÉΓòÉ 4.11. strstreambuf Class ΓòÉΓòÉΓòÉ
  5768.  
  5769. Description 
  5770.  
  5771. Derivation 
  5772.  
  5773. Header File 
  5774.  
  5775. Members 
  5776.  
  5777. To close all the panels in a chapter, double-click on this panel's system menu. 
  5778.  
  5779.  
  5780. ΓòÉΓòÉΓòÉ 4.11.1. Class Description - strstreambuf ΓòÉΓòÉΓòÉ
  5781.  
  5782. This chapter describes the strstreambuf class, the class that specializes 
  5783. streambuf to use an array of bytes in memory as the ultimate producer or 
  5784. ultimate consumer. 
  5785.  
  5786.  
  5787. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  5788.  
  5789. streambuf 
  5790.  
  5791.    strstreambuf
  5792.  
  5793.  
  5794. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  5795.  
  5796. strstreambuf is declared in strstrea.h. 
  5797.  
  5798.  
  5799. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  5800.  
  5801. The following members are provided for strstreambuf: 
  5802.  
  5803.      Constructors for strstreambuf 
  5804.      Destructor for strstreambuf 
  5805.      doallocate 
  5806.      freeze 
  5807.      overflow 
  5808.      seekoff 
  5809.      setbuf 
  5810.      str 
  5811.      underflow 
  5812.  
  5813.  
  5814. ΓòÉΓòÉΓòÉ 4.11.2. Constructors for strstreambuf ΓòÉΓòÉΓòÉ
  5815.  
  5816. strstreambuf();
  5817. strstreambuf(int bufsize);
  5818. strstreambuf(void* (*alloc) (long), void(*free)(void*));
  5819. strstreambuf(char* sp, int len, char* tp);
  5820. strstreambuf(signed char* sp, int len, signed char* tp);
  5821. strstreambuf(unsigned char* sp, int len, unsigned char* tp);
  5822.  
  5823. The first version of the strstreambuf constructor takes no arguments and 
  5824. constructs an empty strstreambuf object in dynamic mode. Space will be 
  5825. allocated automatically to accommodate the characters that are put into the 
  5826. strstreambuf object. This space will be allocated using the operator new and 
  5827. deallocated using the operator delete. The characters that are already stored 
  5828. by the strstreambuf object may have to be copied when new space is allocated. 
  5829. If you know you are going to insert many characters into an strstreambuf 
  5830. object, you can give the I/O Stream Library an estimate of the size of the 
  5831. object before you create it by calling strstreambuf::setbuf(). 
  5832.  
  5833. The second version of the strstreambuf constructor takes one argument and 
  5834. constructs an empty strstreambuf object in dynamic mode. The initial size of 
  5835. the stream buffer will be at least bufsize bytes. 
  5836.  
  5837. The third version of the strstreambuf constructor takes two arguments and 
  5838. creates an empty strstreambuf object in dynamic mode. alloc is a pointer to the 
  5839. function that is used to allocate space. alloc is passed a long value that 
  5840. equals the number of bytes that it is supposed to allocate. If the value of 
  5841. alloc is 0, the operator new is used to allocate space. free is a pointer to 
  5842. the function that is used to free space. free is passed an argument that is a 
  5843. pointer to the array of bytes that alloc allocated. If free has a value of 0, 
  5844. the operator delete is used to free space. 
  5845.  
  5846. The fourth, fifth, and sixth versions of the strstreambuf constructor take 
  5847. three arguments and construct a strstreambuf object with a stream buffer that 
  5848. begins at the position pointed to by sp. The nature of the stream buffer 
  5849. depends on the value of len: 
  5850.  
  5851.      If len is positive, the len bytes following the position pointed to by sp 
  5852.       make up the stream buffer. 
  5853.  
  5854.      If len equals 0, sp points to the beginning of a null-terminated string, 
  5855.       and the bytes of that string, excluding the terminating null character, 
  5856.       will make up the stream buffer. 
  5857.  
  5858.      If len is negative, the stream buffer has an indefinite length. The get 
  5859.       pointer of the stream buffer is initialized to sp, and the put pointer is 
  5860.       initialized to tp. 
  5861.  
  5862.  Regardless of the value of len, if the value of tp is 0, the get area will 
  5863.  include the entire stream buffer, and insertions will cause errors. 
  5864.  
  5865.  
  5866. ΓòÉΓòÉΓòÉ 4.11.3. Destructor for strstreambuf ΓòÉΓòÉΓòÉ
  5867.  
  5868. ~strstreambuf();
  5869.  
  5870. If freeze() has not been called for the strstreambuf object and a stream buffer 
  5871. is associated with the strstreambuf object, the strstreambuf destructor frees 
  5872. the space allocated by the strstreambuf constructor. The effect of the 
  5873. destructor depends on the constructor used to create the strstreambuf object: 
  5874.  
  5875.      If you created the strstreambuf object using the constructor that takes 
  5876.       two pointers to functions as arguments (see Constructors for strstreambuf 
  5877.       for more details), the destructor frees the space allocated by the 
  5878.       destructor by calling the function pointed to by the second argument to 
  5879.       the constructor. 
  5880.  
  5881.      If you created the strstreambuf object using any of the other 
  5882.       constructors, the destructor calls the delete operator to free the space 
  5883.       allocated by the constructor. 
  5884.  
  5885.  
  5886. ΓòÉΓòÉΓòÉ 4.11.4. doallocate ΓòÉΓòÉΓòÉ
  5887.  
  5888. virtual int doallocate();
  5889.  
  5890. doallocate() attempts to allocate space for a stream buffer. If you created the 
  5891. strstreambuf object using the constructor that takes two pointers to functions 
  5892. as arguments (see Constructors for strstreambuf for more details), doallocate() 
  5893. allocates space for the stream buffer by calling the function pointed to by the 
  5894. first argument to the constructor. Otherwise, doallocate() calls the operator 
  5895. new to allocate space for the stream buffer. 
  5896.  
  5897.  
  5898. ΓòÉΓòÉΓòÉ 4.11.5. freeze ΓòÉΓòÉΓòÉ
  5899.  
  5900. void freeze(int n=1);
  5901.  
  5902. freeze() controls whether the array that makes up a stream buffer can be 
  5903. deleted automatically. If n has a nonzero value, the array is not deleted 
  5904. automatically. If n equals 0, the array is deleted automatically when more 
  5905. space is needed or when the strstreambuf object is deleted. If you call 
  5906. freeze() with a nonzero argument for a strstreambuf object that was allocated 
  5907. in dynamic mode, any attempts to put characters in the stream buffer may result 
  5908. in errors. Therefore, you should avoid insertions to such stream buffers 
  5909. because the results are unpredictable. However, if you have a "frozen" stream 
  5910. buffer and you call freeze() with an argument equal to 0, you can put 
  5911. characters in the stream buffer again. 
  5912.  
  5913. Only space that is acquired through dynamic allocation is ever freed. 
  5914.  
  5915.  
  5916. ΓòÉΓòÉΓòÉ 4.11.6. overflow ΓòÉΓòÉΓòÉ
  5917.  
  5918. virtual int overflow(int c);
  5919.  
  5920. overflow() causes the ultimate consumer to consume the characters in the put 
  5921. area and calls setp() to establish a new put area. The argument c is stored in 
  5922. the new put area if c is not equal to EOF. 
  5923.  
  5924.  
  5925. ΓòÉΓòÉΓòÉ 4.11.7. str ΓòÉΓòÉΓòÉ
  5926.  
  5927. char* str();
  5928.  
  5929. str() returns a pointer to the first character in the stream buffer and calls 
  5930. freeze() with a nonzero argument. Any attempts to put characters in the stream 
  5931. buffer may result in errors. If the strstreambuf object was created with an 
  5932. explicit array (that is, the strstreambuf constructor with three arguments was 
  5933. used), str() returns a pointer to that array. If the strstreambuf object was 
  5934. created in dynamic mode and nothing is stored in the array, str() may return 0. 
  5935.  
  5936.  
  5937. ΓòÉΓòÉΓòÉ 4.11.8. seekoff ΓòÉΓòÉΓòÉ
  5938.  
  5939. virtual streampos seekoff(
  5940.       streamoff so, ios::seek_dir dir, int mode);
  5941.  
  5942. seekoff() repositions the get or put pointer in the array of bytes in memory 
  5943. that serves as the ultimate producer or the ultimate consumer. For a text mode 
  5944. file, seekoff() returns the actual physical file position, because carriage 
  5945. return characters and end-of-file characters are discarded on input. Thus, 
  5946. there may not be a one-to-one correspondence between the characters in a stream 
  5947. and those in its external representation. For further details, see "Low-Level 
  5948. I/O" in the IBM VisualAge C++ for OS/2 C Library Reference, S25H-6964. 
  5949.  
  5950. If you constructed the strstreambuf in dynamic mode (see Constructors for 
  5951. strstreambuf), the results of seekoff() are unpredictable. Therefore, do not 
  5952. use seekoff() with an strstreambuf object that you created in dynamic mode. 
  5953.  
  5954. If you did not construct the strstreambuf object in dynamic mode, seekoff() 
  5955. attempts to reposition the get pointer or the put pointer, depending on the 
  5956. value of mode. If ios::in is set in mode, seekoff() repositions the get 
  5957. pointer. If ios::out is set in mode, seekoff() repositions the put pointer. If 
  5958. both ios::in and ios::out are set, seekoff() repositions both pointers. 
  5959.  
  5960. seekoff() attempts to reposition the affected pointer to the value of dir + so. 
  5961. dir can have the following values: 
  5962.  
  5963.      ios::beg: the beginning of the array in memory 
  5964.      ios::cur: the current position in the array in memory 
  5965.      ios::end: the end of the array in memory 
  5966.  
  5967.  If the value of dir + so is equal to or greater than the end of the array, the 
  5968.  value is not valid and seekoff() returns EOF. Otherwise, seekoff() sets the 
  5969.  affected pointer to this value and returns this value. 
  5970.  
  5971.  
  5972. ΓòÉΓòÉΓòÉ 4.11.9. setbuf ΓòÉΓòÉΓòÉ
  5973.  
  5974. virtual streambuf* setbuf(0, int bufsize);
  5975.  
  5976. setbuf() records bufsize. The next time that the strstreambuf object 
  5977. dynamically allocates a stream buffer, the stream buffer is at least bufsize 
  5978. bytes long. 
  5979.  
  5980. Note:  If you call setbuf() for an strstreambuf object, you must call it with 
  5981. the first argument equal to 0. 
  5982.  
  5983.  
  5984. ΓòÉΓòÉΓòÉ 4.11.10. underflow ΓòÉΓòÉΓòÉ
  5985.  
  5986. virtual int underflow();
  5987.  
  5988. If the get area is not empty, underflow() returns the first character in the 
  5989. get area. If the get area is empty, underflow() creates a new get area that is 
  5990. not empty and returns the first character. If no more characters are available 
  5991. in the ultimate producer, underflow() returns EOF and leaves the get area 
  5992. empty. 
  5993.  
  5994.  
  5995. ΓòÉΓòÉΓòÉ 5. Collection Classes ΓòÉΓòÉΓòÉ
  5996.  
  5997. The Collection Class Library lets you develop programs that implement commonly 
  5998. used abstract data types, including sets, maps, sequences, trees, stacks, 
  5999. queues, and sorted or keyed collections.  The following topics are discussed in 
  6000. this section: Flat Collection Classes Tree Collection Classes Auxiliary 
  6001. Collection Classes Abstract Collection Classes Header Files for Coding Examples 
  6002.  
  6003.  
  6004. ΓòÉΓòÉΓòÉ 5.1. Flat Collection Classes ΓòÉΓòÉΓòÉ
  6005.  
  6006. This part contains detailed descriptions of the flat Collection Classes. 
  6007.  
  6008. Introduction to Flat Collections describes the common member functions for flat 
  6009. collections. Subsequent chapters describe individual collection classes. 
  6010.  
  6011. For information on the organization of chapters that describe individual 
  6012. abstract data types, see Format of Class Descriptions. 
  6013.  
  6014. The following flat collections are described in this part: 
  6015.  
  6016.      Bag 
  6017.      Deque 
  6018.      Equality sequence 
  6019.      Heap 
  6020.      Key bag 
  6021.      Key set 
  6022.      Key sorted bag 
  6023.      Key sorted set 
  6024.      Map 
  6025.      Priority queue 
  6026.      Queue 
  6027.      Relation 
  6028.      Sequence 
  6029.      Set 
  6030.      Sorted bag 
  6031.      Sorted map 
  6032.      Sorted relation 
  6033.      Sorted set 
  6034.      Stack 
  6035.  
  6036.  
  6037. ΓòÉΓòÉΓòÉ 5.1.1. Introduction to Flat Collections ΓòÉΓòÉΓòÉ
  6038.  
  6039. This chapter defines some of the terms used in describing the Collection Class 
  6040. Library classes and functions, describes the format of chapters that describe 
  6041. individual collections, and describes some types defined by the Collection 
  6042. Class Library. 
  6043.  
  6044.  
  6045. ΓòÉΓòÉΓòÉ 5.1.1.1. Terms Used ΓòÉΓòÉΓòÉ
  6046.  
  6047.  CLASS_BASE_NAME For constructor and destructor declarations, this term is used 
  6048.                  in place of the default implementation variant of a class. 
  6049.                  For example, the constructor CLASS_BASE_NAME(...) for a Bag, 
  6050.                  is really IBag(...), because the default implementation 
  6051.                  variant of a bag is IBag. 
  6052.  
  6053.  CLASS_NAME      For member function declarations, this term is used in place 
  6054.                  of the class with template arguments. For example, if you want 
  6055.                  to use: 
  6056.  
  6057.                                   IBoolean operator != ( CLASS_NAME const& collection ) const;
  6058.  
  6059.                  for a Bag on BST Key Sorted Set, substitute 
  6060.                  IBagOnBSTKeySortedSet<ElementName> for CLASS_NAME. 
  6061.  
  6062.  equal element   Refers to equality of elements as defined by the equality 
  6063.                  operation or ordering relation provided for the element type 
  6064.                  (Element Functions and Key-Type Functions describes the 
  6065.                  purpose of the equality operation and ordering relation.) 
  6066.                  Where both equality operation and ordering relation are 
  6067.                  provided, the Collection Class Library may use either to 
  6068.                  determine element equality. 
  6069.  
  6070.  given ...       Refers to an argument of the described function, such as given 
  6071.                  element, given key, or given collection. 
  6072.  
  6073.  iteration order The order in which elements are visited in allElementsDo() and 
  6074.                  setToNext() or setToPrevious(). 
  6075.  
  6076.                  In ordered collections, the element at position 1 will be 
  6077.                  visited first, then the element at position 2, and so on. 
  6078.                  Sorted collections, in particular, are visited following the 
  6079.                  ordering relation provided for the element type. 
  6080.  
  6081.                  In collections that are not ordered, the elements are visited 
  6082.                  in an arbitrary order. Each element is visited exactly once. 
  6083.  
  6084.  positioning property The property of an element that is used to position the 
  6085.                  element in a collection. For key collections, the positioning 
  6086.                  property is key equality. For nonsequential collections with 
  6087.                  element equality, the positioning property is element 
  6088.                  equality. Other collections have no positioning property. 
  6089.  
  6090.  same key        Refers to equality of keys as defined by the equality 
  6091.                  operation or ordering relation provided for the key type. (See 
  6092.                  Element Functions and Key-Type Functions.) Where both equality 
  6093.                  operation and ordering relation are provided, the Collection 
  6094.                  Class Library may use either to determine key equality. 
  6095.  
  6096.  this collection The collection to which a function is applied.  Contrast with 
  6097.                  the given collection, which is an argument supplied to a 
  6098.                  function. The collection is synonymous with this collection. 
  6099.  
  6100.  undefined cursor A cursor that may or may not be valid; there is no way to 
  6101.                  know whether the cursor is valid or not.  An undefined cursor, 
  6102.                  even if it remains valid, may refer to a different element 
  6103.                  than before, or even to no element of the collection. Do not 
  6104.                  use cursors, once they become undefined, in functions that 
  6105.                  require the cursor to point to an element of the collection. 
  6106.  
  6107.  
  6108. ΓòÉΓòÉΓòÉ 5.1.1.2. Format of Class Descriptions ΓòÉΓòÉΓòÉ
  6109.  
  6110. Each chapter describing one or more Collection Classes consists of the 
  6111. following components: 
  6112.  
  6113.      The chapter title, which usually refers to the kind of collection being 
  6114.       discussed. 
  6115.  
  6116.      A description of the collection's characteristics, such as whether the 
  6117.       collection is sorted or unsorted, or whether the type and value of the 
  6118.       elements are relevant. 
  6119.  
  6120.      A textual example of using the collection in an application. 
  6121.  
  6122.      Information on the class's derivation. 
  6123.  
  6124.      A section on class implementation variants that provides some or all of 
  6125.       the following information: 
  6126.  
  6127.         -  The default implementation, and the classes that you can use to 
  6128.            alter the way the collection is implemented. These variant classes 
  6129.            are based on other abstract data types within the Collection Class 
  6130.            Library. For example, in the chapter on heap collections, the class 
  6131.            IHeapOnTabularSequence is a heap collection based on 
  6132.            ITabularSequence. 
  6133.         -  The names of the header files that correspond to particular 
  6134.            implementation variants, so that you can include those files in your 
  6135.            source code to make use of the implementation variants. 
  6136.  
  6137.      A section on template arguments and required parameters that provides the 
  6138.       following information: 
  6139.  
  6140.         -  Template arguments, which identify what parameters you must supply 
  6141.            when you instantiate a particular implementation variant. 
  6142.         -  Required functions, which are functions that must be provided by the 
  6143.            element type or key type you use for any implementation variant. 
  6144.  
  6145.      A section on the reference class. The reference class allows you to make 
  6146.       use of polymorphism. This section contains information on include files, 
  6147.       template arguments and required functions similar to the information 
  6148.       provided for the implementation variants described above. In general, 
  6149.       reference classes do not put any additional requirements on the element 
  6150.       type or key type.  The requirements are those of the implementation 
  6151.       variant used with the reference class. 
  6152.  
  6153.      Optionally, a coding example to show you how to use the collection. 
  6154.  
  6155.  
  6156. ΓòÉΓòÉΓòÉ 5.1.1.2.1. Required Functions ΓòÉΓòÉΓòÉ
  6157.  
  6158. As described in Element Functions and Key-Type Functions, the Collection 
  6159. Classes require that you provide certain functions for the element type and key 
  6160. type. These functions are required by member functions of the Collection Class 
  6161. Library to manipulate elements and keys. The functions you must provide depend 
  6162. on the abstraction you use and on the implementation variant you choose. For 
  6163. example, you will usually need to provide a key access for all keyed 
  6164. abstractions, and for a hash table implementation you will need to provide a 
  6165. hash function. 
  6166.  
  6167.  
  6168. ΓòÉΓòÉΓòÉ 5.1.1.3. Types Defined for the Collection Class Library ΓòÉΓòÉΓòÉ
  6169.  
  6170. The following types are defined in iglobals.h or in header files included by 
  6171. iglobals.h: 
  6172.  
  6173.    typedef int IBoolean;
  6174.  
  6175.    enum {
  6176.       false = 0,
  6177.       False = 0,
  6178.       true  = 1,
  6179.       True  = 1
  6180.    };
  6181.  
  6182.    typedef unsigned long INumber;
  6183.    typedef unsigned long IPosition;
  6184.  
  6185.    enum ITreeIterationOrder {IPreorder, IPostorder}; // for n-ary tree only
  6186.  
  6187. Note:  If your environment defines another boolean type, use IBoolean wherever 
  6188. you want to refer to Boolean in the context of the Collection Class Library. 
  6189.  
  6190.  
  6191. ΓòÉΓòÉΓòÉ 5.1.2. Flat Collection Member Functions ΓòÉΓòÉΓòÉ
  6192.  
  6193. Each flat collection implements some or all of the member functions described 
  6194. in this chapter.  Chapters on individual classes identify which functions are 
  6195. implemented for those classes. 
  6196.  
  6197. The following member functions are described: 
  6198.  
  6199. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  6200. Γöé Constructor                    Γöé locate                        Γöé
  6201. Γöé Copy Constructor               Γöé locateElementWithKey          Γöé
  6202. Γöé Destructor                     Γöé locateFirst                   Γöé
  6203. Γöé operator!=                     Γöé locateLast                    Γöé
  6204. Γöé operator=                      Γöé locateNext                    Γöé
  6205. Γöé operator==                     Γöé locateNextElementWithKey      Γöé
  6206. Γöé add                            Γöé locateOrAdd                   Γöé
  6207. Γöé addAllFrom                     Γöé locateOrAddElementWithKey     Γöé
  6208. Γöé addAsFirst                     Γöé locatePrevious                Γöé
  6209. Γöé addAsLast                      Γöé maxNumberOfElements           Γöé
  6210. Γöé addAsNext                      Γöé newCursor                     Γöé
  6211. Γöé addAsPrevious                  Γöé numberOfDifferentElements     Γöé
  6212. Γöé addAtPosition                  Γöé numberOfDifferentKeys         Γöé
  6213. Γöé addDifference                  Γöé numberOfElements              Γöé
  6214. Γöé addIntersection                Γöé numberOfElementsWithKey       Γöé
  6215. Γöé addOrReplaceElementWithKey     Γöé numberOfOccurrences           Γöé
  6216. Γöé addUnion                       Γöé pop                           Γöé
  6217. Γöé allElementsDo                  Γöé push                          Γöé
  6218. Γöé allElementsDo                  Γöé remove                        Γöé
  6219. Γöé anyElement                     Γöé removeAllElementsWithKey      Γöé
  6220. Γöé compare                        Γöé removeAllOccurrences          Γöé
  6221. Γöé contains                       Γöé removeAll                     Γöé
  6222. Γöé containsAllFrom                Γöé removeAll                     Γöé
  6223. Γöé containsAllKeysFrom            Γöé removeAt                      Γöé
  6224. Γöé containsElementWithKey         Γöé removeAtPosition              Γöé
  6225. Γöé copy                           Γöé removeElementWithKey          Γöé
  6226. Γöé dequeue                        Γöé removeFirst                   Γöé
  6227. Γöé differenceWith                 Γöé removeLast                    Γöé
  6228. Γöé elementAt                      Γöé replaceAt                     Γöé
  6229. Γöé elementAtPosition              Γöé replaceElementWithKey         Γöé
  6230. Γöé elementWithKey                 Γöé setToFirst                    Γöé
  6231. Γöé enqueue                        Γöé setToLast                     Γöé
  6232. Γöé firstElement                   Γöé setToNext                     Γöé
  6233. Γöé intersectionWith               Γöé setToNextDifferentElement     Γöé
  6234. Γöé isBounded                      Γöé setToNextWithDifferentKey     Γöé
  6235. Γöé isEmpty                        Γöé setToPosition                 Γöé
  6236. Γöé isFirst                        Γöé setToPrevious                 Γöé
  6237. Γöé isFull                         Γöé sort                          Γöé
  6238. Γöé isLast                         Γöé top                           Γöé
  6239. Γöé key                            Γöé unionWith                     Γöé
  6240. Γöé lastElement                    Γöé                               Γöé
  6241. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  6242.  
  6243.  
  6244. ΓòÉΓòÉΓòÉ 5.1.2.1. Constructor ΓòÉΓòÉΓòÉ
  6245.  
  6246. CLASS_BASE_NAME ( INumber numberOfElements = 100 ) ;
  6247.  
  6248. Constructs a collection. numberOfElements is the estimated maximum number of 
  6249. elements contained in the collection. The collection is unbounded and is 
  6250. initially empty. If the estimated maximum is exceeded, the collection is 
  6251. automatically enlarged. 
  6252.  
  6253. Note:  The collection constructor does not define whether any elements are 
  6254. constructed when the collection is constructed. For some classes, the element's 
  6255. default constructor may be invoked when the collection's constructor is 
  6256. invoked. This happens if a tabular or a diluted sequence implementation variant 
  6257. is used for a collection.  The element's default constructor is used to 
  6258. allocate the required storage and initialize the elements. Therefore, a default 
  6259. constructor must be available for elements in such cases. 
  6260.  
  6261. Exception 
  6262.  
  6263. IOutOfMemory 
  6264.  
  6265.  
  6266. ΓòÉΓòÉΓòÉ 5.1.2.2. Copy Constructor ΓòÉΓòÉΓòÉ
  6267.  
  6268. CLASS_BASE_NAME ( CLASS_NAME const& collection ) ;
  6269.  
  6270. Constructs a collection and copies all elements from the given collection into 
  6271. the collection as described for addAllFrom. 
  6272.  
  6273. Exception 
  6274.  
  6275. IOutOfMemory 
  6276.  
  6277.  
  6278. ΓòÉΓòÉΓòÉ 5.1.2.3. Destructor ΓòÉΓòÉΓòÉ
  6279.  
  6280. ~CLASS_BASE_NAME ( ) ;
  6281.  
  6282. Removes all elements from the collection. Destructors are called for all 
  6283. elements contained in the collection and for elements that have been 
  6284. constructed in advance. 
  6285.  
  6286. Side Effects 
  6287.  
  6288. All cursors of the collection become undefined. 
  6289.  
  6290.  
  6291. ΓòÉΓòÉΓòÉ 5.1.2.4. operator!= ΓòÉΓòÉΓòÉ
  6292.  
  6293. IBoolean operator!= ( CLASS_NAME const& collection ) const;
  6294.  
  6295. Returns True if the given collection is not equal to the collection. For a 
  6296. definition of equality for collections, see operator==. 
  6297.  
  6298.  
  6299. ΓòÉΓòÉΓòÉ 5.1.2.5. operator= ΓòÉΓòÉΓòÉ
  6300.  
  6301. CLASS_NAME& operator= ( CLASS_NAME const& collection ) ;
  6302.  
  6303. Copies the given collection to the collection. Removes all elements from the 
  6304. collection and adds the elements from the given collection as described for 
  6305. addAllFrom. 
  6306.  
  6307. Preconditions 
  6308.  
  6309.      If the collection is bounded, numberOfElements() of the given collection 
  6310.       must be less than maxNumberOfElements() of this collection. 
  6311.  
  6312.  Side Effects 
  6313.  
  6314.      All cursors of this collection become undefined. 
  6315.      Collection classes supporting Visual Builder send a modifiedId 
  6316.       notification. 
  6317.  
  6318.  Return Value 
  6319.  
  6320.  Returns a reference to the collection. 
  6321.  
  6322.  Exceptions 
  6323.  
  6324.      IOutOfMemory 
  6325.      IFullException, if the collection is bounded 
  6326.  
  6327.  
  6328. ΓòÉΓòÉΓòÉ 5.1.2.6. operator== ΓòÉΓòÉΓòÉ
  6329.  
  6330. IBoolean operator== ( CLASS_NAME const& collection ) const;
  6331.  
  6332. Returns True if the given collection is equal to the collection. Two 
  6333. collections are equal if the number of elements in each collection is the same, 
  6334. and if the condition for the collection is described in the following list: 
  6335.  
  6336.  Type of Collection    Condition 
  6337.  
  6338.  Unique Elements       If the collections have unique elements, any element 
  6339.                        that occurs in one collection must occur in the other 
  6340.                        collection. 
  6341.  
  6342.  Non-Unique Elements   If an element has n occurrences in one collection, it 
  6343.                        must have exactly n occurrences in the other collection. 
  6344.  
  6345.  Sequential            The ordering of the elements is the same for both 
  6346.                        collections. 
  6347.  
  6348.  
  6349. ΓòÉΓòÉΓòÉ 5.1.2.7. add ΓòÉΓòÉΓòÉ
  6350.  
  6351. IBoolean add ( Element const& element ) ;
  6352.  
  6353. IBoolean add ( Element const& element,
  6354.    ICursor& cursor ) ;
  6355.  
  6356. If the collection is unique (with respect to elements or keys) and the element 
  6357. or key is already contained in the collection, sets the cursor to the existing 
  6358. element in the collection without adding the element. Otherwise, it adds the 
  6359. element to the collection and sets the cursor to the added element. In 
  6360. sequential collections, the given element is added as the last element. In 
  6361. sorted collections, the element is added at a position determined by the 
  6362. element or key value. Adding an element will either use the element's copy 
  6363. constructor or the assignment operator provided for the element type, depending 
  6364. on the implementation variant you choose. See contains for the definition of 
  6365. element or key containment. 
  6366.  
  6367. Preconditions 
  6368.  
  6369.      The cursor must belong to the collection. 
  6370.      If the collection is bounded and unique, the element or key must exist or 
  6371.       (numberOfElements() < maxNumberOfElements()). 
  6372.      If the collection is bounded and nonunique, 
  6373.       (numberOfElements() < maxNumberOfElements()). 
  6374.      If the collection is a map or a sorted map and contains an element with 
  6375.       the same key as the given element, this element must be equal to the 
  6376.       given element. 
  6377.  
  6378.  Side Effects 
  6379.  
  6380.      If an element was added, all cursors of this collection, except the given 
  6381.       cursor, become undefined. 
  6382.      If an element was added, collection classes supporting Visual Builder 
  6383.       send an addedId notification. 
  6384.  
  6385.  Return Value 
  6386.  
  6387.  Returns True if the element was added. 
  6388.  
  6389.  Exceptions 
  6390.  
  6391.      IOutOfMemory 
  6392.      ICursorInvalidException 
  6393.      IFullException, if the collection is bounded 
  6394.      IKeyAlreadyExistsException, if the collection is a map or a sorted map 
  6395.  
  6396.  
  6397. ΓòÉΓòÉΓòÉ 5.1.2.8. addAllFrom ΓòÉΓòÉΓòÉ
  6398.  
  6399. void addAllFrom ( CLASS_NAME const& collection ) ;
  6400.  
  6401. void addAllFrom (
  6402.    IACollection <Element> const& collection ) ;
  6403.  
  6404. Adds (copies) all elements of the given collection to the collection. The 
  6405. elements are added in the iteration order of the given collection. The contents 
  6406. of the elements, not the pointers to the elements, are copied. The elements are 
  6407. added according to the definition of add for this collection. The given 
  6408. collection is not changed. 
  6409.  
  6410. Preconditions 
  6411.  
  6412. Because the elements are added one by one, the following preconditions are 
  6413. tested for each individual add operation: 
  6414.  
  6415.      If the collection is bounded and unique, the element or key must exist or 
  6416.       (numberOfElements() < maxNumberOfElements()). 
  6417.      If the collection is bounded and nonunique, 
  6418.       (numberOfElements() < maxNumberOfElements()). 
  6419.      If the collection is a map or a sorted map and contains an element with 
  6420.       the same key as the given element, this element must be equal to the 
  6421.       given element. 
  6422.  
  6423.  Side Effects 
  6424.  
  6425.      If any elements were added, all cursors of this collection become 
  6426.       undefined. 
  6427.      If any elements were added, collection classes supporting Visual Builder 
  6428.       send a modifiedId notification. 
  6429.  
  6430.  Exceptions 
  6431.  
  6432.      IOutOfMemory 
  6433.      IIdenticalCollectionException 
  6434.      IFullException, if the collection is bounded 
  6435.      IKeyAlreadyExistsException, if the collection is a map or a sorted map 
  6436.  
  6437.  
  6438. ΓòÉΓòÉΓòÉ 5.1.2.9. addAsFirst ΓòÉΓòÉΓòÉ
  6439.  
  6440. void addAsFirst ( Element const& element ) ;
  6441.  
  6442. void addAsFirst ( Element const& element,
  6443.    ICursor& cursor ) ;
  6444.  
  6445. Adds the element to the collection as the first element in sequential order. 
  6446. Sets the cursor to the added element. 
  6447.  
  6448. Preconditions 
  6449.  
  6450.      The cursor must belong to the collection. 
  6451.      If the collection is bounded, 
  6452.       (numberOfElements() < maxNumberOfElements()). 
  6453.  
  6454.  Side Effects 
  6455.  
  6456.      All cursors of this collection, except the given cursor, become 
  6457.       undefined. 
  6458.      If an element was added, collection classes supporting Visual Builder 
  6459.       send an addedId notification. 
  6460.  
  6461.  Exceptions 
  6462.  
  6463.      ICursorInvalidException 
  6464.      IOutOfMemory 
  6465.      IFullException, if the collection is bounded 
  6466.  
  6467.  
  6468. ΓòÉΓòÉΓòÉ 5.1.2.10. addAsLast ΓòÉΓòÉΓòÉ
  6469.  
  6470. void addAsLast ( Element const& element ) ;
  6471.  
  6472. void addAsLast ( Element const& element,
  6473.    ICursor& cursor ) ;
  6474.  
  6475. Adds the element to the collection as the last element in sequential order. 
  6476. Sets the cursor to the added element. 
  6477.  
  6478. Preconditions 
  6479.  
  6480.      The cursor must belong to the collection. 
  6481.      If the collection is bounded, 
  6482.       (numberOfElements() < maxNumberOfElements()). 
  6483.  
  6484.  Side Effects 
  6485.  
  6486.      All cursors of this collection, except the given cursor, become 
  6487.       undefined. 
  6488.      If an element was added, collection classes supporting Visual Builder 
  6489.       send an addedId notification. 
  6490.  
  6491.  All cursors of this collection, except the given cursor, become undefined. 
  6492.  
  6493.  Exceptions 
  6494.  
  6495.      ICursorInvalidException 
  6496.      IOutOfMemory 
  6497.      IFullException, if the collection is bounded 
  6498.  
  6499.  
  6500. ΓòÉΓòÉΓòÉ 5.1.2.11. addAsNext ΓòÉΓòÉΓòÉ
  6501.  
  6502. void addAsNext ( Element const& element,
  6503.    ICursor& cursor ) ;
  6504.  
  6505. Adds the element to the collection as the element following element pointed to 
  6506. by the cursor. Sets the cursor to the added element. 
  6507.  
  6508. Preconditions 
  6509.  
  6510.      The cursor must belong to the collection and must point to an element of 
  6511.       the collection. 
  6512.      If the collection is bounded, 
  6513.       (numberOfElements() < maxNumberOfElements()). 
  6514.  
  6515.  Side Effects 
  6516.  
  6517.      All cursors of this collection, except the given cursor, become 
  6518.       undefined. 
  6519.      If an element was added, collection classes supporting Visual Builder 
  6520.       send an addedId notification. 
  6521.  
  6522.  Exceptions 
  6523.  
  6524.      IOutOfMemory 
  6525.      ICursorInvalidException 
  6526.      IFullException, if the collection is bounded 
  6527.  
  6528.  
  6529. ΓòÉΓòÉΓòÉ 5.1.2.12. addAsPrevious ΓòÉΓòÉΓòÉ
  6530.  
  6531. void addAsPrevious ( Element const& element,
  6532.    ICursor& cursor ) ;
  6533.  
  6534. Adds the element to the collection as the element preceding the element pointed 
  6535. to by the cursor. Sets the cursor to the added element. 
  6536.  
  6537. Preconditions 
  6538.  
  6539.      The cursor must belong to the collection and must point to an element of 
  6540.       the collection. 
  6541.      If the collection is bounded, 
  6542.       (numberOfElements() < maxNumberOfElements()). 
  6543.  
  6544.  Side Effects 
  6545.  
  6546.      All cursors of this collection, except the given cursor, become 
  6547.       undefined. 
  6548.      If an element was added, collection classes supporting Visual Builder 
  6549.       send an addedId notification. 
  6550.  
  6551.  Exceptions 
  6552.  
  6553.      IOutOfMemory 
  6554.      ICursorInvalidException 
  6555.      IFullException, if the collection is bounded 
  6556.  
  6557.  
  6558. ΓòÉΓòÉΓòÉ 5.1.2.13. addAtPosition ΓòÉΓòÉΓòÉ
  6559.  
  6560. void addAtPosition ( IPosition position,
  6561.    Element const& element ) ;
  6562.  
  6563. void addAtPosition ( IPosition position,
  6564.    Element const& element, ICursor& cursor ) ;
  6565.  
  6566. Adds the element at the given position to the collection, and sets the cursor 
  6567. to the added element. If an element exists at the given position, the new 
  6568. element is added as the element preceding the existing element. 
  6569.  
  6570. Preconditions 
  6571.  
  6572.      The cursor must belong to the collection. 
  6573.      (1 <= position <= numberOfElements + 1). 
  6574.      If the collection is bounded, 
  6575.       (numberOfElements() < maxNumberOfElements()). 
  6576.  
  6577.  Side Effects 
  6578.  
  6579.      All cursors of this collection, except the given cursor, become 
  6580.       undefined. 
  6581.      If an element was added, collection classes supporting Visual Builder 
  6582.       send an addedId notification. 
  6583.  
  6584.  Exceptions 
  6585.  
  6586.      IOutOfMemory 
  6587.      ICursorInvalidException 
  6588.      IPositionInvalidException 
  6589.      IFullException, if the collection is bounded 
  6590.  
  6591.  
  6592. ΓòÉΓòÉΓòÉ 5.1.2.14. addDifference ΓòÉΓòÉΓòÉ
  6593.  
  6594. void addDifference ( CLASS_NAME const& collection1,
  6595.    CLASS_NAME const& collection2 ) ;
  6596.  
  6597. Creates the difference between the two given collections, and adds this 
  6598. difference to the collection. The contents of the added elements, not the 
  6599. pointers to those elements, are copied. 
  6600.  
  6601. For a definition of the difference between two collections, see differenceWith. 
  6602.  
  6603. Preconditions 
  6604.  
  6605. Because the elements are added one by one, the following preconditions are 
  6606. tested for each individual addition. 
  6607.  
  6608.      If the collection is bounded and unique, the element or key must exist or 
  6609.       (numberOfElements() < maxNumberOfElements()). 
  6610.      If the collection is bounded and nonunique, 
  6611.       (numberOfElements() < maxNumberOfElements()). 
  6612.      If the collection is a map or a sorted map and contains an element with 
  6613.       the same key as the given element, this element must be equal to the 
  6614.       given element. 
  6615.  
  6616.  Side Effects 
  6617.  
  6618.      If any elements were added, all cursors of this collection become 
  6619.       undefined. 
  6620.      If any elements were added, collection classes supporting Visual Builder 
  6621.       send a modifiedId notification. 
  6622.  
  6623.  Exceptions 
  6624.  
  6625.      IOutOfMemory 
  6626.      IFullException, if the collection is bounded 
  6627.      IKeyAlreadyExistsException, if the collection is a map or a sorted map 
  6628.  
  6629.  
  6630. ΓòÉΓòÉΓòÉ 5.1.2.15. addIntersection ΓòÉΓòÉΓòÉ
  6631.  
  6632. void addIntersection ( CLASS_NAME const& collection1,
  6633.    CLASS_NAME const& collection2 ) ;
  6634.  
  6635. Creates the intersection of the two given collections, and adds this 
  6636. intersection to the collection. The contents of the added elements, not the 
  6637. pointers to those elements, are copied. 
  6638.  
  6639. For a definition of the intersection of two collections, see intersectionWith. 
  6640.  
  6641. Preconditions 
  6642.  
  6643. Because the elements are added one by one, the following preconditions are 
  6644. tested for each individual addition. 
  6645.  
  6646.      If the collection is bounded and unique, the element or key must exist or 
  6647.       (numberOfElements() < maxNumberOfElements()). 
  6648.      If the collection is bounded and nonunique, 
  6649.       (numberOfElements() < maxNumberOfElements()). 
  6650.      If the collection is a map or a sorted map and contains an element with 
  6651.       the same key as the given element, this element must be equal to the 
  6652.       given element. 
  6653.  
  6654.  Side Effects 
  6655.  
  6656.      If any elements were added, all cursors of this collection become 
  6657.       undefined. 
  6658.      If any elements were added, collection classes supporting Visual Builder 
  6659.       send a modifiedId notification. 
  6660.  
  6661.  Exceptions 
  6662.  
  6663.      IOutOfMemory 
  6664.      IFullException, if the collection is bounded 
  6665.      IKeyAlreadyExistsException, if the collection is a map or a sorted map 
  6666.  
  6667.  
  6668. ΓòÉΓòÉΓòÉ 5.1.2.16. addOrReplaceElementWithKey ΓòÉΓòÉΓòÉ
  6669.  
  6670. IBoolean addOrReplaceElementWithKey (
  6671.    Element const& element );
  6672.  
  6673. IBoolean addOrReplaceElementWithKey (
  6674.    Element const& element, ICursor& cursor ) ;
  6675.  
  6676. If an element is contained in the collection where the key is equal to the key 
  6677. of the given element, sets the cursor to this element in the collection and 
  6678. replaces it with the given element. Otherwise, it adds the given element to the 
  6679. collection, and sets the cursor to the added element. If the given element is 
  6680. added, the contents of the element, not a pointer to it, is added. 
  6681.  
  6682. Preconditions 
  6683.  
  6684.      The cursor must belong to the collection. 
  6685.      If the collection is bounded, an element with the given key must be 
  6686.       contained in the collection, or 
  6687.       (numberOfElements() < maxNumberOfElements()). 
  6688.  
  6689.  Side Effects 
  6690.  
  6691.      If the element was added, all cursors of this collection, except the 
  6692.       given cursor, become undefined. 
  6693.      If the element was added, collection classes supporting Visual Builder 
  6694.       send a replacedId notification. 
  6695.  
  6696.  Return Value 
  6697.  
  6698.  Returns True if the element was added.  Returns False if the element was 
  6699.  replaced. 
  6700.  
  6701.  Exceptions 
  6702.  
  6703.      IOutOfMemory 
  6704.      ICursorInvalidException 
  6705.      IFullException, if the collection is bounded 
  6706.  
  6707.  
  6708. ΓòÉΓòÉΓòÉ 5.1.2.17. addUnion ΓòÉΓòÉΓòÉ
  6709.  
  6710. void addUnion (  CLASS_NAME const& collection1,
  6711.    CLASS_NAME const& collection2 ) ;
  6712.  
  6713. Creates the union of the two given collections, and adds this union to the 
  6714. collection. The contents of the added elements, not the pointers to those 
  6715. elements, are copied. 
  6716.  
  6717. For a definition of the union of two collections, see unionWith. 
  6718.  
  6719. Preconditions 
  6720.  
  6721. Because the elements are added one by one, the following preconditions are 
  6722. tested for each individual addition. 
  6723.  
  6724.      If the collection is bounded and unique, the element or key must exist or 
  6725.       (numberOfElements() < maxNumberOfElements()). 
  6726.      If the collection is bounded and nonunique, 
  6727.       (numberOfElements() < maxNumberOfElements()). 
  6728.      If the collection is a map or a sorted map and contains an element with 
  6729.       the same key as the given element, this element must be equal to the 
  6730.       given element. 
  6731.  
  6732.  Side Effects 
  6733.  
  6734.      If any elements were added, all cursors of this collection become 
  6735.       undefined. 
  6736.      If any elements were added, collection classes supporting Visual Builder 
  6737.       send a modifiedId notification. 
  6738.  
  6739.  Exceptions 
  6740.  
  6741.      IOutOfMemory 
  6742.      IFullException, if the collection is bounded 
  6743.      IKeyAlreadyExistsException, if the collection is a map or a sorted map 
  6744.  
  6745.  
  6746. ΓòÉΓòÉΓòÉ 5.1.2.18. allElementsDo ΓòÉΓòÉΓòÉ
  6747.  
  6748. IBoolean allElementsDo (
  6749.    IBoolean (*function) (Element&, void*),
  6750.    void* additionalArgument = 0 ) ;
  6751.  
  6752. IBoolean allElementsDo (
  6753.    IBoolean (*function) (Element const&, void*),
  6754.    void* additionalArgument = 0 ) const;
  6755.  
  6756. Calls the given function for all elements in the collection until the given 
  6757. function returns False. The elements are visited in iteration order. Additional 
  6758. arguments can be passed to the given function using additionalArgument. The 
  6759. additional argument defaults to zero if no additional argument is given. 
  6760.  
  6761. Note: 
  6762.  
  6763.    1. The given function must not remove elements from or add them to the 
  6764.       collection. If you want to remove elements, you can use the removeAll() 
  6765.       function with a property argument. For further information see removeAll. 
  6766.  
  6767.    2. For the non-const version of allElementsDo(), the given function must not 
  6768.       manipulate the element in the collection in a way that changes the 
  6769.       positioning property of the element. 
  6770.  
  6771.  Return Value 
  6772.  
  6773.  Returns True if the given function returns True for every element it is 
  6774.  applied to. 
  6775.  
  6776.  
  6777. ΓòÉΓòÉΓòÉ 5.1.2.19. allElementsDo ΓòÉΓòÉΓòÉ
  6778.  
  6779. IBoolean allElementsDo (
  6780.    IIterator <Element>& iterator ) ;
  6781.  
  6782. IBoolean allElementsDo (
  6783.    IConstantIterator <Element>& iterator ) const;
  6784.  
  6785. Calls the applyTo() function of the given iterator for all elements of the 
  6786. collection until the applyTo() function returns False. The elements are visited 
  6787. in iteration order. Additional arguments may be passed as arguments to the 
  6788. constructor of the derived iterator class. 
  6789.  
  6790. Note: 
  6791.  
  6792.    1. The applyTo() function must not remove elements from or add elements to 
  6793.       the collection. If you want to remove elements, you can use the 
  6794.       removeAll() function with a property argument. For further information, 
  6795.       see removeAll. 
  6796.  
  6797.    2. For the non-const version of allElementsDo(), the applyTo() function must 
  6798.       not manipulate the element in the collection in a way that changes the 
  6799.       positioning property of the element. 
  6800.  
  6801.  Return Value 
  6802.  
  6803.  Returns True if the applyTo() function returns True for every element it is 
  6804.  applied to. 
  6805.  
  6806.  
  6807. ΓòÉΓòÉΓòÉ 5.1.2.20. anyElement ΓòÉΓòÉΓòÉ
  6808.  
  6809. Element const& anyElement ( ) const;
  6810.  
  6811. Returns a reference to an arbitrary element of the collection. 
  6812.  
  6813. Precondition 
  6814.  
  6815. The collection must not be empty. 
  6816.  
  6817. Exception 
  6818.  
  6819. IEmptyException 
  6820.  
  6821.  
  6822. ΓòÉΓòÉΓòÉ 5.1.2.21. compare ΓòÉΓòÉΓòÉ
  6823.  
  6824. long compare ( CLASS_NAME const& collection,
  6825.    long (*comparisonFunction)
  6826.  (Element const& element1,Element const& element2)
  6827.    ) const;
  6828.  
  6829. Compares the collection with the given collection. Comparison yields <0 if the 
  6830. collection is less than the given collection, 0 if the collection is equal to 
  6831. the given collection, and >0 if the collection is greater than the given 
  6832. collection. Comparison is defined by the first pair of corresponding elements, 
  6833. in both collections, that are not equal. If such a pair exists, the collection 
  6834. with the greater element is the greater one. Otherwise, the collection with 
  6835. more elements is the greater one. 
  6836.  
  6837. Note: 
  6838.  
  6839.    1. The given comparison function must return a result according to the 
  6840.       following rules: 
  6841.  
  6842.       >0             if (element1 > element2) 
  6843.       0              if (element1 == element2) 
  6844.       <0             if (element1 < element2) 
  6845.  
  6846.    2. For elements of type char*, compare() is not locale-sensitive by default. 
  6847.       Because it uses strcmp() and not strcoll(), it compares the binary values 
  6848.       representing the characters, and is not based on the LC_COLLATE category 
  6849.       of the current locale.  Its results are reliable only for code pages and 
  6850.       character sets in which the collating sequence matches the sequence of 
  6851.       binary representations. 
  6852.  
  6853.  Return Value 
  6854.  
  6855.  Returns the result of the collection comparison. 
  6856.  
  6857.  
  6858. ΓòÉΓòÉΓòÉ 5.1.2.22. contains ΓòÉΓòÉΓòÉ
  6859.  
  6860. IBoolean contains ( Element const& element ) const;
  6861.  
  6862. Returns True if the collection contains an element equal to the given element. 
  6863.  
  6864.  
  6865. ΓòÉΓòÉΓòÉ 5.1.2.23. containsAllFrom ΓòÉΓòÉΓòÉ
  6866.  
  6867. IBoolean containsAllFrom (
  6868.    CLASS_NAME const& collection ) const;
  6869.  
  6870. IBoolean containsAllFrom (
  6871.    IACollection <Element> const& collection ) const;
  6872.  
  6873. Returns True if all the elements of the given collection are contained in the 
  6874. collection. The definition of containment is described in contains. 
  6875.  
  6876.  
  6877. ΓòÉΓòÉΓòÉ 5.1.2.24. containsAllKeysFrom ΓòÉΓòÉΓòÉ
  6878.  
  6879. IBoolean containsAllKeysFrom (
  6880.    CLASS_NAME const& collection ) const;
  6881.  
  6882. IBoolean containsAllKeysFrom (
  6883.    IACollection <Element> const& collection ) const;
  6884.  
  6885. Returns True if all of the keys of the given collection are contained in the 
  6886. collection. 
  6887.  
  6888.  
  6889. ΓòÉΓòÉΓòÉ 5.1.2.25. containsElementWithKey ΓòÉΓòÉΓòÉ
  6890.  
  6891. IBoolean containsElementWithKey ( Key const& key ) const;
  6892.  
  6893. Returns True if the collection contains an element with the same key as the 
  6894. given key. 
  6895.  
  6896.  
  6897. ΓòÉΓòÉΓòÉ 5.1.2.26. copy ΓòÉΓòÉΓòÉ
  6898.  
  6899. void copy ( IACollection <Element> const& collection ) ;
  6900.  
  6901. Copies the given collection to this collection.  copy() removes all elements 
  6902. from this collection, and adds the elements from the given collection. For 
  6903. information on how adding is done, see addAllFrom. 
  6904.  
  6905. Note:  The given collection may be of a concrete type other than the collection 
  6906. itself. In this case, copying implicitly performs a conversion. If, for 
  6907. example, the given collection is a bag and the collection itself is a set, 
  6908. elements with multiple occurrences in the copied bag will only occur once in 
  6909. the resulting set. 
  6910.  
  6911. Preconditions 
  6912.  
  6913. Because the elements are copied one by one, the following preconditions are 
  6914. tested for each individual copy operation: 
  6915.  
  6916.      If the collection is bounded and unique, the element or key must exist or 
  6917.       (numberOfElements() < maxNumberOfElements()). 
  6918.      If the collection is bounded and nonunique, 
  6919.       (numberOfElements() < maxNumberOfElements()). 
  6920.      If the collection is a map or a sorted map and contains an element with 
  6921.       the same key as the given element, this element must be equal to the 
  6922.       given element. 
  6923.  
  6924.  Side Effects 
  6925.  
  6926.      All cursors of this collection become undefined. 
  6927.      If any elements were copied, collection classes supporting Visual Builder 
  6928.       send a modifiedId notification. 
  6929.  
  6930.  Exceptions 
  6931.  
  6932.      IOutOfMemory 
  6933.      IFullException, if the collection is bounded 
  6934.      IKeyAlreadyExistsException, if the collection has unique keys. This 
  6935.       exception may be thrown, for example, when copying a bag into a map. 
  6936.  
  6937.  
  6938. ΓòÉΓòÉΓòÉ 5.1.2.27. dequeue ΓòÉΓòÉΓòÉ
  6939.  
  6940. void dequeue ( ) ;
  6941.  
  6942. void dequeue ( Element& element ) ;
  6943.  
  6944. Copies the first element of the collection to the given element, and removes it 
  6945. from the collection. 
  6946.  
  6947. Precondition 
  6948.  
  6949. The collection must not be empty. 
  6950.  
  6951. Side Effects 
  6952.  
  6953.      All cursors of this collection become undefined. 
  6954.      If the element is removed, collection classes supporting Visual Builder 
  6955.       send a modifiedId notification. 
  6956.  
  6957.  Exception 
  6958.  
  6959.  IEmptyException 
  6960.  
  6961.  
  6962. ΓòÉΓòÉΓòÉ 5.1.2.28. differenceWith ΓòÉΓòÉΓòÉ
  6963.  
  6964. void differenceWith ( CLASS_NAME const& collection ) ;
  6965.  
  6966. Makes the collection the difference between the collection and the given 
  6967. collection. The difference of A and B (A minus B) is the set of elements that 
  6968. are contained in A but not in B. 
  6969.  
  6970. The following rule applies for bags with duplicate elements: If bag P contains 
  6971. the element X m times and bag Q contains the element X n times, the difference 
  6972. of P and Q contains the element X m-n times if m > n, and zero times if m<=n. 
  6973.  
  6974. Side Effects 
  6975.  
  6976.      If any elements were removed, all cursors of this collection become 
  6977.       undefined. 
  6978.      If the element is removed, collection classes supporting Visual Builder 
  6979.       send a modifiedId notification. 
  6980.  
  6981.  
  6982. ΓòÉΓòÉΓòÉ 5.1.2.29. elementAt ΓòÉΓòÉΓòÉ
  6983.  
  6984. Element& elementAt ( ICursor const& cursor ) ;
  6985.  
  6986. Element const& elementAt ( ICursor const& cursor ) const;
  6987.  
  6988. Returns a reference to the element pointed to by the given cursor. 
  6989.  
  6990. Note:  For the version of elementAt() without the const suffix, do not 
  6991. manipulate the element or the key of the element in the collection in a way 
  6992. that changes the positioning property of the element. 
  6993.  
  6994. Precondition 
  6995.  
  6996. The cursor must belong to the collection and must point to an element of the 
  6997. collection. 
  6998.  
  6999. Exception 
  7000.  
  7001. ICursorInvalidException 
  7002.  
  7003.  
  7004. ΓòÉΓòÉΓòÉ 5.1.2.30. elementAtPosition ΓòÉΓòÉΓòÉ
  7005.  
  7006. Element const& elementAtPosition (
  7007.    IPosition position ) const;
  7008.  
  7009. Returns a reference to the element at the given position in the collection. 
  7010.  
  7011. Position 1 specifies the first element. 
  7012.  
  7013. Position must be a valid position in the collection; that is, 
  7014. (1 <= position <= numberOfElements()). 
  7015.  
  7016. Precondition 
  7017.  
  7018. (1 <= position <= numberOfElements()). 
  7019.  
  7020. Exception 
  7021.  
  7022. IPositionInvalidException 
  7023.  
  7024.  
  7025. ΓòÉΓòÉΓòÉ 5.1.2.31. elementWithKey ΓòÉΓòÉΓòÉ
  7026.  
  7027. Element& elementWithKey ( Key const& key ) ;
  7028.  
  7029. Element const& elementWithKey ( Key const& key ) const;
  7030.  
  7031. Returns a reference to an element specified by the key. 
  7032.  
  7033. Note: 
  7034.  
  7035.    1. For the version of elementWithKey() without a const suffix, do not 
  7036.       manipulate the element in the collection in a way that changes the 
  7037.       positioning property of the element. 
  7038.  
  7039.    2. If there are several elements with the given key, an arbitrary one is 
  7040.       returned. 
  7041.  
  7042.  Precondition 
  7043.  
  7044.  The given key is contained in the collection. 
  7045.  
  7046.  Exception 
  7047.  
  7048.  INotContainsKeyException 
  7049.  
  7050.  
  7051. ΓòÉΓòÉΓòÉ 5.1.2.32. enqueue ΓòÉΓòÉΓòÉ
  7052.  
  7053. void enqueue ( Element const& element ) ;
  7054.  
  7055. void enqueue ( Element const& element,
  7056.    ICursor& cursor ) ;
  7057.  
  7058. Adds the element to the collection, and sets the cursor to the added element. 
  7059. For ordinary queues, the given element is added as the last element. For 
  7060. priority queues, the element is added at a position determined by the ordering 
  7061. relation provided for the element or key type. 
  7062.  
  7063. Preconditions 
  7064.  
  7065.      The cursor must belong to the collection. 
  7066.      If the collection is bounded, 
  7067.       (numberOfElements() < maxNumberOfElements()). 
  7068.  
  7069.  Side Effects 
  7070.  
  7071.      All cursors of this collection except the given cursor become undefined. 
  7072.      If the element is added, collection classes supporting Visual Builder 
  7073.       send a modifiedId notification. 
  7074.  
  7075.  Exceptions 
  7076.  
  7077.      IOutOfMemory 
  7078.      ICursorInvalidException 
  7079.      IFullException, if the collection is bounded 
  7080.  
  7081.  
  7082. ΓòÉΓòÉΓòÉ 5.1.2.33. firstElement ΓòÉΓòÉΓòÉ
  7083.  
  7084. Element const& firstElement ( ) const;
  7085.  
  7086. Returns a reference to the first element of the collection. 
  7087.  
  7088. Precondition 
  7089.  
  7090. The collection must not be empty. 
  7091.  
  7092. Exception 
  7093.  
  7094. IEmptyException 
  7095.  
  7096.  
  7097. ΓòÉΓòÉΓòÉ 5.1.2.34. intersectionWith ΓòÉΓòÉΓòÉ
  7098.  
  7099. void intersectionWith ( CLASS_NAME const& collection ) ;
  7100.  
  7101. Makes the collection the intersection of the collection and the given 
  7102. collection. The intersection of A and B is the set of elements that is 
  7103. contained in both A and B. 
  7104.  
  7105. The following rule applies for bags with duplicate elements: If bag P contains 
  7106. the element X m times and bag Q contains the element X n times, the 
  7107. intersection of P and Q contains the element X MIN(m,n) times. 
  7108.  
  7109. Side Effects 
  7110.  
  7111.      If any elements were removed, all cursors of this collection become 
  7112.       undefined. 
  7113.      If any elements were removed, collection classes supporting Visual 
  7114.       Builder send a modifiedId notification. 
  7115.  
  7116.  
  7117. ΓòÉΓòÉΓòÉ 5.1.2.35. isBounded ΓòÉΓòÉΓòÉ
  7118.  
  7119. IBoolean isBounded ( ) const;
  7120.  
  7121. Returns True if the collection is bounded. 
  7122.  
  7123.  
  7124. ΓòÉΓòÉΓòÉ 5.1.2.36. isEmpty ΓòÉΓòÉΓòÉ
  7125.  
  7126. IBoolean isEmpty ( ) const;
  7127.  
  7128. Returns True if the collection is empty. 
  7129.  
  7130.  
  7131. ΓòÉΓòÉΓòÉ 5.1.2.37. isFirst ΓòÉΓòÉΓòÉ
  7132.  
  7133. IBoolean isFirst ( ICursor const& cursor ) const;
  7134.  
  7135. Returns True if the given cursor points to the first element of the collection. 
  7136.  
  7137. Preconditions 
  7138.  
  7139. The cursor must belong to the collection and must point to an element of the 
  7140. collection. 
  7141.  
  7142. Exception 
  7143.  
  7144. ICursorInvalidException 
  7145.  
  7146.  
  7147. ΓòÉΓòÉΓòÉ 5.1.2.38. isFull ΓòÉΓòÉΓòÉ
  7148.  
  7149. IBoolean isFull ( ) const;
  7150.  
  7151. Returns True if the collection is bounded and contains the maximum number of 
  7152. elements; that is, if (numberOfElements() == maxNumberOfElements()). 
  7153.  
  7154.  
  7155. ΓòÉΓòÉΓòÉ 5.1.2.39. isLast ΓòÉΓòÉΓòÉ
  7156.  
  7157. IBoolean isLast ( ICursor const& cursor ) const;
  7158.  
  7159. Returns True if the given cursor points to the last element of the collection. 
  7160.  
  7161. Preconditions 
  7162.  
  7163. The cursor must belong to the collection and must point to an element of the 
  7164. collection. 
  7165.  
  7166. Exception 
  7167.  
  7168. ICursorInvalidException 
  7169.  
  7170.  
  7171. ΓòÉΓòÉΓòÉ 5.1.2.40. key ΓòÉΓòÉΓòÉ
  7172.  
  7173. Key const& key ( Element const& element ) const;
  7174.  
  7175. Returns a reference to the key of the given element using the key() function 
  7176. provided for the element type. 
  7177.  
  7178.  
  7179. ΓòÉΓòÉΓòÉ 5.1.2.41. lastElement ΓòÉΓòÉΓòÉ
  7180.  
  7181. Element const& lastElement ( ) const;
  7182.  
  7183. Returns a reference to the last element of the collection. 
  7184.  
  7185. Precondition 
  7186.  
  7187. The collection must not be empty. 
  7188.  
  7189. Exception 
  7190.  
  7191. IEmptyException 
  7192.  
  7193.  
  7194. ΓòÉΓòÉΓòÉ 5.1.2.42. locate ΓòÉΓòÉΓòÉ
  7195.  
  7196. IBoolean locate ( Element const& element,
  7197.    ICursor& cursor ) const;
  7198.  
  7199. Locates an element in the collection that is equal to the given element. Sets 
  7200. the cursor to point to the element in the collection, or invalidates the cursor 
  7201. if no such element exists. 
  7202.  
  7203. If the collection contains several such elements, the first element in 
  7204. iteration order is located. 
  7205.  
  7206. Precondition 
  7207.  
  7208. The cursor must belong to the collection. 
  7209.  
  7210. Return Value 
  7211.  
  7212. Returns True if an element was found. 
  7213.  
  7214. Exceptions 
  7215.  
  7216. ICursorInvalidException 
  7217.  
  7218.  
  7219. ΓòÉΓòÉΓòÉ 5.1.2.43. locateElementWithKey ΓòÉΓòÉΓòÉ
  7220.  
  7221. IBoolean locateElementWithKey ( Key const& key,
  7222.    ICursor& cursor ) const;
  7223.  
  7224. Locates an element in the collection with the same key as the given key. Sets 
  7225. the cursor to point to the element in the collection, or invalidates the cursor 
  7226. if no such element exists. 
  7227.  
  7228. If the collection contains several such elements, the first element in 
  7229. iteration order is located. 
  7230.  
  7231. Precondition 
  7232.  
  7233. The cursor must belong to the collection. 
  7234.  
  7235. Return Value 
  7236.  
  7237. Returns True if an element was found. 
  7238.  
  7239. Exception 
  7240.  
  7241. ICursorInvalidException 
  7242.  
  7243.  
  7244. ΓòÉΓòÉΓòÉ 5.1.2.44. locateFirst ΓòÉΓòÉΓòÉ
  7245.  
  7246. IBoolean locateFirst ( Element const& element,
  7247.    ICursor& cursor ) const;
  7248.  
  7249. Locates the first element in iteration order in the collection that is equal to 
  7250. the given element. Sets the cursor to the located element, or invalidates the 
  7251. cursor if no such element exists. 
  7252.  
  7253. Precondition 
  7254.  
  7255. The cursor must belong to the collection. 
  7256.  
  7257. Return Value 
  7258.  
  7259. Returns True if an element was found. 
  7260.  
  7261. Exception 
  7262.  
  7263. ICursorInvalidException 
  7264.  
  7265.  
  7266. ΓòÉΓòÉΓòÉ 5.1.2.45. locateLast ΓòÉΓòÉΓòÉ
  7267.  
  7268. IBoolean locateLast ( Element const& element,
  7269.    ICursor& cursor ) const;
  7270.  
  7271. Locates the last element in iteration order in the collection that is equal to 
  7272. the given element. Sets the cursor to the located element, or invalidates the 
  7273. cursor if no such element exists. 
  7274.  
  7275. Precondition 
  7276.  
  7277. The cursor must belong to the collection. 
  7278.  
  7279. Return Value 
  7280.  
  7281. Returns True if an element was found. 
  7282.  
  7283. Exception 
  7284.  
  7285. ICursorInvalidException 
  7286.  
  7287.  
  7288. ΓòÉΓòÉΓòÉ 5.1.2.46. locateNext ΓòÉΓòÉΓòÉ
  7289.  
  7290. IBoolean locateNext ( Element const& element,
  7291.    ICursor& cursor ) const;
  7292.  
  7293. Locates the next element in iteration order in the collection that is equal to 
  7294. the given element, starting at the element next to the one pointed to by the 
  7295. given cursor. Sets the cursor to point to the element in the collection. The 
  7296. cursor is invalidated if the end of the collection is reached and no more 
  7297. occurrences of the given element are left to be visited. 
  7298.  
  7299. Note:  If you code a call to locateFirst() and a set of calls to locateNext(), 
  7300. each occurrence of an element will be visited exactly once in iteration order. 
  7301.  
  7302. Precondition 
  7303.  
  7304. The cursor must belong to the collection and must point to an element of the 
  7305. collection. 
  7306.  
  7307. Return Value 
  7308.  
  7309. Returns True if an element was found. 
  7310.  
  7311. Exception 
  7312.  
  7313. ICursorInvalidException 
  7314.  
  7315.  
  7316. ΓòÉΓòÉΓòÉ 5.1.2.47. locateNextElementWithKey ΓòÉΓòÉΓòÉ
  7317.  
  7318. IBoolean locateNextElementWithKey (
  7319.    Key const& key, ICursor& cursor ) const;
  7320.  
  7321. Locates the next element in iteration order in the collection with the given 
  7322. key, starting at the element next to the one pointed to by the given cursor. 
  7323. Sets the cursor to point to the element in the collection. The cursor is 
  7324. invalidated if the end of the collection is reached and no more occurrences of 
  7325. such an element are left to be visited. 
  7326.  
  7327. Note:  If you code a call to locateFirst() and a set of calls to 
  7328. locateNextElementWithKey(), each occurrence of an element will be visited 
  7329. exactly once in iteration order. 
  7330.  
  7331. Preconditions 
  7332.  
  7333. The cursor must belong to the collection and must point to an element of the 
  7334. collection. 
  7335.  
  7336. Return Value 
  7337.  
  7338. Returns True if an element was found. 
  7339.  
  7340. Exception 
  7341.  
  7342. ICursorInvalidException 
  7343.  
  7344.  
  7345. ΓòÉΓòÉΓòÉ 5.1.2.48. locateOrAdd ΓòÉΓòÉΓòÉ
  7346.  
  7347. IBoolean locateOrAdd ( Element const& element ) ;
  7348.  
  7349. IBoolean locateOrAdd ( Element const& element,
  7350.    ICursor& cursor ) ;
  7351.  
  7352. Locates an element in the collection that is equal to the given element.  (See 
  7353. locate for details on locate().) If no such element is found, locateOrAdd() 
  7354. adds the element as described in add. The cursor is set to the located or added 
  7355. element. 
  7356.  
  7357. Note:  This method may be more efficient than using locate() followed by a 
  7358. conditionally called add(). 
  7359.  
  7360. Preconditions 
  7361.  
  7362.      The cursor must belong to the collection. 
  7363.      If the collection is a map or a sorted map and contains an element with 
  7364.       the same key as the given element, this element must be equal to the 
  7365.       given element. 
  7366.      The element or key must exist, or 
  7367.       (numberOfElements() < maxNumberOfElements()). 
  7368.  
  7369.  Side Effects 
  7370.  
  7371.      If the element was added, all cursors of this collection, except the 
  7372.       given cursor, become undefined. 
  7373.      If the element was added, collection classes supporting Visual Builder 
  7374.       send an addedId notification. 
  7375.  
  7376.  Return Value 
  7377.  
  7378.  Returns True if the element was located.  Returns False if the element could 
  7379.  not be located but had to be added. 
  7380.  
  7381.  Exceptions 
  7382.  
  7383.      IOutOfMemory 
  7384.      ICursorInvalidException 
  7385.      IFullException, if the collection is bounded 
  7386.      IKeyAlreadyExistsException, if the collection is a map or a sorted map 
  7387.  
  7388.  
  7389. ΓòÉΓòÉΓòÉ 5.1.2.49. locateOrAddElementWithKey ΓòÉΓòÉΓòÉ
  7390.  
  7391. IBoolean locateOrAddElementWithKey (
  7392.    Element const& element ) ;
  7393.  
  7394. IBoolean locateOrAddElementWithKey (
  7395.    Element const& element; ICursor& cursor ) ;
  7396.  
  7397. Locates an element in the collection with the given key as described for the 
  7398. locateElementWithKey() function. If no such element exists, 
  7399. locateOrAddElementWithKey() adds the element as described in add. The cursor is 
  7400. set to the located or added element. 
  7401.  
  7402. Preconditions 
  7403.  
  7404.      If the collection is bounded and an element with the given key is not 
  7405.       already contained, (numberOfElements() < maxNumberOfElements()). 
  7406.      The cursor must belong to the collection. 
  7407.  
  7408.  Side Effects 
  7409.  
  7410.      If the element was added, all cursors of this collection, except the 
  7411.       given cursor, become undefined. 
  7412.      If the element was added, collection classes supporting Visual Builder 
  7413.       send an addedId notification. 
  7414.  
  7415.  Return Value 
  7416.  
  7417.  Returns True if the element was located.  Returns False if the element could 
  7418.  not be located but had to be added. 
  7419.  
  7420.  Exceptions 
  7421.  
  7422.      IOutOfMemory 
  7423.      ICursorInvalidException 
  7424.      IFullException, if the collection is bounded 
  7425.  
  7426.  
  7427. ΓòÉΓòÉΓòÉ 5.1.2.50. locatePrevious ΓòÉΓòÉΓòÉ
  7428.  
  7429. IBoolean locatePrevious ( Element const& element,
  7430.    ICursor& cursor ) const;
  7431.  
  7432. Locates the previous element in iteration order that is equal to the given 
  7433. element, beginning at the element previous to the one specified by the given 
  7434. cursor and moving in reverse iteration order through the elements. Sets the 
  7435. cursor to the located element, or invalidates the cursor if no such element 
  7436. exists. 
  7437.  
  7438. Preconditions 
  7439.  
  7440. The cursor must belong to the collection and must point to an element of the 
  7441. collection. 
  7442.  
  7443. Return Value 
  7444.  
  7445. Returns True if an element was found. 
  7446.  
  7447. Exceptions 
  7448.  
  7449. ICursorInvalidException 
  7450.  
  7451.  
  7452. ΓòÉΓòÉΓòÉ 5.1.2.51. maxNumberOfElements ΓòÉΓòÉΓòÉ
  7453.  
  7454. INumber maxNumberOfElements ( ) const;
  7455.  
  7456. Returns the maximum number of elements the collection can contain. 
  7457.  
  7458. Precondition 
  7459.  
  7460. The collection is bounded. 
  7461.  
  7462. Exceptions 
  7463.  
  7464. INotBoundedException 
  7465.  
  7466.  
  7467. ΓòÉΓòÉΓòÉ 5.1.2.52. newCursor ΓòÉΓòÉΓòÉ
  7468.  
  7469. Cursor* newCursor ( ) const;
  7470.  
  7471. Creates a cursor for the collection and returns a pointer to the cursor. The 
  7472. cursor is initially not valid. 
  7473.  
  7474. Exception 
  7475.  
  7476. IOutOfMemory 
  7477.  
  7478.  
  7479. ΓòÉΓòÉΓòÉ 5.1.2.53. numberOfDifferentElements ΓòÉΓòÉΓòÉ
  7480.  
  7481. INumber numberOfDifferentElements ( ) const;
  7482.  
  7483. Returns the number of different elements in the collection. 
  7484.  
  7485.  
  7486. ΓòÉΓòÉΓòÉ 5.1.2.54. numberOfDifferentKeys ΓòÉΓòÉΓòÉ
  7487.  
  7488. INumber numberOfDifferentKeys ( ) const;
  7489.  
  7490. Returns the number of different keys in the collection. 
  7491.  
  7492.  
  7493. ΓòÉΓòÉΓòÉ 5.1.2.55. numberOfElements ΓòÉΓòÉΓòÉ
  7494.  
  7495. INumber numberOfElements ( ) const;
  7496.  
  7497. Returns the number of elements the collection contains. 
  7498.  
  7499.  
  7500. ΓòÉΓòÉΓòÉ 5.1.2.56. numberOfElementsWithKey ΓòÉΓòÉΓòÉ
  7501.  
  7502. INumber numberOfElementsWithKey (
  7503.    Key const& key ) const;
  7504.  
  7505. Returns the number of elements in the collection with the given key. 
  7506.  
  7507.  
  7508. ΓòÉΓòÉΓòÉ 5.1.2.57. numberOfOccurrences ΓòÉΓòÉΓòÉ
  7509.  
  7510. INumber numberOfOccurrences (
  7511.    Element const& element ) const;
  7512.  
  7513. Returns the number of occurrences of the given element in the collection. 
  7514.  
  7515.  
  7516. ΓòÉΓòÉΓòÉ 5.1.2.58. pop ΓòÉΓòÉΓòÉ
  7517.  
  7518. void pop ( ) ;
  7519.  
  7520. void pop ( Element& element ) ;
  7521.  
  7522. Copies the last element of the collection to the given element, and removes it 
  7523. from the collection. 
  7524.  
  7525. Precondition 
  7526.  
  7527. The collection must not be empty. 
  7528.  
  7529. Side Effects 
  7530.  
  7531.      All cursors of this collection become undefined. 
  7532.      If the element was removed from the collection, collection classes 
  7533.       supporting Visual Builder send a removedId notification. 
  7534.  
  7535.  Exception 
  7536.  
  7537.  IEmptyException 
  7538.  
  7539.  
  7540. ΓòÉΓòÉΓòÉ 5.1.2.59. position ΓòÉΓòÉΓòÉ
  7541.  
  7542. IPosition position ( ICursor const& cursor) const;
  7543.  
  7544. Determines the position of the current element. Position 1 specifies the first 
  7545. element. 
  7546.  
  7547. Precondition 
  7548.  
  7549. The cursor must belong to the collection, and the cursor must point to an 
  7550. element of the collection. 
  7551.  
  7552. Exception 
  7553.  
  7554. ICursorInvalidException 
  7555.  
  7556.  
  7557. ΓòÉΓòÉΓòÉ 5.1.2.60. push ΓòÉΓòÉΓòÉ
  7558.  
  7559. void push ( Element const& element ) ;
  7560.  
  7561. void push ( Element const& element,
  7562.    ICursor& cursor ) ;
  7563.  
  7564. Adds the element to the collection as the last element (as defined for add), 
  7565. and sets the cursor to the added element. 
  7566.  
  7567. Preconditions 
  7568.  
  7569.      The cursor must belong to the collection. 
  7570.      If the collection is bounded, 
  7571.       (numberOfElements() < maxNumberOfElements()). 
  7572.  
  7573.  Side Effects 
  7574.  
  7575.      All cursors of this collection, except the given cursor, become 
  7576.       undefined. 
  7577.      If the element was added to the collection, collection classes supporting 
  7578.       Visual Builder send an addedId notification. 
  7579.  
  7580.  Exceptions 
  7581.  
  7582.      IOutOfMemory 
  7583.      ICursorInvalidException 
  7584.      IFullException, if the collection is bounded 
  7585.  
  7586.  
  7587. ΓòÉΓòÉΓòÉ 5.1.2.61. remove ΓòÉΓòÉΓòÉ
  7588.  
  7589. IBoolean remove ( Element const& element ) ;
  7590.  
  7591. Removes an element in the collection that is equal to the given element. If no 
  7592. such element exists, the collection remains unchanged. In collections with 
  7593. nonunique elements, an arbitrary occurrence of the given element will be 
  7594. removed. Element destructors are called as described in removeAt. 
  7595.  
  7596. Side Effects 
  7597.  
  7598.      If an element was removed, all cursors of this collection become 
  7599.       undefined. 
  7600.      If an element was removed, collection classes supporting Visual Builder 
  7601.       send a removedId notification. 
  7602.  
  7603.  Return Value 
  7604.  
  7605.  Returns True if an element was removed. 
  7606.  
  7607.  
  7608. ΓòÉΓòÉΓòÉ 5.1.2.62. removeAll ΓòÉΓòÉΓòÉ
  7609.  
  7610. void removeAll ( ) ;
  7611.  
  7612. Removes all elements from the collection. Element destructors are called as 
  7613. described in removeAt. 
  7614.  
  7615. Side Effects 
  7616.  
  7617.      All cursors of this collection become undefined. 
  7618.      Collection classes supporting Visual Builder send a modifiedId 
  7619.       notification. 
  7620.  
  7621.  
  7622. ΓòÉΓòÉΓòÉ 5.1.2.63. removeAll ΓòÉΓòÉΓòÉ
  7623.  
  7624. INumber removeAll (
  7625.    IBoolean (*property) (Element const&, void*),
  7626.    void* additionalArgument = 0 ) ;
  7627.  
  7628. Removes all elements from this collection for which the given property function 
  7629. returns True. Additional arguments can be passed to the given property function 
  7630. using additionalArgument. The additional argument defaults to zero if no 
  7631. additional argument is given. Element destructors are called as described in 
  7632. removeAt. 
  7633.  
  7634. Side Effects 
  7635.  
  7636.      If any elements were removed, all cursors of this collection become 
  7637.       undefined. 
  7638.      If any elements were removed, collection classes supporting Visual 
  7639.       Builder send a modifiedId notification. 
  7640.  
  7641.  Return Value 
  7642.  
  7643.  The number of elements removed. 
  7644.  
  7645.  
  7646. ΓòÉΓòÉΓòÉ 5.1.2.64. removeAllElementsWithKey ΓòÉΓòÉΓòÉ
  7647.  
  7648. INumber removeAllElementsWithKey (
  7649.    Key const& key ) ;
  7650.  
  7651. Removes all elements from the collection with the same key as the given key. 
  7652. Element destructors are called as described in removeAt. 
  7653.  
  7654. Side Effects 
  7655.  
  7656.      If any elements were removed, all cursors of this collection become 
  7657.       undefined. 
  7658.      If any elements were removed, collection classes supporting Visual 
  7659.       Builder send a removedId notification. 
  7660.  
  7661.  Return Value 
  7662.  
  7663.  The number of elements removed. 
  7664.  
  7665.  
  7666. ΓòÉΓòÉΓòÉ 5.1.2.65. removeAllOccurrences ΓòÉΓòÉΓòÉ
  7667.  
  7668. INumber removeAllOccurrences ( Element const& element ) ;
  7669.  
  7670. Removes all elements from the collection that are equal to the given element, 
  7671. and returns the number of elements removed. Element destructors are called as 
  7672. described in removeAt. 
  7673.  
  7674. Side Effects 
  7675.  
  7676.      If any elements were removed, all cursors of this collection become 
  7677.       undefined. 
  7678.      If any elements were removed, collection classes supporting Visual 
  7679.       Builder send a modifiedId notification. 
  7680.  
  7681.  
  7682. ΓòÉΓòÉΓòÉ 5.1.2.66. removeAt ΓòÉΓòÉΓòÉ
  7683.  
  7684. void removeAt ( ICursor& cursor ) ;
  7685.  
  7686. Removes the element pointed to by the given cursor. The given cursor is 
  7687. invalidated. 
  7688.  
  7689. Note:  It is undefined whether the destructor for the removed element is called 
  7690. or whether the element will only be destructed with the collection destructor. 
  7691. For example, in a tabular implementation, a destructor will only be called when 
  7692. the whole collection is destructed, not when a single element is removed. 
  7693.  
  7694. Preconditions 
  7695.  
  7696. The cursor must belong to the collection and must point to an element of the 
  7697. collection. 
  7698.  
  7699. Side Effects 
  7700.  
  7701.      All cursors of this collection, except the given cursor, become 
  7702.       undefined. 
  7703.      If an element was removed, collection classes supporting Visual Builder 
  7704.       send a removedId notification. 
  7705.  
  7706.  Exception 
  7707.  
  7708.  ICursorInvalidException 
  7709.  
  7710.  
  7711. ΓòÉΓòÉΓòÉ 5.1.2.67. removeAtPosition ΓòÉΓòÉΓòÉ
  7712.  
  7713. void removeAtPosition ( IPosition position ) ;
  7714.  
  7715. Removes the element from the collection that is at the given position. Element 
  7716. destructors are called as described in removeAt. 
  7717.  
  7718. The first element of the collection has position 1. 
  7719.  
  7720. Precondition 
  7721.  
  7722. Position must be a valid position in the collection; that is, 
  7723. (1 <= position <= numberOfElements()). 
  7724.  
  7725. Side Effects 
  7726.  
  7727.      All cursors of this collection become undefined. 
  7728.      Collection classes supporting Visual Builder send a removedId 
  7729.       notification. 
  7730.  
  7731.  Exception 
  7732.  
  7733.  IPositionInvalidException 
  7734.  
  7735.  
  7736. ΓòÉΓòÉΓòÉ 5.1.2.68. removeElementWithKey ΓòÉΓòÉΓòÉ
  7737.  
  7738. IBoolean removeElementWithKey ( Key const& key ) ;
  7739.  
  7740. Removes an element from the collection with the same key as the given key. If 
  7741. no such element exists, the collection remains unchanged. In collections with 
  7742. nonunique elements, an arbitrary occurrence of such an element will be removed. 
  7743. Element destructors are called as described in removeAt. 
  7744.  
  7745. Side Effects 
  7746.  
  7747.      If an element was removed, all cursors of this collection become 
  7748.       undefined. 
  7749.      If an element was removed, collection classes supporting Visual Builder 
  7750.       send a removedId notification. 
  7751.  
  7752.  Return Value 
  7753.  
  7754.  Returns True if an element was removed. 
  7755.  
  7756.  
  7757. ΓòÉΓòÉΓòÉ 5.1.2.69. removeFirst ΓòÉΓòÉΓòÉ
  7758.  
  7759. void removeFirst ( ) ;
  7760.  
  7761. Removes the first element from the collection. Element destructors are called 
  7762. as described in removeAt. 
  7763.  
  7764. Precondition 
  7765.  
  7766. The collection must not be empty. 
  7767.  
  7768. Side Effects 
  7769.  
  7770.      All cursors of this collection become undefined. 
  7771.      If an element was removed, collection classes supporting Visual Builder 
  7772.       send a removedId notification. 
  7773.  
  7774.  Exception 
  7775.  
  7776.  IEmptyException 
  7777.  
  7778.  
  7779. ΓòÉΓòÉΓòÉ 5.1.2.70. removeLast ΓòÉΓòÉΓòÉ
  7780.  
  7781. void removeLast ( ) ;
  7782.  
  7783. Removes the last element from the collection. Element destructors are called as 
  7784. described in removeAt. 
  7785.  
  7786. Precondition 
  7787.  
  7788. The collection must not be empty. 
  7789.  
  7790. Side Effects 
  7791.  
  7792.      All cursors of this collection become undefined. 
  7793.      If an element was removed, collection classes supporting Visual Builder 
  7794.       send a removedId notification. 
  7795.  
  7796.  Exception 
  7797.  
  7798.  IEmptyException 
  7799.  
  7800.  
  7801. ΓòÉΓòÉΓòÉ 5.1.2.71. replaceAt ΓòÉΓòÉΓòÉ
  7802.  
  7803. void replaceAt ( ICursor const& cursor,
  7804.    Element const& element ) ;
  7805.  
  7806. Replaces the element pointed to by the cursor with the given element. 
  7807.  
  7808. Preconditions 
  7809.  
  7810.      The cursor must belong to the collection and must point to an element of 
  7811.       the collection. 
  7812.      The given element must have the same positioning property as the replaced 
  7813.       element. 
  7814.  
  7815.  Side Effect 
  7816.  
  7817.  Collection classes supporting Visual Builder send a replacedId notification. 
  7818.  
  7819.  Exceptions 
  7820.  
  7821.      ICursorInvalidException 
  7822.      IInvalidReplacementException 
  7823.  
  7824.  
  7825. ΓòÉΓòÉΓòÉ 5.1.2.72. replaceElementWithKey ΓòÉΓòÉΓòÉ
  7826.  
  7827. IBoolean replaceElementWithKey ( Element const& element ) ;
  7828.  
  7829. IBoolean replaceElementWithKey ( Element const& element,
  7830.    ICursor& cursor ) ;
  7831.  
  7832. Replaces an element with the same key as the given element by the given 
  7833. element, and sets the cursor to this element. If no such element exists, it 
  7834. invalidates the cursor. In collections with nonunique elements, an arbitrary 
  7835. occurrence of such an element will be replaced. 
  7836.  
  7837. Precondition 
  7838.  
  7839. The cursor must belong to the collection. 
  7840.  
  7841. Side Effect 
  7842.  
  7843. Collection classes supporting Visual Builder send a replacedId notification. 
  7844.  
  7845. Return Value 
  7846.  
  7847. Returns True if an element was replaced. 
  7848.  
  7849. Exceptions 
  7850.  
  7851. ICursorInvalidException 
  7852.  
  7853.  
  7854. ΓòÉΓòÉΓòÉ 5.1.2.73. setToFirst ΓòÉΓòÉΓòÉ
  7855.  
  7856. IBoolean setToFirst ( ICursor& cursor ) const;
  7857.  
  7858. Sets the cursor to the first element of the collection in iteration order. If 
  7859. the collection is empty (if no first element exists), it invalidates the given 
  7860. cursor. 
  7861.  
  7862. Precondition 
  7863.  
  7864. The cursor must belong to the collection. 
  7865.  
  7866. Return Value 
  7867.  
  7868. Returns True if the collection is not empty. 
  7869.  
  7870. Exception 
  7871.  
  7872. ICursorInvalidException 
  7873.  
  7874.  
  7875. ΓòÉΓòÉΓòÉ 5.1.2.74. setToLast ΓòÉΓòÉΓòÉ
  7876.  
  7877. IBoolean setToLast ( ICursor& cursor ) const;
  7878.  
  7879. Sets the cursor to the last element of the collection in iteration order. If 
  7880. the collection is empty (if no last element exists), the given cursor is no 
  7881. longer valid. 
  7882.  
  7883. Precondition 
  7884.  
  7885. The cursor must belong to the collection. 
  7886.  
  7887. Return Value 
  7888.  
  7889. Returns True if the collection is not empty. 
  7890.  
  7891. Exceptions 
  7892.  
  7893. ICursorInvalidException 
  7894.  
  7895.  
  7896. ΓòÉΓòÉΓòÉ 5.1.2.75. setToNext ΓòÉΓòÉΓòÉ
  7897.  
  7898. IBoolean setToNext ( ICursor& cursor ) const;
  7899.  
  7900. Sets the cursor to the next element in the collection in iteration order. If no 
  7901. more elements are left to be visited, the given cursor will no longer be valid. 
  7902.  
  7903. Precondition 
  7904.  
  7905. The cursor must belong to the collection and must point to an element. 
  7906.  
  7907. Return Value 
  7908.  
  7909. Returns True if there is a next element. 
  7910.  
  7911. Exceptions 
  7912.  
  7913. ICursorInvalidException 
  7914.  
  7915.  
  7916. ΓòÉΓòÉΓòÉ 5.1.2.76. setToNextDifferentElement ΓòÉΓòÉΓòÉ
  7917.  
  7918. IBoolean setToNextDifferentElement (
  7919.    ICursor& cursor ) const;
  7920.  
  7921. Sets the cursor to the next element in iteration order in the collection that 
  7922. is different from the element pointed to by the given cursor. If no more 
  7923. elements are left to be visited, the given cursor will no longer be valid. 
  7924.  
  7925. Precondition 
  7926.  
  7927. The cursor must belong to the collection and must point to an element of the 
  7928. collection. 
  7929.  
  7930. Return Value 
  7931.  
  7932. Returns True if a subsequent element was found that is different. 
  7933.  
  7934. Exception 
  7935.  
  7936. ICursorInvalidException 
  7937.  
  7938.  
  7939. ΓòÉΓòÉΓòÉ 5.1.2.77. setToNextWithDifferentKey ΓòÉΓòÉΓòÉ
  7940.  
  7941. IBoolean setToNextWithDifferentKey ( ICursor& cursor ) const;
  7942.  
  7943. Sets the cursor to the next element in the collection in iteration order with a 
  7944. key different from the key of the element pointed to by the given cursor. If no 
  7945. such element exists, the given cursor is no longer valid. 
  7946.  
  7947. Preconditions 
  7948.  
  7949. The cursor must belong to the collection and must point to an element of the 
  7950. collection. 
  7951.  
  7952. Return Value 
  7953.  
  7954. Returns True if a subsequent element was found whose key is different from the 
  7955. current key. 
  7956.  
  7957. Exception 
  7958.  
  7959. ICursorInvalidException 
  7960.  
  7961.  
  7962. ΓòÉΓòÉΓòÉ 5.1.2.78. setToPosition ΓòÉΓòÉΓòÉ
  7963.  
  7964. void setToPosition ( IPosition position,
  7965.    ICursor& cursor ) const;
  7966.  
  7967. Sets the cursor to the element at the given position. Position 1 specifies the 
  7968. first element. 
  7969.  
  7970. Precondition 
  7971.  
  7972.      The cursor must belong to the collection. 
  7973.      Position must be a valid position in the collection; that is, 
  7974.       (1 <= position <= numberOfElements()). 
  7975.  
  7976.  Exceptions 
  7977.  
  7978.      ICursorInvalidException 
  7979.      IPositionInvalidException 
  7980.  
  7981.  
  7982. ΓòÉΓòÉΓòÉ 5.1.2.79. setToPrevious ΓòÉΓòÉΓòÉ
  7983.  
  7984. IBoolean setToPrevious ( ICursor& cursor ) const;
  7985.  
  7986. Sets the cursor to the previous element in iteration order, or invalidates the 
  7987. cursor if no such element exists. 
  7988.  
  7989. Preconditions 
  7990.  
  7991. The cursor must belong to the collection and must point to an element of the 
  7992. collection. 
  7993.  
  7994. Return Value 
  7995.  
  7996. Returns True if a previous element exists. 
  7997.  
  7998. Exception 
  7999.  
  8000. ICursorInvalidException 
  8001.  
  8002.  
  8003. ΓòÉΓòÉΓòÉ 5.1.2.80. sort ΓòÉΓòÉΓòÉ
  8004.  
  8005. void sort ( long (*comparisonFunction)
  8006.    (Element const& element1, Element const& element2) );
  8007.  
  8008. Sorts the collection so that the elements occur in ascending order. The 
  8009. relation of two elements is defined by the comparisonFunction, which you 
  8010. provide. 
  8011.  
  8012. Note:  The comparisonFunction must deliver a result according to the following 
  8013. rules: 
  8014.  
  8015.  >0        if (element1 > element2) 
  8016.  0         if (element1 == element2) 
  8017.  <0        if (element1 < element2) 
  8018.  
  8019.  Side Effects 
  8020.  
  8021.      All cursors of this collection become undefined. 
  8022.      Collection classes supporting Visual Builder send a modifiedId 
  8023.       notification. 
  8024.  
  8025.  
  8026. ΓòÉΓòÉΓòÉ 5.1.2.81. top ΓòÉΓòÉΓòÉ
  8027.  
  8028. Element const& top ( ) const;
  8029.  
  8030. Returns a reference to the last element of the collection. 
  8031.  
  8032. Precondition 
  8033.  
  8034. The collection must not be empty. 
  8035.  
  8036. Exception 
  8037.  
  8038. IEmptyException 
  8039.  
  8040.  
  8041. ΓòÉΓòÉΓòÉ 5.1.2.82. unionWith ΓòÉΓòÉΓòÉ
  8042.  
  8043. void unionWith (
  8044.    CLASS_NAME const& collection ) ;
  8045.  
  8046. Makes the collection the union of the collection and the given collection. The 
  8047. union of A and B is the set of elements that are members of A or B or both. 
  8048.  
  8049. The following rule applies for bags with duplicate elements: If bag P contains 
  8050. the element X m times and bag Q contains the element X n times, the union of P 
  8051. and Q contains the element X m+n times. 
  8052.  
  8053. Preconditions 
  8054.  
  8055. Because the elements from the given collection are added to the collection one 
  8056. by one, the following preconditions are tested for each individual add 
  8057. operation : 
  8058.  
  8059.      If the collection is bounded and unique, the element or key must exist or 
  8060.       (numberOfElements() < maxNumberOfElements()). 
  8061.      If the collection is bounded and nonunique, 
  8062.       (numberOfElements() < maxNumberOfElements()). 
  8063.      If the collection is a map or a sorted map and contains an element with 
  8064.       the same key as the given element, this element must be equal to the 
  8065.       given element. 
  8066.  
  8067.  Side Effects 
  8068.  
  8069.      If any elements were added to the collection, all cursors of this 
  8070.       collection become undefined. 
  8071.      Collection classes supporting Visual Builder send a modifiedId 
  8072.       notification. 
  8073.  
  8074.  Exceptions 
  8075.  
  8076.      IOutOfMemory 
  8077.      IFullException, if the collection is bounded 
  8078.      IKeyAlreadyExistsException, if the collection is a map or a sorted map 
  8079.  
  8080.  
  8081. ΓòÉΓòÉΓòÉ 5.1.3. Bag ΓòÉΓòÉΓòÉ
  8082.  
  8083. Description 
  8084.  
  8085. Derivation 
  8086.  
  8087. Variants/Header Files 
  8088.  
  8089. Members 
  8090.  
  8091. Template Arguments and Required Functions 
  8092.  
  8093. Abstract/Reference Classes 
  8094.  
  8095. To close all the panels in a chapter, double-click on this panel's system menu. 
  8096.  
  8097.  
  8098. ΓòÉΓòÉΓòÉ 5.1.3.1. Class Description - Bag ΓòÉΓòÉΓòÉ
  8099.  
  8100. A bag is an unordered collection of zero or more elements with no key. 
  8101. Multiple elements are supported.  A request to add an element that already 
  8102. exists is not ignored. 
  8103.  
  8104. Figure Combination of Flat Collection Properties gives an overview of the 
  8105. properties of a bag and its relationship to other flat collections. 
  8106.  
  8107. An example of using a bag is a program for entering observations on species of 
  8108. plants and animals found in a river.  Each time you spot a plant or animal in 
  8109. the river, you enter the name of the species into the collection.  If you spot 
  8110. a species twice during an observation period, the species is added twice, 
  8111. because a bag supports multiple elements.  You can locate the name of a species 
  8112. that you have observed, and you can determine the number of observations of 
  8113. that species, but you cannot sort the collection by species, because a bag is 
  8114. an unordered collection.  If you want to sort the elements of a bag, use a 
  8115. sorted bag instead. 
  8116.  
  8117. The following rule applies for duplicates: If bag P contains the element X m 
  8118. times and bag Q contains the element X n times, then the union of P and Q 
  8119. contains the element X m+n times, the intersection of P and Q contains the 
  8120. element X MIN(m,n) times, and the difference of P and Q contains the element X 
  8121. m-n times if m is > n, and zero times if m is <= n. 
  8122.  
  8123.  
  8124. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  8125.  
  8126. Collection 
  8127.  
  8128.   Equality Collection
  8129.    Bag
  8130.  
  8131.  
  8132. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  8133.  
  8134. IBag, the first class in the table below, is the default implementation 
  8135. variant. If you want to use polymorphism, you can replace the following class 
  8136. implementation variants by the reference class. 
  8137.  
  8138. To use Visual Builder features with your collections, change the name of the 
  8139. desired collection class template in the list below from I... to IV..., and use 
  8140. the ivbag.h header file instead of the header file that you would normally use 
  8141. without Visual Builder. 
  8142.  
  8143. Class Name                    Header File  Implementation Variant
  8144.  
  8145. IBag                          ibag.h       AVL tree
  8146. IGBag                         ibag.h       AVL tree
  8147.  
  8148. IBagOnBSTKeySortedSet         ibagbst.h    B* tree
  8149. IGBagOnBSTKeySortedSet        ibagbst.h    B* tree
  8150.  
  8151. IBagOnSortedLinkedSequence    ibagsls.h    Linked sequence
  8152. IGBagOnSortedLinkedSequence   ibagsls.h    Linked sequence
  8153.  
  8154. IBagOnSortedTabularSequence   ibagsts.h    Tabular sequence
  8155. IGBagOnSortedTabularSequence  ibagsts.h    Tabular sequence
  8156.  
  8157. IBagOnSortedDilutedSequence   ibagsds.h    Diluted sequence
  8158. IGBagOnSortedDilutedSequence  ibagsds.h    Diluted sequence
  8159.  
  8160. IBagOnHashKeySet              ibaghks.h    Hash table
  8161. IGBagOnHashKeySet             ibaghks.h    Hash table
  8162.  
  8163.  
  8164. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  8165.  
  8166. All member functions of flat collections are described in Introduction to Flat 
  8167. Collections. The following members are provided for bag: 
  8168.  
  8169.      Constructor 
  8170.      Copy Constructor 
  8171.      Destructor 
  8172.      operator!= 
  8173.      operator= 
  8174.      operator== 
  8175.      add 
  8176.      addAllFrom 
  8177.      addDifference 
  8178.      addIntersection 
  8179.      addUnion 
  8180.      allElementsDo 
  8181.      anyElement 
  8182.      contains 
  8183.      containsAllFrom 
  8184.      differenceWith 
  8185.      elementAt 
  8186.      intersectionWith 
  8187.      isBounded 
  8188.      isEmpty 
  8189.      isFull 
  8190.      locate 
  8191.      locateNext 
  8192.      locateOrAdd 
  8193.      maxNumberOfElements 
  8194.      newCursor 
  8195.      numberOfDifferentElements 
  8196.      numberOfElements 
  8197.      numberOfOccurrences 
  8198.      remove 
  8199.      removeAllOccurrences 
  8200.      removeAll 
  8201.      removeAt 
  8202.      replaceAt 
  8203.      setToFirst 
  8204.      setToNext 
  8205.      setToNextDifferentElement 
  8206.      unionWith 
  8207.  
  8208.  Bag also defines a cursor that inherits from IElementCursor.  The members for 
  8209.  IElementCursor are described in Cursor. 
  8210.  
  8211.  
  8212. ΓòÉΓòÉΓòÉ 5.1.3.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  8213.  
  8214. The following implementation variants are defined for bags: 
  8215.  
  8216.      Bag 
  8217.      Bag on b* key sorted set 
  8218.      Bag on sorted linked sequence 
  8219.      Bag on sorted tabular sequence 
  8220.      Bag on sorted diluted sequence 
  8221.      Bag on hash key set 
  8222.  
  8223.  
  8224. ΓòÉΓòÉΓòÉ 5.1.3.2.1. Bag ΓòÉΓòÉΓòÉ
  8225.  
  8226. IBag  <Element>
  8227. IGBag <Element, ECOps>
  8228.  
  8229. The default implementation of the class IBag requires the following element 
  8230. functions: 
  8231.  
  8232. Element Type 
  8233.  
  8234.      Default constructor 
  8235.      Copy constructor 
  8236.      Destructor 
  8237.      Assignment 
  8238.      Equality test 
  8239.      Ordering relation 
  8240.  
  8241.  
  8242. ΓòÉΓòÉΓòÉ 5.1.3.2.2. Bag on B* Key Sorted Set ΓòÉΓòÉΓòÉ
  8243.  
  8244. IBagOnBSTKeySortedSet  <Element>
  8245. IGBagOnBSTKeySortedSet <Element, ECOps>
  8246.  
  8247. The default implementation of the class IBagOnBSTKeySortedSet requires the 
  8248. following element functions: 
  8249.  
  8250. Element Type 
  8251.  
  8252.      Default constructor 
  8253.      Copy constructor 
  8254.      Destructor 
  8255.      Assignment 
  8256.      Equality test 
  8257.      Ordering relation 
  8258.  
  8259.  
  8260. ΓòÉΓòÉΓòÉ 5.1.3.2.3. Bag on Sorted Linked Sequence ΓòÉΓòÉΓòÉ
  8261.  
  8262. IBagOnSortedLinkedSequence  <Element>
  8263. IGBagOnSortedLinkedSequence <Element, ECOps>
  8264.  
  8265. The implementation of the class IBagOnSortedLinkedSequence requires the 
  8266. following element functions: 
  8267.  
  8268. Element Type 
  8269.  
  8270.      Default constructor 
  8271.      Copy constructor 
  8272.      Destructor 
  8273.      Assignment 
  8274.      Equality test 
  8275.      Ordering relation 
  8276.  
  8277.  
  8278. ΓòÉΓòÉΓòÉ 5.1.3.2.4. Bag on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  8279.  
  8280. IBagOnSortedTabularSequence  <Element>
  8281. IGBagOnSortedTabularSequence <Element, ECOps>
  8282.  
  8283. The implementation of the class IBagOnSortedTabularSequence requires the 
  8284. following element functions: 
  8285.  
  8286. Element Type 
  8287.  
  8288.      Default constructor 
  8289.      Copy constructor 
  8290.      Destructor 
  8291.      Assignment 
  8292.      Equality test 
  8293.      Ordering relation 
  8294.  
  8295.  
  8296. ΓòÉΓòÉΓòÉ 5.1.3.2.5. Bag on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  8297.  
  8298. IBagOnSortedDilutedSequence  <Element>
  8299. IGBagOnSortedDilutedSequence <Element, ECOps>
  8300.  
  8301. The implementation of the class IBagOnSortedDilutedSequence requires the 
  8302. following element functions: 
  8303.  
  8304. Element Type 
  8305.  
  8306.      Default constructor 
  8307.      Copy constructor 
  8308.      Destructor 
  8309.      Assignment 
  8310.      Equality test 
  8311.      Ordering relation 
  8312.  
  8313.  
  8314. ΓòÉΓòÉΓòÉ 5.1.3.2.6. Bag on Hash Key Set ΓòÉΓòÉΓòÉ
  8315.  
  8316. IBagOnHashKeySet  <Element>
  8317. IGBagOnHashKeySet <Element, EHOps>
  8318.  
  8319. The implementation of the class IBagOnHashKeySet requires the following element 
  8320. functions: 
  8321.  
  8322. Element Type 
  8323.  
  8324.      Default constructor 
  8325.      Copy constructor 
  8326.      Destructor 
  8327.      Assignment 
  8328.      Equality test 
  8329.      Hash function 
  8330.  
  8331.  
  8332. ΓòÉΓòÉΓòÉ 5.1.3.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  8333.  
  8334. For polymorphism, you can use the corresponding abstract class, IABag, which is 
  8335. found in the iabag.h header file, or the corresponding reference class, IRBag, 
  8336. which is found in the irbag.h header file. See Polymorphic Use of Collections 
  8337. for further information. 
  8338.  
  8339.  
  8340. ΓòÉΓòÉΓòÉ 5.1.3.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  8341.  
  8342. IABag <Element>
  8343. IRBag <Element, ConcreteBase>
  8344.  
  8345. The concrete base class is one of the classes defined above. 
  8346.  
  8347. The required functions are the same as the required functions of the concrete 
  8348. base class. 
  8349.  
  8350.  
  8351. ΓòÉΓòÉΓòÉ 5.1.4. Deque ΓòÉΓòÉΓòÉ
  8352.  
  8353. Description 
  8354.  
  8355. Derivation 
  8356.  
  8357. Variants/Header Files 
  8358.  
  8359. Members 
  8360.  
  8361. Template Arguments and Required Functions 
  8362.  
  8363. Abstract/Reference Classes 
  8364.  
  8365. Examples 
  8366.  
  8367. To close all the panels in a chapter, double-click on this panel's system menu. 
  8368.  
  8369.  
  8370. ΓòÉΓòÉΓòÉ 5.1.4.1. Class Description - Deque ΓòÉΓòÉΓòÉ
  8371.  
  8372. A deque or double-ended queue is a sequence with restricted access.  It is an 
  8373. ordered collection of elements with no key and no element equality.  The 
  8374. elements are arranged so that each collection has a first and a last element, 
  8375. each element except the last has a next element, and each element but the first 
  8376. has a previous element.  You can only add or remove the first or last element. 
  8377.  
  8378. The type and value of the elements are irrelevant, and have no effect on the 
  8379. behavior of the collection. 
  8380.  
  8381. An example of using a deque is a program for managing a lettuce warehouse. 
  8382. Cases of lettuce arriving into the warehouse are registered at one end of the 
  8383. queue (the "fresh" end) by the receiving department.  The shipping department 
  8384. reads the other end of the queue (the "old" end) to determine which case of 
  8385. lettuce to ship next. However, if an order comes in for very fresh lettuce, 
  8386. which is sold at a premium, the shipping department reads the "fresh" end of 
  8387. the queue to select the freshest case of lettuce available. 
  8388.  
  8389.  
  8390. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  8391.  
  8392. Collection 
  8393.  
  8394.   Ordered Collection
  8395.    Sequential Collection
  8396.      Sequence
  8397.       Deque
  8398.  
  8399. Note that deque is based on sequence but is not actually derived from it or 
  8400. from the other classes shown above. See Restricted Access for further details. 
  8401.  
  8402.  
  8403. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  8404.  
  8405. IDeque, the first class in the table below, is the default implementation 
  8406. variant. If you want to use polymorphism, you can replace the following class 
  8407. implementation variants by the reference class. 
  8408.  
  8409. To use Visual Builder features with your collections, change the name of the 
  8410. desired collection class template in the list below from I... to IV..., and use 
  8411. the ivdeque.h header file instead of the header file that you would normally 
  8412. use without Visual Builder. 
  8413.  
  8414. Class Name                Header File  Implementation Variant
  8415.  
  8416. IDeque                    ideque.h     Linked sequence
  8417. IGDeque                   ideque.h     Linked sequence
  8418.  
  8419. IDequeOnTabularSequence   idquts.h     Tabular sequence
  8420. IGDequeOnTabularSequence  idquts.h     Tabular sequence
  8421.  
  8422. IDequeOnDilutedSequence   idquds.h     Diluted sequence
  8423. IGDequeOnDilutedSequence  idquds.h     Diluted sequence
  8424.  
  8425.  
  8426. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  8427.  
  8428. All members of flat collections are described in Introduction to Flat 
  8429. Collections. The following members are provided for deque: 
  8430.  
  8431.      Constructor 
  8432.      Copy Constructor 
  8433.      Destructor 
  8434.      operator= 
  8435.      add 
  8436.      addAllFrom 
  8437.      addAsFirst 
  8438.      addAsLast 
  8439.      allElementsDo 
  8440.      anyElement 
  8441.      compare 
  8442.      elementAt 
  8443.      elementAtPosition 
  8444.      firstElement 
  8445.      isBounded 
  8446.      isEmpty 
  8447.      isFirst 
  8448.      isFull 
  8449.      isLast 
  8450.      lastElement 
  8451.      maxNumberOfElements 
  8452.      newCursor 
  8453.      numberOfElements 
  8454.      position 
  8455.      removeAll 
  8456.      removeFirst 
  8457.      removeLast 
  8458.      setToFirst 
  8459.      setToLast 
  8460.      setToNext 
  8461.      setToPosition 
  8462.      setToPrevious 
  8463.  
  8464.  Deque also defines a cursor that inherits from IOrderedCursor. The members for 
  8465.  IOrderedCursor are described in Cursor. 
  8466.  
  8467.  
  8468. ΓòÉΓòÉΓòÉ 5.1.4.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  8469.  
  8470. The following implementation variants are defined for deques: 
  8471.  
  8472.      Deque 
  8473.      Deque on tabular sequence 
  8474.      Deque on diluted sequence 
  8475.  
  8476.  
  8477. ΓòÉΓòÉΓòÉ 5.1.4.2.1. Deque ΓòÉΓòÉΓòÉ
  8478.  
  8479. IDeque  <Element>
  8480. IGDeque <Element, StdOps>
  8481.  
  8482. The default implementation of the class IDeque requires the following element 
  8483. functions: 
  8484.  
  8485. Element Type 
  8486.  
  8487.      Copy constructor 
  8488.      Destructor 
  8489.      Assignment 
  8490.  
  8491.  
  8492. ΓòÉΓòÉΓòÉ 5.1.4.2.2. Deque on Tabular Sequence ΓòÉΓòÉΓòÉ
  8493.  
  8494. IDequeOnTabularSequence  <Element>
  8495. IGDequeOnTabularSequence <Element, StdOps>
  8496.  
  8497. The implementation of the class IDequeOnTabularSequence requires the following 
  8498. element functions: 
  8499.  
  8500. Element Type 
  8501.  
  8502.      Default constructor 
  8503.      Copy constructor 
  8504.      Destructor 
  8505.      Assignment 
  8506.  
  8507.  
  8508. ΓòÉΓòÉΓòÉ 5.1.4.2.3. Deque on Diluted Sequence ΓòÉΓòÉΓòÉ
  8509.  
  8510. IDequeOnDilutedSequence  <Element>
  8511. IGDequeOnDilutedSequence <Element, StdOps>
  8512.  
  8513. The implementation of the class IDequeOnDilutedSequence requires the following 
  8514. element functions: 
  8515.  
  8516. Element Type 
  8517.  
  8518.      Default constructor 
  8519.      copy constructor 
  8520.      Assignment 
  8521.  
  8522.  
  8523. ΓòÉΓòÉΓòÉ 5.1.4.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  8524.  
  8525. For polymorphism, you can use the corresponding abstract class, IADeque, which 
  8526. is found in the iadeque.h header file, or the corresponding reference class, 
  8527. IRDeque, which is found in the irdeque.h header file. See Polymorphic Use of 
  8528. Collections for further information. 
  8529.  
  8530.  
  8531. ΓòÉΓòÉΓòÉ 5.1.4.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  8532.  
  8533. IADeque <Element>
  8534. IRDeque <Element, ConcreteBase>
  8535.  
  8536. The concrete base class is one of the classes defined above. 
  8537.  
  8538. The required functions are the same as the required functions of the concrete 
  8539. base class. 
  8540.  
  8541.  
  8542. ΓòÉΓòÉΓòÉ 5.1.4.4. Coding Example for Deque ΓòÉΓòÉΓòÉ
  8543.  
  8544. The following program uses the default deque class, IDeque, to create a deque. 
  8545. It fills the deque with characters by adding them to the back end. The program 
  8546. then removes the characters from alternating ends of the deque (beginning with 
  8547. the front end) until the deque is empty. 
  8548.  
  8549. The program uses the constant iterator class, IConstantIterator, when printing 
  8550. the collection. It uses the addAsLast() function to fill the deque and the 
  8551. numberOfElements() function to determine the deque's size. It uses the 
  8552. functions firstElement(), removeFirst(), lastElement(), and removeLast() to 
  8553. empty the deque. 
  8554.  
  8555.    //    letterdq.C  -  An example of using a Deque.
  8556.  
  8557.    #include <iostream.h>
  8558.  
  8559.    #include <ideque.h>
  8560.                         // Let's use the default deque
  8561.    typedef IDeque <char> Deque;
  8562.                         // The deque requires iteration to be const
  8563.    typedef IConstantIterator <char> CharIterator;
  8564.  
  8565.    class Print : public CharIterator
  8566.    {
  8567.    public:
  8568.       IBoolean applyTo(char const-,-)
  8569.          {
  8570.          cout << c;
  8571.          return True;
  8572.          }
  8573.    };
  8574.  
  8575.    /*-------------------------------------------------------------*\
  8576.    | Test variables                                                |
  8577.    \*-------------------------------------------------------------*/
  8578.  
  8579.    char *String = "Teqikbonfxjmsoe  aydg.o zlarv pu o wr cu h";
  8580.  
  8581.  
  8582.    /*-------------------------------------------------------------*\
  8583.    | Main program                                                  |
  8584.    \*-------------------------------------------------------------*/
  8585.    int main()
  8586.    {
  8587.       Deque D;
  8588.       char  C;
  8589.       IBoolean ReadFront = True;
  8590.  
  8591.       int i;
  8592.  
  8593.       // Put all characters in the deque.
  8594.       // Then read it, changing the end to read from
  8595.       // with every character read.
  8596.  
  8597.       cout << endl
  8598.            << "Adding characters to the back end of the deque:" << endl;
  8599.  
  8600.       for (i = 0; String[i] != 0; i ++) {
  8601.          D.addAsLast(String[i]);
  8602.          cout << String[i];
  8603.          }
  8604.  
  8605.       cout << endl << endl
  8606.            << "Current number of elements in the deque: "
  8607.            <<  D.numberOfElements() << endl;
  8608.  
  8609.       cout << endl
  8610.            << "Contents of the deque:" << endl;
  8611.       Print Aprinter;
  8612.       D.allElementsDo(Aprinter);
  8613.  
  8614.       cout << endl << endl
  8615.            << "Reading from the deque one element from front, one "
  8616.            << "from back, and so on:" << endl;
  8617.  
  8618.       while (!D.isEmpty())
  8619.          {
  8620.          if (ReadFront)                  // Read from front of Deque
  8621.             {
  8622.             C = D.firstElement();        // Get the character
  8623.             D.removeFirst();             // Delete it from the Deque
  8624.             }
  8625.          else
  8626.             {
  8627.             C = D.lastElement();
  8628.             D.removeLast();
  8629.             }
  8630.          cout << C;
  8631.  
  8632.          ReadFront = !ReadFront;     // Switch to other end of Deque
  8633.          }
  8634.  
  8635.       cout << endl;
  8636.  
  8637.       return(0);
  8638.    }
  8639.  
  8640. The program produces the following output: 
  8641.  
  8642.  
  8643. Adding characters to the back end of the deque:
  8644. Teqikbonfxjme vralz o.gdya  eospu o wr cu h
  8645.  
  8646. Current number of elements in the deque: 43
  8647.  
  8648. Contents of the deque:
  8649. Teqikbonfxjme vralz o.gdya  eospu o wr cu h
  8650.  
  8651. Reading from the deque one element from front, one from back, and so on:
  8652. The quick brown fox jumpes over a lazy dog.
  8653.  
  8654.  
  8655. ΓòÉΓòÉΓòÉ 5.1.5. Equality Sequence ΓòÉΓòÉΓòÉ
  8656.  
  8657. Description 
  8658.  
  8659. Derivation 
  8660.  
  8661. Variants/Header Files 
  8662.  
  8663. Members 
  8664.  
  8665. Template Arguments and Required Functions 
  8666.  
  8667. Abstract/Reference Classes 
  8668.  
  8669. To close all the panels in a chapter, double-click on this panel's system menu. 
  8670.  
  8671.  
  8672. ΓòÉΓòÉΓòÉ 5.1.5.1. Class Description - Equality Sequence ΓòÉΓòÉΓòÉ
  8673.  
  8674. An equality sequence is an ordered collection of elements. The elements are 
  8675. arranged so that each collection has a first and a last element, each element 
  8676. except the last has a next element, and each element but the first has a 
  8677. previous element.  An equality sequence supports element equality, which gives 
  8678. you the ability, for example, to search for particular elements. 
  8679.  
  8680. An example of using an equality sequence is a program that calculates members 
  8681. of the Fibonacci sequence and places them in a collection.  Multiple elements 
  8682. of the same value are allowed.  For example, the sequence begins with two 
  8683. instances of the value 1.  You can search for a given element, for example 8, 
  8684. and find out what element follows it in the sequence.  Element equality allows 
  8685. you to do this, using the locate() and setToNext() functions. 
  8686.  
  8687.  
  8688. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  8689.  
  8690. Collection 
  8691.  
  8692.   Equality Collection
  8693.   Sequential Collection
  8694.      Equality Sequence
  8695.  
  8696. Figure Combination of Flat Collection Properties illustrates the properties of 
  8697. an equality sequence and its relationship to other flat collections. 
  8698.  
  8699.  
  8700. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  8701.  
  8702. IEqualitySequence, the first class in the table below, is the default 
  8703. implementation variant. If you want to use polymorphism, you can replace the 
  8704. following class implementation variants by the reference class. 
  8705.  
  8706. To use Visual Builder features with your collections, change the name of the 
  8707. desired collection class template in the list below from I... to IV..., and use 
  8708. the iveqseq.h header file instead of the header file that you would normally 
  8709. use without Visual Builder. 
  8710.  
  8711. Class Name          Header File  Implementation Variant
  8712.  
  8713. IEqualitySequence   ieqseq.h     Linked sequence
  8714. IGEqualitySequence  ieqseq.h     Linked sequence
  8715.  
  8716. IEqualitySequence-  ieqts.h      Tabular sequence
  8717.  OnTabularSequence
  8718. IGEqualitySequence  ieqts.h      Tabular sequence
  8719.  
  8720. IEqualitySequence-  ieqds.h      Diluted sequence
  8721.  OnDilutedSequence
  8722. IGEqualitySequence  ieqds.h      Diluted sequence
  8723.  
  8724.  
  8725. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  8726.  
  8727. All members of flat collections are described in Introduction to Flat 
  8728. Collections. The following members are provided for equality sequence: 
  8729.  
  8730.      Constructor 
  8731.      Copy Constructor 
  8732.      Destructor 
  8733.      operator!= 
  8734.      operator= 
  8735.      operator== 
  8736.      add 
  8737.      addAllFrom 
  8738.      addAsFirst 
  8739.      addAsLast 
  8740.      addAsNext 
  8741.      addAsPrevious 
  8742.      addAtPosition 
  8743.      allElementsDo 
  8744.      anyElement 
  8745.      compare 
  8746.      contains 
  8747.      containsAllFrom 
  8748.      elementAt 
  8749.      elementAtPosition 
  8750.      firstElement 
  8751.      isBounded 
  8752.      isEmpty 
  8753.      isFirst 
  8754.      isFull 
  8755.      isLast 
  8756.      lastElement 
  8757.      locate 
  8758.      locateFirst 
  8759.      locateLast 
  8760.      locateNext 
  8761.      locateOrAdd 
  8762.      locatePrevious 
  8763.      maxNumberOfElements 
  8764.      newCursor 
  8765.      numberOfElements 
  8766.      numberOfOccurrences 
  8767.      position 
  8768.      remove 
  8769.      removeAll 
  8770.      removeAllOccurrences 
  8771.      removeAt 
  8772.      removeAtPosition 
  8773.      removeFirst 
  8774.      removeLast 
  8775.      replaceAt 
  8776.      setToFirst 
  8777.      setToLast 
  8778.      setToNext 
  8779.      setToPosition 
  8780.      setToPrevious 
  8781.      sort 
  8782.  
  8783.  Equality sequence also defines a cursor that inherits from IOrderedCursor. The 
  8784.  members for IOrderedCursor are described in Cursor. 
  8785.  
  8786.  
  8787. ΓòÉΓòÉΓòÉ 5.1.5.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  8788.  
  8789. The following implementation variants are defined for equality sequences: 
  8790.  
  8791.      Equality sequence 
  8792.      Equality sequence on tabular sequence 
  8793.      Equality sequence on diluted sequence 
  8794.  
  8795.  
  8796. ΓòÉΓòÉΓòÉ 5.1.5.2.1. Equality Sequence ΓòÉΓòÉΓòÉ
  8797.  
  8798. IEqualitySequence  <Element>
  8799. IGEqualitySequence <Element, EOps>
  8800.  
  8801. The default implementation of IEqualitySequence requires the following element 
  8802. functions: 
  8803.  
  8804. Element Type 
  8805.  
  8806.      Assignment 
  8807.      Equality test 
  8808.  
  8809.  
  8810. ΓòÉΓòÉΓòÉ 5.1.5.2.2. Equality Sequence on Tabular Sequence ΓòÉΓòÉΓòÉ
  8811.  
  8812. IEqualitySequenceOnTabularSequence  <Element>
  8813. IGEqualitySequenceOnTabularSequence <Element, EOps>
  8814.  
  8815. The implementation of the class IEqualitySequenceOnTabularSequence requires the 
  8816. following element functions: 
  8817.  
  8818. Element Type 
  8819.  
  8820.      Default constructor 
  8821.      Copy constructor 
  8822.      Destructor 
  8823.      Assignment 
  8824.      Equality test 
  8825.  
  8826.  
  8827. ΓòÉΓòÉΓòÉ 5.1.5.2.3. Equality Sequence on Diluted Sequence ΓòÉΓòÉΓòÉ
  8828.  
  8829. IEqualitySequenceOnDilutedSequence  <Element>
  8830. IGEqualitySequenceOnDilutedSequence <Element, EOps>
  8831.  
  8832. The implementation of the class IEqualitySequenceOnDilutedSequence requires the 
  8833. following element functions: 
  8834.  
  8835. Element Type 
  8836.  
  8837.      Default constructor 
  8838.      Copy constructor 
  8839.      Destructor 
  8840.      Assignment 
  8841.      Equality test 
  8842.  
  8843.  
  8844. ΓòÉΓòÉΓòÉ 5.1.5.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  8845.  
  8846. For polymorphism, you can use the corresponding abstract class, IAEqSeq, which 
  8847. is found in the iaeqseq.h header file, or the corresponding reference class, 
  8848. IREqSeq, which is found in the ireqseq.h header file. See Polymorphic Use of 
  8849. Collections for further information. 
  8850.  
  8851.  
  8852. ΓòÉΓòÉΓòÉ 5.1.5.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  8853.  
  8854. IAEqSequ <Element>
  8855. IREqSequ <Element, ConcreteBase>
  8856.  
  8857. The concrete base class is one of the classes defined above. 
  8858.  
  8859. The required functions are the same as the required functions of the concrete 
  8860. base class. 
  8861.  
  8862.  
  8863. ΓòÉΓòÉΓòÉ 5.1.6. Heap ΓòÉΓòÉΓòÉ
  8864.  
  8865. Description 
  8866.  
  8867. Derivation 
  8868.  
  8869. Variants/Header Files 
  8870.  
  8871. Members 
  8872.  
  8873. Template Arguments and Required Functions 
  8874.  
  8875. Abstract/Reference Classes 
  8876.  
  8877. Examples 
  8878.  
  8879. To close all the panels in a chapter, double-click on this panel's system menu. 
  8880.  
  8881.  
  8882. ΓòÉΓòÉΓòÉ 5.1.6.1. Class Description - Heap ΓòÉΓòÉΓòÉ
  8883.  
  8884. A heap is an unordered collection of zero or more elements with no key. 
  8885. Element equality is not supported.  Multiple elements are supported.  The type 
  8886. and value of the elements are irrelevant, and have no effect on the behavior of 
  8887. the heap. 
  8888.  
  8889. You can compare using a heap collection to managing the scrap metal entering a 
  8890. scrapyard.  Pieces of scrap are placed in the heap in an arbitrary location, 
  8891. and an element can be added multiple times (for example, the rear left fender 
  8892. from a particular kind of car).  When a customer requests a certain amount of 
  8893. scrap, elements are removed from the heap in an arbitrary order until the 
  8894. required amount is reached. You cannot search for a specific piece of scrap 
  8895. except by examining each piece of scrap in the heap and manually comparing it 
  8896. to the piece you are looking for. 
  8897.  
  8898. Figure Combination of Flat Collection Properties illustrates the properties of 
  8899. a heap and its relationship to other flat collections. 
  8900.  
  8901.  
  8902. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  8903.  
  8904. Collection 
  8905.  
  8906.   Heap
  8907.  
  8908.  
  8909. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  8910.  
  8911. IHeap, the first class in the table below, is the default implementation 
  8912. variant. If you want to use polymorphism, you can replace the following class 
  8913. implementation variants by the reference class. 
  8914.  
  8915. To use Visual Builder features with your collections, change the name of the 
  8916. desired collection class template in the list below from I... to IV..., and use 
  8917. the ivheap.h header file instead of the header file that you would normally use 
  8918. without Visual Builder. 
  8919.  
  8920. Class Name              Header File  Implementation Variant
  8921.  
  8922. IHeap                   iheap.h      Linked sequence
  8923. IGHeap                  iheap.h      Linked sequence
  8924.  
  8925. IHeapOnTabularSequence  iheapts.h    Tabular sequence
  8926. IGHeapOnTabularSequence iheapts.h    Tabular sequence
  8927.  
  8928. IHeapOnDilutedSequence  iheapds.h    Diluted sequence
  8929. IGHeapOnDilutedSequence iheapds.h    Diluted sequence
  8930.  
  8931.  
  8932. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  8933.  
  8934. All members of flat collections are described in Introduction to Flat 
  8935. Collections. The following members are provided for heap: 
  8936.  
  8937.      Constructor 
  8938.      Copy Constructor 
  8939.      Destructor 
  8940.      operator= 
  8941.      add 
  8942.      addAllFrom 
  8943.      allElementsDo 
  8944.      anyElement 
  8945.      elementAt 
  8946.      isBounded 
  8947.      isEmpty 
  8948.      isFull 
  8949.      maxNumberOfElements 
  8950.      newCursor 
  8951.      numberOfElements 
  8952.      removeAll 
  8953.      removeAt 
  8954.      replaceAt 
  8955.      setToFirst 
  8956.      setToNext 
  8957.  
  8958.  Heap also defines a cursor that inherits from IElementCursor. The members for 
  8959.  IElementCursor are described in Cursor. 
  8960.  
  8961.  
  8962. ΓòÉΓòÉΓòÉ 5.1.6.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  8963.  
  8964. The following implementation variants are defined for heaps: 
  8965.  
  8966.      Heap 
  8967.      Heap on Tabular Sequence 
  8968.      Heap on Diluted Sequence 
  8969.  
  8970.  
  8971. ΓòÉΓòÉΓòÉ 5.1.6.2.1. Heap ΓòÉΓòÉΓòÉ
  8972.  
  8973. IHeap  <Element>
  8974. IGHeap <Element, StdOps>
  8975.  
  8976. The default implementation of IHeap requires the following element functions: 
  8977.  
  8978. Element Type 
  8979.  
  8980.      Copy constructor 
  8981.      Assignment 
  8982.  
  8983.  
  8984. ΓòÉΓòÉΓòÉ 5.1.6.2.2. Heap on Tabular Sequence ΓòÉΓòÉΓòÉ
  8985.  
  8986. IHeapOnTabularSequence  <Element>
  8987. IGHeapOnTabularSequence <Element, StdOps>
  8988.  
  8989. The implementation of the class IHeapOnTabularSequence requires the following 
  8990. element functions: 
  8991.  
  8992. Element Type 
  8993.  
  8994.      Default constructor 
  8995.      Copy constructor 
  8996.      Assignment 
  8997.  
  8998.  
  8999. ΓòÉΓòÉΓòÉ 5.1.6.2.3. Heap on Diluted Sequence ΓòÉΓòÉΓòÉ
  9000.  
  9001. IHeapOnDilutedSequence  <Element>
  9002. IGHeapOnDilutedSequence <Element, StdOps>
  9003.  
  9004. The implementation of the class IHeapOnDilutedSequence requires the following 
  9005. element functions: 
  9006.  
  9007. Element Type 
  9008.  
  9009.      Default constructor 
  9010.      Copy constructor 
  9011.  
  9012.  
  9013. ΓòÉΓòÉΓòÉ 5.1.6.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  9014.  
  9015. For polymorphism, you can use the corresponding abstract class, IAHeap, which 
  9016. is found in the iaheap.h header file, or the corresponding reference class, 
  9017. IRHeap, which is found in the irheap.h header file. See Polymorphic Use of 
  9018. Collections for further information. 
  9019.  
  9020.  
  9021. ΓòÉΓòÉΓòÉ 5.1.6.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  9022.  
  9023. IAHeap <Element>
  9024. IRHeap <Element, ConcreteBase>
  9025.  
  9026. The concrete base class is one of the heap classes. 
  9027.  
  9028. The required functions are the same as the required functions of the concrete 
  9029. base class. 
  9030.  
  9031.  
  9032. ΓòÉΓòÉΓòÉ 5.1.6.4. Coding Example for Heap ΓòÉΓòÉΓòÉ
  9033.  
  9034. See Coding Example for Key Sorted Set for an example of using a heap. 
  9035.  
  9036.  
  9037. ΓòÉΓòÉΓòÉ 5.1.7. Key Bag ΓòÉΓòÉΓòÉ
  9038.  
  9039. Description 
  9040.  
  9041. Derivation 
  9042.  
  9043. Variants/Header Files 
  9044.  
  9045. Members 
  9046.  
  9047. Template Arguments and Required Functions 
  9048.  
  9049. Abstract/Reference Classes 
  9050.  
  9051. Examples 
  9052.  
  9053. To close all the panels in a chapter, double-click on this panel's system menu. 
  9054.  
  9055.  
  9056. ΓòÉΓòÉΓòÉ 5.1.7.1. Class Description - Key Bag ΓòÉΓòÉΓòÉ
  9057.  
  9058. A key bag is an unordered collection of zero or more elements that have a key. 
  9059. Multiple elements are supported. 
  9060.  
  9061. An example of using a key bag is a program that manages the distribution of 
  9062. combination locks to members of a fitness club. The element key is the number 
  9063. that is printed on the back of each combination lock.  Each element also has 
  9064. data members for the club member's name, member number, and so on.  When you 
  9065. join the club, you are given one of the available combination locks, and your 
  9066. name, member number, and the number on the combination lock are entered into 
  9067. the collection.  Because a given number on a combination lock may appear on 
  9068. several locks, the program allows the same lock number to be added to the 
  9069. collection multiple times.  When you return a lock because you are leaving the 
  9070. club, the program finds each element whose key matches your lock's serial 
  9071. number, and deletes one such element that has your name associated with it. 
  9072.  
  9073. Figure Behavior of add for Unique and Miltiple Collections illustrates the 
  9074. differences in behavior between map, relation, key set, and key bag when 
  9075. identical elements and elements with the same key are added. 
  9076.  
  9077.  
  9078. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  9079.  
  9080. Collection 
  9081.  
  9082.   Key Collection
  9083.    Key Bag
  9084.  
  9085. Figure Combination of Flat Collection Properties gives an overview of the 
  9086. properties of a key bag and its relationship to other flat collections. 
  9087.  
  9088.  
  9089. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  9090.  
  9091. IKeyBag, the first class in the table below, is the default implementation 
  9092. variant. If you want to use polymorphism, you can replace the following class 
  9093. implementation variants by the reference class. 
  9094.  
  9095. To use Visual Builder features with your collections, change the name of the 
  9096. desired collection class template in the list below from I... to IV..., and use 
  9097. the ivkeybag.h header file instead of the header file that you would normally 
  9098. use without Visual Builder. 
  9099.  
  9100. Class Name       Header File    Implementation Variant
  9101.  
  9102. IKeyBag          ikeybag.h      Hash table
  9103. IGKeyBag         ikeybag.h      Hash table
  9104. IHashKeyBag      ihshkb.h       Hash table
  9105. IGHashKeyBag     ihshkb.h       Hash table
  9106.  
  9107.  
  9108. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  9109.  
  9110. All members of flat collections are described in Introduction to Flat 
  9111. Collections. The following members are provided for key bag: 
  9112.  
  9113.      Constructor 
  9114.      Copy Constructor 
  9115.      Destructor 
  9116.      operator= 
  9117.      add 
  9118.      addAllFrom 
  9119.      addOrReplaceElementWithKey 
  9120.      allElementsDo 
  9121.      anyElement 
  9122.      containsAllKeysFrom 
  9123.      containsElementWithKey 
  9124.      elementAt 
  9125.      elementWithKey 
  9126.      isBounded 
  9127.      isEmpty 
  9128.      isFull 
  9129.      key 
  9130.      locateElementWithKey 
  9131.      locateNextElementWithKey 
  9132.      locateOrAddElementWithKey 
  9133.      maxNumberOfElements 
  9134.      newCursor 
  9135.      numberOfDifferentKeys 
  9136.      numberOfElements 
  9137.      numberOfElementsWithKey 
  9138.      removeAll 
  9139.      removeAllElementsWithKey 
  9140.      removeAt 
  9141.      removeElementWithKey 
  9142.      replaceAt 
  9143.      replaceElementWithKey 
  9144.      setToFirst 
  9145.      setToNext 
  9146.      setToNextWithDifferentKey 
  9147.  
  9148.  Key Bag also defines a cursor that inherits from IElementCursor. The members 
  9149.  for IElementCursor are described in Cursor. 
  9150.  
  9151.  
  9152. ΓòÉΓòÉΓòÉ 5.1.7.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  9153.  
  9154. The following implementation variants are defined for key bags: 
  9155.  
  9156.      Key bag 
  9157.      Hash key bag 
  9158.  
  9159.  
  9160. ΓòÉΓòÉΓòÉ 5.1.7.2.1. Key Bag ΓòÉΓòÉΓòÉ
  9161.  
  9162. IKeyBag  <Element, Key>
  9163. IGKeyBag <Element, Key, KEHOps>
  9164.  
  9165. The default implementation of the class IKeyBag requires the following element 
  9166. and key-type functions: 
  9167.  
  9168. Element Type 
  9169.  
  9170.      Copy constructor 
  9171.      Destructor 
  9172.      Assignment 
  9173.      Key access 
  9174.  
  9175.  Key Type 
  9176.  
  9177.      Equality test 
  9178.      Hash function 
  9179.  
  9180.  
  9181. ΓòÉΓòÉΓòÉ 5.1.7.2.2. Hash Key Bag ΓòÉΓòÉΓòÉ
  9182.  
  9183. IHashKeyBag  <Element, Key>
  9184. IGHashKeyBag <Element, Key, KEHOps>
  9185.  
  9186. The implementation of the class IHashKeyBag requires the following element and 
  9187. key-type functions: 
  9188.  
  9189. Element Type 
  9190.  
  9191.      Copy constructor 
  9192.      Destructor 
  9193.      Assignment 
  9194.      Key access 
  9195.  
  9196.  Key Type 
  9197.  
  9198.      Equality test 
  9199.      Hash function 
  9200.  
  9201.  
  9202. ΓòÉΓòÉΓòÉ 5.1.7.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  9203.  
  9204. For polymorphism, you can use the corresponding abstract class, IAKeyBag, which 
  9205. is found in the iakeybag.h header file, or the corresponding reference class, 
  9206. IRKeyBag, which is found in the irkeybag.h header file. See Polymorphic Use of 
  9207. Collections for further information. 
  9208.  
  9209.  
  9210. ΓòÉΓòÉΓòÉ 5.1.7.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  9211.  
  9212. IAKeyBag <Element, Key>
  9213. IRKeyBag <Element, Key, ConcreteBase>
  9214.  
  9215. The concrete base class is one of the classes defined above. 
  9216.  
  9217. The required functions are the same as the required functions of the concrete 
  9218. base class. 
  9219.  
  9220.  
  9221. ΓòÉΓòÉΓòÉ 5.1.7.4. Coding Example for Key Bag ΓòÉΓòÉΓòÉ
  9222.  
  9223. The following program uses the default key bag class, IKeyBag, to create a key 
  9224. bag for storing observations made on animals. The key of the class is the name 
  9225. of the animal.  The program produces various reports regarding the 
  9226. observations.  Then it removes all the extinct animals, which are stored in a 
  9227. sequence, from the key bag. 
  9228.  
  9229. The program uses the add() function to fill the key bag and the forCursor macro 
  9230. to display the observations. It uses the following functions to produce the 
  9231. reports: 
  9232.  
  9233.      numberOfElements() 
  9234.      numberOfDifferentKeys() 
  9235.      numberOfElementsWithKey() 
  9236.      locateElementWithKey() 
  9237.      setToNextElementWithKey() 
  9238.      removeAllElementsWithKey() 
  9239.  
  9240.      // animals.C  -  An example of using a Key Bag
  9241.      #include <iostream.h>
  9242.                     // Class Animal:
  9243.      #include "animal.h"
  9244.  
  9245.                     // Let's use the default Key Bag:
  9246.      #include <ikeybag.h>
  9247.      typedef IKeyBag<Animal, IString> Animals;
  9248.  
  9249.                     // For keys let's use the default Sequence:
  9250.      #include <iseq.h>
  9251.      typedef ISequence<IString> Names;
  9252.  
  9253.  
  9254.      main() {
  9255.  
  9256.         Animals animals;
  9257.         Animals::Cursor animalsCur1(animals), animalsCur2(animals);
  9258.  
  9259.         animals.add(Animal("bear", "heavy"));
  9260.         animals.add(Animal("bear", "strong"));
  9261.         animals.add(Animal("dinosaur", "heavy"));
  9262.         animals.add(Animal("dinosaur", "huge"));
  9263.         animals.add(Animal("dinosaur", "extinct"));
  9264.         animals.add(Animal("eagle", "black"));
  9265.         animals.add(Animal("eagle", "strong"));
  9266.         animals.add(Animal("lion", "dangerous"));
  9267.         animals.add(Animal("lion", "strong"));
  9268.         animals.add(Animal("mammoth", "long haired"));
  9269.         animals.add(Animal("mammoth", "extinct"));
  9270.         animals.add(Animal("sabre tooth tiger", "extinct"));
  9271.         animals.add(Animal("zebra", "striped"));
  9272.  
  9273.                       // Display all elements in animals:
  9274.         cout << endl
  9275.              << "All our observations on animals:" << endl;
  9276.         forCursor(animalsCur1)  cout << "    " << animalsCur1.element();
  9277.  
  9278.         cout << endl << endl
  9279.              << "Number of observations on animals: "
  9280.              << animals.numberOfElements() << endl;
  9281.  
  9282.         cout << endl
  9283.              << "Number of different animals: "
  9284.              << animals.numberOfDifferentKeys() << endl;
  9285.  
  9286.         Names namesOfExtinct(animals.numberOfDifferentKeys());
  9287.         Names::Cursor extinctCur1(namesOfExtinct);
  9288.  
  9289.         animalsCur1.setToFirst();
  9290.         do {
  9291.            IString name = animalsCur1.element().name();
  9292.  
  9293.            cout << endl
  9294.                 << "We have " << animals.numberOfElementsWithKey(name)
  9295.                 << " observations on " << name << ":" << endl;
  9296.  
  9297.                         // We need to use a separate cursor here
  9298.                         // because otherwise animalsCur1 would become
  9299.                         // invalid after last locateNextElement...()
  9300.            animals.locateElementWithKey(name, animalsCur2);
  9301.            do  {
  9302.               IString attribute = animalsCur2.element().attribute();
  9303.               cout << "    " << attribute << endl;
  9304.               if (attribute == "extinct") namesOfExtinct.add(name);
  9305.            } while (animals.locateNextElementWithKey(name, animalsCur2));
  9306.  
  9307.         } while (animals.setToNextWithDifferentKey(animalsCur1));
  9308.  
  9309.                       // Remove all observations on extinct animals:
  9310.         forCursor(extinctCur1)
  9311.            animals.removeAllElementsWithKey(extinctCur1.element());
  9312.  
  9313.                       // Display all elements in animals:
  9314.         cout << endl << endl
  9315.              << "After removing all observations on extinct animals:" << endl;
  9316.         forCursor(animalsCur1)  cout << "    " << animalsCur1.element();
  9317.  
  9318.         cout << endl
  9319.              << "Number of observations on animals: "
  9320.              << animals.numberOfElements() << endl;
  9321.  
  9322.         cout << endl
  9323.              << "Number of different animals: "
  9324.              << animals.numberOfDifferentKeys() << endl;
  9325.  
  9326.         return 0;
  9327.      }
  9328.  
  9329.  The program produces the following output: 
  9330.  
  9331.  
  9332.   All our observations on animals:
  9333.       The eagle is strong.
  9334.       The eagle is black.
  9335.       The bear is strong.
  9336.       The bear is heavy.
  9337.       The zebra is striped.
  9338.       The mammoth is extinct.
  9339.       The mammoth is long haired.
  9340.       The lion is strong.
  9341.       The lion is dangerous.
  9342.       The dinosaur is extinct.
  9343.       The dinosaur is huge.
  9344.       The dinosaur is heavy.
  9345.       The sabre tooth tiger is extinct.
  9346.  
  9347.  
  9348.   Number of observations on animals: 13
  9349.  
  9350.   Number of different animals: 7
  9351.  
  9352.   We have 2 observations on eagle:
  9353.       strong
  9354.       black
  9355.  
  9356.   We have 2 observations on bear:
  9357.       strong
  9358.       heavy
  9359.  
  9360.   We have 1 observations on zebra:
  9361.       striped
  9362.  
  9363.   We have 2 observations on mammoth:
  9364.       extinct
  9365.       long haired
  9366.  
  9367.   We have 2 observations on lion:
  9368.       strong
  9369.       dangerous
  9370.  
  9371.   We have 3 observations on dinosaur:
  9372.       extinct
  9373.       huge
  9374.       heavy
  9375.  
  9376.   We have 1 observations on sabre tooth tiger:
  9377.       extinct
  9378.  
  9379.  
  9380.   After removing all observations on extinct animals:
  9381.       The eagle is strong.
  9382.       The eagle is black.
  9383.       The bear is strong.
  9384.       The bear is heavy.
  9385.       The zebra is striped.
  9386.       The lion is strong.
  9387.       The lion is dangerous.
  9388.  
  9389.   Number of observations on animals: 7
  9390.  
  9391.   Number of different animals: 4
  9392.  
  9393.  
  9394. ΓòÉΓòÉΓòÉ 5.1.8. Key Set ΓòÉΓòÉΓòÉ
  9395.  
  9396. Description 
  9397.  
  9398. Derivation 
  9399.  
  9400. Variants/Header Files 
  9401.  
  9402. Members 
  9403.  
  9404. Template Arguments and Required Functions 
  9405.  
  9406. Abstract/Reference Classes 
  9407.  
  9408. Examples 
  9409.  
  9410. To close all the panels in a chapter, double-click on this panel's system menu. 
  9411.  
  9412.  
  9413. ΓòÉΓòÉΓòÉ 5.1.8.1. Class Description - Key Set ΓòÉΓòÉΓòÉ
  9414.  
  9415. A key set is an unordered collection of zero or more elements that have a key. 
  9416. Element equality is not supported.  Only unique elements are supported, in 
  9417. terms of their key. 
  9418.  
  9419. An example of using a key set is a program that allocates rooms to patrons 
  9420. checking into a hotel.  The room number serves as the element's key, and the 
  9421. patron's name is a data member of the element.  When you check in at the front 
  9422. desk, the clerk pulls a room key from the board, and enters that key's number 
  9423. and your name into the collection.  When you return the key at check-out time, 
  9424. the record for that key is removed from the collection.  You cannot add an 
  9425. element to the collection that is already present, because there is only one 
  9426. key for each room.  If you attempt to add an element that is already present, 
  9427. the add() function returns False to indicate that the element was not added. 
  9428.  
  9429. Figure Behavior of add for Unique and Miltiple Collections illustrates the 
  9430. differences in behavior between map, relation, key set, and key bag when 
  9431. identical elements and elements with the same key are added. 
  9432.  
  9433. Figure Combination of Flat Collection Properties gives an overview of the 
  9434. properties of a key set and its relationship to other flat collections. 
  9435.  
  9436.  
  9437. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  9438.  
  9439. Collection 
  9440.  
  9441.   Key Collection
  9442.    Key Set
  9443.  
  9444.  
  9445. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  9446.  
  9447. IKeySet, the first class in the table below, is the default implementation 
  9448. variant. If you want to use polymorphism, you can replace the following class 
  9449. implementation variants by the reference class. 
  9450.  
  9451. To use Visual Builder features with your collections, change the name of the 
  9452. desired collection class template in the list below from I... to IV..., and use 
  9453. the ivkeyset.h header file instead of the header file that you would normally 
  9454. use without Visual Builder. 
  9455.  
  9456. Class Name                       Header File Implementation Variant
  9457.  
  9458. IKeySet                         ikeyset.h    AVL tree
  9459. IGKeySet                        ikeyset.h    AVL tree
  9460.  
  9461. IKeySetOnBSTKeySortedSet        iksbst.h     B* tree
  9462. IGKeySetOnBSTKeySortedSet       iksbst.h     B* tree
  9463.  
  9464. IHashKeySet                     ihshks.h     Hash table
  9465. IGHashKeySet                    ihshks.h     Hash table
  9466.  
  9467. IKeySetOnSortedLinkedSequence   ikssls.h     Linked sequence
  9468. IGKeySetOnSortedLinkedSequence  ikssls.h     Linked sequence
  9469.  
  9470. IKeySetOnSortedTabularSequence  ikssts.h     Tabular sequence
  9471. IGKeySetOnSortedTabularSequence ikssts.h     Tabular sequence
  9472.  
  9473. IKeySetOnSortedDilutedSequence  ikssds.h     Diluted sequence
  9474. IGKeySetOnSortedDilutedSequence ikssds.h     Diluted sequence
  9475.  
  9476.  
  9477. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  9478.  
  9479. All members of flat collections are described in Introduction to Flat 
  9480. Collections. The following members are provided for key set: 
  9481.  
  9482.      Constructor 
  9483.      Copy Constructor 
  9484.      Destructor 
  9485.      operator= 
  9486.      add 
  9487.      addAllFrom 
  9488.      addOrReplaceElementWithKey 
  9489.      allElementsDo 
  9490.      anyElement 
  9491.      containsAllKeysFrom 
  9492.      containsElementWithKey 
  9493.      elementAt 
  9494.      elementWithKey 
  9495.      isBounded 
  9496.      isEmpty 
  9497.      isFull 
  9498.      key 
  9499.      locateElementWithKey 
  9500.      locateOrAddElementWithKey 
  9501.      maxNumberOfElements 
  9502.      newCursor 
  9503.      numberOfElements 
  9504.      removeAll 
  9505.      removeAt 
  9506.      removeElementWithKey 
  9507.      replaceAt 
  9508.      replaceElementWithKey 
  9509.      setToFirst 
  9510.      setToNext 
  9511.  
  9512.  Key set also defines a cursor that inherits from IElementCursor. The members 
  9513.  for IElementCursor are described in Cursor. 
  9514.  
  9515.  
  9516. ΓòÉΓòÉΓòÉ 5.1.8.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  9517.  
  9518. The following implementation variants are defined for key sets: 
  9519.  
  9520.      Key set 
  9521.      Key set on B* key sorted set 
  9522.      Hash key set 
  9523.      Key set on sorted linked sequence 
  9524.      Key set on sorted tabular sequence 
  9525.      Key set on sorted diluted sequence 
  9526.  
  9527.  
  9528. ΓòÉΓòÉΓòÉ 5.1.8.2.1. Key Set ΓòÉΓòÉΓòÉ
  9529.  
  9530. IKeySet  <Element, Key>
  9531. IGKeySet <Element, Key, KCOps>
  9532.  
  9533. The default implementation of the class IKeySet requires the following element 
  9534. and key-type functions: 
  9535.  
  9536. Element Type 
  9537.  
  9538.      Copy constructor 
  9539.      Destructor 
  9540.      Assignment 
  9541.      Key access 
  9542.  
  9543.  Key Type 
  9544.  
  9545.  Ordering relation 
  9546.  
  9547.  
  9548. ΓòÉΓòÉΓòÉ 5.1.8.2.2. Key Set on B* Key Sorted Set ΓòÉΓòÉΓòÉ
  9549.  
  9550. IKeySetOnBSTKeySortedSet  <Element, Key>
  9551. IGKeySetOnBSTKeySortedSet <Element, Key, KCOps>
  9552.  
  9553. The implementation of the class IKeySetOnBSTKeySortedSet requires the following 
  9554. element and key-type functions: 
  9555.  
  9556. Element Type 
  9557.  
  9558.      Default constructor 
  9559.      Copy constructor 
  9560.      Destructor 
  9561.      Assignment 
  9562.      Key access 
  9563.  
  9564.  Key Type 
  9565.  
  9566.  Ordering relation 
  9567.  
  9568.  
  9569. ΓòÉΓòÉΓòÉ 5.1.8.2.3. Hash Key Set ΓòÉΓòÉΓòÉ
  9570.  
  9571. IHashKeySet  <Element, Key>
  9572. IGHashKeySet <Element, Key, KEHOps>
  9573.  
  9574. The implementation class IHashKeySet requires the following element and 
  9575. key-type functions: 
  9576.  
  9577. Element Type 
  9578.  
  9579.      Copy constructor 
  9580.      Destructor 
  9581.      Assignment 
  9582.      Key access 
  9583.  
  9584.  Key Type 
  9585.  
  9586.      Equality test 
  9587.      Hash function 
  9588.  
  9589.  
  9590. ΓòÉΓòÉΓòÉ 5.1.8.2.4. Key Set on Sorted Linked Sequence ΓòÉΓòÉΓòÉ
  9591.  
  9592. IKeySetOnSortedLinkedSequence  <Element, Key>
  9593. IGKeySetOnSortedLinkedSequence <Element, Key, KCOps>
  9594.  
  9595. The implementation of the class IKeySetOnSortedLinkedSequence requires the 
  9596. following element and key-type functions: 
  9597.  
  9598. Element Type 
  9599.  
  9600.      Copy constructor 
  9601.      Destructor 
  9602.      Assignment 
  9603.      Key access 
  9604.  
  9605.  Key Type 
  9606.  
  9607.  Ordering relation 
  9608.  
  9609.  
  9610. ΓòÉΓòÉΓòÉ 5.1.8.2.5. Key Set on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  9611.  
  9612. IKeySetOnSortedTabularSequence  <Element, Key>
  9613. IGKeySetOnSortedTabularSequence <Element, Key, KCOps>
  9614.  
  9615. The implementation of the class IKeySetOnSortedTabularSequence requires the 
  9616. following element and key-type functions: 
  9617.  
  9618. Element Type 
  9619.  
  9620.      Default constructor 
  9621.      Copy constructor 
  9622.      Destructor 
  9623.      Assignment 
  9624.      Key access 
  9625.  
  9626.  Key Type 
  9627.  
  9628.  Ordering relation 
  9629.  
  9630.  
  9631. ΓòÉΓòÉΓòÉ 5.1.8.2.6. Key Set on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  9632.  
  9633. IKeySetOnSortedDilutedSequence  <Element, Key>
  9634. IGKeySetOnSortedDilutedSequence <Element, Key, KCOps>
  9635.  
  9636. The implementation of the class IKeySetOnSortedDilutedSequence requires the 
  9637. following element and key-type functions: 
  9638.  
  9639. Element Type 
  9640.  
  9641.      Default constructor 
  9642.      Copy constructor 
  9643.      Destructor 
  9644.      Assignment 
  9645.      Key access 
  9646.  
  9647.  Key Type 
  9648.  
  9649.  Ordering relation 
  9650.  
  9651.  
  9652. ΓòÉΓòÉΓòÉ 5.1.8.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  9653.  
  9654. For polymorphism, you can use the corresponding abstract class, IAKeySet, which 
  9655. is found in the iakeyset.h header file, or the corresponding reference class, 
  9656. IRKeySet, which is found in the irkeyset.h header file. See Polymorphic Use of 
  9657. Collections for further information. 
  9658.  
  9659.  
  9660. ΓòÉΓòÉΓòÉ 5.1.8.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  9661.  
  9662. IAKeySet <Element, Key>
  9663. IRKeySet <Element, Key, ConcreteBase>
  9664.  
  9665. The concrete base class is one of the classes defined above. 
  9666.  
  9667. The required functions are the same as the required functions of the concrete 
  9668. base class. 
  9669.  
  9670.  
  9671. ΓòÉΓòÉΓòÉ 5.1.8.4. Coding Example for Key Set ΓòÉΓòÉΓòÉ
  9672.  
  9673. The following program implements a key set using the default class, IKeySet. 
  9674. The program adds four elements to the key set and then removes one element by 
  9675. looking for a key.  If an exception occurs, it displays the exception name and 
  9676. description. 
  9677.  
  9678. The program uses cursor iteration (the forCursor macro) to display the contents 
  9679. of the collection. To add and remove elements, it uses the add() function and 
  9680. the removeElementWithKey() function. 
  9681.  
  9682. //  intkyset.C  -  An example of using a Key Set
  9683.    #include <iostream.h>
  9684.    #include <iglobals.h>
  9685.    #include <icursor.h>
  9686.  
  9687.    #include <ikeyset.h>
  9688.                          // Class DemoElement:
  9689.    #include "demoelem.h"
  9690.  
  9691.    typedef IKeySet < DemoElement,int > TestKeySet;
  9692.  
  9693.    ostream & operator<< ( ostream & sout, TestKeySet const & t){
  9694.      sout << t.numberOfElements() << " elements are in the set:\n";
  9695.  
  9696.      TestKeySet::Cursor cursor (t);
  9697.      //  forCursor(c)
  9698.      // expands to
  9699.      //  for ((c).setToFirst (); (c).isValid (); (c).setToNext ())
  9700.  
  9701.      forCursor (cursor)
  9702.        sout << "   " << cursor.element() << "\n";
  9703.      return sout << "\n";
  9704.    }
  9705.  
  9706.    main(){
  9707.      TestKeySet t;
  9708.     try {
  9709.         t.add(DemoElement(1,1));
  9710.         t.add(DemoElement(2,4711));
  9711.         t.add(DemoElement(3,1));
  9712.         t.add(DemoElement(4,443));
  9713.  
  9714.         cout << t;
  9715.  
  9716.         t.removeElementWithKey (3);
  9717.         cout << t;
  9718.       }
  9719.     catch (IException & exception) {
  9720.       cout << exception.name() << " : " << exception.text();
  9721.       }
  9722.  
  9723.      return 0;
  9724.    }
  9725.  
  9726. The program produces the following output: 
  9727.  
  9728.    4 elements are in the set:
  9729.       1,1
  9730.       2,4711
  9731.       3,1
  9732.       4,443
  9733.  
  9734.    3 elements are in the set:
  9735.       1,1
  9736.       2,4711
  9737.       4,443
  9738.  
  9739.  
  9740. ΓòÉΓòÉΓòÉ 5.1.9. Key Sorted Bag ΓòÉΓòÉΓòÉ
  9741.  
  9742. Description 
  9743.  
  9744. Derivation 
  9745.  
  9746. Variants/Header Files 
  9747.  
  9748. Members 
  9749.  
  9750. Template Arguments and Required Functions 
  9751.  
  9752. Abstract/Reference Classes 
  9753.  
  9754. Examples 
  9755.  
  9756. To close all the panels in a chapter, double-click on this panel's system menu. 
  9757.  
  9758.  
  9759. ΓòÉΓòÉΓòÉ 5.1.9.1. Class Description - Key Sorted Bag ΓòÉΓòÉΓòÉ
  9760.  
  9761. A key sorted bag is an ordered collection of zero or more elements that have a 
  9762. key.  Elements are sorted according to the value of their key field.  Element 
  9763. equality is not supported.  Multiple elements are supported. 
  9764.  
  9765. An example of using a key sorted bag is a program that maintains a list of 
  9766. families, sorted by the number of family members in each family.  The key is 
  9767. the number of family members.  You can add an element whose key is already in 
  9768. the collection (because two families can have the same number of members), and 
  9769. you can generate a list of families sorted by size.  You cannot locate a family 
  9770. except by its key, because a key sorted bag does not support element equality. 
  9771.  
  9772. Figure Combination of Flat Collection Properties gives an overview of the 
  9773. properties of a key sorted bag and its relationship to other flat collections. 
  9774.  
  9775.  
  9776. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  9777.  
  9778.           Collection 
  9779.  
  9780.                Ordered Collection
  9781.   Key Collection         Sorted Collection
  9782.        Key Sorted Collection
  9783.          Key Sorted Bag
  9784.  
  9785.  
  9786. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  9787.  
  9788. IKeySortedBag, the first class in the table below, is the default 
  9789. implementation variant. If you want to use polymorphism, you can replace the 
  9790. following class implementation variants by the reference class. 
  9791.  
  9792. To use Visual Builder features with your collections, change the name of the 
  9793. desired collection class template in the list below from I... to IV..., and use 
  9794. the ivksbag.h header file instead of the header file that you would normally 
  9795. use without Visual Builder. 
  9796.  
  9797. Class Name                             Header File Implementation Variant
  9798.  
  9799. IKeySortedBag                          iksbag.h    Linked sequence
  9800. IGKeySortedBag                         iksbag.h    Linked sequence
  9801.  
  9802. IKeySortedBagOnSortedTabularSequence   iksbsts.h   Tabular sequence
  9803. IGKeySortedBagOnSortedTabularSequence  iksbsts.h   Tabular sequence
  9804.  
  9805. IKeySortedBagOnSortedDilutedSequence   iksbsds.h   Diluted sequence
  9806. IGKeySortedBagOnSortedDilutedSequence  iksbsds.h   Diluted sequence
  9807.  
  9808.  
  9809. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  9810.  
  9811. All members of flat collections are described in Introduction to Flat 
  9812. Collections. The following members are provided for key sorted bag: 
  9813.  
  9814.      Constructor 
  9815.      Copy Constructor 
  9816.      Destructor 
  9817.      operator= 
  9818.      add 
  9819.      addAllFrom 
  9820.      addOrReplaceElementWithKey 
  9821.      allElementsDo 
  9822.      anyElement 
  9823.      compare 
  9824.      containsAllKeysFrom 
  9825.      containsElementWithKey 
  9826.      elementAt 
  9827.      elementAtPosition 
  9828.      elementWithKey 
  9829.      firstElement 
  9830.      isBounded 
  9831.      isEmpty 
  9832.      isFirst 
  9833.      isFull 
  9834.      isLast 
  9835.      key 
  9836.      lastElement 
  9837.      locateElementWithKey 
  9838.      locateNextElementWithKey 
  9839.      locateOrAddElementWithKey 
  9840.      maxNumberOfElements 
  9841.      newCursor 
  9842.      numberOfDifferentKeys 
  9843.      numberOfElements 
  9844.      numberOfElementsWithKey 
  9845.      position 
  9846.      removeAll 
  9847.      removeAllElementsWithKey 
  9848.      removeAt 
  9849.      removeAtPosition 
  9850.      removeElementWithKey 
  9851.      removeFirst 
  9852.      removeLast 
  9853.      replaceAt 
  9854.      replaceElementWithKey 
  9855.      setToFirst 
  9856.      setToLast 
  9857.      setToNext 
  9858.      setToNextWithDifferentKey 
  9859.      setToPosition 
  9860.      setToPrevious 
  9861.  
  9862.  Key sorted bag also defines a cursor that inherits from IOrderedCursor. The 
  9863.  members for IOrderedCursor are described in Cursor. 
  9864.  
  9865.  
  9866. ΓòÉΓòÉΓòÉ 5.1.9.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  9867.  
  9868. The following implementation variants are defined for key sorted bags: 
  9869.  
  9870.      Key Sorted Bag 
  9871.      Key Sorted Bag on Tabular Sequence 
  9872.      Key Sorted Bag on Diluted Sequence 
  9873.  
  9874.  
  9875. ΓòÉΓòÉΓòÉ 5.1.9.2.1. Key Sorted Bag ΓòÉΓòÉΓòÉ
  9876.  
  9877. IKeySortedBag  <Element, Key>
  9878. IGKeySortedBag <Element, Key, KCOps>
  9879.  
  9880. The implementation of the class IKeySortedBag requires the following element 
  9881. and key-type functions: 
  9882.  
  9883. Element Type 
  9884.  
  9885.      Copy constructor 
  9886.      Destructor 
  9887.      Assignment 
  9888.      Key access 
  9889.  
  9890.  Key Type 
  9891.  
  9892.  Ordering relation 
  9893.  
  9894.  
  9895. ΓòÉΓòÉΓòÉ 5.1.9.2.2. Key Sorted Bag on Tabular Sequence ΓòÉΓòÉΓòÉ
  9896.  
  9897. IKeySortedBagOnTabularSequence  <Element, Key>
  9898. IGKeySortedBagOnTabularSequence <Element, Key, KCOps>
  9899.  
  9900. The implementation of the class IKeySortedBagOnTabularSequence requires the 
  9901. following element and key-type functions: 
  9902.  
  9903. Element Type 
  9904.  
  9905.      Default constructor 
  9906.      Copy constructor 
  9907.      Destructor 
  9908.      Assignment 
  9909.      Key access 
  9910.  
  9911.  Key Type 
  9912.  
  9913.  Ordering relation 
  9914.  
  9915.  
  9916. ΓòÉΓòÉΓòÉ 5.1.9.2.3. Key Sorted Bag on Diluted Sequence ΓòÉΓòÉΓòÉ
  9917.  
  9918. IKeySortedBagOnDilutedSequence  <Element, Key>
  9919. IGKeySortedBagOnDilutedSequence <Element, Key, KCOps>
  9920.  
  9921. The implementation of the class IKeySortedBagOnDilutedSequence requires the 
  9922. following element and key-type functions: 
  9923.  
  9924. Element Type 
  9925.  
  9926.      Default constructor 
  9927.      Copy constructor 
  9928.      Destructor 
  9929.      Assignment 
  9930.      Key access 
  9931.  
  9932.  Key Type 
  9933.  
  9934.  Ordering relation 
  9935.  
  9936.  
  9937. ΓòÉΓòÉΓòÉ 5.1.9.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  9938.  
  9939. For polymorphism, you can use the corresponding abstract class, IAKeySortedBag, 
  9940. which is found in the iaksbag.h header file, or the corresponding reference 
  9941. class, IRKeySortedBag, which is found in the irksbag.h header file. See 
  9942. Polymorphic Use of Collections for further information. 
  9943.  
  9944.  
  9945. ΓòÉΓòÉΓòÉ 5.1.9.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  9946.  
  9947. IAKSBag <Element, Key>
  9948. IRKSBag <Element, Key, ConcreteBase>
  9949.  
  9950. The concrete base class is one of the classes defined above. 
  9951.  
  9952. The required functions are the same as the required functions of the concrete 
  9953. base class. 
  9954.  
  9955.  
  9956. ΓòÉΓòÉΓòÉ 5.1.9.4. Coding Example for Key Sorted Bag ΓòÉΓòÉΓòÉ
  9957.  
  9958. The following program illustrates the use of a key sorted bag. The program 
  9959. determines the number of words that have the same length in a phrase. It stores 
  9960. the words of the phrase in a key sorted bag that it implements using the 
  9961. default class, IKeySortedBag. The program makes the key the length of the word. 
  9962. Because of the properties of a key sorted bag, it sorts the words by their 
  9963. length (the key), and it stores all duplicate words. 
  9964.  
  9965. The program determines the number of different word lengths using the 
  9966. numberOfDifferentKeys() function. It uses the numberOfElementsWithKey() 
  9967. function and the setToNextWithDifferentKey() function to iterate through the 
  9968. collection and count the number of words with the same length. 
  9969.  
  9970.    // wordbag.C  -  An example of using a Key Sorted Bag
  9971.    #include <iostream.h>
  9972.                                 // Class Word
  9973.    #include "toyword.h"
  9974.                                 // Let's use the defaults:
  9975.    #include <iksbag.h>
  9976.  
  9977.    typedef IKeySortedBag <Word, unsigned> WordBag;
  9978.  
  9979.  
  9980.    int main()
  9981.    {
  9982.       IString    phrase[] = {"people", "who", "live", "in", "glass",
  9983.                       "houses", "should", "not", "throw", "stones"};
  9984.       const size_t phraseWords = sizeof(phrase) / sizeof(IString);
  9985.  
  9986.       WordBag wordbag(phraseWords);
  9987.  
  9988.       for (int cnt=0; cnt < phraseWords; cnt++)  {
  9989.        unsigned keyValue = phrase[cnt].length();
  9990.        Word theWord(phrase[cnt],keyValue);
  9991.        wordbag.add (theWord);
  9992.       }
  9993.  
  9994.       cout << "Contents of our WordBag sorted by number of letters:" << endl;
  9995.  
  9996.       WordBag::Cursor wordBagCursor(wordbag);
  9997.       forCursor(wordBagCursor)
  9998.         cout << "WB: " << wordBagCursor.element().getWord() << endl;
  9999.  
  10000.       cout << endl << "Our phrase has " << phraseWords << " words." << endl                        ;
  10001.       cout << "In our WordBag are " << wordbag.numberOfElements()
  10002.            << " words." << endl << endl;
  10003.  
  10004.       cout << "There are " << wordbag.numberOfDifferentKeys()
  10005.            << " different word lengths." << endl << endl;
  10006.  
  10007.       wordBagCursor.setToFirst();
  10008.       do  {
  10009.          unsigned letters = wordbag.key(wordBagCursor.element());
  10010.          cout << "There are "
  10011.               << wordbag.numberOfElementsWithKey(letters)
  10012.               << " words with " << letters << " letters." << endl;
  10013.       }  while  (wordbag.setToNextWithDifferentKey(wordBagCursor));
  10014.  
  10015.       return 0;
  10016.    }
  10017.  
  10018. This program produces the following output: 
  10019.  
  10020. Contents of our WordBag sorted by number of letters:
  10021. WB: in
  10022. WB: who
  10023. WB: not
  10024. WB: live
  10025. WB: glass
  10026. WB: throw
  10027. WB: people
  10028. WB: houses
  10029. WB: should
  10030. WB: stones
  10031.  
  10032. Our phrase has 10 words.
  10033. In our WordBag are 10 words.
  10034.  
  10035. There are 5 different word lengths.
  10036.  
  10037. There are 1 words with 2 letters.
  10038. There are 2 words with 3 letters.
  10039. There are 1 words with 4 letters.
  10040. There are 2 words with 5 letters.
  10041. There are 4 words with 6 letters.
  10042.  
  10043.  
  10044. ΓòÉΓòÉΓòÉ 5.1.10. Key Sorted Set ΓòÉΓòÉΓòÉ
  10045.  
  10046. Description 
  10047.  
  10048. Derivation 
  10049.  
  10050. Variants/Header Files 
  10051.  
  10052. Members 
  10053.  
  10054. Template Arguments and Required Functions 
  10055.  
  10056. Abstract/Reference Classes 
  10057.  
  10058. Examples 
  10059.  
  10060. To close all the panels in a chapter, double-click on this panel's system menu. 
  10061.  
  10062.  
  10063. ΓòÉΓòÉΓòÉ 5.1.10.1. Class Description - Key Sorted Set ΓòÉΓòÉΓòÉ
  10064.  
  10065. A key sorted set is an ordered collection of zero or more elements that have a 
  10066. key.  Elements are sorted according to the value of their key field.  Element 
  10067. equality is not supported.  Only elements with unique keys are supported.  A 
  10068. request to add an element whose key already exists is ignored. 
  10069.  
  10070. An example of using a key sorted set is a program that keeps track of canceled 
  10071. credit card numbers and the individuals to whom they are issued.  Each card 
  10072. number occurs only once, and the collection is sorted by card number.  When a 
  10073. merchant enters a customer's card number into a point-of-sale terminal, the 
  10074. collection is checked to see if that card number is listed in the collection of 
  10075. canceled cards.  If it is found, the name of the individual is shown, and the 
  10076. merchant is given directions for contacting the card company.  If the card 
  10077. number is not found, the transaction can proceed because the card is valid. A 
  10078. list of canceled cards is printed out each month, sorted by card number, and 
  10079. distributed to all merchants who do not have an automatic point-of-sale 
  10080. terminal installed. 
  10081.  
  10082. Figure Combination of Flat Collection Properties gives an overview of the 
  10083. properties of a key sorted set and its relationship to other flat collections. 
  10084.  
  10085.  
  10086. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  10087.  
  10088.           Collection 
  10089.  
  10090.                Ordered Collection
  10091.   Key Collection         Sorted Collection
  10092.        Key Sorted Collection
  10093.          Key Sorted Set
  10094.  
  10095.  
  10096. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  10097.  
  10098. IKeySortedSet, the first class in the table below, is the default 
  10099. implementation variant. If you want to use polymorphism, you can replace the 
  10100. following class implementation variants by the reference class. 
  10101.  
  10102. To use Visual Builder features with your collections, change the name of the 
  10103. desired collection class template in the list below from I... to IV..., and use 
  10104. the ivksset.h header file instead of the header file that you would normally 
  10105. use without Visual Builder. 
  10106.  
  10107. Class Name             Header File  Implementation Variant
  10108.  
  10109. IKeySortedSet          iksset.h     AVL tree
  10110. IGKeySortedSet         iksset.h     AVL tree
  10111. IAVLKeySortedSet       iavlkss.h    AVL tree
  10112. IGAVLKeySortedSet      iavlkss.h    AVL tree
  10113.  
  10114. IBSTKeySortedSet       ibstkss.h    B* tree
  10115. IGBSTKeySortedSet      ibstkss.h    B* tree
  10116.  
  10117. IKeySortedSetOn-       iksssls.h    Linked sequence
  10118.  SortedLinkedSequence
  10119. IGKeySortedSetOn-      iksssls.h    Linked sequence
  10120.  SortedLinkedSequence
  10121.  
  10122. IKeySortedSetOn-       iksssts.h    Tabular sequence
  10123.  SortedTabularSequence
  10124. IGKeySortedSetOn-      iksssts.h    Tabular sequence
  10125.  SortedTabularSequence
  10126.  
  10127. IKeySortedSetOn-       iksssds.h    Diluted sequence
  10128.  SortedDilutedSequence
  10129. IGKeySortedSetOn-      iksssds.h    Diluted sequence
  10130.  SortedDilutedSequence
  10131.  
  10132.  
  10133. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  10134.  
  10135. All members of flat collections are described in Introduction to Flat 
  10136. Collections. The following members are provided for key sorted set: 
  10137.  
  10138.      Constructor 
  10139.      Copy Constructor 
  10140.      Destructor 
  10141.      operator= 
  10142.      add 
  10143.      addAllFrom 
  10144.      addOrReplaceElementWithKey 
  10145.      allElementsDo 
  10146.      anyElement 
  10147.      compare 
  10148.      containsAllKeysFrom 
  10149.      containsElementWithKey 
  10150.      elementAt 
  10151.      elementAtPosition 
  10152.      elementWithKey 
  10153.      firstElement 
  10154.      isBounded 
  10155.      isEmpty 
  10156.      isFirst 
  10157.      isFull 
  10158.      isLast 
  10159.      key 
  10160.      lastElement 
  10161.      locateElementWithKey 
  10162.      locateNextElementWithKey 
  10163.      locateOrAddElementWithKey 
  10164.      maxNumberOfElements 
  10165.      newCursor 
  10166.      numberOfElements 
  10167.      position 
  10168.      removeAll 
  10169.      removeAt 
  10170.      removeAtPosition 
  10171.      removeElementWithKey 
  10172.      removeFirst 
  10173.      removeLast 
  10174.      replaceAt 
  10175.      replaceElementWithKey 
  10176.      setToFirst 
  10177.      setToLast 
  10178.      setToNext 
  10179.      setToPosition 
  10180.      setToPrevious 
  10181.  
  10182.  Key Sorted Set also defines a cursor that inherits from IOrderedCursor. The 
  10183.  members for IOrderedCursor are described in Cursor. 
  10184.  
  10185.  
  10186. ΓòÉΓòÉΓòÉ 5.1.10.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  10187.  
  10188. The following implementation variants are defined for key sorted sets: 
  10189.  
  10190.      Key sorted set 
  10191.      AVL key sorted set 
  10192.      B* key sorted set 
  10193.      Key sorted set on sorted linked sequence 
  10194.      Key sorted set on sorted tabular sequence 
  10195.      Key sorted set on Sorted diluted sequence 
  10196.  
  10197.  
  10198. ΓòÉΓòÉΓòÉ 5.1.10.2.1. Key Sorted Set ΓòÉΓòÉΓòÉ
  10199.  
  10200. IKeySortedSet  <Element, Key>
  10201. IGKeySortedSet <Element, Key, KCOps>
  10202.  
  10203. The implementation of the class IKeySortedSet requires the following element 
  10204. and key-type functions: 
  10205.  
  10206. Element Type 
  10207.  
  10208.      Copy constructor 
  10209.      Destructor 
  10210.      Assignment 
  10211.      Key access 
  10212.  
  10213.  Key Type 
  10214.  
  10215.  Ordering relation 
  10216.  
  10217.  
  10218. ΓòÉΓòÉΓòÉ 5.1.10.2.2. AVL Key Sorted Set. ΓòÉΓòÉΓòÉ
  10219.  
  10220. IAVLKeySortedSet  <Element>
  10221. IGAVLKeySortedSet <Element, Key, KCOps>
  10222.  
  10223. The implementation of the class IAVLKeySortedSet requires the following element 
  10224. and key-type functions: 
  10225.  
  10226. Element Type 
  10227.  
  10228.      Copy constructor 
  10229.      Assignment 
  10230.      Destructor 
  10231.      Key access 
  10232.  
  10233.  Key Type 
  10234.  
  10235.  Ordering relation 
  10236.  
  10237.  
  10238. ΓòÉΓòÉΓòÉ 5.1.10.2.3. B* Key Sorted Set ΓòÉΓòÉΓòÉ
  10239.  
  10240. IBSTKeySortedSet  <Element, Key>
  10241. IBSTKeySortedSet  <Element, Key, KCOps>
  10242.  
  10243. The implementation of the class IBSTKeySortedSet requires the following element 
  10244. and key-type functions: 
  10245.  
  10246. Element Type 
  10247.  
  10248.      Default constructor 
  10249.      Copy constructor 
  10250.      Destructor 
  10251.      Assignment 
  10252.      Key access 
  10253.  
  10254.  Key Type 
  10255.  
  10256.  Ordering relation 
  10257.  
  10258.  
  10259. ΓòÉΓòÉΓòÉ 5.1.10.2.4. Key Sorted Set on Sorted Linked Sequence ΓòÉΓòÉΓòÉ
  10260.  
  10261. IKeySortedSetOnSortedLinkedSequence  <Element>
  10262. IGKeySortedSetOnSortedLinkedSequence <Element, Key, KCOps>
  10263.  
  10264. The implementation of the class IKeySortedSetOnSortedLinkedSequence requires 
  10265. the following element and key-type functions: 
  10266.  
  10267. Element Type 
  10268.  
  10269.      Copy constructor 
  10270.      Destructor 
  10271.      Assignment 
  10272.      Key access 
  10273.  
  10274.  Key Type 
  10275.  
  10276.  Ordering relation 
  10277.  
  10278.  
  10279. ΓòÉΓòÉΓòÉ 5.1.10.2.5. Key Sorted Set on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  10280.  
  10281. IKeySortedSetOnSortedTabularSequence  <Element>
  10282. IGKeySortedSetOnSortedTabularSequence <Element, Key, KCOps>
  10283.  
  10284. The implementation of the class IKeySortedSetOnSortedTabularSequence requires 
  10285. the following element and key-type functions: 
  10286.  
  10287. Element Type 
  10288.  
  10289.      Default constructor 
  10290.      Copy constructor 
  10291.      Destructor 
  10292.      Assignment 
  10293.      Key access 
  10294.  
  10295.  Key Type 
  10296.  
  10297.  Ordering relation 
  10298.  
  10299.  
  10300. ΓòÉΓòÉΓòÉ 5.1.10.2.6. Key Sorted Set on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  10301.  
  10302. IKeySortedSetOnSortedDilutedSequence  <Element, Key>
  10303. IGKeySortedSetOnSortedDilutedSequence <Element, Key, KCOps>
  10304.  
  10305. The implementation of the class IKeySortedSetOnSortedDilutedSequence requires 
  10306. the following element and key-type functions: 
  10307.  
  10308. Element Type 
  10309.  
  10310.      Default constructor 
  10311.      Copy constructor 
  10312.      Destructor 
  10313.      Assignment 
  10314.      Key access 
  10315.  
  10316.  Key Type 
  10317.  
  10318.  Ordering relation 
  10319.  
  10320.  
  10321. ΓòÉΓòÉΓòÉ 5.1.10.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  10322.  
  10323. For polymorphism, you can use the corresponding abstract class, IAKeySortedSet, 
  10324. which is found in the iaksset.h header file, or the corresponding reference 
  10325. class, IRKeySortedSet, which is found in the irksset.h header file. See 
  10326. Polymorphic Use of Collections for further information. 
  10327.  
  10328.  
  10329. ΓòÉΓòÉΓòÉ 5.1.10.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  10330.  
  10331. IAKeySortedSet <Element, Key>
  10332. IRKeySortedSet <Element, Key, ConcreteBase>
  10333.  
  10334. The concrete base class is one of the classes defined above. 
  10335.  
  10336. The required functions are the same as the required functions of the concrete 
  10337. base class. 
  10338.  
  10339.  
  10340. ΓòÉΓòÉΓòÉ 5.1.10.4. Coding Example for Key Sorted Set ΓòÉΓòÉΓòÉ
  10341.  
  10342. The following program uses the default classes for a key sorted set and a heap, 
  10343. IKeySortedSet and IHeap, to track parcels for a delivery service.  It uses a 
  10344. key sorted set to record the parcels that are currently in circulation.  The 
  10345. fast access of a sorted collection is not necessary to keep track of the 
  10346. delivered parcels, so the program uses a heap to keep track of them. 
  10347.  
  10348. The parcel element contains three data members: one of type PlaceTime that 
  10349. stores the origin time and place of the parcel, another of type PlaceTime that 
  10350. stores the current time and place of the parcel, and one of type ToyString that 
  10351. stores the destination. 
  10352.  
  10353. The function update() adds parcels that have arrived at their destinations to 
  10354. the heap of delivered parcels, and removes them from the key sorted set for 
  10355. circulating parcels. 
  10356.  
  10357. The program uses the add() function to update and the removeAll() function to 
  10358. remove elements from the key sorted set. 
  10359.  
  10360.    // parcel.C  -  An example of using a Key Sorted Set and a Heap
  10361.    #include <iostream.h>
  10362.  
  10363.    #include "parcel.h"
  10364.                              // Let's use the default KeySorted Set:
  10365.    #include <iksset.h>
  10366.                              // Let's use the default Heap:
  10367.    #include <iheap.h>
  10368.  
  10369.    typedef IKeySortedSet<Parcel, ToyString> ParcelSet;
  10370.    typedef IHeap        <Parcel>            ParcelHeap;
  10371.  
  10372.    ostream& operator<<(ostream&, ParcelSet const&);
  10373.    ostream& operator<<(ostream&, ParcelHeap const&);
  10374.  
  10375.    void update(ParcelSet&, ParcelHeap&);
  10376.  
  10377.  
  10378.    main()  {
  10379.  
  10380.        ParcelSet circulating;
  10381.        ParcelHeap delivered;
  10382.  
  10383.        int today = 8;
  10384.  
  10385.        circulating.add(Parcel("London", "Athens",
  10386.           today,      "26LoAt"));
  10387.        circulating.add(Parcel("Amsterdam", "Toronto",
  10388.           today += 2, "27AmTo"));
  10389.        circulating.add(Parcel("Washington", "Stockholm",
  10390.           today += 5, "25WaSt"));
  10391.        circulating.add(Parcel("Dublin", "Kairo",
  10392.           today += 1, "25DuKa"));
  10393.        update(circulating, delivered);
  10394.        cout << "\nThe situation at start:\n";
  10395.        cout << "Parcels in circulation:\n" << circulating;
  10396.  
  10397.        today ++;
  10398.        circulating.elementWithKey("27AmTo").arrivedAt(
  10399.           "Atlanta",   today);
  10400.        circulating.elementWithKey("25WaSt").arrivedAt(
  10401.           "Amsterdam", today);
  10402.        circulating.elementWithKey("25DuKa").arrivedAt(
  10403.           "Paris",     today);
  10404.        update(circulating, delivered);
  10405.        cout << "\n\nThe situation at day " << today << ":\n";
  10406.        cout << "Parcels in circulation:\n" << circulating;
  10407.  
  10408.        today ++;          // One day later ...
  10409.        circulating.elementWithKey("27AmTo").arrivedAt("Chicago", today);
  10410.                   // As in real life, one parcel gets lost:
  10411.        circulating.removeElementWithKey("26LoAt");
  10412.        update(circulating, delivered);
  10413.        cout << "\n\nThe situation at day " << today << ":\n";
  10414.        cout << "Parcels in circulation:\n" << circulating;
  10415.  
  10416.        today ++;
  10417.        circulating.elementWithKey("25WaSt").arrivedAt("Oslo", today);
  10418.        circulating.elementWithKey("25DuKa").arrivedAt("Kairo", today);
  10419.                   // New parcels are shipped.
  10420.        circulating.add(Parcel("Dublin", "Rome", today,   "27DuRo"));
  10421.                   // Let's try to add one with a key already there.
  10422.                   // The KeySsorted Set should ignore it:
  10423.        circulating.add(Parcel("Nowhere", "Nirvana", today, "25WaSt"));
  10424.        update(circulating, delivered);
  10425.        cout << "\n\nThe situation at day " << today << ":\n";
  10426.        cout << "Parcels in circulation:\n" << circulating;
  10427.        cout << "Parcels delivered:\n" << delivered;
  10428.  
  10429.                         // Now we make all parcels arrive today:
  10430.        today ++;
  10431.  
  10432.        ParcelSet::Cursor circulatingcursor(circulating);
  10433.        forCursor(circulatingcursor) {
  10434.           circulating.elementAt(circulatingcursor).wasDelivered(today);
  10435.        }
  10436.        update(circulating, delivered);
  10437.        cout << "\n\nThe situation at day " << today << ":\n";
  10438.        cout << "Parcels in circulation:\n" << circulating;
  10439.        cout << "Parcels delivered:\n" << delivered;
  10440.  
  10441.        if (circulating.isEmpty())
  10442.           cout << "\nAll parcels were delivered.\n";
  10443.        else
  10444.           cout << "\nSomething very strange happened here.\n";
  10445.  
  10446.        return  0;
  10447.    }
  10448.  
  10449.    ostream& operator<<(ostream& os, ParcelSet const& parcels)  {
  10450.        ParcelSet::Cursor pcursor(parcels);
  10451.        forCursor(pcursor) {
  10452.           os <<  pcursor.element() << "\n";
  10453.        }
  10454.        return os;
  10455.    }
  10456.  
  10457.    ostream& operator<<(ostream& os, ParcelHeap const& parcels)  {
  10458.        ParcelHeap::Cursor pcursor(parcels);
  10459.        forCursor(pcursor) {
  10460.           os <<  pcursor.element() << "\n";
  10461.        }
  10462.        return os;
  10463.    }
  10464.  
  10465.    Boolean wasDelivered(Parcel const& p, void* dp) {
  10466.         if ( p.lastArrival().city() == p.destination() ) {
  10467.            ((ParcelHeap*)dp)->add(p);
  10468.            return True;
  10469.         }
  10470.         else
  10471.            return False;
  10472.    }
  10473.  
  10474.    void update(ParcelSet& p, ParcelHeap& d) {
  10475.         p.removeAll(wasDelivered, &d);
  10476.    }
  10477.  
  10478. The program produces the following output: 
  10479.  
  10480.  
  10481. The situation at start:
  10482. Parcels in circulation:
  10483. 25DuKa: From Dublin(day 16) to Kairo
  10484.             is at Dublin  since day 16.
  10485. 25WaSt: From Washington(day 15) to Stockholm
  10486.             is at Washington  since day 15.
  10487. 26LoAt: From London(day 8) to Athens
  10488.             is at London  since day 8.
  10489. 27AmTo: From Amsterdam(day 10) to Toronto
  10490.             is at Amsterdam  since day 10.
  10491.  
  10492.  
  10493. The situation at day 17:
  10494. Parcels in circulation:
  10495. 25DuKa: From Dublin(day 16) to Kairo
  10496.             is at Paris  since day 17.
  10497. 25WaSt: From Washington(day 15) to Stockholm
  10498.             is at Amsterdam  since day 17.
  10499. 26LoAt: From London(day 8) to Athens
  10500.             is at London  since day 8.
  10501. 27AmTo: From Amsterdam(day 10) to Toronto
  10502.             is at Atlanta  since day 17.
  10503.  
  10504.  
  10505. The situation at day 18:
  10506. Parcels in circulation:
  10507. 25DuKa: From Dublin(day 16) to Kairo
  10508.             is at Paris  since day 17.
  10509. 25WaSt: From Washington(day 15) to Stockholm
  10510.             is at Amsterdam  since day 17.
  10511. 27AmTo: From Amsterdam(day 10) to Toronto
  10512.             is at Chicago  since day 18.
  10513.  
  10514.  
  10515. The situation at day 19:
  10516. Parcels in circulation:
  10517. 25WaSt: From Washington(day 15) to Stockholm
  10518.             is at Oslo  since day 19.
  10519. 27AmTo: From Amsterdam(day 10) to Toronto
  10520.             is at Chicago  since day 18.
  10521. 27DuRo: From Dublin(day 19) to Rome
  10522.             is at Dublin  since day 19.
  10523. Parcels delivered:
  10524. 25DuKa: From Dublin(day 16) to Kairo
  10525.             was delivered on day 19.
  10526.  
  10527.  
  10528. The situation at day 20:
  10529. Parcels in circulation:
  10530. Parcels delivered:
  10531. 25DuKa: From Dublin(day 16) to Kairo
  10532.             was delivered on day 19.
  10533. 25WaSt: From Washington(day 15) to Stockholm
  10534.             was delivered on day 20.
  10535. 27AmTo: From Amsterdam(day 10) to Toronto
  10536.             was delivered on day 20.
  10537. 27DuRo: From Dublin(day 19) to Rome
  10538.             was delivered on day 20.
  10539.  
  10540. All parcels were delivered.
  10541.  
  10542.  
  10543. ΓòÉΓòÉΓòÉ 5.1.11. Map ΓòÉΓòÉΓòÉ
  10544.  
  10545. Description 
  10546.  
  10547. Derivation 
  10548.  
  10549. Variants/Header Files 
  10550.  
  10551. Members 
  10552.  
  10553. Template Arguments and Required Functions 
  10554.  
  10555. Abstract/Reference Classes 
  10556.  
  10557. Examples 
  10558.  
  10559. To close all the panels in a chapter, double-click on this panel's system menu. 
  10560.  
  10561.  
  10562. ΓòÉΓòÉΓòÉ 5.1.11.1. Class Description - Map ΓòÉΓòÉΓòÉ
  10563.  
  10564. A map is an unordered collection of zero or more elements that have a key. 
  10565. Element equality is supported and the values of the elements are relevant. 
  10566.  
  10567. Only elements with unique keys are supported.  A request to add an element 
  10568. whose key already exists in another element of the collection causes an 
  10569. exception to be thrown.  A request to add a duplicate element is ignored. 
  10570.  
  10571. An example of using a map is a program that translates integer values between 
  10572. the ranges of 0 and 20 to their written equivalents, or between written numbers 
  10573. and their numeric values. Two maps are created, one with the integer values as 
  10574. keys, one with the written equivalents as keys.  You can enter a number, and 
  10575. that number is used as a key to locate the written equivalent.  You can enter a 
  10576. written equivalent of a number, and that text is used as a key to locate the 
  10577. value.  A given key always matches only one element.  You cannot add an element 
  10578. with a key of 1 or "one" if that element is already present in the collection. 
  10579.  
  10580. Figure Behavior of add for Unique and Miltiple Collections illustrates the 
  10581. differences in behavior between map, relation, key set, and key bag when 
  10582. identical elements and elements with the same key are added. 
  10583.  
  10584. Figure Combination of Flat Collection Properties gives an overview of the 
  10585. properties of a map and its relationship to other flat collections. 
  10586.  
  10587.  
  10588. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  10589.  
  10590.            Collection 
  10591.  
  10592.   Key Collection          Equality Collection
  10593.          Equality Key Collection
  10594.              Map
  10595.  
  10596.  
  10597. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  10598.  
  10599. IMap, the first class in the table below, is the default implementation 
  10600. variant. If you want to use polymorphism, you can replace the following class 
  10601. implementation variants by the reference class. 
  10602.  
  10603. To use Visual Builder features with your collections, change the name of the 
  10604. desired collection class template in the list below from I... to IV..., and use 
  10605. the ivmap.h header file instead of the header file that you would normally use 
  10606. without Visual Builder. 
  10607.  
  10608. Class Name                   Header File Implementation Variant
  10609.  
  10610. IMap                         imap.h      AVL tree
  10611. IGMap                        imap.h      AVL tree
  10612.  
  10613. IMapOnBSTKeySortedSet        imapbst.h   B* tree
  10614. IGMapOnBSTKeySortedSet       imapbst.h   B* tree
  10615.  
  10616. IMapOnSortedLinkedSequence   imapsls.h   Linked sequence
  10617. IGMapOnSortedLinkedSequence  imapsls.h   Linked sequence
  10618.  
  10619. IMapOnSortedTabularSequence  imapsts.h   Tabular sequence
  10620. IGMapOnSortedTabularSequence imapsts.h   Tabular sequence
  10621.  
  10622. IMapOnSortedDilutedSequence  imapsds.h   Diluted sequence
  10623. IGMapOnSortedDilutedSequence imapsds.h   Diluted sequence
  10624.  
  10625. IMapOnHashKeySet             imaphks.h   Hash table
  10626. IGMapOnHashKeySet            imaphks.h   Hash table
  10627.  
  10628.  
  10629. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  10630.  
  10631. All members of flat collections are described in Introduction to Flat 
  10632. Collections. The following members are provided for map: 
  10633.  
  10634.      Constructor 
  10635.      Copy Constructor 
  10636.      Destructor 
  10637.      operator!= 
  10638.      operator= 
  10639.      operator== 
  10640.      add 
  10641.      addAllFrom 
  10642.      addDifference 
  10643.      addIntersection 
  10644.      addOrReplaceElementWithKey 
  10645.      addUnion 
  10646.      allElementsDo 
  10647.      anyElement 
  10648.      contains 
  10649.      containsAllFrom 
  10650.      containsAllKeysFrom 
  10651.      containsElementWithKey 
  10652.      differenceWith 
  10653.      elementAt 
  10654.      elementWithKey 
  10655.      intersectionWith 
  10656.      isBounded 
  10657.      isEmpty 
  10658.      isFull 
  10659.      key 
  10660.      locate 
  10661.      locateElementWithKey 
  10662.      locateOrAdd 
  10663.      locateOrAddElementWithKey 
  10664.      maxNumberOfElements 
  10665.      newCursor 
  10666.      numberOfElements 
  10667.      remove 
  10668.      removeAll 
  10669.      removeAt 
  10670.      removeElementWithKey 
  10671.      replaceAt 
  10672.      replaceElementWithKey 
  10673.      setToFirst 
  10674.      setToNext 
  10675.      unionWith 
  10676.  
  10677.  Map also defines a cursor that inherits from IElementCursor. The members for 
  10678.  IElementCursor are described in Cursor. 
  10679.  
  10680.  
  10681. ΓòÉΓòÉΓòÉ 5.1.11.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  10682.  
  10683. The following implementation variants are defined for maps: 
  10684.  
  10685.      Map 
  10686.      Map on B* key sorted set 
  10687.      Map on sorted linked sequence 
  10688.      Map on sorted tabular sequence 
  10689.      Map on sorted diluted sequence 
  10690.      Map on hash key set 
  10691.  
  10692.  
  10693. ΓòÉΓòÉΓòÉ 5.1.11.2.1. Map ΓòÉΓòÉΓòÉ
  10694.  
  10695. IMap  <Element, Key>
  10696. IGMap <Element, Key, EKCOps>
  10697.  
  10698. The default implementation of the class IMap requires the following element and 
  10699. key-type functions: 
  10700.  
  10701. Element Type 
  10702.  
  10703.      Copy constructor 
  10704.      Destructor 
  10705.      Assignment 
  10706.      Equality test 
  10707.      Key access 
  10708.  
  10709.  Key Type 
  10710.  
  10711.  Ordering relation 
  10712.  
  10713.  
  10714. ΓòÉΓòÉΓòÉ 5.1.11.2.2. Map on B* Key Sorted Set ΓòÉΓòÉΓòÉ
  10715.  
  10716. IMapOnBSTKeySortedSet  <Element, Key>
  10717. IGMapOnBSTKeySortedSet <Element, Key, EKCOps>
  10718.  
  10719. The implementation of the class IMapOnBSTKeySortedSet requires the following 
  10720. element and key-type functions: 
  10721.  
  10722. Element Type 
  10723.  
  10724.      Default constructor 
  10725.      Copy constructor 
  10726.      Destructor 
  10727.      Assignment 
  10728.      Equality test 
  10729.      Key access 
  10730.  
  10731.  Key Type 
  10732.  
  10733.  Ordering relation 
  10734.  
  10735.  
  10736. ΓòÉΓòÉΓòÉ 5.1.11.2.3. Map on Sorted Linked Sequence ΓòÉΓòÉΓòÉ
  10737.  
  10738. IMapOnSortedLinkedSequence  <Element, Key>
  10739. IGMapOnSortedLinkedSequence <Element, Key, EKCOps>
  10740.  
  10741. The implementation of the class IMapOnSortedLinkedSequence requires the 
  10742. following element and key-type functions: 
  10743.  
  10744. Element Type 
  10745.  
  10746.      Copy constructor 
  10747.      Destructor 
  10748.      Assignment 
  10749.      Equality test 
  10750.      Key access 
  10751.  
  10752.  Key Type 
  10753.  
  10754.  Ordering relation 
  10755.  
  10756.  
  10757. ΓòÉΓòÉΓòÉ 5.1.11.2.4. Map on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  10758.  
  10759. IMapOnSortedTabularSequence  <Element, Key>
  10760. IGMapOnSortedTabularSequence <Element, Key, EKCOps>
  10761.  
  10762. The implementation of the class IMapOnSortedTabularSequence requires the 
  10763. following element and key-type functions: 
  10764.  
  10765. Element Type 
  10766.  
  10767.      Default constructor 
  10768.      Copy constructor 
  10769.      Destructor 
  10770.      Assignment 
  10771.      Equality test 
  10772.      Key access 
  10773.  
  10774.  Key Type 
  10775.  
  10776.  Ordering relation 
  10777.  
  10778.  
  10779. ΓòÉΓòÉΓòÉ 5.1.11.2.5. Map on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  10780.  
  10781. IMapOnSortedDilutedSequence  <Element, Key>
  10782. IGMapOnSortedDilutedSequence <Element, Key, EKCOps>
  10783.  
  10784. The implementation of the class IMapOnSortedDilutedSequence requires the 
  10785. following element and key-type functions: 
  10786.  
  10787. Element Type 
  10788.  
  10789.      Default constructor 
  10790.      Copy constructor 
  10791.      Destructor 
  10792.      Assignment 
  10793.      Equality test 
  10794.      Key access 
  10795.  
  10796.  Key Type 
  10797.  
  10798.  Ordering relation 
  10799.  
  10800.  
  10801. ΓòÉΓòÉΓòÉ 5.1.11.2.6. Map on Hash Key Set ΓòÉΓòÉΓòÉ
  10802.  
  10803. IMapOnHashKeySet  <Element, Key>
  10804. IGMapOnHashKeySet <Element, Key, EKEHOps>
  10805.  
  10806. The implementation of the class IMapOnHashKeySet requires the following element 
  10807. and key-type functions: 
  10808.  
  10809. Element Type 
  10810.  
  10811.      Copy constructor 
  10812.      Destructor 
  10813.      Assignment 
  10814.      Equality test 
  10815.      Key access 
  10816.  
  10817.  Key Type 
  10818.  
  10819.      Equality test 
  10820.      Hash function 
  10821.  
  10822.  
  10823. ΓòÉΓòÉΓòÉ 5.1.11.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  10824.  
  10825. For polymorphism, you can use the corresponding abstract class, IAMap, which is 
  10826. found in the iamap.h header file, or the corresponding reference class, IRMap, 
  10827. which is found in the irmap.h header file. See Polymorphic Use of Collections 
  10828. for further information. 
  10829.  
  10830.  
  10831. ΓòÉΓòÉΓòÉ 5.1.11.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  10832.  
  10833. IAMap <Element, Key>
  10834. IRMap <Element, Key, ConcreteBase>
  10835.  
  10836. The concrete base class is one of the classes defined above. 
  10837.  
  10838. The required functions are the same as the required functions of the concrete 
  10839. base class. 
  10840.  
  10841.  
  10842. ΓòÉΓòÉΓòÉ 5.1.11.4. Coding Example for Map ΓòÉΓòÉΓòÉ
  10843.  
  10844. The following program translates a string from EBCDIC to ASCII and from ASCII 
  10845. to EBCDIC. It uses two maps, one with the EBCDIC code as key (E2AMap) and one 
  10846. with the ASCII code as key (A2EMap). It converts from EBCDIC to ASCII by 
  10847. finding the element whose key matches the EBCDIC code in E2AMap (which has the 
  10848. EBCDIC code as key) and taking the ASCII code information from that element. It 
  10849. converts from ASCII to EBCDIC by finding the key that matches the ASCII code in 
  10850. A2EMap (which has the ASCII code as key) and taking the EBCDIC code information 
  10851. for that element. 
  10852.  
  10853. The program uses the add() function to build the maps and the elementWithKey() 
  10854. function to convert the characters. 
  10855.  
  10856.    // transtab.C  -  An example of using a Map
  10857.    #include "transelm.h"
  10858.  
  10859.           // Get the standard operation classes:
  10860.    #include <istdops.h>
  10861.  
  10862.    #include "trmapops.h"
  10863.  
  10864.           //    char const translationTable[256] =  ....
  10865.    #include "xebc2asc.h"
  10866.    /*-------------------------------------------------------------*\
  10867.    |  Now we define the two Map templates and two maps.            |
  10868.    |  We want both of them to be based on the Hashtable KeySet.    |
  10869.    \*-------------------------------------------------------------*/
  10870.    #include <imaphks.h>
  10871.  
  10872.    typedef IGMapOnHashKeySet
  10873.              < TranslationElement, char, TranslationOpsE2A >  TransE2AMap;
  10874.  
  10875.    typedef IGMapOnHashKeySet
  10876.              < TranslationElement, char, TranslationOpsA2E >  TransA2EMap;
  10877.  
  10878.    void display(char*, char*);
  10879.  
  10880.    int main(int argc, char* argv[])  {
  10881.  
  10882.       TransA2EMap  A2EMap;
  10883.       TransE2AMap  E2AMap;
  10884.  
  10885.           /*-----------------------------------------------------*\
  10886.           |  Load the translation table into both maps.           |
  10887.           |  The maps organize themselves according to the key    |
  10888.           |  specification already given.                         |
  10889.           \*-----------------------------------------------------*/
  10890.       for (int i=0; i < 256; i++)
  10891.       {
  10892.                           /*      ascCode          ebcCode      */
  10893.          TranslationElement te(translationTable[i],   i   );
  10894.  
  10895.          E2AMap.add(te);
  10896.          A2EMap.add(te);
  10897.       }
  10898.           // What do we want to convert now?
  10899.       char* toConvert;
  10900.       if  (argc > 1)  toConvert = argv[1];
  10901.       else            toConvert = "$7  (=Dollar seven)";
  10902.  
  10903.       size_t textLength = strlen(toConvert) +1;
  10904.  
  10905.       char* convertedToAsc = new char[textLength];
  10906.       char* convertedToEbc = new char[textLength];
  10907.  
  10908.           // Convert the strings in place, character by character
  10909.       for (i=0; toConvert[i] != 0x00; i++)   {
  10910.          convertedToAsc[i]
  10911.            = E2AMap.elementWithKey(toConvert[i]).ascCode ();
  10912.          convertedToEbc[i]
  10913.            = A2EMap.elementWithKey(toConvert[i]).ebcCode ();
  10914.       }
  10915.  
  10916.       display("To convert", toConvert);
  10917.       display("After EBCDIC-ASCII conversion", convertedToAsc);
  10918.       display("After ASCII-EBCDIC conversion", convertedToEbc);
  10919.  
  10920.       delete[] convertedToAsc;
  10921.       delete[] convertedToEbc;
  10922.  
  10923.       return 0;
  10924.    }
  10925.  
  10926.    #include <iostream.h>
  10927.    #include <iomanip.h>
  10928.  
  10929.    void display (char* title, char* text)  {
  10930.      cout << endl << title << ':' << endl;
  10931.      cout << "  Text: '" << text << "'" << endl;
  10932.      cout << "  Hex:   " << hex;
  10933.      for (int i=0; text[i] != 0x00; i++)    {
  10934.         cout << (int)(unsigned) text[i] << " ";
  10935.      }
  10936.      cout << dec << endl;
  10937.    }
  10938.  
  10939. The program produces the following output: 
  10940.  
  10941. To convert:
  10942.   Hex:   24 37 20 20 28 3d 44 6f 6c 6c 61 72 20 73 65 76 65 6e 29
  10943.  
  10944. After EBCDIC-ASCII conversion:
  10945.   Hex:   86 4 81 81 89 15 eb 3f 25 25 2f 94 81 b0 dd fc dd 3e 91
  10946.  
  10947. After ASCII-EBCDIC conversion:
  10948.   Hex:   5b f7 40 40 4d 7e c4 96 93 93 81 99 40 a2 85 a5 85 95 5d
  10949.  
  10950.  
  10951. ΓòÉΓòÉΓòÉ 5.1.12. Priority Queue ΓòÉΓòÉΓòÉ
  10952.  
  10953. Description 
  10954.  
  10955. Derivation 
  10956.  
  10957. Variants/Header Files 
  10958.  
  10959. Members 
  10960.  
  10961. Template Arguments and Required Functions 
  10962.  
  10963. Abstract/Reference Classes 
  10964.  
  10965. To close all the panels in a chapter, double-click on this panel's system menu. 
  10966.  
  10967.  
  10968. ΓòÉΓòÉΓòÉ 5.1.12.1. Class Description - Priority Queue ΓòÉΓòÉΓòÉ
  10969.  
  10970. A priority queue is a key sorted bag with restricted access.  It is an ordered 
  10971. collection of zero or more elements.  Keys and multiple elements are supported. 
  10972. Element equality is not supported. 
  10973.  
  10974. When an element is added, it is placed in the queue according to its key value 
  10975. or priority. The highest priority is indicated by the lowest key value.  You 
  10976. can only remove the element with the highest priority.  Within the priority 
  10977. queue, elements are sorted according to ascending key values, as in other key 
  10978. collections. You can only remove the element with the lowest key value. 
  10979.  
  10980. For elements with equal priority, the priority queue has a first-in, first-out 
  10981. behavior. 
  10982.  
  10983. An example of a priority queue is a program used to assign priorities to 
  10984. service calls in a heating repair firm.  When a customer calls with a problem, 
  10985. a record with the customer's name and the seriousness of the situation is 
  10986. placed in a priority queue.  When a service person becomes available, customers 
  10987. are chosen by the program beginning with those whose situation is most severe. 
  10988. In this example, a serious problem such as a nonfunctioning furnace would be 
  10989. indicated by a low value for the priority, and a minor problem such as a noisy 
  10990. radiator would be indicated by a high value for the priority. 
  10991.  
  10992.  
  10993. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  10994.  
  10995. Key Sorted Collection 
  10996.  
  10997.   Key Sorted Bag
  10998.    Priority Queue
  10999.  
  11000. Note that priority queue is based on key sorted bag but is not actually derived 
  11001. from it or from the other classes shown above. The diagram does not show all 
  11002. bases of priority queue. See the figure "Abstract Class Hierarchy" in section 
  11003. Abstract Classes for an illustration. See Restricted Access for further 
  11004. details. 
  11005.  
  11006.  
  11007. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  11008.  
  11009. IPriorityQueue, the first class in the table below, is the default 
  11010. implementation variant. If you want to use polymorphism, you can replace the 
  11011. following class implementation variants by the reference class. 
  11012.  
  11013. To use Visual Builder features with your collections, change the name of the 
  11014. desired collection class template in the list below from I... to IV..., and use 
  11015. the ivprioqu.h header file instead of the header file that you would normally 
  11016. use without Visual Builder. 
  11017.  
  11018. Class Name            Header File Implementation Variant
  11019.  
  11020. IPriorityQueue        iprioqu.h   Linked sequence
  11021. IGPriorityQueue       iprioqu.h   Linked sequence
  11022.  
  11023. IPriorityQueueOn-     ipqusts.h   Tabular sequence
  11024.  SortedTabularSequence
  11025. IGPriorityQueueOn-    ipqusts.h   Tabular sequence
  11026.  SortedTabularSequence
  11027.  
  11028. IPriorityQueueOn-     ipqusds.h   Diluted sequence
  11029.  SortedDilutedSequence
  11030. IGPriorityQueueOn-    ipqusds.h   Diluted sequence
  11031.  SortedDilutedSequence
  11032.  
  11033.  
  11034. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  11035.  
  11036. All members of flat collections are described in Introduction to Flat 
  11037. Collections. The following members are provided for priority queue: 
  11038.  
  11039.      Constructor 
  11040.      Copy Constructor 
  11041.      Destructor 
  11042.      operator= 
  11043.      add 
  11044.      addAllFrom 
  11045.      allElementsDo 
  11046.      anyElement 
  11047.      compare 
  11048.      containsAllKeysFrom 
  11049.      containsElementWithKey 
  11050.      dequeue 
  11051.      elementAt 
  11052.      elementAtPosition 
  11053.      elementWithKey 
  11054.      enqueue 
  11055.      firstElement 
  11056.      isBounded 
  11057.      isEmpty 
  11058.      isFirst 
  11059.      isFull 
  11060.      isLast 
  11061.      key 
  11062.      lastElement 
  11063.      locateElementWithKey 
  11064.      locateNextElementWithKey 
  11065.      locateOrAddElementWithKey 
  11066.      maxNumberOfElements 
  11067.      newCursor 
  11068.      numberOfDifferentKeys 
  11069.      numberOfElements 
  11070.      numberOfElementsWithKey 
  11071.      position 
  11072.      removeAll 
  11073.      removeFirst 
  11074.      setToFirst 
  11075.      setToLast 
  11076.      setToNext 
  11077.      setToNextWithDifferentKey 
  11078.      setToPosition 
  11079.      setToPrevious 
  11080.  
  11081.  Priority queue also defines a cursor that inherits from IOrderedCursor. The 
  11082.  members for IOrderedCursor are described in Cursor. 
  11083.  
  11084.  
  11085. ΓòÉΓòÉΓòÉ 5.1.12.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  11086.  
  11087. The following implementation variants are defined for priority queues: 
  11088.  
  11089.      Priority queue 
  11090.      Priority queue on sorted tabular sequence 
  11091.      Priority queue on sorted diluted sequence 
  11092.  
  11093.  
  11094. ΓòÉΓòÉΓòÉ 5.1.12.2.1. Priority Queue ΓòÉΓòÉΓòÉ
  11095.  
  11096. IPriorityQueue  <Element, Key>
  11097. IGPriorityQueue <Element, Key, KCOps>
  11098.  
  11099. The implementation of the class IPriorityQueue requires the following element 
  11100. and key-type functions: 
  11101.  
  11102. Element Type 
  11103.  
  11104.      Copy constructor 
  11105.      Destructor 
  11106.      Assignment 
  11107.      Key access 
  11108.  
  11109.  Key Type 
  11110.  
  11111.  Ordering relation 
  11112.  
  11113.  
  11114. ΓòÉΓòÉΓòÉ 5.1.12.2.2. Priority Queue on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  11115.  
  11116. IPriorityQueueOnSortedTabularSequence  <Element, Key>
  11117. IGPriorityQueueOnSortedTabularSequence <Element, Key, KCOps>
  11118.  
  11119. The implementation of the class IPriorityQueueOnSortedTabularSequence requires 
  11120. the following element and key-type functions: 
  11121.  
  11122. Element Type 
  11123.  
  11124.      Default constructor 
  11125.      Copy constructor 
  11126.      Destructor 
  11127.      Assignment 
  11128.      Key access 
  11129.  
  11130.  Key Type 
  11131.  
  11132.  Ordering relation 
  11133.  
  11134.  
  11135. ΓòÉΓòÉΓòÉ 5.1.12.2.3. Priority Queue on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  11136.  
  11137. IPriorityQueueOnSortedDilutedSequence  <Element, Key>
  11138. IGPriorityQueueOnSortedDilutedSequence <Element, Key, KCOps>
  11139.  
  11140. The implementation of the class IPriorityQueueOnSortedDilutedSequence requires 
  11141. the following element and key-type functions: 
  11142.  
  11143. Element Type 
  11144.  
  11145.      Default constructor 
  11146.      Copy constructor 
  11147.      Destructor 
  11148.      Assignment 
  11149.      Key access 
  11150.  
  11151.  Key Type 
  11152.  
  11153.  Ordering relation 
  11154.  
  11155.  
  11156. ΓòÉΓòÉΓòÉ 5.1.12.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  11157.  
  11158. For polymorphism, you can use the corresponding abstract class, 
  11159. IAPriorityQueue, which is found in the iaprioqu.h header file, or the 
  11160. corresponding reference class, IRPriorityQueue, which is found in the 
  11161. irprioqu.h header file. See Polymorphic Use of Collections for further 
  11162. information. 
  11163.  
  11164.  
  11165. ΓòÉΓòÉΓòÉ 5.1.12.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  11166.  
  11167. IAPriorityQueue <Element, Key>
  11168. IRPriorityQueue <Element, Key, ConcreteBase>
  11169.  
  11170. The concrete base class is one of the classes defined above. 
  11171.  
  11172. The required functions are the same as the required functions of the concrete 
  11173. base class. 
  11174.  
  11175.  
  11176. ΓòÉΓòÉΓòÉ 5.1.13. Queue ΓòÉΓòÉΓòÉ
  11177.  
  11178. Description 
  11179.  
  11180. Derivation 
  11181.  
  11182. Variants/Header Files 
  11183.  
  11184. Members 
  11185.  
  11186. Template Arguments and Required Functions 
  11187.  
  11188. Abstract/Reference Classes 
  11189.  
  11190. To close all the panels in a chapter, double-click on this panel's system menu. 
  11191.  
  11192.  
  11193. ΓòÉΓòÉΓòÉ 5.1.13.1. Class Description - Queue ΓòÉΓòÉΓòÉ
  11194.  
  11195. A queue is a sequence with restricted access.  It is an ordered collection of 
  11196. elements with no key and no element equality.  The elements are arranged so 
  11197. that each collection has a first and a last element, each element except the 
  11198. last has a next element, and each element but the first has a previous element. 
  11199. The type and value of the elements are irrelevant, and have no effect on the 
  11200. behavior of the collection. 
  11201.  
  11202. You can only add an element as the last element, and you can only remove the 
  11203. first element.  Consequently, the elements of a queue are in chronological 
  11204. order. 
  11205.  
  11206. A queue is characterized by a first-in, first-out (FIFO) behavior. 
  11207.  
  11208. An example of using a queue is a program that processes requests for parts at 
  11209. the cash sales desk of a warehouse.  A request for a part is added to the queue 
  11210. when the customer's order is taken, and is removed from the queue when an order 
  11211. picker receives the order form for the part.  Using a queue collection in such 
  11212. an application ensures that all orders for parts are processed on a first-come, 
  11213. first-served basis. 
  11214.  
  11215.  
  11216. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  11217.  
  11218. Collection 
  11219.  
  11220.   Ordered Collection
  11221.    Sequential Collection
  11222.      Sequence
  11223.       Queue
  11224.  
  11225. Note that queue is based on sequence but is not actually derived from it or 
  11226. from the other classes shown above. See Restricted Access for further details. 
  11227.  
  11228.  
  11229. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  11230.  
  11231. IQueue, the first class in the table below, is the default implementation 
  11232. variant. If you want to use polymorphism, you can replace the following class 
  11233. implementation variants by the reference class. 
  11234.  
  11235. To use Visual Builder features with your collections, change the name of the 
  11236. desired collection class template in the list below from I... to IV..., and use 
  11237. the ivqueue.h header file instead of the header file that you would normally 
  11238. use without Visual Builder. 
  11239.  
  11240. Class Name               Header File   Implementation Variant
  11241.  
  11242. IQueue                   iqueue.h      Linked sequence
  11243. IGQueue                  iqueue.h      Linked sequence
  11244.  
  11245. IQueueOnTabularSequence  iquets.h      Tabular sequence
  11246. IGQueueOnTabularSequence iquets.h      Tabular sequence
  11247.  
  11248. IQueueOnDilutedSequence  iqueds.h      Diluted sequence
  11249. IGQueueOnDilutedSequence iqueds.h      Diluted sequence
  11250.  
  11251.  
  11252. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  11253.  
  11254. All members of flat collections are described in Introduction to Flat 
  11255. Collections. The following members are provided for queue: 
  11256.  
  11257.      Constructor 
  11258.      Copy Constructor 
  11259.      Destructor 
  11260.      operator= 
  11261.      add 
  11262.      addAllFrom 
  11263.      addAsLast 
  11264.      allElementsDo 
  11265.      anyElement 
  11266.      compare 
  11267.      dequeue 
  11268.      elementAt 
  11269.      elementAtPosition 
  11270.      enqueue 
  11271.      firstElement 
  11272.      isBounded 
  11273.      isEmpty 
  11274.      isFirst 
  11275.      isFull 
  11276.      isLast 
  11277.      lastElement 
  11278.      maxNumberOfElements 
  11279.      newCursor 
  11280.      numberOfElements 
  11281.      position 
  11282.      removeAll 
  11283.      removeFirst 
  11284.      setToFirst 
  11285.      setToLast 
  11286.      setToNext 
  11287.      setToPosition 
  11288.  
  11289.  Queue also defines a cursor that inherits from IOrderedCursor.  The members 
  11290.  for IOrderedCursor are described in Cursor. 
  11291.  
  11292.  
  11293. ΓòÉΓòÉΓòÉ 5.1.13.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  11294.  
  11295. The following implementation variants are defined for queues: 
  11296.  
  11297.      Queue 
  11298.      Queue on tabular sequence 
  11299.      Queue on diluted sequence 
  11300.  
  11301.  
  11302. ΓòÉΓòÉΓòÉ 5.1.13.2.1. Queue ΓòÉΓòÉΓòÉ
  11303.  
  11304. IQueue  <Element>
  11305. IGQueue <Element, StdOps>
  11306.  
  11307. The default implementation of the class IQueue requires the following element 
  11308. functions: 
  11309.  
  11310. Element Type 
  11311.  
  11312.      Copy constructor 
  11313.      Destructor 
  11314.      Assignment 
  11315.  
  11316.  
  11317. ΓòÉΓòÉΓòÉ 5.1.13.2.2. Queue on Tabular Sequence ΓòÉΓòÉΓòÉ
  11318.  
  11319. IQueueOnTabularSequence  <Element>
  11320. IGQueueOnTabularSequence <Element, StdOps>
  11321.  
  11322. The implementation of the class IDequeOnTabularSequence requires the following 
  11323. element functions: 
  11324.  
  11325. Element Type 
  11326.  
  11327.      Copy constructor 
  11328.      Destructor 
  11329.      Assignment 
  11330.  
  11331.  
  11332. ΓòÉΓòÉΓòÉ 5.1.13.2.3. Queue on Diluted Sequence ΓòÉΓòÉΓòÉ
  11333.  
  11334. IQueueOnDilutedSequence  <Element>
  11335. IGQueueOnDilutedSequence <Element, StdOps>
  11336.  
  11337. The implementation of the class IQueueOnDilutedSequence requires the following 
  11338. element functions: 
  11339.  
  11340. Element Type 
  11341.  
  11342.      Copy constructor 
  11343.      Destructor 
  11344.      Assignment 
  11345.  
  11346.  
  11347. ΓòÉΓòÉΓòÉ 5.1.13.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  11348.  
  11349. For polymorphism, you can use the corresponding abstract class, IAQueue, which 
  11350. is found in the iaqueue.h header file, or the corresponding reference class, 
  11351. IRQueue, which is found in the irqueue.h header file. See Polymorphic Use of 
  11352. Collections for further information. 
  11353.  
  11354.  
  11355. ΓòÉΓòÉΓòÉ 5.1.13.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  11356.  
  11357. IAQueue <Element>
  11358. IRQueue <Element, ConcreteBase>
  11359.  
  11360. The concrete base class is one of the classes defined above. 
  11361.  
  11362. The required functions are the same as the required functions of the concrete 
  11363. base class. 
  11364.  
  11365.  
  11366. ΓòÉΓòÉΓòÉ 5.1.14. Relation ΓòÉΓòÉΓòÉ
  11367.  
  11368. Description 
  11369.  
  11370. Derivation 
  11371.  
  11372. Variants/Header Files 
  11373.  
  11374. Members 
  11375.  
  11376. Template Arguments and Required Functions 
  11377.  
  11378. Abstract/Reference Classes 
  11379.  
  11380. To close all the panels in a chapter, double-click on this panel's system menu. 
  11381.  
  11382.  
  11383. ΓòÉΓòÉΓòÉ 5.1.14.1. Class Description - Relation ΓòÉΓòÉΓòÉ
  11384.  
  11385. A relation is an unordered collection of zero or more elements that have a key. 
  11386. Element equality is supported, and the values of the elements are relevant. 
  11387.  
  11388. The keys of the elements are not unique.  You can add an element whether or not 
  11389. there is already an element in the collection with the same key. 
  11390.  
  11391. Figure Behavior of add for Unique and Miltiple Collections illustrates the 
  11392. differences in behavior between map, relation, key set, and key bag when 
  11393. identical elements and elements with the same key are added. 
  11394.  
  11395. An example of using a relation is a program that maintains a list of all your 
  11396. relatives, with an individual's relationship to you as the key. You can add an 
  11397. aunt, uncle, grandmother, daughter, father-in-law, and so on.  You can add an 
  11398. aunt even if an aunt is already in the collection, because you can have several 
  11399. relatives who have the same relationship to you.  (For unique relationships 
  11400. such as mother or father, your program would have to check the collection to 
  11401. make sure it did not already contain a family member with that key, before 
  11402. adding the family member.) You can locate a member of the family, but the 
  11403. family members are not in any particular order. 
  11404.  
  11405. Figure Combination of Flat Collection Properties gives an overview of the 
  11406. properties of a relation and its relationship to other flat collections. 
  11407.  
  11408.  
  11409. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  11410.  
  11411.            Collection 
  11412. Key Collection       Equality Collection 
  11413.  
  11414.        Equality Key Collection
  11415.             Relation
  11416.  
  11417.  
  11418. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  11419.  
  11420. IRelation is the default implementation variant.  IGRelation is the default 
  11421. implementation with generic operations class.  Both variants are declared in 
  11422. the header file irel.h. 
  11423.  
  11424. To use Visual Builder features with your collections, use IVRelation instead of 
  11425. IRelation, and IVGRelation instead of IGRelation.  Both variants are declared 
  11426. in the header file ivrel.h. 
  11427.  
  11428.  
  11429. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  11430.  
  11431. All members of flat collections are described in Introduction to Flat 
  11432. Collections. The following members are provided for relation: 
  11433.  
  11434.      Constructor 
  11435.      Copy Constructor 
  11436.      Destructor 
  11437.      operator!= 
  11438.      operator= 
  11439.      operator== 
  11440.      add 
  11441.      addAllFrom 
  11442.      addDifference 
  11443.      addIntersection 
  11444.      addOrReplaceElementWithKey 
  11445.      addUnion 
  11446.      allElementsDo 
  11447.      anyElement 
  11448.      contains 
  11449.      containsAllFrom 
  11450.      containsAllKeysFrom 
  11451.      containsElementWithKey 
  11452.      differenceWith 
  11453.      elementAt 
  11454.      elementWithKey 
  11455.      intersectionWith 
  11456.      isBounded 
  11457.      isEmpty 
  11458.      isFull 
  11459.      key 
  11460.      locate 
  11461.      locateElementWithKey 
  11462.      locateNextElementWithKey 
  11463.      locateOrAdd 
  11464.      locateOrAddElementWithKey 
  11465.      maxNumberOfElements 
  11466.      newCursor 
  11467.      numberOfDifferentKeys 
  11468.      numberOfElements 
  11469.      numberOfElementsWithKey 
  11470.      remove 
  11471.      removeAll 
  11472.      removeAllElementsWithKey 
  11473.      removeAt 
  11474.      removeElementWithKey 
  11475.      replaceAt 
  11476.      replaceElementWithKey 
  11477.      setToFirst 
  11478.      setToNext 
  11479.      setToNextWithDifferentKey 
  11480.      unionWith 
  11481.  
  11482.  Relation also defines a cursor that inherits from IElementCursor.  The members 
  11483.  for IElementCursor are described in Cursor. 
  11484.  
  11485.  
  11486. ΓòÉΓòÉΓòÉ 5.1.14.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  11487.  
  11488. IRelation  <Element, Key>
  11489. IGRelation <Element, Key, EKEHOps>
  11490.  
  11491. The default implementation of the class IRelation requires the following 
  11492. element functions: 
  11493.  
  11494. Element Type 
  11495.  
  11496.      Copy constructor 
  11497.      Destructor 
  11498.      Assignment 
  11499.      Key access 
  11500.      Equality test 
  11501.  
  11502.  Key Type 
  11503.  
  11504.      Equality test 
  11505.      Hash function 
  11506.  
  11507.  
  11508. ΓòÉΓòÉΓòÉ 5.1.14.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  11509.  
  11510. For polymorphism, you can use the corresponding abstract class, IARelation, 
  11511. which is found in the iarel.h header file, or the corresponding reference 
  11512. class, IRRelation, which is found in the irrel.h header file. See Polymorphic 
  11513. Use of Collections for further information. 
  11514.  
  11515.  
  11516. ΓòÉΓòÉΓòÉ 5.1.14.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  11517.  
  11518. IARelation <Element, Key>
  11519. IRRelation <Element, Key, ConcreteBase>
  11520.  
  11521. The concrete base class is one of the classes defined above. 
  11522.  
  11523. The required functions are the same as the required functions of the concrete 
  11524. base class. 
  11525.  
  11526.  
  11527. ΓòÉΓòÉΓòÉ 5.1.15. Sequence ΓòÉΓòÉΓòÉ
  11528.  
  11529. Description 
  11530.  
  11531. Derivation 
  11532.  
  11533. Variants/Header Files 
  11534.  
  11535. Members 
  11536.  
  11537. Template Arguments and Required Functions 
  11538.  
  11539. Abstract/Reference Classes 
  11540.  
  11541. Examples 
  11542.  
  11543. To close all the panels in a chapter, double-click on this panel's system menu. 
  11544.  
  11545.  
  11546. ΓòÉΓòÉΓòÉ 5.1.15.1. Class Description - Sequence ΓòÉΓòÉΓòÉ
  11547.  
  11548. A sequence is an ordered collection of elements.  The elements are arranged so 
  11549. that each collection has a first and a last element, each element except the 
  11550. last has a next element, and each element but the first has a previous element. 
  11551.  
  11552. The type and value of the elements are irrelevant, and have no effect on the 
  11553. behavior of the collection.  Elements can be added and deleted from any 
  11554. position in the collection.  Elements can be retrieved or replaced.  A sequence 
  11555. does not support element equality or a key. If you require element equality for 
  11556. a sequence, you can use an equality sequence. 
  11557.  
  11558. An example of a sequence is a program that maintains a list of the words in a 
  11559. paragraph.  The order of the words is obviously important, and you can add or 
  11560. remove words at a given position, but you cannot search for individual words 
  11561. except by iterating through the collection and comparing each word to the word 
  11562. you are searching for.  You can add a word that is already present in the 
  11563. sequence, because a given word may be used more than once in a paragraph. 
  11564.  
  11565. Figure Combination of Flat Collection Properties illustrates the properties of 
  11566. a sequence and its relationship to other flat collections. 
  11567.  
  11568.  
  11569. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  11570.  
  11571. Collection 
  11572.  
  11573.   Ordered Collection
  11574.    Sequential Collection
  11575.      Sequence
  11576.  
  11577.  
  11578. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  11579.  
  11580. ISequence, the first class in the table below, is the default implementation 
  11581. variant. If you want to use polymorphism, you can replace the following class 
  11582. implementation variants by the reference class. 
  11583.  
  11584. To use Visual Builder features with your collections, change the name of the 
  11585. desired collection class template in the list below from I... to IV..., and use 
  11586. the ivseq.h header file instead of the header file that you would normally use 
  11587. without Visual Builder. 
  11588.  
  11589. Class Name         Header File Implementation Variant
  11590.  
  11591. ISequence          iseq.h      Linked sequence
  11592. IGSequence         iseq.h      Linked sequence
  11593. ILinkedSequence    ilnseq.h    Linked sequence
  11594. IGLinkedSequence   ilnseq.h    Linked sequence
  11595.  
  11596. ITabularSequence   itbseq.h    Tabular sequence
  11597. IGTabularSequence  itbseq.h    Tabular sequence
  11598.  
  11599. IDilutedSequence   itdseq.h    Diluted sequence
  11600. IGDilutedSequence  itdseq.h    Diluted sequence
  11601.  
  11602.  
  11603. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  11604.  
  11605. All members of flat collections are described in Introduction to Flat 
  11606. Collections. The following members are provided for sequence: 
  11607.  
  11608.      Constructor 
  11609.      Copy Constructor 
  11610.      Destructor 
  11611.      operator= 
  11612.      add 
  11613.      addAllFrom 
  11614.      addAsFirst 
  11615.      addAsLast 
  11616.      addAsNext 
  11617.      addAsPrevious 
  11618.      addAtPosition 
  11619.      allElementsDo 
  11620.      anyElement 
  11621.      compare 
  11622.      elementAt 
  11623.      elementAtPosition 
  11624.      firstElement 
  11625.      isBounded 
  11626.      isEmpty 
  11627.      isFirst 
  11628.      isFull 
  11629.      isLast 
  11630.      lastElement 
  11631.      maxNumberOfElements 
  11632.      newCursor 
  11633.      numberOfElements 
  11634.      position 
  11635.      removeAll 
  11636.      removeAt 
  11637.      removeAtPosition 
  11638.      removeFirst 
  11639.      removeLast 
  11640.      replaceAt 
  11641.      setToFirst 
  11642.      setToLast 
  11643.      setToNext 
  11644.      setToPosition 
  11645.      setToPrevious 
  11646.      sort 
  11647.  
  11648.  Sequence also defines a cursor that inherits from IOrderedCursor.  The members 
  11649.  for IOrderedCursor are described in Cursor. 
  11650.  
  11651.  
  11652. ΓòÉΓòÉΓòÉ 5.1.15.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  11653.  
  11654. The following implementation variants are defined for sequences: 
  11655.  
  11656.      Sequence 
  11657.      linked sequence 
  11658.      tabular sequence 
  11659.      diluted sequence 
  11660.  
  11661.  
  11662. ΓòÉΓòÉΓòÉ 5.1.15.2.1. Sequence ΓòÉΓòÉΓòÉ
  11663.  
  11664. ISequence  <Element>
  11665. IGSequence <Element, StdOps>
  11666.  
  11667. The default implementation of ISequence requires the following element 
  11668. functions: 
  11669.  
  11670. Element Type 
  11671.  
  11672.      Copy constructor 
  11673.      Destructor 
  11674.      Assignment 
  11675.  
  11676.  
  11677. ΓòÉΓòÉΓòÉ 5.1.15.2.2. Linked Sequence ΓòÉΓòÉΓòÉ
  11678.  
  11679. ILinkedSequence  <Element>
  11680. IGLinkedSequence <Element, StdOps>
  11681.  
  11682. The implementation of the class ILinkedSequence requires the following element 
  11683. functions: 
  11684.  
  11685. Element Type 
  11686.  
  11687.      Copy constructor 
  11688.      Destructor 
  11689.      Assignment 
  11690.  
  11691.  
  11692. ΓòÉΓòÉΓòÉ 5.1.15.2.3. Tabular Sequence ΓòÉΓòÉΓòÉ
  11693.  
  11694. ITabularSequence  <Element>
  11695. IGTabularSequence <Element, StdOps>
  11696.  
  11697. The implementation of the class ITabularSequence requires the following element 
  11698. functions: 
  11699.  
  11700. Element Type 
  11701.  
  11702.      Default constructor 
  11703.      Copy constructor 
  11704.      Destructor 
  11705.      Assignment 
  11706.  
  11707.  
  11708. ΓòÉΓòÉΓòÉ 5.1.15.2.4. Diluted Sequence ΓòÉΓòÉΓòÉ
  11709.  
  11710. IDilutedSequence  <Element>
  11711. IGDilutedSequence <Element, StdOps>
  11712.  
  11713. The implementation of the class IDilutedSequence requires the following element 
  11714. functions: 
  11715.  
  11716. Element Type 
  11717.  
  11718.      Copy constructor 
  11719.      Destructor 
  11720.      Assignment 
  11721.  
  11722.  
  11723. ΓòÉΓòÉΓòÉ 5.1.15.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  11724.  
  11725. For polymorphism, you can use the corresponding abstract class, IASequence, 
  11726. which is found in the iaseq.h header file, or the corresponding reference 
  11727. class, IRSequence, which is found in the irseq.h header file. See Polymorphic 
  11728. Use of Collections for further information. 
  11729.  
  11730.  
  11731. ΓòÉΓòÉΓòÉ 5.1.15.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  11732.  
  11733. IASequence <Element>
  11734. IRSequence <Element, ConcreteBase>
  11735.  
  11736. The concrete base class is one of the sequence classes. 
  11737.  
  11738. The required functions are the same as the required functions of the concrete 
  11739. base class. 
  11740.  
  11741.  
  11742. ΓòÉΓòÉΓòÉ 5.1.15.4. Coding Example for Sequence ΓòÉΓòÉΓòÉ
  11743.  
  11744. The following program creates a sequence using the default sequence class, 
  11745. ISequence, and adds a number of words to it.  The program sorts the words in 
  11746. ascending order and searches the sequence for the word "fox".  Finally, it 
  11747. prints the word that is in position 9. 
  11748.  
  11749. The program uses two types of iteration.  It uses the iterator class, 
  11750. IIterator, when printing the sequence, and it uses cursor iteration when 
  11751. searching for a word.  With the iterator object, the program uses the 
  11752. allElementsDo() function. With cursor iteration, it uses the setToFirst(), 
  11753. isValid(), and setToNext() functions. It uses the elementAt() and 
  11754. elementAtPosition() functions to find words in the sequence. 
  11755.  
  11756.    // wordseq.C  -  An example of using a Sequence
  11757.    #include <iostream.h>
  11758.  
  11759.                  // Get definition and declaration of class Word:
  11760.    #include "toyword.h"
  11761.  
  11762.                  // Define a compare function to be used for sort:
  11763.    inline long wordCompare ( Word const& w1, Word const& w2) {
  11764.       return (w1.getWord() > w2.getWord());
  11765.    }
  11766.  
  11767.    // We want to use the default Sequence called ISequence.
  11768.    #include <iseq.h>
  11769.  
  11770.    typedef ISequence <Word> WordSeq;
  11771.    typedef IIterator <Word> WordIter;
  11772.  
  11773.  
  11774.    // Test variables to put into the Sequence.
  11775.  
  11776.    IString wordArray[9] = {
  11777.       "the",    "quick",   "brown",   "fox",   "jumps",
  11778.       "over",   "a",       "lazy",    "dog"
  11779.    };
  11780.  
  11781.  
  11782.  
  11783.    // Our Iterator class for use with allElementsDo().
  11784.  
  11785.    // The alternative method of iteration, using a cursor, does
  11786.    // not need such an iterator class.
  11787.    class PrintClass : public WordIter
  11788.    {
  11789.    public:
  11790.       IBoolean applyTo(Word &w)
  11791.          {
  11792.          cout << endl << w.getWord();    // Print the string
  11793.          return(True);
  11794.          }
  11795.    };
  11796.  
  11797.  
  11798.  
  11799.  
  11800.    // Main program
  11801.    int main()  {
  11802.       WordSeq WL;
  11803.       WordSeq::Cursor cursor(WL);
  11804.       PrintClass Print;
  11805.  
  11806.       int i;
  11807.  
  11808.       for (i = 0; i < 9; i ++) {     // Put all strings into Sequence
  11809.          Word aWord(wordArray[i]);   // Fill object with right value
  11810.          WL.addAsLast(aWord);        // Add it to the Sequence at end
  11811.       }
  11812.  
  11813.       cout << endl << "Sequence in initial order:" << endl;
  11814.       WL.allElementsDo(Print);
  11815.  
  11816.       WL.sort(wordCompare);       // Sort the Sequence ascending
  11817.       cout << endl << endl << "Sequence in sorted order:" << endl;
  11818.       WL.allElementsDo(Print);
  11819.  
  11820.       // Use iteration via cursor now:
  11821.  
  11822.       cout << endl << endl << "Look for \"fox\" in the Sequence:" << endl;
  11823.       for (cursor.setToFirst();
  11824.            cursor.isValid() && (WL.elementAt(cursor).getWord() != "fox");
  11825.            cursor.setToNext());
  11826.  
  11827.       if (WL.elementAt(cursor).getWord() != "fox") {
  11828.           cout << endl << "The element was not found." << endl;
  11829.       }
  11830.       else {
  11831.           cout << endl << " The element was found." << endl;
  11832.       }
  11833.  
  11834.       cout << endl << "The element at position 9: "
  11835.            << WL.elementAtPosition(9).getWord()
  11836.            << endl;
  11837.  
  11838.       return(0);
  11839.    }
  11840.  
  11841. The program produces the following output: 
  11842.  
  11843.  
  11844. Sequence in initial order:
  11845.  
  11846. the
  11847. quick
  11848. brown
  11849. fox
  11850. jumps
  11851. over
  11852. a
  11853. lazy
  11854. dog
  11855.  
  11856. Sequence in sorted order:
  11857.  
  11858. a
  11859. brown
  11860. dog
  11861. fox
  11862. jumps
  11863. lazy
  11864. over
  11865. quick
  11866. the
  11867.  
  11868. Look for "fox" in the Sequence:
  11869.  
  11870.  The element was found.
  11871.  
  11872.  
  11873. The element at position 9: the
  11874.  
  11875.  
  11876. ΓòÉΓòÉΓòÉ 5.1.16. Set ΓòÉΓòÉΓòÉ
  11877.  
  11878. Description 
  11879.  
  11880. Derivation 
  11881.  
  11882. Variants/Header Files 
  11883.  
  11884. Members 
  11885.  
  11886. Template Arguments and Required Functions 
  11887.  
  11888. Abstract/Reference Classes 
  11889.  
  11890. Examples 
  11891.  
  11892. To close all the panels in a chapter, double-click on this panel's system menu. 
  11893.  
  11894.  
  11895. ΓòÉΓòÉΓòÉ 5.1.16.1. Class Description - Set ΓòÉΓòÉΓòÉ
  11896.  
  11897. A set is an unordered collection of zero or more elements with no key.  Element 
  11898. equality is supported, and the values of the elements are relevant. 
  11899.  
  11900. Only unique elements are supported.  A request to add an element that already 
  11901. exists is ignored. 
  11902.  
  11903. An example of a set is a program that creates a packing list for a box of free 
  11904. samples to be sent to a warehouse customer.  The program searches a database of 
  11905. in-stock merchandise, and selects ten items at random whose price is below a 
  11906. threshold level.  Each item is then added to the set.  The set does not allow 
  11907. an item to be added if it is already present in the collection, ensuring that a 
  11908. customer does not get two samples of a single product.  The set is not sorted, 
  11909. and elements of the set cannot be located by key. 
  11910.  
  11911. Figure Combination of Flat Collection Properties gives an overview of the 
  11912. properties of a set and its relationship to other flat collections. 
  11913.  
  11914. The set also offers typical set functions such as union, intersection, and 
  11915. difference. 
  11916.  
  11917.  
  11918. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  11919.  
  11920. Collection 
  11921.  
  11922.   Equality Collection
  11923.    Set
  11924.  
  11925.  
  11926. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  11927.  
  11928. ISet, the first class in the table below, is the default implementation 
  11929. variant. If you want to use polymorphism, you can replace the following class 
  11930. implementation variants by the reference class. 
  11931.  
  11932. To use Visual Builder features with your collections, change the name of the 
  11933. desired collection class template in the list below from I... to IV..., and use 
  11934. the ivset.h header file instead of the header file that you would normally use 
  11935. without Visual Builder. 
  11936.  
  11937. Class Name                   Header File  Implementation Variant
  11938.  
  11939. ISet                         iset.h       AVL tree
  11940. IGSet                        iset.h       AVL tree
  11941.  
  11942. ISetOnBSTKeySortedSet        isetbst.h    B* tree
  11943. IGSetOnBSTKeySortedSet       isetbst.h    B* tree
  11944.  
  11945. ISetOnSortedLinkedSequence   isetsls.h    Linked sequence
  11946. IGSetOnSortedLinkedSequence  isetsls.h    Linked sequence
  11947.  
  11948. ISetOnSortedTabularSequence  isetsts.h    Tabular sequence
  11949. IGSetOnSortedTabularSequence isetsts.h    Tabular sequence
  11950.  
  11951. ISetOnSortedDilutedSequence  isetsds.h    Diluted sequence
  11952. IGSetOnSortedDilutedSequence isetsds.h    Diluted sequence
  11953.  
  11954. ISetOnHashKeySet             isethks.h    Hash table
  11955. IGSetOnHashKeySet            isethks.h    Hash table
  11956.  
  11957.  
  11958. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  11959.  
  11960. All members of flat collections are described in Introduction to Flat 
  11961. Collections. The following members are provided for set: 
  11962.  
  11963.      Constructor 
  11964.      Copy Constructor 
  11965.      Destructor 
  11966.      operator!= 
  11967.      operator= 
  11968.      operator== 
  11969.      add 
  11970.      addAllFrom 
  11971.      addDifference 
  11972.      addIntersection 
  11973.      addUnion 
  11974.      allElementsDo 
  11975.      anyElement 
  11976.      contains 
  11977.      containsAllFrom 
  11978.      differenceWith 
  11979.      elementAt 
  11980.      intersectionWith 
  11981.      isBounded 
  11982.      isEmpty 
  11983.      isFull 
  11984.      locate 
  11985.      locateOrAdd 
  11986.      maxNumberOfElements 
  11987.      newCursor 
  11988.      numberOfElements 
  11989.      remove 
  11990.      removeAll 
  11991.      removeAt 
  11992.      replaceAt 
  11993.      setToFirst 
  11994.      setToNext 
  11995.      unionWith 
  11996.  
  11997.  Set also defines a cursor that inherits from IElementCursor. The members for 
  11998.  IElementCursor are described in Cursor. 
  11999.  
  12000.  
  12001. ΓòÉΓòÉΓòÉ 5.1.16.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  12002.  
  12003. The following implementation variants are defined for sets: 
  12004.  
  12005.      Set 
  12006.      Set on B* key sorted set 
  12007.      Set on sorted linked sequence 
  12008.      Set on sorted tabular sequence 
  12009.      Set on sorted diluted sequence 
  12010.      Set on hash key set 
  12011.  
  12012.  
  12013. ΓòÉΓòÉΓòÉ 5.1.16.2.1. Set ΓòÉΓòÉΓòÉ
  12014.  
  12015. ISet  <Element>
  12016. IGSet <Element, ECOps>
  12017.  
  12018. The default implementation of the class ISet requires the following element 
  12019. functions: 
  12020.  
  12021. Element Type 
  12022.  
  12023.      Copy constructor 
  12024.      Destructor 
  12025.      Assignment 
  12026.      Equality test 
  12027.      Ordering relation 
  12028.  
  12029.  
  12030. ΓòÉΓòÉΓòÉ 5.1.16.2.2. Set on B* Key Sorted Set ΓòÉΓòÉΓòÉ
  12031.  
  12032. ISetOnBSTKeySortedSet  <Element>
  12033. IGSetOnBSTKeySortedSet <Element, ECOps>
  12034.  
  12035. The implementation of the class ISetOnBSTKeySortedSet requires the following 
  12036. element functions: 
  12037.  
  12038. Element Type 
  12039.  
  12040.      Default constructor 
  12041.      Copy constructor 
  12042.      Destructor 
  12043.      Assignment 
  12044.      Equality test 
  12045.      Ordering relation 
  12046.  
  12047.  
  12048. ΓòÉΓòÉΓòÉ 5.1.16.2.3. Set on Sorted Linked Sequence ΓòÉΓòÉΓòÉ
  12049.  
  12050. ISetOnSortedLinkedSequence  <Element>
  12051. IGSetOnSortedLinkedSequence <Element, ECOps>
  12052.  
  12053. The implementation of the class ISetOnSortedLinkedSequence requires the 
  12054. following element functions: 
  12055.  
  12056. Element Type 
  12057.  
  12058.      Copy constructor 
  12059.      Destructor 
  12060.      Assignment 
  12061.      Equality test 
  12062.      Ordering relation 
  12063.  
  12064.  
  12065. ΓòÉΓòÉΓòÉ 5.1.16.2.4. Set on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  12066.  
  12067. ISetOnSortedTabularSequence  <Element>
  12068. IGSetOnSortedTabularSequence <Element, ECOps>
  12069.  
  12070. The implementation of the class ISetOnSortedTabularSequence requires the 
  12071. following element functions: 
  12072.  
  12073. Element Type 
  12074.  
  12075.      Default constructor 
  12076.      Copy constructor 
  12077.      Destructor 
  12078.      Assignment 
  12079.      Equality test 
  12080.      Ordering relation 
  12081.  
  12082.  
  12083. ΓòÉΓòÉΓòÉ 5.1.16.2.5. Set on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  12084.  
  12085. ISetOnSortedDilutedSequence  <Element>
  12086. IGSetOnSortedDilutedSequence <Element, ECOps>
  12087.  
  12088. The implementation of the class ISetOnSortedDilutedSequence requires the 
  12089. following element functions: 
  12090.  
  12091. Element Type 
  12092.  
  12093.      Default constructor 
  12094.      Copy constructor 
  12095.      Destructor 
  12096.      Assignment 
  12097.      Equality test 
  12098.      Ordering relation 
  12099.  
  12100.  
  12101. ΓòÉΓòÉΓòÉ 5.1.16.2.6. Set on Hash Key Set ΓòÉΓòÉΓòÉ
  12102.  
  12103. ISetOnHashKeySet  <Element>
  12104. IGSetOnHashKeySet <Element, EHOps>
  12105.  
  12106. The implementation of the class ISetOnHashKeySet requires the following element 
  12107. functions: 
  12108.  
  12109. Element Type 
  12110.  
  12111.      Copy constructor 
  12112.      Destructor 
  12113.      Assignment 
  12114.      Equality test 
  12115.      Hash function 
  12116.  
  12117.  
  12118. ΓòÉΓòÉΓòÉ 5.1.16.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  12119.  
  12120. For polymorphism, you can use the corresponding abstract class, IASet, which is 
  12121. found in the iaset.h header file, or the corresponding reference class, IRSet, 
  12122. which is found in the irset.h header file. See Polymorphic Use of Collections 
  12123. for further information. 
  12124.  
  12125.  
  12126. ΓòÉΓòÉΓòÉ 5.1.16.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  12127.  
  12128. IASet <Element>
  12129. IRSet <Element, ConcreteBase>
  12130.  
  12131. The concrete base class is one of the classes defined above. 
  12132.  
  12133. The required functions are the same as the required functions of the concrete 
  12134. base class. 
  12135.  
  12136.  
  12137. ΓòÉΓòÉΓòÉ 5.1.16.4. Coding Example for Set ΓòÉΓòÉΓòÉ
  12138.  
  12139. The follow program creates sets using the default class, ISet. The odd set 
  12140. contains all odd numbers less than ten. The prime set contains all prime 
  12141. numbers less than ten.  The program creates a set, oddPrime, that contains all 
  12142. the prime numbers less than ten that are odd, by using the intersection of odd 
  12143. and prime. It creates another set, evenPrime, that contains all the prime 
  12144. numbers less than ten that are even, by using the difference of prime and 
  12145. oddPrime. 
  12146.  
  12147. When printing the sets, the program uses the iterator class, IIterator. It uses 
  12148. the add() function to build the odd and prime sets.  It uses the 
  12149. addIntersection() and addDifference() functions to create the oddPrime and 
  12150. evenPrime sets, respectively. 
  12151.  
  12152.    // evenodd.C  -  An example of using a Set
  12153.    #include <iostream.h>
  12154.  
  12155.    #include <iset.h>        // Take the
  12156. defaults for the Set and for
  12157.                             // the required functions for integer
  12158.    typedef ISet <int> IntSet;
  12159.  
  12160.    // For iteration we want to use an object of an iterator class
  12161.    class PrintClass : public IIterator<int>  {
  12162.      public:
  12163.        virtual IBoolean applyTo(int& i)
  12164.          { cout << " " << i << " "; return True;}
  12165.    };
  12166.  
  12167.    // Local prototype for the function to display an IntSet.
  12168.    void    List(char *, IntSet &);
  12169.  
  12170.    // Main program
  12171.    int main ()  {
  12172.       IntSet odd, prime;
  12173.       IntSet oddPrime, evenPrime;
  12174.  
  12175.       int One = 1, Two = 2, Three = 3, Five = 5, Seven = 7, Nine = 9;
  12176.  
  12177.    // Fill odd set with odd integers < 10
  12178.       odd.add( One );
  12179.       odd.add( Three );
  12180.       odd.add( Five );
  12181.       odd.add( Seven );
  12182.       odd.add( Nine );
  12183.       List("Odds less than 10:  ", odd);
  12184.  
  12185.    // Fill prime set with primes < 10
  12186.       prime.add( Two );
  12187.       prime.add( Three );
  12188.       prime.add( Five );
  12189.       prime.add( Seven );
  12190.       List("Primes less than 10:  ", prime);
  12191.  
  12192.    // Intersect 'Odd' and 'Prime' to give 'OddPrime'
  12193.       oddPrime.addIntersection( odd, prime);
  12194.       List("Odd primes less than 10:  ", oddPrime);
  12195.  
  12196.    // Subtract all 'Odd' from 'Prime' to give 'EvenPrime'
  12197.       evenPrime.addDifference( prime, oddPrime);
  12198.       List("Even primes less than 10:  ", evenPrime);
  12199.  
  12200.       return(0);
  12201.    }
  12202.  
  12203.    // Local function to display an IntSet.
  12204.  
  12205.    void List(char *Message, IntSet &anIntSet)  {
  12206.       PrintClass Print;
  12207.  
  12208.       cout << Message;
  12209.       anIntSet.allElementsDo(Print);
  12210.       cout << endl;
  12211.    }
  12212.  
  12213. The program produces the following output: 
  12214.  
  12215. Odds less than 10:   1  3  5  7  9
  12216. Primes less than 10:   2  3  5  7
  12217. Odd primes less than 10:   3  5  7
  12218. Even primes less than 10:   2
  12219.  
  12220.  
  12221. ΓòÉΓòÉΓòÉ 5.1.17. Sorted Bag ΓòÉΓòÉΓòÉ
  12222.  
  12223. Description 
  12224.  
  12225. Derivation 
  12226.  
  12227. Variants/Header Files 
  12228.  
  12229. Members 
  12230.  
  12231. Template Arguments and Required Functions 
  12232.  
  12233. Abstract/Reference Classes 
  12234.  
  12235. To close all the panels in a chapter, double-click on this panel's system menu. 
  12236.  
  12237.  
  12238. ΓòÉΓòÉΓòÉ 5.1.17.1. Class Description - Sorted Bag ΓòÉΓòÉΓòÉ
  12239.  
  12240. A sorted bag is an ordered collection of zero or more elements with no key. 
  12241. Both element equality and multiple elements are supported. 
  12242.  
  12243. An example of using a sorted bag is a program for entering observations on the 
  12244. types of stones found in a riverbed.  Each time you find a stone on the 
  12245. riverbed, you enter the stone's mineral type into the collection.  You can 
  12246. enter the same mineral type for several stones, because a sorted bag supports 
  12247. multiple elements.  You can search for stones of a particular mineral type, and 
  12248. you can determine the number of observations of stones of that type.  You can 
  12249. also display the contents of the collection, sorted by mineral type, if you 
  12250. want a complete list of observations made to date. 
  12251.  
  12252. Figure Combination of Flat Collection Properties gives an overview of the 
  12253. properties of a sorted bag and its relationship to other flat collections. 
  12254.  
  12255.  
  12256. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  12257.  
  12258.        Collection 
  12259.  
  12260.               Ordered Collection
  12261.  
  12262. Equality Collection    Sorted Collection 
  12263.  
  12264.      Equality Sorted Collection
  12265.          Sorted Bag
  12266.  
  12267.  
  12268. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  12269.  
  12270. ISortedBag, the first class in the table below, is the default implementation 
  12271. variant. If you want to use polymorphism, you can replace the following class 
  12272. implementation variants by the reference class. 
  12273.  
  12274. To use Visual Builder features with your collections, change the name of the 
  12275. desired collection class template in the list below from I... to IV..., and use 
  12276. the ivsrtbag.h header file instead of the header file that you would normally 
  12277. use without Visual Builder. 
  12278.  
  12279. Class Name                    Header File  Implementation Variant
  12280.  
  12281. ISortedBag                    isrtbag.h    AVL tree
  12282. IGSortedBag                   isrtbag.h    AVL tree
  12283.  
  12284. ISortedBagOnBSTKeySortedSet   isbbst.h     B* tree
  12285. IGSortedBagOnBSTKeySortedSet  isbbst.h     B* tree
  12286.  
  12287. ISortedBagOn-                 isbsls.h     Linked sequence
  12288.  SortedLinkedSequence
  12289. IGSortedBagOn                 isbsls.h     Linked sequence
  12290.  SortedLinkedSequence
  12291.  
  12292. ISortedBagOn-                 isbsts.h     Tabular sequence
  12293.  SortedTabularSequence
  12294. IGSortedBagOn-                isbsts.h     Tabular sequence
  12295.  SortedTabularSequence
  12296.  
  12297. ISortedBagOn-                 isbsds.h     Diluted sequence
  12298.  SortedDilutedSequence
  12299. IGSortedBagOn-                isbsds.h     Diluted sequence
  12300.  SortedDilutedSequence
  12301.  
  12302.  
  12303. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  12304.  
  12305. All members of flat collections are described in Introduction to Flat 
  12306. Collections. The following members are provided for sorted bag: 
  12307.  
  12308.      Constructor 
  12309.      Copy Constructor 
  12310.      Destructor 
  12311.      operator!= 
  12312.      operator= 
  12313.      operator== 
  12314.      add 
  12315.      addAllFrom 
  12316.      addDifference 
  12317.      addIntersection 
  12318.      addUnion 
  12319.      allElementsDo 
  12320.      anyElement 
  12321.      compare 
  12322.      contains 
  12323.      containsAllFrom 
  12324.      differenceWith 
  12325.      elementAt 
  12326.      elementAtPosition 
  12327.      firstElement 
  12328.      intersectionWith 
  12329.      isBounded 
  12330.      isEmpty 
  12331.      isFirst 
  12332.      isFull 
  12333.      isLast 
  12334.      lastElement 
  12335.      locate 
  12336.      locateNext 
  12337.      locateOrAdd 
  12338.      maxNumberOfElements 
  12339.      newCursor 
  12340.      numberOfDifferentElements 
  12341.      numberOfElements 
  12342.      numberOfOccurrences 
  12343.      position 
  12344.      remove 
  12345.      removeAll 
  12346.      removeAllOccurrences 
  12347.      removeAt 
  12348.      removeAtPosition 
  12349.      removeFirst 
  12350.      removeLast 
  12351.      replaceAt 
  12352.      setToFirst 
  12353.      setToLast 
  12354.      setToNext 
  12355.      setToNextDifferentElement 
  12356.      setToPosition 
  12357.      setToPrevious 
  12358.      unionWith 
  12359.  
  12360.  Sorted Bag also defines a cursor that inherits from IOrderedCursor. The 
  12361.  members for IOrderedCursor are described in Cursor. 
  12362.  
  12363.  
  12364. ΓòÉΓòÉΓòÉ 5.1.17.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  12365.  
  12366. The following implementation variants are defined for sorted bags: 
  12367.  
  12368.      Sorted bag 
  12369.      Sorted bag on B* key sorted set 
  12370.      Sorted bag on sorted linked sequence 
  12371.      Sorted bag on sorted tabular sequence 
  12372.      Sorted bag on sorted diluted sequence 
  12373.  
  12374.  
  12375. ΓòÉΓòÉΓòÉ 5.1.17.2.1. Sorted Bag ΓòÉΓòÉΓòÉ
  12376.  
  12377. ISortedBag  <Element>
  12378. IGSortedBag <Element, ECOps>
  12379.  
  12380. The default implementation of the class ISortedBag requires the following 
  12381. element functions: 
  12382.  
  12383. Element Type 
  12384.  
  12385.      Default constructor 
  12386.      Copy constructor 
  12387.      Destructor 
  12388.      Assignment 
  12389.      Equality test 
  12390.      Ordering relation 
  12391.  
  12392.  
  12393. ΓòÉΓòÉΓòÉ 5.1.17.2.2. Sorted Bag on B* Key Sorted Set ΓòÉΓòÉΓòÉ
  12394.  
  12395. ISortedBagOnBSTKeySortedSet  <Element>
  12396. IGSortedBagOnBSTKeySortedSet <Element, ECOps>
  12397.  
  12398. The implementation of the class ISortedBagOnBSTKeySortedSet requires the 
  12399. following element functions: 
  12400.  
  12401. Element Type 
  12402.  
  12403.      Default constructor 
  12404.      Copy constructor 
  12405.      Destructor 
  12406.      Assignment 
  12407.      Equality test 
  12408.      Ordering relation 
  12409.  
  12410.  
  12411. ΓòÉΓòÉΓòÉ 5.1.17.2.3. Sorted Bag on Sorted Linked Sequence ΓòÉΓòÉΓòÉ
  12412.  
  12413. ISortedBagOnSortedLinkedSequence  <Element>
  12414. IGSortedBagOnSortedLinkedSequence <Element, ECOps>
  12415.  
  12416. The implementation of the class ISortedBagOnSortedLinkedSequence requires the 
  12417. following element functions: 
  12418.  
  12419. Element Type 
  12420.  
  12421.      Default constructor 
  12422.      Constructor 
  12423.      Assignment 
  12424.      Equality test 
  12425.      Ordering relation 
  12426.  
  12427.  
  12428. ΓòÉΓòÉΓòÉ 5.1.17.2.4. Sorted Bag on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  12429.  
  12430. ISortedBagOnSortedTabularSequence  <Element>
  12431. IGSortedBagOnSortedTabularSequence <Element, ECOps>
  12432.  
  12433. The implementation of the class ISortedBagOnSortedTabularSequence requires the 
  12434. following element functions: 
  12435.  
  12436. Element Type 
  12437.  
  12438.      Default constructor 
  12439.      Copy constructor 
  12440.      Destructor 
  12441.      Assignment 
  12442.      Equality test 
  12443.      Ordering relation 
  12444.  
  12445.  
  12446. ΓòÉΓòÉΓòÉ 5.1.17.2.5. Sorted Bag on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  12447.  
  12448. ISortedBagOnSortedDilutedSequence  <Element>
  12449. IGSortedBagOnSortedDilutedSequence <Element, ECOps>
  12450.  
  12451. The implementation of the class ISortedBagOnSortedDilutedSequence requires the 
  12452. following element functions: 
  12453.  
  12454. Element Type 
  12455.  
  12456.      Default constructor 
  12457.      Copy constructor 
  12458.      Destructor 
  12459.      Assignment 
  12460.      Equality test 
  12461.      Ordering relation 
  12462.  
  12463.  
  12464. ΓòÉΓòÉΓòÉ 5.1.17.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  12465.  
  12466. For polymorphism, you can use the corresponding abstract class, IASortedBag, 
  12467. which is found in the iasrtbag.h header file, or the corresponding reference 
  12468. class, IRSortedBag, which is found in the irsrtbag.h header file. See 
  12469. Polymorphic Use of Collections for further information. 
  12470.  
  12471.  
  12472. ΓòÉΓòÉΓòÉ 5.1.17.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  12473.  
  12474. IASortedBag <Element>
  12475. IRSortedBag <Element, ConcreteBase>
  12476.  
  12477. The concrete base class is one of the classes defined above. 
  12478.  
  12479. The required functions are the same as the required functions of the concrete 
  12480. base class. 
  12481.  
  12482.  
  12483. ΓòÉΓòÉΓòÉ 5.1.18. Sorted Map ΓòÉΓòÉΓòÉ
  12484.  
  12485. Description 
  12486.  
  12487. Derivation 
  12488.  
  12489. Variants/Header Files 
  12490.  
  12491. Members 
  12492.  
  12493. Template Arguments and Required Functions 
  12494.  
  12495. Abstract/Reference Classes 
  12496.  
  12497. Examples 
  12498.  
  12499. To close all the panels in a chapter, double-click on this panel's system menu. 
  12500.  
  12501.  
  12502. ΓòÉΓòÉΓòÉ 5.1.18.1. Class Description - Sorted Map ΓòÉΓòÉΓòÉ
  12503.  
  12504. A sorted map is an ordered collection of zero or more elements that have a key. 
  12505. Element equality is supported and the values of the elements are relevant. 
  12506. Elements are sorted by the value of their keys. 
  12507.  
  12508. Only elements with unique keys are supported.  A request to add an element 
  12509. whose key already exists in another element of the collection causes an 
  12510. exception to be thrown.  A request to add a duplicate element is ignored. 
  12511.  
  12512. An example of using a sorted map is a program that matches the names of rivers 
  12513. and lakes to their coordinates on a topographical map.  The river or lake name 
  12514. is the key.  You cannot add a lake or river to the collection if it is already 
  12515. present in the collection.  You can display a list of all lakes and rivers, 
  12516. sorted by their names, and you can locate a given lake or river by its key, to 
  12517. determine its coordinates. 
  12518.  
  12519. Figure Combination of Flat Collection Properties gives an overview of the 
  12520. properties of a sorted map and its relationship to other flat collections. 
  12521.  
  12522.  
  12523. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  12524.  
  12525. Equality Key Collection     Equality Sorted Collection 
  12526.  
  12527.        Equality Key Sorted Collection
  12528.             Sorted Map
  12529.  
  12530. The diagram does not show all bases of sorted map. See the figure "Abstract 
  12531. Class Hierarchy" in section Abstract Classes for an illustration. 
  12532.  
  12533.  
  12534. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  12535.  
  12536. ISortedMap, the first class in the table below, is the default implementation 
  12537. variant. If you want to use polymorphism, you can replace the following class 
  12538. implementation variants by the reference class. 
  12539.  
  12540. To use Visual Builder features with your collections, change the name of the 
  12541. desired collection class template in the list below from I... to IV..., and use 
  12542. the ivsrtmap.h header file instead of the header file that you would normally 
  12543. use without Visual Builder. 
  12544.  
  12545. Class Name                   Header File  Implementation Variant
  12546.  
  12547. ISortedMap                   isrtmap.h    AVL tree
  12548. IGSortedMap                  isrtmap.h    AVL tree
  12549.  
  12550. ISortedMapOnBSTKeySortedSet  ismbst.h     B* tree
  12551. IGSortedMapOnBSTKeySortedSet ismbst.h     B* tree
  12552.  
  12553. ISortedMapOn-                ismsls.h     Linked sequence
  12554.  SortedLinkedSequence
  12555. IGSortedMapOn-               ismsls.h     Linked sequence
  12556.  SortedLinkedSequence
  12557.  
  12558. ISortedMapOn-                ismsts.h     Tabular sequence
  12559.  SortedTabularSequence
  12560. IGSortedMapOn-               ismsts.h     Tabular sequence
  12561.  SortedTabularSequence
  12562.  
  12563. ISortedMapOn-                ismsds.h     Diluted sequence
  12564.  SortedDilutedSequence
  12565. IGSortedMapOn-               ismsds.h     Diluted sequence
  12566.  SortedDilutedSequence
  12567.  
  12568.  
  12569. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  12570.  
  12571. All members of flat collections are described in Introduction to Flat 
  12572. Collections. The following members are provided for sorted maps: 
  12573.  
  12574.      Constructor 
  12575.      Copy Constructor 
  12576.      Destructor 
  12577.      operator!= 
  12578.      operator= 
  12579.      operator== 
  12580.      add 
  12581.      addAllFrom 
  12582.      addDifference 
  12583.      addIntersection 
  12584.      addOrReplaceElementWithKey 
  12585.      addUnion 
  12586.      allElementsDo 
  12587.      anyElement 
  12588.      compare 
  12589.      contains 
  12590.      containsAllFrom 
  12591.      containsAllKeysFrom 
  12592.      containsElementWithKey 
  12593.      differenceWith 
  12594.      elementAt 
  12595.      elementAtPosition 
  12596.      elementWithKey 
  12597.      firstElement 
  12598.      intersectionWith 
  12599.      isBounded 
  12600.      isEmpty 
  12601.      isFirst 
  12602.      isFull 
  12603.      isLast 
  12604.      key 
  12605.      lastElement 
  12606.      locate 
  12607.      locateElementWithKey 
  12608.      locateNext 
  12609.      locateNextElementWithKey 
  12610.      locateOrAdd 
  12611.      locateOrAddElementWithKey 
  12612.      maxNumberOfElements 
  12613.      newCursor 
  12614.      numberOfElements 
  12615.      position 
  12616.      remove 
  12617.      removeAll 
  12618.      removeAt 
  12619.      removeAtPosition 
  12620.      removeElementWithKey 
  12621.      removeFirst 
  12622.      removeLast 
  12623.      replaceAt 
  12624.      replaceElementWithKey 
  12625.      setToFirst 
  12626.      setToLast 
  12627.      setToNext 
  12628.      setToPosition 
  12629.      setToPrevious 
  12630.      unionWith 
  12631.  
  12632.  Sorted map also defines a cursor that inherits from IOrderedCursor. The 
  12633.  members for IOrderedCursor are described in Cursor. 
  12634.  
  12635.  
  12636. ΓòÉΓòÉΓòÉ 5.1.18.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  12637.  
  12638. The following implementation variants are defined for sorted maps: 
  12639.  
  12640.      Sorted map 
  12641.      Sorted map on B* key sorted set 
  12642.      Sorted map on sorted linked sequence 
  12643.      Sorted map on sorted tabular sequence 
  12644.      Sorted map on sorted diluted sequence 
  12645.  
  12646.  
  12647. ΓòÉΓòÉΓòÉ 5.1.18.2.1. Sorted Map ΓòÉΓòÉΓòÉ
  12648.  
  12649. ISortedMap  <Element, Key>
  12650. IGSortedMap <Element, Key, EKCOps>
  12651.  
  12652. The implementation of the class ISortedMap requires the following element and 
  12653. key-type functions: 
  12654.  
  12655. Element Type 
  12656.  
  12657.      Copy constructor 
  12658.      Destructor 
  12659.      Assignment 
  12660.      Key access 
  12661.      Equality test 
  12662.  
  12663.  Key Type 
  12664.  
  12665.  Ordering relation 
  12666.  
  12667.  
  12668. ΓòÉΓòÉΓòÉ 5.1.18.2.2. Sorted Map on B* Key Sorted Set ΓòÉΓòÉΓòÉ
  12669.  
  12670. ISortedMapOnBSTKeySortedSet  <Element, Key>
  12671. IGSortedMapOnBSTKeySortedSet <Element, Key, EKCOps>
  12672.  
  12673. The implementation of the class ISortedMapOnBSTKeySortedSet requires the 
  12674. following element and key-type functions: 
  12675.  
  12676. Element Type 
  12677.  
  12678.      Default constructor 
  12679.      Copy constructor 
  12680.      Destructor 
  12681.      Assignment 
  12682.      Key access 
  12683.      Equality test 
  12684.  
  12685.  Key Type 
  12686.  
  12687.  Ordering relation 
  12688.  
  12689.  
  12690. ΓòÉΓòÉΓòÉ 5.1.18.2.3. Sorted Map on Sorted Linked Sequence ΓòÉΓòÉΓòÉ
  12691.  
  12692. ISortedMapOnSortedLinkedSequence  <Element, Key>
  12693. IGSortedMapOnSortedLinkedSequence <Element, Key, EKCOps>
  12694.  
  12695. The implementation of the class ISortedMapOnSortedLinkedSequence requires the 
  12696. following element and key-type functions: 
  12697.  
  12698. Element Type 
  12699.  
  12700.      Copy constructor 
  12701.      Destructor 
  12702.      Assignment 
  12703.      Key access 
  12704.      Equality test 
  12705.  
  12706.  Key Type 
  12707.  
  12708.  Ordering relation 
  12709.  
  12710.  
  12711. ΓòÉΓòÉΓòÉ 5.1.18.2.4. Sorted Map on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  12712.  
  12713. ISortedMapOnSortedTabularSequence  <Element, Key>
  12714. IGSortedMapOnSortedTabularSequence <Element, Key, EKCOps>
  12715.  
  12716. The implementation of the class ISortedMapOnSortedTabularSequence requires the 
  12717. following element and key-type functions: 
  12718.  
  12719. Element Type 
  12720.  
  12721.      Default constructor 
  12722.      Copy constructor 
  12723.      Destructor 
  12724.      Assignment 
  12725.      Key access 
  12726.      Equality test 
  12727.  
  12728.  Key Type 
  12729.  
  12730.  Ordering relation 
  12731.  
  12732.  
  12733. ΓòÉΓòÉΓòÉ 5.1.18.2.5. Sorted Map on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  12734.  
  12735. ISortedMapOnSortedDilutedSequence  <Element, Key>
  12736. IGSortedMapOnSortedDilutedSequence <Element, Key, EKCOps>
  12737.  
  12738. The implementation of the class ISortedMapOnSortedDilutedSequence requires the 
  12739. following element and key-type functions: 
  12740.  
  12741. Element Type 
  12742.  
  12743.      Default constructor 
  12744.      Copy constructor 
  12745.      Destructor 
  12746.      Assignment 
  12747.      Key access 
  12748.      Equality test 
  12749.  
  12750.  Key Type 
  12751.  
  12752.  Ordering relation 
  12753.  
  12754.  
  12755. ΓòÉΓòÉΓòÉ 5.1.18.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  12756.  
  12757. For polymorphism, you can use the corresponding abstract class, IASortedMap, 
  12758. which is found in the iasrtmap.h header file, or the corresponding reference 
  12759. class, IRSortedMap, which is found in the irsrtmap.h header file. See 
  12760. Polymorphic Use of Collections for further information. 
  12761.  
  12762.  
  12763. ΓòÉΓòÉΓòÉ 5.1.18.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  12764.  
  12765. IASortedMap <Element, Key>
  12766. IRSortedMap <Element, Key, ConcreteBase>
  12767.  
  12768. The concrete base class is one of the classes defined above. 
  12769.  
  12770. The required functions are the same as the required functions of the concrete 
  12771. base class. 
  12772.  
  12773.  
  12774. ΓòÉΓòÉΓòÉ 5.1.18.4. Coding Example for Sorted Map ΓòÉΓòÉΓòÉ
  12775.  
  12776. The following program uses a sorted map and a sorted relation to display sorted 
  12777. lists of the name and size of files contained on a disk. It uses the default 
  12778. classes, ISortedMap and ISortedRelation, to implement the collections. The 
  12779. program uses the sorted map to store the name of the file, because all elements 
  12780. in a sorted map are unique and all names on a disk are unique.  It uses a 
  12781. sorted relation for the file size, because there may be identical file sizes, 
  12782. and identical values are permissible in sorted relations. 
  12783.  
  12784. The program uses the add() function to fill both collections.  To print the 
  12785. collections, it uses the forCursor macro and the allElementsDo() function. 
  12786.  
  12787. The program produces a list of files sorted by name (in ascending order) and a 
  12788. list of the same files sorted by file size (in descending order).  Because the 
  12789. output varies depending on the file system in use when it is run, no output is 
  12790. shown here. 
  12791.  
  12792.    // dskusage.C -  An example of using a Sorted Map and a Sorted Relation
  12793.    #include "dsur.h"
  12794.                         // Our own common exit for all errors:
  12795.    void errorExit(int, char*, char* = "");
  12796.  
  12797.                         // Use the default Sorted Map as is:
  12798.    #include <isrtmap.h>
  12799.                         // Use the default Sorted Relation as is:
  12800.    #include <isrtrel.h>
  12801.  
  12802.    int main (int argc, char* argv[]) {
  12803.        char* fspec = "dsu.dat"; // Default for input file
  12804.        if (argc > 1)   fspec = argv[1];
  12805.        ifstream  inputfile(fspec);
  12806.        if (!inputfile)
  12807.            errorExit(20, "Unable to open input file", fspec);
  12808.  
  12809.        ISortedMap     <DiskSpaceUR, char*> dsurByName;
  12810.        ISortedMap     <DiskSpaceUR, char*>::Cursor
  12811.                                             curByName(dsurByName);
  12812.  
  12813.        IGSortedRelation <DiskSpaceUR, int, DSURBySpaceOps>
  12814.           dsurBySpace;
  12815.        IGSortedRelation <DiskSpaceUR, int, DSURBySpaceOps>::Cursor
  12816.           curBySpace(dsurBySpace);
  12817.  
  12818.                             // Read all records into dsurByName
  12819.        while (inputfile.good()) {
  12820.           DiskSpaceUR dsur(inputfile);
  12821.           if (dsur.isValid()) {
  12822.              dsurByName.add(dsur);
  12823.              dsurBySpace.add(dsur);
  12824.           }
  12825.        }
  12826.        if (! inputfile.eof())
  12827.                 errorExit(39, "Error during read of", fspec);
  12828.  
  12829.        cout << "\n\nAll Disk Space Usage records "
  12830.             << "sorted (ascending) by name:\n" << endl;
  12831.  
  12832.        forCursor(curByName)
  12833.           cout << "  " << dsurByName.elementAt(curByName) << endl;
  12834.  
  12835.        cout << "\n\nAll Disk Space Usage records "
  12836.             << "sorted (descending) by space:\n" << endl;
  12837.  
  12838.        forCursor(curBySpace)
  12839.           cout << "  " << dsurBySpace.elementAt(curBySpace) << endl;
  12840.  
  12841.        return 0;
  12842.    }
  12843.  
  12844.    #include <stdlib.h>
  12845.                                        // for exit() definition
  12846.    void errorExit (int rc, char* s1, char* s2) {
  12847.        cerr << s1 << " " << s2 << endl;
  12848.        exit(rc);
  12849.    }
  12850.  
  12851.  
  12852. ΓòÉΓòÉΓòÉ 5.1.19. Sorted Relation ΓòÉΓòÉΓòÉ
  12853.  
  12854. Description 
  12855.  
  12856. Derivation 
  12857.  
  12858. Variants/Header Files 
  12859.  
  12860. Members 
  12861.  
  12862. Template Arguments and Required Functions 
  12863.  
  12864. Abstract/Reference Classes 
  12865.  
  12866. Examples 
  12867.  
  12868. To close all the panels in a chapter, double-click on this panel's system menu. 
  12869.  
  12870.  
  12871. ΓòÉΓòÉΓòÉ 5.1.19.1. Class Description - Sorted Relation ΓòÉΓòÉΓòÉ
  12872.  
  12873. A sorted relation is an ordered collection of zero or more elements that have a 
  12874. key.  The elements are sorted by the value of their key.  Element equality is 
  12875. supported, and the values of the elements are relevant. 
  12876.  
  12877. The keys of the elements are not unique.  You can add an element whether or not 
  12878. there is already an element in the collection with the same key. 
  12879.  
  12880. An example of using a sorted relation is a program used by telephone operators 
  12881. to provide directory assistance.  The computerized directory is a sorted 
  12882. relation whose key is the name of the individual or business associated with a 
  12883. telephone number.  When a caller requests the number of a given person or 
  12884. company, the operator enters the name of that person or company to access the 
  12885. phone number.  The collection can have multiple identical keys, because two 
  12886. individuals or companies might have the same name.  The collection is sorted 
  12887. alphabetically, because once a year it is used as the source material for a 
  12888. printed telephone directory. 
  12889.  
  12890. Figure Combination of Flat Collection Properties gives an overview of the 
  12891. properties of a sorted relation and its relationship to other flat collections. 
  12892.  
  12893.  
  12894. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  12895.  
  12896. Equality Key Collection    Equality Collection 
  12897.  
  12898.      Equality Key Sorted Collection
  12899.          Sorted Relation
  12900.  
  12901. The diagram does not show all bases of sorted relation. See the figure 
  12902. "Abstract Class Hierarchy" in section Abstract Classes for an illustration. 
  12903.  
  12904.  
  12905. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  12906.  
  12907. ISortedRelation, the first class in the table below, is the default 
  12908. implementation variant. If you want to use polymorphism, you can replace the 
  12909. following class implementation variants by the reference class. 
  12910.  
  12911. Note:  In the table, some class names have been hyphenated to fit in their 
  12912. column.  In your code you should not include these hyphens in the class names. 
  12913.  
  12914. To use Visual Builder features with your collections, change the name of the 
  12915. desired collection class template in the list below from I... to IV..., and use 
  12916. the ivsrtrel.h header file instead of the header file that you would normally 
  12917. use without Visual Builder. 
  12918.  
  12919. Class Name              Header File  Implementation Variant
  12920.  
  12921. ISortedRelation         isrtrel.h    Linked sequence
  12922. IGSortedRelation        isrtrel.h    Linked sequence
  12923.  
  12924. ISortedRelationOn-      isrsts.h     Tabular sequence
  12925.  SortedTabularSequence
  12926. IGSortedRelationOn-     isrsts.h     Tabular sequence
  12927.  SortedTabularSequence
  12928.  
  12929. ISortedRelationOn-      isrsds.h     Diluted sequence
  12930.  SortedDilutedSequence
  12931. IGSortedRelationOn-     isrsds.h     Diluted sequence
  12932.  SortedDilutedSequence
  12933.  
  12934.  
  12935. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  12936.  
  12937. All members of flat collections are described in Introduction to Flat 
  12938. Collections. The following members are provided for sorted relation: 
  12939.  
  12940.      Constructor 
  12941.      Copy Constructor 
  12942.      Destructor 
  12943.      operator!= 
  12944.      operator= 
  12945.      operator== 
  12946.      add 
  12947.      addAllFrom 
  12948.      addDifference 
  12949.      addIntersection 
  12950.      addOrReplaceElementWithKey 
  12951.      addUnion 
  12952.      allElementsDo 
  12953.      anyElement 
  12954.      compare 
  12955.      contains 
  12956.      containsAllFrom 
  12957.      containsAllKeysFrom 
  12958.      containsElementWithKey 
  12959.      differenceWith 
  12960.      elementAt 
  12961.      elementAtPosition 
  12962.      elementWithKey 
  12963.      firstElement 
  12964.      intersectionWith 
  12965.      isBounded 
  12966.      isEmpty 
  12967.      isFirst 
  12968.      isFull 
  12969.      isLast 
  12970.      key 
  12971.      lastElement 
  12972.      locate 
  12973.      locateElementWithKey 
  12974.      locateNext 
  12975.      locateNextElementWithKey 
  12976.      locateOrAdd 
  12977.      locateOrAddElementWithKey 
  12978.      maxNumberOfElements 
  12979.      newCursor 
  12980.      numberOfDifferentKeys 
  12981.      numberOfElements 
  12982.      numberOfElementsWithKey 
  12983.      position 
  12984.      remove 
  12985.      removeAll 
  12986.      removeAllElementsWithKey 
  12987.      removeAt 
  12988.      removeAtPosition 
  12989.      removeElementWithKey 
  12990.      removeFirst 
  12991.      removeLast 
  12992.      replaceAt 
  12993.      replaceElementWithKey 
  12994.      setToFirst 
  12995.      setToLast 
  12996.      setToNext 
  12997.      setToNextWithDifferentKey 
  12998.      setToPosition 
  12999.      setToPrevious 
  13000.      unionWith 
  13001.  
  13002.  Sorted relation also defines a cursor that inherits from IOrderedCursor. The 
  13003.  members for IOrderedCursor are described in Cursor. 
  13004.  
  13005.  
  13006. ΓòÉΓòÉΓòÉ 5.1.19.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  13007.  
  13008. The following implementation variants are defined for sorted relations: 
  13009.  
  13010.      Sorted relation 
  13011.      Sorted relation on sorted tabular sequence 
  13012.      Sorted relation on sorted diluted sequence 
  13013.  
  13014.  
  13015. ΓòÉΓòÉΓòÉ 5.1.19.2.1. Sorted Relation ΓòÉΓòÉΓòÉ
  13016.  
  13017. ISortedRelation  <Element, Key>
  13018. IGSortedRelation <Element, Key, EKCOps>
  13019.  
  13020. The default implementation of the class ISortedRelation requires the following 
  13021. element and key-type functions: 
  13022.  
  13023. Element Type 
  13024.  
  13025.      Copy constructor 
  13026.      Destructor 
  13027.      Assignment 
  13028.      Key access 
  13029.      Equality test 
  13030.  
  13031.  Key Type 
  13032.  
  13033.  Ordering relation 
  13034.  
  13035.  
  13036. ΓòÉΓòÉΓòÉ 5.1.19.2.2. Sorted Relation on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  13037.  
  13038. ISortedRelationOnSortedTabularSequence  <Element, Key>
  13039. IGSortedRelationOnSortedTabularSequence <Element, Key, EKCOps>
  13040.  
  13041. The implementation of the class ISortedRelationOnSortedTabularSequence requires 
  13042. the following element and key-type functions: 
  13043.  
  13044. Element Type 
  13045.  
  13046.      Default constructor 
  13047.      Copy constructor 
  13048.      Destructor 
  13049.      Assignment 
  13050.      Key access 
  13051.      Equality test 
  13052.  
  13053.  Key Type 
  13054.  
  13055.  Ordering relation 
  13056.  
  13057.  
  13058. ΓòÉΓòÉΓòÉ 5.1.19.2.3. Sorted Relation on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  13059.  
  13060. ISortedRelationOnSortedDilutedSequence  <Element, Key>
  13061. IGSortedRelationOnSortedDilutedSequence <Element, Key, EKCOps>
  13062.  
  13063. The implementation of the class ISortedRelationOnSortedDilutedSequence requires 
  13064. the following element and key-type functions: 
  13065.  
  13066. Element Type 
  13067.  
  13068.      Default constructor 
  13069.      Copy constructor 
  13070.      Destructor 
  13071.      Assignment 
  13072.      Key access 
  13073.      Equality test 
  13074.  
  13075.  Key Type 
  13076.  
  13077.  Ordering relation 
  13078.  
  13079.  
  13080. ΓòÉΓòÉΓòÉ 5.1.19.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  13081.  
  13082. For polymorphism, you can use the corresponding abstract class, 
  13083. IASortedRelation, which is found in the iasrtrel.h header file, or the 
  13084. corresponding reference class, IRSortedRelation, which is found in the 
  13085. irsrtrel.h header file. See Polymorphic Use of Collections for further 
  13086. information. 
  13087.  
  13088.  
  13089. ΓòÉΓòÉΓòÉ 5.1.19.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  13090.  
  13091. IASortedRelation <Element, Key>
  13092. IRSortedRelation <Element, Key,ConcreteBase>
  13093.  
  13094. The concrete base class is one of the classes defined above. 
  13095.  
  13096. The required functions are the same as the required functions of the concrete 
  13097. base class. 
  13098.  
  13099.  
  13100. ΓòÉΓòÉΓòÉ 5.1.19.4. Coding Example for Sorted Relation ΓòÉΓòÉΓòÉ
  13101.  
  13102. See Coding Example for Sorted Map for an example of a sorted relation. 
  13103.  
  13104.  
  13105. ΓòÉΓòÉΓòÉ 5.1.20. Sorted Set ΓòÉΓòÉΓòÉ
  13106.  
  13107. Description 
  13108.  
  13109. Derivation 
  13110.  
  13111. Variants/Header Files 
  13112.  
  13113. Members 
  13114.  
  13115. Template Arguments and Required Functions 
  13116.  
  13117. Abstract/Reference Classes 
  13118.  
  13119. Examples 
  13120.  
  13121. To close all the panels in a chapter, double-click on this panel's system menu. 
  13122.  
  13123.  
  13124. ΓòÉΓòÉΓòÉ 5.1.20.1. Class Description - Sorted Set ΓòÉΓòÉΓòÉ
  13125.  
  13126. A sorted set is an ordered collection of zero or more elements with element 
  13127. equality but no key.  Only unique elements are supported.  A request to add an 
  13128. element that already exists is ignored. The value of the elements is relevant. 
  13129.  
  13130. The elements of a sorted set are ordered such that the value of each element is 
  13131. less than or equal to the value of its successor. 
  13132.  
  13133. The element with the smallest value currently in a sorted set is called the 
  13134. first element.  The element with the largest value is called the last element. 
  13135. When an element is added, it is placed in the sorted set according to the 
  13136. defined ordering relation. 
  13137.  
  13138. An example of using a sorted set is a program that tests numbers to see if they 
  13139. are prime.  Two complementary sorted sets are used, one for prime numbers, and 
  13140. one for nonprime numbers.  When you enter a number, the program first looks in 
  13141. the set of nonprime numbers.  If the value is found there, the number is 
  13142. nonprime.  If the value is not found there, the program looks in the set of 
  13143. prime numbers.  If the value is found there, the number is prime.  Otherwise 
  13144. the program determines whether the number is prime or nonprime, and places it 
  13145. in the appropriate sorted set.  The program can also display a list of prime or 
  13146. nonprime numbers, beginning at the first prime or nonprime following a given 
  13147. value, because the numbers in a sorted set are sorted from smallest to largest. 
  13148.  
  13149. Figure Combination of Flat Collection Properties gives an overview of the 
  13150. properties of a sorted set and its relationship to other flat collections. 
  13151.  
  13152.  
  13153. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  13154.  
  13155.         Collection 
  13156. Ordered Collection 
  13157.  
  13158.   Sorted Collection     Equality Collection
  13159.       Equality Sorted Collection
  13160.           Sorted Set
  13161.  
  13162.  
  13163. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  13164.  
  13165. ISortedSet, the first class in the table below, is the default implementation 
  13166. variant. If you want to use polymorphism, you can replace the following class 
  13167. implementation variants by the reference class. 
  13168.  
  13169. To use Visual Builder features with your collections, change the name of the 
  13170. desired collection class template in the list below from I... to IV..., and use 
  13171. the ivsrtset.h header file instead of the header file that you would normally 
  13172. use without Visual Builder. 
  13173.  
  13174. Class Name            Header File  Implementation Variant
  13175.  
  13176. ISortedSet            isrtset.h    AVL tree
  13177. IGSortedSet           isrtset.h    AVL tree
  13178.  
  13179. ISortedSetOn-         issbst.h     B* tree
  13180.  BSTKeySortedSet
  13181. IGSortedSetOn-        issbst.h     B* tree
  13182.  BSTKeySortedSet
  13183.  
  13184. ISortedSetOn-         isssls.h     Linked sequence
  13185.  SortedLinkedSequence
  13186. IGSortedSetOn-        isssls.h     Linked sequence
  13187.  SortedLinkedSequence
  13188.  
  13189. ISortedSetOn-         isssts.h     Tabular sequence
  13190.  SortedTabularSequence
  13191. IGSortedSetOn-        isssts.h     Tabular sequence
  13192.  SortedTabularSequence
  13193.  
  13194. ISortedSetOn-         isssds.h     Diluted sequence
  13195.  SortedDilutedSequence
  13196. IGSortedSetOn-        isssds.h     Diluted sequence
  13197.  SortedDilutedSequence
  13198.  
  13199.  
  13200. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  13201.  
  13202. All members of flat collections are described in Introduction to Flat 
  13203. Collections. The following members are provided for sorted sets: 
  13204.  
  13205.      Constructor 
  13206.      Copy Constructor 
  13207.      Destructor 
  13208.      operator!= 
  13209.      operator= 
  13210.      operator== 
  13211.      add 
  13212.      addAllFrom 
  13213.      addDifference 
  13214.      addIntersection 
  13215.      addUnion 
  13216.      allElementsDo 
  13217.      anyElement 
  13218.      compare 
  13219.      contains 
  13220.      containsAllFrom 
  13221.      differenceWith 
  13222.      elementAt 
  13223.      elementAtPosition 
  13224.      firstElement 
  13225.      intersectionWith 
  13226.      isBounded 
  13227.      isEmpty 
  13228.      isFirst 
  13229.      isFull 
  13230.      isLast 
  13231.      lastElement 
  13232.      locate 
  13233.      locateNext 
  13234.      locateOrAdd 
  13235.      maxNumberOfElements 
  13236.      newCursor 
  13237.      position 
  13238.      remove 
  13239.      removeAll 
  13240.      removeAt 
  13241.      removeAtPosition 
  13242.      removeFirst 
  13243.      removeLast 
  13244.      replaceAt 
  13245.      setToFirst 
  13246.      setToLast 
  13247.      setToNext 
  13248.      setToPosition 
  13249.      setToPrevious 
  13250.      unionWith 
  13251.  
  13252.  Sorted Set also defines a cursor that inherits from IOrderedCursor. The 
  13253.  members for IOrderedCursor are described in Cursor. 
  13254.  
  13255.  
  13256. ΓòÉΓòÉΓòÉ 5.1.20.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  13257.  
  13258. The following implementation variants are defined for sorted sets: 
  13259.  
  13260.      Sorted set 
  13261.      Sorted set on B* key sorted set 
  13262.      Sorted set on sorted linked sequence 
  13263.      Sorted set on sorted tabular sequence 
  13264.      Sorted set on sorted diluted sequence 
  13265.  
  13266.  
  13267. ΓòÉΓòÉΓòÉ 5.1.20.2.1. Sorted Set ΓòÉΓòÉΓòÉ
  13268.  
  13269. ISortedSet  <Element>
  13270. IGSortedSet <Element, ECOps>
  13271.  
  13272. The default implementation of the class ISortedSet requires the following 
  13273. element functions: 
  13274.  
  13275. Element Type 
  13276.  
  13277.      Copy constructor 
  13278.      Destructor 
  13279.      Assignment 
  13280.      Equality test 
  13281.      Ordering relation 
  13282.  
  13283.  
  13284. ΓòÉΓòÉΓòÉ 5.1.20.2.2. Sorted Set on B* Key Sorted Set ΓòÉΓòÉΓòÉ
  13285.  
  13286. ISortedSetOnBSTKeySortedSet  <Element>
  13287. IGSortedSetOnBSTKeySortedSet <Element, ECOps>
  13288.  
  13289. The default implementation of the class ISortedSetOnBSTKeySortedSet requires 
  13290. the following element functions: 
  13291.  
  13292. Element Type 
  13293.  
  13294.      Default constructor 
  13295.      Copy constructor 
  13296.      Destructor 
  13297.      Assignment 
  13298.      Equality test 
  13299.      Ordering relation 
  13300.  
  13301.  
  13302. ΓòÉΓòÉΓòÉ 5.1.20.2.3. Sorted Set on Sorted Linked Sequence ΓòÉΓòÉΓòÉ
  13303.  
  13304. ISortedSetOnSortedLinkedSequence  <Element>
  13305. IGSortedSetOnSortedLinkedSequence <Element, ECOps>
  13306.  
  13307. The implementation of the class ISortedSetOnSortedLinkedSequence requires the 
  13308. following element functions: 
  13309.  
  13310. Element Type 
  13311.  
  13312.      Copy constructor 
  13313.      Assignment 
  13314.      Destructor 
  13315.      Equality test 
  13316.      Ordering relation 
  13317.  
  13318.  
  13319. ΓòÉΓòÉΓòÉ 5.1.20.2.4. Sorted Set on Sorted Tabular Sequence ΓòÉΓòÉΓòÉ
  13320.  
  13321. ISortedSetOnSortedTabularSequence  <Element>
  13322. IGSortedSetOnSortedTabularSequence <Element, ECOps>
  13323.  
  13324. The implementation of the class ISortedSetOnSortedTabularSequence requires the 
  13325. following element functions: 
  13326.  
  13327. Element Type 
  13328.  
  13329.      Default constructor 
  13330.      Copy constructor 
  13331.      Destructor 
  13332.      Assignment 
  13333.      Equality test 
  13334.      Ordering relation 
  13335.  
  13336.  
  13337. ΓòÉΓòÉΓòÉ 5.1.20.2.5. Sorted Set on Sorted Diluted Sequence ΓòÉΓòÉΓòÉ
  13338.  
  13339. ISortedSetOnSortedDilutedSequence  <Element>
  13340. IGSortedSetOnSortedDilutedSequence <Element, ECOps>
  13341.  
  13342. The implementation of the class ISortedSetOnSortedDilutedSequence requires the 
  13343. following element functions: 
  13344.  
  13345. Element Type 
  13346.  
  13347.      Default constructor 
  13348.      Copy constructor 
  13349.      Destructor 
  13350.      Assignment 
  13351.      Equality test 
  13352.      Ordering relation 
  13353.  
  13354.  
  13355. ΓòÉΓòÉΓòÉ 5.1.20.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  13356.  
  13357. For polymorphism, you can use the corresponding abstract class, IASortedSet, 
  13358. which is found in the iasrtset.h header file, or the corresponding reference 
  13359. class, IRSortedSet, which is found in the irsrtset.h header file. See 
  13360. Polymorphic Use of Collections for further information. 
  13361.  
  13362.  
  13363. ΓòÉΓòÉΓòÉ 5.1.20.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  13364.  
  13365. IASortedSet <Element>
  13366. IRSortedSet <Element, ConcreteBase>
  13367.  
  13368. The concrete base class is one of the classes defined above. 
  13369.  
  13370. The required functions are the same as the required functions of the concrete 
  13371. base class. 
  13372.  
  13373.  
  13374. ΓòÉΓòÉΓòÉ 5.1.20.4. Coding Example for Sorted Set ΓòÉΓòÉΓòÉ
  13375.  
  13376. The following program uses the default class, ISortedSet, to create sorted 
  13377. lists of planets with different properties. The program stores all planets in 
  13378. our solar system, all heavy planets in our solar system, all bright planets in 
  13379. our solar system, and all heavy or bright planets in our solar system in a 
  13380. number of sorted sets.  Each set sorts the planets by its distance from the 
  13381. sun. 
  13382.  
  13383. The program uses the forCursor macro to create the heavyPlanets and the 
  13384. brightPlanets collections. It uses the allElementsDo() function to display the 
  13385. planets in each collection and the unionWith() function when creating the 
  13386. bright-or-heavy planets category. 
  13387.  
  13388.    // planets.C  -  An example of using a Sorted Set
  13389.    #include <iostream.h>
  13390.  
  13391.                      // Let's use the Sorted Set Default Variant:
  13392.    #include <isrtset.h>
  13393.  
  13394.                      // Get Class Planet:
  13395.    #include "planet.h"
  13396.  
  13397.  
  13398.    int main()    {
  13399.       ISortedSet<Planet>  allPlanets, heavyPlanets, brightPlanets;
  13400.                           // A cursor to cursor through allPlanets:
  13401.       ISortedSet<Planet>::Cursor aPCursor(allPlanets);
  13402.  
  13403.       SayPlanetName showPlanet;
  13404.  
  13405.       allPlanets.add( Planet("Earth",   149.60f,   1.0000f, 99.9f));
  13406.       allPlanets.add( Planet("Jupiter", 778.3f,  317.818f,  -2.4f));
  13407.       allPlanets.add( Planet("Mars",    227.9f,    0.1078f, -1.9f));
  13408.       allPlanets.add( Planet("Mercury",  57.91f,   0.0558f, -0.2f));
  13409.       allPlanets.add( Planet("Neptun", 4498.f,    17.216f,  +7.6f));
  13410.       allPlanets.add( Planet("Pluto",  5910.f,     0.18f,  +14.7f));
  13411.       allPlanets.add( Planet("Saturn", 1428.f,    95.112f,  +0.8f));
  13412.       allPlanets.add( Planet("Uranus", 2872.f,    14.517f,  +5.8f));
  13413.       allPlanets.add( Planet("Venus",   108.21f,   0.8148f, -4.1f));
  13414.  
  13415.       forCursor(aPCursor)    {
  13416.          if (allPlanets.elementAt(aPCursor).isHeavy())
  13417.             heavyPlanets.add(allPlanets.elementAt(aPCursor));
  13418.  
  13419.          if (allPlanets.elementAt(aPCursor).isBright())
  13420.             brightPlanets.add(allPlanets.elementAt(aPCursor));
  13421.       }
  13422.  
  13423.       cout << endl << endl << "All Planets: " << endl;
  13424.       allPlanets.allElementsDo(showPlanet);
  13425.  
  13426.       cout << endl << endl << "Heavy Planets: " << endl;
  13427.       heavyPlanets.allElementsDo(showPlanet);
  13428.  
  13429.       cout << endl << endl << "Bright Planets: " << endl;
  13430.       brightPlanets.allElementsDo(showPlanet);
  13431.  
  13432.       cout << endl << endl << "Bright-or-Heavy Planets: " << endl;
  13433.       brightPlanets.unionWith(heavyPlanets);
  13434.       brightPlanets.allElementsDo(showPlanet);
  13435.  
  13436.       cout << endl << endl
  13437.            << "Did you notice that all these Sets are sorted"
  13438.            << " in the same order"
  13439.            << endl
  13440.            << " (distance of planet from sun) ? " << endl;
  13441.  
  13442.       return 0;
  13443.  
  13444.    }
  13445.  
  13446. The program produces the following output: 
  13447.  
  13448.  
  13449.  
  13450. All Planets:
  13451.  Mercury  Venus  Earth  Mars  Jupiter  Saturn  Uranus  Neptune  Pluto
  13452.  
  13453. Heavy Planets:
  13454.  Jupiter  Saturn  Uranus  Neptune
  13455.  
  13456. Bright Planets:
  13457.  Mercury  Venus  Mars  Jupiter
  13458.  
  13459. Bright-or-Heavy Planets:
  13460.  Mercury  Venus  Mars  Jupiter  Saturn  Uranus  Neptune
  13461.  
  13462. Did you notice that all these Sets are sorted in the same order
  13463.  (distance of planet from sun) ?
  13464.  
  13465.  
  13466. ΓòÉΓòÉΓòÉ 5.1.21. Stack ΓòÉΓòÉΓòÉ
  13467.  
  13468. Description 
  13469.  
  13470. Derivation 
  13471.  
  13472. Variants/Header Files 
  13473.  
  13474. Members 
  13475.  
  13476. Template Arguments and Required Functions 
  13477.  
  13478. Abstract/Reference Classes 
  13479.  
  13480. Examples 
  13481.  
  13482. To close all the panels in a chapter, double-click on this panel's system menu. 
  13483.  
  13484.  
  13485. ΓòÉΓòÉΓòÉ 5.1.21.1. Class Description - Stack ΓòÉΓòÉΓòÉ
  13486.  
  13487. A stack is a sequence with restricted access.  It is an ordered collection of 
  13488. elements with no key and no element equality.  The elements are arranged so 
  13489. that each collection has a first and a last element, each element except the 
  13490. last has a next element, and each element but the first has a previous element. 
  13491. The type and value of the elements are irrelevant and have no effect on the 
  13492. behavior of the stack. 
  13493.  
  13494. Elements are added to and deleted from the top of the stack.  Consequently, the 
  13495. elements of a stack are in reverse chronological order. 
  13496.  
  13497. A stack is characterized by a last-in, first-out (LIFO) behavior. 
  13498.  
  13499. An example of using a stack is a program that keeps track of daily tasks that 
  13500. you have begun to work on but that have been interrupted. When you are working 
  13501. on a task and something else comes up that is more urgent, you enter a 
  13502. description of the interrupted task and where you stopped it into your program, 
  13503. and the task is pushed onto the stack. Whenever you complete a task, you ask 
  13504. the program for the most recently saved task that was interrupted.  This task 
  13505. is popped off the stack, and you resume your work where you left off.  When you 
  13506. attempt to pop an item off the stack and no item is available, you have 
  13507. completed all your tasks and you can go home. 
  13508.  
  13509.  
  13510. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  13511.  
  13512. Collection 
  13513.  
  13514.   Ordered Collection
  13515.    Sequential Collection
  13516.      Sequence
  13517.       Stack
  13518.  
  13519. Note that stack is based on sequence but is not actually derived from it or 
  13520. from the other classes shown above. See Restricted Access for further details. 
  13521.  
  13522.  
  13523. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  13524.  
  13525. IStack, the first class in the table below, is the default implementation 
  13526. variant. If you want to use polymorphism you can replace the following class 
  13527. implementation variants by the reference class. 
  13528.  
  13529. To use Visual Builder features with your collections, change the name of the 
  13530. desired collection class template in the list below from I... to IV..., and use 
  13531. the ivstack.h header file instead of the header file that you would normally 
  13532. use without Visual Builder. 
  13533.  
  13534. Class Name                 Header File  Implementation Variant
  13535.  
  13536. IStack                     istack.h     Linked sequence
  13537. IGStack                    istack.h     Linked sequence
  13538.  
  13539. IStackOnTabularSequence    istkts.h     Tabular sequence
  13540. IGStackOnTabularSequence   istkts.h     Tabular sequence
  13541.  
  13542. IStackOnDilutedSequence    istkds.h     Diluted sequence
  13543. IGStackOnDilutedSequence   istkds.h     Diluted sequence
  13544.  
  13545.  
  13546. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  13547.  
  13548. All members of flat collections are described in Introduction to Flat 
  13549. Collections. The following members are provided for stack: 
  13550.  
  13551.      Constructor 
  13552.      Copy Constructor 
  13553.      Destructor 
  13554.      operator= 
  13555.      add 
  13556.      addAllFrom 
  13557.      addAsLast 
  13558.      allElementsDo 
  13559.      anyElement 
  13560.      compare 
  13561.      elementAt 
  13562.      elementAtPosition 
  13563.      firstElement 
  13564.      isBounded 
  13565.      isEmpty 
  13566.      isFirst 
  13567.      isFull 
  13568.      isLast 
  13569.      lastElement 
  13570.      maxNumberOfElements 
  13571.      newCursor 
  13572.      numberOfElements 
  13573.      pop 
  13574.      position 
  13575.      push 
  13576.      removeAll 
  13577.      removeLast 
  13578.      setToFirst 
  13579.      setToLast 
  13580.      setToNext 
  13581.      setToPosition 
  13582.      setToPrevious 
  13583.      top 
  13584.  
  13585.  Stack also defines a cursor that inherits from IOrderedCursor.  The members 
  13586.  for IOrderedCursor are described in Cursor. 
  13587.  
  13588.  
  13589. ΓòÉΓòÉΓòÉ 5.1.21.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  13590.  
  13591. The following implementation variants are defined for stacks: 
  13592.  
  13593.      Stack 
  13594.      Stack on tabular sequence 
  13595.      Stack on diluted sequence 
  13596.  
  13597.  
  13598. ΓòÉΓòÉΓòÉ 5.1.21.2.1. Stack ΓòÉΓòÉΓòÉ
  13599.  
  13600. IStack  <Element>
  13601. IGStack <Element, StdOps>
  13602.  
  13603. The default implementation of the class IStack requires the following element 
  13604. functions: 
  13605.  
  13606. Element Type 
  13607.  
  13608.      Copy constructor 
  13609.      Destructor 
  13610.      Assignment 
  13611.  
  13612.  
  13613. ΓòÉΓòÉΓòÉ 5.1.21.2.2. Stack on Tabular Sequence ΓòÉΓòÉΓòÉ
  13614.  
  13615. IStackOnTabularSequence  <Element>
  13616. IGStackOnTabularSequence <Element, StdOps>
  13617.  
  13618. The implementation of the class IStackOnTabularSequence requires the following 
  13619. element functions: 
  13620.  
  13621. Element Type 
  13622.  
  13623.      Default constructor 
  13624.      Copy constructor 
  13625.      Destructor 
  13626.      Assignment 
  13627.  
  13628.  
  13629. ΓòÉΓòÉΓòÉ 5.1.21.2.3. Stack on Diluted Sequence ΓòÉΓòÉΓòÉ
  13630.  
  13631. IStackOnDilutedSequence  <Element>
  13632. IGStackOnDilutedSequence <Element, StdOps>
  13633.  
  13634. The implementation of the class IStackOnDilutedSequence requires the following 
  13635. element functions: 
  13636.  
  13637. Element Type 
  13638.  
  13639.      Default constructor 
  13640.      Copy constructor 
  13641.      Destructor 
  13642.      Assignment 
  13643.  
  13644.  
  13645. ΓòÉΓòÉΓòÉ 5.1.21.3. Abstract Class and Reference Class ΓòÉΓòÉΓòÉ
  13646.  
  13647. For polymorphism, you can use the corresponding abstract class, IAStack, which 
  13648. is found in the iastack.h header file, or the corresponding reference class, 
  13649. IRStack, which is found in the irstack.h header file. See Polymorphic Use of 
  13650. Collections for further information. 
  13651.  
  13652.  
  13653. ΓòÉΓòÉΓòÉ 5.1.21.3.1. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  13654.  
  13655. IRStack <Element, ConcreteBase>
  13656. IAStack <Element>
  13657.  
  13658. The concrete base class is one of the classes defined above. 
  13659.  
  13660. The required functions are the same as the required functions of the concrete 
  13661. base class. 
  13662.  
  13663.  
  13664. ΓòÉΓòÉΓòÉ 5.1.21.4. Coding Example for Stack ΓòÉΓòÉΓòÉ
  13665.  
  13666. The following program creates two stacks (Stack1 and Stack2) using the default 
  13667. class, IStack. It adds a number of words to Stack1, removes them from Stack1, 
  13668. adds them to Stack2, and finally removes them from Stack2 so that they can be 
  13669. printed.  The push() and pop() functions are used for adding and removing 
  13670. elements, respectively. 
  13671.  
  13672. Between these stack operations the stacks are printed. To prevent the stack 
  13673. from changing during printing, the program uses the constant version of the 
  13674. iterator class, IConstantIterator with the allElementsDo() function.  The words 
  13675. print in the same order as they were originally added to Stack1. 
  13676.  
  13677. Because of the nature of the stack class, the program must use the constant 
  13678. iterator class, IConstantIterator, when printing the stacks. It uses the push() 
  13679. and pop() functions for adding and removing elements, respectively.  The 
  13680. allElementsDo() function is used when the collection is printed. 
  13681.  
  13682.    // pushpop.C  -  An example of using a Stack
  13683.    #include <string.h>
  13684.    #include <iostream.h>
  13685.                          // Let's use the default stack: IStack
  13686.    #include <istack.h>
  13687.  
  13688.    typedef IStack <char*> SimpleStack;
  13689.                          // The stack requires iteration to be const.
  13690.    typedef IConstantIterator <char*> StackIterator;
  13691.  
  13692.  
  13693.    // Test variables to put into our Stack:
  13694.  
  13695.    char *String[9] = {    "The",  "quick",  "brown",  "fox",
  13696.                           "jumps",  "over",  "a",  "lazy",  "dog." };
  13697.  
  13698.    // A class to display the contents of our Stack:
  13699.  
  13700.    class PrintClass : public StackIterator
  13701.    {
  13702.    public:
  13703.       IBoolean applyTo(char* const& w)
  13704.          {
  13705.          cout << w << endl;
  13706.          return(True);
  13707.          }
  13708.    };
  13709.  
  13710.  
  13711.    // Main program
  13712.    int main()
  13713.    {
  13714.       SimpleStack Stack1, Stack2;
  13715.       char *S;
  13716.       PrintClass Print;
  13717.  
  13718.       // We specify two stacks.
  13719.       // First all the strings are pushed onto the first stack.
  13720.       // Next, they are popped from the first and pushed onto
  13721.       // the second.
  13722.       // Finally they are popped from the second and printed.
  13723.       // During this final print the strings must appear
  13724.       // in their original order.
  13725.  
  13726.       int i;
  13727.  
  13728.       for (i = 0; i < 9; i ++) {
  13729.          Stack1.push(String[i]);
  13730.          }
  13731.  
  13732.       cout << "Contents of Stack1:" << endl;
  13733.       Stack1.allElementsDo(Print);
  13734.       cout << "----------------------------" << endl;
  13735.  
  13736.       while (!Stack1.isEmpty()) {
  13737.          Stack1.pop(S);             // Pop from stack 1
  13738.          Stack2.push(S);            // Add it on top of stack 2
  13739.          }
  13740.  
  13741.       cout << "Contents of Stack2:" << endl;
  13742.       Stack2.allElementsDo(Print);
  13743.       cout << "----------------------------" << endl;
  13744.  
  13745.       while (!Stack2.isEmpty()) {
  13746.          Stack2.pop(S);
  13747.          cout << "Popped from Stack 2: " << S << endl;
  13748.          }
  13749.  
  13750.       return(0);
  13751.    }
  13752.  
  13753. This program produces the following output: 
  13754.  
  13755. Contents of Stack1:
  13756. The
  13757. quick
  13758. brown
  13759. fox
  13760. jumps
  13761. over
  13762. a
  13763. lazy
  13764. dog.
  13765. ----------------------------
  13766. Contents of Stack2:
  13767. dog.
  13768. lazy
  13769. a
  13770. over
  13771. jumps
  13772. fox
  13773. brown
  13774. quick
  13775. The
  13776. ----------------------------
  13777. Popped from Stack 2: The
  13778. Popped from Stack 2: quick
  13779. Popped from Stack 2: brown
  13780. Popped from Stack 2: fox
  13781. Popped from Stack 2: jumps
  13782. Popped from Stack 2: over
  13783. Popped from Stack 2: a
  13784. Popped from Stack 2: lazy
  13785. Popped from Stack 2: dog.
  13786.  
  13787.  
  13788. ΓòÉΓòÉΓòÉ 5.2. Tree Collection Classes ΓòÉΓòÉΓòÉ
  13789.  
  13790. This section contains the following chapters: 
  13791.  
  13792.  Introduction to Trees Introduces the concept of trees. 
  13793.  
  13794.  N-ary Tree     Describes n-ary tree, the tree collection of the Collection 
  13795.                 Class Library. Defines the class implementation variants, 
  13796.                 template arguments, and required functions for n-ary tree. 
  13797.                 Declarations for n-ary tree are provided, terms are defined, 
  13798.                 and the public member functions of n-ary tree are described. 
  13799.  
  13800.  
  13801. ΓòÉΓòÉΓòÉ 5.2.1. Introduction to Trees ΓòÉΓòÉΓòÉ
  13802.  
  13803. A tree is a collection of nodes that can have an arbitrary number of references 
  13804. to other nodes.  There can be no cycles or short-circuit references. A unique 
  13805. path connects every two nodes. One node is designated as the root of the tree. 
  13806.  
  13807. Formally, a tree can be defined recursively in the following manner: 
  13808.  
  13809.    1. A single node by itself is a tree.  This node is also the root of the 
  13810.       tree. 
  13811.  
  13812.    2. If N is a node and T-1, T-2, ..., T-k are trees with roots R-1, R-2, ..., 
  13813.       R-k, respectively, then a new tree can be constructed by making N the 
  13814.       parent of the nodes R-1, R-2, ..., R-k. In this new tree, N is the root 
  13815.       and T-1, T-2, ..., T-k are the subtrees of the root N.  Nodes R-1, R-2, 
  13816.       ..., R-k are called children of node N. 
  13817.  
  13818.  Associated with each node is a data item called element. 
  13819.  
  13820.  Nodes without children are called leaves or terminals. The number of children 
  13821.  in a node is called the degree of that node. The level of a given node is the 
  13822.  number of steps in the path from the root to the given node. The root is at 
  13823.  level 0 by definition. The height of a tree is the length of the longest path 
  13824.  from the root to any node. 
  13825.  
  13826.  
  13827. ΓòÉΓòÉΓòÉ 5.2.1.1. Defining the Traversal Order of Tree Elements ΓòÉΓòÉΓòÉ
  13828.  
  13829. You can define the order in which nodes of a tree are traversed by specifying a 
  13830. parameter of type ITreeIterationOrder in calls to the following member 
  13831. functions: 
  13832.  
  13833.      setToFirst 
  13834.      setToLast 
  13835.      setToNext 
  13836.      setToPrevious 
  13837.      allElementsDo, allSubtreeElementsDo 
  13838.  
  13839.  These functions are described in N-ary Tree. 
  13840.  
  13841.  The ITreeIterationOrder parameter can have one of two values: IPreorder or 
  13842.  IPostorder. The effect of each of these values is explained below. 
  13843.  
  13844.  IPreorder 
  13845.  
  13846.  The search begins at the root of the tree, and continues with the leftmost 
  13847.  child of the root.  If the child is the root of a subtree, the search 
  13848.  continues with the leftmost child of the subtree, and so on, until a terminal 
  13849.  node is detected.  The search continues with all siblings of the terminal 
  13850.  node, from left to right.  If any of these siblings is the root of a subtree, 
  13851.  the subtree is searched the same way as described above for the tree. 
  13852.  
  13853.  The preorder method can be summarized by the following recursive rules: 
  13854.  
  13855.    1. Visit the root. 
  13856.    2. Traverse the subtrees from left to right in preorder. 
  13857.  
  13858.  IPostorder 
  13859.  
  13860.  The IPostorder method is the opposite of IPreorder.  The search begins with 
  13861.  the leftmost terminal node in the tree.  Then that node's siblings are 
  13862.  searched from left to right.  If any of these siblings is the root of a 
  13863.  subtree, the subtree is searched for its leftmost terminal node. 
  13864.  
  13865.  The postorder method can be sumarized by the following recursive rules: 
  13866.  
  13867.    1. Traverse the subtrees from left to right in postorder. 
  13868.    2. Visit the root. 
  13869.  
  13870.  The following figure shows a tree with 12 nodes, and the order of traversal 
  13871.  for both preorder and postorder methods. Numbers indicate the preorder method 
  13872.  (node 1 is searched before node 2) while letters indicate the postorder method 
  13873.  (node A is searched before node B). 
  13874.  
  13875.  
  13876.   Preorder and Postorder Iteration Methods for Trees
  13877.  
  13878.  
  13879. ΓòÉΓòÉΓòÉ 5.2.2. N-ary Tree ΓòÉΓòÉΓòÉ
  13880.  
  13881. Description 
  13882.  
  13883. Derivation 
  13884.  
  13885. Variants/Header Files 
  13886.  
  13887. Members 
  13888.  
  13889. Template Arguments and Required Functions 
  13890.  
  13891. Examples 
  13892.  
  13893. To close all the panels in a chapter, double-click on this panel's system menu. 
  13894.  
  13895.  
  13896. ΓòÉΓòÉΓòÉ 5.2.2.1. Class Description - ITree ΓòÉΓòÉΓòÉ
  13897.  
  13898. An n-ary tree is a special tree where each node can have up to n children. 
  13899.  
  13900. n must be greater than one.  If n is one, the tree is a list.  If n is zero, 
  13901. the structure loses its meaning. 
  13902.  
  13903. An example of using an n-ary tree is a program used to build a family tree. 
  13904. (For simplicity, assume that the family tree is not concerned with information 
  13905. about spouses.) Whenever you discover a relative who is not already in your 
  13906. family tree, you enter the relative's name. If you know the parent's name, and 
  13907. the parent is already in the collection, the new relative is added as a child 
  13908. of the existing parent. If the parent is known but is not in the collection, a 
  13909. new collection is created, with the parent as the root element and the child as 
  13910. a child node of the parent.  If you do not know the parent, the relative is 
  13911. entered as the root element of a new collection.  You can also enter 
  13912. information about the children of a given relative; this information is used to 
  13913. attach a subtree, whose root node is the child, to the node of the parent of 
  13914. that child. Once you have established the collection, you can determine who is 
  13915. the parent or oldest known ancestor of a given relative, and you can display a 
  13916. list of all descendents of a given family member. 
  13917.  
  13918.  
  13919. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  13920.  
  13921. There are no bases or derived classes for N-ary Tree. 
  13922.  
  13923.  
  13924. ΓòÉΓòÉΓòÉ <hidden> Variants and Header Files ΓòÉΓòÉΓòÉ
  13925.  
  13926. ITree is the default implementation variant based on tabular tree.  IGTree is 
  13927. the default implementation variant with generic operations class.  Both classes 
  13928. are declared in itree.h. No reference class exists for tree classes. 
  13929.  
  13930.  
  13931. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  13932.  
  13933. Tree Functions lists the member functions for N-ary Tree. 
  13934.  
  13935.  
  13936. ΓòÉΓòÉΓòÉ 5.2.2.2. Template Arguments and Required Functions ΓòÉΓòÉΓòÉ
  13937.  
  13938. ITree  <Element, numberOfChildren>
  13939. IGTree <Element, StdOps, numberOfChildren>
  13940.  
  13941. The default implementation of ITree requires the following element functions: 
  13942.  
  13943. Element Type 
  13944.  
  13945.      Copy constructor 
  13946.      Destructor 
  13947.      Assignment 
  13948.  
  13949.  The argument value of numberOfChildren() specifies the maximum number of 
  13950.  children for each node. 
  13951.  
  13952.  
  13953. ΓòÉΓòÉΓòÉ 5.2.2.3. Terms Used ΓòÉΓòÉΓòÉ
  13954.  
  13955. Some of the terms used in this chapter are defined below. You can also use the 
  13956. Glossary to look up terms you are unfamiliar with. 
  13957.  
  13958.  this tree           The tree to which a function is applied, in contrast to 
  13959.                      the given tree. 
  13960.  
  13961.  given ...           Referring to a tree, element, or function that is given as 
  13962.                      a function argument. 
  13963.  
  13964.  returned element    An element returned as a function return value. 
  13965.  
  13966.  iteration order     The order in which elements are visited in functions 
  13967.                      allElementsDo(), allSubtreeElementsDo(), setToNext(), and 
  13968.                      setToPrevious(). 
  13969.  
  13970.  
  13971. ΓòÉΓòÉΓòÉ 5.2.2.4. Coding Example for N-ary Tree ΓòÉΓòÉΓòÉ
  13972.  
  13973. The following sample constructs a binary tree for the following expression: 
  13974. (8+2) * (2+4) / (7-5). The program prints this tree in preorder, using prefix 
  13975. notation. It then calculates the result of the expression. The program 
  13976. identifies subtrees consisting of an operand and two operators, calculates the 
  13977. result and replaces the subtree by its result. Finally, the tree consists of 
  13978. one node that is the result of the expression. 
  13979.  
  13980. Note that the code does not respect precedence of "/" and "*" over "+" and "-". 
  13981.  
  13982.    // nary.C  -  An example of using an n-ary tree
  13983.    #include <itree.h>
  13984.    #include <istring.hpp>
  13985.    #include <iostream.h>
  13986.  
  13987.    ////////////////////////////////////////////////////////////
  13988.    // The tree for this expression is as follows:            //
  13989.    //                                                        //
  13990.    //                              /                         //
  13991.    //                     *                -                 //
  13992.    //                +         +      7         5            //
  13993.    //              8   2     2   4                           //
  13994.    ////////////////////////////////////////////////////////////
  13995.  
  13996.    typedef ITree <IString, 2> BinaryTree;
  13997.  
  13998.    IBoolean printNode(IString const& node, void* dummy) {
  13999.    // Prints one node of an n-ary tree
  14000.       cout << node << "|";
  14001.       return  True;
  14002.     }
  14003.  
  14004.    void prefixedNotation(BinaryTree const& naryTree) {
  14005.    // Prints an n-ary tree in prefixed notation
  14006.       naryTree.allElementsDo(printNode , IPreorder);
  14007.       cout << endl;
  14008.     }
  14009.  
  14010.  
  14011.    void identifyChildren  (IString &child1,
  14012.                            IString &child2,
  14013.                            BinaryTree &binTree,
  14014.                            ITreeCursor &binTreeCursor) {
  14015.    // Identifies the children of a node
  14016.  
  14017.      binTree.setToNext(binTreeCursor, IPreorder);
  14018.      child1 = binTree.elementAt(binTreeCursor);
  14019.      binTree.setToNextExistingChild(binTreeCursor);
  14020.      child2 = binTree.elementAt(binTreeCursor);
  14021.      binTree.setToParent(binTreeCursor);
  14022.     }
  14023.  
  14024.  
  14025.    IBoolean isNumber(IString child) {
  14026.    // Checks whether a node contains a number
  14027.      if ((child != '+') &&
  14028.          (child != '-') &&
  14029.          (child != '*') &&
  14030.          (child != '/'))
  14031.         { return True; }
  14032.      else { return False; }
  14033.    }
  14034.  
  14035.  
  14036.    void lookForNextOperator(BinaryTree &binTree,
  14037.                             ITreeCursor &binTreeCursor) {
  14038.    // Looks for the next operator in the tree
  14039.       IBoolean operatorFound = False;
  14040.  
  14041.       do {
  14042.        if (!isNumber(binTree.elementAt(binTreeCursor))) {
  14043.             operatorFound = True;
  14044.           }
  14045.        else {
  14046.             binTree.setToNext(binTreeCursor, IPreorder);
  14047.           }
  14048.       }
  14049.       while (! operatorFound);
  14050.     }
  14051.  
  14052.  
  14053.    void calculateSubtree(double &result, double &operand1,
  14054.                          double &operand2, IString &operatorSign) {
  14055.    // Calculates the result from a subtree in the complete tree
  14056.       switch (*(char*)operatorSign) {
  14057.           case '+':
  14058.              result = operand1+operand2;
  14059.              break;
  14060.           case '-':
  14061.              result = operand1-operand2;
  14062.              break;
  14063.           case '/':
  14064.              result = operand1/operand2;
  14065.              break;
  14066.           case '*':
  14067.              result = operand1*operand2;
  14068.              break;
  14069.         } // end of switch
  14070.     }
  14071.  
  14072.    /************************ main ****************************/
  14073.    int main () {
  14074.      // Construct the tree:
  14075.  
  14076.      BinaryTree  binTree;
  14077.      BinaryTree::Cursor binTreeCursor(binTree);
  14078.      BinaryTree::Cursor binTreeSaveCursor(binTree);
  14079.  
  14080.  
  14081.      binTree.addAsRoot("/");
  14082.      binTree.setToRoot(binTreeCursor);
  14083.      binTree.addAsChild(binTreeCursor, 1, "*");
  14084.      binTree.setToChild(1, binTreeCursor);
  14085.      binTree.addAsChild(binTreeCursor, 1, "+");
  14086.      binTree.setToChild(1, binTreeCursor);
  14087.      binTree.addAsChild(binTreeCursor, 1, "8");
  14088.      binTree.addAsChild(binTreeCursor, 2, "2");
  14089.      binTree.setToParent(binTreeCursor);
  14090.      binTree.addAsChild(binTreeCursor, 2, "+");
  14091.      binTree.setToChild(2, binTreeCursor);
  14092.      binTree.addAsChild(binTreeCursor, 1, "2");
  14093.      binTree.addAsChild(binTreeCursor, 2, "4");
  14094.      binTree.setToRoot(binTreeCursor);
  14095.      binTree.addAsChild(binTreeCursor, 2, "-");
  14096.      binTree.setToChild(2, binTreeCursor);
  14097.      binTree.addAsChild(binTreeCursor, 1, "7");
  14098.      binTree.addAsChild(binTreeCursor, 2, "5");
  14099.  
  14100.      // Print complete tree in prefix notation
  14101.  
  14102.      cout << "Printing the original tree in prefixed notation:"
  14103.           << endl;
  14104.      prefixedNotation(binTree);
  14105.      cout << " " << endl;
  14106.  
  14107.      // Calculate tree
  14108.  
  14109.      double      operand1 = 0;
  14110.      double      operand2 = 0;
  14111.      double      result = 0;
  14112.      INumber     replacePosition;
  14113.      IString     operatorSign, child1, child2;
  14114.  
  14115.      binTree.setToRoot(binTreeCursor);
  14116.      do
  14117.      {
  14118.       lookForNextOperator(binTree, binTreeCursor);
  14119.       operatorSign = binTree.elementAt(binTreeCursor);
  14120.       identifyChildren  (child1, child2, binTree, binTreeCursor);
  14121.       if ((isNumber(child1)) && (isNumber(child2)))
  14122.          {
  14123.            operand1 = child1.asDouble();
  14124.            operand2 = child2.asDouble();
  14125.            calculateSubtree(result, operand1, operand2,
  14126.                             operatorSign);
  14127.            if (binTree.numberOfElements() > 3)
  14128.            {
  14129.            // If tree contains more than three elements, replace
  14130.            // the calculated subtree by its result as follows.
  14131.            // (Save the cursor, because it will become invalidated after
  14132.            // removeSubtree)
  14133.             binTreeSaveCursor = binTreeCursor;
  14134.             binTree.setToParent(binTreeSaveCursor);
  14135.             replacePosition = binTree.position(binTreeCursor);
  14136.             binTree.removeSubtree(binTreeCursor);
  14137.             binTree.addAsChild(binTreeSaveCursor,
  14138.                                replacePosition,
  14139.                                (IString)result);
  14140.            cout << "Tree with calculated subtree replaced: "
  14141.                 << endl;
  14142.            prefixedNotation(binTree);
  14143.            binTree.setToRoot(binTreeCursor);
  14144.            }
  14145.            else
  14146.            {
  14147.            // If tree contains root with two children only, replace
  14148.            // this calculated subtree by its result as follows:
  14149.             binTree.removeAll();
  14150.             binTree.addAsRoot(IString(result));
  14151.             cout << "Now the tree contains the result only:" << endl;
  14152.             prefixedNotation(binTree);
  14153.            }
  14154.          }
  14155.       else
  14156.          {
  14157.          binTree.setToNext(binTreeCursor, IPreorder);
  14158.          }
  14159.      }
  14160.      while (binTree.numberOfElements() > 1);
  14161.  
  14162.      return 0;
  14163.    }
  14164.  
  14165. The program produces the following output: 
  14166.  
  14167. Printing the original tree in prefixed notation:
  14168. /|*|+|8|2|+|2|4|-|7|5|
  14169.  
  14170. Tree with calculated subtree replaced:
  14171. /|*|10|+|2|4|-|7|5|
  14172. Tree with calculated subtree replaced:
  14173. /|*|10|6|-|7|5|
  14174. Tree with calculated subtree replaced:
  14175. /|60|-|7|5|
  14176. Tree with calculated subtree replaced:
  14177. /|60|2|
  14178. Now the tree contains the result only:
  14179. 30|
  14180.  
  14181.  
  14182. ΓòÉΓòÉΓòÉ 5.2.2.5. Tree Functions ΓòÉΓòÉΓòÉ
  14183.  
  14184. This section lists the public member functions of n-ary trees. The following 
  14185. member functions are described: 
  14186.  
  14187. Constructor
  14188. Copy Constructor
  14189. Destructor
  14190. operator=
  14191. addAsChild
  14192. addAsRoot
  14193. allElementsDo (Using a function)
  14194. allElementsDo (Using an iterator)
  14195. allSubtreeElementsDo (Using a function)
  14196. allSubtreeElementsDo (Using an iterator)
  14197. attachAsChild
  14198. attachSubtreeAsChild
  14199. attachAsRoot
  14200. attachSubtreeAsRoot
  14201. copy
  14202. copySubtree
  14203. elementAt
  14204. hasChild
  14205. isEmpty
  14206. isLeaf
  14207. isRoot
  14208. newCursor
  14209. numberOfChildren
  14210. numberOfElements
  14211. numberOfSubtreeElements
  14212. numberOfLeaves
  14213. numberOfSubtreeLeaves
  14214. position
  14215. removeAll
  14216. removeSubtree
  14217. replaceAt
  14218. setToChild
  14219. setToFirst
  14220. setToFirstExistingChild
  14221. setToLast
  14222. setToLastExistingChild
  14223. setToNext
  14224. setToNextExistingChild
  14225. setToParent
  14226. setToPrevious
  14227. setToPreviousExistingChild
  14228. setToRoot
  14229.  
  14230.  
  14231. ΓòÉΓòÉΓòÉ 5.2.2.5.1. Constructor ΓòÉΓòÉΓòÉ
  14232.  
  14233. ITree ( ) ;
  14234.  
  14235. Constructs a tree. The tree is initially empty; that is, it does not contain 
  14236. any nodes. 
  14237.  
  14238.  
  14239. ΓòÉΓòÉΓòÉ 5.2.2.5.2. Copy Constructor ΓòÉΓòÉΓòÉ
  14240.  
  14241. ITree ( ITree <Element, numberOfChildren> const& tree ) ;
  14242.  
  14243. Constructs a tree by copying all elements from the given tree. 
  14244.  
  14245. Exception 
  14246.  
  14247. IOutOfMemory 
  14248.  
  14249.  
  14250. ΓòÉΓòÉΓòÉ 5.2.2.5.3. Destructor ΓòÉΓòÉΓòÉ
  14251.  
  14252. ~ITree ( ) ;
  14253.  
  14254. Removes all elements from this tree. 
  14255.  
  14256. Side Effects 
  14257.  
  14258. All cursors of the tree become undefined. 
  14259.  
  14260.  
  14261. ΓòÉΓòÉΓòÉ 5.2.2.5.4. operator= ΓòÉΓòÉΓòÉ
  14262.  
  14263. ITree <Element, numberOfChildren>& operator= (
  14264.    ITree <Element, numberOfChildren> const& tree ) ;
  14265.  
  14266. Copies all elements of the given tree to this tree. 
  14267.  
  14268. Return Value 
  14269.  
  14270. A reference to this tree. 
  14271.  
  14272. Side Effects 
  14273.  
  14274. All cursors of this tree become undefined. 
  14275.  
  14276. Exception 
  14277.  
  14278. IOutOfMemory 
  14279.  
  14280.  
  14281. ΓòÉΓòÉΓòÉ 5.2.2.5.5. addAsChild ΓòÉΓòÉΓòÉ
  14282.  
  14283. void addAsChild ( ITreeCursor const& cursor,
  14284.    IPosition position, Element const& element ) ;
  14285.  
  14286. Adds the given element as a child with the given position to the node of this 
  14287. tree denoted by the given cursor. 
  14288.  
  14289. Preconditions 
  14290.  
  14291.      The cursor must point to an element of this tree. 
  14292.      (1 <= position <= numberOfChildren()). 
  14293.      The node denoted by the given cursor (of this tree) must not have a child 
  14294.       at the given position. 
  14295.  
  14296.  Exceptions 
  14297.  
  14298.      IOutOfMemory 
  14299.      ICursorInvalidException 
  14300.      IPositionInvalidException 
  14301.      IChildAlreadyExistsException 
  14302.  
  14303.  
  14304. ΓòÉΓòÉΓòÉ 5.2.2.5.6. addAsRoot ΓòÉΓòÉΓòÉ
  14305.  
  14306. void addAsRoot ( Element const& element ) ;
  14307.  
  14308. Adds the given element as root of the tree. 
  14309.  
  14310. Precondition 
  14311.  
  14312. The tree must not have a root; that is, it must be empty. 
  14313.  
  14314. Exceptions 
  14315.  
  14316.      IOutOfMemory 
  14317.      IRootAlreadyExistsException 
  14318.  
  14319.  
  14320. ΓòÉΓòÉΓòÉ 5.2.2.5.7. allElementsDo, allSubtreeElementsDo ΓòÉΓòÉΓòÉ
  14321.  
  14322. IBoolean allElementsDo (
  14323.    IBoolean (*function) (Element&, void*),
  14324.    ITreeIterationOrder iterationOrder,
  14325.    void* additionalArgument = 0 ) ;
  14326.  
  14327. IBoolean allElementsDo (
  14328.    IBoolean (*function) (Element const&, void*),
  14329.    ITreeIterationOrder iterationOrder,
  14330.    void* additionalArgument = 0 ) const;
  14331.  
  14332. IBoolean allSubtreeElementsDo ( ITreeCursor const& cursor,
  14333.    IBoolean (*function) (Element const&, void*),
  14334.    ITreeIterationOrder iterationOrder,
  14335.    void* additionalArgument = 0 ) const;
  14336.  
  14337. IBoolean allSubtreeElementsDo (
  14338.    ITreeCursor const& cursor,
  14339.    IBoolean (*function) (Element&, void*),
  14340.    ITreeIterationOrder iterationOrder,
  14341.    void* additionalArgument = 0 ) ;
  14342.  
  14343. Calls the given function for all elements of the subtree denoted by the given 
  14344. cursor (of this tree) until the given function returns False. The elements are 
  14345. visited in the given iteration order. Additional arguments can be passed to the 
  14346. given function using additionalArgument. The additional argument defaults to 
  14347. zero if no additional argument is given. The allElementsDo() function (without 
  14348. a subtree cursor argument) iterates over all elements of the tree. 
  14349.  
  14350. Note:  The given function must not remove elements from or add elements to the 
  14351. tree. 
  14352.  
  14353. Return Value 
  14354.  
  14355. Returns True if the given function returns True for every element it is applied 
  14356. to. 
  14357.  
  14358. Preconditions 
  14359.  
  14360.      The cursor must belong to this tree. 
  14361.      The cursor must point to an element of this tree. 
  14362.  
  14363.  Exception 
  14364.  
  14365.  ICursorInvalidException 
  14366.  
  14367.  
  14368. ΓòÉΓòÉΓòÉ 5.2.2.5.8. allElementsDo, allSubtreeElementsDo ΓòÉΓòÉΓòÉ
  14369.  
  14370. IBoolean allElementsDo (
  14371.    IIterator <Element>& iterator,
  14372.    ITreeIterationOrder iterationOrder ) ;
  14373.  
  14374. IBoolean allElementsDo (
  14375.    IConstantIterator <Element>& iterator,
  14376.    ITreeIterationOrder iterationOrder ) const;
  14377.  
  14378. IBoolean allSubtreeElementsDo ( ITreeCursor const& cursor,
  14379.    IIterator <Element>& iterator,
  14380.    ITreeIterationOrder iterationOrder ) ;
  14381.  
  14382. IBoolean allSubtreeElementsDo ( ITreeCursor const& cursor,
  14383.    IConstantIterator <Element>& iterator,
  14384.    ITreeIterationOrder iterationOrder ) const;
  14385.  
  14386. Calls the applyTo() function of the given iterator for all elements of the 
  14387. subtree denoted by the given cursor (of this tree) until the applyTo() function 
  14388. returns False. The elements are visited in the given iteration order. The 
  14389. allElementsDo() function (without a subtree cursor argument) iterates over all 
  14390. elements of the tree. 
  14391.  
  14392. Note:  The applyTo() function must not remove elements from or add elements to 
  14393. the tree. 
  14394.  
  14395. Preconditions 
  14396.  
  14397.      The cursor must belong to this tree. 
  14398.      The cursor must point to an element of this tree. 
  14399.  
  14400.  Return Value 
  14401.  
  14402.  Returns True if the applyTo() function returns True for every element it is 
  14403.  applied to. 
  14404.  
  14405.  Exceptions 
  14406.  
  14407.  ICursorInvalidException 
  14408.  
  14409.  
  14410. ΓòÉΓòÉΓòÉ 5.2.2.5.9. attachAsChild, attachSubtreeAsChild ΓòÉΓòÉΓòÉ
  14411.  
  14412. void attachAsChild ( ITreeCursor const& cursor,
  14413.    IPosition position,
  14414.    ITree <Element, numberOfChildren>& tree ) ;
  14415.  
  14416. void attachSubtreeAsChild ( ITreeCursor const& cursor,
  14417.    IPosition position,
  14418.    ITree <Element, numberOfChildren>& tree,
  14419.    ITreeCursor const& subTreeCursor ) ;
  14420.  
  14421. Copies the subtree denoted by the given subtree cursor as a child with the 
  14422. given position of the node (of this tree) denoted by the given cursor. Removes 
  14423. this subtree from the given tree. The attachAsChild() function (without a 
  14424. subtree cursor argument) copies and removes the whole given tree. 
  14425.  
  14426. Be careful when this tree and the given tree are the same. In such cases you 
  14427. must not attach a subtree to one of its own children, because a cyclic tree 
  14428. structure would result. Because attachSubtreeAsChild() removes this subtree 
  14429. from this tree, you will never be able to access either this subtree or the 
  14430. given subtree attached to it.  This practice can also lead to memory not being 
  14431. properly freed. 
  14432.  
  14433. This warning applies to both attachAsChild() and attachSubtreeAsChild(). 
  14434.  
  14435. Note:  These functions are implemented by copying a pointer to the subtree, 
  14436. rather than by copying all elements in the subtree. 
  14437.  
  14438. Preconditions 
  14439.  
  14440.      The cursor must point to an element of this tree. 
  14441.      The subtree cursor must point to an element of the given tree. 
  14442.      (1 <= position <= numberOfChildren()). 
  14443.      The node denoted by the given cursor (of this tree) must not have a child 
  14444.       at the given position. 
  14445.      If this tree and the given tree are the same, a subtree must not be 
  14446.       attached to one of its own children. 
  14447.  
  14448.  Exceptions 
  14449.  
  14450.      ICursorInvalidException 
  14451.      IPositionInvalidException 
  14452.      IChildAlreadyExistsException 
  14453.      ICyclicAttachException 
  14454.  
  14455.  
  14456. ΓòÉΓòÉΓòÉ 5.2.2.5.10. attachAsRoot, attachSubtreeAsRoot ΓòÉΓòÉΓòÉ
  14457.  
  14458. void attachAsRoot (
  14459.    ITree <Element, numberOfChildren>& tree ) ;
  14460.  
  14461. void attachSubtreeAsRoot (
  14462.    ITree <Element, numberOfChildren>& tree,
  14463.    ITreeCursor const& cursor ) ;
  14464.  
  14465. Copies the subtree denoted by the cursor of the given tree to (the root of) 
  14466. this tree, and removes this subtree from the given tree. The attachAsRoot() 
  14467. function (without a cursor argument) copies and removes the whole given tree. 
  14468.  
  14469. Note:  These functions are implemented by copying a pointer to the subtree, 
  14470. rather than by copying all elements in the subtree. 
  14471.  
  14472. Preconditions 
  14473.  
  14474.      The cursor must point to an element of this tree. 
  14475.      The tree must not have a root; that is, it must be empty. 
  14476.  
  14477.  Exceptions 
  14478.  
  14479.      ICursorInvalidException 
  14480.      IRootAlreadyExistsException 
  14481.  
  14482.  
  14483. ΓòÉΓòÉΓòÉ 5.2.2.5.11. copy, copySubtree ΓòÉΓòÉΓòÉ
  14484.  
  14485. void copy (
  14486.    (ITree <Element, numberOfChildren> const& tree ) ;
  14487.  
  14488. void copySubtree (
  14489.    ITree <Element, numberOfChildren> const& tree,
  14490.    ITreeCursor const& cursor ) ;
  14491.  
  14492. Removes all elements from this tree, and copies the subtree denoted by the 
  14493. given cursor of the given tree to (the root of) this tree. The copy function 
  14494. (without a cursor argument) copies the whole given tree. 
  14495.  
  14496. Preconditions 
  14497.  
  14498. The cursor must point to an element of the given tree. 
  14499.  
  14500. Exceptions 
  14501.  
  14502.      IOutOfMemory 
  14503.      ICursorInvalidException 
  14504.  
  14505.  
  14506. ΓòÉΓòÉΓòÉ 5.2.2.5.12. elementAt ΓòÉΓòÉΓòÉ
  14507.  
  14508. Element const& elementAt (
  14509.    ITreeCursor const& cursor ) const;
  14510.  
  14511. Element& elementAt ( ITreeCursor const& cursor ) ;
  14512.  
  14513. Returns a reference to the element pointed to by the given cursor. 
  14514.  
  14515. Precondition 
  14516.  
  14517. The cursor must point to an element of this tree. 
  14518.  
  14519. Exception 
  14520.  
  14521. ICursorInvalidException 
  14522.  
  14523.  
  14524. ΓòÉΓòÉΓòÉ 5.2.2.5.13. hasChild ΓòÉΓòÉΓòÉ
  14525.  
  14526. IBoolean hasChild ( IPosition position,
  14527.    ITreeCursor const& cursor ) const;
  14528.  
  14529. Returns True if the node pointed to by the given cursor has a child at the 
  14530. given position. 
  14531.  
  14532. Preconditions 
  14533.  
  14534.      The cursor must point to an element of this tree. 
  14535.      (1 <= position <= numberOfChildren()) 
  14536.  
  14537.  Exceptions 
  14538.  
  14539.      ICursorInvalidException 
  14540.      IPositionInvalidException 
  14541.  
  14542.  
  14543. ΓòÉΓòÉΓòÉ 5.2.2.5.14. isEmpty ΓòÉΓòÉΓòÉ
  14544.  
  14545. IBoolean isEmpty ( ) const;
  14546.  
  14547. Returns True if the tree is empty. 
  14548.  
  14549.  
  14550. ΓòÉΓòÉΓòÉ 5.2.2.5.15. isLeaf ΓòÉΓòÉΓòÉ
  14551.  
  14552. IBoolean isLeaf ( ITreeCursor const& cursor ) const;
  14553.  
  14554. Returns True if the node pointed to by the given cursor is a leaf node of the 
  14555. tree.  A leaf node is a node with no children. 
  14556.  
  14557. Precondition 
  14558.  
  14559. The cursor must point to an element of this tree. 
  14560.  
  14561. Exception 
  14562.  
  14563. ICursorInvalidException 
  14564.  
  14565.  
  14566. ΓòÉΓòÉΓòÉ 5.2.2.5.16. isRoot ΓòÉΓòÉΓòÉ
  14567.  
  14568. IBoolean isRoot ( ITreeCursor const& cursor ) const;
  14569.  
  14570. Returns True if the node pointed to by the given cursor is the root node of the 
  14571. tree. 
  14572.  
  14573. Precondition 
  14574.  
  14575. The cursor must point to an element of this tree. 
  14576.  
  14577. Exception 
  14578.  
  14579. ICursorInvalidException 
  14580.  
  14581.  
  14582. ΓòÉΓòÉΓòÉ 5.2.2.5.17. newCursor ΓòÉΓòÉΓòÉ
  14583.  
  14584. ITreeCursor* newCursor ( ) const;
  14585.  
  14586. Creates a cursor for the tree. The cursor is initially invalid. 
  14587.  
  14588. Return Value 
  14589.  
  14590. Pointer to the cursor. 
  14591.  
  14592. Exception 
  14593.  
  14594. IOutOfMemory 
  14595.  
  14596.  
  14597. ΓòÉΓòÉΓòÉ 5.2.2.5.18. numberOfChildren ΓòÉΓòÉΓòÉ
  14598.  
  14599. INumber numberOfChildren ( ) const;
  14600.  
  14601. Returns the number of children a node can possibly have. The actual number of 
  14602. children of any node will always be less than or equal to this number. 
  14603.  
  14604.  
  14605. ΓòÉΓòÉΓòÉ 5.2.2.5.19. numberOfElements, numberOfSubtreeElements ΓòÉΓòÉΓòÉ
  14606.  
  14607. INumber numberOfElements ( ) const;
  14608.  
  14609. INumber numberOfSubtreeElements (
  14610.    ITreeCursor const& cursor ) const;
  14611.  
  14612. Returns the number of elements that the subtree denoted by the given cursor 
  14613. contains. The subtree root, inner, and leaf nodes are counted. The 
  14614. numberOfElements() function (without a cursor argument) counts the number of 
  14615. elements in the whole tree. 
  14616.  
  14617. Preconditions 
  14618.  
  14619. The cursor must belong to the tree and must point to an element in the tree. 
  14620.  
  14621. Exception 
  14622.  
  14623. ICursorInvalidException 
  14624.  
  14625.  
  14626. ΓòÉΓòÉΓòÉ 5.2.2.5.20. numberOfLeaves, numberOfSubtreeLeaves ΓòÉΓòÉΓòÉ
  14627.  
  14628. INumber numberOfLeaves ( ) const;
  14629.  
  14630. INumber numberOfSubtreeLeaves (
  14631.    ITreeCursor const& cursor ) const;
  14632.  
  14633. Returns the number of leaf elements that the subtree denoted by the given 
  14634. cursor contains. Leaves are nodes that have no children. The numberOfLeaves() 
  14635. function (without a cursor argument) counts the number of leaves in the whole 
  14636. tree. 
  14637.  
  14638. Preconditions 
  14639.  
  14640. The cursor must belong to the tree and must point to an element in the tree. 
  14641.  
  14642. Exception 
  14643.  
  14644. ICursorInvalidException 
  14645.  
  14646.  
  14647. ΓòÉΓòÉΓòÉ 5.2.2.5.21. position ΓòÉΓòÉΓòÉ
  14648.  
  14649. INumber position (
  14650.    ITreeCursor const& cursor ) const;
  14651.  
  14652. Returns the position of the node pointed to by the given cursor as a child with 
  14653. respect to its parent node. The position of the root node is 1. 
  14654.  
  14655. Precondition 
  14656.  
  14657. The cursor must point to an element of this tree. 
  14658.  
  14659. Exception 
  14660.  
  14661. ICursorInvalidException 
  14662.  
  14663.  
  14664. ΓòÉΓòÉΓòÉ 5.2.2.5.22. removeAll, removeSubtree ΓòÉΓòÉΓòÉ
  14665.  
  14666. void removeAll ( ) ;
  14667.  
  14668. void removeSubtree ( ITreeCursor const& cursor ) ;
  14669.  
  14670. Removes the subtree denoted by the given cursor (of this tree). The removeAll() 
  14671. function (without a cursor argument) removes all elements from this tree. 
  14672.  
  14673. Precondition 
  14674.  
  14675. The cursor must point to an element of this tree. 
  14676.  
  14677. Side Effects 
  14678.  
  14679. For removeSubtree(), the given cursor is invalidated after removal. 
  14680.  
  14681. Exception 
  14682.  
  14683. ICursorInvalidException 
  14684.  
  14685.  
  14686. ΓòÉΓòÉΓòÉ 5.2.2.5.23. replaceAt ΓòÉΓòÉΓòÉ
  14687.  
  14688. void replaceAt ( ITreeCursor const& cursor,
  14689.    Element const& element ) ;
  14690.  
  14691. Replaces the element pointed to by the cursor with the given element. 
  14692.  
  14693. Precondition 
  14694.  
  14695. The cursor must point to an element of this tree. 
  14696.  
  14697. Exception 
  14698.  
  14699. ICursorInvalidException 
  14700.  
  14701.  
  14702. ΓòÉΓòÉΓòÉ 5.2.2.5.24. setToChild ΓòÉΓòÉΓòÉ
  14703.  
  14704. IBoolean setToChild ( IPosition position,
  14705.    ITreeCursor& cursor ) const;
  14706.  
  14707. Sets the cursor to the child with the given position of the node denoted by the 
  14708. given cursor (of this tree). Invalidates the cursor if this child does not 
  14709. exist. 
  14710.  
  14711. Preconditions 
  14712.  
  14713.      The cursor must point to an element of this tree. 
  14714.      (1 <= position <= numberOfChildren()). 
  14715.  
  14716.  Return Value 
  14717.  
  14718.  Returns True if the child exists. 
  14719.  
  14720.  Exceptions 
  14721.  
  14722.      ICursorInvalidException 
  14723.      IPositionInvalidException 
  14724.  
  14725.  
  14726. ΓòÉΓòÉΓòÉ 5.2.2.5.25. setToFirst ΓòÉΓòÉΓòÉ
  14727.  
  14728. IBoolean setToFirst ( ITreeCursor& cursor,
  14729.    ITreeIterationOrder iterationOrder ) const;
  14730.  
  14731. Sets the cursor to the first node in the given iteration order. Invalidates the 
  14732. cursor if the tree is empty. 
  14733.  
  14734. Precondition 
  14735.  
  14736. The cursor must belong to this tree. 
  14737.  
  14738. Return Value 
  14739.  
  14740. Returns True if the tree is not empty. 
  14741.  
  14742. Exception 
  14743.  
  14744. ICursorInvalidException 
  14745.  
  14746.  
  14747. ΓòÉΓòÉΓòÉ 5.2.2.5.26. setToFirstExistingChild ΓòÉΓòÉΓòÉ
  14748.  
  14749. IBoolean setToFirstExistingChild (
  14750.    ITreeCursor& cursor ) const;
  14751.  
  14752. Sets the cursor to the first child of the node denoted by the given cursor (of 
  14753. this tree). Invalidates the cursor if the node has no child.  A node with no 
  14754. child is a leaf node of the tree. 
  14755.  
  14756. Preconditions 
  14757.  
  14758. The cursor must point to an element of this tree. 
  14759.  
  14760. Return Value 
  14761.  
  14762. Returns True if the node has a child. 
  14763.  
  14764. Exception 
  14765.  
  14766. ICursorInvalidException 
  14767.  
  14768.  
  14769. ΓòÉΓòÉΓòÉ 5.2.2.5.27. setToLast ΓòÉΓòÉΓòÉ
  14770.  
  14771. IBoolean setToLast ( ITreeCursor& cursor,
  14772.    ITreeIterationOrder iterationOrder ) const;
  14773.  
  14774. Sets the cursor to the last node in the given iteration order. Invalidates the 
  14775. cursor if the tree is empty. 
  14776.  
  14777. Precondition 
  14778.  
  14779. The cursor must belong to this tree. 
  14780.  
  14781. Return Value 
  14782.  
  14783. Returns True if the tree is not empty. 
  14784.  
  14785. Exception 
  14786.  
  14787. ICursorInvalidException 
  14788.  
  14789.  
  14790. ΓòÉΓòÉΓòÉ 5.2.2.5.28. setToLastExistingChild ΓòÉΓòÉΓòÉ
  14791.  
  14792. IBoolean setToLastExistingChild (
  14793.    ITreeCursor& cursor ) const;
  14794.  
  14795. Sets the cursor to the last child of the node denoted by the given cursor (of 
  14796. this tree). Invalidates the cursor if the node has no child.  A node with no 
  14797. child is a leaf node of the tree. 
  14798.  
  14799. Precondition 
  14800.  
  14801. The cursor must point to an element of this tree. 
  14802.  
  14803. Return Value 
  14804.  
  14805. Returns True if the node has a child. 
  14806.  
  14807. Exception 
  14808.  
  14809. ICursorInvalidException 
  14810.  
  14811.  
  14812. ΓòÉΓòÉΓòÉ 5.2.2.5.29. setToNext ΓòÉΓòÉΓòÉ
  14813.  
  14814. IBoolean setToNext ( ITreeCursor& cursor,
  14815.    ITreeIterationOrder iterationOrder ) const;
  14816.  
  14817. Sets the cursor to the next node in the given iteration order. Invalidates the 
  14818. cursor if there is no next node. 
  14819.  
  14820. Precondition 
  14821.  
  14822. The cursor must point to an element of this tree. 
  14823.  
  14824. Return Value 
  14825.  
  14826. Returns True if the given cursor does not point to the last node (in iteration 
  14827. order). 
  14828.  
  14829. Exception 
  14830.  
  14831. ICursorInvalidException 
  14832.  
  14833.  
  14834. ΓòÉΓòÉΓòÉ 5.2.2.5.30. setToNextExistingChild ΓòÉΓòÉΓòÉ
  14835.  
  14836. IBoolean setToNextExistingChild (
  14837.    ITreeCursor& cursor ) const;
  14838.  
  14839. Sets the cursor to the next existing sibling of the node denoted by the given 
  14840. cursor (of this tree). Invalidates the cursor if the node has no next sibling. 
  14841. A node with no next sibling is the last existing child of its parent. 
  14842.  
  14843. Precondition 
  14844.  
  14845. The cursor must point to an element of this tree. 
  14846.  
  14847. Return Value 
  14848.  
  14849. Returns True if the node has a next sibling. 
  14850.  
  14851. Exception 
  14852.  
  14853. ICursorInvalidException 
  14854.  
  14855.  
  14856. ΓòÉΓòÉΓòÉ 5.2.2.5.31. setToParent ΓòÉΓòÉΓòÉ
  14857.  
  14858. IBoolean setToParent ( ITreeCursor& cursor ) const;
  14859.  
  14860. Sets the cursor to the parent of the node denoted by the given cursor (of this 
  14861. tree). Invalidates the cursor if the node has no parent. A node with no parent 
  14862. is the root node of its tree. 
  14863.  
  14864. Precondition 
  14865.  
  14866. The cursor must point to an element of this tree. 
  14867.  
  14868. Return Value 
  14869.  
  14870. Returns True if the node has a parent. 
  14871.  
  14872. Exception 
  14873.  
  14874. ICursorInvalidException 
  14875.  
  14876.  
  14877. ΓòÉΓòÉΓòÉ 5.2.2.5.32. setToPrevious ΓòÉΓòÉΓòÉ
  14878.  
  14879. IBoolean setToPrevious ( ITreeCursor& cursor,
  14880.    ITreeIterationOrder iterationOrder ) const;
  14881.  
  14882. Sets the cursor to the previous node in the given iteration order. Invalidates 
  14883. the cursor if there is no previous node. 
  14884.  
  14885. Precondition 
  14886.  
  14887. The cursor must point to an element of this tree. 
  14888.  
  14889. Return Value 
  14890.  
  14891. Returns True if the given cursor does not point to the first node (in iteration 
  14892. order). 
  14893.  
  14894. Exception 
  14895.  
  14896. ICursorInvalidException 
  14897.  
  14898.  
  14899. ΓòÉΓòÉΓòÉ 5.2.2.5.33. setToPreviousExistingChild ΓòÉΓòÉΓòÉ
  14900.  
  14901. IBoolean setToPreviousExistingChild (
  14902.    ITreeCursor& cursor ) const;
  14903.  
  14904. Sets the cursor to the previous existing sibling of the node denoted by the 
  14905. given cursor (of this tree). Invalidates the cursor if the node has no previous 
  14906. sibling. A node with no previous sibling is the first existing child of its 
  14907. parent. 
  14908.  
  14909. Precondition 
  14910.  
  14911. The cursor must point to an element of this tree. 
  14912.  
  14913. Return Value 
  14914.  
  14915. Returns True if the node has a previous sibling. 
  14916.  
  14917. Exception 
  14918.  
  14919. ICursorInvalidException 
  14920.  
  14921.  
  14922. ΓòÉΓòÉΓòÉ 5.2.2.5.34. setToRoot ΓòÉΓòÉΓòÉ
  14923.  
  14924. IBoolean setToRoot ( ITreeCursor& cursor ) const;
  14925.  
  14926. Sets the cursor to the root node of the tree. Invalidates the cursor if the 
  14927. tree is empty (that is, if no root node exists). 
  14928.  
  14929. Precondition 
  14930.  
  14931. The cursor must belong to this tree. 
  14932.  
  14933. Return Value 
  14934.  
  14935. Returns True if the tree is not empty. 
  14936.  
  14937. Exception 
  14938.  
  14939. ICursorInvalidException 
  14940.  
  14941.  
  14942. ΓòÉΓòÉΓòÉ 5.3. Auxiliary Collection Classes ΓòÉΓòÉΓòÉ
  14943.  
  14944. This section contains the following chapters: 
  14945.  
  14946.  Cursor         Describes the declarations and public member functions for the 
  14947.                 cursor classes. 
  14948.  
  14949.  Tree Cursor    Describes the declarations and public member functions for the 
  14950.                 tree cursor classes. 
  14951.  
  14952.  Iterator and Constant Iterator Classes Describes the declarations and public 
  14953.                 member functions for the classes that define the interface for 
  14954.                 iterator objects. 
  14955.  
  14956.  Pointer Classes Describes the declarations and public member functions for the 
  14957.                 classes that allow you to access collection classes through 
  14958.                 pointers. 
  14959.  
  14960.  
  14961. ΓòÉΓòÉΓòÉ 5.3.1. Cursor ΓòÉΓòÉΓòÉ
  14962.  
  14963. Description 
  14964.  
  14965. Header File 
  14966.  
  14967. Constructors 
  14968.  
  14969. Members 
  14970.  
  14971. To close all the panels in a chapter, double-click on this panel's system menu. 
  14972.  
  14973.  
  14974. ΓòÉΓòÉΓòÉ 5.3.1.1. Class Description - ICursor ΓòÉΓòÉΓòÉ
  14975.  
  14976. Each collection class defines its own nested cursor class. All of these cursor 
  14977. classes are derived from one of the following classes: 
  14978.  
  14979.      IElementCursor 
  14980.      IOrderedCursor 
  14981.  
  14982.  IOrderedCursor is derived from IElementCursor, and IElementCursor is in turn 
  14983.  derived from ICursor. Only cursors of ordered collections are derived from 
  14984.  IOrderedCursor. Cursors from unordered collections are derived from 
  14985.  IElementCursor, and only know the member functions from IElementCursor and 
  14986.  ICursor. 
  14987.  
  14988.  This chapter describes the general member functions of these three cursor 
  14989.  classes as well as the specific member functions provided for specific 
  14990.  collections. Because the cursor classes are all abstract classes, no objects 
  14991.  of type IOrderedCursor, IElementCursor, or ICursor can be declared. You can 
  14992.  obtain cursor objects by using the collection member newCursor(), or by 
  14993.  defining a cursor of a specific collection cursor class. The newCursor() 
  14994.  member creates a cursor of the collection to which it is applied. 
  14995.  
  14996.  The newCursor() member returns a pointer to the newly created cursor object. 
  14997.  
  14998.  Each cursor object is associated with a collection object. A cursor function 
  14999.  merely calls the corresponding function for this collection. For example, 
  15000.  cursor.setToFirst() is the same as collection.setToFirst(cursor), where 
  15001.  collection is the object associated with cursor. 
  15002.  
  15003.  
  15004. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  15005.  
  15006. The cursor classes are declared in icursor.h. Note that individual collection 
  15007. header files already include icursor.h; you do not need to include the file in 
  15008. your programs. 
  15009.  
  15010.  
  15011. ΓòÉΓòÉΓòÉ 5.3.1.2. Members ΓòÉΓòÉΓòÉ
  15012.  
  15013. The following member functions are described: 
  15014.  
  15015.      Constructor 
  15016.      copy 
  15017.      isValid 
  15018.      invalidate 
  15019.      element 
  15020.      operator!= 
  15021.      operator== 
  15022.      setToFirst 
  15023.      setToLast 
  15024.      setToNext 
  15025.      setToPrevious 
  15026.  
  15027.  
  15028. ΓòÉΓòÉΓòÉ 5.3.1.2.1. Constructor ΓòÉΓòÉΓòÉ
  15029.  
  15030. Cursor ( Collection const& collection ) ;
  15031.  
  15032. Constructs the cursor and associates it with the given collection. The cursor 
  15033. is initially invalid.  The name of the constructor is that of the nested cursor 
  15034. class. 
  15035.  
  15036.  
  15037. ΓòÉΓòÉΓòÉ 5.3.1.2.2. copy ΓòÉΓòÉΓòÉ
  15038.  
  15039. void copy (ICursor const& cursor) ;
  15040.  
  15041. Copies the given cursor to this cursor. This cursor now points to where the 
  15042. given cursor points. 
  15043.  
  15044. Precondition 
  15045.  
  15046. The given cursor and this cursor must refer to the same collection type. 
  15047.  
  15048. Note:  This precondition cannot be checked. 
  15049.  
  15050.  
  15051. ΓòÉΓòÉΓòÉ 5.3.1.2.3. isValid ΓòÉΓòÉΓòÉ
  15052.  
  15053. IBoolean isValid ( ) const;
  15054.  
  15055. Returns True if the cursor points to an element of the associated collection. 
  15056.  
  15057.  
  15058. ΓòÉΓòÉΓòÉ 5.3.1.2.4. invalidate ΓòÉΓòÉΓòÉ
  15059.  
  15060. void invalidate ( ) ;
  15061.  
  15062. Invalidates the cursor; that is, it no longer points to an element of the 
  15063. associated collection. 
  15064.  
  15065.  
  15066. ΓòÉΓòÉΓòÉ 5.3.1.2.5. element ΓòÉΓòÉΓòÉ
  15067.  
  15068. Element const& element ( ) const;
  15069.  
  15070. Returns a constant reference to the element of the associated collection to 
  15071. which the cursor points. 
  15072.  
  15073. Precondition 
  15074.  
  15075. The cursor must point to an element of the associated collection. 
  15076.  
  15077. Exception 
  15078.  
  15079. ICursorInvalidException 
  15080.  
  15081.  
  15082. ΓòÉΓòÉΓòÉ 5.3.1.2.6. operator!= ΓòÉΓòÉΓòÉ
  15083.  
  15084. IBoolean operator!= ( Cursor const& cursor ) const;
  15085. IBoolean operator!= ( ICursor const& cursor ) const;
  15086.  
  15087. Returns True if the cursor does not point to the same element (of the same 
  15088. collection) as the given cursor. 
  15089.  
  15090.  
  15091. ΓòÉΓòÉΓòÉ 5.3.1.2.7. operator== ΓòÉΓòÉΓòÉ
  15092.  
  15093. IBoolean operator== ( Cursor const& cursor ) const;
  15094. IBoolean operator== ( ICursor const& cursor ) const;
  15095.  
  15096. Returns True if the cursor points to the same element (of the same collection) 
  15097. as the given cursor. 
  15098.  
  15099.  
  15100. ΓòÉΓòÉΓòÉ 5.3.1.2.8. setToFirst ΓòÉΓòÉΓòÉ
  15101.  
  15102. IBoolean setToFirst ( ) ;
  15103.  
  15104. Sets the cursor to the first element of the associated collection in iteration 
  15105. order. Invalidates the cursor if the collection is empty (if no first element 
  15106. exists). 
  15107.  
  15108. Return Value 
  15109.  
  15110. Returns True if the associated collection is not empty. 
  15111.  
  15112.  
  15113. ΓòÉΓòÉΓòÉ 5.3.1.2.9. setToLast ΓòÉΓòÉΓòÉ
  15114.  
  15115. IBoolean setToLast ( ) ;
  15116.  
  15117. Sets the cursor to the last element of the associated collection in iteration 
  15118. order. Invalidates the cursor if the collection is empty (no last element 
  15119. exists). This function is only available for cursors of ordered collections. 
  15120. Returns True if the associated collection was not empty. 
  15121.  
  15122.  
  15123. ΓòÉΓòÉΓòÉ 5.3.1.2.10. setToNext ΓòÉΓòÉΓòÉ
  15124.  
  15125. IBoolean setToNext ( ) ;
  15126.  
  15127. Sets the cursor to the next element in the associated collection in iteration 
  15128. order. Invalidates the cursor if no more elements are left to be visited. 
  15129. Returns True if there was a next element. 
  15130.  
  15131. Precondition 
  15132.  
  15133. The cursor must point to an element of the associated collection. 
  15134.  
  15135. Exception 
  15136.  
  15137. ICursorInvalidException 
  15138.  
  15139.  
  15140. ΓòÉΓòÉΓòÉ 5.3.1.2.11. setToPrevious ΓòÉΓòÉΓòÉ
  15141.  
  15142. IBoolean setToPrevious ( ) ;
  15143.  
  15144. Sets the cursor to the previous element of the associated collection in 
  15145. iteration order. Invalidates the cursor if no such element exists. This 
  15146. function is only available for cursors of ordered collections. 
  15147.  
  15148. Return Value 
  15149.  
  15150. Returns True if a previous element exists. 
  15151.  
  15152. Precondition 
  15153.  
  15154. The cursor must point to an element of the associated collection. 
  15155.  
  15156. Exception 
  15157.  
  15158. ICursorInvalidException 
  15159.  
  15160.  
  15161. ΓòÉΓòÉΓòÉ 5.3.2. Tree Cursor ΓòÉΓòÉΓòÉ
  15162.  
  15163. Description 
  15164.  
  15165. Header File 
  15166.  
  15167. Members 
  15168.  
  15169. To close all the panels in a chapter, double-click on this panel's system menu. 
  15170.  
  15171.  
  15172. ΓòÉΓòÉΓòÉ 5.3.2.1. Class Description - ITreeCursor ΓòÉΓòÉΓòÉ
  15173.  
  15174. For n-ary trees, cursors are used to point to nodes in the tree. Unlike cursors 
  15175. of flat collections, tree cursors stay defined when elements are added to the 
  15176. tree, or when elements other than the one pointed to are removed.  Cursors are 
  15177. used in operations to access the element information stored in a node.  They 
  15178. are also used to designate a subtree of the tree, namely the subtree whose root 
  15179. node the cursor points to. 
  15180.  
  15181. As for flat collections, a distinction is made between the abstract base class 
  15182. ITreeCursor, and cursor classes local to the tree classes themselves.  The 
  15183. local, or nested, cursor classes are derived from the abstract base class. 
  15184.  
  15185.  
  15186. ΓòÉΓòÉΓòÉ <hidden> Header Files ΓòÉΓòÉΓòÉ
  15187.  
  15188. The declarations for ITreeCursor can be found in itcursor.h. 
  15189.  
  15190.  
  15191. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  15192.  
  15193. Tree Cursor defines the following member functions: 
  15194.  
  15195.      Constructor 
  15196.      operator!= 
  15197.      operator== 
  15198.      element 
  15199.      isValid 
  15200.      invalidate 
  15201.      setToChild 
  15202.      setToFirstExistingChild 
  15203.      setToLastExistingChild 
  15204.      setToNextExistingChild 
  15205.      setToParent 
  15206.      setToPreviousExistingChild 
  15207.      setToRoot 
  15208.  
  15209.  
  15210. ΓòÉΓòÉΓòÉ 5.3.2.2. Constructor ΓòÉΓòÉΓòÉ
  15211.  
  15212. Cursor ( Tree const& tree ) ;
  15213.  
  15214. Constructs the cursor and associates it with the given tree. The cursor is 
  15215. initially invalid. 
  15216.  
  15217.  
  15218. ΓòÉΓòÉΓòÉ 5.3.2.3. operator!= ΓòÉΓòÉΓòÉ
  15219.  
  15220. IBoolean operator!= ( Cursor const& cursor ) ;
  15221.  
  15222. Returns True if the cursor does not point to the same node of the same tree as 
  15223. the given cursor. 
  15224.  
  15225.  
  15226. ΓòÉΓòÉΓòÉ 5.3.2.4. operator== ΓòÉΓòÉΓòÉ
  15227.  
  15228. IBoolean operator== ( Cursor const& cursor ) ;
  15229.  
  15230. Returns True if the cursor points to the same node of the same tree as the 
  15231. given cursor. 
  15232.  
  15233.  
  15234. ΓòÉΓòÉΓòÉ 5.3.2.5. element ΓòÉΓòÉΓòÉ
  15235.  
  15236. Element const& element ( ) ;
  15237.  
  15238. Returns a reference to the element of the associated tree to which the cursor 
  15239. points. 
  15240.  
  15241. Preconditions 
  15242.  
  15243. The cursor must point to a node of the associated tree. 
  15244.  
  15245. Exception 
  15246.  
  15247. ICursorInvalidException 
  15248.  
  15249.  
  15250. ΓòÉΓòÉΓòÉ 5.3.2.6. isValid ΓòÉΓòÉΓòÉ
  15251.  
  15252. IBoolean isValid ( ) ;
  15253.  
  15254. Returns True if the cursor points to a node of the associated tree. 
  15255.  
  15256.  
  15257. ΓòÉΓòÉΓòÉ 5.3.2.7. invalidate ΓòÉΓòÉΓòÉ
  15258.  
  15259. void invalidate ( ) ;
  15260.  
  15261. Invalidates the cursor so that it no longer points to a node of the associated 
  15262. tree. 
  15263.  
  15264.  
  15265. ΓòÉΓòÉΓòÉ 5.3.2.8. setToChild ΓòÉΓòÉΓòÉ
  15266.  
  15267. IBoolean setToChild ( IPosition position ) ;
  15268.  
  15269. Sets the cursor to the child node with the given position. If the child does 
  15270. not exist, the cursor is invalidated. If the child at the given position 
  15271. exists, setToChild() returns True. 
  15272.  
  15273. Preconditions 
  15274.  
  15275.      (1 <= position <= numberOfChildren). 
  15276.      The cursor must point to a node of the associated tree. 
  15277.  
  15278.  Exceptions 
  15279.  
  15280.      IPositionInvalidException 
  15281.  
  15282.      ICursorInvalidException 
  15283.  
  15284.  
  15285. ΓòÉΓòÉΓòÉ 5.3.2.9. setToFirstExistingChild ΓòÉΓòÉΓòÉ
  15286.  
  15287. IBoolean setToFirstExistingChild ( ) ;
  15288.  
  15289. Sets the cursor to the first existing child of the associated tree. If the node 
  15290. pointed to by the cursor has no children (that is, if the node is a leaf) the 
  15291. cursor is invalidated.  If the node pointed to by the cursor has a child, 
  15292. setToFirstExistingChild() returns True. 
  15293.  
  15294.  
  15295. ΓòÉΓòÉΓòÉ 5.3.2.10. setToLastExistingChild ΓòÉΓòÉΓòÉ
  15296.  
  15297. IBoolean setToLastExistingChild ( ) ;
  15298.  
  15299. Sets the cursor to the last existing child of the associated tree. If the node 
  15300. pointed to by the cursor has no children (that is, if the node is a leaf) the 
  15301. cursor is invalidated. If the node pointed to by the cursor has a child, 
  15302. setToLastExistingChild() returns True. 
  15303.  
  15304.  
  15305. ΓòÉΓòÉΓòÉ 5.3.2.11. setToNextExistingChild ΓòÉΓòÉΓòÉ
  15306.  
  15307. IBoolean setToNextExistingChild ( ) ;
  15308.  
  15309. Sets the cursor to the next existing sibling of the node to which the cursor 
  15310. points. If the node to which the cursor points is the last child of its parent, 
  15311. no next existing child exists and the cursor is invalidated. 
  15312.  
  15313. Return Value 
  15314.  
  15315. Returns False if a next existing child exists. 
  15316.  
  15317. Preconditions 
  15318.  
  15319. The cursor must point to a node of the associated tree. 
  15320.  
  15321. Exception 
  15322.  
  15323. ICursorInvalidException 
  15324.  
  15325.  
  15326. ΓòÉΓòÉΓòÉ 5.3.2.12. setToParent ΓòÉΓòÉΓòÉ
  15327.  
  15328. IBoolean setToParent ( ) ;
  15329.  
  15330. Sets the cursor to the parent of the node pointed to by the cursor. If the 
  15331. cursor points to the root, the node has no parent, and the cursor is 
  15332. invalidated. 
  15333.  
  15334. Return Value 
  15335.  
  15336. Returns True if the node has a parent. 
  15337.  
  15338. Preconditions 
  15339.  
  15340. The cursor must point to a node of the associated tree. 
  15341.  
  15342. Exception 
  15343.  
  15344. ICursorInvalidException 
  15345.  
  15346.  
  15347. ΓòÉΓòÉΓòÉ 5.3.2.13. setToPreviousExistingChild ΓòÉΓòÉΓòÉ
  15348.  
  15349. IBoolean setToPreviousExistingChild ( ) ;
  15350.  
  15351. Sets the cursor to the previous existing sibling of the node to which the 
  15352. cursor points. If the node to which the cursor points is the last child of its 
  15353. parent, no more children exist and the cursor is invalidated. 
  15354.  
  15355. Return Value 
  15356.  
  15357. Returns True if there was a previous child. 
  15358.  
  15359. Precondition 
  15360.  
  15361. The cursor must point to a node of the associated tree. 
  15362.  
  15363. Exception 
  15364.  
  15365. ICursorInvalidException 
  15366.  
  15367.  
  15368. ΓòÉΓòÉΓòÉ 5.3.2.14. setToRoot ΓòÉΓòÉΓòÉ
  15369.  
  15370. IBoolean setToRoot ( ) ;
  15371.  
  15372. Sets the cursor to the root of the associated tree. If the collection is empty 
  15373. (if no root element exists), the cursor is invalidated.  Otherwise, setToRoot() 
  15374. returns True. 
  15375.  
  15376.  
  15377. ΓòÉΓòÉΓòÉ 5.3.3. Iterator and Constant Iterator Classes ΓòÉΓòÉΓòÉ
  15378.  
  15379. Description 
  15380.  
  15381. Derivation 
  15382.  
  15383. Header File 
  15384.  
  15385. Members 
  15386.  
  15387. To close all the panels in a chapter, double-click on this panel's system menu. 
  15388.  
  15389.  
  15390. ΓòÉΓòÉΓòÉ 5.3.3.1. Class Description - IIterator ΓòÉΓòÉΓòÉ
  15391.  
  15392. The classes IIterator and IConstantIterator define the interface for iterator 
  15393. objects. The redefinition of the function applyTo() defines the actions that 
  15394. are performed with the version of allElementsDo() that takes an iterator 
  15395. argument. (See allElementsDo for more information on this function.) Iteration 
  15396. stops when applyTo() returns False. 
  15397.  
  15398.  
  15399. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  15400.  
  15401. These classes do not derive from any other class. 
  15402.  
  15403.  
  15404. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  15405.  
  15406. iiter.h 
  15407.  
  15408.  
  15409. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  15410.  
  15411. These classes define only one function, as a virtual function. 
  15412.  
  15413.      applyTo() 
  15414.  
  15415.  
  15416. ΓòÉΓòÉΓòÉ 5.3.3.2. applyTo ΓòÉΓòÉΓòÉ
  15417.  
  15418. virtual IBoolean applyTo (Element const& element) = 0;
  15419.  
  15420. This function applies a series of specified statements or a function to all 
  15421. elements of a collection for which you use the iterator.  For example, 
  15422. myCollection.allElementsDo(myIterator); causes the code in the applyTo() 
  15423. function that you code for your iterator object myIterator to be applied to all 
  15424. elements of the collection myCollection. 
  15425.  
  15426. For an example on how to use iterators, see Iteration Using Iterators in the 
  15427. Open Class Library User's Guide. 
  15428.  
  15429.  
  15430. ΓòÉΓòÉΓòÉ 5.3.4. Pointer Classes ΓòÉΓòÉΓòÉ
  15431.  
  15432. Description 
  15433.  
  15434. Header File 
  15435.  
  15436. Members 
  15437.  
  15438. Examples 
  15439.  
  15440. To close all the panels in a chapter, double-click on this panel's system menu. 
  15441.  
  15442.  
  15443. ΓòÉΓòÉΓòÉ 5.3.4.1. Class Description - Pointer Classes ΓòÉΓòÉΓòÉ
  15444.  
  15445. The Collection Class Library defines five pointer classes: 
  15446.  
  15447.      IAutoPointer 
  15448.      IAutoElemPointer 
  15449.      IElemPointer 
  15450.      IMngPointer 
  15451.      IMngElemPointer 
  15452.  
  15453.  You can select from these classes depending on your requirements: 
  15454.  
  15455.      Pointers from classes named I...ElemPointer (also called element 
  15456.       pointers) route the operations on the pointers to the referenced 
  15457.       elements. 
  15458.      Pointers from classes named IAuto...Pointer (also called automatic 
  15459.       pointers) delete the elements they reference when the pointers are 
  15460.       destructed. No reference count is kept. 
  15461.      Pointers from classes named IMng...Pointer (also called managed pointers) 
  15462.       keep a reference count for each referenced element. When the last managed 
  15463.       pointer to the element is destructed, the element is automatically 
  15464.       deleted. 
  15465.  
  15466.  For further information on the characteristics of these pointer types and how 
  15467.  to use them, see Using Pointer Classes. 
  15468.  
  15469.  
  15470. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  15471.  
  15472. The pointer classes are declared in the header file iptr.h. 
  15473.  
  15474.  
  15475. ΓòÉΓòÉΓòÉ 5.3.4.2. Members ΓòÉΓòÉΓòÉ
  15476.  
  15477. The pointer classes define constructors, a destructor, and four operators. An 
  15478. equality test operator, although not actually a member of the pointer classes, 
  15479. is also available. 
  15480.  
  15481.      Constructors 
  15482.      Constructors from a Given C++ Pointer 
  15483.      Copy Constructors from a Given Collection Class Pointer 
  15484.      Destructors 
  15485.      operator* 
  15486.      Conversion operator 
  15487.      operator-> 
  15488.      operator= 
  15489.      operator== 
  15490.  
  15491.  
  15492. ΓòÉΓòÉΓòÉ 5.3.4.2.1. Constructors ΓòÉΓòÉΓòÉ
  15493.  
  15494. IAutoPointer ();
  15495. IElemPointer ();
  15496. IMngPointer ();
  15497.  
  15498. Constructs a pointer of the indicated type and initializes it with NULL. 
  15499.  
  15500.  
  15501. ΓòÉΓòÉΓòÉ 5.3.4.2.2. Constructors from a Given C++ Pointer ΓòÉΓòÉΓòÉ
  15502.  
  15503. IAutoPointer (Element *ptr, IExplicitInit)
  15504. IAutoElemPointer (Element *ptr, IExplicitInit)
  15505. IElemPointer (Element *ptr, IExplicitInit = IINIT)
  15506. IMngPointer (Element *ptr, IExplicitInit)
  15507. IMngElemPointer (Element *ptr, IExplicitInit)
  15508. Constructs a pointer object of the indicated type from a given C++ pointer. For 
  15509. managed pointers, the reference count of the referenced element is set to 1. 
  15510.  
  15511.  
  15512. ΓòÉΓòÉΓòÉ 5.3.4.2.3. Copy Constructors from a Given Collection Class Pointer ΓòÉΓòÉΓòÉ
  15513.  
  15514. IAutoPointer (IAutoPointer < Element > const& ptr)
  15515. IMngPointer (IMngPointer < Element > const& ptr)
  15516.  
  15517. Constructs a new pointer and initializes it with the given pointer. For 
  15518. automatic pointers, the given pointer is set to NULL. For managed pointers, the 
  15519. reference count of the referenced element is incremented by 1. 
  15520.  
  15521.  
  15522. ΓòÉΓòÉΓòÉ 5.3.4.2.4. Destructors ΓòÉΓòÉΓòÉ
  15523.  
  15524. ~IAutoPointer ()
  15525. ~IAutoElemPointer ()
  15526.  
  15527. Deletes the object referenced to by the automatic pointer. 
  15528.  
  15529. ~IMngPointer ()
  15530. ~IMngElemPointer ()
  15531.  
  15532. Destructs the pointer and decrements the reference count of the referenced 
  15533. element. If the reference count is 0, the referenced element is deleted. 
  15534.  
  15535.  
  15536. ΓòÉΓòÉΓòÉ 5.3.4.2.5. operator* ΓòÉΓòÉΓòÉ
  15537.  
  15538. Element& operator * () const;
  15539.  
  15540. Returns a reference to the object to which the pointer refers. 
  15541.  
  15542.  
  15543. ΓòÉΓòÉΓòÉ 5.3.4.2.6. Conversion operator ΓòÉΓòÉΓòÉ
  15544.  
  15545. operator Element* () const
  15546.  
  15547. Implicitly convert this pointer to a C++ pointer. 
  15548.  
  15549.  
  15550. ΓòÉΓòÉΓòÉ 5.3.4.2.7. operator-> ΓòÉΓòÉΓòÉ
  15551.  
  15552. Element* operator-> () const
  15553.  
  15554. Returns a C pointer to the object to which the pointer refers. 
  15555.  
  15556.  
  15557. ΓòÉΓòÉΓòÉ 5.3.4.2.8. operator= ΓòÉΓòÉΓòÉ
  15558.  
  15559. void                         operator = (IAutoPointer < Element > const& ptr)
  15560. IMngPointer < Element >&     operator = (IMngPointer < Element > const& ptr)
  15561. IMngElemPointer < Element >& operator = (IMngElemPointer < Element > const& ptr)
  15562.  
  15563. Assigns the given pointer to this pointer. For automatic pointers, the given 
  15564. pointer is set to NULL and the previously referenced element is deleted. For 
  15565. managed pointers, the reference count of the referenced element is incremented 
  15566. and the reference count of the previously referenced element is decremented. 
  15567.  
  15568.  
  15569. ΓòÉΓòÉΓòÉ 5.3.4.2.9. operator== ΓòÉΓòÉΓòÉ
  15570.  
  15571. The pointer classes do not have an operator== explicitly defined for them. 
  15572. However, for equality test you can use the syntax: 
  15573.  
  15574.    pointerVariable1 == pointerVariable2;
  15575.  
  15576. The conversion operator (operator Element*) implicitly converts the objects to 
  15577. C pointers, and then the operator== for C pointers is invoked. 
  15578.  
  15579. Because the operator== is not actually a member of the class, you cannot write 
  15580. an equality test like the following: 
  15581.  
  15582.    if (pointerVariable1.operator==(pointerVariable2)) {/* ... */}
  15583.  
  15584.  
  15585. ΓòÉΓòÉΓòÉ 5.3.4.3. Coding Example for Managed Element Pointer ΓòÉΓòÉΓòÉ
  15586.  
  15587. The following sample allows you to store managed pointers for various graphical 
  15588. objects into a key sorted set. The graphical objects, namely lines, curves, and 
  15589. circles, inherit from a base class Graphics. Using these pointers, you can draw 
  15590. the various shapes from the collection. 
  15591.  
  15592. // graph.C  - demonstrate how to use Collection Class pointers
  15593.  
  15594. #include <iostream.h>
  15595. #include "graph.h"
  15596. #include "line.h"
  15597. #include "circle.h"
  15598. #include "curve.h"
  15599. #include <iptr.h>
  15600. #include <iksset.h>
  15601.  
  15602. typedef IMngElemPointer <Graphics> MngGraphicsPointer;
  15603. typedef IKeySortedSet <MngGraphicsPointer, int> MngPointerKSet;
  15604.  
  15605. ostream & operator << (ostream & sout,
  15606.                        MngPointerKSet const& mgdPointerKSet) {
  15607.    MngGraphicsPointer drawObject;
  15608.    MngPointerKSet::Cursor
  15609.    gpsCursor(mgdPointerKSet);
  15610.  
  15611.    forCursor(gpsCursor) {
  15612.         drawObject = gpsCursor.element();
  15613.  
  15614.         sout << "\n Key is: " <<  drawObject->graphicsKey()
  15615.              << "\n ID is: " <<  drawObject->id() << endl;
  15616.  
  15617.         drawObject->draw();
  15618.      } /* endfor */
  15619.  
  15620.    return sout;
  15621. }
  15622.  
  15623.  int main () {
  15624.      MngPointerKSet graphMngPointerKSet;
  15625.      //   Add curve pointers, circle pointers and line
  15626.      //   pointers to the graphMngPointerKSet.
  15627.  
  15628.       //Creating curve objects and adding pointers to the collections
  15629.       MngGraphicsPointer pcurve1 (new Curve
  15630.        (10, "Curve 1",
  15631.        1.1, 4.3,  2.1, 6.4,  3.1, 9.7,  4.1, 6.5,  5.1, 7.4),
  15632.        IINIT);
  15633.       MngGraphicsPointer pcurve2 (new Curve
  15634.        (20 ,"Curve 2",
  15635.        1.2, 3.9,  2.2, 5.9,  3.2, 8.8,  4.2, 7.5,  5.2, 9.4),
  15636.        IINIT);
  15637.  
  15638.       graphMngPointerKSet.add(pcurve1);
  15639.       graphMngPointerKSet.add(pcurve2);
  15640.  
  15641.       //Creating circle objects and adding pointers to the collections
  15642.  
  15643.       MngGraphicsPointer pcircle1 (new Circle
  15644.        (40 , "Circle 1" , 1.0, 1.0, 1.0), IINIT);
  15645.       MngGraphicsPointer pcircle2 (new Circle
  15646.        (50 , "Circle  2", 2.0, 2.0, 2.0), IINIT);
  15647.  
  15648.       graphMngPointerKSet.add(pcircle1);
  15649.       graphMngPointerKSet.add(pcircle2);
  15650.  
  15651.       //Creating line objects and adding pointers to the collections
  15652.  
  15653.       MngGraphicsPointer pline1 (new Line
  15654.        (70 , "Line 1" , 1.1 , 1.1 , 5.1 , 5.1), IINIT);
  15655.       MngGraphicsPointer pline2 (new Line
  15656.        (80 , "Line 2" , 2.2 , 2.2 , 5.2 , 5.2), IINIT);
  15657.       // if you want to have a normal C-pointer:
  15658.       Line* cPointerToLine = new Line
  15659.        (90 , "Line 3" , 3.3 , 3.3 , 5.3 , 5.3);
  15660.       MngGraphicsPointer pline3 (cPointerToLine, IINIT);
  15661.  
  15662.       graphMngPointerKSet.add(pline1);
  15663.       graphMngPointerKSet.add(pline2);
  15664.       graphMngPointerKSet.add(pline3);
  15665.  
  15666.       cout << "Drawing the shapes from the key set "
  15667.            << "of Managed Pointers: \n"
  15668.            << graphMngPointerKSet << "\n " << endl;
  15669.  
  15670.       graphMngPointerKSet.elementWithKey(70)->draw();
  15671.       cPointerToLine->draw();
  15672.       pline3->draw();
  15673.  
  15674.   // Now we are about to end the program.  The objects referenced
  15675.   // by managed pointers are automatically deleted.  See what
  15676.   // happens in the output of the program.
  15677.   return 0;
  15678.  }
  15679.  
  15680.  
  15681. ΓòÉΓòÉΓòÉ 5.4. Abstract Collection Classes ΓòÉΓòÉΓòÉ
  15682.  
  15683. This part describes the abstract Collection Classes. The following classes are 
  15684. described: 
  15685.  
  15686.      Collection 
  15687.      Equality collection 
  15688.      Equality key collection 
  15689.      Equality key sorted collection 
  15690.      Equality sorted collection 
  15691.      Key collection 
  15692.      Key sorted collection 
  15693.      Ordered collection 
  15694.      Sequential collection 
  15695.      Sorted collection 
  15696.  
  15697.  
  15698. ΓòÉΓòÉΓòÉ 5.4.1. Collection ΓòÉΓòÉΓòÉ
  15699.  
  15700. Description 
  15701.  
  15702. Derivation 
  15703.  
  15704. Variants/Header Files 
  15705.  
  15706. Members 
  15707.  
  15708. To close all the panels in a chapter, double-click on this panel's system menu. 
  15709.  
  15710.  
  15711. ΓòÉΓòÉΓòÉ 5.4.1.1. Class Description - Collection ΓòÉΓòÉΓòÉ
  15712.  
  15713. Collection is the base class for almost all classes defined by the Collection 
  15714. Class Library. Because collection is an abstract class, it cannot be used to 
  15715. create any objects. 
  15716.  
  15717.  
  15718. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  15719.  
  15720. Collection does not have any bases. The following abstract classes are derived 
  15721. from collection: 
  15722.  
  15723.      Key collection 
  15724.      Equality collection 
  15725.      Ordered collection 
  15726.  
  15727.  The concrete class heap is defined by collection. 
  15728.  
  15729.  The Abstract Class Hierarchy shows the relationship of collection to the class 
  15730.  hierarchy. 
  15731.  
  15732.  
  15733. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  15734.  
  15735. Collection is declared in the header file iacllct.h. 
  15736.  
  15737.  
  15738. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  15739.  
  15740. All the member functions of collection are defined as virtual functions and are 
  15741. described in Introduction to Flat Collections. The following member functions 
  15742. are provided for collection: 
  15743.  
  15744.      Destructor 
  15745.      add 
  15746.      addAllFrom 
  15747.      anyElement 
  15748.      compare 
  15749.      Copy Constructor 
  15750.      elementAtPosition 
  15751.      isBounded 
  15752.      isEmpty 
  15753.      isFull 
  15754.      maxNumberOfElements 
  15755.      newCursor 
  15756.      numberOfElements 
  15757.      removeAll 
  15758.      removeAt 
  15759.      replaceAt 
  15760.      setToFirst 
  15761.      setToNext 
  15762.  
  15763.  
  15764. ΓòÉΓòÉΓòÉ 5.4.2. Equality Collection ΓòÉΓòÉΓòÉ
  15765.  
  15766. Description 
  15767.  
  15768. Derivation 
  15769.  
  15770. Variants/Header Files 
  15771.  
  15772. Members 
  15773.  
  15774. To close all the panels in a chapter, double-click on this panel's system menu. 
  15775.  
  15776.  
  15777. ΓòÉΓòÉΓòÉ 5.4.2.1. Class Description - Equality Collection ΓòÉΓòÉΓòÉ
  15778.  
  15779. Because equality collection is an abstract class, it cannot be used to create 
  15780. any objects. The equality collection defines the interfaces for the property of 
  15781. element equality. 
  15782.  
  15783.  
  15784. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  15785.  
  15786. Collection 
  15787.  
  15788.   Equality Collection
  15789.  
  15790. The following abstract classes are derived from equality collection: 
  15791.  
  15792.      Equality key collection 
  15793.      Equality sorted collection 
  15794.  
  15795.  The following concrete classes are defined by equality collection: 
  15796.  
  15797.      Set 
  15798.      Bag 
  15799.      Equality Sequence 
  15800.  
  15801.  The Abstract Class Hierarchy shows the relationship of equality collection to 
  15802.  the class hierarchy. 
  15803.  
  15804.  
  15805. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  15806.  
  15807. The equality collection class is declared in the header file iaequal.h. 
  15808.  
  15809.  
  15810. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  15811.  
  15812. The equality collection class defines the following member functions, described 
  15813. in Introduction to Flat Collections, as virtual functions: 
  15814.  
  15815.      Destructor 
  15816.      contains 
  15817.      containsAllFrom 
  15818.      locate 
  15819.      locateNext 
  15820.      locateOrAdd 
  15821.      numberOfOccurrences 
  15822.      remove 
  15823.      removeAllOccurrences 
  15824.  
  15825.  
  15826. ΓòÉΓòÉΓòÉ 5.4.3. Equality Key Collection ΓòÉΓòÉΓòÉ
  15827.  
  15828. Description 
  15829.  
  15830. Derivation 
  15831.  
  15832. Variants/Header Files 
  15833.  
  15834. Members 
  15835.  
  15836. To close all the panels in a chapter, double-click on this panel's system menu. 
  15837.  
  15838.  
  15839. ΓòÉΓòÉΓòÉ 5.4.3.1. Class Description - Equality Key Collection ΓòÉΓòÉΓòÉ
  15840.  
  15841. Because equality key collection is an abstract class, it cannot be used to 
  15842. create any objects. It defines the interfaces for the following properties: 
  15843.  
  15844.      Element equality 
  15845.      Key equality 
  15846.  
  15847.  
  15848. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  15849.  
  15850.           Collection 
  15851.  
  15852.   Equality Collection      Key Collection
  15853.         Equality Key Collection
  15854.  
  15855. Equality key sorted collection is an abstract class that is derived from 
  15856. equality key collection. The following concrete classes are defined by equality 
  15857. key collection: 
  15858.  
  15859.      Map 
  15860.      Relation 
  15861.  
  15862.  The Abstract Class Hierarchy shows the relationship of equality key collection 
  15863.  to the whole class hierarchy. 
  15864.  
  15865.  
  15866. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  15867.  
  15868. The equality key collection class is declared in the header file iaeqkey.h. 
  15869.  
  15870.  
  15871. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  15872.  
  15873. All the members of equality key sorted collection are inherited from its base 
  15874. classes. 
  15875.  
  15876.  
  15877. ΓòÉΓòÉΓòÉ 5.4.4. Equality Key Sorted Collection ΓòÉΓòÉΓòÉ
  15878.  
  15879. Description 
  15880.  
  15881. Derivation 
  15882.  
  15883. Variants/Header Files 
  15884.  
  15885. Members 
  15886.  
  15887. To close all the panels in a chapter, double-click on this panel's system menu. 
  15888.  
  15889.  
  15890. ΓòÉΓòÉΓòÉ 5.4.4.1. Class Description - Equality Key Sorted Collection ΓòÉΓòÉΓòÉ
  15891.  
  15892. Equality key sorted collection is an abstract class that defines the interfaces 
  15893. for the following properties: 
  15894.  
  15895.      Element equality 
  15896.      Key equality 
  15897.      Sorted elements 
  15898.  
  15899.  Because equality key sorted collection is an abstract class, it cannot be used 
  15900.  to create any objects. 
  15901.  
  15902.  
  15903. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  15904.  
  15905. Equality key sorted collection is derived from the following three abstract 
  15906. classes: 
  15907.  
  15908.      Key sorted collection 
  15909.      Equality sorted collection 
  15910.      Equality key sorted collection 
  15911.  
  15912.  For information on the bases of these classes, see the figure "Abstract Class 
  15913.  Hierarchy" in section Abstract Classes. 
  15914.  
  15915.  The following concrete classes are defined by equality key sorted collection: 
  15916.  
  15917.      Sorted map 
  15918.      Sorted relation 
  15919.  
  15920.  The Abstract Class Hierarchy shows the relationship of equality key sorted 
  15921.  collection to the class hierarchy. 
  15922.  
  15923.  
  15924. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  15925.  
  15926. The equality key sorted collection class is declared in the header file 
  15927. iaeqksrt.h. 
  15928.  
  15929.  
  15930. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  15931.  
  15932. All the members of equality key sorted collection are inherited from its base 
  15933. classes. 
  15934.  
  15935.  
  15936. ΓòÉΓòÉΓòÉ 5.4.5. Equality Sorted Collection ΓòÉΓòÉΓòÉ
  15937.  
  15938. Description 
  15939.  
  15940. Derivation 
  15941.  
  15942. Variants/Header Files 
  15943.  
  15944. Members 
  15945.  
  15946. To close all the panels in a chapter, double-click on this panel's system menu. 
  15947.  
  15948.  
  15949. ΓòÉΓòÉΓòÉ 5.4.5.1. Class Description - Equality Sorted Collection ΓòÉΓòÉΓòÉ
  15950.  
  15951. Because equality sorted collection is an abstract class, it cannot be used to 
  15952. create any objects. It defines the interfaces for the following properties: 
  15953.  
  15954.      Element equality 
  15955.      Sorted elements 
  15956.  
  15957.  
  15958. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  15959.  
  15960.             Collection 
  15961.  
  15962.                   Ordered Collection
  15963.   Equality Collection      Sorted Collection
  15964.        Equality Sorted Collection
  15965.  
  15966. Equality key sorted collection is an abstract class that is derived from 
  15967. equality sorted collection. The following concrete classes are defined by 
  15968. equality sorted collection: 
  15969.  
  15970.      Sorted set 
  15971.      Sorted bag 
  15972.  
  15973.  The Abstract Class Hierarchy shows the relationship of equality sorted 
  15974.  collection to the class hierarchy. 
  15975.  
  15976.  
  15977. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  15978.  
  15979. The equality sorted collection class is declared in the header file iaeqsrt.h. 
  15980.  
  15981.  
  15982. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  15983.  
  15984. All members of equality sorted collection are inherited from its base classes. 
  15985.  
  15986.  
  15987. ΓòÉΓòÉΓòÉ 5.4.6. Key Collection ΓòÉΓòÉΓòÉ
  15988.  
  15989. Description 
  15990.  
  15991. Derivation 
  15992.  
  15993. Variants/Header Files 
  15994.  
  15995. Members 
  15996.  
  15997. To close all the panels in a chapter, double-click on this panel's system menu. 
  15998.  
  15999.  
  16000. ΓòÉΓòÉΓòÉ 5.4.6.1. Class Description - Key Collection ΓòÉΓòÉΓòÉ
  16001.  
  16002. Because key collection is an abstract class, it cannot be used to create any 
  16003. objects. The key collection inherits from collection and defines the interfaces 
  16004. for the key property. 
  16005.  
  16006.  
  16007. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  16008.  
  16009. Collection 
  16010.  
  16011.   Key Collection
  16012.  
  16013. The following abstract classes are derived from key collection: 
  16014.  
  16015.      Equality key collection 
  16016.      Key sorted collection 
  16017.  
  16018.  The following concrete classes are defined by key collection: 
  16019.  
  16020.      Key set 
  16021.      Key bag 
  16022.  
  16023.  The Abstract Class Hierarchy shows the relationship of key collection to the 
  16024.  class hierarchy. 
  16025.  
  16026.  
  16027. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  16028.  
  16029. The key collection class is declared in the header file iakey.h. 
  16030.  
  16031.  
  16032. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  16033.  
  16034. The key collection class defines the following member functions, described in 
  16035. Introduction to Flat Collections, as virtual functions: 
  16036.  
  16037.      Destructor 
  16038.      addOrReplaceElementWithKey 
  16039.      containsAllKeysFrom 
  16040.      containsElementWithKey 
  16041.      elementWithKey 
  16042.      key 
  16043.      locateElementWithKey 
  16044.      locateNextElementWithKey 
  16045.      locateOrAddElementWithKey 
  16046.      numberOfDifferentKeys 
  16047.      numberOfElementsWithKey 
  16048.      removeAllElementsWithKey 
  16049.      removeElementWithKey 
  16050.      replaceElementWithKey 
  16051.      setToNextWithDifferentKey 
  16052.  
  16053.  
  16054. ΓòÉΓòÉΓòÉ 5.4.7. Key Sorted Collection ΓòÉΓòÉΓòÉ
  16055.  
  16056. Description 
  16057.  
  16058. Derivation 
  16059.  
  16060. Variants/Header Files 
  16061.  
  16062. Members 
  16063.  
  16064. To close all the panels in a chapter, double-click on this panel's system menu. 
  16065.  
  16066.  
  16067. ΓòÉΓòÉΓòÉ 5.4.7.1. Class Description - Key Sorted Collection ΓòÉΓòÉΓòÉ
  16068.  
  16069. Because key sorted collection is an abstract class, it cannot be used to create 
  16070. any objects. The key sorted collection inherits from sorted collection and key 
  16071. collection. It defines the interfaces for the following properties: 
  16072.  
  16073.      Key equality 
  16074.      Sorted elements 
  16075.  
  16076.  
  16077. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  16078.  
  16079.           Collection 
  16080.  
  16081.               Ordered Collection
  16082.   Key Collection    Sorted Collection
  16083.        Key Sorted Collection
  16084.  
  16085. The equality key sorted collection is an abstract class that is derived from 
  16086. key sorted collection. The following concrete classes are defined by key sorted 
  16087. collection: 
  16088.  
  16089.      Key sorted set 
  16090.      Key sorted bag 
  16091.  
  16092.  The Abstract Class Hierarchy shows the relationship of key sorted collection 
  16093.  to the class hierarchy. 
  16094.  
  16095.  
  16096. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  16097.  
  16098. The key sorted collection class is declared in the header file iaksrt.h. 
  16099.  
  16100.  
  16101. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  16102.  
  16103. The key sorted collection class inherits all member functions from its base 
  16104. classes. 
  16105.  
  16106.  
  16107. ΓòÉΓòÉΓòÉ 5.4.8. Ordered Collection ΓòÉΓòÉΓòÉ
  16108.  
  16109. Description 
  16110.  
  16111. Derivation 
  16112.  
  16113. Variants/Header Files 
  16114.  
  16115. Members 
  16116.  
  16117. To close all the panels in a chapter, double-click on this panel's system menu. 
  16118.  
  16119.  
  16120. ΓòÉΓòÉΓòÉ 5.4.8.1. Class Description - Ordered Collection ΓòÉΓòÉΓòÉ
  16121.  
  16122. Because ordered collection is an abstract class, it cannot be used to create 
  16123. any objects. The ordered collection defines the interfaces for the property of 
  16124. ordered elements. 
  16125.  
  16126.  
  16127. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  16128.  
  16129. Collection 
  16130.  
  16131.   Ordered Collection
  16132.  
  16133. The following abstract classes are derived from ordered collection: 
  16134.  
  16135.      Sorted collection 
  16136.      Sequential collection 
  16137.  
  16138.  The Abstract Class Hierarchy shows the relationship of ordered collection to 
  16139.  the class hierarchy. 
  16140.  
  16141.  
  16142. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  16143.  
  16144. The ordered collection class is declared in the header file iaorder.h. 
  16145.  
  16146.  
  16147. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  16148.  
  16149. The ordered collection class defines the following member functions, described 
  16150. in  Introduction to Flat Collections, as pure virtual functions: 
  16151.  
  16152.      Destructor 
  16153.      elementAtPosition 
  16154.      firstElement 
  16155.      isFirst 
  16156.      isLast 
  16157.      lastElement 
  16158.      position 
  16159.      removeAtPosition 
  16160.      removeFirst 
  16161.      removeLast 
  16162.      setToLast 
  16163.      setToPosition 
  16164.      setToPrevious 
  16165.  
  16166.  
  16167. ΓòÉΓòÉΓòÉ 5.4.9. Sequential Collection ΓòÉΓòÉΓòÉ
  16168.  
  16169. Description 
  16170.  
  16171. Derivation 
  16172.  
  16173. Variants/Header Files 
  16174.  
  16175. Members 
  16176.  
  16177. To close all the panels in a chapter, double-click on this panel's system menu. 
  16178.  
  16179.  
  16180. ΓòÉΓòÉΓòÉ 5.4.9.1. Class Description - Sequential Collection ΓòÉΓòÉΓòÉ
  16181.  
  16182. Because sequential collection is an abstract class, it cannot be used to create 
  16183. any objects. The sequential collection inherits from ordered collection and 
  16184. defines the interfaces for the properties of ordered elements. 
  16185.  
  16186.  
  16187. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  16188.  
  16189. Collection 
  16190.  
  16191.   Ordered Collection
  16192.    Sequential Collection
  16193.  
  16194. The following concrete classes are defined by sequential collection: 
  16195.  
  16196.      Sequence 
  16197.      Equality sequence 
  16198.  
  16199.  The Abstract Class Hierarchy shows the relationship of sequential collection 
  16200.  to the class hierarchy. 
  16201.  
  16202.  
  16203. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  16204.  
  16205. The sequential collection class is declared in the header file iasqntl.h. 
  16206.  
  16207.  
  16208. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  16209.  
  16210. Sequential collection defines the following member functions as pure virtual 
  16211. functions: 
  16212.  
  16213.      Destructor 
  16214.      operator= 
  16215.      add 
  16216.      addAllFrom 
  16217.      addAsFirst 
  16218.      addAsLast 
  16219.      addAsNext 
  16220.      addAsPrevious 
  16221.      addAtPosition 
  16222.      allElementsDo 
  16223.      anyElement 
  16224.      compare 
  16225.      elementAt 
  16226.      elementAtPosition 
  16227.      firstElement 
  16228.      isBounded 
  16229.      isEmpty 
  16230.      isFirst 
  16231.      isFull 
  16232.      isLast 
  16233.      lastElement 
  16234.      maxNumberOfElements 
  16235.      newCursor 
  16236.      position 
  16237.      removeAll 
  16238.      removeAt 
  16239.      removeAtPosition 
  16240.      removeFirst 
  16241.      removeLast 
  16242.      replaceAt 
  16243.      setToFirst 
  16244.      setToLast 
  16245.      setToNext 
  16246.      setToPosition 
  16247.      setToPrevious 
  16248.      sort 
  16249.  
  16250.  
  16251. ΓòÉΓòÉΓòÉ 5.4.10. Sorted Collection ΓòÉΓòÉΓòÉ
  16252.  
  16253. Description 
  16254.  
  16255. Derivation 
  16256.  
  16257. Variants/Header Files 
  16258.  
  16259. Members 
  16260.  
  16261. To close all the panels in a chapter, double-click on this panel's system menu. 
  16262.  
  16263.  
  16264. ΓòÉΓòÉΓòÉ 5.4.10.1. Class Description - Sorted Collection ΓòÉΓòÉΓòÉ
  16265.  
  16266. Because sorted collection is an abstract class, it cannot be used to create any 
  16267. objects. The sorted collection inherits from ordered collection and defines the 
  16268. interfaces for the properties of sorted elements. 
  16269.  
  16270.  
  16271. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  16272.  
  16273. Collection 
  16274.  
  16275.   Ordered Collection
  16276.    Sorted Collection
  16277.  
  16278. The following abstract classes are derived from sorted collection: 
  16279.  
  16280.      Equality sorted collection 
  16281.      Key sorted collection 
  16282.  
  16283.  The Abstract Class Hierarchy shows the relationship of sorted collection to 
  16284.  the class hierarchy. 
  16285.  
  16286.  
  16287. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  16288.  
  16289. The sorted collection class is declared in the header file iasrt.h. 
  16290.  
  16291.  
  16292. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  16293.  
  16294. The sorted collection class inherits all its members from its bases. 
  16295.  
  16296.  
  16297. ΓòÉΓòÉΓòÉ 5.5. Header Files for Collection Class Library Coding Examples ΓòÉΓòÉΓòÉ
  16298.  
  16299. This section contains edited header files used by some coding examples found in 
  16300. this book.  The following header files are shown: 
  16301.  
  16302.       animal 
  16303.       circle.h 
  16304.       curve.h 
  16305.       demoelem 
  16306.       dsur 
  16307.       graph.h 
  16308.       line.h 
  16309.       parcel 
  16310.       planet 
  16311.       toyword 
  16312.       transelm 
  16313.       trmapops 
  16314.       xebc2asc 
  16315.  
  16316.  These header files can be found in ...\ibmclass\samples\iclcc. Some comments 
  16317.  and white space have been removed. 
  16318.  
  16319.  
  16320. ΓòÉΓòÉΓòÉ 5.5.1. animal.h ΓòÉΓòÉΓòÉ
  16321.  
  16322. // animal.h  -  Class Animal for use with the example animals.C
  16323.  
  16324.   #include <iglobals.h>           // For
  16325. definition of Boolean
  16326.   #include <istring.hpp>          // Class
  16327. IString
  16328.   #include <iostream.h>
  16329.  
  16330. class Animal {
  16331.   IString nm;
  16332.   IString attr;
  16333.  
  16334. public:
  16335.  
  16336.   Animal(IString n, IString a) : nm(n), attr(a)  {}
  16337.  
  16338.   // For copy constructor we use the compiler generated default.
  16339.   // For assignment we use the compiler generated default.
  16340.  
  16341.   IBoolean operator==(Animal const& p) const  {
  16342.      return  ((nm == p.name()) && (attr == p.attribute()));
  16343.   }
  16344.  
  16345.   IString const& name() const {
  16346.      return nm;
  16347.   }
  16348.  
  16349.   IString const& attribute() const {
  16350.      return attr;
  16351.   }
  16352.  
  16353.   friend ostream& operator<<(ostream& os, Animal const& p)  {
  16354.      return os << "The " << p.name() << " is " << p.attribute()
  16355.      << "." << endl;
  16356.   }
  16357.  
  16358. };
  16359.  
  16360.   // Key access:
  16361. inline IString const& key(Animal const& p)  {
  16362.   return p.name();
  16363. }
  16364.  
  16365.   // We need a hash function for the key type as well.
  16366.   // Let's just use the default provided for IString.
  16367. inline unsigned long hash(Animal const& animal, unsigned long n) {
  16368.   return hash(animal.name(), n);
  16369. }
  16370.  
  16371.  
  16372. ΓòÉΓòÉΓòÉ 5.5.2. circle.h ΓòÉΓòÉΓòÉ
  16373.  
  16374. // circle.h
  16375.  
  16376. #include <istring.hpp>
  16377.  
  16378. class Circle : public Graphics {
  16379. public:
  16380.   float ivXCenter;
  16381.   float ivYCenter;
  16382.   float ivRadius;
  16383.  
  16384.   Circle(int graphicsKey, IString id ,
  16385.          double xCenter, double yCenter,
  16386.          double radius)
  16387.                           : Graphics(graphicsKey, id),
  16388.                             ivXCenter(xCenter),
  16389.                             ivYCenter(yCenter),
  16390.                             ivRadius(radius) { }
  16391.  
  16392.   IBoolean operator== (Circle const& circle) const {
  16393.      return (this->ivXCenter == circle.ivXCenter &&
  16394.              this->ivYCenter == circle.ivYCenter &&
  16395.              this->ivRadius == circle.ivRadius);
  16396.     }
  16397.  
  16398.  
  16399.   void          draw() const {
  16400.      cout << "drawing "
  16401.           << Graphics::id() << endl
  16402.           << "with center: "
  16403.           << "(" << this->ivXCenter << "|"
  16404.           << this->ivYCenter << ")"
  16405.           << " and with radius: "
  16406.           << this->ivRadius << endl;
  16407.     }
  16408.  
  16409.   void          circumference() const {
  16410.      cout << "The circumference of "
  16411.           << Graphics::id() << " is: "
  16412.           << ((this->ivRadius)*2*3.14) << endl;
  16413.     }
  16414. };
  16415.  
  16416.  
  16417. ΓòÉΓòÉΓòÉ 5.5.3. curve.h ΓòÉΓòÉΓòÉ
  16418.  
  16419. // curve.h
  16420.  
  16421. #include <istring.hpp>
  16422.  
  16423. class Curve : public Graphics {
  16424. public:
  16425.  
  16426.   float ivXStart, ivYStart;
  16427.   float ivXFix1, ivYFix1;
  16428.   float ivXFix2, ivYFix2;
  16429.   float ivXFix3, ivYFix3;
  16430.   float ivXEnd,  ivYEnd;
  16431.  
  16432.   Curve(int graphicsKey, IString id,
  16433.         float xstart, float ystart,
  16434.         float xfix1, float yfix1,
  16435.         float xfix2, float yfix2,
  16436.         float xfix3, float yfix3,
  16437.         float xend, float yend)  :
  16438.   Graphics(graphicsKey, id),
  16439.   ivXStart(xstart), ivYStart(ystart),
  16440.   ivXFix1(xfix1),   ivYFix1(yfix1),
  16441.   ivXFix2(xfix2),   ivYFix2(yfix2),
  16442.   ivXFix3(xfix3),   ivYFix3(yfix3),
  16443.   ivXEnd(xend),     ivYEnd(yend) { }
  16444.  
  16445.   IBoolean operator== (Curve const& curve) const {
  16446.      return (this->ivXStart == curve.ivXStart &&
  16447.              this->ivYStart == curve.ivYStart &&
  16448.              this->ivXFix1  == curve.ivXFix1  &&
  16449.              this->ivYFix1  == curve.ivYFix1  &&
  16450.              this->ivXFix2  == curve.ivXFix2  &&
  16451.              this->ivYFix2  == curve.ivYFix2  &&
  16452.              this->ivXFix3  == curve.ivXFix3  &&
  16453.              this->ivYFix3  == curve.ivYFix3  &&
  16454.              this->ivXEnd   == curve.ivXEnd   &&
  16455.              this->ivYEnd   == curve.ivYEnd);
  16456.     }
  16457.  
  16458.   void           draw() const {
  16459.      cout << "drawing " << Graphics::id()
  16460.           << "\nwith starting point: "
  16461.           << "(" << this->ivXStart << "|"
  16462.           << this->ivYStart << ")"
  16463.           << " and with fix points: "
  16464.           << "(" << this->ivXFix1 << "|" << this->ivYFix1 << ")"
  16465.           << "(" << this->ivXFix2 << "|" << this->ivYFix2 << ")"
  16466.           << "(" << this->ivXFix3 << "|" << this->ivYFix3 << ")\n"
  16467.           << "and with ending point: "
  16468.           << "(" << this->ivXEnd << "|" << this->ivYEnd << ")"
  16469.           << endl;
  16470.     }
  16471.  
  16472.   void           lengthOfCurve() const {
  16473.      cout << "Length of "
  16474.           << Graphics::id()
  16475.           << " is: "
  16476.           << (sqrt(pow(((this->ivXFix1) - (this->ivXStart)),2)
  16477.                  + pow(((this->ivYFix1) - (this->ivYStart)),2))
  16478.             + sqrt(pow(((this->ivXFix2) - (this->ivXFix1)),2)
  16479.                  + pow(((this->ivYFix2) - (this->ivYFix1)),2))
  16480.             + sqrt(pow(((this->ivXFix3) - (this->ivXFix2)),2)
  16481.                  + pow(((this->ivYFix3) - (this->ivYFix2)),2))
  16482.             + sqrt(pow(((this->ivXEnd) -  (this->ivXFix3)),2)
  16483.                  + pow(((this->ivYEnd) - (this->ivYFix3)),2)))
  16484.           << endl;
  16485.     }
  16486. };
  16487.  
  16488.  
  16489. ΓòÉΓòÉΓòÉ 5.5.4. demoelem.h ΓòÉΓòÉΓòÉ
  16490.  
  16491. // demoelem.h  -  DemoElement for use with Key Collections
  16492. #ifndef _DEMOELEM_H
  16493. #define _DEMOELEM_H
  16494.  
  16495. #include <stdlib.h>
  16496. #include <iglobals.h>
  16497. #include <iostream.h>
  16498. #include <istdops.h>
  16499.  
  16500. class DemoElement {
  16501.   int i, j;
  16502.  
  16503. public:
  16504.            DemoElement () : i(0), j(0) {}
  16505.            DemoElement (int i,int j) : i (i), j(j) {}
  16506.            operator int () const { return i; }
  16507.  
  16508.   IBoolean operator == (DemoElement const& k) const
  16509.            { return i == k.i && j == k.j; }
  16510.  
  16511.   IBoolean operator < (DemoElement const& k) const
  16512.            { return i < k.i || (i == k.i && j < k.j); }
  16513.  
  16514.   friend unsigned long hash (DemoElement const& k, unsigned long n)
  16515.            { return k.i % n; }
  16516.  
  16517.   int const & geti () const { return i; }
  16518.   int const & getj () const { return j; }
  16519. };
  16520.  
  16521. inline ostream & operator << (ostream &sout, DemoElement const& e)
  16522. { sout << e.geti () << "," << e.getj ();
  16523.   return sout;
  16524. }
  16525.  
  16526. inline int const& key (DemoElement const& k) { return k.geti (); }
  16527.  
  16528. // NOTE: You must return a const & in the key function!  Otherwise the
  16529. // standard element operations will return a reference to a temporary.
  16530. // This would lead to incorrect behavior of the collection operations.
  16531.  
  16532. // The key function must be declared in the header file of
  16533. // the collection's element type.
  16534.  
  16535. // If either of these is not possible or is undesirable,
  16536. // an element operations class must be used.
  16537. #endif
  16538.  
  16539.  
  16540. ΓòÉΓòÉΓòÉ 5.5.5. dsur.h ΓòÉΓòÉΓòÉ
  16541.  
  16542. // dsur.h  -  Class for Disk Space Usage Records
  16543. //            Used by Sorted Map and Sorted Relation example
  16544.   #include <fstream.h>
  16545.   #include <string.h>
  16546.   #include <iglobals.h>
  16547.   const int bufSize = 62;
  16548.  
  16549.   class DiskSpaceUR    {
  16550.      int       blocks;
  16551.      char*     name;
  16552.  
  16553.    public:
  16554.      DiskSpaceUR() {}
  16555.      DiskSpaceUR (DiskSpaceUR const& dsur)  { init(dsur); }
  16556.      void operator= (DiskSpaceUR const& dsur)   {
  16557.        deInit();
  16558.        init(dsur);
  16559.      }
  16560.  
  16561.      DiskSpaceUR (istream& DSURfile) { DSURfile >> *this; }
  16562.      ~DiskSpaceUR () { deInit(); }
  16563.  
  16564.      IBoolean operator == (DiskSpaceUR const& dsur) const  {
  16565.        return (blocks == dsur.blocks)
  16566.            && strcmp (name, dsur.name) == 0;
  16567.      }
  16568.  
  16569.  
  16570.      friend istream& operator >> (istream& DSURfile,
  16571.                                   DiskSpaceUR& dsur)     {
  16572.          DSURfile >> dsur.blocks;
  16573.  
  16574.          char temp[bufSize];
  16575.          DSURfile.get(temp, bufSize);
  16576.  
  16577.          if (DSURfile.good())  {
  16578.                                 // Remove leading tabs and blanks
  16579.             for (int cnt=0;
  16580.                  (temp[cnt] == '\t') || (temp[cnt] == ' ');
  16581.                  cnt++) {}
  16582.             dsur.name = new char[strlen(temp+cnt)+1];
  16583.             strcpy(dsur.name, temp+cnt);
  16584.          }
  16585.          else   {
  16586.             dsur.setInvalid();
  16587.             dsur.name = new char[1];
  16588.             dsur.name[0] = '\0';
  16589.          }
  16590.  
  16591.          return DSURfile;
  16592.      }
  16593.  
  16594.      friend ostream& operator << (ostream& outstream,
  16595.                                   DiskSpaceUR& dsur)     {
  16596.          outstream.width(bufSize);
  16597.          outstream.setf(ios::left, ios::adjustfield);
  16598.          outstream << dsur.name;
  16599.  
  16600.          outstream.width(9);
  16601.          outstream.setf(ios::right, ios::adjustfield);
  16602.          outstream << dsur.blocks;
  16603.  
  16604.          return outstream;
  16605.      }
  16606.  
  16607.      inline int const& space () const {return blocks;}
  16608.      inline char* const& id () const {return name;}
  16609.      inline IBoolean isValid () const {return (blocks > 0);}
  16610.  
  16611.    protected:
  16612.  
  16613.      inline void init (DiskSpaceUR const& dsur)     {
  16614.         blocks = dsur.blocks;
  16615.         name = new char[strlen(dsur.name) + 1];
  16616.         strcpy(name, dsur.name);
  16617.      }
  16618.  
  16619.      inline void deInit() {  delete[] name;  }
  16620.      inline void setInvalid () { blocks = -1;}
  16621.   };
  16622.  
  16623.  
  16624.      // Key access on name
  16625.   inline  char* const& key (DiskSpaceUR const& dsur)  {
  16626.      return dsur.id();
  16627.   }
  16628.  
  16629.      // Key access on space used
  16630.      // Since we can not have two key functions with same args
  16631.      // in global name space, we need to use an operations class.
  16632.   #include <istdops.h>
  16633.      // We can inherit all from the default operations class
  16634.      // and then define just the key access function ourselves.
  16635.      // We cannot use StdKeyOps here, because they in turn
  16636.      // use the key function in global name space, which is
  16637.      // already defined for keys of type char* above.
  16638.   class DSURBySpaceOps :  public IStdMemOps,
  16639.                           public IStdAsOps< DiskSpaceUR >,
  16640.                           public IStdEqOps< DiskSpaceUR >    {
  16641.     public:
  16642.        IStdCmpOps < int > keyOps;
  16643.  
  16644.      // Key Access
  16645.        int const& key (DiskSpaceUR const& dsur) const
  16646.        { return dsur.space(); }
  16647.   };
  16648.  
  16649.  
  16650. ΓòÉΓòÉΓòÉ 5.5.6. graph.h ΓòÉΓòÉΓòÉ
  16651.  
  16652. #include <istring.hpp>
  16653. #include <iostream.h>
  16654.  
  16655. class Graphics {
  16656. protected:
  16657.   IString ivId;    //*** graphics ID ****/
  16658.   int     ivKey;   //*** graphics key ****/
  16659.  
  16660. public:
  16661.   Graphics (int graphicsKey, IString id) : ivKey(graphicsKey),
  16662.                                            ivId(id) { }
  16663.  
  16664.   ~Graphics() {
  16665.      cout << this->ivId  << " will now be deleted ... "  << endl;
  16666.     }
  16667.  
  16668.   IBoolean operator== (Graphics const& graphics) const {
  16669.      return (this->ivId == graphics.ivId);
  16670.     }
  16671.  
  16672.   IString const& id() const   { return ivId; }
  16673.  
  16674.   virtual void draw() const =0;
  16675.  
  16676.   /**** This member function returns the graphic's key ****/
  16677.   /*    Note that we are returning the int by reference,  */
  16678.   /*    because this member function will be used by the  */
  16679.   /*    key(...) function, which must return a reference. */
  16680.   /********************************************************/
  16681.   int const& graphicsKey() const {
  16682.      return ivKey;
  16683.     }
  16684. };
  16685.  
  16686. /****************       key function       *********************/
  16687. /****   note that this interface must always be used with:  ****/
  16688. /****              Keytype const& key(....)                 ****/
  16689. /****   We are providing this key function for the element  ****/
  16690. /****   type Graphics  and not for the managed pointer.     ****/
  16691. /***************************************************************/
  16692.   inline int const& key (Graphics const& graphics) {
  16693.      return graphics.graphicsKey();
  16694.     }
  16695.  
  16696.  
  16697. ΓòÉΓòÉΓòÉ 5.5.7. line.h ΓòÉΓòÉΓòÉ
  16698.  
  16699. #include <istring.hpp>
  16700. #include <math.h>
  16701.  
  16702. class Line : public Graphics {
  16703. public:
  16704.  
  16705.   double ivXStart, ivYStart;
  16706.   double ivXEnd, ivYEnd;
  16707.  
  16708.   Line(int graphicsKey, IString id, double xstart, double ystart,
  16709.                                     double xend,   double yend) :
  16710.  
  16711.      Graphics(graphicsKey, id),
  16712.      ivXStart(xstart), ivYStart(ystart),
  16713.      ivXEnd(xend), ivYEnd(yend) { }
  16714.  
  16715.   IBoolean operator== (Line const& line) const {
  16716.      return (this->ivXStart == line.ivXStart &&
  16717.              this->ivYStart == line.ivYStart &&
  16718.              this->ivXEnd == line.ivXEnd &&
  16719.              this->ivYEnd == line.ivYEnd);
  16720.     }
  16721.  
  16722.   void           draw() const {
  16723.      cout << "drawing " << Graphics::id() << endl
  16724.           << "with starting point: "
  16725.           << "(" << this->ivXStart << "|" << this->ivYStart << ")"
  16726.           << " and with ending point: "
  16727.           << "(" << this->ivXEnd   << "|" << this->ivYEnd << ")" << endl;
  16728.     }
  16729.  
  16730.   void           lengthOfLine() const {
  16731.      cout << "The length of line " << Graphics::id() << " is: "
  16732.           << sqrt(pow(((this->ivXEnd) - (this->ivXStart)),2)
  16733.                 + pow(((this->ivYEnd) - (this->ivYStart)),2))
  16734.           << endl;
  16735.     }
  16736. };
  16737.  
  16738.  
  16739. ΓòÉΓòÉΓòÉ 5.5.8. parcel.h ΓòÉΓòÉΓòÉ
  16740.  
  16741. // parcel.h  -  Class Parcel and its parts for use with the
  16742. //              example for Key Sorted Set and Heap.
  16743. #include <iostream.h>
  16744.  
  16745.                         // For definition of Boolean:
  16746. #include <iglobals.h>
  16747.                         // Class IString:
  16748. #include <istring.hpp>
  16749.  
  16750. class PlaceTime {
  16751.  
  16752.   IString cty;
  16753.   int   daynum;  // Keeping it simple:  January 9 is day 9
  16754.  
  16755. public:
  16756.   PlaceTime(IString acity, int aday) : cty(acity), daynum(aday) {}
  16757.   PlaceTime(IString acity) : cty(acity) {daynum = 0;}
  16758.   IString const& city() const { return cty; }
  16759.   int const& day() const { return daynum; }
  16760.   void operator=(PlaceTime const& pt) {
  16761.       cty = pt.cty;
  16762.       daynum = pt.daynum;
  16763.   }
  16764.  
  16765.   IBoolean operator==(PlaceTime const& pt)  const {
  16766.      return ( (cty == pt.cty)
  16767.            && (daynum == pt.daynum) );
  16768.   }
  16769. };
  16770.  
  16771.  
  16772. class Parcel {
  16773.   PlaceTime org, lstAr;
  16774.   IString dst, id;
  16775.  
  16776. public:
  16777.  
  16778.   Parcel(IString orig,  IString dest, int day, IString ident)
  16779.      :  org(orig, day),  lstAr(orig, day),  dst(dest), id(ident) {}
  16780.  
  16781.   void arrivedAt(IString const& acity, int const& day) {
  16782.      PlaceTime nowAt(acity, day);
  16783.                               // Only if not already there before
  16784.      if (nowAt.city() != lstAr.city())
  16785.         lstAr = nowAt;
  16786.   }
  16787.  
  16788.   void wasDelivered(int const& day) {arrivedAt(dst, day);  }
  16789.   PlaceTime const& origin() const { return org; }
  16790.   IString const& destination() const { return dst; }
  16791.   PlaceTime const& lastArrival() const { return lstAr; }
  16792.   IString const& ID() const { return id; }
  16793.  
  16794.   friend ostream& operator<<(ostream& os, Parcel const& p) {
  16795.     os << p.id << ": From " << p.org.city()
  16796.        << "(day "  << p.org.day() << ") to " << p.dst;
  16797.  
  16798.     if (p.lstAr.city() != p.dst) {
  16799.        os << endl << "            is at " << p.lstAr.city()
  16800.           << "  since day " << p.lstAr.day() << ".";
  16801.     }
  16802.     else {
  16803.        os << endl << "            was delivered on day "
  16804.           << p.lstAr.day() << ".";
  16805.     }
  16806.     return os;
  16807.   }
  16808. };
  16809.  
  16810.                         // Key access:
  16811.   inline  IString const& key( Parcel const&  p) { return p.ID(); }
  16812.                         // We need a compare function for the key.
  16813.                         // Let's use the default provided for IString:
  16814.   inline long compare(Parcel const& p1, Parcel const& p2) {
  16815.      return compare(p1.ID(), p2.ID());
  16816.   }
  16817.  
  16818.  
  16819. ΓòÉΓòÉΓòÉ 5.5.9. planet.h ΓòÉΓòÉΓòÉ
  16820.  
  16821. // planet.h  -  Class Planet for use in our Sorted Set example
  16822.  
  16823. class Planet   {
  16824.  private:
  16825.    char* plname;
  16826.    float dist, mass, bright;
  16827.  
  16828.  public:
  16829.      // Use the compiler generated default for the copy constructor
  16830.  
  16831.    Planet(char* aname, float adist, float amass, float abright) :
  16832.      plname(aname), dist(adist),  mass(amass), bright(abright) {}
  16833.  
  16834.      // For any Set we need to provide element equality.
  16835.    IBoolean operator== (Planet const& aPlanet) const
  16836.       { return plname == aPlanet.plname; }
  16837.  
  16838.      // For a Sorted Set we need to provide element comparision.
  16839.    IBoolean operator< (Planet const& aPlanet) const
  16840.       { return dist < aPlanet.dist; }
  16841.  
  16842.    char*   name()     { return  plname; }
  16843.  
  16844.    IBoolean isHeavy()  { return (mass   > 1.0); }
  16845.    IBoolean isBright() { return (bright < 0.0); }
  16846. };
  16847.  
  16848.  
  16849. // Iterator
  16850. #include <iostream.h>
  16851.  
  16852. class SayPlanetName : public IIterator<Planet>   {
  16853.  public:
  16854.    virtual IBoolean applyTo(Planet& p)
  16855.          { cout << " " << p.name() << " "; return True;}
  16856. };
  16857.  
  16858.  
  16859. ΓòÉΓòÉΓòÉ 5.5.10. toyword.h ΓòÉΓòÉΓòÉ
  16860.  
  16861. // toyword.h  -  Class Word for use with coding examples.
  16862.  
  16863. #include <istring.hpp>
  16864.  
  16865. class Word  {
  16866.         IString       ivWord;
  16867.         unsigned      ivKey;
  16868.  
  16869. public:
  16870.  
  16871.   //Constructor to be used for sample: wordbag.c
  16872.   Word (IString word, unsigned theLength) : ivWord(word),
  16873.                                             ivKey(theLength)
  16874.                                             {}
  16875.  
  16876.   //Constructor to be used for sample: wordseq.c
  16877.   Word (IString word) : ivWord(word) {}
  16878.  
  16879.   IBoolean operator> (Word const& w1) {
  16880.             return this->ivWord > w1.ivWord;
  16881.             }
  16882.  
  16883.   unsigned setKey() {
  16884.             this->ivKey = this->ivWord.length();
  16885.             return this->ivKey;
  16886.             }
  16887.  
  16888.   IString const& getWord() const { return this->ivWord; }
  16889.   unsigned const& getKey() const { return this->ivKey; }
  16890. };
  16891.  
  16892.        // Key access.  The length of the word is the key.
  16893. inline unsigned const& key (Word const &aWord)
  16894. { return aWord.getKey(); }
  16895.  
  16896.  
  16897. ΓòÉΓòÉΓòÉ 5.5.11. transelm.h ΓòÉΓòÉΓòÉ
  16898.  
  16899. // transelm.h  -  For use with the Translation Table example.
  16900. #ifndef _TRANSELM_H
  16901. #define _TRANSELM_H
  16902.  
  16903. #include <iglobals.h>
  16904.  
  16905. class TranslationElement  {
  16906.  
  16907.   char ivAscCode;
  16908.   char ivEbcCode;
  16909.  
  16910. public:
  16911.  
  16912.   /* Let the compiler generate Default and Copy Constructor,*/
  16913.   /* Destructor and Assignment for us.                      */
  16914.  
  16915.   char const& ascCode () const { return ivAscCode; }
  16916.   char const& ebcCode () const { return ivEbcCode; }
  16917.  
  16918.   TranslationElement (char asc, char ebc)
  16919.        : ivAscCode(asc), ivEbcCode(ebc) {};
  16920.  
  16921.   /* We need to define the equality relation.               */
  16922.   IBoolean operator == (TranslationElement const& te) const  {
  16923.      return ivAscCode == te.ivAscCode
  16924.         &&  ivEbcCode == te.ivEbcCode;
  16925.    };
  16926.  
  16927.   /* An ordering relation must not be defined for           */
  16928.   /* elements in a map.                                     */
  16929.  
  16930.   /* We need to define the key access for the elements.     */
  16931.   /* We decided to define all key operations in a           */
  16932.   /* separate operations class in file trmapops.h.          */
  16933.  
  16934. };
  16935. #endif
  16936.  
  16937.  
  16938. ΓòÉΓòÉΓòÉ 5.5.12. trmapops.h ΓòÉΓòÉΓòÉ
  16939.  
  16940. // trmapops.h  -  Translation Map Operations
  16941. //  Base class for element operations for Translation Map example
  16942. #ifndef _TRMAPOPS_H
  16943. #define _TRMAPOPS_H
  16944.  
  16945. // Get the standard operation classes.
  16946. #include <istdops.h>
  16947.  
  16948. #include "transelm.h"
  16949.  
  16950. class TranslationOps : public IEOps < TranslationElement >
  16951. {
  16952. public:
  16953.   class KeyOps : public IStdEqOps < char >, public IStdHshOps < char >
  16954.   {
  16955.   }  keyOps;
  16956. };
  16957.  
  16958. // Operations Class for the EBCDIC-ASCII mapping:
  16959. class TranslationOpsE2A : public TranslationOps
  16960. {
  16961. public:              // Key Access
  16962.   char const& key (TranslationElement const& te) const
  16963.     { return te.ebcCode (); }
  16964. };
  16965.  
  16966. // Operations Class for the ASCII-EBCDIC mapping:
  16967. class TranslationOpsA2E : public TranslationOps
  16968. {
  16969. public:              // Key Access
  16970.   char const& key (TranslationElement const& te) const
  16971.     { return te.ascCode (); }
  16972. };
  16973. #endif
  16974.  
  16975.  
  16976. ΓòÉΓòÉΓòÉ 5.5.13. xebc2asc.h ΓòÉΓòÉΓòÉ
  16977.  
  16978. // xebc2asc.h :   EBCDIC - ASCII Translation Table.
  16979.  const unsigned char translationTable[256] = {
  16980. 0x00,0x01,0x02,0x03,0xCF,0x09,0xD3,0x7F,0xD4,0xD5,0xC3,0x0B,0x0C,0x0D,0x0E,0x0F,
  16981. 0x10,0x11,0x12,0x13,0xC7,0xB4,0x08,0xC9,0x18,0x19,0xCC,0xCD,0x83,0x1D,0xD2,0x1F,
  16982. 0x81,0x82,0x1C,0x84,0x86,0x0A,0x17,0x1B,0x89,0x91,0x92,0x95,0xA2,0x05,0x06,0x07,
  16983. 0xE0,0xEE,0x16,0xE5,0xD0,0x1E,0xEA,0x04,0x8A,0xF6,0xC6,0xC2,0x14,0x15,0xC1,0x1A,
  16984. 0x20,0xA6,0xE1,0x80,0xEB,0x90,0x9F,0xE2,0xAB,0x8B,0x9B,0x2E,0x3C,0x28,0x2B,0x7C,
  16985. 0x26,0xA9,0xAA,0x9C,0xDB,0xA5,0x99,0xE3,0xA8,0x9E,0x21,0x24,0x2A,0x29,0x3B,0x5E,
  16986. 0x2D,0x2F,0xDF,0xDC,0x9A,0xDD,0xDE,0x98,0x9D,0xAC,0xBA,0x2C,0x25,0x5F,0x3E,0x3F,
  16987. 0xD7,0x88,0x94,0xB0,0xB1,0xB2,0xFC,0xD6,0xFB,0x60,0x3A,0x23,0x40,0x27,0x3D,0x22,
  16988. 0xF8,0x61,0x62,0x63,0x64,0x65,0x66,0x67,0x68,0x69,0x96,0xA4,0xF3,0xAF,0xAE,0xC5,
  16989. 0x8C,0x6A,0x6B,0x6C,0x6D,0x6E,0x6F,0x70,0x71,0x72,0x97,0x87,0xCE,0x93,0xF1,0xFE,
  16990. 0xC8,0x7E,0x73,0x74,0x75,0x76,0x77,0x78,0x79,0x7A,0xEF,0xC0,0xDA,0x5B,0xF2,0xF9,
  16991. 0xB5,0xB6,0xFD,0xB7,0xB8,0xB9,0xE6,0xBB,0xBC,0xBD,0x8D,0xD9,0xBF,0x5D,0xD8,0xC4,
  16992. 0x7B,0x41,0x42,0x43,0x44,0x45,0x46,0x47,0x48,0x49,0xCB,0xCA,0xBE,0xE8,0xEC,0xED,
  16993. 0x7D,0x4A,0x4B,0x4C,0x4D,0x4E,0x4F,0x50,0x51,0x52,0xA1,0xAD,0xF5,0xF4,0xA3,0x8F,
  16994. 0x5C,0xE7,0x53,0x54,0x55,0x56,0x57,0x58,0x59,0x5A,0xA0,0x85,0x8E,0xE9,0xE4,0xD1,
  16995. 0x30,0x31,0x32,0x33,0x34,0x35,0x36,0x37,0x38,0x39,0xB3,0xF7,0xF0,0xFA,0xA7,0xFF
  16996. };
  16997.  
  16998.  
  16999. ΓòÉΓòÉΓòÉ 6. Database Access Classes ΓòÉΓòÉΓòÉ
  17000.  
  17001. Use the database access classes to connect and disconnect from your DB2/2 
  17002. database and to perform transactions in the database. 
  17003.  
  17004.  Database Access C++ Classes This chapter describes the C++ version of the 
  17005.                database access class library. Use these classes when you create 
  17006.                applications or components with C++ or the Visual Builder. 
  17007.  
  17008.  Database Access C++ Exception Classes This chapter describes the exception 
  17009.                classes. 
  17010.  
  17011.  Database Access SOM Classes This chapter describes the SOM version of the 
  17012.                database access class library. Use these classes when you want 
  17013.                to use SOM objects to access your database. 
  17014.  
  17015.  
  17016. ΓòÉΓòÉΓòÉ 6.1. Database Access C++ Classes ΓòÉΓòÉΓòÉ
  17017.  
  17018. This chapter describes the C++ version of the database access classes. Use 
  17019. these classes when you generate Visual Builder parts. 
  17020.  
  17021.  
  17022. ΓòÉΓòÉΓòÉ 6.1.1. IDatastore ΓòÉΓòÉΓòÉ
  17023.  
  17024. Description 
  17025.  
  17026. Derivation 
  17027.  
  17028. Header File 
  17029.  
  17030. Members 
  17031.  
  17032. To close all the panels in a chapter, double-click on this panel's system menu. 
  17033.  
  17034.  
  17035. ΓòÉΓòÉΓòÉ 6.1.2. Class Description - IDatastore ΓòÉΓòÉΓòÉ
  17036.  
  17037. The IDatastore provides client connection to the database, disconnect from the 
  17038. database, and commit and rollback of transactions. 
  17039.  
  17040. The following attributes are used by IDatastore: 
  17041.  
  17042.      authentication 
  17043.  
  17044.       The authentication is the password. When logon is performed, if the 
  17045.       userName is a null string, authentication is not used. 
  17046.      datastoreName 
  17047.  
  17048.       This is the name of the datastore to connect to. 
  17049.      userName 
  17050.  
  17051.       When attempting a connect, if userName or authentication are not 
  17052.       specified (""), IDatastore throws the exception IDatastoreLogonFailed if 
  17053.       there is no current user logged on. If userName and authentication are 
  17054.       both specified, IDatastore.connect attempts a logon if the current logged 
  17055.       on user is different than userName. 
  17056.         -  If logon was performed during IDatastore.connect, 
  17057.            IDatastore.disconnect will logoff. 
  17058.         -  If already connected, IDatastore.connect disconnects and reconnects 
  17059.            (including logon if necessary). 
  17060.  
  17061.  Two classes are provided to allow IDatastore to be used within Visual Builder 
  17062.  when building your applications. They are: 
  17063.  
  17064.      IDatastore 
  17065.      IDSConnectCanvas 
  17066.  
  17067.  These parts can be found in the file VBDAX.VBB. 
  17068.  
  17069.  IDatastore is a nonvisual part provided in VBDAX.VBB. This part is the visual 
  17070.  interface to the Data Access Builder class IDatastore. It is a reusable part 
  17071.  that can be dropped into the nonvisual portion of your application. 
  17072.  
  17073.  Use this part to connect to the datastore when the application is started. Use 
  17074.  the settings page for this part to set the datastoreName after placing it into 
  17075.  the composition editor edit area. Then use the ready event of the frame to 
  17076.  call the connect() method, and the close event of the frame to call the 
  17077.  disconnect() method. 
  17078.  
  17079.  IDSConnectCanvas is a visual part (a child of ICanvas), provided in VBDAX.VBB. 
  17080.  
  17081.  This part provides a user interface to access the functions of IDatastore. It 
  17082.  is a reusable part that can be dropped into the main frame window of your 
  17083.  visual applications. Use this part when the connect panel is to be the primary 
  17084.  window of an application, or to access IDatastore from other places within the 
  17085.  application in addition to the connect window. 
  17086.  
  17087.  Use this part by dropping onto the canvas of the primary frame window of the 
  17088.  application. IDatastoreInterface is an exposed attribute of this part. Use the 
  17089.  exposed events, methods and attributes to control IDatastore in addition to 
  17090.  the controls provided on the canvas. 
  17091.  
  17092.  
  17093. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  17094.  
  17095. IStandardNotifier 
  17096.  
  17097.   IDatastore
  17098.  
  17099.  
  17100. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  17101.  
  17102. IDatastore is declared in idsmcon.hpp. 
  17103.  
  17104.  
  17105. ΓòÉΓòÉΓòÉ 6.1.2.1. Members ΓòÉΓòÉΓòÉ
  17106.  
  17107. The following methods are provided: 
  17108.  
  17109.      Constructor 
  17110.      Destructor 
  17111.      authentication 
  17112.      commit 
  17113.      connect() 
  17114.      connect 
  17115.      datastoreName 
  17116.      isConnected 
  17117.      disconnect 
  17118.      rollback 
  17119.      setAuthentication 
  17120.      setDatastoreName 
  17121.      setUserName 
  17122.      userName 
  17123.  
  17124.  
  17125. ΓòÉΓòÉΓòÉ 6.1.2.1.1. Constructor ΓòÉΓòÉΓòÉ
  17126.  
  17127. IDatastore ();
  17128.  
  17129. IDatastore ( const IString& datastoreName,
  17130.                           const IString& userName = "",
  17131.                           const IString& authentication = "");
  17132.  
  17133. The IDatastore constructor allocates an object. This object is used to manage a 
  17134. connection to the datastore. 
  17135.  
  17136.  
  17137. ΓòÉΓòÉΓòÉ 6.1.2.1.2. Destructor ΓòÉΓòÉΓòÉ
  17138.  
  17139. virtual ~IDatastore ();
  17140.  
  17141. The IDatastore destructor frees space allocated by the constructor. 
  17142.  
  17143.  
  17144. ΓòÉΓòÉΓòÉ 6.1.2.1.3. authentication ΓòÉΓòÉΓòÉ
  17145.  
  17146. IString
  17147.    authentication() const;
  17148. IDatastore&
  17149.    setAuthentication(const IString& aAuthentication);
  17150.  
  17151. Gets the authentication. 
  17152.  
  17153.  
  17154. ΓòÉΓòÉΓòÉ 6.1.2.1.4. commit ΓòÉΓòÉΓòÉ
  17155.  
  17156. void commit ()
  17157.  
  17158. Commits the transactions. 
  17159.  
  17160. Exceptions 
  17161.  
  17162.      IDatastoreAccessError 
  17163.      IDatastoreConnectionNotOpen 
  17164.  
  17165.  
  17166. ΓòÉΓòÉΓòÉ 6.1.2.1.5. connect() ΓòÉΓòÉΓòÉ
  17167.  
  17168. void connect ()
  17169.  
  17170. Performs the connect using the current settings specified. If there is already 
  17171. a connection to the database, it is disconnected and then reconnected using the 
  17172. current settings. For information regarding userName, see page IDatastore. 
  17173.  
  17174. Exceptions 
  17175.  
  17176.      IConnectFailed 
  17177.      IDatastoreAccessError 
  17178.      IDatastoreConnectionInUse 
  17179.      IDatastoreLogoffFailed 
  17180.      IDatastoreLogonFailed 
  17181.  
  17182.  
  17183. ΓòÉΓòÉΓòÉ 6.1.2.1.6. connect ΓòÉΓòÉΓòÉ
  17184.  
  17185. void
  17186.    connect ( const IString& datastoreName,
  17187.              const IString& userName = "",
  17188.              const IString& authentication = "");
  17189.  
  17190. Performs the connect using the input parameters specified. If there is already 
  17191. a connection to the database, it is disconnected and then reconnected using the 
  17192. current settings. For information regarding userName, see page IDatastore. 
  17193.  
  17194. Exceptions 
  17195.  
  17196.      IConnectFailed 
  17197.      IDatastoreAccessError 
  17198.      IDatastoreConnectionInUse 
  17199.      IDatastoreLogoffFailed 
  17200.      IDatastoreLogonFailed 
  17201.  
  17202.  
  17203. ΓòÉΓòÉΓòÉ 6.1.2.1.7. datastoreName ΓòÉΓòÉΓòÉ
  17204.  
  17205. IString
  17206.    datastoreName() const;
  17207.  
  17208. Gets the current datastore name setting. 
  17209.  
  17210.  
  17211. ΓòÉΓòÉΓòÉ 6.1.2.1.8. disconnect ΓòÉΓòÉΓòÉ
  17212.  
  17213. void disconnect ()
  17214.  
  17215. Closes the connection to a database. If a logon was performed on the connect, 
  17216. userName is logged off. 
  17217.  
  17218. Exceptions 
  17219.  
  17220.      IDatastoreConnectionNotOpen 
  17221.      IDatastoreLogoffFailed 
  17222.      IDisconnectError 
  17223.  
  17224.  
  17225. ΓòÉΓòÉΓòÉ 6.1.2.1.9. isConnected ΓòÉΓòÉΓòÉ
  17226.  
  17227. Boolean isConnected ();
  17228.  
  17229. Returns true if there is a connection to the database. 
  17230.  
  17231.  
  17232. ΓòÉΓòÉΓòÉ 6.1.2.1.10. rollback ΓòÉΓòÉΓòÉ
  17233.  
  17234. void rollback ()
  17235.  
  17236. Performs a rollback on the transactions. 
  17237.  
  17238. Exceptions 
  17239.  
  17240.      IDatastoreAccessError 
  17241.      IDatastoreConnectionNotOpen 
  17242.  
  17243.  
  17244. ΓòÉΓòÉΓòÉ 6.1.2.1.11. setAuthentication ΓòÉΓòÉΓòÉ
  17245.  
  17246. IDatastore&
  17247.    setAuthentication(const IString& aAuthentication);
  17248.  
  17249. Sets the authentication (password). For information regarding authentication, 
  17250. see page IDatastore. 
  17251.  
  17252.  
  17253. ΓòÉΓòÉΓòÉ 6.1.2.1.12. setDatastoreName ΓòÉΓòÉΓòÉ
  17254.  
  17255. IDatastore&
  17256.    setDatastoreType(const IString& aDatastoreName);
  17257.  
  17258. Sets the datastore name that is used when a connection is established. 
  17259.  
  17260.  
  17261. ΓòÉΓòÉΓòÉ 6.1.2.1.13. setUserName ΓòÉΓòÉΓòÉ
  17262.  
  17263. IDatastore&
  17264.    setUserName(const IString& aUserName);
  17265.  
  17266. Sets the user name. For information regarding userName, see page IDatastore. 
  17267.  
  17268.  
  17269. ΓòÉΓòÉΓòÉ 6.1.2.1.14. userName ΓòÉΓòÉΓòÉ
  17270.  
  17271. IString
  17272.    userName() const;
  17273.  
  17274. Gets the current user name setting. For information regarding userName, see 
  17275. page IDatastore. 
  17276.  
  17277.  
  17278. ΓòÉΓòÉΓòÉ 6.1.3. IPersistentObject ΓòÉΓòÉΓòÉ
  17279.  
  17280. Description 
  17281.  
  17282. Derivation 
  17283.  
  17284. Header File 
  17285.  
  17286. Members 
  17287.  
  17288. To close all the panels in a chapter, double-click on this panel's system menu. 
  17289.  
  17290.  
  17291. ΓòÉΓòÉΓòÉ 6.1.4. Class Description - IPersistentObject ΓòÉΓòÉΓòÉ
  17292.  
  17293. The IPersistentObject class provides the basic data manipulation operations 
  17294. where a client can call directly to add, update, delete or retrieve a row from 
  17295. a table. It is the abstract base class for all of the parts generated by the 
  17296. tool. 
  17297.  
  17298. The generated part also contains the methods for getting and setting the 
  17299. attribute values. These methods are: 
  17300.  
  17301.      <attribute type> <Attribute>() const 
  17302.      const IString & <Attribute>AsString() const 
  17303.      void set<attribute>(attribute type) 
  17304.      void set<Attribute>(const IString &) 
  17305.      Boolean is<Attribute>Nullabe() const 
  17306.      Boolean is<Attribute>Null() const 
  17307.      void set<Attribute>ToNull(Boolean = true) 
  17308.  
  17309.  
  17310. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  17311.  
  17312. IStandardNotifier 
  17313.  
  17314.   IPersistentObject
  17315.  
  17316.  
  17317. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  17318.  
  17319. IPersistentObject is declared in ipersist.hpp. 
  17320.  
  17321.  
  17322. ΓòÉΓòÉΓòÉ <hidden> Members ΓòÉΓòÉΓòÉ
  17323.  
  17324. The following methods are provided: 
  17325.  
  17326.      Constructors 
  17327.      Destructor 
  17328.      add 
  17329.      delete 
  17330.      isDefaultReadOnly 
  17331.      isReadOnly 
  17332.      operator!= 
  17333.      operator== 
  17334.      operator= 
  17335.      retrieve 
  17336.      setReadOnly 
  17337.      update 
  17338.  
  17339.  
  17340. ΓòÉΓòÉΓòÉ 6.1.4.1. Public Members ΓòÉΓòÉΓòÉ
  17341.  
  17342. The following member functions are described: 
  17343.  
  17344.      constructors 
  17345.      destructor 
  17346.      add 
  17347.      delete 
  17348.      isDefaultReadOnly 
  17349.      isReadOnly 
  17350.      operator!= 
  17351.      operator== 
  17352.      operator= 
  17353.      retrieve 
  17354.      setReadOnly 
  17355.      update 
  17356.  
  17357.  
  17358. ΓòÉΓòÉΓòÉ 6.1.4.1.1. Constructors ΓòÉΓòÉΓòÉ
  17359.  
  17360. IPersistentObject ();
  17361. IPersistentObject (const IPersistentObject& partCopy);
  17362.  
  17363. The IPersistentObject constructor allocates space for keeping the values of the 
  17364. selected columns from a single row of a table. 
  17365.  
  17366.  
  17367. ΓòÉΓòÉΓòÉ 6.1.4.1.2. Destructor ΓòÉΓòÉΓòÉ
  17368.  
  17369. virtual ~IPersistentObject ();
  17370.  
  17371. The IPersistentObject destructor frees the allocated space by the constructor. 
  17372.  
  17373.  
  17374. ΓòÉΓòÉΓòÉ 6.1.4.1.3. add ΓòÉΓòÉΓòÉ
  17375.  
  17376. virtual IPersistentObject &add () = 0;
  17377.  
  17378. Add a row to a table using the data attribute values set in the object. The 
  17379. object should be uniquely identified by the data identifier. 
  17380.  
  17381. Exceptions 
  17382.  
  17383.      IDSAccessError 
  17384.  
  17385.  
  17386. ΓòÉΓòÉΓòÉ 6.1.4.1.4. delete ΓòÉΓòÉΓòÉ
  17387.  
  17388. virtual IPersistentObject &del () = 0;
  17389.  
  17390. Delete rows from a table using the data identifier set in the object. The 
  17391. composition of the data identifier is defined for the concrete class. 
  17392.  
  17393. Exceptions 
  17394.  
  17395.      IDSAccessError 
  17396.  
  17397.  
  17398. ΓòÉΓòÉΓòÉ 6.1.4.1.5. isDefaultReadOnly ΓòÉΓòÉΓòÉ
  17399.  
  17400. virtual void isDefaultReadOnly();
  17401.  
  17402. This function returns a value of true if the table is read-only by default. 
  17403. Otherwise, it returns a value of false. If the table is read-only by default, 
  17404. an exception occurs on an add, delete or update statement. In this case, you 
  17405. can only use the retrieve statement to read the row from the table. Also, when 
  17406. the table is read-only by default, you can not use setReadOnly to change the 
  17407. setting. 
  17408.  
  17409.  
  17410. ΓòÉΓòÉΓòÉ 6.1.4.1.6. isReadOnly ΓòÉΓòÉΓòÉ
  17411.  
  17412. virtual Boolean isReadOnly();
  17413.  
  17414. This function returns a value of true if the table is read-only. Otherwise, it 
  17415. returns a value of false. If the table is read-only, an exception occurs on an 
  17416. add, delete or update statement. 
  17417.  
  17418.  
  17419. ΓòÉΓòÉΓòÉ 6.1.4.1.7. operator!= ΓòÉΓòÉΓòÉ
  17420.  
  17421. Boolean
  17422.  operator != (const IPersistentObject& value) const,
  17423.  operator != (const IPersistentObject* value) const;
  17424.  
  17425. Compares the values of two persistent objects. 
  17426.  
  17427.  
  17428. ΓòÉΓòÉΓòÉ 6.1.4.1.8. operator== ΓòÉΓòÉΓòÉ
  17429.  
  17430. Boolean
  17431.  operator == (const IPersistentObject& value) const,
  17432.  operator == (const IPersistentObject* value) const,
  17433.  
  17434. Compares the values of two persistent objects. 
  17435.  
  17436.  
  17437. ΓòÉΓòÉΓòÉ 6.1.4.1.9. operator= ΓòÉΓòÉΓòÉ
  17438.  
  17439. IPersistentObject&
  17440.       operator= (const IPersistentObject& aIPersistentObject);
  17441.  
  17442. This function assigns the values kept in the other object to this object. 
  17443.  
  17444.  
  17445. ΓòÉΓòÉΓòÉ 6.1.4.1.10. retrieve ΓòÉΓòÉΓòÉ
  17446.  
  17447. virtual IPersistentObject &retrieve () = 0;
  17448.  
  17449. Retrieve a row from a table using the data identifier set in the object. The 
  17450. composition of the data identifier is defined by the concrete class. The data 
  17451. identifier must be set on the object before calling retrieve. 
  17452.  
  17453. Exceptions 
  17454.  
  17455.      IDSAccessError 
  17456.  
  17457.  
  17458. ΓòÉΓòÉΓòÉ 6.1.4.1.11. setReadOnly ΓòÉΓòÉΓòÉ
  17459.  
  17460. virtual void setReadOnly (Boolean flag=true);
  17461.  
  17462. This function sets the table to read-only or updateable. 
  17463.  
  17464.  
  17465. ΓòÉΓòÉΓòÉ 6.1.4.1.12. update ΓòÉΓòÉΓòÉ
  17466.  
  17467. virtual IPersistentObject &update () = 0;
  17468.  
  17469. Update the row using the data identifier set in the object. The composition of 
  17470. the data identifier is defined by the concrete class. 
  17471.  
  17472. Exceptions 
  17473.  
  17474.      IDSAccessError 
  17475.  
  17476.  
  17477. ΓòÉΓòÉΓòÉ 6.1.5. IPOManager ΓòÉΓòÉΓòÉ
  17478.  
  17479. Description 
  17480.  
  17481. Derivation 
  17482.  
  17483. Header File 
  17484.  
  17485. Members 
  17486.  
  17487. To close all the panels in a chapter, double-click on this panel's system menu. 
  17488.  
  17489.  
  17490. ΓòÉΓòÉΓòÉ 6.1.6. Class Description - IPOManager ΓòÉΓòÉΓòÉ
  17491.  
  17492. The IPOManager class provides operations to deal with collections of rows from 
  17493. a table. It is the abstract base class for all of the generated collection 
  17494. parts. The collection is pointed by a private data member and its data type is 
  17495. a pointer to IVSequence<PersistentObject*>. You can manipulate the items in the 
  17496. collection with the functions in the IVSequence class. 
  17497.  
  17498.  
  17499. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  17500.  
  17501. IStandardNotifier 
  17502.  
  17503.   IPOManager
  17504.  
  17505.  
  17506. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  17507.  
  17508. IPOManager is declared in ipersist.hpp. 
  17509.  
  17510.  
  17511. ΓòÉΓòÉΓòÉ 6.1.6.1. Members ΓòÉΓòÉΓòÉ
  17512.  
  17513. The following methods are provided: 
  17514.  
  17515.      Constructors 
  17516.      Destructor 
  17517.      items() 
  17518.      refresh 
  17519.      select 
  17520.  
  17521.  
  17522. ΓòÉΓòÉΓòÉ 6.1.6.1.1. Constructors ΓòÉΓòÉΓòÉ
  17523.  
  17524. IPOManager();
  17525. IPOManager(const IPOManager& partCopy);
  17526. IPOManager& operator= (const IPOManager& aIPOManager);
  17527.  
  17528. The IPOManager constructor allocates space for supporting collection parts. 
  17529.  
  17530.  
  17531. ΓòÉΓòÉΓòÉ 6.1.6.1.2. Destructor ΓòÉΓòÉΓòÉ
  17532.  
  17533. virtual ~IPOManager();
  17534.  
  17535. The IPOManager destructor frees allocated space. 
  17536.  
  17537.  
  17538. ΓòÉΓòÉΓòÉ 6.1.6.1.3. items() ΓòÉΓòÉΓòÉ
  17539.  
  17540. virtual IVSequence<PersistentObject*>* items();
  17541.  
  17542. Returns the pointer to the cllection containing objects. This is a template and 
  17543. is not implemented in the base class. 
  17544.  
  17545.  
  17546. ΓòÉΓòÉΓòÉ 6.1.6.1.4. refresh ΓòÉΓòÉΓòÉ
  17547.  
  17548. virtual IPOManager &refresh () = 0;
  17549.  
  17550. Retrieves a collection of all rows on the table from the database. 
  17551.  
  17552. Exceptions 
  17553.  
  17554.      IDSAccessError 
  17555.  
  17556.  
  17557. ΓòÉΓòÉΓòÉ 6.1.6.1.5. select ΓòÉΓòÉΓòÉ
  17558.  
  17559. virtual IPOManager &select (const IString& clause) = 0;
  17560.  
  17561. Retrieves a collection of all rows on the table that match the specified 
  17562. predicate from the datastore. The predicate must be specified in the syntax of 
  17563. the SQL where clause. 
  17564.  
  17565. Exceptions 
  17566.  
  17567.      IDSAccessError 
  17568.  
  17569.  
  17570. ΓòÉΓòÉΓòÉ 6.2. Database Access C++ Exception Classes ΓòÉΓòÉΓòÉ
  17571.  
  17572. The following classes are described: 
  17573.  
  17574.      IConnectFailed 
  17575.      IDatastoreAccessError 
  17576.      IDatastoreAdaptorException 
  17577.      IDatastoreConnectionInUse 
  17578.      IDatastoreConnectionNotOpen 
  17579.      IDatastoreLogoffFailed 
  17580.      IDatastoreLogonFailed 
  17581.      IDisconnectError 
  17582.      IDSAccessError 
  17583.  
  17584.  
  17585. ΓòÉΓòÉΓòÉ 6.2.1. IConnectFailed ΓòÉΓòÉΓòÉ
  17586.  
  17587. Description 
  17588.  
  17589. Derivation 
  17590.  
  17591. Header File 
  17592.  
  17593. Constructors 
  17594.  
  17595. Member - name 
  17596.  
  17597. Inherited Public Members 
  17598.  
  17599. To close all the panels in a chapter, double-click on this panel's system menu. 
  17600.  
  17601.  
  17602. ΓòÉΓòÉΓòÉ 6.2.2. Class Description - IConnectFailed ΓòÉΓòÉΓòÉ
  17603.  
  17604. Objects of the IConnectFailed class represent an exception. This class creates 
  17605. and throws an object when one of the following occurs: 
  17606.  
  17607.      maximum number of IDatastoreMgr connections has already been reached 
  17608.      a connection was attempted while a transaction was in progress 
  17609.  
  17610.  
  17611. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  17612.  
  17613. IException 
  17614.  
  17615.  IDatastoreAdaptorException
  17616.   IConnectFailed
  17617.  
  17618.  
  17619. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  17620.  
  17621. idsexc.hpp. 
  17622.  
  17623.  
  17624. ΓòÉΓòÉΓòÉ 6.2.2.1. Constructors ΓòÉΓòÉΓòÉ
  17625.  
  17626. public:
  17627. IConnectFailed(
  17628.    const char *errorText, unsigned long errorId,
  17629.    Severity severity = IException::unrecoverable);
  17630.  
  17631. You can create objects of this class by doing the following: 
  17632.  
  17633.      Using the constructor. 
  17634.  
  17635.       errorText      The text describing this particular error. 
  17636.  
  17637.       errorId        The identifier you want to associate with this particular 
  17638.                      error. 
  17639.  
  17640.       severity       Use the enumeration IException::Severity to specify the 
  17641.                      severity of the error. The default is unrecoverable. 
  17642.  
  17643.  
  17644. ΓòÉΓòÉΓòÉ 6.2.2.2. Public Member - name ΓòÉΓòÉΓòÉ
  17645.  
  17646. virtual const char *name() const;
  17647.  
  17648. Returns the name of the object's class. 
  17649.  
  17650.  
  17651. ΓòÉΓòÉΓòÉ 6.2.2.3. Inherited Public Members ΓòÉΓòÉΓòÉ
  17652.  
  17653. For information on the members inherited from the IException class, see 
  17654. IException 
  17655.  
  17656.  
  17657. ΓòÉΓòÉΓòÉ 6.2.3. IDatastoreAccessError ΓòÉΓòÉΓòÉ
  17658.  
  17659. Description 
  17660.  
  17661. Derivation 
  17662.  
  17663. Header File 
  17664.  
  17665. Constructors 
  17666.  
  17667. Member - name 
  17668.  
  17669. Inherited Public Members 
  17670.  
  17671. To close all the panels in a chapter, double-click on this panel's system menu. 
  17672.  
  17673.  
  17674. ΓòÉΓòÉΓòÉ 6.2.4. Class Description - IDatastoreAccessError ΓòÉΓòÉΓòÉ
  17675.  
  17676. Objects of the IDatastoreAccessError class represent an exception. This class 
  17677. creates and throws an object when one of the following occurs: 
  17678.  
  17679.      bind file not found 
  17680.      connect error 
  17681.      bind error. 
  17682.  
  17683.  
  17684. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  17685.  
  17686. IException 
  17687.  
  17688.  IDatastoreAdaptorException
  17689.   IDatastoreAccessError
  17690.  
  17691.  
  17692. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  17693.  
  17694. idsexc.hpp 
  17695.  
  17696.  
  17697. ΓòÉΓòÉΓòÉ 6.2.4.1. Constructors ΓòÉΓòÉΓòÉ
  17698.  
  17699. public:
  17700. IDatastoreAccessError(
  17701.    const char *errorText, unsigned long errorId,
  17702.    Severity severity = IException::unrecoverable);
  17703.  
  17704. You can create objects of this class by doing the following: 
  17705.  
  17706.      Using the constructor. 
  17707.  
  17708.       errorText      The text describing this particular error. 
  17709.  
  17710.       errorId        The identifier you want to associate with this particular 
  17711.                      error. 
  17712.  
  17713.       severity       Use the enumeration IException::Severity to specify the 
  17714.                      severity of the error. The default is unrecoverable. 
  17715.  
  17716.  
  17717. ΓòÉΓòÉΓòÉ 6.2.4.2. Public Member - name ΓòÉΓòÉΓòÉ
  17718.  
  17719. virtual const char *name() const;
  17720.  
  17721. Returns the name of the object's class. 
  17722.  
  17723.  
  17724. ΓòÉΓòÉΓòÉ 6.2.4.3. Inherited Public Members ΓòÉΓòÉΓòÉ
  17725.  
  17726. For information on the members inherited from the IException class, see 
  17727. IException 
  17728.  
  17729.  
  17730. ΓòÉΓòÉΓòÉ 6.2.5. IDatastoreAdaptorException ΓòÉΓòÉΓòÉ
  17731.  
  17732. Description 
  17733.  
  17734. Derivation 
  17735.  
  17736. Header File 
  17737.  
  17738. Constructors 
  17739.  
  17740. Member - name 
  17741.  
  17742. Inherited Public Members 
  17743.  
  17744. To close all the panels in a chapter, double-click on this panel's system menu. 
  17745.  
  17746.  
  17747. ΓòÉΓòÉΓòÉ 6.2.6. Class Description - IDatastoreAdaptorException ΓòÉΓòÉΓòÉ
  17748.  
  17749. Objects of the IDatastoreAdaptorException class represent an exception. This 
  17750. class is a generic exception message of accessing datastore. 
  17751.  
  17752.  
  17753. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  17754.  
  17755. IException 
  17756.  
  17757.  IDatastoreAdaptorException
  17758.  
  17759.  
  17760. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  17761.  
  17762. idsexc.hpp 
  17763.  
  17764.  
  17765. ΓòÉΓòÉΓòÉ 6.2.6.1. Constructors ΓòÉΓòÉΓòÉ
  17766.  
  17767. public:
  17768. IDatastoreAdaptorException(
  17769.    const char *errorText, unsigned long errorId,
  17770.    Severity severity = IException::unrecoverable);
  17771.  
  17772. You can create objects of this class by doing the following: 
  17773.  
  17774.      Using the constructor. 
  17775.  
  17776.       errorText      The text describing this particular error. 
  17777.  
  17778.       errorId        The identifier you want to associate with this particular 
  17779.                      error. 
  17780.  
  17781.       severity       Use the enumeration IException::Severity to specify the 
  17782.                      severity of the error. The default is unrecoverable. 
  17783.  
  17784.  
  17785. ΓòÉΓòÉΓòÉ 6.2.6.2. Public Member - name ΓòÉΓòÉΓòÉ
  17786.  
  17787. virtual const char *name() const;
  17788.  
  17789. Returns the name of the object's class. 
  17790.  
  17791.  
  17792. ΓòÉΓòÉΓòÉ 6.2.6.3. Inherited Public Members ΓòÉΓòÉΓòÉ
  17793.  
  17794. For information on the members inherited from the IException class, see 
  17795. IException 
  17796.  
  17797.  
  17798. ΓòÉΓòÉΓòÉ 6.2.7. IDatastoreConnectionInUse ΓòÉΓòÉΓòÉ
  17799.  
  17800. Description 
  17801.  
  17802. Derivation 
  17803.  
  17804. Header File 
  17805.  
  17806. Constructors 
  17807.  
  17808. Member - name 
  17809.  
  17810. Inherited Public Members 
  17811.  
  17812. To close all the panels in a chapter, double-click on this panel's system menu. 
  17813.  
  17814.  
  17815. ΓòÉΓòÉΓòÉ 6.2.8. Class Description - IDatastoreConnectionInUse ΓòÉΓòÉΓòÉ
  17816.  
  17817. Objects of the IDatastoreConnectionInUse class represent an exception. This 
  17818. class creates and throws an object when a connection is attempted using a 
  17819. connection which is already in use. 
  17820.  
  17821.  
  17822. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  17823.  
  17824. IException 
  17825.  
  17826.  IDatastoreAdaptorException
  17827.   IDatastoreConnectionInUse
  17828.  
  17829.  
  17830. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  17831.  
  17832. idsexc.hpp 
  17833.  
  17834.  
  17835. ΓòÉΓòÉΓòÉ 6.2.8.1. Constructors ΓòÉΓòÉΓòÉ
  17836.  
  17837. public:
  17838. IDatastoreConnectionInUse(
  17839.    const char *errorText, unsigned long errorId,
  17840.    Severity severity = IException::unrecoverable);
  17841.  
  17842. You can create objects of this class by doing the following: 
  17843.  
  17844.      Using the constructor. 
  17845.  
  17846.       errorText      The text describing this particular error. 
  17847.  
  17848.       errorId        The identifier you want to associate with this particular 
  17849.                      error. 
  17850.  
  17851.       severity       Use the enumeration IException::Severity to specify the 
  17852.                      severity of the error. The default is unrecoverable. 
  17853.  
  17854.  
  17855. ΓòÉΓòÉΓòÉ 6.2.8.2. Public Member - name ΓòÉΓòÉΓòÉ
  17856.  
  17857. virtual const char *name() const;
  17858.  
  17859. Returns the name of the object's class. 
  17860.  
  17861.  
  17862. ΓòÉΓòÉΓòÉ 6.2.8.3. Inherited Public Members ΓòÉΓòÉΓòÉ
  17863.  
  17864. For information on the members inherited from the IException class, see 
  17865. IException 
  17866.  
  17867.  
  17868. ΓòÉΓòÉΓòÉ 6.2.9. IDatastoreConnectionNotOpen ΓòÉΓòÉΓòÉ
  17869.  
  17870. Description 
  17871.  
  17872. Derivation 
  17873.  
  17874. Header File 
  17875.  
  17876. Constructors 
  17877.  
  17878. Member - name 
  17879.  
  17880. Inherited Public Members 
  17881.  
  17882. To close all the panels in a chapter, double-click on this panel's system menu. 
  17883.  
  17884.  
  17885. ΓòÉΓòÉΓòÉ 6.2.10. Class Description - IDatastoreConnectionNotOpen ΓòÉΓòÉΓòÉ
  17886.  
  17887. Objects of the IDatastoreConnectionNotOpen class represent an exception. This 
  17888. class creates and throws an object when an operation which requires a 
  17889. connection was attempted but the connection has not been established yet. For 
  17890. example, a call to disconnect before a connection was made. 
  17891.  
  17892.  
  17893. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  17894.  
  17895. IException 
  17896.  
  17897.  IDatastoreAdaptorException
  17898.   IDatastoreConnectionNotOpen
  17899.  
  17900.  
  17901. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  17902.  
  17903. idsexc.hpp 
  17904.  
  17905.  
  17906. ΓòÉΓòÉΓòÉ 6.2.10.1. Constructors ΓòÉΓòÉΓòÉ
  17907.  
  17908. public:
  17909. IDatastoreConnectionNotOpen(
  17910.    const char *errorText, unsigned long errorId,
  17911.    Severity severity = IException::unrecoverable);
  17912.  
  17913. You can create objects of this class by doing the following: 
  17914.  
  17915.      Using the constructor. 
  17916.  
  17917.       errorText      The text describing this particular error. 
  17918.  
  17919.       errorId        The identifier you want to associate with this particular 
  17920.                      error. 
  17921.  
  17922.       severity       Use the enumeration IException::Severity to specify the 
  17923.                      severity of the error. The default is unrecoverable. 
  17924.  
  17925.  
  17926. ΓòÉΓòÉΓòÉ 6.2.10.2. Public Member - name ΓòÉΓòÉΓòÉ
  17927.  
  17928. virtual const char *name() const;
  17929.  
  17930. Returns the name of the object's class. 
  17931.  
  17932.  
  17933. ΓòÉΓòÉΓòÉ 6.2.10.3. Inherited Public Members ΓòÉΓòÉΓòÉ
  17934.  
  17935. For information on the members inherited from the IException class, see 
  17936. IException 
  17937.  
  17938.  
  17939. ΓòÉΓòÉΓòÉ 6.2.11. IDatastoreLogoffFailed ΓòÉΓòÉΓòÉ
  17940.  
  17941. Description 
  17942.  
  17943. Derivation 
  17944.  
  17945. Header File 
  17946.  
  17947. Constructors 
  17948.  
  17949. Member - name 
  17950.  
  17951. Inherited Public Members 
  17952.  
  17953. To close all the panels in a chapter, double-click on this panel's system menu. 
  17954.  
  17955.  
  17956. ΓòÉΓòÉΓòÉ 6.2.12. Class Description - IDatastoreLogoffFailed ΓòÉΓòÉΓòÉ
  17957.  
  17958. Objects of the IDatastoreLogoffFailed class represent an exception. The class 
  17959. creates and throws an object when a logoff failes. 
  17960.  
  17961.  
  17962. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  17963.  
  17964. IException 
  17965.  
  17966.  IDatastoreLogoffFailed
  17967.  
  17968.  
  17969. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  17970.  
  17971. idsexc.hpp 
  17972.  
  17973.  
  17974. ΓòÉΓòÉΓòÉ 6.2.12.1. Constructors ΓòÉΓòÉΓòÉ
  17975.  
  17976. public:
  17977. IDatastoreLogoffFailed(
  17978.    const char *errorText, unsigned long errorId,
  17979.    Severity severity = IException::unrecoverable);
  17980.  
  17981. You can create objects of this class by doing the following: 
  17982.  
  17983.      Using the constructor. 
  17984.  
  17985.       errorText      The text describing this particular error. 
  17986.  
  17987.       errorId        The identifier you want to associate with this particular 
  17988.                      error. 
  17989.  
  17990.       severity       Use the enumeration IException::Severity to specify the 
  17991.                      severity of the error. The default is unrecoverable. 
  17992.  
  17993.  
  17994. ΓòÉΓòÉΓòÉ 6.2.12.2. Public Member - name ΓòÉΓòÉΓòÉ
  17995.  
  17996. virtual const char *name() const;
  17997.  
  17998. Returns the name of the object's class. 
  17999.  
  18000.  
  18001. ΓòÉΓòÉΓòÉ 6.2.12.3. Inherited Public Members ΓòÉΓòÉΓòÉ
  18002.  
  18003. For information on the members inherited from the IException class, see 
  18004. IException 
  18005.  
  18006.  
  18007. ΓòÉΓòÉΓòÉ 6.2.13. IDatastoreLogonFailed ΓòÉΓòÉΓòÉ
  18008.  
  18009. Description 
  18010.  
  18011. Derivation 
  18012.  
  18013. Header File 
  18014.  
  18015. Constructors 
  18016.  
  18017. Member - name 
  18018.  
  18019. Inherited Public Members 
  18020.  
  18021. To close all the panels in a chapter, double-click on this panel's system menu. 
  18022.  
  18023.  
  18024. ΓòÉΓòÉΓòÉ 6.2.14. Class Description - IDatastoreLogonFailed ΓòÉΓòÉΓòÉ
  18025.  
  18026. Objects of the IDatastoreLogonFailed class represent an exception. The class 
  18027. creates and throws an object when a logon attempt fails. 
  18028.  
  18029.  
  18030. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  18031.  
  18032. IException 
  18033.  
  18034.  IDatastoreLogonFailed
  18035.  
  18036.  
  18037. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  18038.  
  18039. idsexc.hpp 
  18040.  
  18041.  
  18042. ΓòÉΓòÉΓòÉ 6.2.14.1. Constructors ΓòÉΓòÉΓòÉ
  18043.  
  18044. public:
  18045. IDatastoreLogonFailed(
  18046.    const char *errorText, unsigned long errorId,
  18047.    Severity severity = IException::unrecoverable);
  18048.  
  18049. You can create objects of this class by doing the following: 
  18050.  
  18051.      Using the constructor. 
  18052.  
  18053.       errorText      The text describing this particular error. 
  18054.  
  18055.       errorId        The identifier you want to associate with this particular 
  18056.                      error. 
  18057.  
  18058.       severity       Use the enumeration IException::Severity to specify the 
  18059.                      severity of the error. The default is unrecoverable. 
  18060.  
  18061.  
  18062. ΓòÉΓòÉΓòÉ 6.2.14.2. Public Member - name ΓòÉΓòÉΓòÉ
  18063.  
  18064. virtual const char *name() const;
  18065.  
  18066. Returns the name of the object's class. 
  18067.  
  18068.  
  18069. ΓòÉΓòÉΓòÉ 6.2.14.3. Inherited Public Members ΓòÉΓòÉΓòÉ
  18070.  
  18071. For information on the members inherited from the IException class, see 
  18072. IException 
  18073.  
  18074.  
  18075. ΓòÉΓòÉΓòÉ 6.2.15. IDisconnectError ΓòÉΓòÉΓòÉ
  18076.  
  18077. Description 
  18078.  
  18079. Derivation 
  18080.  
  18081. Header File 
  18082.  
  18083. Constructors 
  18084.  
  18085. Member - name 
  18086.  
  18087. Inherited Public Members 
  18088.  
  18089. To close all the panels in a chapter, double-click on this panel's system menu. 
  18090.  
  18091.  
  18092. ΓòÉΓòÉΓòÉ 6.2.16. Class Description - IDisconnectError ΓòÉΓòÉΓòÉ
  18093.  
  18094. Objects of the IDisconnectError class represent an exception. This class 
  18095. creates and throws an object when a disconnect error occurs. 
  18096.  
  18097.  
  18098. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  18099.  
  18100. IException 
  18101.  
  18102.  IDatastoreAdaptorException
  18103.   IDisconnectError
  18104.  
  18105.  
  18106. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  18107.  
  18108. idsexc.hpp 
  18109.  
  18110.  
  18111. ΓòÉΓòÉΓòÉ 6.2.16.1. Constructors ΓòÉΓòÉΓòÉ
  18112.  
  18113. public:
  18114. IDisconnectError(
  18115.    const char *errorText, unsigned long errorId,
  18116.    Severity severity = IException::unrecoverable);
  18117.  
  18118. You can create objects of this class by doing the following: 
  18119.  
  18120.      Using the constructor. 
  18121.  
  18122.       errorText      The text describing this particular error. 
  18123.  
  18124.       errorId        The identifier you want to associate with this particular 
  18125.                      error. 
  18126.  
  18127.       severity       Use the enumeration IException::Severity to specify the 
  18128.                      severity of the error. The default is unrecoverable. 
  18129.  
  18130.  
  18131. ΓòÉΓòÉΓòÉ 6.2.16.2. Public Member - name ΓòÉΓòÉΓòÉ
  18132.  
  18133. virtual const char *name() const;
  18134.  
  18135. Returns the name of the object's class. 
  18136.  
  18137.  
  18138. ΓòÉΓòÉΓòÉ 6.2.16.3. Inherited Public Members ΓòÉΓòÉΓòÉ
  18139.  
  18140. For information on the members inherited from the IException class, see 
  18141. IException 
  18142.  
  18143.  
  18144. ΓòÉΓòÉΓòÉ 6.2.17. IDSAccessError ΓòÉΓòÉΓòÉ
  18145.  
  18146. Description 
  18147.  
  18148. Derivation 
  18149.  
  18150. Header File 
  18151.  
  18152. Constructors 
  18153.  
  18154. Member - name 
  18155.  
  18156. Inherited Public Members 
  18157.  
  18158. To close all the panels in a chapter, double-click on this panel's system menu. 
  18159.  
  18160.  
  18161. ΓòÉΓòÉΓòÉ 6.2.18. Class Description - IDSAccessError ΓòÉΓòÉΓòÉ
  18162.  
  18163. Objects of the IDSAccessError class represent an exception thrown from 
  18164. generated code. 
  18165.  
  18166. When thrown, errorId is set with the following values: 
  18167.  
  18168. DAX_ADD_READONLY  // Add used on a readonly table/view
  18169. DAX_ADD_SQLERR    // SQL error occurred on add
  18170. DAX_UPD_READONLY  // Update used on a readonly table/view
  18171. DAX_UPD_SQLERR    // SQL error occurred on update
  18172. DAX_DEL_READONLY  // Delete used ona readonly table/view
  18173. DAX_DEL_SQLERR    // SQL error occurred on delete
  18174. DAX_RET_SQLERR    // SQL error occurred on retrieve
  18175. DAX_REF_SQLERR    // SQL error occurred on refresh
  18176. DAX_SEL_SQLERR    // SQL error occurred on select
  18177. DAX_ADD_NONNULL   // Add with non-nullable column not mapped
  18178. DAX_NUL_NONNULL   // Cannot SetToNull non-nullable column
  18179. DAX_DFT_READONLY  // Cannot SetReadOnly to false on a readonly table/view
  18180. DAX_SYS_LOCK      // Error occurred during system semaphore/locking call
  18181. DAX_ADD_NULL_DATAID // Add with a null DataId
  18182. DAX_UPD_NULL_DATAID // Update with a null DataId
  18183. DAX_DEL_NULL_DATAID // Delete with a null DataId
  18184. DAX_RET_NULL_DATAID // Retrieve with a null DataId
  18185.  
  18186.  
  18187. ΓòÉΓòÉΓòÉ <hidden> Derivation ΓòÉΓòÉΓòÉ
  18188.  
  18189. IException 
  18190.  
  18191.  IDatastoreAdaptorException
  18192.   IDSAccessError
  18193.  
  18194.  
  18195. ΓòÉΓòÉΓòÉ <hidden> Header File ΓòÉΓòÉΓòÉ
  18196.  
  18197. idsexc.hpp 
  18198.  
  18199.  
  18200. ΓòÉΓòÉΓòÉ 6.2.18.1. Constructors ΓòÉΓòÉΓòÉ
  18201.  
  18202. public:
  18203. IDSAccessError(
  18204.       const char* a,
  18205.       unsigned long b = 0,
  18206.       Severity c = IException::unrecoverable,
  18207.       struct sqlca* sqlca_p=0
  18208.       );
  18209.  
  18210. You can create objects of this class by doing the following: 
  18211.  
  18212.      Using the constructor. 
  18213.  
  18214.       errorText      The text describing this particular error. 
  18215.  
  18216.       errorId        The identifier you want to associate with this particular 
  18217.                      error. 
  18218.  
  18219.       severity       Use the enumeration IException::Severity to specify the 
  18220.                      severity of the error. The default is unrecoverable. 
  18221.  
  18222.       sqlca          Uses the contents of the sqlca at the time of the 
  18223.                      exception. 
  18224.  
  18225.  
  18226. ΓòÉΓòÉΓòÉ 6.2.18.2. Public Member - name ΓòÉΓòÉΓòÉ
  18227.  
  18228. virtual const char *name() const;
  18229.  
  18230. Returns the name of the object's class. 
  18231.  
  18232.  
  18233. ΓòÉΓòÉΓòÉ 6.2.18.3. Public Member - getSqlca ΓòÉΓòÉΓòÉ
  18234.  
  18235. struct sqlca const& getSqlca() const;
  18236.  
  18237. Returns the contents of the sqlca at the time of the exception. 
  18238.  
  18239.  
  18240. ΓòÉΓòÉΓòÉ 6.2.18.4. Inherited Public Members ΓòÉΓòÉΓòÉ
  18241.  
  18242. For information on the members inherited from the IException class, see 
  18243. IException 
  18244.  
  18245.  
  18246. ΓòÉΓòÉΓòÉ 6.3. Database Access SOM Classes ΓòÉΓòÉΓòÉ
  18247.  
  18248. This chapter describes the SOM version of the Database Access classes. Use 
  18249. these classes when you want to use SOM objects. 
  18250.  
  18251.  
  18252. ΓòÉΓòÉΓòÉ 6.3.1. Datastore & DatastoreFactory ΓòÉΓòÉΓòÉ
  18253.  
  18254. Datastore and DatastoreFactory provide client connection to the database, 
  18255. disconnect from the database, and commit and rollback of transactions. 
  18256.  
  18257. For additional information, see IDatastore. 
  18258.  
  18259. interface DatastoreFactory : SOMClass {
  18260.  
  18261.     Datastore create_object();
  18262.     Datastore create_object_defaults(in string datastore_name,
  18263.                                      in string user_name,
  18264.                                      in string authentication);
  18265.  
  18266.     #ifdef __SOMIDL__
  18267.     implementation {
  18268.  
  18269.         releaseorder :
  18270.                        create_object;
  18271.                        create_object_defaults;
  18272.  
  18273.     };
  18274.     #endif
  18275.  
  18276. };
  18277.  
  18278. interface Datastore : SOMObject {
  18279.  
  18280.   void
  18281.       connect   ( in string datastore_name,
  18282.                   in string user_name,
  18283.                   in string authentication,
  18284.       raises    (DaxExcep::ConnectFailed,
  18285.                  DaxExcep::DatastoreConnectionInUse,
  18286.                  DaxExcep::DatastoreAccessError,
  18287.                  DaxExcep::DatastoreLogonFailed,
  18288.                  DaxExcep::DatastoreLogoffFailed);
  18289.  
  18290.   void
  18291.       connect_defaults ()
  18292.       raises    (DaxExcep::ConnectFailed,
  18293.                  DaxExcep::DatastoreConnectionInUse,
  18294.                  DaxExcep::DatastoreAccessError,
  18295.                  DaxExcep::DatastoreLogonFailed,
  18296.                  DaxExcep::DatastoreLogoffFailed);
  18297.  
  18298.   void
  18299.       disconnect ()
  18300.       raises     (DaxExcep::DatastoreConnectionNotOpen,
  18301.                   DaxExcep::DisconnectError,
  18302.                   DaxExcep::DatastoreLogoffFailed);
  18303.  
  18304.   void
  18305.       commit ()
  18306.       raises         DaxExcep::DatastoreAccessError,
  18307.                      DaxExcep::DatastoreConnectionNotOpen);
  18308.  
  18309.   void
  18310.       rollback ()
  18311.       raises         DaxExcep::DatastoreAccessError,
  18312.                      DaxExcep::DatastoreConnectionNotOpen);
  18313.  
  18314.   boolean
  18315.       is_connected ();
  18316.   boolean
  18317.       is_sharemode_exclusive();
  18318.   void
  18319.       enable_sharemode_exclusive (in boolean enable);
  18320.  
  18321.   attribute string datastore_name;
  18322.   attribute string user_name;
  18323.   attribute string authentication;
  18324.  
  18325.    #ifdef __SOMIDL__
  18326.    implementation
  18327.    {
  18328.  
  18329.       metaclass = DatastoreFactory;
  18330.  
  18331.       releaseorder: connect,
  18332.                     connect_defaults,
  18333.                     disconnect,
  18334.                     commit,
  18335.                     rollback,
  18336.                     is_connected,
  18337.                     is_sharemode_exclusive,
  18338.                     enable_sharemode_exclusive,
  18339.                     _get_datastore_name,
  18340.                     _set_datastore_name,
  18341.                     _get_user_name,
  18342.                     _set_user_name,
  18343.                     _get_authentication,
  18344.                     _set_authentication,
  18345.  
  18346.       datastore_name: noset, noget;
  18347.       user_name: noset, noget;
  18348.       authentication: noset, noget;
  18349.  
  18350.       somInit: override;
  18351.       somUninit: override;
  18352.    };
  18353.    #endif
  18354. };
  18355. #endif
  18356.  
  18357.  
  18358. ΓòÉΓòÉΓòÉ 6.3.2. PersistentObject & POFactory ΓòÉΓòÉΓòÉ
  18359.  
  18360. The PersistentObject class provides the basic data manipulation operations 
  18361. where a client can call directly to add, update, delete or retrieve a row from 
  18362. a table. It is the abstract base class for all of the parts generated by the 
  18363. tool. For additional information, see IPersistentObject. 
  18364.  
  18365. The POFactory class provides operations to deal with collections of rows from a 
  18366. table. For additional information, see IPOManager. 
  18367.  
  18368. interface POFactory : SOMClass
  18369. {
  18370.    exception POFError
  18371.    {
  18372.        long error_code;
  18373.        long sqlcode;
  18374.    };
  18375.  
  18376.    sequence<PersistentObject> retrieveAll() raises(POFError);
  18377.    sequence<PersistentObject> select(in string clause) raises(POFError);
  18378.  
  18379.    void setPOFException(in long errorCode, in long sqlcode);
  18380.  
  18381.    #ifdef __SOMIDL__
  18382.    implementation
  18383.    {
  18384.        releaseorder : retrieveAll,
  18385.                       select,
  18386.                       setPOFException;
  18387.    };
  18388.    #endif
  18389. };
  18390. interface PersistentObject : SOMObject
  18391. {
  18392.    exception POError
  18393.    {
  18394.        long error_code;
  18395.        long sqlcode;
  18396.    };
  18397.  
  18398.    void add() raises(POError);
  18399.    void update() raises(POError);
  18400.    void del() raises(POError);
  18401.    void retrieve() raises(POError);
  18402.    void setPOException(in long errorCode, in long sqlcode);
  18403.  
  18404.    #ifdef __SOMIDL__
  18405.    implementation
  18406.    {
  18407.        releaseorder : add,
  18408.                       update,
  18409.                       del,
  18410.                       retrieve,
  18411.                       setPOException;
  18412.        metaclass = POFactory;
  18413.    };
  18414.    #endif
  18415. };
  18416.  
  18417. When an exception occurs, error_code is set with the following values: 
  18418.  
  18419. DAX_ADD_READONLY  // Add used on a readonly table/view
  18420. DAX_ADD_SQLERR    // SQL error occurred on add
  18421. DAX_UPD_READONLY  // Update used on a readonly table/view
  18422. DAX_UPD_SQLERR    // SQL error occurred on update
  18423. DAX_DEL_READONLY  // Delete used ona readonly table/view
  18424. DAX_DEL_SQLERR    // SQL error occurred on delete
  18425. DAX_RET_SQLERR    // SQL error occurred on retrieve
  18426. DAX_REF_SQLERR    // SQL error occurred on refresh
  18427. DAX_SEL_SQLERR    // SQL error occurred on select
  18428. DAX_ADD_NONNULL   // Add with non-nullable column not mapped
  18429. DAX_NUL_NONNULL   // Cannot SetToNull non-nullable column
  18430. DAX_DFT_READONLY  // Cannot SetReadOnly to false on a readonly table/view
  18431. DAX_SYS_LOCK      // Error occurred during system semaphore/locking call
  18432. DAX_ADD_NULL_DATAID  // Add with a null DataId
  18433. DAX_UPD_NULL_DATAID  // Update with a null DataId
  18434. DAX_DEL_NULL_DATAID  // Delete with a null DataId
  18435. DAX_RET_NULL_DATAID  // Retrieve with a null DataId
  18436.  
  18437. If the exception is an SQL exception, the sqlcode is set with the SQLCODE 
  18438. returned from the static SQL statement.