#include <genesis/taxonomy/taxonomy.hpp>

Inherited by Taxon.

Detailed Description

Store a Taxonomy, i.e., a nested hierarchy of Taxa.

We call a string of the form

Animalia;Vertebrata;Mammalia;Carnivora

a taxonomic path string. Those strings are often found in taxonomic databases, and usually use semicola to separete their parts. Each part of such a string is called a Taxon, and can have a rank associated with it. See Taxopath for details on the format.

In the example above, the rank associations could be

Kingdom: Animalia
Phylum:  Vertebrata
Class:   Mammalia
Order:   Carnivora

We use the term "taxon" to refer to one element in such a string, and model this in the Taxon class. Both the Taxonomy and Taxon classes work with just those parts of the string. Each Taxon can itself contain further lower level Taxa, resulting in a hierarchy.

The above taxonomic path string for example would give a hierarchy of Taxa like this

Animalia
    Vertebrata
        Mammalia
            Carnivora

where each line is one Taxon, stored within their parent Taxa. A Taxonomy is the uppermost parent of the Taxa in the hierarchy.

There are functions to work with taxonomic path strings and Taxopaths directly, for example to "translate" them into a Taxonomy or to find a Taxon given a Taxopath. See the namespace taxonomy for a list of those functions.

In a sense, each Taxon is itself a Taxonomy, because of their hierarchical relationship. However, we use the distinction between the two in order to separate concerns. That means, only the Taxonomy should be seen as the top level of the hierarchy.

This class serves as a container for storing a list of Taxa. It allows to add, remove and get Taxa by their name, as well as iterating over them.

Definition at line 96 of file taxonomy/taxonomy.hpp.

Public Member Functions
	Taxonomy ()=default

	Taxonomy (Taxonomy &&)
	Move constructor. More...

	Taxonomy (Taxonomy const &)
	Copy constructor. More...

virtual	~Taxonomy ()=default

Taxon &	add_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...

Taxon &	add_child (Taxon const &child, bool merge_duplicates=true)
	Add a child Taxon as a copy of a given Taxon and return it. More...

