A library for working with phylogenetic and population genetic data.
v0.32.0
Taxon Class Reference

#include <genesis/taxonomy/taxon.hpp>

Inherits Taxonomy.

Detailed Description

Store a Taxon, i.e., an element in a Taxonomy, with its name, rank, ID and sub-taxa.

This class models a taxon within the hierarchy of a Taxonomy. Each such taxon can have a name assigned to it, a taxonomic rank, an ID, and an arbitrarily nested set of sub-taxa. The name, rank, and ID are free-form strings which can have any value.

The name is one part of a taxonomic path string. For example, given the string

Animalia;Vertebrata;Mammalia;Carnivora

a Taxon could have the name "Mammalia", and contain a Taxon with the name "Carnivora" as child. See Taxonomy for details, see Taxopath for the taxonomic path string format.

Each taxon is itself also a Taxonomy, in terms of class inheritance. This also makes some biological sense, as a taxon can be seen as the taxonomy of its sub-taxa. We however only consider the Taxonomy as the top level of the hierarchy. For more information, see there. The class inheritance is mainly due to software design descisions, in order to make working with Taxonomies and Taxa as easy and straight forward as possible.

Definition at line 76 of file taxon.hpp.

Public Member Functions

 Taxon ()
 Default constructor. Does nothing. Yields an empty Taxon. More...
 
 Taxon (std::string const &name, std::string const &rank="", std::string const &id="")
 Constructor that uses the given name for the Taxon. More...
 
 Taxon (Taxon &&)
 Move constructor. More...
 
 Taxon (Taxon const &)
 Copy constructor. More...
 
virtual ~Taxon () override=default
 
template<class TaxonDataType >
TaxonDataType & data ()
 
template<class TaxonDataType >
TaxonDataType const & data () const
 
template<class TaxonDataType >
TaxonDataType * data_cast ()
 
template<class TaxonDataType >
TaxonDataType const * data_cast () const
 
BaseTaxonDatadata_ptr ()
 Return a pointer to the data. More...
 
BaseTaxonData const * data_ptr () const
 Return a const pointer to the data. More...
 
bool has_data () const
 Return true if the Taxon has a data object assigned to it. More...
 
std::string const & id () const
 Set the ID of this taxon. More...
 
void id (std::string const &value)
 
std::string const & name () const
 Return the name of this taxon. More...
 
void name (std::string const &value)
 Set the name of this taxon. More...
 
Taxonoperator= (Taxon &&)
 Move assignment operator. More...
 
Taxonoperator= (Taxon const &)
 Copy assignment operator. More...
 
Taxonparent ()
 Return a pointer to the parent of this taxon, or a nullptr if this is the top level taxon. More...
 
Taxon const * parent () const
 Return a pointer to the parent of this taxon, or a nullptr if this is the top level taxon. More...
 
std::string const & rank () const
 Return the rank of this taxon. More...
 
void rank (std::string const &value)
 
Taxonreset_data (std::unique_ptr< BaseTaxonData > data)
 Reset the data pointer of this Taxon. More...
 
- Public Member Functions inherited from Taxonomy
 Taxonomy ()=default
 
 Taxonomy (Taxonomy &&)
 Move constructor. More...
 
 Taxonomy (Taxonomy const &)
 Copy constructor. More...
 
virtual ~Taxonomy ()=default
 
Taxonadd_child (std::string const &name, bool merge_duplicates=true)
 Add a child Taxon by creating a new one with the given name and return it. More...
 
Taxonadd_child (Taxon const &child, bool merge_duplicates=true)
 Add a child Taxon as a copy of a given Taxon and return it. More...
 
Taxonat (size_t index)
 Return the child Taxon at the given index. More...
 
Taxon const & at (size_t index) const
 Return the child Taxon at the given index. More...
 
iterator begin ()
 Return an iterator to the beginning of the child taxa. More...
 
const_iterator begin () const
 Return a const iterator to the beginning of the child taxa. More...
 
