seqan3::cigar Class Reference

The seqan3::cigar semialphabet pairs a counter with a seqan3::cigar::operation letter. More...

#include <seqan3/alphabet/cigar/cigar.hpp>

Inheritance diagram for seqan3::cigar:

Public Types
using	operation = exposition_only::cigar_operation
	The (extended) cigar operation alphabet of M,D,I,H,N,P,S,X,=. More...

Public Member Functions
Constructors, destructor and assignment
constexpr	cigar () noexcept=default
	Defaulted.
constexpr	cigar (cigar const &) noexcept=default
	Defaulted.
constexpr	cigar (cigar &&) noexcept=default
	Defaulted.
constexpr cigar &	operator= (cigar const &) noexcept=default
	Defaulted.
constexpr cigar &	operator= (cigar &&) noexcept=default
	Defaulted.
	~cigar () noexcept=default
	Defaulted.
constexpr	cigar (component_type const alph) noexcept
	Construction via a value of one of the components. More...
constexpr cigar &	operator= (component_type const alph) noexcept
	Assignment via a value of one of the components. More...
Read functions
small_string< 11 >	to_string () const noexcept
	Return the string representation.
Write functions
cigar &	assign_string (small_string< 11 > const s) noexcept
	Assign from the string representation.
Get functions
template<size_t index>
constexpr auto	get (cigar &l) noexcept
	Tuple-like access to the contained components. More...
template<typename type >
constexpr auto	get (cigar &l) noexcept
	Tuple-like access to the contained components. More...
Read functions
All read operations are constant complexity.
constexpr	operator type () const noexcept
	Implicit cast to a single letter. Works only if the type is unique in the type list.
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 cigar &	assign_char (char_type const c) noexcept
	Assign from a character, implicitly converts invalid characters. More...
constexpr cigar &	assign_rank (rank_type const c) noexcept
	Assign from a numeric value. More...

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

Protected Types
Member types
using	char_type = std::conditional_t< std::same_as< void, void >, char, void >
	The char representation; conditional needed to make semi alphabet definitions legal. More...
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()). More...

Private Types
using	base_t = alphabet_tuple_base< cigar, uint32_t, exposition_only::cigar_operation >
	The base class.
using	component_list = meta::list< component_types... >
	A meta::list The types of each component in the composite.
using	seqan3_recursive_required_types = meta::concat< component_list, detail::transformation_trait_or_t< detail::recursive_required_types< component_types >, meta::list<> >... >
	Export this type's components and possibly the components' components in a visible manner.
using	seqan3_required_types = component_list
	Export this type's components in a visible manner.

