seqan3::debug_stream_type< char_t > Class Template Reference

A "pretty printer" for most SeqAn data structures and related types. More...

#include <seqan3/core/detail/debug_stream_type.hpp>

Public Types
using	fmtflags = decltype(std::declval< std::basic_ostream< char_t > >().flags())
	This type is std::ios_base::fmtflags.

Public Member Functions
Constructor, destructor and assignment.
The standard functions are explicitly defaulted.
	debug_stream_type ()=default
	Defaulted.
	debug_stream_type (debug_stream_type const &)=default
	Defaulted.
	debug_stream_type (debug_stream_type &&)=default
	Defaulted.
debug_stream_type &	operator= (debug_stream_type const &)=default
	Defaulted.
debug_stream_type &	operator= (debug_stream_type &&)=default
	Defaulted.
	~debug_stream_type ()=default
	Defaulted.
constexpr	debug_stream_type (std::basic_ostream< char_t > &out)
	Construction from an output stream.
Miscelleneous
void	set_underlying_stream (std::basic_ostream< char_t > &out)
	Change the underlying output stream. More...
Format flags (std::ios_base::fmtflags)
std::ios_base::fmtflags that modify the stream's behaviour.
fmtflags	flags () const
	Retrieve the format flags from the stream.
fmtflags	flags (fmtflags const flgs)
	Replace the current flags on the stream with the given argument.
void	setf (fmtflags const flag)
	Set the format flag(s) on the stream (current flags are ORed with the argument).
void	unsetf (fmtflags const flag)
	Unset the format flag(s) on the stream.
debug_stream_type &	operator<< (fmtflags const flag)
	Set the format flag(s) on the stream (current flags are ORed with the argument).
Format flags (seqan3::fmtflags2)
SeqAn specific debug flags for the debug stream.
fmtflags2	flags2 () const
	Retrieve the format flags from the stream.
fmtflags2	flags2 (fmtflags2 flgs)
	Replace the current flags on the stream with the given argument.
void	setf (fmtflags2 const flag)
	Set the format flag(s) on the stream (current flags are ORed with the argument).
void	unsetf (fmtflags2 const flag)
	Unset the format flag(s) on the stream.
debug_stream_type &	operator<< (fmtflags2 const flag)
	Set the format flag(s) on the stream (current flags are ORed with the argument).

Related Functions
(Note that these are not member functions.)
template<typename char_t , detail::matrix alignment_matrix_t>
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, alignment_matrix_t &&matrix)
	An alignment matrix can be printed to the seqan3::debug_stream. More...
template<typename char_t , typename coordinate_type >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, coordinate_type &&c)
	A seqan3::alignment_coordinate can be printed to the seqan3::debug_stream. More...
template<typename char_t >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, detail::trace_directions const trace)
	All trace_directions can be printed as ascii or as utf8 to the seqan3::debug_stream. More...
template<typename char_t , typename tuple_t >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, tuple_t &&t)
	All tuples can be printed by printing their elements separately. More...
template<typename char_t , typename alignment_result_t >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &stream, alignment_result_t &&result)
	Streams the seqan3::alignment_result to the seqan3::debug_stream. More...
template<typename char_t >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &stream, sam_flag const flag)
	Overload for the seqan3::sam_flags. More...
template<typename char_t , typename search_result_t >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &stream, search_result_t &&result)
	Print the seqan3::search_result to seqan3::debug_stream. More...
Formatted output overloads
template<typename char_t , typename option_type >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, option_type &&op)
	A type (e.g. an enum) can be made debug streamable by customizing the seqan3::enumeration_names. More...
template<typename char_t , alphabet alphabet_t>
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, alphabet_t &&l)
	All alphabets can be printed to the seqan3::debug_stream by their char representation. More...
template<typename char_t >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, mask const l)
	Overload for the seqan3::mask alphabet. More...
template<typename char_t >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, std::nullopt_t arg)
	Make std::nullopt_t printable. More...
template<typename char_t , typename optional_type >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, optional_type &&arg)
	A std::optional can be printed by printing its value or nothing if valueless. More...
template<typename char_t , std::ranges::input_range rng_t>
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, rng_t &&r)
	All input ranges can be printed to the seqan3::debug_stream element-wise (if their elements are printable). More...
template<typename char_t , typename variant_type >
debug_stream_type< char_t > &	operator<< (debug_stream_type< char_t > &s, variant_type &&v)
	A std::variant can be printed by visiting the stream operator for the corresponding type. More...

Formatted output
debug_stream_type &	operator<< (std::ostream &(*fp)(std::ostream &))
	This overloads enables forwarding std::endl and other manipulators.
template<typename other_char_t , typename t >
debug_stream_type< other_char_t > &	operator<< (debug_stream_type< other_char_t > &s, t &&v)
	Forwards to the underlying stream object.

Detailed Description

template<typename char_t = char>
class seqan3::debug_stream_type< char_t >