const_iterator cbegin () const
 Return a const iterator to the beginning of the child taxa. More...
 
const_iterator cend () const
 Return a const iterator to the end of the child taxa. More...
 
void clear_children ()
 Remove all children. More...
 
iterator end ()
 Return an iterator to the end of the child taxa. More...
 
const_iterator end () const
 Return a const iterator to the end of the child taxa. More...
 
Taxonget_child (std::string name)
 Return the child Taxon with a given name if it exists, or throw otherwise. More...
 
Taxon const & get_child (std::string name) const
 Return the child Taxon with a given name if it exists, or throw otherwise. More...
 
bool has_child (std::string name) const
 Return whether an immediate child Taxon with the given name exists. More...
 
size_t index_of (std::string const &name) const
 
Taxonomyoperator= (Taxonomy &&)
 Move assignment operator. More...
 
Taxonomyoperator= (Taxonomy const &)
 Copy assignment operator. More...
 
Taxonoperator[] (size_t index)
 Return the child Taxon at the given index. More...
 
Taxon const & operator[] (size_t index) const
 Return the child Taxon at the given index. More...
 
Taxonoperator[] (std::string name)
 Return the child Taxon with a given name if it exists, or throw otherwise. More...
 
Taxon const & operator[] (std::string name) const
 Return the child Taxon with a given name if it exists, or throw otherwise. More...
 
void remove_at (size_t index)
 Remove a child Taxon at a certain index. More...
 
void remove_child (std::string const &name)
 Remove a child Taxon with a certain name. More...
 
size_t size () const
 Return the number of immediate child Taxa. More...
 
template<class Compare >
void sort (Compare comp)
 Sort the taxonomy according to some compare criterion. More...
 

Public Attributes

friend Taxonomy
 Taxonomy is a friend, as it needs access to parent_ in order to ensure consistency. More...
 

Protected Member Functions

Taxonadd_child_ (Taxon const &child, bool merge_duplicates) override
 Virtual implementation function for adding a child taxon. More...
 
- Protected Member Functions inherited from Taxonomy
void reset_parent_pointers_ (Taxon *parent)
 Internal helper function that resets the parent pointer of all stored Taxa. More...
 

Friends

void swap (Taxon &lhs, Taxon &rhs)
 Swapperator for Taxon. More...
 

Additional Inherited Members

- Public Types inherited from Taxonomy
typedef std::list< Taxon >::const_iterator const_iterator
 
typedef std::list< Taxon >::iterator iterator
 

Constructor & Destructor Documentation

◆ Taxon() [1/4]

Taxon ( )

Default constructor. Does nothing. Yields an empty Taxon.

Definition at line 43 of file taxon.cpp.

◆ Taxon() [2/4]

Taxon ( std::string const &  name,
std::string const &  rank = "",
std::string const &  id = "" 
)
explicit

Constructor that uses the given name for the Taxon.

Definition at line 52 of file taxon.cpp.

◆ ~Taxon()

virtual ~Taxon ( )
overridevirtualdefault

◆ Taxon() [3/4]

Taxon ( Taxon const &  other)

Copy constructor.

We need a custom version of this in order to set the Taxon::parent() pointers of all children correctly when copying and to copy the data.

Copying first sets the parent() pointer to nullptr. This is because we might want to get a 'blank' copy, i.e., a Taxon that is not attached to a Taxonomy. This way, the functions expecting a parent pointer don't get a potentially invalid pointer.

If however we copy a Taxon into a Taxonomy (or into some other Taxon), reset_parent_pointers_() is called later anyway, which then sets the parent pointer to the correct value.

Definition at line 61 of file taxon.cpp.

◆ Taxon() [4/4]

Taxon ( Taxon &&  other)

Move constructor.

We need a custom version of this in order to set the Taxon::parent() pointers of all children correctly, and to treat the data correctlty when copying.

Definition at line 74 of file taxon.cpp.

Member Function Documentation

◆ add_child_()

