SeqAn3
The Modern C++ library for sequence analysis.
seqan3::alphabet_variant< alternative_types > Class Template Reference

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_variantoperator= (alphabet_variant const &) noexcept=default
 Defaulted.
 
constexpr alphabet_variantoperator= (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
 Constructor for arguments implicitly convertible to an alternative. More...
 
template<typename indirect_alternative_t >
constexpr alphabet_variant (indirect_alternative_t const rhs) noexcept
 Constructor for arguments explicitly (but not implicitly) convertible to an alternative. More...
 
template<typename indirect_alternative_t >
constexpr alphabet_variantoperator= (indirect_alternative_t const &rhs) noexcept
 Assignment for arguments assignable to an alternative. 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
 Whether the variant alphabet currently holds a value of the given alternative. More...
 
template<typename alternative_t >
constexpr alternative_t convert_to () const
 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
 Convert to the specified alphabet (undefined behaviour if is_alternative() would be false). More...
 
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.
 

Friends

Comparison operators (against indirect alternatives)

Defines comparison against types that are not subject to implicit construction/conversion but are comparable against alternatives, e.g. alphabet_variant<seqan3::rna4, seqan3::gap> vs alphabet_variant<seqan3::dna4, seqan3::gap>. Only (in-)equality comparison is defined as reasoning about order of variants is inherently difficult.

template<typename alphabet_variant_t , typename indirect_alternative_type >
constexpr auto operator== (alphabet_variant_t const lhs, indirect_alternative_type const rhs) noexcept -> std::enable_if_t< detail::variant_comparison_guard< alphabet_variant_t, indirect_alternative_type, false, alternative_types... >, bool >
 (In-)Equality comparison against types comparable with alternatives but not convertible to the variant. More...
 
template<typename alphabet_variant_t , typename indirect_alternative_type >
constexpr auto operator!= (alphabet_variant_t const lhs, indirect_alternative_type const rhs) noexcept -> std::enable_if_t< detail::variant_comparison_guard< alphabet_variant_t, indirect_alternative_type, false, alternative_types... >, bool >
 (In-)Equality comparison against types comparable with alternatives but not convertible to the variant. More...
 
template<typename alphabet_variant_t , typename indirect_alternative_type , typename = void>
constexpr auto operator== (indirect_alternative_type const lhs, alphabet_variant_t const rhs) noexcept -> std::enable_if_t< detail::variant_comparison_guard< alphabet_variant_t, indirect_alternative_type, true, alternative_types... >, bool >
 (In-)Equality comparison against types comparable with alternatives but not convertible to the variant. More...
 
template<typename alphabet_variant_t , typename indirect_alternative_type , typename = void>
constexpr auto operator!= (indirect_alternative_type const lhs, alphabet_variant_t const rhs) noexcept -> std::enable_if_t< detail::variant_comparison_guard< alphabet_variant_t, indirect_alternative_type, true, alternative_types... >, bool >
 (In-)Equality comparison against types comparable with alternatives but not convertible to the variant. More...
 

Related Functions

(Note that these are not member functions.)

Requirements for std::totally_ordered

You can expect these functions on all types that implement std::totally_ordered.

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::equality_comparable

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_typesTypes of possible values (at least 2); all must model seqan3::writable_alphabet, std::regular and must be unique; all required functions for seqan3::writable_alphabet 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

int main()
{
using seqan3::operator""_dna5;
using seqan3::operator""_rna5;
seqan3::alphabet_variant<seqan3::dna5, seqan3::gap> letter{}; // implicitly 'A'_dna5
seqan3::alphabet_variant<seqan3::dna5, seqan3::gap> letter2{'C'_dna5}; // constructed from alternative (== 'C'_dna5)
seqan3::alphabet_variant<seqan3::dna5, seqan3::gap> letter3{'U'_rna5}; // constructed from type that alternative is constructible 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 = seqan3::gap{}; // assigned from alternative (== gap{})
letter2 = 'U'_rna5; // assigned from type that alternative is assignable from (== 'T'_dna5)
seqan3::dna5 letter4 = letter2.convert_to<seqan3::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.

int main()
{
using seqan3::operator""_dna5;
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/3]

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_tOne of the alternative types.
Parameters
alternativeThe value of a alternative that should be assigned.

◆ alphabet_variant() [2/3]

template<typename ... alternative_types>
template<typename indirect_alternative_t >
constexpr seqan3::alphabet_variant< alternative_types >::alphabet_variant ( indirect_alternative_t const  rhs)
inlinenoexcept

Constructor for arguments implicitly convertible to an alternative.

Template Parameters
indirect_alternative_tA type that is implicitly convertible to an alternative type.
Parameters
rhsThe value that should be assigned.

This constructor is preferred over the explicit version.

Example

  • seqan3::dna4 and seqan3::rna4 are implicitly convertible to each other so the variant accepts either.
  • Construction via {} considers implicit and explicit conversions.
  • Construction via = considers only implicit conversions (but that is sufficient here).

◆ alphabet_variant() [3/3]

template<typename ... alternative_types>
template<typename indirect_alternative_t >
constexpr seqan3::alphabet_variant< alternative_types >::alphabet_variant ( indirect_alternative_t const  rhs)
inlineexplicitnoexcept

Constructor for arguments explicitly (but not implicitly) convertible to an alternative.

Template Parameters
indirect_alternative_tA type that is explicitly (but not implicitly) convertible to an alternative type.
Parameters
rhsThe value that should be assigned.

Example

int main()
{
using seqan3::operator""_dna5;
// possible:
// not possible:
// seqan3::alphabet_variant<seqan3::dna4, seqan3::gap> letter2 = 'C'_dna5;
}
  • seqan3::dna4 and seqan3::dna5 are not implicitly convertible to each other, only explicitly.
  • Construction via {} considers implicit and explicit conversions so this works.
  • Construction via = considers only implicit conversions so it does not work.

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
cThe 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
cThe 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
indexIndex of the alternative to check for.
Exceptions
std::bad_variant_accessIf 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_tThe type of the alternative that you wish to check for.
Exceptions
std::bad_variant_accessIf 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
indexIndex 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_tThe 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_tThe type to check.
#include <gtest/gtest.h>
int main()
{
static_assert(variant_t::holds_alternative<seqan3::dna5>(), "dna5 is an alternative of variant_t");
static_assert(!variant_t::holds_alternative<seqan3::dna4>(), "dna4 is not an alternative of variant_t");
static_assert(variant_t::holds_alternative<seqan3::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
indexIndex 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_tThe 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 for arguments assignable to an alternative.

Template Parameters
indirect_alternative_tA type that one of the alternatives is assignable from.
Parameters
rhsThe value of an alternative.

Most assignments happen through implicit conversion and the defaulted assignment operator. This is for the rest.

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

Friends And Related Function Documentation

◆ operator!= [1/2]

template<typename ... alternative_types>
template<typename alphabet_variant_t , typename indirect_alternative_type >
constexpr auto operator!= ( alphabet_variant_t const  lhs,
indirect_alternative_type const  rhs 
) -> std::enable_if_t<detail::variant_comparison_guard<alphabet_variant_t, indirect_alternative_type, false, alternative_types...>, bool>
friend

(In-)Equality comparison against types comparable with alternatives but not convertible to the variant.

Template Parameters
alphabet_variant_tThe type of the variant; given as template parameter to prevent conversion.
indirect_alternative_typeMust be comparable with an alternative's type.
Parameters
lhsLeft-hand-side of comparison.
rhsRight-hand-side of comparison.
Returns
true or false.

To determine (in-)equality, it is first deduced which alternative the argument is comparable with. It is then checked if the variant currently is in that alternative's state and if yes whether the values compare to true; else false is returned.

◆ operator!= [2/2]

template<typename ... alternative_types>
template<typename alphabet_variant_t , typename indirect_alternative_type , typename = void>
constexpr auto operator!= ( indirect_alternative_type const  lhs,
alphabet_variant_t const  rhs 
) -> std::enable_if_t<detail::variant_comparison_guard<alphabet_variant_t, indirect_alternative_type, true, alternative_types...>, bool>
friend

(In-)Equality comparison against types comparable with alternatives but not convertible to the variant.

Template Parameters
alphabet_variant_tThe type of the variant; given as template parameter to prevent conversion.
indirect_alternative_typeMust be comparable with an alternative's type.
Parameters
lhsLeft-hand-side of comparison.
rhsRight-hand-side of comparison.
Returns
true or false.

To determine (in-)equality, it is first deduced which alternative the argument is comparable with. It is then checked if the variant currently is in that alternative's state and if yes whether the values compare to true; else false is returned.

◆ operator== [1/2]

template<typename ... alternative_types>
template<typename alphabet_variant_t , typename indirect_alternative_type >
constexpr auto operator== ( alphabet_variant_t const  lhs,
indirect_alternative_type const  rhs 
) -> std::enable_if_t<detail::variant_comparison_guard<alphabet_variant_t, indirect_alternative_type, false, alternative_types...>, bool>
friend

(In-)Equality comparison against types comparable with alternatives but not convertible to the variant.

Template Parameters
alphabet_variant_tThe type of the variant; given as template parameter to prevent conversion.
indirect_alternative_typeMust be comparable with an alternative's type.
Parameters
lhsLeft-hand-side of comparison.
rhsRight-hand-side of comparison.
Returns
true or false.

To determine (in-)equality, it is first deduced which alternative the argument is comparable with. It is then checked if the variant currently is in that alternative's state and if yes whether the values compare to true; else false is returned.

◆ operator== [2/2]

template<typename ... alternative_types>
template<typename alphabet_variant_t , typename indirect_alternative_type , typename = void>
constexpr auto operator== ( indirect_alternative_type const  lhs,
alphabet_variant_t const  rhs 
) -> std::enable_if_t<detail::variant_comparison_guard<alphabet_variant_t, indirect_alternative_type, true, alternative_types...>, bool>
friend

(In-)Equality comparison against types comparable with alternatives but not convertible to the variant.

Template Parameters
alphabet_variant_tThe type of the variant; given as template parameter to prevent conversion.
indirect_alternative_typeMust be comparable with an alternative's type.
Parameters
lhsLeft-hand-side of comparison.
rhsRight-hand-side of comparison.
Returns
true or false.

To determine (in-)equality, it is first deduced which alternative the argument is comparable with. It is then checked if the variant currently is in that alternative's state and if yes whether the values compare to true; else false is returned.


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