SeqAn3 3.4.0-rc.1
The Modern C++ library for sequence analysis.
|
A class for reading sequence files, e.g. FASTA, FASTQ ... More...
#include <seqan3/io/sequence_file/input.hpp>
Public Types | |
using | field_ids = fields< field::seq, field::id, field::qual > |
The subset of seqan3::field IDs that are valid for this file; order corresponds to the types in field_types. | |
using | sequence_file_input_options_type = sequence_file_input_options< typename traits_type::sequence_legal_alphabet > |
The input file options type. | |
Template arguments | |
Exposed as member types for public access. | |
using | traits_type = traits_type_ |
A traits type that defines aliases and template for storage of the fields. | |
using | selected_field_ids = selected_field_ids_ |
A seqan3::fields list with the fields selected for the record. | |
using | valid_formats = valid_formats_ |
A seqan3::type_list with the possible formats. | |
using | stream_char_type = char |
Character type of the stream(s). | |
Field types and record type | |
These types are relevant for record/row-based reading; they may be manipulated via the traits_type to achieve different storage behaviour. | |
using | sequence_type = typename traits_type::template sequence_container< typename traits_type::sequence_alphabet > |
The type of field::seq (std::vector <seqan3::dna5> by default). | |
using | id_type = typename traits_type::template id_container< typename traits_type::id_alphabet > |
The type of field::id (std::string by defaul). | |
using | quality_type = typename traits_type::template quality_container< typename traits_type::quality_alphabet > |
The type of field::qual (std::vector <seqan3::phred42> by default). | |
using | field_types = type_list< sequence_type, id_type, quality_type > |
The previously defined types aggregated in a seqan3::type_list. | |
using | record_type = sequence_record< detail::select_types_with_ids_t< field_types, field_ids, selected_field_ids >, selected_field_ids > |
The type of the record, a specialisation of seqan3::record; acts as a tuple of the selected field types. | |
Range associated types | |
The types necessary to facilitate the behaviour of an input range (used in record-wise reading). | |
using | value_type = record_type |
The value_type is the record_type. | |
using | reference = record_type & |
The reference type. | |
using | const_reference = void |
The const_reference type is void, because files are not const-iterable. | |
using | size_type = size_t |
An unsigned integer type, usually std::size_t. | |
using | difference_type = std::make_signed_t< size_t > |
A signed integer type, usually std::ptrdiff_t. | |
using | iterator = detail::in_file_iterator< sequence_file_input > |
The iterator type of this view (an input iterator). | |
using | const_iterator = void |
The const iterator type is void, because files are not const-iterable. | |
using | sentinel = std::default_sentinel_t |
The type returned by end(). | |
Public Member Functions | |
Constructors, destructor and assignment | |
sequence_file_input ()=delete | |
Default constructor is explicitly deleted, you need to give a stream or file name. | |
sequence_file_input (sequence_file_input const &)=delete | |
Copy construction is explicitly deleted, because you can't have multiple access to the same file. | |
sequence_file_input & | operator= (sequence_file_input const &)=delete |
Copy assignment is explicitly deleted, because you can't have multiple access to the same file. | |
sequence_file_input (sequence_file_input &&)=default | |
Move construction is defaulted. | |
sequence_file_input & | operator= (sequence_file_input &&)=default |
Move assignment is defaulted. | |
~sequence_file_input ()=default | |
Destructor is defaulted. | |
sequence_file_input (std::filesystem::path filename, selected_field_ids const &fields_tag=selected_field_ids{}) | |
Construct from filename. | |
template<input_stream stream_t, sequence_file_input_format file_format> requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, stream_char_type> | |
sequence_file_input (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. | |
template<input_stream stream_t, sequence_file_input_format file_format> requires std::same_as<typename std::remove_reference_t<stream_t>::char_type, stream_char_type> | |
sequence_file_input (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 only in what argument(s) it accepts. | |
Range interface | |
Provides functions for record based reading of the file. | |
iterator | begin () |
Returns an iterator to current position in the file. | |
sentinel | end () noexcept |
Returns a sentinel for comparison with iterator. | |
reference | front () noexcept |
Return the record we are currently at in the file. | |
Public Attributes | |
sequence_file_input_options_type | options |
The options are public and its members can be set directly. | |
Related Symbols | |
(Note that these are not member symbols.) | |
Type deduction guides | |
template<input_stream stream_type, sequence_file_input_format file_format> | |
sequence_file_input (stream_type &stream, file_format const &) -> sequence_file_input< typename sequence_file_input<>::traits_type, typename sequence_file_input<>::selected_field_ids, type_list< file_format > > | |
Deduces the sequence input file type from the stream and the format. | |
template<input_stream stream_type, sequence_file_input_format file_format> | |
sequence_file_input (stream_type &&stream, file_format const &) -> sequence_file_input< typename sequence_file_input<>::traits_type, typename sequence_file_input<>::selected_field_ids, type_list< file_format > > | |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
template<input_stream stream_type, sequence_file_input_format file_format, detail::fields_specialisation selected_field_ids> | |
sequence_file_input (stream_type &&stream, file_format const &, selected_field_ids const &) -> sequence_file_input< typename sequence_file_input<>::traits_type, selected_field_ids, type_list< file_format > > | |
Deduces the sequence input file type from the stream, the format and the field ids. | |
template<input_stream stream_type, sequence_file_input_format file_format, detail::fields_specialisation selected_field_ids> | |
sequence_file_input (stream_type &stream, file_format const &, selected_field_ids const &) -> sequence_file_input< typename sequence_file_input<>::traits_type, selected_field_ids, type_list< file_format > > | |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
A class for reading sequence files, e.g. FASTA, FASTQ ...
traits_type | An auxiliary type that defines certain member types and constants, must satisfy seqan3::sequence_file_input_traits. (Default: seqan3::sequence_file_input_default_traits_dna) |
selected_field_ids | A seqan3::fields type with the list and order of desired record entries; all fields must be in seqan3::sequence_file_input::field_ids. |
valid_formats | A seqan3::type_list of the selectable formats (each must meet seqan3::sequence_file_input_format). |
sequence_file_input<>
(with angle brackets). In the latter case they are explicitly set to their default values, in the former case automatic deduction happens which chooses different parameters depending on the constructor arguments. For opening from file, sequence_file_input<>
would have also worked, but for opening from stream it would not have. In some cases, you do need to specify the arguments, e.g. if you want to read amino acids:record
has the type seqan3::sequence_file_input::record_type which is seqan3::sequence_record. Note: It is important to write auto &
and not just auto
, otherwise you will copy the record on every iteration. Since the buffer gets "refilled" on every iteration, you can also move the data out of the record if you want to store it somewhere without copying:sequence
of seqan3::sequence_file_input::sequence_type and id
of seqan3::sequence_file_input::id_type. But beware: with structured bindings you do need to get the order of elements correctly!selected_field_ids
parameter) are ignored.
|
inline |
Construct from filename.
[in] | filename | Path to the file you wish to open. |
[in] | fields_tag | A seqan3::fields tag. [optional] |
seqan3::file_open_error | If the file could not be opened, e.g. non-existant, non-readable, unknown format. |
In addition to the file name, you may specify a custom seqan3::fields type which may be easier than defining all the template parameters.
This constructor transparently applies a decompression stream on top of the file stream in case the file is detected as being compressed. See the section on compression and decompression for more information.
|
inline |
Construct from an existing stream and with specified format.
file_format | The format of the file in the stream, must satisfy seqan3::sequence_file_input_format. |
[in] | stream | The stream to operate on; must be derived of std::basic_istream. |
[in] | format_tag | The file format tag. |
[in] | fields_tag | A seqan3::fields tag. [optional] |
This constructor transparently applies a decompression stream on top of the stream in case it is detected as being compressed. See the section on compression and decompression for more information.
|
inline |
Returns an iterator to current position in the file.
seqan3::format_error |
Equals end() if the file is at end.
Constant.
Throws seqan3::format_error if the first record could not be read into the buffer.
|
inlinenoexcept |
Returns a sentinel for comparison with iterator.
This element acts as a placeholder; attempting to dereference it results in undefined behaviour.
Constant.
No-throw guarantee.
|
inlinenoexcept |
Return the record we are currently at in the file.
This function returns a reference to the currently buffered record, it is identical to dereferencing begin(), but begin also always points to the current record on single pass input ranges:
It most situations using the iterator interface or a range-based for-loop are preferable to using front(), because you can only move to the next record via the iterator.
In any case, don't forget the reference! If you want to save the data from the record elsewhere, use move:
Constant.
No-throw guarantee.