Taxon & add_child_ ( Taxon const &  child,
bool  merge_duplicates 
)
overrideprotectedvirtual

Virtual implementation function for adding a child taxon.

See Taxonomy::add_child_() for details. In addition to the base class implementation, this function also sets the parent pointer of the Taxon.

Reimplemented from Taxonomy.

Definition at line 212 of file taxon.cpp.

◆ data() [1/2]

TaxonDataType& data ( )
inline

Definition at line 197 of file taxon.hpp.

◆ data() [2/2]

TaxonDataType const& data ( ) const
inline

Definition at line 203 of file taxon.hpp.

◆ data_cast() [1/2]

TaxonDataType* data_cast ( )
inline

Definition at line 209 of file taxon.hpp.

◆ data_cast() [2/2]

TaxonDataType const* data_cast ( ) const
inline

Definition at line 215 of file taxon.hpp.

◆ data_ptr() [1/2]

BaseTaxonData const * data_ptr ( )

Return a pointer to the data.

In most cases, using data<>() is more convenient. However, in some cases, this function might be necessary.

Definition at line 192 of file taxon.cpp.

◆ data_ptr() [2/2]

BaseTaxonData const* data_ptr ( ) const

Return a const pointer to the data.

In most cases, using data<>() is more convenient. However, in some cases, this function might be necessary.

◆ has_data()

bool has_data ( ) const

Return true if the Taxon has a data object assigned to it.

Definition at line 187 of file taxon.cpp.

◆ id() [1/2]

std::string const & id ( ) const

Set the ID of this taxon.

Definition at line 159 of file taxon.cpp.

◆ id() [2/2]

void id ( std::string const &  value)

Definition at line 164 of file taxon.cpp.

◆ name() [1/2]

std::string const & name ( ) const

Return the name of this taxon.

Definition at line 131 of file taxon.cpp.

◆ name() [2/2]

void name ( std::string const &  value)

Set the name of this taxon.

Definition at line 136 of file taxon.cpp.

◆ operator=() [1/2]

Taxon & operator= ( Taxon &&  other)

Move assignment operator.

We need a custom version of this in order to set the Taxon::parent() pointers of all children correctly, and to treat the data correctlty when copying.

Definition at line 99 of file taxon.cpp.

◆ operator=() [2/2]

Taxon & operator= ( Taxon const &  other)

Copy assignment operator.

We need a custom version of this in order to set the Taxon::parent() pointers of all children correctly, and to treat the data correctlty when copying.

See the move constructor for details.

Definition at line 85 of file taxon.cpp.

◆ parent() [1/2]

Taxon* parent ( )

Return a pointer to the parent of this taxon, or a nullptr if this is the top level taxon.

◆ parent() [2/2]

Taxon * parent ( ) const

Return a pointer to the parent of this taxon, or a nullptr if this is the top level taxon.

Definition at line 173 of file taxon.cpp.

◆ rank() [1/2]

std::string const & rank ( ) const

Return the rank of this taxon.

Definition at line 145 of file taxon.cpp.

◆ rank() [2/2]

void rank ( std::string const &  value)

Definition at line 150 of file taxon.cpp.

◆ reset_data()

Taxon & reset_data ( std::unique_ptr< BaseTaxonData data)

Reset the data pointer of this Taxon.

Using this function, a Taxon can be assigend new data. It is also possible to change the data type completely (as long as it derives from BaseTaxonData). Be however aware that many functions that work with a Taxonomy expect a certain data type. Thus, changing it might break those functions and lead to exceptions and other errors.

Definition at line 202 of file taxon.cpp.

Friends And Related Function Documentation

◆ swap

void swap ( Taxon lhs,
Taxon rhs 
)
friend

Swapperator for Taxon.

Definition at line 111 of file taxon.cpp.

Member Data Documentation

◆ Taxonomy

friend Taxonomy

Taxonomy is a friend, as it needs access to parent_ in order to ensure consistency.

Definition at line 87 of file taxon.hpp.


The documentation for this class was generated from the following files: