SeqAn3  3.0.2
The Modern C++ library for sequence analysis.
output.hpp
Go to the documentation of this file.
1 // -----------------------------------------------------------------------------------------------------
2 // Copyright (c) 2006-2020, Knut Reinert & Freie Universität Berlin
3 // Copyright (c) 2016-2020, Knut Reinert & MPI für molekulare Genetik
4 // This file may be used, modified and/or redistributed under the terms of the 3-clause BSD-License
5 // shipped with this file and also available at: https://github.com/seqan/seqan3/blob/master/LICENSE.md
6 // -----------------------------------------------------------------------------------------------------
7 
13 #pragma once
14 
15 #include <cassert>
16 #include <fstream>
17 #include <string>
18 #include <variant>
19 #include <vector>
24 #include <seqan3/io/exception.hpp>
25 #include <seqan3/std/filesystem>
26 #include <seqan3/io/record.hpp>
30 #include <seqan3/io/detail/record.hpp>
41 #include <seqan3/std/ranges>
42 
43 namespace seqan3
44 {
45 
46 // ----------------------------------------------------------------------------
47 // sequence_file_output
48 // ----------------------------------------------------------------------------
49 
164 template <detail::fields_specialisation selected_field_ids_ = fields<field::seq, field::id, field::qual>,
165  detail::type_list_of_sequence_file_output_formats valid_formats_ =
166  type_list<format_embl, format_fasta, format_fastq, format_genbank, format_sam>>
168 {
169 public:
174  using selected_field_ids = selected_field_ids_;
177  using valid_formats = valid_formats_;
179  using stream_char_type = char;
181 
184 
185  static_assert([] () constexpr
186  {
187  for (field f : selected_field_ids::as_array)
188  if (!field_ids::contains(f))
189  return false;
190  return true;
191  }(),
192  "You selected a field that is not valid for sequence files, please refer to the documentation "
193  "of sequence_file_output::field_ids for the accepted values.");
194 
195  static_assert([] () constexpr
196  {
197  return !(selected_field_ids::contains(field::seq_qual) &&
199  (selected_field_ids::contains(field::qual))));
200  }(),
201  "You may not select field::seq_qual and either of field::seq and field::qual at the same time.");
202 
208  using value_type = void;
211  using reference = void;
213  using const_reference = void;
215  using size_type = void;
219  using iterator = detail::out_file_iterator<sequence_file_output>;
221  using const_iterator = void;
223  using sentinel = std::default_sentinel_t;
225 
229  sequence_file_output() = delete;
241 
258  selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
259  primary_stream{new std::ofstream{}, stream_deleter_default}
260  {
261  primary_stream->rdbuf()->pubsetbuf(stream_buffer.data(), stream_buffer.size());
262  static_cast<std::basic_ofstream<char> *>(primary_stream.get())->open(filename,
263  std::ios_base::out | std::ios::binary);
264 
265  if (!primary_stream->good())
266  throw file_open_error{"Could not open file " + filename.string() + " for writing."};
267 
268  // possibly add intermediate compression stream
269  secondary_stream = detail::make_secondary_ostream(*primary_stream, filename);
270 
271  // initialise format handler or throw if format is not found
272  detail::set_format(format, filename);
273  }
274 
290  template <output_stream stream_t,
291  sequence_file_output_format file_format>
293  requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, stream_char_type>
295  sequence_file_output(stream_t & stream,
296  file_format const & SEQAN3_DOXYGEN_ONLY(format_tag),
297  selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
298  primary_stream{&stream, stream_deleter_noop},
299  secondary_stream{&stream, stream_deleter_noop},
300  format{detail::sequence_file_output_format_exposer<file_format>{}}
301  {
302  static_assert(list_traits::contains<file_format, valid_formats>,
303  "You selected a format that is not in the valid_formats of this file.");
304  }
305 
307  template <output_stream stream_t,
308  sequence_file_output_format file_format>
310  requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, stream_char_type>
312  sequence_file_output(stream_t && stream,
313  file_format const & SEQAN3_DOXYGEN_ONLY(format_tag),
314  selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
315  primary_stream{new stream_t{std::move(stream)}, stream_deleter_default},
316  secondary_stream{&*primary_stream, stream_deleter_noop},
317  format{detail::sequence_file_output_format_exposer<file_format>{}}
318  {
319  static_assert(list_traits::contains<file_format, valid_formats>,
320  "You selected a format that is not in the valid_formats of this file.");
321  }
323 
345  iterator begin() noexcept
346  {
347  return {*this};
348  }
349 
364  sentinel end() noexcept
365  {
366  return {};
367  }
368 
387  template <typename record_t>
388  void push_back(record_t && r)
390  requires tuple_like<record_t> &&
391  requires { requires detail::is_type_specialisation_of_v<std::remove_cvref_t<record_t>, record>; }
393  {
394  write_record(detail::get_or_ignore<field::seq>(r),
395  detail::get_or_ignore<field::id>(r),
396  detail::get_or_ignore<field::qual>(r),
397  detail::get_or_ignore<field::seq_qual>(r));
398 
399  }
400 
422  template <typename tuple_t>
423  void push_back(tuple_t && t)
425  requires tuple_like<tuple_t>
427  {
428  // index_of might return npos, but this will be handled well by get_or_ignore (and just return ignore)
429  write_record(detail::get_or_ignore<selected_field_ids::index_of(field::seq)>(t),
430  detail::get_or_ignore<selected_field_ids::index_of(field::id)>(t),
431  detail::get_or_ignore<selected_field_ids::index_of(field::qual)>(t),
432  detail::get_or_ignore<selected_field_ids::index_of(field::seq_qual)>(t));
433  }
434 
458  template <typename arg_t, typename ...arg_types>
459  void emplace_back(arg_t && arg, arg_types && ... args)
460  {
461  push_back(std::tie(arg, args...));
462  }
463 
485  template <std::ranges::input_range rng_t>
486  sequence_file_output & operator=(rng_t && range)
490  {
491  for (auto && record : range)
492  push_back(std::forward<decltype(record)>(record));
493  return *this;
494  }
495 
523  template <std::ranges::input_range rng_t>
528  {
529  f = range;
530  return f;
531  }
532 
534  template <std::ranges::input_range rng_t>
539  {
540  #if defined(__GNUC__) && (__GNUC__ == 9) // an unreported build problem of GCC9
541  for (auto && record : range)
542  f.push_back(std::forward<decltype(record)>(record));
543  #else // ^^^ workaround | regular solution ↓↓↓
544  f = range;
545  #endif
546  return std::move(f);
547  }
549 
552 
557  {
558  return *secondary_stream;
559  }
561 protected:
564  std::vector<char> stream_buffer{std::vector<char>(1'000'000)};
565 
573  static void stream_deleter_noop(std::basic_ostream<stream_char_type> *) {}
575  static void stream_deleter_default(std::basic_ostream<stream_char_type> * ptr) { delete ptr; }
576 
578  stream_ptr_t primary_stream{nullptr, stream_deleter_noop};
580  stream_ptr_t secondary_stream{nullptr, stream_deleter_noop};
581 
583  using format_type = typename detail::variant_from_tags<valid_formats,
584  detail::sequence_file_output_format_exposer>::type;
586  format_type format;
588 
590  template <typename seq_t, typename id_t, typename qual_t, typename seq_qual_t>
591  void write_record(seq_t && seq, id_t && id, qual_t && qual, seq_qual_t && seq_qual)
592  {
593  static_assert(detail::decays_to_ignore_v<seq_qual_t> ||
594  (detail::decays_to_ignore_v<seq_t> && detail::decays_to_ignore_v<qual_t>),
595  "You may not select field::seq_qual and either of field::seq and field::qual at the same time.");
596 
597  if constexpr (!detail::decays_to_ignore_v<seq_qual_t>)
598  static_assert(detail::is_type_specialisation_of_v<std::ranges::range_value_t<seq_qual_t>, qualified>,
599  "The SEQ_QUAL field must contain a range over the seqan3::qualified alphabet.");
600 
601  assert(!format.valueless_by_exception());
602  std::visit([&] (auto & f)
603  {
604  if constexpr (!detail::decays_to_ignore_v<seq_qual_t>)
605  {
606  f.write_sequence_record(*secondary_stream,
607  options,
608  seq_qual | views::get<0>,
609  id,
610  seq_qual | views::get<1>);
611  }
612  else
613  {
614  f.write_sequence_record(*secondary_stream,
615  options,
616  seq,
617  id,
618  qual);
619  }
620  }, format);
621  }
622 
624  friend iterator;
625 };
626 
632 template <output_stream stream_t,
634  sequence_file_output_format file_format>
636  file_format const &)
639 
641 template <output_stream stream_t,
642  sequence_file_output_format file_format>
644  file_format const &)
647 
649 template <output_stream stream_t,
650  sequence_file_output_format file_format,
651  detail::fields_specialisation selected_field_ids>
653  file_format const &,
654  selected_field_ids const &)
657 
659 template <output_stream stream_t,
660  sequence_file_output_format file_format,
661  detail::fields_specialisation selected_field_ids>
663  file_format const &,
664  selected_field_ids const &)
668 } // namespace seqan3
seqan3::sequence_file_output::reference
void reference
The reference type (void).
Definition: output.hpp:211
zip.hpp
Provides seqan3::views::zip.
seqan3::sequence_file_output::options
sequence_file_output_options options
The options are public and its members can be set directly.
Definition: output.hpp:551
fstream
pack_algorithm.hpp
Provides algorithms for meta programming, parameter packs and seqan3::type_list.
misc_output.hpp
Provides various utility functions required only for output.
seqan3::type_list
meta::list< types... > type_list
Type that contains multiple types, an alias for meta::list.
Definition: type_list.hpp:31
tuple.hpp
Provides seqan3::tuple_like.
concept.hpp
Stream concepts.
vector
std::vector::size
T size(T... args)
seqan3::sequence_file_output::operator=
sequence_file_output & operator=(rng_t &&range)
Write a range of records (or tuples) to the file.
Definition: output.hpp:486
seqan3::sequence_file_output::value_type
void value_type
The value type (void).
Definition: output.hpp:209
convert.hpp
Provides seqan3::views::convert.
seqan3::field::id
@ id
The identifier, usually a string.
std::unique_ptr::get
T get(T... args)
format_sam.hpp
Provides the seqan3::format_sam.
seqan3::sequence_file_output::begin
iterator begin() noexcept
Returns an iterator to current position in the file.
Definition: output.hpp:345
record.hpp
Provides the seqan3::record template and the seqan3::field enum.
std::function
filesystem
This header includes C++17 filesystem support and imports it into namespace std::filesystem (independ...
seqan3::sequence_file_output::valid_formats
valid_formats_ valid_formats
A seqan3::type_list with the possible formats.
Definition: output.hpp:177
std::filesystem::path
seqan3::sequence_file_output::sequence_file_output
sequence_file_output(stream_t &, file_format const &, selected_field_ids const &) -> sequence_file_output< selected_field_ids, type_list< file_format >>
This is an overloaded member function, provided for convenience. It differs from the above function o...
seqan3::pack_traits::contains
constexpr bool contains
Whether a type occurs in a pack or not.
Definition: traits.hpp:193
seqan3::fields
A class template that holds a choice of seqan3::field.
Definition: record.hpp:166
std::tie
T tie(T... args)
seqan3::seq
constexpr sequenced_policy seq
Global execution policy object for sequenced execution policy.
Definition: execution.hpp:54
seqan3::sequence_file_output::operator=
sequence_file_output & operator=(sequence_file_output const &)=delete
Copy assignment is explicitly deleted, because you can't have multiple access to the same file.
format_fastq.hpp
seqan3::sequence_file_output::sequence_file_output
sequence_file_output(sequence_file_output &&)=default
Move construction is defaulted.
seqan3::views::move
auto const move
A view that turns lvalue-references into rvalue-references.
Definition: move.hpp:68
seqan3::sequence_file_output::sequence_file_output
sequence_file_output(sequence_file_output const &)=delete
Copy construction is explicitly deleted, because you can't have multiple access to the same file.
std::basic_ostream
std::forward
T forward(T... args)
std::ofstream
seqan3::sequence_file_output::end
sentinel end() noexcept
Returns a sentinel for comparison with iterator.
Definition: output.hpp:364
seqan3::sequence_file_output::sentinel
std::default_sentinel_t sentinel
The type returned by end().
Definition: output.hpp:223
seqan3::sequence_file_output::selected_field_ids
selected_field_ids_ selected_field_ids
A seqan3::fields list with the fields selected for the record.
Definition: output.hpp:175
seqan3::sequence_file_output::sequence_file_output
sequence_file_output(stream_t &&, file_format const &) -> sequence_file_output< typename sequence_file_output<>::selected_field_ids, type_list< file_format >>
This is an overloaded member function, provided for convenience. It differs from the above function o...
exception.hpp
Provides exceptions used in the I/O module.
seqan3
The main SeqAn3 namespace.
Definition: aligned_sequence_concept.hpp:29
seqan3::sequence_file_output
A class for writing sequence files, e.g. FASTA, FASTQ ...
Definition: output.hpp:168
seqan3::sequence_file_output_options
The options type defines various option members that influence the behaviour of all or some formats.
Definition: output_options.hpp:22
seqan3::sequence_file_output::push_back
void push_back(tuple_t &&t)
Write a record in form of a std::tuple to the file.
Definition: output.hpp:423
output_options.hpp
Provides seqan3::sequence_file_output_options.
seqan3::sequence_file_output::const_reference
void const_reference
The const reference type (void).
Definition: output.hpp:213
format_fasta.hpp
std::format
T format(T... args)
seqan3::sequence_file_output::sequence_file_output
sequence_file_output(stream_t &&, file_format const &, selected_field_ids const &) -> sequence_file_output< selected_field_ids, type_list< file_format >>
Deduction guide for given stream, file format and field ids.
tuple_like
Whether a type behaves like a tuple.
seqan3::sequence_file_output::sequence_file_output
sequence_file_output(stream_t &stream, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})
Construct from an existing stream and with specified format.
Definition: output.hpp:295
output_format_concept.hpp
Provides seqan3::sequence_file_output_format and auxiliary classes.
ranges
Adaptations of concepts from the Ranges TS.
sequence_file_output_format
The generic concept for sequence file out formats.
seqan3::sequence_file_output::emplace_back
void emplace_back(arg_t &&arg, arg_types &&... args)
Write a record to the file by passing individual fields.
Definition: output.hpp:459
seqan3::sequence_file_output::const_iterator
void const_iterator
The const iterator type is void, because files are not const-iterable.
Definition: output.hpp:221
seqan3::sequence_file_output::iterator
detail::out_file_iterator< sequence_file_output > iterator
The iterator type of this view (an output iterator).
Definition: output.hpp:219
seqan3::sequence_file_output::~sequence_file_output
~sequence_file_output()=default
Destructor is defaulted.
seqan3::sequence_file_output::size_type
void size_type
The size type (void).
Definition: output.hpp:215
seqan3::sequence_file_output::operator|
friend sequence_file_output & operator|(rng_t &&range, sequence_file_output &f)
Write a range of records (or tuples) to the file.
Definition: output.hpp:524
cassert
seqan3::sequence_file_output::push_back
void push_back(record_t &&r)
Write a seqan3::record to the file.
Definition: output.hpp:388
seqan3::field
field
An enumerator for the fields used in file formats.
Definition: record.hpp:65
format_embl.hpp
seqan3::sequence_file_output::sequence_file_output
sequence_file_output(stream_t &&stream, file_format const &format_tag, selected_field_ids const &fields_tag=selected_field_ids{})
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: output.hpp:312
seqan3::record
The class template that file records are based on; behaves like an std::tuple.
Definition: record.hpp:226
std::ptrdiff_t
seqan3::sequence_file_output::sequence_file_output
sequence_file_output()=delete
Default constructor is explicitly deleted, you need to give a stream or file name.
std::visit
T visit(T... args)
seqan3::sequence_file_output::sequence_file_output
sequence_file_output(stream_t &, file_format const &) -> sequence_file_output< typename sequence_file_output<>::selected_field_ids, type_list< file_format >>
Deduction guide for given stream and file format.
seqan3::sequence_file_output::stream_char_type
char stream_char_type
Character type of the stream(s).
Definition: output.hpp:179
seqan3::sequence_file_output::operator=
sequence_file_output & operator=(sequence_file_output &&)=default
Move assignment is defaulted.
out_file_iterator.hpp
Provides the seqan3::detail::out_file_iterator class template.
seqan3::sequence_file_output::sequence_file_output
sequence_file_output(std::filesystem::path filename, selected_field_ids const &fields_tag=selected_field_ids{})
Construct from filename.
Definition: output.hpp:257
misc.hpp
Provides various utility functions.
traits.hpp
Provides traits for seqan3::type_list.
std::unique_ptr
seqan3::sequence_file_output::operator|
friend sequence_file_output operator|(rng_t &&range, sequence_file_output &&f)
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: output.hpp:535
std::vector::data
T data(T... args)
format_genbank.hpp
Provides the seqan3::sequence_file_format_genbank class.
get.hpp
Provides seqan3::views::get.
variant
string