Taxon &	at (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...

Taxon &	get_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

Taxonomy &	operator= (Taxonomy &&)
	Move assignment operator. More...

Taxonomy &	operator= (Taxonomy const &)
	Copy assigment operator. More...

Taxon &	operator[] (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...

Taxon &	operator[] (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 Types
typedef std::list< Taxon >::const_iterator	const_iterator

typedef std::list< Taxon >::iterator	iterator

Protected Member Functions
virtual Taxon &	add_child_ (Taxon const &child, bool merge_duplicates)
	Virtual implementation function for adding a child Taxon. More...

void	reset_parent_pointers_ (Taxon *parent)
	Internal helper function that resets the parent pointer of all stored Taxa. More...

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

Constructor & Destructor Documentation

◆ Taxonomy() [1/3]

Taxonomy ( )

default

◆ ~Taxonomy()

virtual ~Taxonomy ( )

virtualdefault

◆ Taxonomy() [2/3]

Taxonomy ( Taxonomy 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.

Definition at line 45 of file taxonomy.cpp.

◆ Taxonomy() [3/3]

Taxonomy ( Taxonomy && other )

Move constructor.

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

Definition at line 51 of file taxonomy.cpp.

Member Function Documentation

◆ add_child() [1/2]

Taxon & add_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.

If merge_duplicates is true (default), the Taxonomy is checked for a child Taxon with the same name, and if one exists, nothing is added. Otherwise (merge_duplicates is false), a new Taxon is added, even if this creates another child Taxon with the same name.

Definition at line 187 of file taxonomy.cpp.

◆ add_child() [2/2]

Taxon & add_child	(	Taxon const &	child,
		bool	merge_duplicates = `true`
	)

Add a child Taxon as a copy of a given Taxon and return it.

If merge_duplicates is true (default), the Taxonomy is checked for a child Taxon with the same name, and if one exists, it is recursively merged with the given Taxon. Otherwise (merge_duplicates is false), the Taxon is added, even if this creates another child Taxon with the same name.

Definition at line 182 of file taxonomy.cpp.

◆ add_child_()

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

protectedvirtual

Virtual implementation function for adding a child Taxon.

This function is invoked by all add_child() functions in order to implement the non-virtual interface pattern.

It needs to be virtual because adding a child Taxon differs for Taxonomy and Taxon. In the latter case, the additional parent property has to be set. Thus, this function is overridden by Taxon, see Taxon::add_child_().

If a child Taxon with the same name already exists, it is recursively merged with the given Taxon. The function returns the child.

Reimplemented in Taxon.

Definition at line 267 of file taxonomy.cpp.

◆ at() [1/2]

Taxon & at ( size_t index )

Return the child Taxon at the given index.

The function throws an exception if the index in invalid, i.e., >= size().

Definition at line 142 of file taxonomy.cpp.

◆ at() [2/2]

Taxon const & at ( size_t index ) const

Return the child Taxon at the given index.

The function throws an exception if the index in invalid, i.e., >= size().

Definition at line 130 of file taxonomy.cpp.

◆ begin() [1/2]

Taxonomy::const_iterator begin ( )

Return an iterator to the beginning of the child taxa.

Definition at line 233 of file taxonomy.cpp.

◆ begin() [2/2]

const_iterator begin ( ) const

Return a const iterator to the beginning of the child taxa.

◆ cbegin()

Taxonomy::const_iterator cbegin ( ) const

Return a const iterator to the beginning of the child taxa.

Definition at line 253 of file taxonomy.cpp.

◆ cend()

Taxonomy::const_iterator cend ( ) const

Return a const iterator to the end of the child taxa.

Definition at line 258 of file taxonomy.cpp.

◆ clear_children()

void clear_children ( )

Remove all children.

Definition at line 224 of file taxonomy.cpp.

◆ end() [1/2]

Taxonomy::const_iterator end ( )

Return an iterator to the end of the child taxa.

Definition at line 238 of file taxonomy.cpp.

◆ end() [2/2]

const_iterator end ( ) const

Return a const iterator to the end of the child taxa.

◆ get_child() [1/2]

Taxon & get_child ( std::string name )

Return the child Taxon with a given name if it exists, or throw otherwise.

Definition at line 110 of file taxonomy.cpp.

◆ get_child() [2/2]

Taxon const & get_child ( std::string name ) const

Return the child Taxon with a given name if it exists, or throw otherwise.

Definition at line 100 of file taxonomy.cpp.

◆ has_child()

bool has_child ( std::string name ) const

Return whether an immediate child Taxon with the given name exists.

Definition at line 89 of file taxonomy.cpp.

◆ index_of()

size_t index_of ( std::string const & name ) const

Definition at line 164 of file taxonomy.cpp.

◆ operator=() [1/2]

Taxonomy & operator= ( Taxonomy && other )

Move assignment operator.

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

Definition at line 64 of file taxonomy.cpp.

◆ operator=() [2/2]

Taxonomy & operator= ( Taxonomy const & other )

Copy assigment operator.

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

Definition at line 57 of file taxonomy.cpp.

◆ operator[]() [1/4]

Taxon & operator[] ( size_t index )

Return the child Taxon at the given index.

The function does not check whether the provided index is within the valid range of size().

Definition at line 159 of file taxonomy.cpp.

◆ operator[]() [2/4]

Taxon const & operator[] ( size_t index ) const

Return the child Taxon at the given index.

The function does not check whether the provided index is within the valid range of size().

Definition at line 154 of file taxonomy.cpp.

◆ operator[]() [3/4]

Taxon & operator[] ( std::string name )

Return the child Taxon with a given name if it exists, or throw otherwise.

Definition at line 125 of file taxonomy.cpp.

◆ operator[]() [4/4]

Taxon const & operator[] ( std::string name ) const

Return the child Taxon with a given name if it exists, or throw otherwise.

Definition at line 120 of file taxonomy.cpp.

◆ remove_at()

void remove_at ( size_t index )

Remove a child Taxon at a certain index.

The Taxon (and all its sub-taxa) are destroyed. Throws an std::runtime_error if the index is out of bounds.

Definition at line 213 of file taxonomy.cpp.

◆ remove_child()

void remove_child ( std::string const & name )

Remove a child Taxon with a certain name.

The Taxon (and all its sub-taxa) are destroyed. Throws an std::runtime_error if there is no Taxon with the given name.

Definition at line 192 of file taxonomy.cpp.

◆ reset_parent_pointers_()

void reset_parent_pointers_ ( Taxon * parent )

protected

Internal helper function that resets the parent pointer of all stored Taxa.

This function is used whenever the children_ container is changed (copy, move, add elements) in order to make sure that all parent pointers are correct.

As all constructors and assignment operators use this function, we also make sure that adding or removing elements or changing their order (sort etc) does not break the correctness of the parent pointers. This might be slightly inefficient if many such moves (and thus, reset operations) are done in sequence. However, this is acceptable in order to keep the object stable at any time.

Definition at line 293 of file taxonomy.cpp.

◆ size()

size_t size ( ) const

Return the number of immediate child Taxa.

See total_taxa_count() for counting all Taxa, including all nested ones.

Definition at line 84 of file taxonomy.cpp.

◆ sort()

void sort ( Compare comp )

inline

Sort the taxonomy according to some compare criterion.

Definition at line 263 of file taxonomy/taxonomy.hpp.

Friends And Related Function Documentation

◆ swap

void swap	(	Taxonomy &	lhs,
		Taxonomy &	rhs
	)

friend

Swapperator for Taxonomy.

Definition at line 74 of file taxonomy.cpp.

Member Typedef Documentation

◆ const_iterator

typedef std::list<Taxon>::const_iterator const_iterator

Definition at line 105 of file taxonomy/taxonomy.hpp.

◆ iterator

typedef std::list<Taxon>::iterator iterator

Definition at line 104 of file taxonomy/taxonomy.hpp.

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

Detailed Description

Public Member Functions

Public Types

Protected Member Functions

Friends

Constructor & Destructor Documentation

◆ Taxonomy() [1/3]

◆ ~Taxonomy()

◆ Taxonomy() [2/3]

◆ Taxonomy() [3/3]

Member Function Documentation

◆ add_child() [1/2]

◆ add_child() [2/2]

◆ add_child_()

◆ at() [1/2]

◆ at() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ cbegin()

◆ cend()

◆ clear_children()

◆ end() [1/2]

◆ end() [2/2]

◆ get_child() [1/2]

◆ get_child() [2/2]

◆ has_child()

◆ index_of()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]() [1/4]

◆ operator[]() [2/4]

◆ operator[]() [3/4]

◆ operator[]() [4/4]

◆ remove_at()

◆ remove_child()

◆ reset_parent_pointers_()

◆ size()

◆ sort()

Friends And Related Function Documentation

◆ swap

Member Typedef Documentation

◆ const_iterator

◆ iterator