A combined alphabet that can hold values of either of its alternatives. More...

#include <seqan3/alphabet/composite/alphabet_variant.hpp>

Inheritance diagram for seqan3::alphabet_variant< alternative_types >:

Public Member Functions
Constructors, destructor and assignment
constexpr	alphabet_variant () noexcept=default
	Defaulted.

constexpr	alphabet_variant (alphabet_variant const &) noexcept=default
	Defaulted.

constexpr	alphabet_variant (alphabet_variant &&) noexcept=default
	Defaulted.

constexpr alphabet_variant &	operator= (alphabet_variant const &) noexcept=default
	Defaulted.

constexpr alphabet_variant &	operator= (alphabet_variant &&) noexcept=default
	Defaulted.

	~alphabet_variant () noexcept=default
	Defaulted.

template<typename alternative_t >
constexpr	alphabet_variant (alternative_t const &alternative) noexcept
	Construction via the value of an alternative. More...

template<typename indirect_alternative_t >
constexpr	alphabet_variant (indirect_alternative_t const &rhs) noexcept
	Construction via the value of a type that an alternative type is constructible from. More...

template<typename indirect_alternative_t >
constexpr alphabet_variant &	operator= (indirect_alternative_t const &rhs) noexcept
	Assignment via a value that one of the alternative types is assignable from. More...

Conversion (by index)
template<size_t index>
constexpr bool	is_alternative () const noexcept
	Whether the variant alphabet currently holds a value of the given alternative. More...

template<size_t index>
constexpr auto	convert_to () const
	Convert to the specified alphabet (throws if is_alternative() would be false). More...

template<size_t index>
constexpr auto	convert_unsafely_to () const noexcept
	Convert to the specified alphabet (undefined behaviour if is_alternative() would be false). More...

Conversion (by type)
template<typename alternative_t >
constexpr bool	is_alternative () const noexcept requires holds_alternative< alternative_t >()
	Whether the variant alphabet currently holds a value of the given alternative. More...

template<typename alternative_t >
constexpr alternative_t	convert_to () const requires holds_alternative< alternative_t >()
	Convert to the specified alphabet (throws if is_alternative() would be false). More...

template<typename alternative_t >
constexpr alternative_t	convert_unsafely_to () const noexcept requires holds_alternative< alternative_t >()
	Convert to the specified alphabet (undefined behaviour if is_alternative() would be false). More...

Comparison operators (against alternatives)
Defines comparison against alternatives, e.g. ‘alphabet_variant<dna5, gap>{gap{}} == 'C’_dna5`. Only (in-)equality comparison is explicitly defined, because it would be difficult to argue about e.g. ‘alphabet_variant<dna5, gap>{gap{}} < 'C’_dna5`.
template<typename alternative_t >
constexpr bool	operator== (alternative_t const rhs) const noexcept requires holds_alternative< alternative_t >()

template<typename alternative_t >
constexpr bool	operator!= (alternative_t const rhs) const noexcept requires holds_alternative< alternative_t >()

Comparison operators (against indirect alternatives)
Defines comparison against types that are comparable with alternatives, e.g. ‘alphabet_variant<dna5, gap>{'C’_dna5} == 'C'_rna5`. Only (in-)equality comparison is explicitly defined, because it would be difficult to argue about e.g. ‘alphabet_variant<dna5, gap>{gap{}} < 'C’_rna5`.
template<typename indirect_alternative_type >
constexpr bool	operator== (indirect_alternative_type const rhs) const noexcept

template<typename indirect_alternative_type >
constexpr bool	operator!= (indirect_alternative_type const rhs) const noexcept

Read functions
constexpr char_type	to_char () const noexcept
	Return the letter as a character of char_type. More...

constexpr rank_type	to_rank () const noexcept
	Return the letter's numeric value (rank in the alphabet). More...

Write functions
constexpr alphabet_variant< alternative_types... > &	assign_char (char_type const c) noexcept
	Assign from a character, implicitly converts invalid characters. More...

constexpr alphabet_variant< alternative_types... > &	assign_rank (rank_type const c) noexcept
	Assign from a numeric value. More...

Static Public Member Functions
template<typename alternative_t >
static constexpr bool	holds_alternative () noexcept
	Returns true if alternative_t is one of the given alternative types. More...

