Merge pull request #2409 from marehr/sam_file06

[DOC] test/snippet/io/{alignment => sam}_file

include/seqan3/io/alignment_file/detail.hpp

@@ -130,7 +130,7 @@ template <typename reference_char_type, typename query_char_type>
  * the following cigar vector: "[('M',4),('I',2),('M',5),('D',2),('M',1)]".
  * The extended cigar string would look like this: "[('=',3)('X',1)('I',2)('=',3)('X',1)('=',1)('D',2)('=',1)]".
  *
- * \include test/snippet/io/alignment_file/get_cigar_vector.cpp
+ * \include test/snippet/io/sam_file/get_cigar_vector.cpp
  *
  * \sa seqan3::aligned_sequence
  */

include/seqan3/io/alignment_file/input.hpp

@@ -177,7 +177,7 @@ SEQAN3_CONCEPT alignment_file_input_traits = requires (t v)
  *
  * This example will make the file read into a smaller alphabet and a compressed container:
  *
- * \include test/snippet/io/alignment_file/alignment_file_input_my_traits.cpp
+ * \include test/snippet/io/sam_file/sam_file_input_my_traits.cpp
  */
 template <typename ref_sequences_t = ref_info_not_given, typename ref_ids_t = std::deque<std::string>>
 struct alignment_file_input_default_traits
@@ -252,11 +252,11 @@ struct alignment_file_input_default_traits
  *
  * In most cases the template parameters are deduced automatically:
  *
- * \include test/snippet/io/alignment_file/alignment_file_input_construction_from_filename.cpp
+ * \include test/snippet/io/sam_file/sam_file_input_construction_from_filename.cpp
  *
  * Reading from an std::istringstream:
  *
- * \include test/snippet/io/alignment_file/alignment_file_input_construction_from_stream.cpp
+ * \include test/snippet/io/sam_file/sam_file_input_construction_from_stream.cpp
  *
  * Note that this is not the same as writing `alignment_file_input<>` (with angle brackets). In the latter case they
  * are explicitly set to their default values, in the former case
@@ -269,13 +269,13 @@ struct alignment_file_input_default_traits
  * template parameter yourself means that you loose automatic deduction. The following is equivalent to the automatic
  * type deduction example with a stream from above:
  *
- * \include test/snippet/io/alignment_file/alignment_file_input_construction_without_automatic_type_deduction.cpp
+ * \include test/snippet/io/sam_file/sam_file_input_construction_without_automatic_type_deduction.cpp
  *
  * ### Reading record-wise
  *
  * You can iterate over this file record-wise:
  *