A "pretty printer" for most SeqAn data structures and related types.

A global instance of this type exists as seqan3::debug_stream. You can stream to it as you would to std::cout or std::cerr, but the debug stream has special overloads that make certain types streamable (that are not streamable to std::cout). Additionally some data structures are visualised more elaborately via the debug stream and there are extra flags to configure it (seqan3::fmtflags2).

Example

Simple usage:

#include <iostream>
 
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/to_rank.hpp>
 
int main()
{
    using seqan3::operator""_dna5;
 
    // The alphabet normally needs to be converted to char explicitly:
    std::cout << seqan3::to_char('C'_dna5);                // prints 'C'
 
    // The debug_stream, on the other hand, does this automatically:
    seqan3::debug_stream << 'C'_dna5;                      // prints 'C'
 
    // The debug_stream can also print all types that model std::ranges::input_range:
    std::vector<seqan3::dna5> vec{"ACGT"_dna5};
    seqan3::debug_stream << vec;                           // prints "ACGT"
 
    // ranges of non-alphabets are printed comma-separated:
    seqan3::debug_stream << (vec | seqan3::views::to_rank); // prints "[0,1,2,3]"
}

Changing flags:

#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    uint8_t i = 71;
    seqan3::debug_stream << '\'' << i << "'\n";                                           // prints '71' (because flag is set by default)
    seqan3::debug_stream.unsetf(seqan3::fmtflags2::small_int_as_number);                  // unsets the flag
    seqan3::debug_stream << '\'' << i << "'\n";                                           // prints 'G'
    seqan3::debug_stream << seqan3::fmtflags2::small_int_as_number << '\'' << i << "'\n"; // prints '71' again
    // instead of formatting the stream "inline", one can also call .setf()
}

See seqan3::fmtflags2 for more details.

Attention

This class does not yet model seqan3::output_stream_over fully,

Todo:

implement.

Member Function Documentation

set_underlying_stream()

template<typename char_t = char>

void seqan3::debug_stream_type< char_t >::set_underlying_stream ( std::basic_ostream< char_t > &  out )

inline

Change the underlying output stream.

Parameters

out	Reference to the new output stream.

The actual underlying stream that is printed to defaults to std::cerr, but can be changed via this function. You can set any kind of output stream, e.g. a std::ostringstream or a std::ofstream if you want to write to a file, but please be aware that the debug_stream never takes ownership of the underlying stream so you need to take special care that its object lifetime does not end before the debug_stream's.

#include <sstream>
 
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    using seqan3::operator""_dna5;
 
    std::ostringstream o;
    seqan3::debug_stream.set_underlying_stream(o);
 
    seqan3::debug_stream << "ACGT"_dna5;
 
    o.flush();
    seqan3::debug_stream << o.str(); // prints the string stream's buffer: "ACGT"
}

In the case where you wish to print to some stream object locally, instead create you own debug stream:

#include <sstream>
 
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    using seqan3::operator""_dna5;
 
    std::ostringstream o;
    seqan3::debug_stream_type my_stream{o};
 
    my_stream << "ACGT"_dna5;
 
    o.flush();
    seqan3::debug_stream << o.str(); // prints the string stream's buffer: "ACGT"
}

Friends And Related Function Documentation

operator<<() [1/14]

template<typename char_t , detail::matrix alignment_matrix_t>

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, alignment_matrix_t &&  matrix  )

related

An alignment matrix can be printed to the seqan3::debug_stream.

Template Parameters

alignment_matrix_t

Type of the alignment matrix to be printed; must model seqan3::detail::matrix.

Parameters

s	The seqan3::debug_stream.
matrix	The alignment matrix.

This prints out an alignment matrix which can be a score matrix or a trace matrix.

operator<<() [2/14]

template<typename char_t , alphabet alphabet_t>

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, alphabet_t &&  l  )

related

All alphabets can be printed to the seqan3::debug_stream by their char representation.

Template Parameters

alphabet_t

Type of the alphabet to be printed; must model seqan3::alphabet.

Parameters

s	The seqan3::debug_stream.
l	The alphabet letter.

operator<<() [3/14]

template<typename char_t , typename coordinate_type >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, coordinate_type &&  c  )

related

A seqan3::alignment_coordinate can be printed to the seqan3::debug_stream.

Template Parameters

coordinate_type

The alignment coordinate type.

Parameters

[in]	s	The seqan3::debug_stream.
[in]	c	The alignment coordinate to print.

Prints the alignment coordinate as a tuple.

operator<<() [4/14]

template<typename char_t >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, detail::trace_directions const  trace  )

related

All trace_directions can be printed as ascii or as utf8 to the seqan3::debug_stream.

Parameters

s	The seqan3::debug_stream.
trace	The trace direction.

The following table shows the printed symbol of a particular seqan3::detail::trace_directions:

trace direction	utf8	ascii
seqan3::detail::trace_directions::none	↺	N
seqan3::detail::trace_directions::diagonal	↖	D
seqan3::detail::trace_directions::up_open	↑	U
seqan3::detail::trace_directions::up	⇡	u
seqan3::detail::trace_directions::left_open	←	L
seqan3::detail::trace_directions::left	⇠	l

operator<<() [5/14]

template<typename char_t >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, mask const  l  )

related

Overload for the seqan3::mask alphabet.

Template Parameters

char_t

Type char type of the debug_stream.

Parameters

s	The seqan3::debug_stream.
l	The mask alphabet letter.

operator<<() [6/14]

template<typename char_t , typename option_type >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, option_type &&  op  )

related

A type (e.g. an enum) can be made debug streamable by customizing the seqan3::enumeration_names.

Template Parameters

option_type

Type of the enum to be printed.

Parameters

s	The seqan3::debug_stream.
op	The value to print.

This searches the seqan3::enumeration_names of the respective type for the value op and prints the respective string if found or '<UNKNOWN_VALUE>' if the value cannot be found in the map.

operator<<() [7/14]

template<typename char_t , typename optional_type >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, optional_type &&  arg  )

related

A std::optional can be printed by printing its value or nothing if valueless.

Template Parameters

optional_type

The type of the optional.

Parameters

[in]	s	The seqan3::debug_stream.
[in]	arg	The std::optional.

operator<<() [8/14]

template<typename char_t , std::ranges::input_range rng_t>

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, rng_t &&  r  )

related

All input ranges can be printed to the seqan3::debug_stream element-wise (if their elements are printable).

Template Parameters

rng_t

Type of the range to be printed; must model std::ranges::input_range.

Parameters

s	The seqan3::debug_stream.
r	The input range.

If the element type models seqan3::alphabet (and is not an unsigned integer), the range is printed just as if it were a string, i.e. std::vector<dna4>{'C'_dna4, 'G'_dna4, 'A'_dna4} is printed as "CGA".

In all other cases the elements are comma separated and the range is enclosed in brackets, i.e. std::vector<int>{3, 1, 33, 7} is printed as "[3,1,33,7]".

operator<<() [9/14]

template<typename char_t >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, std::nullopt_t  arg  )

related

Make std::nullopt_t printable.

Template Parameters

optional_type

This is std::nullopt_t.

Parameters

[in]	s	The seqan3::debug_stream.
[in]	arg	This is std::nullopt.

operator<<() [10/14]

template<typename char_t , typename tuple_t >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, tuple_t &&  t  )

related

All tuples can be printed by printing their elements separately.

Template Parameters

tuple_t

Type of the tuple to be printed; must model seqan3::tuple_like.

Parameters

s	The seqan3::debug_stream.
t	The tuple.

operator<<() [11/14]

template<typename char_t , typename variant_type >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s, variant_type &&  v  )

related

A std::variant can be printed by visiting the stream operator for the corresponding type.

Template Parameters

variant_type

The type of the variant.

Parameters

[in]	s	The seqan3::debug_stream.
[in]	v	The variant.

Note that in case the variant is valueless(_by_exception), nothing is printed.

operator<<() [12/14]

template<typename char_t , typename alignment_result_t >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  stream, alignment_result_t &&  result  )

related

Streams the seqan3::alignment_result to the seqan3::debug_stream.

Template Parameters

char_t	The underlying character type of the seqan3::debug_stream_type.
alignment_result_t	A type specialisation of seqan3::alignment_result.

Parameters

[in,out]	stream	The output stream.
[in]	result	The alignment result to print.

operator<<() [13/14]

template<typename char_t >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  stream, sam_flag const  flag  )

related

Overload for the seqan3::sam_flags.

Template Parameters

char_t

Type char type of the debug_stream.

Parameters

stream	The seqan3::debug_stream.
flag	The flag to print.

operator<<() [14/14]

template<typename char_t , typename search_result_t >

debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  stream, search_result_t &&  result  )

related

Print the seqan3::search_result to seqan3::debug_stream.

Template Parameters

char_t	The underlying character type of the seqan3::debug_stream_type.
search_result_t	A specialization of seqan3::search_result.

Parameters

stream	The stream.
result	The search result to print.

---

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

• seqan3/core/detail/debug_stream_type.hpp
• seqan3/alignment/matrix/alignment_coordinate.hpp
• seqan3/alignment/matrix/debug_matrix.hpp
• seqan3/alignment/matrix/trace_directions.hpp
• seqan3/alignment/pairwise/alignment_result.hpp
• seqan3/argument_parser/auxiliary.hpp
• seqan3/core/detail/debug_stream_alphabet.hpp
• seqan3/core/detail/debug_stream_optional.hpp
• seqan3/core/detail/debug_stream_range.hpp
• seqan3/core/detail/debug_stream_tuple.hpp
• seqan3/core/detail/debug_stream_variant.hpp
• seqan3/io/alignment_file/misc.hpp
• seqan3/search/search_result.hpp