Static Public Attributes
static detail::min_viable_uint_t< size > constexpr	alphabet_size
	The size of the alphabet, i.e. the number of different values it can take.

Protected Types
Member types
using	char_type = std::conditional_t< std::Same< char, void >, char, char >
	The char representation; conditional needed to make semi alphabet definitions legal.

using	rank_type = detail::min_viable_uint_t< size - 1 >
	The type of the alphabet when represented as a number (e.g. via to_rank()).

Related Functions
(Note that these are not member functions.)
Comparison operators
Free function (in-)equality comparison operators that forward to member operators (for types != self).
template<typename lhs_t , typename ... alternative_types>
constexpr bool	operator== (lhs_t const lhs, alphabet_variant< alternative_types... > const rhs) noexcept

template<typename lhs_t , typename ... alternative_types>
constexpr bool	operator!= (lhs_t const lhs, alphabet_variant< alternative_types... > const rhs) noexcept

Requirements for std::StrictTotallyOrdered
You can expect these functions on all types that implement std::StrictTotallyOrdered.
bool	operator< (type const &lhs, type const &rhs)
	Less-than, greater-than and -or-equal comparisons. More...

bool	operator<= (type const &lhs, type const &rhs)
	Less-than, greater-than and -or-equal comparisons. More...

bool	operator> (type const &lhs, type const &rhs)
	Less-than, greater-than and -or-equal comparisons. More...

bool	operator>= (type const &lhs, type const &rhs)
	Less-than, greater-than and -or-equal comparisons. More...

Requirements for std::EqualityComparable
You can expect these functions on all types that implement std::Equality_comparable.
bool	operator== (type const &lhs, type const &rhs)
	(In-)Equality comparison. More...

bool	operator!= (type const &lhs, type const &rhs)
	(In-)Equality comparison. More...

Requirements for std::Swappable
You can expect these functions on all types that implement std::Swappable.
void	swap (t &lhs, t &rhs)
	Swaps the contents of two objects. More...

Detailed Description

template<typename ... alternative_types>
class seqan3::alphabet_variant< alternative_types >

A combined alphabet that can hold values of either of its alternatives.

Template Parameters

...alternative_types Types of possible values (at least 2); all must model seqan3::WritableAlphabet, must not be references and must be unique; all required functions for seqan3::WritableAlphabet need to be callable in a constexpr-context.

The alphabet_variant represents the union of two or more alternative alphabets (e.g. the four letter DNA alternative + the gap alternative). It behaves similar to a variant or std::variant, but it preserves the seqan3::Alphabet.

Short description:

combines multiple different alphabets in an "either-or"-fashion;
is itself a seqan3::Alphabet;
its alphabet size is the sum of the individual sizes;
default initialises to the the first alternative's default (no empty state like std::variant);
constructible, assignable and (in-)equality-comparable with each alternative type and also all types that these are constructible/assignable/equality-comparable with;
only convertible to its alternatives through the member function convert_to() (which can throw!)

Example

alphabet_variant<dna5, gap> letter{};          // implicitly 'A'_dna5
alphabet_variant<dna5, gap> letter2{'C'_dna5}; // constructed from alternative (== 'C'_dna5)
alphabet_variant<dna5, gap> letter3{'U'_rna5}; // constructed from type that alternative is constructable from (== 'T'_dna5)
letter2.assign_char('T');                       // == 'T'_dna5
letter2.assign_char('-');                       // == gap{}
letter2.assign_char('K');                       // unknown characters map to the default/unknown
                                                // character of the first alternative type (== 'N'_dna5)
letter2 = gap{};                                // assigned from alternative (== gap{})
letter2 = 'U'_rna5;                             // assigned from type that alternative is assignable from (== 'T'_dna5)
dna5 letter4 = letter2.convert_to<dna5>();      // this works
// gap letter5  = letter2.convert_to<gap>();    // this throws an exception, because the set value was 'T'_dna5

The `char` representation of an alphabet_variant

Part of the seqan3::Alphabet concept requires that the alphabet_variant provides a char representation in addition to the rank representation. For an object of seqan3::alphabet_variant, the to_char() member function will always return the same character as if invoked on the respective alternative. In contrast, the assign_char() member function might be ambiguous between the alternative alphabets in a variant.