Private Member Functions
constexpr void	assign_component_rank (ptrdiff_t const r) noexcept
	Assign via the rank of i-th component (does not update other components' state).
constexpr rank_type	to_component_rank () const noexcept
	Return the rank of the i-th component.

Static Private Member Functions
static constexpr rank_type	rank_sum_helper (component_types ... components, std::index_sequence< idx... > const &) noexcept
	For the given components, compute the combined rank.

Private Attributes
friend	derived_type
	Befriend the derived type so that it can instantiate. More...
rank_type	rank
	The value of the alphabet letter is stored as the rank.

Static Private Attributes
static constexpr std::array< rank_type, component_list::size()>	cummulative_alph_sizes
	The cumulative alphabet size products are cached.
static constexpr bool	is_component
	Is set to true if the type is contained in the type list.
static constexpr bool	is_unique_component
	Is set to true if the type is uniquely contained in the type list.
static constexpr bool	seqan3_alphabet_tuple_like
	Make specialisations of this template identifiable in metapgrogramming contexts.

Related Functions
(Note that these are not member functions.)
Literals
cigar::operation	operator""_cigar_operation (char const c) noexcept
	The seqan3::cigar::operation char literal. More...
Generic serialisation functions for all seqan3::semialphabet
All types that satisfy seqan3::semialphabet can be serialised via Cereal.
template<cereal_output_archive archive_t, semialphabet alphabet_t>
alphabet_rank_t< alphabet_t >	save_minimal (archive_t const &, alphabet_t const &l)
	Save an alphabet letter to stream. More...

Detailed Description

The seqan3::cigar semialphabet pairs a counter with a seqan3::cigar::operation letter.

This semialphabet represents a unit in a CIGAR string, typically found in the SAM and BAM formats. It consists of a number and a seqan3::cigar::operation symbol.

It has a "visual representation", but since this is a string and not a char, the type only models seqan3::writable_semialphabet and not seqan3::writable_alphabet. Members for reading/writing the string are provided.

To avoid confusion between string and char literal, this alphabet has no user defined literal operators. Always assign from a pair of uint32_t and seqan3::cigar::operation.

OP	Description
M	Alignment match (can be a sequence match or mismatch, used only in basic CIGAR representations)
I	Insertion to the reference
D	Deletion from the reference
N	Skipped region from the reference
S	Soft clipping (clipped sequences present in seqan3::sam_record::sequence)
H	Hard clipping (clipped sequences NOT present in seqan3::sam_record::sequence)
P	Padding (silent deletion from padded reference)
=	Sequence match
X	Sequence mismatch

Example

#include <seqan3/alphabet/cigar/cigar.hpp>
#include <seqan3/core/debug_stream.hpp>
 
using seqan3::operator""_cigar_operation;
 
int main()
{
    seqan3::cigar c{13, 'M'_cigar_operation};
    seqan3::debug_stream << c << '\n'; // "13M"
 
    c.assign_string("14X");
    seqan3::debug_stream << c << '\n'; // "14X"
}

See also

https://samtools.github.io/hts-specs/SAMv1.pdf#page=8

Member Typedef Documentation

char_type

using seqan3::alphabet_base< cigar , size, void >::char_type = std::conditional_t<std::same_as<void , void>, char, void >

protectedinherited

The char representation; conditional needed to make semi alphabet definitions legal.

We need a return type for seqan3::alphabet_base::to_char and seqan3::alphabet_base::assign_char other than void to make these in-class definitions valid when char_t is void.

This entity is stable. Since version 3.1.

operation

using seqan3::cigar::operation = exposition_only::cigar_operation

The (extended) cigar operation alphabet of M,D,I,H,N,P,S,X,=.

The CIGAR string can be either basic or extended. The only difference in the extended cigar alphabet is that aligned bases are classified as an actual match ('=') or mismatch ('X'). In contrast, the basic cigar alphabet only indicated the aligned status with an 'M', without further information if the bases are actually equal or not.

The main purpose of the seqan3::cigar::operation alphabet is to be used in the seqan3::cigar composition, where a cigar operation is paired with a count value.

OP	Description
M	Alignment match (can be a sequence match or mismatch, used only in basic CIGAR representations)
I	Insertion to the reference
D	Deletion from the reference
N	Skipped region from the reference
S	Soft clipping (clipped sequences present in seqan3::sam_record::sequence)
H	Hard clipping (clipped sequences NOT present in seqan3::sam_record::sequence)
P	Padding (silent deletion from padded reference)
=	Sequence match
X	Sequence mismatch

Example usage:

#include <seqan3/alphabet/cigar/cigar.hpp>
#include <seqan3/core/debug_stream.hpp>
 
using seqan3::operator""_cigar_operation;
 
int main()
{
    // Initialise a seqan3::cigar::operation:
    seqan3::cigar::operation match{'M'_cigar_operation};
 
    // you can print cigar_op values:
    seqan3::debug_stream << match << '\n'; // M
}

Note

Usually you do not want to manipulate cigar elements and vectors on your own but convert an alignment to a cigar and back. See seqan3::detail::get_cigar_vector for how to convert two aligned sequences into a cigar_vector.

See also

https://samtools.github.io/hts-specs/SAMv1.pdf#page=8

This entity is stable. Since version 3.1.

rank_type

using seqan3::alphabet_base< cigar , size, void >::rank_type = detail::min_viable_uint_t<size - 1>

protectedinherited

The type of the alphabet when represented as a number (e.g. via to_rank()).

This entity is stable. Since version 3.1.

Constructor & Destructor Documentation

cigar()

constexpr seqan3::cigar::cigar ( component_type const  alph )

inlineconstexprnoexcept

Construction via a value of one of the components.

Template Parameters

component_type

One of the component types; must be uniquely contained in the type list of the composite.

Parameters

[in]

alph

The value of a component that should be assigned.

#include <seqan3/alphabet/cigar/cigar.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    using seqan3::operator""_cigar_operation;
 
    // creates 10M, as the cigar_op field is not provided.
    seqan3::cigar letter1{10};
    seqan3::debug_stream << "letter1: " << letter1 << '\n'; // 10M
 
    // creates 0I, as the integer field is not provided.
    seqan3::cigar letter2{'I'_cigar_operation};
    seqan3::debug_stream << "letter2: " << letter2 << '\n'; // 0I
 
    // creates 10I, as both fields are explicitly given.
    seqan3::cigar letter3{10, 'I'_cigar_operation};
    seqan3::debug_stream << "letter3: " << letter3 << '\n'; // 10I
}

Member Function Documentation

assign_char()

constexpr cigar & seqan3::alphabet_base< cigar , size, void >::assign_char ( char_type const  c )

inlineconstexprnoexceptinherited

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.

This entity is stable. Since version 3.1.

assign_rank()

constexpr cigar & seqan3::alphabet_base< cigar , size, void >::assign_rank ( rank_type const  c )

