home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / nihcl-3.0 / doc / readme.tr < prev    next >
Encoding:
Text File  |  1993-01-01  |  56.7 KB  |  2,612 lines
  1. .ig
  2. [Note: This file has been modified by the Free Software Foundation]
  3.  
  4.     A complete rewrite of the texttroff macro package.
  5.     It would be loosely modelled after the -ms macros
  6.  
  7.     main concept is to separate the elements of the page,
  8.     so a trap for the footer and a trap for the header separatly
  9.  
  10.     Also all default values are in well known registers,
  11.     initialized by the .IZ macro
  12. ..
  13. .\"
  14. .    \" IZ - initialize. Provide some default settings
  15. .de IZ
  16. .nr PS \n(.p    \" pointsize
  17. .nr VS \n(.v    \" linespacing
  18. .nr HM 1i    \" header margin
  19. .nr FM 1i    \" footer margin
  20. .nr LL \n(.l    \" line length
  21. .nr IN 36p    \" indent to allow outdenting headers
  22. .nr LT \n(.l-\n(INu    \" title length
  23. .\" trap setting
  24. .\"
  25. .\" for the top of page
  26. .wh 0 NP
  27. .\" for dealing with footnotes
  28. .wh 14i FO    \" footer trap, temp position
  29. .    \" to process footnote overflow, we fire this trap
  30. .    \" the trap for FO will be moved way up so we will fire
  31. .    \" this one when FO is putting the footnote out
  32. .wh -\\n(FMu Fx
  33. .    \" Now install FO on top of this position so it
  34. .    \" will be fired when no footnote needs to be processed
  35. .ch -\\n(FMu FO
  36. .\" for the bottom tittle
  37. .wh -\\n(FMu/2u BT
  38. ..
  39. .\"
  40. .    \" TA - set tabstops
  41. .de TA
  42. .ta \\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu
  43. ..
  44. .\"
  45. .    \" RS - Reset.    Bring troff into a known state
  46. .de RS
  47. .ps \\n(PS
  48. .vs \\n(VSu
  49. .ll \\n(LLu
  50. .lt \\n(LTu
  51. .in \\n(INu
  52. .po \\n(POu
  53. .nr FS \\n(VSu/4u    \" footnote separation
  54. .nr F 0 1        \" for footnote numbering
  55. .ev 1
  56. .    \" where footnotes are processed
  57. .ps \\n(PS-2
  58. .vs (\\n(VSu-2p)u
  59. .ll \\n(LLu-\\n(INu
  60. .ev
  61. .ev 2
  62. .    \" where the table of contents is stored
  63. .ps \\n(PS
  64. .vs \\n(VSu
  65. .ev
  66. .TA
  67. ..
  68. .\"
  69. .    \" string for footnote numebering. Note that the increment takes place here
  70. .    \" note that Fn is defined in texttroff to get the body font
  71. .ds * \v'-.3v'\\*(Fn\s-3\\n+F\s0\fP\v'.3v'
  72. .ig
  73.     Running headers & footers.
  74.     These will be called from the header & footer macro
  75.     halfway the current margins in the macros PT & BT
  76.     Note that we don't use the page counter (%) directly.
  77.     We stick the value in register PN.
  78.     This allows for changing the format of the page number with
  79.     the .af request without screwing up troff
  80.  
  81.     We will enable the possibility to change on odd & even pages eventually
  82. ..
  83. .\"
  84. .    \" PT - Page Trap & Bottom Trap macro
  85. .de PT
  86. .if \\n(Tc=2 .br
  87. .po +\\n(INu
  88. .pc %
  89. .ie \\n(Tc=3 .nr PN \\n%-\\n(Pc
  90. .el .nr PN \\n%
  91. .nr Pn \\n%
  92. .if \\n(Pn>1 .if e .tl '\\*(LT'\\*(CT'\\*(RT'
  93. .if \\n(Pn>1 .if o .tl '\\*(RT'\\*(CT'\\*(LT'
  94. .po
  95. ..
  96. .    \" default footer string definitions 
  97. .po +\\n(INu
  98. .de BT
  99. .nr PF \\n(.f
  100. .nr PX \\n(.s
  101. .ft 1
  102. .ps \\n(PS
  103. .lt \\n(LTu
  104. .po +\\n(INu
  105. .if e .tl '\\*(LB'\\*(CB'\\*(RB'
  106. .if o .tl '\\*(RB'\\*(CB'\\*(LB'
  107. .ft \\n(PF
  108. .ps \\n(PX
  109. .po
  110. .if \\n(Tc=2 \{\
  111. .    nr Pc \\n%
  112. .    nr Tc 3
  113. .    af PN i
  114. .    TC
  115. .\}
  116. ..
  117. .    \" default header string definitions
  118. .ds CT - \\n(PN -
  119. .\"
  120. .\"
  121. .    \" NP - header macro
  122. .ig
  123.     print the header halfway the margins
  124.     only print when not on the first page
  125. ..
  126. .de NP
  127. .\".tm in NP page \\n% PO \\n(PO .o \\n(.o
  128. .nr PF \\n(.f
  129. .nr PX \\n(.s
  130. .ft 1
  131. .ps \\n(PS
  132. 'sp |\\n(HMu/2u
  133. .if !\\n%=0 .PT
  134. .ps \\n(PX
  135. .ft \\n(PF
  136. 'sp |\\n(HMu
  137. .nr Fc 0 1    \" init footnote count
  138. .nr Fp 0-\\n(HMu    \" current footer place
  139. .ch FO -\\n(HMu    \" reset footer trap
  140. .if \\n(dn .Fz    \" proces left over footnote
  141. .ns    \" no space mode
  142. ..
  143. .\"
  144. .    \" FO - footer macro
  145. .de FO
  146. .nr dn 0    \" zero last diversion size
  147. .if \\n(Fc \{\
  148. .    ev 1        \" expand footnotes in ev1
  149. .\".if '\\n(.z'Fy' .tm in overlow .i \\n(.i
  150. .in \\n(INu        \" set indentation to the one for the page
  151. .    nf        \" retain vertical size
  152. .    FN        \" dump the footnotes
  153. .            \" remove them; Don't put a comment on the next line
  154. .            \" with .rm, some troffs go into an infinite loop
  155. .    rm FN
  156. .\".if '\\n(.z'Fy' .tm in overlow .i \\n(.i
  157. .    if \\n(.zFy .di    \"end overflow diversion
  158. .    nr Fc 0        \" disable fx
  159. .    in 0        \" clear indentation
  160. .ev
  161. .\}
  162. .        \" pop environment
  163. 'bp
  164. ..
  165. ."
  166. .\"    Fx - process footnote overflow
  167. .\"
  168. .de Fx
  169. .if \\n(Fc \{\
  170. .    \" the foonote didn't fit so
  171. .di Fy    \" divert the overflow into Fy (we are still in env 1, so nofill mode)
  172. .    \" since we are in nofill mode and head indentation set,
  173. .in 0    \" set no indentation, so we don't indent twice
  174. .\}
  175. ..
  176. .\"
  177. .\"    FS - Footnote Start
  178. .de FS
  179. .da FN    \" divert (or append) footnote
  180. .ev 1    \" in environment 1
  181. .if \\n+(Fc=1 .FM    \" if first include seperator
  182. .fi    \" process in fill mode
  183. .if !\\n(Fo .FP    \" Footnote paragraph if not processing overflow
  184. ..
  185. .\"
  186. .    \" FP - footnote paragraph
  187. .de FP
  188. .sp \\n(FSu
  189. \v'-.3'\s-3\\nF\s0\v'.3'\|\c
  190. ..
  191. .\"
  192. .\"    FE - Footnote End
  193. .de FE
  194. .br        \" flush the output buffer
  195. .nr Sv \\n(.v    \" save baselinespacing of this env
  196. .ev        \" pop env
  197. .di        \" end the diversion
  198. .nr Fp -\\n(dn    \" new footer position
  199. .if \\n(Fc=1 .nr Fp -(\\n(.v-\\n(Sv)    \" For Separator
  200. .ch FO \\n(Fpu    \" change the trap, Fp is negative
  201. .    \" See whether the stuff really fits.
  202. .    \"if not change trap and we overflow
  203. .if (\\n(nl+1v)>(\\n(.p+\\n(Fp) .ch FO \\n(nlu+1v    \" it didn't fit,
  204. .    \" so fire the FO macro on the next line
  205. ..
  206. .\"
  207. .    \" FM - footnote separator one inch line
  208. .de FM
  209. \l'1i'
  210. .br
  211. ..
  212. .\"
  213. .\"    Fz - process footnote overflow
  214. .de Fz
  215. .nr Fo 1
  216. .FS
  217. .nf    \" is already processed, so keep size
  218. .Fy    \" where Fx put it
  219. .nr Fo 0
  220. .FE
  221. ..
  222. .\"
  223. .\"    HE - next thing will be a header
  224. .\" minimalistic widow control in HE macro.
  225. .\" We aks for a couple of lines with the .ne statement, will trigger the
  226. .\" bottom of page trap on the moment when there is no space 
  227. .de HE
  228. .ne 1.5i
  229. ..
  230. .\"
  231. .\"    IC - in table of contents
  232. .\"    $1 type of header $3 number, $2 text
  233. .\"
  234. .de IC
  235. .nr Tc 1    \"flag that we have a contents
  236. .ev 2
  237. .if !'\\$3'NO' \{\
  238. .    nr Tx \w'\\$3\0'u
  239. .    if \\n(Tx>\\n(Ta .nr Ta \\n(Tx
  240. .\}
  241. .nr Tp \w'\0\\n(PN'u
  242. .da Tc
  243. \\!.xx "\\$1" "\\$2" \\$3 \\n(PN
  244. .br
  245. .di
  246. .ev
  247. ..
  248. .\"
  249. .\"    An item in the table of contents
  250. .de xx
  251. .if \\$1=1 .sp .5
  252. .ie !'\\$3'NO' \\$3\t\\$2\a\t\\$4
  253. .el .ie \\n(Ta \&\t\\$2\a\t\\$4
  254. .el \&\\$2\a\t\\$4
  255. ..
  256. .\"    EM
  257. .\" check for work at end of file
  258. .de EM
  259. .if \\n(Tc \{\
  260. \c
  261. .nr Tc 2
  262. .\}
  263. .\"tm EM called, Tc: \\n(Tc
  264. ..
  265. .\" do the things we want at the end of the paper
  266. .de TC
  267. .\"tm TC called
  268. 'bp
  269. .ft B
  270. .\".tm tabel of contents
  271. .ce
  272. .rs
  273. .sp
  274. .ti -\\n(INu
  275. \s+2Table of Contents\s0
  276. .sp 2
  277. .ft R
  278. .nf
  279. .ev 2
  280. .    \" where the table of contents is stored
  281. .nf
  282. .nr Tb \\n(LLu-\\n(Tpu-\\n(INu
  283. .nr c \w'1.1.1.1\0'u
  284. .ie \\n(Ta .ta \\n(Tau \\n(Tbu \\n(LLu-\\n(INuR
  285. .el .ta \\n(Tbu \\n(LLu-\\n(INuR
  286. .in \\n(INu
  287. .Tc
  288. .ev
  289. ..
  290. .\"
  291. .\"    set end macro
  292. .em EM
  293. .\" in texttroff .IZ
  294. .\" in texttroff .RS
  295. .\"
  296. .\"
  297. .\"
  298. .\" Begin of the PSmacros, coutesy of fred hansen (I believe)
  299. .\"
  300. .nr zT 0
  301. .if  "\*(.T"postscript"  'nr zT 1
  302. .if  "\*(.T"psc"  'nr zT 1
  303. .de PB
  304. 'ne \\$2p
  305. 'nr zw \\n(.l-\\n(.k-1m-\\$1p
  306. 'nr zH \\n(.k
  307. 'nr zV \\n(.d
  308. 'if  \\n(zT  \\{\\
  309. 'ie  !\\n(zw  \\{\\
  310. 'nr zx \\n(.l-\\$1p-10m
  311. 'nr zV \\n(zV+1v
  312. .sp 0
  313. \\v'-.75v'\\ \\v'+.75v'\\c\\}
  314. 'el \\{\\
  315. 'nr zx \\n(zw-10m
  316. \\v'-.75v'\\ \\v'+.75v'\\c\\}
  317. .sp |\\n(zVu
  318. 'if ((\\n(zx<=0)&(\\$2p>0.75v)) \\x'\\$2p-0.75v'\\c
  319. \\!%
  320. \\!%!
  321. \\!  PB
  322. 'if \\n(.j=3 \\{\\
  323. \\!    /troffadjust { neg 2 idiv } def
  324. 'ss\\}
  325. 'if \\n(.j=5 \\{\\
  326. \\!    /troffadjust { neg } def
  327. 'ss\\}
  328. 'if \\n(.j<3 \\{\\
  329. \\!    /troffadjust { pop 0 } def
  330. 'ss\\}\\}
  331. ..
  332. .de PE
  333. 'if \\n(zT \\{\\
  334. \\!  PE
  335. \\!.
  336. 'ie \\n(zx \\{\\
  337. 'if (\\$2p>0.75v) \\x'\\$2p-0.75v'\\c
  338. \\h'-\\n(.ku+\\n(zHu+\\$1p'\\c\\}
  339. 'el  .br\\}
  340. 'if !\\n(zT \\{\\
  341. 'if  !\\n(zw  \\{\\
  342.  \\h'-\\n(.k'\\ \\h'-\\n(.w'\\c
  343. .sp -1\\}
  344. \\x'\\$2p-0.75v'\\v'-.75v'\\D'l \\$1p \
  345. 0.0i'\\D'l 0.0i \\$2p'\\D'l -\\$1p 0.0i'\\D'l 0.0i \
  346. -\\$2p'\\v'+.75v'\\h'\\$1p'\\c\\}
  347. ..
  348. .\"
  349. .\" End of PSmacros
  350. .\"
  351. .\"
  352. .\" ix macro for index production. 
  353. .\"
  354. .de ix
  355. .ie '\\n(.z'' .tm ix: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9    \\n%
  356. .el \\!.ix \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9    \\n%
  357. ..
  358. .\"
  359. .\" End of ix macro
  360. .\"
  361. .IZ
  362. .nr IN 36p
  363. .nr LT 432p
  364. .nr PO 54p
  365. .br
  366. .ad b
  367. 'ft R
  368. .nr PS 12
  369. .ps \n(PS
  370. .nr VS 14p
  371. .vs \n(VSu
  372. .nr EN 8n
  373. .sp 0.5i
  374. .nr DP 0
  375. .ds Fn \fR
  376. .ds HF R
  377. .nr HS \n(.s
  378. .ds FF R
  379. .nr FS \n(.s
  380. .RS
  381. .nh
  382. .OC
  383. .ds Cl Release Notes
  384. .ll 6.75i
  385. .po .75i
  386. .nr Dr 1
  387. .nr DP 0
  388. .ds BU \s-2\(bu\s0
  389. .ds EM \(em
  390. .if\n(mo-0 .ds DT January
  391. .if\n(mo-1 .ds DT February
  392. .if\n(mo-2 .ds DT March
  393. .if\n(mo-3 .ds DT April
  394. .if\n(mo-4 .ds DT May
  395. .if\n(mo-5 .ds DT June
  396. .if\n(mo-6 .ds DT July
  397. .if\n(mo-7 .ds DT August
  398. .if\n(mo-8 .ds DT September
  399. .if\n(mo-9 .ds DT October
  400. .if\n(mo-10 .ds DT November
  401. .if\n(mo-11 .ds DT December
  402. .asDT " \n(dy, 19\n(yr
  403. .ds LT \*(Cl
  404. .ds CT NIH Class Library Revision 3.0
  405. .ds RT \*(Cl
  406. .ds LB Page \\n%
  407. .ds RB \*(DT
  408. .tl `\*(LT`\*(CT`\*(RT`
  409. .ps
  410. .ft P
  411. 'sp 0.3i
  412. .OC
  413. .br
  414. .TA
  415. .HE
  416. .br
  417. .ad l
  418. 'ft B
  419. .ps 14
  420. .OC
  421. .sv 1
  422. .vs 16
  423. INTRODUCTION
  424. .ad b
  425. 'ft R
  426. .ps 12
  427. .OC
  428. .sp 1
  429. .vs 14
  430. These are the release notes for Revision 3.0 of the NIH Class Library.
  431. This release contains the following classes:\fB
  432. .OC
  433. .sp 1
  434. NIHCL\fR---Library Static Member Variables and Functions
  435. .OC
  436. .br
  437.     \fBObject\fR---Root of the NIH Class Library Inheritance Tree
  438. .OC
  439. .br
  440.         \fBBitset\fR---Set of Small Integers (like Pascal's type SET)
  441. .OC
  442. .br
  443.         \fBClass\fR---Class Descriptor
  444. .OC
  445. .br
  446.         \fBCollection\fR---Abstract Class for Collections
  447. .OC
  448. .br
  449.             \fBArraychar\fR---Byte Array
  450. .OC
  451. .br
  452.             \fBArrayOb\fR---Array of Object Pointers
  453. .OC
  454. .br
  455.             \fBBag\fR---Unordered Collection of Objects
  456. .OC
  457. .br
  458.             \fBSeqCltn\fR---Abstract Class for Ordered, Indexed Collections
  459. .OC
  460. .br
  461.                 \fBHeap\fR---Min-Max Heap of Object Pointers
  462. .OC
  463. .br
  464.                 \fBLinkedList\fR---Singly-Linked List
  465. .OC
  466. .br
  467.                 \fBOrderedCltn\fR---Ordered Collection of Object Pointers
  468. .OC
  469. .br
  470.                     \fBSortedCltn\fR---Sorted Collection
  471. .OC
  472. .br
  473.                         \fBKeySortCltn\fR---Keyed Sorted Collection
  474. .OC
  475. .br
  476.                 \fBStack\fR---Stack of Object Pointers
  477. .OC
  478. .br
  479.             \fBSet\fR---Unordered Collection of Non-Duplicate Objects
  480. .OC
  481. .br
  482.                 \fBDictionary\fR---Set of Associations
  483. .OC
  484. .br
  485.                     \fBIdentDict\fR---Dictionary Keyed by Object Address
  486. .OC
  487. .br
  488.                 \fBIdentSet\fR---Set Keyed by Object Address
  489. .OC
  490. .br
  491.         \fBDate\fR---Gregorian Calendar Date
  492. .OC
  493. .br
  494.         \fBFDSet\fR---Set of File Descriptors for Use with \fCselect(2)\fR System Call
  495. .OC
  496. .br
  497.         \fBFloat\fR---Floating Point Number
  498. .OC
  499. .br
  500.         \fBFraction\fR---Rational Arithmetic
  501. .OC
  502. .br
  503.         \fBInteger\fR---Integer Number Object
  504. .OC
  505. .br
  506.         \fBIterator\fR---Collection Iterator
  507. .OC
  508. .br
  509.         \fBLink\fR---Abstract Class for LinkedList Links
  510. .OC
  511. .br
  512.             \fBLinkOb\fR---Link Containing Object Pointer
  513. .OC
  514. .br
  515.             \fBProcess\fR---Co-routine Process Object
  516. .OC
  517. .br
  518.                 \fBHeapProc\fR---Process with Stack in Free Store
  519. .OC
  520. .br
  521.                 \fBStackProc\fR---Process with Stack on \fCmain()\fR Stack
  522. .OC
  523. .br
  524.         \fBLookupKey\fR---Abstract Class for Dictionary Associations
  525. .OC
  526. .br
  527.             \fBAssoc\fR---Association of Object Pointers
  528. .OC
  529. .br
  530.             \fBAssocInt\fR---Association of Object Pointer with Integer
  531. .OC
  532. .br
  533.         \fBNil\fR---The Nil Object
  534. .OC
  535. .br
  536.         \fBPoint\fR---X-Y Coordinate Pair
  537. .OC
  538. .br
  539.         \fBRandom\fR---Random Number Generator
  540. .OC
  541. .br
  542.         \fBRange\fR---Range of Integers
  543. .OC
  544. .br
  545.         \fBRectangle\fR---Rectangle Object
  546. .OC
  547. .br
  548.         \fBScheduler\fR---Co-routine Process Scheduler
  549. .OC
  550. .br
  551.         \fBSemaphore\fR---Process Synchronization
  552. .OC
  553. .br
  554.         \fBSharedQueue\fR---Shared Queue of Objects
  555. .OC
  556. .br
  557.         \fBString\fR---Character String
  558. .OC
  559. .br
  560.             \fBRegex\fR---Regular Expression
  561. .OC
  562. .br
  563.         \fBTime\fR---Time of Day
  564. .OC
  565. .br
  566.         \fBVector\fR---Abstract Class for Vectors
  567. .OC
  568. .br
  569.             \fBBitVec\fR---Bit Vector
  570. .OC
  571. .br
  572.             \fBByteVec\fR---Byte Vector
  573. .OC
  574. .br
  575.             \fBShortVec\fR---Short Integer Vector
  576. .OC
  577. .br
  578.             \fBIntVec\fR---Integer Vector
  579. .OC
  580. .br
  581.             \fBLongVec\fR---Long Integer Vector
  582. .OC
  583. .br
  584.             \fBFloatVec\fR---Floating Point Vector
  585. .OC
  586. .br
  587.             \fBDoubleVec\fR---Double-Precision Floating Point Vector
  588. .OC
  589. .br
  590.     \fBOIOifd\fR---File Descriptor Object I/O \fCreadFrom()\fR Formatting
  591. .OC
  592. .br
  593.     \fBOIOin\fR---Abstract Class for Object I/O \fCreadFrom()\fR Formatting
  594. .OC
  595. .br
  596.         \fBOIOistream\fR---Abstract Class for Stream Object I/O \fCreadFrom()\fR Formatting
  597. .OC
  598. .br
  599.             \fBOIOnihin\fR---Stream Object I/O \fCreadFrom()\fR Formatting
  600. .OC
  601. .br
  602.     \fBOIOofd\fR---File Descriptor Object I/O \fCstoreOn()\fR Formatting
  603. .OC
  604. .br
  605.     \fBOIOout\fR---Abstract Class for Object I/O \fCstoreOn()\fR Formatting
  606. .OC
  607. .br
  608.         \fBOIOostream\fR---Abstract Class for Stream Object I/O \fCstoreOn()\fR Formatting
  609. .OC
  610. .br
  611.             \fBOIOnihout\fR---Stream Object I/O \fCstoreOn()\fR Formatting
  612. .OC
  613. .br
  614.     \fBReadFromTbl\fR---Tables used by Object I/O \fCreadFrom()\fR
  615. .OC
  616. .br
  617.     \fBStoreOnTbl\fR---Tables used by Object I/O \fCstoreOn()\fR
  618. .HE
  619. .br
  620. .ad l
  621. 'ft B
  622. .ps 14
  623. .OC
  624. .sp 2
  625. .vs 16
  626. CHANGES BETWEEN OOPS V2R2 AND NIHCL R3.0
  627. .ad b
  628. 'ft R
  629. .ps 12
  630. .OC
  631. .sp 1
  632. .vs 14
  633. This section highlights the most significant changes that have been made since the 
  634. previous release.  It is by no stretch of the imagination complete.
  635. .HE
  636. .br
  637. .ad l
  638. 'ft B
  639. .OC
  640. .sp 1
  641. Library name changed from "OOPS" to "NIH Class Library" (NIHCL)
  642. .ad b
  643. 'ft R
  644. .OC
  645. .sp 1
  646. Since there's too many things called "OOPS" these days, we've changed the name of 
  647. our library to the "NIH Class Library".  All file and C++ names containing "OOPS" have 
  648. been changed, often just by substituting "NIHCL" for "OOPS".
  649. .HE
  650. .br
  651. .ad l
  652. 'ft B
  653. .OC
  654. .sp 1
  655. Class NIHCL
  656. .ad b
  657. 'ft R
  658. .OC
  659. .sp 1
  660. With the introduction of static member functions and (useful) static member variables 
  661. in R2.0, it is now possible to eliminate most global names.  In R3.0, we've gathered 
  662. many previously global functions and variables and made them static members of a new 
  663. class, \fCNIHCL\fR, which is the base class of \fCObject\fR.  Here's a list of the public functions:
  664. 'in 72p
  665. .br
  666. .ad l
  667. 'ft C
  668. .ps 10
  669. .OC
  670. .sp 1
  671. .vs 12
  672. static class NIHCL {
  673. .OC
  674. .br
  675. // ...
  676. .OC
  677. .br
  678. public:             // static member functions
  679. .OC
  680. .br
  681.     static unsigned char charBitMask(int i);
  682. .OC
  683. .br
  684.     static unsigned short shortBitMask(int i);
  685. .OC
  686. .br
  687.     static unsigned int intBitMask(int i);
  688. .OC
  689. .br
  690.     static unsigned char bitCount(int i);
  691. .OC
  692. .br
  693.     static unsigned char bitReverse(int i);
  694. .OC
  695. .br
  696.     static void initialize();           // library initialization
  697. .OC
  698. .br
  699.     static bool initialized();          // library initialized?
  700. .OC
  701. .br
  702.     static void setError(int error, int sev ...);
  703. .OC
  704. .br
  705. } NIHCL_init;
  706. 'in 36p
  707. .ad b
  708. 'ft R
  709. .ps 12
  710. .OC
  711. .sp 1
  712. .vs 14
  713. Since all NIH Library classes inherit these members, their member functions can use 
  714. these names without needing to specify a scope qualifier, except to resolve ambiguities.  
  715. However, non-member functions and member functions of classes not derived from \fCNIHCL\fR 
  716. can access them with the \fCNIHCL\fR scope qualifier; for example:
  717. 'in 72p
  718. .br
  719. .ad l
  720. 'ft C
  721. .ps 10
  722. .OC
  723. .sp 1
  724. .vs 12
  725. NIHCL::setError(ERROR_CODE, DEFAULT);
  726. 'in 36p
  727. .ad b
  728. 'ft R
  729. .ps 12
  730. .HE
  731. .br
  732. .ad l
  733. 'ft B
  734. .OC
  735. .sp 1
  736. .vs 14
  737. Optional support for multiple inheritance
  738. .ad b
  739. 'ft R
  740. .OC
  741. .sp 1
  742. The NIH Class Library can be compiled to support Multiple Inheritance (MI) by defining 
  743. the preprocessor symbol \fCMI\fR.  \fIAll classes linked together in a program must all have 
  744. been compiled with the same \f(COMI\fI option setting\fR.  The major effect of this switch is 
  745. that all classes derived from \fCObject\fR specify it as a virtual base class.  Since C++ 
  746. does not permit a pointer to a virtual base class to be cast down to a pointer to a 
  747. derived class, the new \fCDECLARE_MEMBERS\fR macro defines an overloaded family of static 
  748. member functions named \fCcastDown()\fR that can perform this conversion. (If \fCMI\fR is not enabled, \fC
  749. castDown()\fR becomes an ordinary pointer cast.)
  750. .OC
  751. .sp 1
  752. The \fCcastDown()\fR functions all call the function \fC_castDown()\fR to perform the pointer 
  753. conversion.  If a class has only a single base class, it uses the \fCDEFINE_CLASS\fR and \fC
  754. DEFINE_ABSTRACT_CLASS\fR preprocessor macros as before, and these generate an  implementation 
  755. of \fC_castDown()\fR suitable for the single inheritance case.  If a class has multiple base 
  756. classes, it uses the new \fCDEFINE_CLASS_MI\fR and \fCDEFINE_ABSTRACT_CLASS_MI\fR macros, which 
  757. do \fInot\fR generate \fC_castDown()\fR---the class provider must supply a definition as described 
  758. in \fCTemplate_c\fR.
  759. .OC
  760. .sp 1
  761. All \fCreadFrom()\fR constructors must specify the \fCreadFrom()\fR constructor for the virtual 
  762. base class \fCObject\fR in their initialization lists when \fCMI\fR is enabled.  See \fCTemplate_h\fR 
  763. for details.
  764. .OC
  765. .sp 1
  766. If you use virtual base classes in conjunction with the NIH Class Library, you must 
  767. take care when implementing the \fCdeepCopy()\fR and \fCstoreOn()\fR operations that a virtual 
  768. base class's member variables are only deepened or stored once.  The library provides 
  769. the functions \fCdeepenVBase()\fR and \fCstoreVBaseOn()\fR to help with this.  Call \fCdeepenVBase()\fR 
  770. instead of \fCdeepenShallowCopy()\fR to deepen the member variables of a virtual base class, 
  771. and call \fCstoreVBaseOn()\fR instead of \fCstorer()\fR to store the member variables of a virtual 
  772. base class.
  773. .br
  774. .ad l
  775. 'ft CB
  776. .OC
  777. .sp 1
  778. DECLARE_MEMBERS
  779. .HE
  780. 'ft B
  781. \c
  782.  macro
  783. .ad b
  784. 'ft R
  785. .OC
  786. .sp 1
  787. The new DECLARE_MEMBERS preprocessor macro generates the declarations for the class 
  788. descriptor and most of the member functions that all NIH Library classes must provide, 
  789. including:
  790. 'in 72p
  791. .br
  792. .ad l
  793. 'ft C
  794. .ps 10
  795. .OC
  796. .sp 1
  797. .vs 12
  798. private:
  799. .OC
  800. .br
  801.     static Class classDesc;        // class descriptor
  802. .OC
  803. .br
  804. public:\f(CO
  805. .OC
  806. .br
  807.     classname\fC* castDown(Object*);
  808. .OC
  809. .br
  810.     const \f(COclassname\fC* castDown(const Object*);
  811. .OC
  812. .br
  813.     \f(COclassname\fC& castDown(Object&);
  814. .OC
  815. .br
  816.     const \f(COclassname\fC& castDown(const Object&);
  817. .OC
  818. .br
  819.     static const Class* desc();        // return class descriptor
  820. .OC
  821. .br
  822.     static \f(COclassname\fC* readFrom(OIOin&);
  823. .OC
  824. .br
  825.     static \f(COclassname\fC* readFrom(OIOifd&);
  826. .OC
  827. .br
  828.     \f(COclassname\fC(OIOin&);            // readFrom() constructors
  829. .OC
  830. .br
  831.     \f(COclassname\fC(OIOout&);
  832. .OC
  833. .br
  834.     virtual const Class* isA() const;
  835. .OC
  836. .br
  837.     virtual Object* shallowCopy() const;
  838. .OC
  839. .br
  840.     virtual void* _castdown(const Class&) const;
  841. .OC
  842. .br
  843. protected:
  844. .OC
  845. .br
  846.    void deepenVBase();
  847. .OC
  848. .br
  849.     void storeVBaseOn(OIOofd&) const;    // store virtual base class
  850. .OC
  851. .br
  852.     void storeVBaseOn(OIOout&) const;
  853. .OC
  854. .br
  855. private:
  856. .OC
  857. .br
  858.     static Object* reader(OIOin& strm);
  859. .OC
  860. .br
  861.     static Object* reader(OIOifd& fd);
  862. 'in 36p
  863. .ad b
  864. 'ft R
  865. .ps 12
  866. .OC
  867. .sp 1
  868. .vs 14
  869. The DECLARE_MEMBERS macro takes a single argument, the name of the class being declared.
  870. .HE
  871. .br
  872. .ad l
  873. 'ft B
  874. .OC
  875. .sp 1
  876. New implementation of Process classes
  877. .ad b
  878. 'ft R
  879. .OC
  880. .sp 1
  881. In R3.0, class \fCProcess\fR has two derived classes, \fCStackProc\fR and \fCHeapProc\fR, which serve 
  882. as the base classes for client processes.  \fCStackProc\fR and \fCHeapProc\fR differ in where a 
  883. process's stack is located when the process is running: a \fCStackProc\fR has its stack located 
  884. on the real stack in the stack segment, while a \fCHeapProc\fR has its stack in the free 
  885. storage area in the data segment.  A context switch of a \fCStackProc\fR involves copying 
  886. the active part of the current process's stack into a save area, then copying the saved 
  887. stack of the new process onto the real stack.  A context switch of a \fCHeapProc\fR involves 
  888. simply resetting the processor's stack pointer and frame pointer registers to point 
  889. to the new stack, so a \fCStackProc\fR context switch is much slower than a \fCHeapProc\fR context 
  890. switch.  However, using \fCHeapProc\fRs tends to break debuggers, which usually can't cope 
  891. with the bizarre stack location, so programs using them are difficult to debug.  Also, 
  892. the stack area for a \fCHeapProc\fR must be specified when it is constructed, and must be 
  893. large enough to hold the largest stack that can occur anytime during execution.  In 
  894. contrast, the stack save area for a \fCStackProc\fR grows in size if necessary and must only 
  895. be large enough to hold the largest stack in use when the process is suspended.  Thus, 
  896. the tradeoff is debuggability and reduced memory requirement vs. speed.
  897. .OC
  898. .sp 1
  899. Fiddling with the stack area and machine registers is something you can't do directly 
  900. from C++, so processes are inherently non-portable.  The R3.0 implementation of the \fC
  901. Process\fR classes attempts to use the C library routines \fCsetjmp()\fR, \fClongjmp()\fR, and \fCalloca()\fR 
  902. to do context switching.  While this works on many machines, you may need to write 
  903. your own versions of these routines for machines on which it doesn't.  See the section 
  904. on \fIPORTING THE PROCESS CLASSES\fR for instructions.
  905. .HE
  906. .br
  907. .ad l
  908. 'ft B
  909. .OC
  910. .sp 1
  911. External \f(CBclass_\f(BIclassname\fB identifiers eliminated
  912. .ad b
  913. 'ft R
  914. .OC
  915. .sp 1
  916. The class descriptor for each class no longer has an external identifier of the form \fC
  917. class_\fIclassname\fR.  Instead, the class descriptor is a static member variable of each 
  918. class, and the inline static member function \fCdesc()\fR returns its address.
  919. .HE
  920. .br
  921. .ad l
  922. 'ft B
  923. .OC
  924. .sp 1
  925. Changes to Object I/O
  926. .ad b
  927. 'ft R
  928. .OC
  929. .sp 1
  930. Previous releases of OOPS have a fundamental problem in the way they handle object 
  931. I/O for classes with member variables that are class instances.  For example, consider 
  932. an OOPS class \fCX\fR with a member variable of class \fCM\fR, where \fCM\fR is also an OOPS class:
  933. 'in 72p
  934. .br
  935. .ad l
  936. 'ft C
  937. .ps 10
  938. .OC
  939. .sp 1
  940. .vs 12
  941. class X : public BASE {
  942. .OC
  943. .br
  944.     M m;    // a member class instance
  945. .OC
  946. .br
  947.     M* p;   // a member pointer to a class instance
  948. .OC
  949. .br
  950.     int i;  // a fundamental type
  951. .OC
  952. .br
  953. // ...
  954. .OC
  955. .br
  956. };
  957. 'in 36p
  958. .ad b
  959. 'ft R
  960. .ps 12
  961. .OC
  962. .sp 1
  963. .vs 14
  964. Previous releases implement \fCX::storer()\fR and\fC X::X(istream&,X&)\fR as follows:
  965. 'in 72p
  966. .br
  967. .ad l
  968. 'ft C
  969. .ps 10
  970. .OC
  971. .sp 1
  972. .vs 12
  973. void X::storer(ostream& strm)
  974. .OC
  975. .br
  976. {
  977. .OC
  978. .br
  979.     BASE::storer(strm);
  980. .OC
  981. .br
  982.     m.storeOn(strm);
  983. .OC
  984. .br
  985.     p->storeOn(strm);
  986. .OC
  987. .br
  988.     strm << i << " ";
  989. .OC
  990. .br
  991. }
  992. .OC
  993. .sp 1
  994. void X::X(istream&strm, X& where)
  995. .OC
  996. .br
  997.     : (strm,where)
  998. .OC
  999. .br
  1000. {
  1001. .OC
  1002. .br
  1003.     this = &where;
  1004. .OC
  1005. .br
  1006.     readFrom(strm,"M",m);
  1007. .OC
  1008. .br
  1009.     p = (M*)readFrom(strm,"M");
  1010. .OC
  1011. .br
  1012.     strm >> i;
  1013. .OC
  1014. .br
  1015. }
  1016. .OC
  1017. .sp 1
  1018. void X::storer(FileDescTy& fd)
  1019. .OC
  1020. .br
  1021. {
  1022. .OC
  1023. .br
  1024.     BASE::storer(fd);
  1025. .OC
  1026. .br
  1027.     m.storeOn(fd);
  1028. .OC
  1029. .br
  1030.     p->storeOn(fd);
  1031. .OC
  1032. .br
  1033.     storeBin(fd,i);
  1034. .OC
  1035. .br
  1036. }
  1037. .OC
  1038. .sp 1
  1039. void X::X(FileDescTy& fd, X& where)
  1040. .OC
  1041. .br
  1042.     : (fd,where)
  1043. .OC
  1044. .br
  1045. {
  1046. .OC
  1047. .br
  1048.     this = &where;
  1049. .OC
  1050. .br
  1051.     readFrom(fd,"M",m);
  1052. .OC
  1053. .br
  1054.     p = (M*)readFrom(fd,"M");
  1055. .OC
  1056. .br
  1057.     readBin(fd,i);
  1058. .OC
  1059. .br
  1060. }
  1061. 'in 36p
  1062. .ad b
  1063. 'ft R
  1064. .ps 12
  1065. .OC
  1066. .sp 1
  1067. .vs 14
  1068. The problem is that this constructor first initializes \fCm\fR using the \fCM::M()\fR constructor, 
  1069. then calls \fCreadFrom()\fR, which overwrites this initialized instance with an instance 
  1070. constructed by reading \fCstrm\fR.  We didn't notice this bug earlier because, in practice, 
  1071. the problem occurs only in classes \fCRectangle\fR and \fCSharedQueue\fR, and has no obvious consequences.  
  1072. The worst that is likely to happen is that \fCM::M()\fR allocates some memory that never 
  1073. gets reclaimed.
  1074. .OC
  1075. .sp 1
  1076. Unfortunately, the fix requires some widespread changes.  But, it turns out that numerous 
  1077. other improvements become possible.  The new format for \fCstorer()\fR functions and \fCreadFrom()\fR 
  1078. constructors when not using MI is:
  1079. 'in 72p
  1080. .br
  1081. .ad l
  1082. 'ft C
  1083. .ps 10
  1084. .OC
  1085. .sp 1
  1086. .vs 12
  1087. void X::storer(OIOout& strm)
  1088. .OC
  1089. .br
  1090. {
  1091. .OC
  1092. .br
  1093.     BASE::storer(strm);
  1094. .OC
  1095. .br
  1096.     m.storeMemberOn(strm);
  1097. .OC
  1098. .br
  1099.     p->storeOn(strm);
  1100. .OC
  1101. .br
  1102.     strm << i;
  1103. .OC
  1104. .br
  1105. }
  1106. .OC
  1107. .sp 1
  1108. void X::X(OIOin& strm)
  1109. .OC
  1110. .br
  1111.     : (strm), m(strm)
  1112. .OC
  1113. .br
  1114. {
  1115. .OC
  1116. .br
  1117.     p = M::readFrom(strm);
  1118. .OC
  1119. .br
  1120.     strm >> i;
  1121. .OC
  1122. .br
  1123. }
  1124. .OC
  1125. .sp 1
  1126. void X::storer(OIOofd& fd)
  1127. .OC
  1128. .br
  1129. {
  1130. .OC
  1131. .br
  1132.     BASE::storer(fd);
  1133. .OC
  1134. .br
  1135.     m.storeMemberOn(fd);
  1136. .OC
  1137. .br
  1138.     p->storeOn(fd);
  1139. .OC
  1140. .br
  1141.     fd << i;
  1142. .OC
  1143. .br
  1144. }
  1145. .OC
  1146. .sp 1
  1147. void X::X(OIOifd& fd)
  1148. .OC
  1149. .br
  1150.     : (fd), m(fd)
  1151. .OC
  1152. .br
  1153. {
  1154. .OC
  1155. .br
  1156.     p = M::readFrom(fd);
  1157. .OC
  1158. .br
  1159.     fd >> i;
  1160. .OC
  1161. .br
  1162. }
  1163. 'in 36p
  1164. .ad b
  1165. 'ft R
  1166. .ps 12
  1167. .OC
  1168. .sp 1
  1169. .vs 14
  1170. The new format is simpler and consistent---\fCstorer()\fR functions always call \fCBASE::storer()\fR 
  1171. and \fCX::X(OIOin&)\fR constructors always call \fCBASE::BASE(OIOin&)\fR.
  1172. .HE
  1173. .br
  1174. .ad l
  1175. 'ft I
  1176. .OC
  1177. .sp 1
  1178. Public \f(COreadFrom()\fI constructor
  1179. .ad b
  1180. 'ft R
  1181. .OC
  1182. .sp 1
  1183. Since other classes in general must have access to \fCX::X(OIOin&)\fR, it must be public 
  1184. instead of protected, requiring a change to all header files.
  1185. .HE
  1186. .br
  1187. .ad l
  1188. 'ft I
  1189. .OC
  1190. .sp 1
  1191. Changes to \f(COreadFrom()
  1192. .ad b
  1193. 'ft R
  1194. .OC
  1195. .sp 1
  1196. As explained previously, calls to \fCreadFrom()\fR that specify the third argument overwrite 
  1197. an initialized instance of a class.  Since this is generally a bad thing to do, the 
  1198. third argument to \fCreadFrom()\fR has been eliminated; thus, \fCreadFrom()\fR will only return 
  1199. a pointer to an object. This form of \fCreadFrom()\fR was used to initialize member class 
  1200. instances.  These must now be initialized via the \fCreadFrom()\fR constructor in the initializer 
  1201. list, as shown in the example.  When converting old programs, these calls to \fCreadFrom()\fR 
  1202. will be flagged as errors because the three argument form of \fCreadFrom()\fR is no longer 
  1203. defined.  \fINote that when you change the \f(COreadFrom()\fI constructor, you must also change 
  1204. the corresponding \f(COstorer()\fI function to store the member using \f(COstoreMemberOn()\fI rather 
  1205. than \f(COstoreOn()\fI.\fR 
  1206. .OC
  1207. .sp 1
  1208. In previous releases, the second argument to \fCreadFrom()\fR was an optional name of the 
  1209. class of object that was expected to be read.  If the object read was of a different 
  1210. class, \fCreadFrom()\fR raised an error.  Beginning with this release, \fCreadFrom(OIOin&)\fR, 
  1211. and \fCreadFrom(OIOifd&)\fR are static member functions of each class which will also accept 
  1212. derived classes of the specified class, just as C++ allows a pointer to a derived class 
  1213. to be used instead of a pointer to a base class.  The global functions \fCreadFrom(istream, 
  1214. const char* classname)\fR and \fCreadFrom(int fd, const char* classname)\fR have been eliminated.
  1215. .br
  1216. .ad l
  1217. 'ft CO
  1218. .OC
  1219. .sp 1
  1220. istream&
  1221. .HE
  1222. 'ft I
  1223. replaced by \f(COOIOin&
  1224. 'ft I
  1225. .ad b
  1226. 'ft R
  1227. .OC
  1228. .sp 1
  1229. The type of the first (and now only) argument to the constructors called by \fCreadFrom(istream&)\fR 
  1230. has been changed from an \fCistream&\fR to an \fCOIOin&\fR.  This avoids naming conflicts with 
  1231. other constructors.  Also, \fCOIOin\fR is an abstract base class, and all input operators 
  1232. are virtual functions, so you can customize the Object I/O format by defining your 
  1233. own derived classes.   \fCOIOistream\fR and \fCOIOnihin\fR implement a format similar to the old 
  1234. OOPS format.
  1235. .br
  1236. .ad l
  1237. 'ft CO
  1238. .OC
  1239. .sp 1
  1240. ostream&
  1241. .HE
  1242. 'ft I
  1243. replaced by \f(COOIOout&
  1244. 'ft I
  1245. .ad b
  1246. 'ft R
  1247. .OC
  1248. .sp 1
  1249. The type of the argument to the \fCstorer(ostream&)\fR function has been changed  to an \fC
  1250. OIOout&\fR.  \fCOIOout\fR is an abstract base class, and all output operators are virtual functions, 
  1251. so you can customize the Object I/O format by defining your own derived classes.   \fC
  1252. OIOostream\fR and \fCOIOnihout\fR implement a format similar to the old OOPS format.
  1253. .HE
  1254. .br
  1255. .ad l
  1256. 'ft I
  1257. .OC
  1258. .sp 1
  1259. Automatic separators output by \f(COOIOostream::operator<<()
  1260. 'ft I
  1261. .ad b
  1262. 'ft R
  1263. .OC
  1264. .sp 1
  1265. It is no longer necessary to explicitly output a space after each number written in 
  1266. a \fCstorer(OIOnihout&)\fR function.  Class \fCOIOostream\fR reimplements \fCoperator<<()\fR to supply 
  1267. the space automatically.
  1268. .br
  1269. .ad l
  1270. 'ft CO
  1271. .OC
  1272. .sp 1
  1273. FileDescTy&
  1274. .HE
  1275. 'ft I
  1276. replaced by \f(COOIOifd&/OIOofd&
  1277. 'ft I
  1278. .ad b
  1279. 'ft R
  1280. .OC
  1281. .sp 1
  1282. The type of the argument to the \fCstorer(FileDescTy&)\fR function has been changed  to 
  1283. an \fCOIOofd&\fR. and the argument to the \fCreadFrom(FileDescTy&)\fR function has been changed 
  1284. to an \fCOIOifd&\fR.  \fCOIOifd\fR and \fCOIOofd\fR are not abstract classes, and their I/O operators 
  1285. are not virtual functions as in \fCOIOin\fR and \fCOIOout\fR, so using them does not incur the 
  1286. overhead of a virtual function call for each member variable.
  1287. .HE
  1288. .br
  1289. .ad l
  1290. 'ft I
  1291. .OC
  1292. .sp 1
  1293. Change to \f(COreadFrom(OIOin&)
  1294. 'ft I
  1295. .ad b
  1296. 'ft R
  1297. .OC
  1298. .sp 1
  1299. Encountering EOF during \fCreadFrom(OIOin&)\fR is now always an error.  Previous releases 
  1300. returned \fCnil\fR if the input stream was initially at the EOF.  \fCreadFrom(OIOin&)\fR now behaves 
  1301. like \fCreadFrom(OIOifd&)\fR always has.
  1302. .br
  1303. .ad l
  1304. 'ft CO
  1305. .OC
  1306. .sp 1
  1307. storeBin()
  1308. .HE
  1309. 'ft I
  1310. replaced by \f(COOIOofd::operator<<()\fI and \f(COOIOofd::put()
  1311. 'ft I
  1312. .ad b
  1313. 'ft R
  1314. .OC
  1315. .sp 1
  1316. The function \fCstoreBin(FileDescTy&, \f(COtype\fC)\fR has been replaced by \fCOIOofd::operator<<(\f(COtype\fC)\fR 
  1317. and the function \fCstoreBin(FileDescTy&, \f(COtype\fC*, unsigned)\fR has been replaced by \fCOIOofd::put(\f(COtype\fC*, 
  1318. unsigned)\fR.
  1319. .br
  1320. .ad l
  1321. 'ft CO
  1322. .OC
  1323. .sp 1
  1324. readBin()
  1325. .HE
  1326. 'ft I
  1327. replaced by \f(COOIOifd::operator>>()\fI and \f(COOIOifd::get()
  1328. 'ft I
  1329. .ad b
  1330. 'ft R
  1331. .OC
  1332. .sp 1
  1333. The function \fCreadBin(FileDescTy&, \f(COtype\fC)\fR has been replaced by \fCOIOifd::operator>>(\f(COtype\fC)\fR 
  1334. and the function \fCreadBin(FileDescTy&, \f(COtype\fC*, unsigned)\fR has been replaced by \fCOIOifd::get(\f(COtype\fC*, 
  1335. unsigned)\fR.
  1336. .br
  1337. .ad l
  1338. 'ft CO
  1339. .OC
  1340. .sp 1
  1341. read_Cstring()
  1342. .HE
  1343. 'ft I
  1344. replaced by \f(COOIOin::getCstring()
  1345. 'ft I
  1346. .ad b
  1347. 'ft R
  1348. .OC
  1349. .sp 1
  1350. The function \fCread_Cstring()\fR has been replaced by \fCOIOin::getCstring()\fR.
  1351. .br
  1352. .ad l
  1353. 'ft CO
  1354. .OC
  1355. .sp 1
  1356. store_Cstring()
  1357. .HE
  1358. 'ft I
  1359. replaced by \f(COOIOout::putCstring()
  1360. 'ft I
  1361. .ad b
  1362. 'ft R
  1363. .OC
  1364. .sp 1
  1365. The function \fCstore_Cstring()\fR has been replaced by \fCOIOout::putCstring()\fR.
  1366. .br
  1367. .ad l
  1368. 'ft CO
  1369. .OC
  1370. .sp 1
  1371. READ_OBJECT_AS_BINARY
  1372. .HE
  1373. 'ft I
  1374. eliminated
  1375. .ad b
  1376. 'ft R
  1377. .OC
  1378. .sp 1
  1379. The \fCREAD_OBJECT_AS_BINARY\fR macro has been eliminated.  Replace it with code to read 
  1380. member variables individually using \fC>>\fR and \fCget()\fR.
  1381. .br
  1382. .ad l
  1383. 'ft CO
  1384. .OC
  1385. .sp 1
  1386. STORE_OBJECT_AS_BINARY
  1387. .HE
  1388. 'ft I
  1389. eliminated
  1390. .ad b
  1391. 'ft R
  1392. .OC
  1393. .sp 1
  1394. The \fCSTORE_OBJECT_AS_BINARY\fR macro has been eliminated.  Replace it with code to store 
  1395. member variables individually using \fC<<\fR and \fCput()\fR.
  1396. .HE
  1397. .br
  1398. .ad l
  1399. 'ft B
  1400. .OC
  1401. .sp 1
  1402. Changes to the \f(CBDEFINE_CLASS\fB macro
  1403. .ad b
  1404. 'ft R
  1405. .OC
  1406. .sp 1
  1407. The new version of the \fCDEFINE_CLASS\fR macro has hooks for supporting multiple inheritance.  
  1408. Before calling the \fCDEFINE_CLASS\fR macro, you must define three preprocessor symbols: \fC
  1409. BASE_CLASSES\fR, \fCMEMBER_CLASSES\fR, and \fCVIRTUAL_BASE_CLASSES\fR.  As an example, suppose you 
  1410. are writing the implementation of a class with the following declaration:
  1411. 'in 72p
  1412. .br
  1413. .ad l
  1414. 'ft C
  1415. .ps 10
  1416. .OC
  1417. .sp 1
  1418. .vs 12
  1419. class X: public A, public virtual B {
  1420. .OC
  1421. .br
  1422.     C c;        // C is a class
  1423. .OC
  1424. .br
  1425.     D d;        // D is a class
  1426. .OC
  1427. .br
  1428. //...
  1429. .OC
  1430. .br
  1431. };
  1432. 'in 36p
  1433. .ad b
  1434. 'ft R
  1435. .ps 12
  1436. .OC
  1437. .sp 1
  1438. .vs 14
  1439. Set the symbol \fCBASE_CLASSES\fR to a list of the addresses of the class descriptors for 
  1440. the base classes of the class you are defining.  These must be in the same order as 
  1441. they appear in the class declaration:
  1442. 'in 72p
  1443. .br
  1444. .ad l
  1445. 'ft C
  1446. .ps 10
  1447. .OC
  1448. .sp 1
  1449. .vs 12
  1450. #define BASE_CLASSES A::desc(), B::desc()
  1451. 'in 36p
  1452. .ad b
  1453. 'ft R
  1454. .ps 12
  1455. .OC
  1456. .sp 1
  1457. .vs 14
  1458. Set the symbol \fCMEMBER_CLASSES\fR to a list of the addresses of the class descriptors 
  1459. for any member variables of the class that are NIH Library classes.  These must be 
  1460. in the same order as they appear in the class declaration:
  1461. 'in 72p
  1462. .br
  1463. .ad l
  1464. 'ft C
  1465. .ps 10
  1466. .OC
  1467. .sp 1
  1468. .vs 12
  1469. #define MEMBER_CLASSES C::desc(), D::desc()
  1470. 'in 36p
  1471. .ad b
  1472. 'ft R
  1473. .ps 12
  1474. .OC
  1475. .sp 1
  1476. .vs 14
  1477. If a class has no class members, define \fCMEMBER_CLASSES\fR, but give it no value.
  1478. .OC
  1479. .sp 1
  1480. Set the symbol \fCVIRTUAL_BASE_CLASSES\fR to a list of the addresses of the class descriptors 
  1481. for the virtual base classes of the class you are defining.  These must be in the same 
  1482. order as they appear in the class declaration:
  1483. 'in 72p
  1484. .br
  1485. .ad l
  1486. 'ft C
  1487. .ps 10
  1488. .OC
  1489. .sp 1
  1490. .vs 12
  1491. #define VIRTUAL_BASE_CLASSES B::desc()
  1492. 'in 36p
  1493. .ad b
  1494. 'ft R
  1495. .ps 12
  1496. .OC
  1497. .sp 1
  1498. .vs 14
  1499. If a class has no virtual base classes, define \fCVIRTUAL_BASE_CLASSES\fR, but give it no 
  1500. value.
  1501. .OC
  1502. .sp 1
  1503. Now you are ready to call the \fCDEFINE_CLASS\fR macro:
  1504. 'in 72p
  1505. .br
  1506. .ad l
  1507. 'ft C
  1508. .ps 10
  1509. .OC
  1510. .sp 1
  1511. .vs 12
  1512. DEFINE_CLASS(\f(COclassname\fC,\f(COversion\fC,\f(COidentification\fC,\f(COinitor1\fC,\f(COinitor2\fC)
  1513. 'in 36p
  1514. .ad b
  1515. 'ft R
  1516. .ps 12
  1517. 'ft I
  1518. .OC
  1519. .sp 1
  1520. .vs 14
  1521. Classname\fR is the name of the class you are defining.\fI
  1522. .OC
  1523. .sp 1
  1524. Version\fR is the version number of the class you are defining.  It should be changed 
  1525. whenever the format of the information written by the \fCstorer()\fR function changes such 
  1526. that older versions of \fCreadFrom()\fR can no longer interpret it correctly.\fI
  1527. .OC
  1528. .sp 1
  1529. Identification\fR is a character string that identifies the revision level of the implementation 
  1530. of the class.  It is simply stored in the class descriptor where you can retrieve it 
  1531. by calling the function \fCClass::ident()\fR.  The identification parameter is intended for 
  1532. use with a revision control system such as RCS or SCCS.  NIH Library classes specify 
  1533. it as the string "\fC$Header$\fR", which RCS replaces with the revision identification.\fI
  1534. .OC
  1535. .sp 1
  1536. Initor1\fR and \fIinitor2\fR are pointers to functions you may supply to perform initialization 
  1537. for the class, for example, initializing \fCstatic\fR data that the class uses.
  1538. .HE
  1539. .br
  1540. .ad l
  1541. 'ft CB
  1542. .OC
  1543. .sp 1
  1544. DEFINE_ABSTRACT_CLASS
  1545. .ad b
  1546. 'ft R
  1547. .OC
  1548. .sp 1
  1549. Abstract classes should use the new macro \fCDEFINE_ABSTRACT_CLASS\fR instead of \fCDEFINE_CLASS\fR.  \fC
  1550. DEFINE_ABSTRACT_CLASS \fRhas the same arguments as \fCDEFINE_CLASS\fR; the only difference is 
  1551. that the \fCreader()\fR functions it generates do not reference the class's object I/O constructors, 
  1552. and \fCshallowCopy()\fR is defined as a \fCderivedClassResponsibility()\fR.
  1553. .HE
  1554. .br
  1555. .ad l
  1556. 'ft B
  1557. .OC
  1558. .sp 1
  1559. Change to \f(CBClass::className()
  1560. 'ft B
  1561. .ad b
  1562. 'ft R
  1563. .OC
  1564. .sp 1
  1565. The function \fCclassName()\fR returns the name of the class of the object to which it is 
  1566. applied.  In previous releases \fCClass::className()\fR does not do this.  Instead, it returns 
  1567. the name of the class described by the class object to which it is applied.  This release 
  1568. eliminates this inconsistency: \fCclassName()\fR returns \fC"Class"\fR when applied to an instance 
  1569. of class \fCClass\fR.  The new function \fCClass::name()\fR returns the name of the class described 
  1570. by an instance of class \fCClass\fR.
  1571. .HE
  1572. .br
  1573. .ad l
  1574. 'ft B
  1575. .OC
  1576. .sp 1
  1577. New member functions of class \f(CBClass
  1578. 'ft B
  1579. .ad b
  1580. 'ft R
  1581. 'ft C
  1582. .OC
  1583. .sp 1
  1584. Class** baseClasses()\fR returns a zero-terminated array of pointers to the class descriptors 
  1585. of the base classes of this class.\fC
  1586. .OC
  1587. .sp 1
  1588. Class** memberClasses()\fR returns a zero-terminated array of pointers to the class descriptors 
  1589. of the member classes of this class.\fC
  1590. .OC
  1591. .sp 1
  1592. Class** virtualBaseClasses()\fR returns a zero-terminated array of pointers to the class 
  1593. descriptors of the virtual base classes of this class.\fC
  1594. .OC
  1595. .sp 1
  1596. unsigned long signature()\fR returns the signature of this class.  The signature of a 
  1597. class is computed by hashing the signatures of this class's base and member classes 
  1598. and the version number of this class.  It is currently used by \fCstoreOn()\fR/\fCreadFrom()\fR 
  1599. to prevent obsolete versions of objects from being read.\fC
  1600. .OC
  1601. .sp 1
  1602. const Class* Class::lookup(const char* name)\fR returns a pointer to the class descriptor 
  1603. object for the class with the specified name.  \fCClass::lookup()\fR returns 0 if the name 
  1604. is not found.
  1605. .HE
  1606. .br
  1607. .ad l
  1608. 'ft B
  1609. .OC
  1610. .sp 1
  1611. Changes to \f(CBcopy()\fB, \f(CBshallowCopy()\fB, and \f(CBdeepCopy()
  1612. 'ft B
  1613. .ad b
  1614. 'ft R
  1615. .OC
  1616. .sp 1
  1617. In previous releases, \fCshallowCopy()\fR made a bitwise copy of an object, and \fCdeepCopy()\fR 
  1618. first made a shallow copy of an object, and then called the virtual function \fCdeepenShallowCopy()\fR 
  1619. to convert the shallow copy to a deep copy.  Each class reimplemented \fCdeepenShallowCopy()\fR 
  1620. to handle any pointer member variables contained in instances of its class.
  1621. .OC
  1622. .sp 1
  1623. The problems with this approach are that (1) it is usually unsafe to make a shallow 
  1624. copy of an object that contains pointers, and (2) with Release 2.0 of the AT&T C++ 
  1625. Translator, objects may contain compiler-generated pointers which \fCdeepenShallowCopy()\fR 
  1626. cannot handle easily and portably.
  1627. .OC
  1628. .sp 1
  1629. The following changes have been made in an attempt to solve these problems:
  1630. .OC
  1631. .sp 1
  1632. Each class now reimplements the virtual function \fCshallowCopy()\fR to call the initialization 
  1633. constructor \fCX::X(const X&)\fR to make a shallow copy of an object.  The implementation 
  1634. of \fCshallowCopy()\fR is the same for all classes and is generated automatically by the \fC
  1635. DEFINE_CLASS\fR macro:
  1636. 'in 72p
  1637. .br
  1638. .ad l
  1639. 'ft C
  1640. .ps 10
  1641. .OC
  1642. .sp 1
  1643. .vs 12
  1644. Object* \f(COclassname\fC::shallowCopy()
  1645. .OC
  1646. .br
  1647. {
  1648. .OC
  1649. .br
  1650.     return new \f(COclassname\fC(*this);
  1651. .OC
  1652. .br
  1653. }
  1654. 'in 36p
  1655. .ad b
  1656. 'ft R
  1657. .ps 12
  1658. 'ft C
  1659. .OC
  1660. .sp 1
  1661. .vs 14
  1662. Object::deepCopy()\fR still calls the virtual function \fCdeepenShallowCopy()\fR to convert 
  1663. a shallow copy, now made by the initialization constructor, to a deep copy.  Since 
  1664. the shallow copy is no longer a simple bitwise copy, you may need to change \fCdeepenShallowCopy()\fR 
  1665. for some classes.
  1666. .OC
  1667. .sp 1
  1668. In previous releases, \fCcopy()\fR defaulted to \fCdeepCopy()\fR since it was unsafe for general 
  1669. use.  Beginning with this release, \fCcopy()\fR defaults to \fCshallowCopy()\fR as it does in Smalltalk-80.  
  1670. Also, \fCObject::deepCopy()\fR is no longer a virtual function.
  1671. .HE
  1672. .br
  1673. .ad l
  1674. 'ft B
  1675. .OC
  1676. .sp 1
  1677. New function \f(CBdumpOn()\fB and changes to \f(CBprintOn()
  1678. 'ft B
  1679. .ad b
  1680. 'ft R
  1681. .OC
  1682. .sp 1
  1683. To make the \fCprintOn()\fR function more useful in application programs, it has been changed 
  1684. to print minimal formatting information, the idea being that this can frequently be 
  1685. added by an application to suit its specific needs.  The virtual function \fCdumpOn()\fR 
  1686. has been added to assist in debugging by printing more detailed information than \fCprintOn()\fR.  \fC
  1687. Object::dumpOn()\fR prints the name of an object's class, a left square bracket (\fC"["\fR), 
  1688. calls \fCprintOn()\fR, then prints a matching right square bracket and a newline (\fC"]\\n"\fR).  \fC
  1689. Collection::dumpOn()\fR does the same, except that it applies \fCdumpOn()\fR to all objects 
  1690. in the collection instead of calling \fCprintOn()\fR.  Other classes reimplement \fCdumpOn()\fR 
  1691. to print more appropriate information.
  1692. .OC
  1693. .sp 1
  1694. By default, \fCdumpOn()\fR sends its output to \fCcerr\fR.  A default argument has also been added 
  1695. to \fCprintOn()\fR so that it writes to \fCcout\fR by default.
  1696. .HE
  1697. .br
  1698. .ad l
  1699. 'ft B
  1700. .OC
  1701. .sp 1
  1702. Changes to class \f(CBLink
  1703. 'ft B
  1704. .ad b
  1705. 'ft R
  1706. .HE
  1707. .br
  1708. .ad l
  1709. 'ft I
  1710. .OC
  1711. .sp 1
  1712. Constructor \f(COLink(const Link&)\fI changed to \f(COLink(Link*)
  1713. .ad b
  1714. 'ft R
  1715. .OC
  1716. .sp 1
  1717. The constructor \fCLink(const Link&)\fR, which constructs a \fCLink\fR that points to the argument \fC
  1718. Link\fR, has been replaced by the constructor \fCLink(Link*)\fR.  This change was necessary 
  1719. so that \fCshallowCopy()\fR could call the constructor \fCLink(const Link&)\fR to make a bitwise 
  1720. copy.  We suggest temporarily commenting out the declaration of this constructor in 
  1721. the file \fCLink.h\fR and recompiling the programs that depend upon it so you can easily 
  1722. detect and change the code using \fCLink(const Link&)\fR to use the new \fCLink(Link*)\fR constructor 
  1723. instead.
  1724. .OC
  1725. .sp 1
  1726. As a result of this change, \fCLink::shallowCopy()\fR is now enabled and will return a bitwise 
  1727. copy of a \fCLink\fR.
  1728. .HE
  1729. .br
  1730. .ad l
  1731. 'ft I
  1732. .OC
  1733. .sp 1
  1734. New function \f(COisListEnd()
  1735. .ad b
  1736. 'ft R
  1737. .OC
  1738. .sp 1
  1739. Class \fCLink\fR has a new member function \fCbool isListEnd()\fR, which you must use to check 
  1740. for the end of a \fCLinkedList\fR instead of checking for a pointer to \fCNil\fR.  Compile your 
  1741. program with \fC-DMI\fR to find the places where you need to make this change.
  1742. .HE
  1743. .br
  1744. .ad l
  1745. 'ft B
  1746. .OC
  1747. .sp 1
  1748. Changes to class \f(CBIterator
  1749. 'ft B
  1750. .ad b
  1751. 'ft R
  1752. 'ft C
  1753. .OC
  1754. .sp 1
  1755. Iterator::shallowCopy()\fR now produces a shallow copy with a pointer to the same collection 
  1756. bound to the original instead of to a shallow copy of the collection bound to the original, 
  1757. as in prior releases.  \fCIterator::deepCopy()\fR works as before: it produces a deep copy 
  1758. with a pointer to a deep copy of the collection bound to the original.
  1759. .OC
  1760. .sp 1
  1761. The member variable \fCObject* state\fR has been added, which collection classes can use 
  1762. to associate additional state information with an \fCIterator\fR.  For example, a collection 
  1763. class implemented as a tree structure can use \fCstate\fR to point to a \fCStack\fR used to maintain 
  1764. the state of a traversal of the tree.  The destructor for class \fCIterator\fR calls a new 
  1765. virtual function, \fCdoFinish()\fR, which a class that uses \fCstate\fR can reimplement to delete 
  1766. the state object when the \fCIterator\fR is destroyed.
  1767. .OC
  1768. .sp 1
  1769. The \fCstoreOn()\fR format has changed as a result of these modifications.
  1770. .OC
  1771. .sp 1
  1772. The function \fCObject* Iterator::operator()()\fR has been added to return a pointer to 
  1773. the current object, or 0 if there is none.
  1774. .HE
  1775. .br
  1776. .ad l
  1777. 'ft B
  1778. .OC
  1779. .sp 1
  1780. Changes to class \f(CBDictionary
  1781. 'ft B
  1782. .ad b
  1783. 'ft R
  1784. .OC
  1785. .sp 1
  1786. The return type of \fCassocAt()\fR, \fCremoveAssoc()\fR, and \fCremoveKey()\fR has been changed from \fC
  1787. LookupKey&\fR to \fCLookupKey*\fR for consistency with the return types of similar functions.  \fC
  1788. Dictionary::assocAt()\fR returns 0 instead of \fCnil\fR if the key is not found.
  1789. .br
  1790. .ad l
  1791. 'ft CB
  1792. .OC
  1793. .sp 1
  1794. const
  1795. .HE
  1796. 'ft B
  1797. arguments to member functions
  1798. .ad b
  1799. 'ft R
  1800. .OC
  1801. .sp 1
  1802. In previous versions , it was possible to convert, or "widen", a pointer to a \fCconst\fR 
  1803. object into a pointer to a non-\fCconst\fR object by adding the \fCconst\fR object to a collection 
  1804. class and then removing it:
  1805. 'in 72p
  1806. .br
  1807. .ad l
  1808. 'ft C
  1809. .ps 10
  1810. .OC
  1811. .sp 1
  1812. .vs 12
  1813. Object* f(const Object& co)
  1814. .OC
  1815. .br
  1816. {
  1817. .OC
  1818. .br
  1819.     OrderedCltn c;
  1820. .OC
  1821. .br
  1822.     c.add(co);
  1823. .OC
  1824. .br
  1825.     return c.remove(co);
  1826. .OC
  1827. .br
  1828. }
  1829. 'in 36p
  1830. .ad b
  1831. 'ft R
  1832. .ps 12
  1833. .OC
  1834. .sp 1
  1835. .vs 14
  1836. C++ R2.0 now issues error or warning messages when a \fCconst\fR pointer is converted into 
  1837. a non-\fCconst\fR pointer.  To eliminate these problems, the const arguments to some functions 
  1838. such as \fCadd()\fR have been changed to non-\fCconst\fR arguments.  These changes affect classes \fC
  1839. Assoc\fR, \fCLinkOb\fR, and the collection classes.
  1840. .OC
  1841. .sp 1
  1842. If you need to add a \fCconst\fR object to a collection class, you must use an explicit 
  1843. cast:
  1844. 'in 72p
  1845. .br
  1846. .ad l
  1847. 'ft C
  1848. .ps 10
  1849. .OC
  1850. .sp 1
  1851. .vs 12
  1852. c.add((Object&)co);
  1853. 'in 36p
  1854. .ad b
  1855. 'ft R
  1856. .ps 12
  1857. .HE
  1858. .br
  1859. .ad l
  1860. 'ft B
  1861. .OC
  1862. .sp 1
  1863. .vs 14
  1864. Change to \f(CBBag::remove(const Object&)
  1865. 'ft B
  1866. .ad b
  1867. 'ft R
  1868. 'ft C
  1869. .OC
  1870. .sp 1
  1871. Bag::remove(const Object&)\fR now returns 0 until last occurrence removed instead of 
  1872. the address of the argument to eliminate "widening" of the \fCconst\fR argument.
  1873. .br
  1874. .ad l
  1875. 'ft CB
  1876. .OC
  1877. .sp 1
  1878. shouldNotImplement()
  1879. .HE
  1880. 'ft B
  1881. functions now \f(CBprivate
  1882. 'ft B
  1883. .ad b
  1884. 'ft R
  1885. .OC
  1886. .sp 1
  1887. Virtual member functions that a class reimplements to call \fCshouldNotImplement()\fR have 
  1888. been made private so that the compiler can give an error message if a client program 
  1889. attempts to apply the function to an instance of the class.
  1890. .HE
  1891. .br
  1892. .ad l
  1893. 'ft B
  1894. .OC
  1895. .sp 1
  1896. Change to class Stack
  1897. .ad b
  1898. 'ft R
  1899. .OC
  1900. .sp 1
  1901. When a \fCStack\fR is converted to another type of collection, the objects in the \fCStack\fR 
  1902. are added to the collection from the top of the stack down.  Previous releases added 
  1903. them bottom-up.
  1904. .HE
  1905. .br
  1906. .ad l
  1907. 'ft B
  1908. .OC
  1909. .sp 1
  1910. Changes to class Heap
  1911. .ad b
  1912. 'ft R
  1913. .OC
  1914. .sp 1
  1915. The new member function \fCHeap::removeId(const Object&)\fR allows you to remove the object 
  1916. that is the \fIsame\fR (i.e. \fCisSame()\fR) as the argument object from a \fCHeap\fR.
  1917. .OC
  1918. .sp 1
  1919. Iterating over a \fCHeap\fR now visits the objects in the heap in sorted order, from smallest 
  1920. to largest.  Previous implementations visited the objects in heap order.  This affects 
  1921. the order in which \fCprintOn()\fR lists the objects in a \fCHeap\fR, for example.
  1922. .HE
  1923. .br
  1924. .ad l
  1925. 'ft B
  1926. .OC
  1927. .sp 1
  1928. Changes to class LinkedList
  1929. .ad b
  1930. 'ft R
  1931. .OC
  1932. .sp 1
  1933. The new member function \fCLinkedList::removeId(const Object&)\fR allows you to remove the 
  1934. object that is the \fIsame\fR (i.e. \fCisSame()\fR) as the argument object from a \fCLinkedList\fR.
  1935. .HE
  1936. .br
  1937. .ad l
  1938. 'ft B
  1939. .OC
  1940. .sp 1
  1941. Changes to class LookupKey
  1942. .ad b
  1943. 'ft R
  1944. .OC
  1945. .sp 1
  1946. The virtual function \fCObject* LookupKey::value() const\fR has been replaced by two virtual 
  1947. functions
  1948. 'in 72p
  1949. .br
  1950. .ad l
  1951. 'ft C
  1952. .ps 10
  1953. .OC
  1954. .sp 1
  1955. .vs 12
  1956. virtual Object* value();
  1957. .OC
  1958. .br
  1959. virtual const Object* value() const;
  1960. 'in 36p
  1961. .ad b
  1962. 'ft R
  1963. .ps 12
  1964. .OC
  1965. .sp 1
  1966. .vs 14
  1967. to prevent obtaining a non-const pointer from a const \fCLookupKey\fR.
  1968. .HE
  1969. .br
  1970. .ad l
  1971. 'ft B
  1972. .OC
  1973. .sp 1
  1974. Changes to class Arraychar
  1975. .ad b
  1976. 'ft R
  1977. .OC
  1978. .sp 1
  1979. The constructor for class \fCArraychar\fR now initializes each element of the the array 
  1980. to 0.
  1981. .OC
  1982. .sp 1
  1983. The virtual function \fCremoveAll()\fR has been implemented, which resets each element of 
  1984. the array to 0.
  1985. .HE
  1986. .br
  1987. .ad l
  1988. 'ft B
  1989. .OC
  1990. .sp 1
  1991. Changes to class Assoc
  1992. .ad b
  1993. 'ft R
  1994. .OC
  1995. .sp 1
  1996. The virtual function \fCObject* Assoc::value() const\fR has been replaced by two virtual 
  1997. functions
  1998. 'in 72p
  1999. .br
  2000. .ad l
  2001. 'ft C
  2002. .ps 10
  2003. .OC
  2004. .sp 1
  2005. .vs 12
  2006. virtual Object* value();
  2007. .OC
  2008. .br
  2009. virtual const Object* value() const;
  2010. 'in 36p
  2011. .ad b
  2012. 'ft R
  2013. .ps 12
  2014. .OC
  2015. .sp 1
  2016. .vs 14
  2017. to prevent obtaining a non-const pointer from a const \fCAssoc\fR.
  2018. .HE
  2019. .br
  2020. .ad l
  2021. 'ft B
  2022. .OC
  2023. .sp 1
  2024. Changes to class AssocInt
  2025. .ad b
  2026. 'ft R
  2027. .OC
  2028. .sp 1
  2029. The virtual function \fCObject* AssocInt::value() const\fR has been replaced by two virtual 
  2030. functions
  2031. 'in 72p
  2032. .br
  2033. .ad l
  2034. 'ft C
  2035. .ps 10
  2036. .OC
  2037. .sp 1
  2038. .vs 12
  2039. virtual Object* value();
  2040. .OC
  2041. .br
  2042. virtual const Object* value() const;
  2043. 'in 36p
  2044. .ad b
  2045. 'ft R
  2046. .ps 12
  2047. .OC
  2048. .sp 1
  2049. .vs 14
  2050. to prevent obtaining a non-const pointer from a const \fCAssocInt\fR.
  2051. .HE
  2052. .br
  2053. .ad l
  2054. 'ft B
  2055. .ps 14
  2056. .OC
  2057. .sp 2
  2058. .vs 16
  2059. CHANGES BETWEEN OOPS V2R1 AND OOPS V2R2
  2060. .ad b
  2061. 'ft R
  2062. .ps 12
  2063. .HE
  2064. .br
  2065. .ad l
  2066. 'ft B
  2067. .OC
  2068. .sp 1
  2069. .vs 14
  2070. Class name changes
  2071. .ad b
  2072. 'ft R
  2073. .OC
  2074. .sp 1
  2075. The name of class \fCArrayobid\fR is now \fCArrayOb\fR, the name of class \fCLinkobid\fR is now \fCLinkOb\fR, 
  2076. and the typedef \fCobid\fR has been removed.  Just change all occurrences of \fCArrayobid\fR to \fC
  2077. ArrayOb\fR, \fCLinkobid\fR to \fCLinkOb\fR, and \fCobid\fR to \fCObject*\fR.
  2078. .HE
  2079. .br
  2080. .ad l
  2081. 'ft B
  2082. .OC
  2083. .sp 1
  2084. Type \f(CBbool\fB now \f(CBint
  2085. 'ft B
  2086. .ad b
  2087. 'ft R
  2088. .OC
  2089. .sp 1
  2090. Type \fCbool\fR has been changed from \fCchar\fR to \fCint\fR for compatibility with X V11.
  2091. .HE
  2092. .br
  2093. .ad l
  2094. 'ft B
  2095. .OC
  2096. .sp 1
  2097. New \f(CBString\fB class
  2098. .ad b
  2099. 'ft R
  2100. .OC
  2101. .sp 1
  2102. There is a new, more efficient implementation of class \fCString\fR.  The new \fCString\fR class 
  2103. is compatible with the old \fCString\fR class except for the following:
  2104. 'in 72p
  2105. .br
  2106. .ad l
  2107. 'ft C
  2108. .ps 10
  2109. .OC
  2110. .sp 1
  2111. .vs 12
  2112. String(char c, unsigned l =1);
  2113. 'in 36p
  2114. .ad b
  2115. 'ft R
  2116. .ps 12
  2117. .OC
  2118. .sp 1
  2119. .vs 14
  2120. is now:
  2121. 'in 72p
  2122. .br
  2123. .ad l
  2124. 'ft C
  2125. .ps 10
  2126. .OC
  2127. .sp 1
  2128. .vs 12
  2129. String(char& c, unsigned l=1,
  2130. .OC
  2131. .br
  2132.     unsigned extra=DEFAULT_STRING_EXTRA);
  2133. 'in 36p
  2134. .ad b
  2135. 'ft R
  2136. .ps 12
  2137. .OC
  2138. .sp 1
  2139. .vs 14
  2140. The argument\fC unsigned extra\fR has been added to most of the \fCString::String()\fR constructors 
  2141. to allow the programmer to give a hint as to how much space to allocate in the string 
  2142. for additional characters.  When properly used, this can reduce the number of calls 
  2143. made to the memory allocator.
  2144. .OC
  2145. .sp 1
  2146. Assignment to substrings has changed slightly.  The old \fCString\fR class handled an assignment 
  2147. to a substring such as:
  2148. 'in 72p
  2149. .br
  2150. .ad l
  2151. 'ft C
  2152. .ps 10
  2153. .OC
  2154. .sp 1
  2155. .vs 12
  2156. String s = "abcdef";
  2157. .OC
  2158. .br
  2159. s(0,2) = "123";         // result is 12cdef
  2160. 'in 36p
  2161. .ad b
  2162. 'ft R
  2163. .ps 12
  2164. .OC
  2165. .sp 1
  2166. .vs 14
  2167. by truncating the source string to the length of the destination substring.  An assignment 
  2168. such as:
  2169. 'in 72p
  2170. .br
  2171. .ad l
  2172. 'ft C
  2173. .ps 10
  2174. .OC
  2175. .sp 1
  2176. .vs 12
  2177. s(0,2) = "1";           // result is 1\\0cdef
  2178. 'in 36p
  2179. .ad b
  2180. 'ft R
  2181. .ps 12
  2182. .OC
  2183. .sp 1
  2184. .vs 14
  2185. would cause a null byte to be inserted in the destination substring.
  2186. .OC
  2187. .sp 1
  2188. The new \fCString\fR class replaces the target substring with the source string, adjusting 
  2189. the length of the target string if necessary.  Thus
  2190. 'in 72p
  2191. .br
  2192. .ad l
  2193. 'ft C
  2194. .ps 10
  2195. .OC
  2196. .sp 1
  2197. .vs 12
  2198. String s = "abcdef";
  2199. .OC
  2200. .br
  2201. s(0,2) = "123";         // result is 123cdef
  2202. 'in 36p
  2203. .ad b
  2204. 'ft R
  2205. .ps 12
  2206. .OC
  2207. .sp 1
  2208. .vs 14
  2209. and:    
  2210. 'in 72p
  2211. .br
  2212. .ad l
  2213. 'ft C
  2214. .ps 10
  2215. .OC
  2216. .sp 1
  2217. .vs 12
  2218. s(0,2) = "1";           // result is 1cdef
  2219. 'in 36p
  2220. .ad b
  2221. 'ft R
  2222. .ps 12
  2223. .HE
  2224. .br
  2225. .ad l
  2226. 'ft B
  2227. .OC
  2228. .sp 1
  2229. .vs 14
  2230. Changes to Class \f(CBProcess
  2231. 'ft B
  2232. .ad b
  2233. 'ft R
  2234. .OC
  2235. .sp 1
  2236. An interface to \fCselect\fR(2) has been added:
  2237. 'in 72p
  2238. .br
  2239. .ad l
  2240. 'ft C
  2241. .ps 10
  2242. .OC
  2243. .sp 1
  2244. .vs 12
  2245. void Process::select(FDSet& rdmask, FDSet& wrmask, FDSet& exmask);
  2246. 'in 36p
  2247. .ad b
  2248. 'ft R
  2249. .ps 12
  2250. .HE
  2251. .br
  2252. .ad l
  2253. 'ft B
  2254. .ps 14
  2255. .OC
  2256. .sp 2
  2257. .vs 16
  2258. PORTING THE PROCESS CLASSES
  2259. .ad b
  2260. 'ft R
  2261. .ps 12
  2262. .OC
  2263. .sp 1
  2264. .vs 14
  2265. This section describes the steps to follow if you want to be a pioneer and port the \fC
  2266. Process\fR classes to a new machine/operating system.
  2267. .OC
  2268. .sp 1
  2269. If your target system provides the C library routines \fCsetjmp()\fR, \fClongjmp()\fR, and \fCalloca()\fR, 
  2270. and if the implementation of \fCsetjmp()\fR/\fClongjmp()\fR operates by saving/restoring all of 
  2271. the machine's volatile registers (as they do on the Sun-3, Sun-4, and IBM RT/AOS), 
  2272. then the port should be very easy; otherwise, you'll need to write versions of these 
  2273. routines in assembly language that behave as expected.
  2274. .OC
  2275. .sp 1
  2276. To find out how your \fCsetjmp()\fR/\fClongjmp()\fR works, either look at the source code for 
  2277. these routines (if you're fortunate enough to have it) or use the debugger to disassemble 
  2278. them.  A data structure of type \fCjmp_buf\fR, defined in \fCsetjmp.h\fR, is passed as an argument 
  2279. to these routines.  If your \fCsetjmp()\fR just saves all the volatile registers in it to 
  2280. be restored later by \fClongjmp()\fR, then you're probably in luck---all you need to figure 
  2281. out are the offsets in the \fCjmp_buf\fR structure where the PC (Program Counter), SP (Stack 
  2282. Pointer), and FP (Frame Pointer) registers are saved.
  2283. .OC
  2284. .sp 1
  2285. Next, look at \fCnihclconfig.h\fR and locate the place where it defines the machine-specific 
  2286. inline functions \fCSETJMP()\fR, \fCLONGJMP()\fR, \fC_SETJMP()\fR, \fC_LONGJMP()\fR, \fCENV_PC()\fR, \fCENV_SP()\fR, and \fC
  2287. ENV_FP()\fR.  These define the interface to the \fCProcess\fR classes.  For example, here are 
  2288. the definitions for SunOS 4.0 on the Sun-3:
  2289. 'in 72p
  2290. .br
  2291. .ad l
  2292. 'ft C
  2293. .ps 10
  2294. .OC
  2295. .sp 1
  2296. .vs 12
  2297. #ifdef SUNOS4
  2298. .OC
  2299. .sp 1
  2300. #ifdef mc68000
  2301. .OC
  2302. .br
  2303. typedef jmp_buf JMP_BUF;
  2304. .OC
  2305. .br
  2306. inline int SETJMP(JMP_BUF env)              { return setjmp(env); }
  2307. .OC
  2308. .br
  2309. inline void LONGJMP(JMP_BUF env, int val)   { longjmp(env,val); }
  2310. .OC
  2311. .br
  2312. inline int _SETJMP(JMP_BUF env)             { return _setjmp(env); }
  2313. .OC
  2314. .br
  2315. inline void _LONGJMP(JMP_BUF env, int val)  { _longjmp(env,val); }
  2316. .OC
  2317. .br
  2318. inline unsigned& ENV_PC(JMP_BUF env)        
  2319. .OC
  2320. .br
  2321.                     { return (unsigned&)env[3]; }
  2322. .OC
  2323. .br
  2324. inline unsigned& ENV_SP(JMP_BUF env)        
  2325. .OC
  2326. .br
  2327.                     { return (unsigned&)env[2]; }
  2328. .OC
  2329. .br
  2330. inline unsigned& ENV_FP(JMP_BUF env)        
  2331. .OC
  2332. .br
  2333.                     { return (unsigned&)env[15]; }
  2334. .OC
  2335. .br
  2336. #endif
  2337. .OC
  2338. .sp 1
  2339. // ...
  2340. .OC
  2341. .br
  2342. #endif
  2343. 'in 36p
  2344. .ad b
  2345. 'ft R
  2346. .ps 12
  2347. .OC
  2348. .sp 1
  2349. .vs 14
  2350. Add an \fC#if\fR ... \fC#endif\fR section for your machine and define the \fCENV_PC()\fR, \fCENV_SP()\fR, 
  2351. and \fCENV_FP()\fR functions to return a reference to the appropriate word in the \fCJMP_BUF\fR 
  2352. array.
  2353. .OC
  2354. .sp 1
  2355. If your machine doesn't use both an SP and FP, then you'll also need to add some machine 
  2356. dependent C++ code to \fCHeapProc.c\fR to relocate only the one actually used.  See the code 
  2357. for the \fCibm032\fR in \fCHeapProc.c\fR as an example.
  2358. .OC
  2359. .sp 1
  2360. If your system has both \fCsetjmp()\fR/\fClongjmp()\fR and \fC_setjmp()\fR/\fC_longjmp()\fR, define \fCSETJMP()\fR, \fC
  2361. LONGJMP()\fR, \fC_SETJMP()\fR, and \fC_LONGJMP()\fR to call the corresponding routine.  If your system 
  2362. doesn't have the "\fC_\fR" versions, check your documentation to see if your \fCsetjmp()\fR/\fClongjmp()\fR 
  2363. saves and restores the signal mask; if so, define \fC_SETJMP()\fR and \fC_LONGJMP()\fR to call \fC
  2364. setjmp()\fR and \fClongjmp()\fR, respectively.  See the code for \fCSUNOS3\fR as an example.
  2365. .OC
  2366. .sp 1
  2367. If your \fCsetjmp()\fR and \fClongjmp()\fR do \fInot\fR save and restore the signal mask, you'll need 
  2368. to provide versions that do.  Define \fCJMP_BUF\fR to be a struct that consists of a \fCjmp_buf\fR 
  2369. plus whatever other members you need to save the signal mask.  Then define \fC_SETJMP()\fR 
  2370. and \fC_LONGJMP()\fR to call \fCsetjmp()\fR and \fClongjmp()\fR using the \fCjmp_buf\fR part of a \fCJMP_BUF\fR, 
  2371. and define \fCSETJMP()\fR and \fCLONGJMP()\fR to do the same, but in addition to save/restore the 
  2372. signal mask using the other members of a \fCJMP_BUF\fR.  See the code for the \fCmc300\fR as an 
  2373. example.
  2374. .OC
  2375. .sp 1
  2376. If your \fCsetjmp()\fR/\fClongjmp()\fR do not work by saving/restoring all volatile registers 
  2377. (as on the VAX), you'll need to write versions with different names that do, and call 
  2378. these instead from the interface functions.
  2379. .OC
  2380. .sp 1
  2381. If you succeed in porting the \fCProcess\fR classes to a new machine/operating system, we'd 
  2382. appreciate a copy of the code for inclusion in future releases.
  2383. .HE
  2384. .br
  2385. .ad l
  2386. 'ft B
  2387. .ps 14
  2388. .OC
  2389. .sp 2
  2390. .vs 16
  2391. AT&T C++ TRANSLATOR RELEASE 2.00/2.1 BUGS
  2392. .ad b
  2393. 'ft R
  2394. .ps 12
  2395. .OC
  2396. .sp 1
  2397. .vs 14
  2398. Releases 2.00 and R2.1 of the AT&T C++ Translator have a few bugs that we had to insert 
  2399. work-arounds for in the NIH Class Library.  These are conditionally compiled based 
  2400. on the definition of preprocessor symbols beginning with \fCBUG_\fR.  If you are using the 
  2401. NIH Class Library to test a Release 2.00 or 2.1 -compatible C++ compiler, we suggest 
  2402. that you edit the master \fCMakefile\fR to define these symbols:
  2403. 'in 72p
  2404. .br
  2405. .ad l
  2406. 'ft C
  2407. .ps 10
  2408. .OC
  2409. .sp 1
  2410. .vs 12
  2411. # Disable AT&T R2.0/R2.1 bug work-around code
  2412. .OC
  2413. .br
  2414. #BUGDEFS =
  2415. .OC
  2416. .br
  2417. BUGDEFS = -DBUG_bC2728 -DBUG_38 -DBUG_39 -DBUG_OPTYPECONST
  2418. 'in 36p
  2419. .ad b
  2420. 'ft R
  2421. .ps 12
  2422. .HE
  2423. .br
  2424. .ad l
  2425. 'ft B
  2426. .ps 14
  2427. .OC
  2428. .sp 2
  2429. .vs 16
  2430. YACC STACK OVERFLOWS
  2431. .ad b
  2432. 'ft R
  2433. .ps 12
  2434. .OC
  2435. .sp 1
  2436. .vs 14
  2437. The preprocessor symbol \fCBUG_TOOBIG\fR controls compilation of code we had to insert to 
  2438. avoid "yacc stack overflow" errors in the SunOS 3.5 C compiler.  Release 2.0 produces 
  2439. very complicated expressions for the inline copy constructors it generates for deeply-derived 
  2440. classes.  Explicitly defining non-inline copy constructors solves the problem.  If 
  2441. you are a C compiler vendor, please make your tables big enough to handle the C code 
  2442. generated by the AT&T C++ Translator!
  2443. .HE
  2444. .br
  2445. .ad l
  2446. 'ft B
  2447. .ps 14
  2448. .OC
  2449. .sp 2
  2450. .vs 16
  2451. COMPILING UNDER AT&T C++ TRANSLATOR RELEASE 2.1
  2452. .ad b
  2453. 'ft R
  2454. .ps 12
  2455. .OC
  2456. .sp 1
  2457. .vs 14
  2458. R3.0 of the NIH Class Library has been tested with Release 2.1 of the AT&T C++ Translator 
  2459. under SunOS 4.0.  The following subsections summarize the changes required when compiling 
  2460. with R2.1.
  2461. .HE
  2462. .br
  2463. .ad l
  2464. 'ft B
  2465. .OC
  2466. .sp 1
  2467. Inconsistent declarations of alloca() in header files
  2468. .ad b
  2469. 'ft R
  2470. .OC
  2471. .sp 1
  2472. The header files supplied with R2.1 declare \fCalloca()\fR with a return type of \fCvoid*\fR in \fC
  2473. alloca.h\fR and \fCchar*\fR in \fCmalloc.h\fR, so you get an error message from the compiler when 
  2474. both of these files are included in the same compilation unit.  We solved this problem 
  2475. by changing the return type of the declaration of \fCalloca()\fR in \fCmalloc.h\fR to \fCvoid*\fR.
  2476. .HE
  2477. .br
  2478. .ad l
  2479. 'ft B
  2480. .OC
  2481. .sp 1
  2482. Warning and error messages due to #pragmas in SunOS 4.0 header files
  2483. .ad b
  2484. 'ft R
  2485. .OC
  2486. .sp 1
  2487. The C compiler occasionally issues warning messages such as the following when compiling 
  2488. the output of the AT&T C++ Translator (both R2.0 and R2.1) under SunOS 4.0:
  2489. 'in 72p
  2490. 'll \n(.lu-(36p)
  2491. .OC
  2492. .sp 1
  2493. "/usr/include/CC/sys/signal.h", line 38: warning: function name expected
  2494. 'in 36p
  2495. 'll \n(.lu-(-36p)
  2496. .OC
  2497. .sp 1
  2498. This is because C++ doesn't understand the \fC#pragma\fR directives it encounters in some 
  2499. system header files,  so it just passes them through to the C compiler.  The warning 
  2500. message results because C++ eliminates or moves the C function declarations that the \fC
  2501. pragma\fR references.  Another problem is that the C++ header files use \fC#define\fR to temporarily 
  2502. rename system functions when they include the vendor's C header files as a way to hide 
  2503. the effects of the vendor's C declarations for these functions.  Unfortunately, this 
  2504. garbles the function names in the \fC#pragma\fR directives also.
  2505. .OC
  2506. .sp 1
  2507. Under R2.0, the \fC#pragma\fR problem just results in warning messages, but under R2.1, 
  2508. the C compilation occasionally fails with an error message.  We manually made a new, 
  2509. self-contained version of \fC/usr/include/CC/setjmp.h\fR with the following \fCpragma\fR at the 
  2510. end:
  2511. 'in 72p
  2512. .br
  2513. .ad l
  2514. 'ft C
  2515. .ps 10
  2516. .OC
  2517. .sp 1
  2518. .vs 12
  2519. /*
  2520. .OC
  2521. .br
  2522.  * Routines that call setjmp have strange control flow graphs,
  2523. .OC
  2524. .br
  2525.  * since a call to a routine that calls resume/longjmp will eventually
  2526. .OC
  2527. .br
  2528.  * return at the setjmp site, not the original call site.  This
  2529. .OC
  2530. .br
  2531.  * utterly wrecks control flow analysis.
  2532. .OC
  2533. .br
  2534.  */
  2535. .OC
  2536. .br
  2537. #pragma unknown_control_flow(sigsetjmp, setjmp, _setjmp)
  2538. 'in 36p
  2539. .ad b
  2540. 'ft R
  2541. .ps 12
  2542. .OC
  2543. .sp 1
  2544. .vs 14
  2545. This eliminates the error messages, but not the warning messages.  It would probably 
  2546. be no worse to simply remove the \fC#pragma\fRs altogether, since they don't seem to be having 
  2547. the intended effect, and that would eliminate the warning messages also.
  2548. .HE
  2549. .br
  2550. .ad l
  2551. 'ft B
  2552. .OC
  2553. .sp 1
  2554. C++ Translator +p option broken
  2555. .ad b
  2556. 'ft R
  2557. .OC
  2558. .sp 1
  2559. The +p option produces spurious errors under R2.1.  Edit the master \fCMakefile\fR to not 
  2560. use the +p option when compiling with R2.1:
  2561. 'in 72p
  2562. .br
  2563. .ad l
  2564. 'ft C
  2565. .ps 10
  2566. .OC
  2567. .sp 1
  2568. .vs 12
  2569. # C++ flags
  2570. .OC
  2571. .br
  2572. # NOTE: Disable +p option when compiling with AT&T R2.1
  2573. .OC
  2574. .br
  2575. #CCFLAGS = +p
  2576. .OC
  2577. .br
  2578. CCFLAGS =
  2579. 'in 36p
  2580. .ad b
  2581. 'ft R
  2582. .ps 12
  2583. .HE
  2584. .br
  2585. .ad l
  2586. 'ft B
  2587. .OC
  2588. .sp 1
  2589. .vs 14
  2590. Optional support for nested types
  2591. .ad b
  2592. 'ft R
  2593. .OC
  2594. .sp 1
  2595. You can optionally define the preprocessor symbol \fCNESTED_TYPES\fR to cause the NIH Class 
  2596. Library to use nested types under R2.1.  Edit the master \fCMakefile\fR as follows:
  2597. 'in 72p
  2598. .br
  2599. .ad l
  2600. 'ft C
  2601. .ps 10
  2602. .OC
  2603. .sp 1
  2604. .vs 12
  2605. # Compile with nested types (works with AT&T R2.1 and GNU C++)
  2606. .OC
  2607. .br
  2608. #NESTED_TYPES =
  2609. .OC
  2610. .br
  2611. NESTED_TYPES = -DNESTED_TYPES
  2612.