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].