SeqAn3
seqan3::union_composition< alternative_types > Class Template Reference

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

#include <seqan3/alphabet/composition/union_composition.hpp>

Inheritance diagram for seqan3::union_composition< alternative_types >:
[legend]

Public Types

using char_type = char_t
 The type of the alphabet when converted to char (e.g. via to_char()).
 
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()).
 

Public Member Functions

Constructors, destructor and assignment
constexpr union_composition ()=default
 
constexpr union_composition (union_composition const &)=default
 
constexpr union_composition (union_composition &&)=default
 
constexpr union_compositionoperator= (union_composition const &)=default
 
constexpr union_compositionoperator= (union_composition &&)=default
 
 ~union_composition ()=default
 
template<typename alternative_t >
constexpr union_composition (alternative_t const &alternative) noexcept
 Construction via the value of an alternative. More...
 
template<typename indirect_alternative_t >
constexpr union_composition (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 union_compositionoperator= (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 union 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 union 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. `union_composition<dna5, gap>{gap::GAP} == 'C'_dna5`. Only (in-)equality comparison is explicitly defined, because it would be difficult to argue about e.g. `union_composition<dna5, gap>{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. `union_composition<dna5, gap>{'C'_dna5} == 'C'_rna5`. Only (in-)equality comparison is explicitly defined, because it would be difficult to argue about e.g. `union_composition<dna5, gap>{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 union_composition< alternative_types... > & assign_char (std::conditional_t< std::Same< char_type, void >, char, char_type > const c) noexcept
 Assign from a character. More...
 
constexpr union_composition< 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 value_size
 The size of the alphabet, i.e. the number of different values it can take.
 

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, union_composition< alternative_types... > const &rhs) noexcept
 
template<typename lhs_t , typename ... alternative_types>
constexpr bool operator!= (lhs_t const &lhs, union_composition< alternative_types... > const &rhs) noexcept
 
Requirements for seqan3::alphabet_concept

You can expect these functions on all types that implement seqan3::alphabet_concept.

template<typename alphabet_type >
using underlying_char_t = typename underlying_char< alphabet_type >::type
 The char_type of the alphabet. [type metafunction shortcut]. More...
 
char_type to_char (alphabet_concept const alph)
 Returns the alphabet letter's value in character representation. More...
 
alphabet_concept && assign_char (alphabet_concept &&alph, char_type const chr)
 Returns the alphabet letter's value in character representation. More...
 
Requirements for seqan3::semi_alphabet_concept

You can expect these functions on all types that implement seqan3::semi_alphabet_concept.

template<typename semi_alphabet_type >
using underlying_rank_t = typename underlying_rank< semi_alphabet_type >::type
 The rank_type of the semi_alphabet. [type metafunction shortcut]. More...
 
template<typename alphabet_type >
constexpr auto alphabet_size_v = alphabet_size<alphabet_type>::value
 The size of the alphabet. [value metafunction shortcut]. More...
 
rank_type to_rank (semi_alphabet_concept const alph)
 Returns the alphabet letter's value in rank representation. More...
 
semi_alphabet_concept && assign_rank (semi_alphabet_concept &&alph, rank_type const rank)
 Returns the alphabet letter's value in rank representation. 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...
 
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::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...
 

Detailed Description

template<typename ... alternative_types>
class seqan3::union_composition< 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::alphabet_concept and be unique.

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

Short description:

  • combines multiple different alphabets in an "either-or"-fashion;
  • is itself a seqan3::alphabet_concept;
  • 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

union_composition<dna5, gap> letter{}; // implicitly 'A'_dna5
union_composition<dna5, gap> letter2{'C'_dna5}; // constructed from alternative (== 'C'_dna5)
union_composition<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::GAP
letter2.assign_char('K'); // unknown characters map to the default/unknown
// character of the first alternative type (== 'N'_dna5)
letter2 = gap::GAP; // assigned from alternative (== gap::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

Constructor & Destructor Documentation

◆ union_composition() [1/2]

template<typename ... alternative_types>
template<typename alternative_t >
constexpr seqan3::union_composition< alternative_types >::union_composition ( 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.
union_composition<dna4, gap> letter1{'C'_dna4}; // or
union_composition<dna4, gap> letter2 = gap::GAP;

◆ union_composition() [2/2]

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

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

Template Parameters
indirect_alternative_tA type that one of the alternative types is constructible from.
Parameters
rhsThe value that should be assigned.
union_composition<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 union_composition< alternative_types... > & seqan3::alphabet_base< union_composition< alternative_types... > , size, char >::assign_char ( std::conditional_t< std::Same< char_type, void >, char, char_type > const  c)
inlinenoexceptinherited

Assign from a character.

Satisfies the seqan3::alphabet_concept::assign_char() requirement via the seqan3::assign_char() wrapper.

Complexity

Constant.

Exceptions

Guaranteed not to throw.

◆ assign_rank()

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

Assign from a numeric value.

Satisfies the seqan3::semi_alphabet_concept::assign_rank() requirement via the seqan3::assign_rank() wrapper.

Complexity

Constant.

Exceptions

Guaranteed not to throw.

◆ convert_to() [1/2]

template<typename ... alternative_types>
template<size_t index>
constexpr auto seqan3::union_composition< 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 union_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::union_composition< 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 union_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::union_composition< 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::union_composition< 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::union_composition< alternative_types >::holds_alternative ( )
inlinestaticnoexcept

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

Template Parameters
alternative_tThe type to check.
using union_t = union_composition<dna5, gap>;
static_assert(union_t::holds_alternative<dna5>(), "dna5 is an alternative of union_t");
static_assert(!union_t::holds_alternative<dna4>(), "dna4 is not an alternative of union_t");
static_assert(union_t::holds_alternative<gap>(), "gap is an alternative of union_t");

◆ is_alternative() [1/2]

template<typename ... alternative_types>
template<size_t index>
constexpr bool seqan3::union_composition< alternative_types >::is_alternative ( ) const
inlinenoexcept

Whether the union 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::union_composition< alternative_types >::is_alternative ( ) const
inlinenoexcept

Whether the union 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 union_composition& seqan3::union_composition< 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_tA type that one of the alternatives is assignable from.
Parameters
rhsThe value of an alternative.
union_composition<dna4, gap> letter1{};
letter1 = 'C'_rna4;

◆ to_char()

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

Return the letter as a character of char_type.

Satisfies the seqan3::alphabet_concept::to_char() requirement via the seqan3::to_char() wrapper.

Complexity

Constant.

Exceptions

Guaranteed not to throw.

◆ to_rank()

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

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

Satisfies the seqan3::semi_alphabet_concept::to_rank() requirement via the to_rank() wrapper.

Complexity

Constant.

Exceptions

Guaranteed not to throw.


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