1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head><title>NEXUS CLASS LIBRARY: NxsEmptyBlock Class</title>
<style type="text/css">
<!--
@import url(ncl.css);
.quickref {font-family: Arial, sans-serif}
.public {font-weight: bold; color: black; background: white;}
.protected {font-weight: bold; color: teal; background: white;}
.private {font-weight: bold; color: red; background: white;}
.groupheading {font-size: large; font-weight: bold;}
.classy {font-family: Arial, sans-serif; color: navy;}
.variablename {font-weight: bold; color: maroon;}
-->
</style>
</head>
<body>
<table border="1" width="100%">
<tr><td>
<table border="0" width="100%">
<tr>
<td align="left"><span class="classy">NEXUS CLASS LIBRARY</span></td>
<td align="right"><span class="classy"><a href="v2.0index.html">home</a> | <a href="classes.html">classes</a> | <a href="functions.html">functions</a></span></td>
</tr>
</table>
</td></tr>
</table>
<h1>Class NxsEmptyBlock</h1>
<h2>Member Functions</h2>
<a href="#CharLabelToNumber45"><span class="quickref">CharLabelToNumber</span></a><a href="#HandleEndblock55"><span class="quickref">, HandleEndblock</span></a><a href="#NxsEmptyBlock25"><span class="quickref">, NxsEmptyBlock</span></a><a href="#NxsEmptyBlock33"><span class="quickref">, ~NxsEmptyBlock</span></a><a href="#Read76"><span class="quickref">, Read</span></a><a href="#Report143"><span class="quickref">, Report</span></a><a href="#Reset134"><span class="quickref">, Reset</span></a><a href="#SkippingCommand156"><span class="quickref">, SkippingCommand</span></a><a href="#TaxonLabelToNumber169"><span class="quickref">, TaxonLabelToNumber</span></a>
<h2>Class Description</h2>
<p>
This is a template that can be used to create a class representing a NEXUS block. Here are the steps to follow if you wish to create a new block specifically for use with your particular application. Suppose your application is called Phylome and you want to create a private block called a PHYLOME block that can appear in NEXUS data files and contains commands for your program.<ul> <li>Copy the files nxsemptyblock.h and nxsemptyblock.cpp and rename them (e.g. nxsphylomeblock.h and </li> nxsphylomeblock.cpp)</li> <li>In nxsphylomeblock.h and nxsphylomeblock.cpp, replace all instances of EMPTY (case-sensitive, whole word search)</li> with PHYLOME</li> <li>In nxsphylomeblock.h, replace both instances of NCL_NXSEMPTYBLOCK_H at the top of the file with</li> NCL_NXSPHYLOMEBLOCK_H</li> <li>In nxsphylomeblock.h and nxsphylomeblock.cpp, replace all instances of NxsEmptyBlock (case-sensitive, whole word</li> search) with NxsPhylomeBlock</li> <li>Modify the Read function in nxsphylomeblock.cpp to interpret what comes after the BEGIN PHYLOME command in the</li> NEXUS data file</li> <li>Modify the CharLabelToNumber and TaxonLabelToNumber if you need to read in sets of characters or taxa, </li> respectively. These functions provide a way for <a href="NxsSetReader.html">NxsSetReader</a> objects to translate character or taxon labels to</li> the corresponding numbers. If you do not need these capabilities, then it is safe to just delete these functions</li> from nxsphylomeblock.h and nxsphylomeblock.cpp because they are no different that the base class versions</li> <li>Modify the SkippingCommand function if you want to notify users when commands within the PHYLOME block are not </li> recognized and are being skipped</li> <li>In nxsphylomeblock.h, replace this comment with something meaningful for your class. Start off with something</li> like "This class handles reading and storage for the NEXUS block PHYLOME. It overrides the member functions </li> Read and Reset, which are abstract virtual functions in the base class <a href="NxsBlock.html">NxsBlock</a> "</li></ul> Adding a new data member? Don't forget to:<ul> <li>Describe it in the class declaration using a C-style comment. </li> <li>Initialize it (unless it is self-initializing) in the constructor and reinitialize it in the Reset function.</li> <li>Describe the initial state in the constructor documentation. </li> <li>Delete memory allocated to it in both the destructor and Reset function. </li> <li>Report it in some way in the Report function. </li></ul>
<h3>Key to symbols and colors</h3>
<p><span class="public">public</span>, <span class="protected">protected</span>, <span class="private">private</span>, <code>A</code> = abstract, <code>C</code> = constructor, <code>D</code> = destructor, <code>I</code> = inline, <code>S</code> = static, <code>V</code> = virtual, <code>F</code> = friend</p>
<p> </p>
<center>
<table border="5" cellpadding="1" cellspacing="0" width="95%">
<tr bgcolor="#CCCCFF">
<td><span class="groupheading">Member Functions</span></td>
</table>
<table border="1" cellpadding="3" cellspacing="0" width="95%">
<tr><td>
<table width="100%" border="0" cellpadding="1">
<tr>
<td> </td>
<td> </td>
<td align="right" valign="top" width="15%"><code>unsigned</code></td>
<td> </td>
<td align="left" valign="top" width="82%"><code class="public"><a name="CharLabelToNumber45">CharLabelToNumber</a></code><code>(NxsString s)</code></td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td><dd>The code here is identical to the base class version (simply returns 0), so the code here should either be modified or this derived version eliminated altogether. Under what circumstances would you need to modify the default code, you ask? This function should be modified to something meaningful if this derived class needs to construct and run a <a href="NxsSetReader.html">NxsSetReader</a> object to read a set involving characters. The <a href="NxsSetReader.html">NxsSetReader</a> object may need to use this function to look up a character label encountered in the set. A class that overrides this method should return the character index in the range [1..<span class="variablename">nchar</span>]; i.e., add one to the 0-offset index.</dd></td>
</tr>
</table>
</td></tr>
<tr><td>
<table width="100%" border="0" cellpadding="1">
<tr>
<td> </td>
<td> </td>
<td align="right" valign="top" width="15%"><code>void</code></td>
<td> </td>
<td align="left" valign="top" width="82%"><code class="public"><a name="HandleEndblock55">HandleEndblock</a></code><code>(NxsToken &token)</code></td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td><dd>Called when the END or ENDBLOCK command needs to be parsed from within the EMPTY block. Basically just checks to make sure the next token in the data file is a semicolon.</dd></td>
</tr>
</table>
</td></tr>
<tr><td>
<table width="100%" border="0" cellpadding="1">
<tr>
<td>C</td>
<td> </td>
<td align="right" valign="top" width="15%"><code></code></td>
<td> </td>
<td align="left" valign="top" width="82%"><code class="public"><a name="NxsEmptyBlock25">NxsEmptyBlock</a></code><code>()</code></td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td><dd>Sets the base class data member <span class="variablename">id</span> to the name of the block (i.e. "EMPTY") in NEXUS data files.</dd></td>
</tr>
</table>
</td></tr>
<tr><td>
<table width="100%" border="0" cellpadding="1">
<tr>
<td>D</td>
<td> </td>
<td align="right" valign="top" width="15%"><code></code></td>
<td> </td>
<td align="left" valign="top" width="82%"><code class="public"><a name="NxsEmptyBlock33">~NxsEmptyBlock</a></code><code>()</code></td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td><dd>Nothing needs to be done.</dd></td>
</tr>
</table>
</td></tr>
<tr><td>
<table width="100%" border="0" cellpadding="1">
<tr>
<td>V</td>
<td> </td>
<td align="right" valign="top" width="15%"><code>void</code></td>
<td> </td>
<td align="left" valign="top" width="82%"><code class="public"><a name="Read76">Read</a></code><code>(NxsToken &token)</code></td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td><dd>This function provides the ability to read everything following the block name (which is read by the <a href="NxsReader.html">NxsReader</a> object) to the END or ENDBLOCK statement. Characters are read from the input stream <span class="variablename">in</span>. Overrides the pure virtual function in the base class.</dd></td>
</tr>
</table>
</td></tr>
<tr><td>
<table width="100%" border="0" cellpadding="1">
<tr>
<td>V</td>
<td> </td>
<td align="right" valign="top" width="15%"><code>void</code></td>
<td> </td>
<td align="left" valign="top" width="82%"><code class="public"><a name="Report143">Report</a></code><code>(ostream &out)</code></td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td><dd>This function outputs a brief report of the contents of this EMPTY block. Overrides the pure virtual function in the base class.</dd></td>
</tr>
</table>
</td></tr>
<tr><td>
<table width="100%" border="0" cellpadding="1">
<tr>
<td>V</td>
<td> </td>
<td align="right" valign="top" width="15%"><code>void</code></td>
<td> </td>
<td align="left" valign="top" width="82%"><code class="public"><a name="Reset134">Reset</a></code><code>()</code></td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td><dd>Sets <span class="variablename">isEmpty</span> to true in preparation for reading a new EMPTY block. Overrides the pure virtual function in the base class.</dd></td>
</tr>
</table>
</td></tr>
<tr><td>
<table width="100%" border="0" cellpadding="1">
<tr>
<td> </td>
<td> </td>
<td align="right" valign="top" width="15%"><code>void</code></td>
<td> </td>
<td align="left" valign="top" width="82%"><code class="public"><a name="SkippingCommand156">SkippingCommand</a></code><code>(NxsString commandName)</code></td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td><dd>This function is called when an unknown command named <span class="variablename">commandName</span> is about to be skipped. This version of the function (which is identical to the base class version) does nothing (i.e., no warning is issued that a command was unrecognized). Modify this virtual function to provide such warnings to the user (or eliminate it altogether since the base class version already does what this does).</dd></td>
</tr>
</table>
</td></tr>
<tr><td>
<table width="100%" border="0" cellpadding="1">
<tr>
<td> </td>
<td> </td>
<td align="right" valign="top" width="15%"><code>unsigned</code></td>
<td> </td>
<td align="left" valign="top" width="82%"><code class="public"><a name="TaxonLabelToNumber169">TaxonLabelToNumber</a></code><code>(NxsString s)</code></td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td><dd>The code here is identical to the base class version (simply returns 0), so the code here should either be modified or this derived version eliminated altogether. Under what circumstances would you need to modify the default code, you ask? This function should be modified to something meaningful if this derived class needs to construct and run a <a href="NxsSetReader.html">NxsSetReader</a> object to read a set involving taxa. The <a href="NxsSetReader.html">NxsSetReader</a> object may need to use this function to look up a taxon label encountered in the set. A class that overrides this method should return the taxon index in the range [1..ntax]; i.e., add one to the 0-offset index.</dd></td>
</tr>
</table>
</td></tr>
</table>
</center>
|