inlineconstexprnoexceptinherited

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.

This entity is stable. Since version 3.1.

get() [1/2]

template<size_t index>

constexpr auto seqan3::cigar::get ( cigar &  l )

inlineconstexprnoexcept

Tuple-like access to the contained components.

Template Parameters

index

Return the i-th element.

Returns

A proxy to the contained element that models the same alphabets concepts and supports assignment.

#include <seqan3/alphabet/cigar/cigar.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    using seqan3::get;
    using seqan3::operator""_cigar_operation;
 
    seqan3::cigar letter{10, 'M'_cigar_operation};
 
    // Note this is equivalent to get<uint32_t>(letter)
    uint32_t size{get<0>(letter)};
 
    // Note this is equivalent to get<seqan3::cigar::operation>(letter)
    seqan3::cigar::operation cigar_char{get<1>(letter)};
 
    seqan3::debug_stream << "Size is "       << size       << '\n';
    seqan3::debug_stream << "Cigar char is " << cigar_char << '\n'; // seqan3::debug_stream converts to char on the fly.
 
}

get() [2/2]

template<typename type >

constexpr auto seqan3::cigar::get ( cigar &  l )

inlineconstexprnoexcept

Tuple-like access to the contained components.

Template Parameters

type	Return the element of specified type; only available if the type is unique in the set of components.

Returns

A proxy to the contained element that models the same alphabet concepts and supports assignment.

#include <seqan3/alphabet/cigar/cigar.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    using seqan3::get;
    using seqan3::operator""_cigar_operation;
 
    seqan3::cigar letter{10, 'M'_cigar_operation};
 
    // Note this is equivalent to get<0>(letter)
    uint32_t size{get<uint32_t>(letter)};
 
    // Note this is equivalent to get<1>(letter)
    seqan3::cigar::operation cigar_char{get<seqan3::cigar::operation>(letter)};
 
    seqan3::debug_stream << "Size is "       << size       << '\n';
    seqan3::debug_stream << "Cigar char is " << cigar_char << '\n'; // seqan3::debug_stream converts to char on the fly.
 
}

operator=()

constexpr cigar& seqan3::cigar::operator= ( component_type const  alph )

inlineconstexprnoexcept

Assignment via a value of one of the components.

Template Parameters

component_type

One of the component types; must be uniquely contained in the type list of the composite.

Parameters

[in]

alph

The value of a component that should be assigned.

#include <seqan3/alphabet/cigar/cigar.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    using seqan3::operator""_cigar_operation;
 
    seqan3::cigar letter{10, 'I'_cigar_operation};
    seqan3::debug_stream << "letter: " << letter << '\n'; // 10I
 
    letter = 'D'_cigar_operation;
    seqan3::debug_stream << "letter: " << letter << '\n'; // 10D
 
    letter = 20;
    seqan3::debug_stream << "letter: " << letter << '\n'; // 20D
}

to_char()

constexpr char_type seqan3::alphabet_base< cigar , size, void >::to_char ( ) const

inlineconstexprnoexceptinherited

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.

This entity is stable. Since version 3.1.

to_rank()

constexpr rank_type seqan3::alphabet_base< cigar , size, void >::to_rank ( ) const

inlineconstexprnoexceptinherited

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.

This entity is stable. Since version 3.1.

Friends And Related Function Documentation

operator""_cigar_operation()

cigar::operation operator""_cigar_operation ( char const  c )

related

The seqan3::cigar::operation char literal.

Returns

seqan3::cigar::operation

This entity is stable. Since version 3.1.

save_minimal()

template<cereal_output_archive archive_t, semialphabet alphabet_t>

alphabet_rank_t< alphabet_t > save_minimal ( archive_t const &  , alphabet_t const &  l  )

related

Save an alphabet letter to stream.

Template Parameters

archive_t	Must satisfy seqan3::cereal_output_archive.
alphabet_t	Type of l; must satisfy seqan3::semialphabet.

Parameters

l	The alphabet letter.

Delegates to seqan3::to_rank.

Attention

These functions are never called directly, see the Alphabet module on how to use serialisation.

This entity is stable. Since version 3.1.

Member Data Documentation

alphabet_size

constexpr detail::min_viable_uint_t<size> seqan3::alphabet_base< cigar , size, void >::alphabet_size

staticconstexprinherited

The size of the alphabet, i.e. the number of different values it can take.

This entity is stable. Since version 3.1.

derived_type

friend seqan3::alphabet_tuple_base< cigar , component_types >::cigar

privateinherited

Befriend the derived type so that it can instantiate.

See also

https://isocpp.org/blog/2017/04/quick-q-prevent-user-from-derive-from-incorrect-crtp-base

---

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

• seqan3/alphabet/cigar/cigar.hpp