NEXUS CLASS LIBRARY: NxsEmptyBlock Class

NEXUS CLASS LIBRARY | home | classes | functions

# Class NxsEmptyBlock

## Member Functions

CharLabelToNumber, HandleEndblock, NxsEmptyBlock, ~NxsEmptyBlock, Read, Report, Reset, SkippingCommand, TaxonLabelToNumber

## Class Description

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.

- Copy the files nxsemptyblock.h and nxsemptyblock.cpp and rename them (e.g. nxsphylomeblock.h and
nxsphylomeblock.cpp)
- In nxsphylomeblock.h and nxsphylomeblock.cpp, replace all instances of EMPTY (case-sensitive, whole word search)
with PHYLOME
- In nxsphylomeblock.h, replace both instances of NCL_NXSEMPTYBLOCK_H at the top of the file with
NCL_NXSPHYLOMEBLOCK_H
- In nxsphylomeblock.h and nxsphylomeblock.cpp, replace all instances of NxsEmptyBlock (case-sensitive, whole word
search) with NxsPhylomeBlock
- Modify the Read function in nxsphylomeblock.cpp to interpret what comes after the BEGIN PHYLOME command in the
NEXUS data file
- Modify the CharLabelToNumber and TaxonLabelToNumber if you need to read in sets of characters or taxa,
respectively. These functions provide a way for NxsSetReader objects to translate character or taxon labels to the corresponding numbers. If you do not need these capabilities, then it is safe to just delete these functions from nxsphylomeblock.h and nxsphylomeblock.cpp because they are no different that the base class versions
- Modify the SkippingCommand function if you want to notify users when commands within the PHYLOME block are not
recognized and are being skipped
- In nxsphylomeblock.h, replace this comment with something meaningful for your class. Start off with something
like "This class handles reading and storage for the NEXUS block PHYLOME. It overrides the member functions Read and Reset, which are abstract virtual functions in the base class NxsBlock "

Adding a new data member? Don't forget to:

- Describe it in the class declaration using a C-style comment.
- Initialize it (unless it is self-initializing) in the constructor and reinitialize it in the Reset function.
- Describe the initial state in the constructor documentation.
- Delete memory allocated to it in both the destructor and Reset function.
- Report it in some way in the Report function.

### Key to symbols and colors

public, protected, private, `A` = abstract, `C` = constructor, `D` = destructor, `I` = inline, `S` = static, `V` = virtual, `F` = friend

Member Functions

|  | `unsigned` |  | `CharLabelToNumber``(NxsString s)`
|  |  |  | 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 NxsSetReader object to read a set involving characters. The NxsSetReader 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..nchar]; i.e., add one to the 0-offset index.
|  | `void` |  | `HandleEndblock``(NxsToken &token)`
|  |  |  | 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.
C |  | `` |  | `NxsEmptyBlock``()`
|  |  |  | Sets the base class data member id to the name of the block (i.e. "EMPTY") in NEXUS data files.
D |  | `` |  | `~NxsEmptyBlock``()`
|  |  |  | Nothing needs to be done.
V |  | `void` |  | `Read``(NxsToken &token)`
|  |  |  | This function provides the ability to read everything following the block name (which is read by the NxsReader object) to the END or ENDBLOCK statement. Characters are read from the input stream in. Overrides the pure virtual function in the base class.
V |  | `void` |  | `Report``(ostream &out)`
|  |  |  | This function outputs a brief report of the contents of this EMPTY block. Overrides the pure virtual function in the base class.
V |  | `void` |  | `Reset``()`
|  |  |  | Sets isEmpty to true in preparation for reading a new EMPTY block. Overrides the pure virtual function in the base class.
|  | `void` |  | `SkippingCommand``(NxsString commandName)`
|  |  |  | This function is called when an unknown command named commandName 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).
|  | `unsigned` |  | `TaxonLabelToNumber``(NxsString s)`
|  |  |  | 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 NxsSetReader object to read a set involving taxa. The NxsSetReader 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.