seqan3::debug_stream_type Class Reference

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

#include <seqan3/core/debug_stream.hpp>

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::ostream &out)
	Construction from an output stream.
Miscelleneous
void	set_underlying_stream (std::ostream &out)
	Change the underlying output stream. More...
Formatted output
template<typename t >
debug_stream_type &	operator<< (t &&v)
	Forwards to the underlying stream object.
debug_stream_type &	operator<< (std::ostream &(*fp)(std::ostream &))
	This overloads enables forwarding std::endl and other manipulators.
Format flags (std::ios_base::fmtflags)
std::ios_base::fmtflags that modify the stream's behaviour.
std::ios_base::fmtflags	flags () const
	Retrieve the format flags from the stream.
std::ios_base::fmtflags	flags (std::ios_base::fmtflags const flgs)
	Replace the current flags on the stream with the given argument.
void	setf (std::ios_base::fmtflags const flag)
	Set the format flag(s) on the stream (current flags are ORed with the argument).
void	unsetf (std::ios_base::fmtflags const flag)
	Unset the format flag(s) on the stream.
debug_stream_type &	operator<< (std::ios_base::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.)
debug_stream_type &	operator<< (debug_stream_type &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 tuple_t >
debug_stream_type &	operator<< (debug_stream_type &s, tuple_t &&t)
	All tuples can be printed by printing their elements separately. More...
template<typename variant_type >
debug_stream_type &	operator<< (debug_stream_type &s, variant_type &&v)
	A std::variant can be printed by visiting the stream operator for the corresponding type. More...
template<typename optional_type >
debug_stream_type &	operator<< (debug_stream_type &s, optional_type &&arg)
	A std::optional can be printed by printing its value or nothing if valueless. More...
template<std::ranges::InputRange rng_t>
debug_stream_type &	operator<< (debug_stream_type &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 coordinate_type >
debug_stream_type &	operator<< (debug_stream_type &s, coordinate_type &&c)
	A seqan3::alignment_coordinate can be printed to the seqan3::debug_stream. More...
template<detail::Matrix alignment_matrix_t>
debug_stream_type &	operator<< (debug_stream_type &s, alignment_matrix_t &&matrix)
	An alignment matrix can be printed to the seqan3::debug_stream. More...
Formatted output overloads
template<Alphabet alphabet_t>
debug_stream_type &	operator<< (debug_stream_type &s, alphabet_t const l)
	All alphabets can be printed to the seqan3::debug_stream by their char representation. More...

Detailed Description

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:

// This does not work:
// std::cout << 'C'_dna5;
// because the alphabet needs to be converted to char explicitly:
debug_stream << to_char('C'_dna5);  // prints 'C'

// The debug_stream, on the other hand, does this automatically:
debug_stream << 'C'_dna5;        // prints 'C'

// Vectors are also not printable to debug_stream:
std::vector<dna5> vec{"ACGT"_dna5};
//debug_stream << vec;
// but all types that model std::ranges::InputRange are printable to the debug_stream:
debug_stream << vec;            // prints "ACGT"

// ranges of non-alphabets are printed comma-separated:
debug_stream << (vec | view::to_rank); // prints "[0,1,2,3]"

Changing flags:

uint8_t i = 71;
debug_stream << '\'' << i << "'\n";                                     // prints '71' (because flag is set by default)
debug_stream.unsetf(fmtflags2::small_int_as_number);                    // unsets the flag
debug_stream << '\'' << i << "'\n";                                     // prints 'G'
debug_stream << 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::OStream fully,

Todo:

implement.

Member Function Documentation

set_underlying_stream()

void seqan3::debug_stream_type::set_underlying_stream ( std::ostream &  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.

{
    std::ostringstream o;
    debug_stream.set_underlying_stream(o);

    debug_stream << "ACGT"_dna5;

    o.flush();
    debug_stream << o.str(); // prints the string stream's buffer: "ACGT"
}

// this is UNDEFINED BEHAVIOUR, because the underlying stream went out-of-scope:
//debug_stream << 'C'_dna4;

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

{
    std::ostringstream o;
    debug_stream_type my_stream{o};

    my_stream << "ACGT"_dna5;

    o.flush();
    debug_stream << o.str(); // prints the string stream's buffer: "ACGT"
}
// now your custom debug stream went out of scope with its underlying stream

Friends And Related Function Documentation

operator<<() [1/8]

debug_stream_type & operator<< ( debug_stream_type &  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.

operator<<() [2/8]

template<Alphabet alphabet_t>

debug_stream_type & operator<< ( debug_stream_type &  s, alphabet_t const  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/8]

template<typename tuple_t >

debug_stream_type & operator<< ( debug_stream_type &  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::TupleLike.

Parameters

s	The seqan3::debug_stream.
t	The tuple.

operator<<() [4/8]

template<typename variant_type >

debug_stream_type & operator<< ( debug_stream_type &  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 underlying 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<<() [5/8]

template<typename optional_type >

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

related

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

Template Parameters

optional_type

The underlying type of the optional.

Parameters

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

operator<<() [6/8]

template<std::ranges::InputRange rng_t>

debug_stream_type & operator<< ( debug_stream_type &  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::InputRange.

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<<() [7/8]

template<typename coordinate_type >

debug_stream_type & operator<< ( debug_stream_type &  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<<() [8/8]

template<detail::Matrix alignment_matrix_t>

debug_stream_type & operator<< ( debug_stream_type &  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.

---

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

• seqan3/core/debug_stream.hpp
• seqan3/alignment/matrix/alignment_coordinate.hpp
• seqan3/alignment/matrix/debug_matrix.hpp
• seqan3/alignment/matrix/trace_directions.hpp