SeqAn3  3.0.2
The Modern C++ library for sequence analysis.
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_typeoperator= (debug_stream_type const &)=default
 Defaulted.
 
debug_stream_typeoperator= (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...
 
Formatted output
template<typename t >
debug_stream_typeoperator<< (t &&v)
 Forwards to the underlying stream object.
 
debug_stream_typeoperator<< (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.

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_typeoperator<< (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_typeoperator<< (fmtflags2 const flag)
 Set the format flag(s) on the stream (current flags are ORed with the argument).
 

Private Attributes

fmtflags2 flgs2 {fmtflags2::default_}
 The SeqAn specific flags to the stream.
 
std::basic_ostream< char_t > * stream
 Pointer to the output stream.
 

Related Functions

(Note that these are not member functions.)

template<detail::matrix alignment_matrix_t, typename char_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 coordinate_type , typename char_t >
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 tuple_t , typename char_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 >
debug_stream_type< char_t > & operator<< (debug_stream_type< char_t > &stream, sam_flag const flag)
 Overload for the seqan3::sam_flags. 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<alphabet alphabet_t, typename char_t >
debug_stream_type< char_t > & operator<< (debug_stream_type< char_t > &s, alphabet_t const 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 optional_type , typename char_t >
debug_stream_type< char_t > & operator<< (debug_stream_type< char_t > &s, optional_type &&arg)
 Make std::nullopt_t printable. More...
 
template<typename optional_type , typename char_t >
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<std::ranges::input_range rng_t, typename char_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 variant_type , typename char_t >
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...
 

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

int main()
{
uint8_t i = 71;
seqan3::debug_stream << '\'' << i << "'\n"; // prints '71' (because flag is set by default)
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
outReference 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>
int main()
{
using seqan3::operator""_dna5;
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>
int main()
{
using seqan3::operator""_dna5;
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/12]

template<detail::matrix alignment_matrix_t, typename char_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_tType of the alignment matrix to be printed; must model seqan3::detail::matrix.
Parameters
sThe seqan3::debug_stream.
matrixThe alignment matrix.

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

◆ operator<<() [2/12]

template<alphabet alphabet_t, typename char_t >
debug_stream_type< char_t > & operator<< ( debug_stream_type< char_t > &  s,
alphabet_t const  l 
)
related

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

Template Parameters
alphabet_tType of the alphabet to be printed; must model seqan3::alphabet.
Parameters
sThe seqan3::debug_stream.
lThe alphabet letter.

◆ operator<<() [3/12]

template<typename coordinate_type , typename char_t >
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_typeThe alignment coordinate type.
Parameters
[in]sThe seqan3::debug_stream.
[in]cThe alignment coordinate to print.

Prints the alignment coordinate as a tuple.

◆ operator<<() [4/12]

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
sThe seqan3::debug_stream.
traceThe 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/12]

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_tType char type of the debug_stream.
Parameters
sThe seqan3::debug_stream.
lThe mask alphabet letter.

◆ operator<<() [6/12]

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_typeType of the enum to be printed.
Parameters
sThe seqan3::debug_stream.
opThe 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/12]

template<typename optional_type , typename char_t >
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_typeThe type of the optional.
Parameters
[in]sThe seqan3::debug_stream.
[in]argThe std::optional.

◆ operator<<() [8/12]

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

Make std::nullopt_t printable.

Template Parameters
optional_typeThis is std::nullopt_t.
Parameters
[in]sThe seqan3::debug_stream.
[in]argThis is std::nullopt.

◆ operator<<() [9/12]

template<std::ranges::input_range rng_t, typename char_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_tType of the range to be printed; must model std::ranges::input_range.
Parameters
sThe seqan3::debug_stream.
rThe 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]".

Note that overloads for range based streaming need to refine the seqan3::detail::debug_stream_range_guard concept to avoid ambiguous function calls.

◆ operator<<() [10/12]

template<typename tuple_t , typename char_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_tType of the tuple to be printed; must model seqan3::tuple_like.
Parameters
sThe seqan3::debug_stream.
tThe tuple.

◆ operator<<() [11/12]

template<typename variant_type , typename char_t >
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_typeThe type of the variant.
Parameters
[in]sThe seqan3::debug_stream.
[in]vThe variant.

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

◆ operator<<() [12/12]

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_tType char type of the debug_stream.
Parameters
streamThe seqan3::debug_stream.
flagThe flag to print.

The documentation for this class was generated from the following files:
seqan3::small_int_as_number
@ small_int_as_number
Definition: debug_stream_type.hpp:32
debug_stream.hpp
Provides seqan3::debug_stream and related types.
sstream
std::vector
seqan3::to_char
constexpr auto to_char
Return the char representation of an alphabet object.
Definition: concept.hpp:320
seqan3::views::to_rank
const auto to_rank
A view that calls seqan3::to_rank() on each element in the input range.
Definition: to_rank.hpp:67
iostream
std::cout
seqan3::debug_stream_type
A "pretty printer" for most SeqAn data structures and related types.
Definition: debug_stream_type.hpp:70
dna5.hpp
Provides seqan3::dna5, container aliases and string literals.
std::ostringstream::flush
T flush(T... args)
seqan3::debug_stream_type::unsetf
void unsetf(fmtflags const flag)
Unset the format flag(s) on the stream.
Definition: debug_stream_type.hpp:180
std::ostringstream
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition: debug_stream.hpp:42
std::ostringstream::str
T str(T... args)
seqan3::debug_stream_type::set_underlying_stream
void set_underlying_stream(std::basic_ostream< char_t > &out)
Change the underlying output stream.
Definition: debug_stream_type.hpp:109
to_rank.hpp
Provides seqan3::views::to_rank.