- * \include test/snippet/io/alignment_file/alignment_file_input_reading_range_based_for_loop.cpp
+ * \include test/snippet/io/sam_file/sam_file_input_reading_range_based_for_loop.cpp
  *
  * In the above example, `rec` has the type \ref record_type which is a specialisation of seqan3::record and behaves
  * like an std::tuple (that's why we can access it via `get`). Instead of using the seqan3::field based interface on
@@ -286,7 +286,7 @@ struct alignment_file_input_default_traits
  * 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:
  *
- * \include test/snippet/io/alignment_file/alignment_file_input_reading_move_record.cpp
+ * \include test/snippet/io/sam_file/sam_file_input_reading_move_record.cpp
  *
  * ### Reading record-wise (custom fields)
  *
@@ -295,7 +295,7 @@ struct alignment_file_input_default_traits
  * you may only be interested in the mapping flag and mapping quality of your SAM data to get some statistics.
  * The following snippets demonstrate the usage of such a fields trait object.
  *
- * \include test/snippet/io/alignment_file/alignment_file_input_reading_custom_fields.cpp
+ * \include test/snippet/io/sam_file/sam_file_input_reading_custom_fields.cpp
  *
  * When reading a file, all fields not present in the file (but requested implicitly or via the `selected_field_ids`
  * parameter) are ignored and the respective value in the record stays empty.
@@ -307,7 +307,7 @@ struct alignment_file_input_default_traits
  * to decompose the record into its elements. Considering the example of reading only the flag and mapping quality
  * like before you can also write:
  *
- * \include test/snippet/io/alignment_file/alignment_file_input_reading_structured_bindings.cpp
+ * \include test/snippet/io/sam_file/sam_file_input_reading_structured_bindings.cpp
  *
  * In this case you immediately get the two elements of the tuple: `flag` of \ref flag_type and `mapq` of
  * \ref mapq_type. **But beware: with structured bindings you do need to get the order of elements correctly!**
@@ -317,7 +317,7 @@ struct alignment_file_input_default_traits
  * Since SeqAn files are ranges, you can also create views over files. A useful example is to filter the records
  * based on certain criteria, e.g. minimum length of the sequence field:
  *
- * \include test/snippet/io/alignment_file/alignment_file_input_reading_filter.cpp
+ * \include test/snippet/io/sam_file/sam_file_input_reading_filter.cpp
  *
  * ### End of file
  *
@@ -743,7 +743,7 @@ class alignment_file_input
      *
      * Equals end() if the file is at end.
      *
-     * \include test/snippet/io/alignment_file/alignment_file_input_begin_and_front.cpp
+     * \include test/snippet/io/sam_file/sam_file_input_begin_and_front.cpp
      *
      * ### Complexity
      *
@@ -789,14 +789,14 @@ class alignment_file_input
      * This function returns a reference to the currently buffered record, it is identical to dereferencing begin(),
      * and begin also always points to the current record on single pass input ranges:
      *
-     * \include test/snippet/io/alignment_file/alignment_file_input_begin_and_front.cpp
+     * \include test/snippet/io/sam_file/sam_file_input_begin_and_front.cpp
      *
      * In 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:
      *
-     * \include test/snippet/io/alignment_file/alignment_file_input_front.cpp
+     * \include test/snippet/io/sam_file/sam_file_input_front.cpp
      *
      * ### Complexity
      *
@@ -823,7 +823,7 @@ class alignment_file_input
      *
      * ### Example
      *
-     * \include test/snippet/io/alignment_file/alignment_file_input_get_header.cpp
+     * \include test/snippet/io/sam_file/sam_file_input_get_header.cpp
      *
      * \sa seqan3::alignment_file_header
      */

include/seqan3/io/alignment_file/misc.hpp

@@ -34,7 +34,7 @@ struct ref_info_not_given
  *
  * Example:
  *
- * \include test/snippet/io/alignment_file/sam_flags.cpp
+ * \include test/snippet/io/sam_file/sam_flags.cpp
  *
  * Adapted from the [SAM specifications](https://samtools.github.io/hts-specs/SAMv1.pdf) are the following additional
  * information to some flag values:

include/seqan3/io/alignment_file/output.hpp

@@ -69,11 +69,11 @@ namespace seqan3
  *
  * In most cases the template parameters are deduced completely automatically:
  *
- * \include test/snippet/io/alignment_file/alignment_file_output_filename_construction.cpp
+ * \include test/snippet/io/sam_file/sam_file_output_filename_construction.cpp
  *
  * Writing to std::cout:
  *
- * \include test/snippet/io/alignment_file/alignment_file_output_cout_write.cpp
+ * \include test/snippet/io/sam_file/sam_file_output_cout_write.cpp
  *
  * Note that this is not the same as writing `alignment_file_output<>`
  * (with angle brackets). In the latter case they are explicitly set to their
@@ -85,7 +85,7 @@ namespace seqan3
  *
  * ### Writing record-wise
  *
- * \include test/snippet/io/alignment_file/record_based_writing.cpp
+ * \include test/snippet/io/sam_file/record_based_writing.cpp
  *
  * The easiest way to write to an alignment file is to use the push_back() member functions. These
  * work similarly to how they work on an std::vector.
@@ -105,14 +105,14 @@ namespace seqan3
  *
  * The following snippets demonstrates the usage of such a field_traits object.
  *
- * \include test/snippet/io/alignment_file/record_based_writing2.cpp
+ * \include test/snippet/io/sam_file/record_based_writing2.cpp
  *
  * A different way of passing custom fields to the file is to pass a seqan3::record – instead of a tuple – to
  * push_back(). The seqan3::record clearly indicates which of its elements has which seqan3::field so **the file will
  * use that information instead of the template argument**. This is especially handy when reading from one file and
  * writing to another, because you don't have to configure the output file to match the input file, it will just work:
  *
- * \include test/snippet/io/alignment_file/alignment_file_output_custom_fields.cpp
+ * \include test/snippet/io/sam_file/sam_file_output_custom_fields.cpp
  *
  * This will copy the FLAG and REF_OFFSET value into the new output file. Note that the other SAM columns in the
  * output file will have a default value, so unless you specify to read all SAM columns (see seqan3::format_sam)
@@ -122,18 +122,18 @@ namespace seqan3
  *
  * You can write multiple records at once, by assigning to the file:
  *
- * \include test/snippet/io/alignment_file/alignment_file_output_write_range.cpp
+ * \include test/snippet/io/sam_file/sam_file_output_write_range.cpp
  *
  * ### File I/O pipelines
  *
  * Record-wise writing in batches also works for writing from input files directly to output files, because input
  * files are also input ranges in SeqAn:
  *
- * \include test/snippet/io/alignment_file/alignment_file_output_input_range.cpp
+ * \include test/snippet/io/sam_file/sam_file_output_input_range.cpp
  *
  * This can be combined with file-based views to create I/O pipelines:
  *
- * \include test/snippet/io/alignment_file/alignment_file_output_io_pipeline.cpp
+ * \include test/snippet/io/sam_file/sam_file_output_io_pipeline.cpp
  *
  * ### Formats
  *
@@ -262,11 +262,11 @@ class alignment_file_output
      *
      * In most cases the template parameters are deduced completely automatically:
      *
-     * \include test/snippet/io/alignment_file/alignment_file_output_filename_construction.cpp
+     * \include test/snippet/io/sam_file/sam_file_output_filename_construction.cpp
      *
      * Writing with custom selected fields:
      *
-     * \include test/snippet/io/alignment_file/alignment_file_output_format_construction.cpp
+     * \include test/snippet/io/sam_file/sam_file_output_format_construction.cpp
      */
     alignment_file_output(std::filesystem::path filename,
                           selected_field_ids const & SEQAN3_DOXYGEN_ONLY(fields_tag) = selected_field_ids{}) :
@@ -358,11 +358,11 @@ class alignment_file_output
      *
      * In most cases the template parameters are deduced completely automatically:
      *
-     * \include test/snippet/io/alignment_file/alignment_file_output_filename_construction_with_ref_info.cpp
+     * \include test/snippet/io/sam_file/sam_file_output_filename_construction_with_ref_info.cpp
      *
      * Writing with custom selected fields:
      *
-     * \include test/snippet/io/alignment_file/alignment_file_output_format_construction.cpp
+     * \include test/snippet/io/sam_file/sam_file_output_format_construction.cpp
      */
     template <typename ref_ids_type_, std::ranges::forward_range ref_lengths_type>
     //!\cond
@@ -436,7 +436,7 @@ class alignment_file_output
      *
      * ### Example
      *
-     * \include test/snippet/io/alignment_file/begin_iterator.cpp
+     * \include test/snippet/io/sam_file/begin_iterator.cpp
      */
     iterator begin() noexcept
     {
@@ -478,7 +478,7 @@ class alignment_file_output
      *
      * ### Example
      *
-     * \include test/snippet/io/alignment_file/push_back_record.cpp
+     * \include test/snippet/io/sam_file/push_back_record.cpp
      */
     template <typename record_t>
     void push_back(record_t && r)
@@ -526,7 +526,7 @@ class alignment_file_output
      *
      * ### Example
      *
-     * \include test/snippet/io/alignment_file/push_back_tuple.cpp
+     * \include test/snippet/io/sam_file/push_back_tuple.cpp
      */
     template <typename tuple_t>
     void push_back(tuple_t && t)
@@ -577,7 +577,7 @@ class alignment_file_output
      *
      * ### Example
      *
-     * \include test/snippet/io/alignment_file/emplace_back.cpp
+     * \include test/snippet/io/sam_file/emplace_back.cpp
      */
     template <typename arg_t, typename ...arg_types>
     void emplace_back(arg_t && arg, arg_types && ... args)
@@ -604,7 +604,7 @@ class alignment_file_output
      *
      * ### Example
      *
-     * \include test/snippet/io/alignment_file/alignment_file_output_write_range.cpp
+     * \include test/snippet/io/sam_file/sam_file_output_write_range.cpp
      */
     template <typename rng_t>
     alignment_file_output & operator=(rng_t && range)
@@ -638,11 +638,11 @@ class alignment_file_output
      *
      * ### Example
      *
-     * \include test/snippet/io/alignment_file/alignment_file_output_write_range.cpp
+     * \include test/snippet/io/sam_file/sam_file_output_write_range.cpp
      *
      * This is especially useful in combination with file-based filters:
      *
-     * \include test/snippet/io/alignment_file/alignment_file_output_io_pipeline.cpp
+     * \include test/snippet/io/sam_file/sam_file_output_io_pipeline.cpp
      *
      */
     template <typename rng_t>
@@ -685,7 +685,7 @@ class alignment_file_output
      *
      * ### Example
      *
-     * \include test/snippet/io/alignment_file/alignment_file_output_set_header.cpp
+     * \include test/snippet/io/sam_file/sam_file_output_set_header.cpp
      *
      * \sa seqan3::alignment_file_header
      */

include/seqan3/io/alignment_file/sam_tag_dictionary.hpp

@@ -53,7 +53,7 @@ namespace seqan3
  * which delegate to its unique id.
  * e.g.
  *
- * \snippet test/snippet/io/alignment_file/sam_tag_dictionary/sam_tag_dictionary.cpp tag
+ * \snippet test/snippet/io/sam_file/sam_tag_dictionary/sam_tag_dictionary.cpp tag
  *
  * The purpose of those tags is to fill or query the seqan3::sam_tag_dictionary
  * for a specific key (tag_id) and retrieve the corresponding value.
@@ -100,7 +100,7 @@ constexpr uint16_t operator""_tag()
  * recommend to use X?, Y? or Z?) you need to overload the seqan3::sam_tag_type
  * struct in the following way: (take tag "XX" as an example)
  *
- * \snippet test/snippet/io/alignment_file/sam_tag_dictionary/sam_tag_dictionary.cpp type_overload
+ * \snippet test/snippet/io/sam_file/sam_tag_dictionary/sam_tag_dictionary.cpp type_overload
  *
  * Everything else, like the get and set functions and correct SAM output
  * (XX:i:? in this case) is handled by the seqan3::sam_tag_dictionary.
@@ -255,7 +255,7 @@ template <> struct sam_tag_type<"UQ"_tag> { using type = int32_t; };
  * which delegates to its unique id (type uint16_t).
  * Example:
  *
- * \snippet test/snippet/io/alignment_file/sam_tag_dictionary/sam_tag_dictionary.cpp tag
+ * \snippet test/snippet/io/sam_file/sam_tag_dictionary/sam_tag_dictionary.cpp tag
  *
  * The purpose of those tags is to fill or query the seqan3::sam_tag_dictionary
  * for a specific key (tag_id) and retrieve the corresponding value.
@@ -271,11 +271,11 @@ template <> struct sam_tag_type<"UQ"_tag> { using type = int32_t; };
  * are pre-defined by a type trait called seqan3::sam_tag_type. You can access
  * the type via:
  *
- * \snippet test/snippet/io/alignment_file/sam_tag_dictionary/sam_tag_dictionary.cpp tag_type_t
+ * \snippet test/snippet/io/sam_file/sam_tag_dictionary/sam_tag_dictionary.cpp tag_type_t
  *
  * which is the short cut for:
  *
- * \snippet test/snippet/io/alignment_file/sam_tag_dictionary/sam_tag_dictionary.cpp tag_type
+ * \snippet test/snippet/io/sam_file/sam_tag_dictionary/sam_tag_dictionary.cpp tag_type
  *
  * The following types are allowed by the
  * [SAM specifications](https://samtools.github.io/hts-specs/SAMtags.pdf):
@@ -301,7 +301,7 @@ template <> struct sam_tag_type<"UQ"_tag> { using type = int32_t; };
  *
  * Example:
  *
- * \include test/snippet/io/alignment_file/sam_tag_dictionary/general_usage.cpp
+ * \include test/snippet/io/sam_file/sam_tag_dictionary/general_usage.cpp
  *
  * \attention You can get any SAM_tag out of the dictionary, even if the tag is
  *            user defined, but note that for unknown tags the return type is an
@@ -311,7 +311,7 @@ template <> struct sam_tag_type<"UQ"_tag> { using type = int32_t; };
  *
  * Unknown Tag Example:
  *
- * \include test/snippet/io/alignment_file/sam_tag_dictionary/unknown_tag.cpp
+ * \include test/snippet/io/sam_file/sam_tag_dictionary/unknown_tag.cpp
  *
  * As mentioned before you can either overload the type trait seqan3::sam_tag_type
  * for the tag "XZ" or learn more about an std::variant at