For example, assigning a '!' to seqan3::dna15 resolves to an object of rank 8 with char representation 'N' while assigning '!' to seqan3::gap always resolves to rank 0, the gap symbol itself ('-'_gap). We tackle this ambiguousness by defaulting unknown characters to the representation of the first alternative (e.g. ‘alphabet_variant<dna15, gap>{}.assign_char(’!')resolves to rank 8, representingN`_dna15).

On the other hand, two alternative alphabets might have the same char representation (e.g if you combine dna4 with dna5, 'A', 'C', 'G' and 'T' are ambiguous). We tackle this ambiguousness by always choosing the first valid char representation (e.g. ‘alphabet_variant<dna4, dna5>{}.assign_char('A’)resolves to rank 0, representing anA`_dna4).

To explicitly assign via the character representation of a specific alphabet, assign to that type first and then assign to the variant, e.g.

alphabet_variant<dna4, dna5> var;
var.assign_char('A');             // will be in the "dna4-state"
var = 'A'_dna5;                   // will be in the "dna5-state"

Constructor & Destructor Documentation

◆ alphabet_variant() [1/2]

template<typename ... alternative_types>

template<typename alternative_t >

constexpr seqan3::alphabet_variant< alternative_types >::alphabet_variant ( alternative_t const & alternative )

inlinenoexcept

Construction via the value of an alternative.

Template Parameters

alternative_t One of the alternative types.

Parameters

alternative The value of a alternative that should be assigned.

alphabet_variant<dna4, gap> letter1{'C'_dna4}; // or

alphabet_variant<dna4, gap> letter2 = gap{};

◆ alphabet_variant() [2/2]

template<typename ... alternative_types>

template<typename indirect_alternative_t >

constexpr seqan3::alphabet_variant< alternative_types >::alphabet_variant ( indirect_alternative_t const & rhs )

inlinenoexcept

Construction via the value of a type that an alternative type is constructible from.

Template Parameters

indirect_alternative_t A type that one of the alternative types is constructible from.

Parameters

rhs	The value that should be assigned.

alphabet_variant<dna4, gap> letter1{'C'_rna4};

Attention: When selecting the alternative alphabet types which require only implicit conversion or constructor calls, are preferred over those that require explicit ones.

Member Function Documentation

◆ assign_char()

constexpr alphabet_variant< alternative_types... > & seqan3::alphabet_base< alphabet_variant< alternative_types... > , size, char >::assign_char ( char_type const c )

inlinenoexceptinherited

Assign from a character, implicitly converts invalid characters.

Parameters

c	The character to be assigned.

Provides an implementation for seqan3::assign_char_to, required to model seqan3::Alphabet.

Complexity

Constant.

Exceptions

Guaranteed not to throw.

◆ assign_rank()

constexpr alphabet_variant< alternative_types... > & seqan3::alphabet_base< alphabet_variant< alternative_types... > , size, char >::assign_rank ( rank_type const c )

inlinenoexceptinherited

Assign from a numeric value.

Parameters

c	The rank to be assigned.

Provides an implementation for seqan3::assign_rank_to, required to model seqan3::Semialphabet.

Complexity

Constant.

Exceptions

Guaranteed not to throw.

◆ convert_to() [1/2]

template<typename ... alternative_types>

template<size_t index>

constexpr auto seqan3::alphabet_variant< alternative_types >::convert_to ( ) const

inline

Convert to the specified alphabet (throws if is_alternative() would be false).

Template Parameters

index Index of the alternative to check for.

Exceptions

std::bad_variant_access If the variant_alphabet currently holds the value of a different alternative.

◆ convert_to() [2/2]

template<typename ... alternative_types>

template<typename alternative_t >

constexpr alternative_t seqan3::alphabet_variant< alternative_types >::convert_to ( ) const

inline

Convert to the specified alphabet (throws if is_alternative() would be false).

Template Parameters

alternative_t The type of the alternative that you wish to check for.

Exceptions

std::bad_variant_access If the variant_alphabet currently holds the value of a different alternative.

◆ convert_unsafely_to() [1/2]

template<typename ... alternative_types>

template<size_t index>

constexpr auto seqan3::alphabet_variant< alternative_types >::convert_unsafely_to ( ) const

inlinenoexcept

Convert to the specified alphabet (undefined behaviour if is_alternative() would be false).

Template Parameters

index Index of the alternative to check for.

◆ convert_unsafely_to() [2/2]

template<typename ... alternative_types>

template<typename alternative_t >

constexpr alternative_t seqan3::alphabet_variant< alternative_types >::convert_unsafely_to ( ) const

inlinenoexcept

Convert to the specified alphabet (undefined behaviour if is_alternative() would be false).

Template Parameters

alternative_t The type of the alternative that you wish to check for.

◆ holds_alternative()

template<typename ... alternative_types>

template<typename alternative_t >

static constexpr bool seqan3::alphabet_variant< alternative_types >::holds_alternative ( )

inlinestaticnoexcept

Returns true if alternative_t is one of the given alternative types.

Template Parameters

alternative_t The type to check.

using variant_t = alphabet_variant<dna5, gap>;
static_assert(variant_t::holds_alternative<dna5>(), "dna5 is an alternative of variant_t");
static_assert(!variant_t::holds_alternative<dna4>(), "dna4 is not an alternative of variant_t");
static_assert(variant_t::holds_alternative<gap>(), "gap is an alternative of variant_t");

◆ is_alternative() [1/2]

template<typename ... alternative_types>

template<size_t index>

constexpr bool seqan3::alphabet_variant< alternative_types >::is_alternative ( ) const

inlinenoexcept

Whether the variant alphabet currently holds a value of the given alternative.

Template Parameters

index Index of the alternative to check for.

◆ is_alternative() [2/2]

template<typename ... alternative_types>

template<typename alternative_t >

constexpr bool seqan3::alphabet_variant< alternative_types >::is_alternative ( ) const

inlinenoexcept

Whether the variant alphabet currently holds a value of the given alternative.

Template Parameters

alternative_t The type of the alternative that you wish to check for.

◆ operator=()

template<typename ... alternative_types>

template<typename indirect_alternative_t >

constexpr alphabet_variant& seqan3::alphabet_variant< alternative_types >::operator= ( indirect_alternative_t const & rhs )

inlinenoexcept

Assignment via a value that one of the alternative types is assignable from.

Template Parameters

indirect_alternative_t A type that one of the alternatives is assignable from.

Parameters

rhs	The value of an alternative.

alphabet_variant<dna4, gap> letter1{};

letter1 = 'C'_rna4;

◆ to_char()

constexpr char_type seqan3::alphabet_base< alphabet_variant< alternative_types... > , size, char >::to_char ( ) const

inlinenoexceptinherited

Return the letter as a character of char_type.

Provides an implementation for seqan3::to_char, required to model seqan3::Alphabet.

Complexity

Constant.

Exceptions

Guaranteed not to throw.

◆ to_rank()

constexpr rank_type seqan3::alphabet_base< alphabet_variant< alternative_types... > , size, char >::to_rank ( ) const

inlinenoexceptinherited

Return the letter's numeric value (rank in the alphabet).

Provides an implementation for seqan3::to_rank, required to model seqan3::Semialphabet.

Complexity

Constant.

Exceptions

Guaranteed not to throw.

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

seqan3/alphabet/composite/alphabet_variant.hpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Types

Related Functions

Detailed Description

template<typename ... alternative_types> class seqan3::alphabet_variant< alternative_types >

Example

The char representation of an alphabet_variant

Constructor & Destructor Documentation

◆ alphabet_variant() [1/2]

◆ alphabet_variant() [2/2]

Member Function Documentation

◆ assign_char()

Complexity

Exceptions

◆ assign_rank()

Complexity

Exceptions

◆ convert_to() [1/2]

◆ convert_to() [2/2]

◆ convert_unsafely_to() [1/2]

◆ convert_unsafely_to() [2/2]

◆ holds_alternative()

◆ is_alternative() [1/2]

◆ is_alternative() [2/2]

◆ operator=()

◆ to_char()

Complexity

Exceptions

◆ to_rank()

Complexity

Exceptions

template<typename ... alternative_types>
class seqan3::alphabet_variant< alternative_types >

The `char` representation of an alphabet_variant