NEXUS CLASS LIBRARY: NxsBlock Class

NEXUS CLASS LIBRARY | home | classes | functions

# Class NxsBlock

## Friends

class NxsReader

## Data Members

errormsg, id, isEmpty, isEnabled, isUserSupplied, next, nexus

## Member Functions

CharLabelToNumber, Disable, Enable, GetID, IsEmpty, IsEnabled, IsUserSupplied, NxsBlock, ~NxsBlock, Read, Report, Reset, SetNexus, SkippingCommand, TaxonLabelToNumber

## Class Description

This is the base class from which all block classes are derived. A NxsBlock-derived class encapsulates a Nexus block (e.g. DATA block, TREES block, etc.). The abstract virtual function Read must be overridden for each derived class to provide the ability to read everything following the block name (which is read by the NxsReader object) to the end or endblock statement. Derived classes must provide their own data storage and access functions. The abstract virtual function Report must be overridden to provide some feedback to user on contents of block. The abstract virtual function Reset must be overridden to empty the block of all its contents, restoring it to its just-constructed state.

### Key to symbols and colors

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

Data Members

|  | `NxsString` |  | `errormsg`
|  |  |  | workspace for creating error messages
|  | `NxsString` |  | `id`
|  |  |  | holds name of block (e.g., "DATA", "TREES", etc.)
|  | `bool` |  | `isEmpty`
|  |  |  | true if this object is currently storing data
|  | `bool` |  | `isEnabled`
|  |  |  | true if this block is currently ebabled
|  | `bool` |  | `isUserSupplied`
|  |  |  | true if this object has been read from a file; false otherwise
|  | `NxsBlock` |  | `*next`
|  |  |  | pointer to next block in list
|  | `NxsReader` |  | `*nexus`
|  |  |  | pointer to the Nexus file reader object

Member Functions

V |  | `unsigned` |  | `CharLabelToNumber``(NxsString s)`
|  |  |  | This base class version simply returns 0 but a derived class should override this function if it 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].
|  | `void` |  | `Disable``()`
|  |  |  | Sets the value of isEnabled to false. A NxsBlock can be disabled (by calling this method) if blocks of that type are to be skipped during execution of the NEXUS file. If a disabled block is encountered, the virtual NxsReader::SkippingDisabledBlock function is called, giving your application the opportunity to inform the user that a block was skipped.
|  | `void` |  | `Enable``()`
|  |  |  | Sets the value of isEnabled to true. A NxsBlock can be disabled (by calling Disable) if blocks of that type are to be skipped during execution of the NEXUS file. If a disabled block is encountered, the virtual NxsReader::SkippingDisabledBlock function is called, giving your application the opportunity to inform the user that a block was skipped.
|  | `NxsString` |  | `GetID``()`
|  |  |  | Returns the id NxsString.
|  | `bool` |  | `IsEmpty``()`
|  |  |  | Returns true if Read function has not been called since the last Reset. This base class version simply returns the value of the data member isEmpty. If you derive a new block class from NxsBlock, be sure to set isEmpty to true in your Reset function and isEmpty to false in your Read function.
|  | `bool` |  | `IsEnabled``()`
|  |  |  | Returns value of isEnabled, which can be controlled through use of the Enable and Disable member functions. A NxsBlock should be disabled if blocks of that type are to be skipped during execution of the NEXUS file. If a disabled block is encountered, the virtual NxsReader::SkippingDisabledBlock function is called, giving your application the opportunity to inform the user that a block was skipped.
|  | `bool` |  | `IsUserSupplied``()`
|  |  |  | Returns value of isUserSupplied, which is true if and only if this block's Read function is called to process a block of this type appearing in a data file. This is useful because in some cases, a block object may be created internally (e.g. a NxsTaxaBlock may be populated using taxon names provided in a DATA block), and such blocks do not require permission from the user to delete data stored therein.
C |  | `` |  | `NxsBlock``()`
|  |  |  | Initializes all pointer data members to NULL, and all bool data members to true except isUserSupplied, which is initialized to false.
D |  | `` |  | `~NxsBlock``()`
|  |  |  | Nothing to be done.
V |  | `void` |  | `Read``(NxsToken &token)`
|  |  |  | This virtual function must be overridden for each derived class to provide 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'. Note that to get output comments displayed, you must derive a class from NxsToken, override the member function OutputComment to display a supplied comment, and then pass a reference to an object of the derived class to this function.
V |  | `void` |  | `Report``(ostream &out)`
|  |  |  | This virtual function provides a brief report of the contents of the block.
V |  | `void` |  | `Reset``()`
|  |  |  | This virtual function should be overridden for each derived class to completely reset the block object in preparation for reading in another block of this type. This function is called by the NxsReader object just prior to calling the block object's Read function.
|  | `void` |  | `SetNexus``(NxsReader *nxsptr)`
|  |  |  | Sets the nexus data member of the NxsBlock object to 'nxsptr'.
V |  | `void` |  | `SkippingCommand``(NxsString commandName)`
|  |  |  | This function is called when an unknown command named commandName is about to be skipped. This version of the function does nothing (i.e., no warning is issued that a command was unrecognized). Override this virtual function in a derived class to provide such warnings to the user.
V |  | `unsigned` |  | `TaxonLabelToNumber``(NxsString s)`
|  |  |  | This base class version simply returns 0, but a derived class should override this function if it 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].