SeqAn3 3.4.0-rc.1
The Modern C++ library for sequence analysis.
Loading...
Searching...
No Matches
Classes | Variables
Views
IO

IO related views. More...

+ Collaboration diagram for Views:

Classes

class  seqan3::detail::async_input_buffer_view< urng_t >
 The type returned by seqan3::views::async_input_buffer. More...
 
struct  seqan3::detail::istreambuf_fn
 View adaptor/factory definition for views::istream. More...
 
class  seqan3::detail::view_take_exactly< urng_t, or_throw >
 The type returned by seqan3::views::take, seqan3::detail::take_exactly and seqan3::detail::take_exactly_or_throw. More...
 
class  seqan3::detail::view_take_until< urng_t, fun_t, or_throw, and_consume >
 The type returned by seqan3::detail::take_until and seqan3::detail::take_until_or_throw. More...
 

Variables

constexpr auto seqan3::views::async_input_buffer
 A view adapter that returns a concurrent-queue-like view over the underlying range.
 
constexpr auto seqan3::detail::istreambuf
 A view factory that returns a view over the stream buffer of an input stream.
 
constexpr auto seqan3::detail::take_exactly
 A view adaptor that returns the first size elements from the underlying range (or less if the underlying range is shorter); also provides size information.
 
constexpr auto seqan3::detail::take_exactly_or_throw
 A view adaptor that returns the first size elements from the underlying range and also exposes size information; throws if the underlying range is smaller than size.
 
constexpr auto seqan3::detail::take_line = detail::take_until_and_consume(is_char<'\r'> || is_char<'\n'>)
 A view adaptor that returns a single line from the underlying range or the full range if there is no newline.
 
constexpr auto seqan3::detail::take_line_or_throw = detail::take_until_or_throw_and_consume(is_char<'\r'> || is_char<'\n'>)
 A view adaptor that returns a single line from the underlying range (throws if there is no end-of-line).
 
constexpr auto seqan3::detail::take_until
 A view adaptor that returns elements from the underlying range until the functor evaluates to true (or the end of the underlying range is reached).
 
constexpr auto seqan3::detail::take_until_and_consume
 A view adaptor that returns elements from the underlying range until the functor evaluates to true (or the end of the underlying range is reached and consumes the end in single-pass ranges).
 
constexpr auto seqan3::detail::take_until_or_throw
 A view adaptor that returns elements from the underlying range until the functor evaluates to true (throws if the end of the underlying range is reached).
 
constexpr auto seqan3::detail::take_until_or_throw_and_consume
 A view adaptor that returns elements from the underlying range until the functor evaluates to true (throws if the end of the underlying range is reached and consumes the end in single-pass ranges).
 

Detailed Description

IO related views.

See also
IO

Variable Documentation

◆ async_input_buffer

constexpr auto seqan3::views::async_input_buffer
inlineconstexpr

A view adapter that returns a concurrent-queue-like view over the underlying range.

Template Parameters
urng_tThe type of the range being processed. See below for requirements.
Parameters
[in,out]urangeThe range being processed.
[in]buffer_sizeSize of the buffer. Choose the size (> 0) depending on the expected work per element.
Returns
A view that pre-fetches elements from the underlying range and provides a thread-safe interface. See below for the properties of the returned range.

Header File

#include <seqan3/io/views/async_input_buffer.hpp>

Summary

This view spawns a background thread that pre-fetches elements from the underlying range and stores them in a concurrent queue. Iterating over this view then pops elements out of the queue and returns them. This is primarily useful if dereferencing/incrementing the iterator of the underlying range is expensive, e.g. with SeqAn files which lazily perform I/O.

Another advantage of this view is that multiple iterators can be created that are safe to iterate individually, even from different threads, i.e. you can use multiple threads to iterate safely over a single-pass input view with the added benefit of background pre-fetching.

In technical terms: this view facilitates a single-producer, multi-consumer design; it's a range interface over a concurrent queue.

Size of the buffer

The buffer_size parameter should be chosen depending on the expected work per element, e.g. if the underlying range is an input file over short reads, a buffer size of 100 or 1000 could be beneficial; if on the other hand the file contains genome-sized sequences, it would be better to buffer only a single sequence (buffering 100 sequences would result in the entire file being preloaded and likely consuming significant memory).

Range consumption

This view always moves elements from the underlying range into its buffer which means that the elements in the underlying range will be invalidated! For underlying ranges that are single-pass, this makes no difference, but it might be unexpected for multi-pass ranges (std::ranges::forward_range).

Typically this adaptor is used when you want to consume the entire underlying range. Destructing this view before all elements have been read will also stop the thread that moves object from the underlying range. In general, it is not safe to access the underlying range in other contexts once it has been passed to seqan3::views::async_input_buffer.

Note that in addition to the buffer of the view, every iterator has its own one-element-buffer. Dereferencing the iterator returns a reference to the element in the buffer, usually you will want to move this element out of the buffer with std::move std::ranges::iter_move. Incrementing the iterator refills the buffer from the queue inside the view (which in turn is then refilled from the underlying range).

View properties

concepts and reference type urng_t (underlying range type) rrng_t (returned range type)
std::ranges::input_range required preserved
std::ranges::forward_range lost
std::ranges::bidirectional_range lost
std::ranges::random_access_range lost
std::ranges::contiguous_range lost
std::ranges::viewable_range required guaranteed
std::ranges::view guaranteed
std::ranges::sized_range lost
std::ranges::common_range lost
std::ranges::output_range lost
seqan3::const_iterable_range lost
std::ranges::range_reference_t std::ranges::range_value_t<urng_t> &
std::iterator_traits ::iterator_category none

See the views submodule documentation for detailed descriptions of the view properties.

Thread safety

The following operations are thread-safe:

  • calling .begin() and .end() on the view returned by this adaptor;
  • calling operators on the different iterator objects.

Calling operators on the same iterator object from different threads is not safe, i.e. you can pass the view to different threads by reference, and have each of those threads call begin() on the view and then perform operations (dereference, increment...) on that iterator from the respective thread; but you cannot call begin() in a parent thread, pass the iterator to different threads and operate on that concurrently.

Example

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <cstdlib> // std::rand
#include <future> // std::async
#include <string> // std::string
#include <seqan3/core/debug_stream.hpp> // seqan3::debug_stream
#include <seqan3/io/sequence_file/input.hpp> // seqan3::sequence_file_input
#include <seqan3/io/views/async_input_buffer.hpp> // seqan3::views::async_input_buffer
std::string fasta_file =
R"(> seq1
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq2
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq3
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq4
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq5
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq6
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq7
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq8
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq9
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq10
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq11
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq12
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
)";
int main()
{
// initialise random number generator, only needed for demonstration purposes
std::srand(std::time(nullptr));
// create an input file from the string above
seqan3::sequence_file_input fin{std::istringstream{fasta_file}, seqan3::format_fasta{}};
// create the async buffer around the input file
// spawns a background thread that tries to keep four records in the buffer
auto v = fin | seqan3::views::async_input_buffer(4);
// create a lambda function that iterates over the async buffer when called
// (the buffer gets dynamically refilled as soon as possible)
auto worker = [&v]()
{
for (auto & record : v)
{
// pretend we are doing some work
std::this_thread::sleep_for(std::chrono::milliseconds(std::rand() % 1000));
// print current thread and sequence ID
seqan3::debug_stream << "Thread: " << std::this_thread::get_id() << '\t' << "Seq: " << record.id()
<< '\n';
}
};
// launch two threads and pass the lambda function to both
auto f0 = std::async(std::launch::async, worker);
auto f1 = std::async(std::launch::async, worker);
}
async_input_buffer.hpp
Provides seqan3::views::async_input_buffer.
std::async
T async(T... args)
seqan3::format_fasta
The FASTA format.
Definition format_fasta.hpp:77
seqan3::sequence_file_input
A class for reading sequence files, e.g. FASTA, FASTQ ...
Definition sequence_file/input.hpp:207
debug_stream.hpp
Provides seqan3::debug_stream and related types.
std::this_thread::get_id
T get_id(T... args)
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:37
seqan3::views::async_input_buffer
constexpr auto async_input_buffer
A view adapter that returns a concurrent-queue-like view over the underlying range.
Definition async_input_buffer.hpp:478
std::rand
T rand(T... args)
input.hpp
Provides seqan3::sequence_file_input and corresponding traits classes.
std::this_thread::sleep_for
T sleep_for(T... args)
std::srand
T srand(T... args)
std::time
T time(T... args)

Running the snippet could yield the following output:

Thread: 0x80116bf00 Seq: seq2
Thread: 0x80116bf00 Seq: seq3
Thread: 0x80116ba00 Seq: seq1
Thread: 0x80116bf00 Seq: seq4
Thread: 0x80116bf00 Seq: seq6
Thread: 0x80116ba00 Seq: seq5
Thread: 0x80116bf00 Seq: seq7
Thread: 0x80116ba00 Seq: seq8
Thread: 0x80116bf00 Seq: seq9
Thread: 0x80116bf00 Seq: seq11
Thread: 0x80116bf00 Seq: seq12
Thread: 0x80116ba00 Seq: seq10

This shows that indeed elements from the underlying range are processed non-sequentially, that there are two threads and that work is "balanced" between them (one thread processed more element than the other, because its "work" per item happened to be smaller).

Note that you might encounter jumbled output if by chance two threads write to the stream at the exact same time.

If you remove the line starting with auto f1 = ... you will get sequential processing:

Thread: 0x80116aa00 Seq: seq1
Thread: 0x80116aa00 Seq: seq2
Thread: 0x80116aa00 Seq: seq3
Thread: 0x80116aa00 Seq: seq4
Thread: 0x80116aa00 Seq: seq5
Thread: 0x80116aa00 Seq: seq6
Thread: 0x80116aa00 Seq: seq7
Thread: 0x80116aa00 Seq: seq8
Thread: 0x80116aa00 Seq: seq9
Thread: 0x80116aa00 Seq: seq10
Thread: 0x80116aa00 Seq: seq11
Thread: 0x80116aa00 Seq: seq12

Note that even if you have a single processing thread, using this view can still improve performance measurably, because loading of the elements into the buffer (which reads input from disk) happens in a background thread.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

◆ istreambuf

constexpr auto seqan3::detail::istreambuf
inlineconstexpr

A view factory that returns a view over the stream buffer of an input stream.

Template Parameters
istreambuf_tThe type of the stream(buffer); must be std::basic_streambuf or model seqan3::input_stream.
Parameters
[in]istreambufThe stream buffer or an input stream of whom the buffer is retrieved.
Returns

Header File

#include <seqan3/io/views/detail/istreambuf_view.hpp>

View properties

This is a source-only view adaptor, also known as a range factory; you cannot pipe anything into it.

Concepts and traits rrng_t (returned range type)
std::ranges::input_range guaranteed
std::ranges::forward_range
std::ranges::bidirectional_range
std::ranges::random_access_range
std::ranges::contiguous_range
std::ranges::viewable_range guaranteed
std::ranges::view guaranteed
std::ranges::sized_range
std::ranges::common_range
std::ranges::output_range
seqan3::const_iterable_range guaranteed
std::ranges::range_reference_t istream_t::char_type

See the views submodule documentation for detailed descriptions of the view properties.

This adaptor is different from std::ranges::basic_istream_view in that it operates directly on the buffer. It further uses a custom streambuf_iterator (not std::istreambuf_iterator) that performs less virtual function calls.

◆ take_exactly

constexpr auto seqan3::detail::take_exactly
inlineconstexpr

A view adaptor that returns the first size elements from the underlying range (or less if the underlying range is shorter); also provides size information.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]sizeThe target size of the view.
Returns
Up to size elements of the underlying range.

Header File

#include <seqan3/io/views/detail/take_exactly_view.hpp>

View properties

Concepts and traits urng_t (underlying range type) rrng_t (returned range type)
std::ranges::input_range required preserved
std::ranges::forward_range preserved
std::ranges::bidirectional_range preserved
std::ranges::random_access_range preserved
std::ranges::contiguous_range preserved
std::ranges::viewable_range required guaranteed
std::ranges::view guaranteed
std::ranges::sized_range guaranteed
std::ranges::common_range preserved
std::ranges::output_range preserved except if urng_t is std::basic_string
seqan3::const_iterable_range preserved
std::ranges::range_reference_t std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

The difference to seqan3::views::take is that this view always exposes size information – even if the underlying range is not sized. You should only use this if you know that the underlying range will always be at least size long.

For seqan3::detail::take_exactly if the underlying range is shorter than size, the behaviour is undefined. seqan3::detail::take_exactly_or_throw is a safer alternative, because it throws an exception when an iterator before the size-th one compares equal to the end sentinel; and it also throws on construction if it knows that the underlying range is smaller.

Example

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/io/views/detail/take_exactly_view.hpp>
int main()
{
std::string vec{"foobar"};
auto v = vec | seqan3::detail::take_exactly(3); // or seqan3::detail::take_exactly_or_throw
seqan3::debug_stream << v << '\n'; // "foo"
seqan3::debug_stream << std::ranges::size(v) << '\n'; // 3
auto v2 = vec | seqan3::detail::take_exactly(9);
seqan3::debug_stream << std::ranges::size(v2) << '\n'; // 9 <- here be dragons! (undefined behaviour)
}
seqan3::detail::take_exactly
constexpr auto take_exactly
A view adaptor that returns the first size elements from the underlying range (or less if the underly...
Definition take_exactly_view.hpp:573
take_exactly_view.hpp
Provides seqan3::views::take_exactly and seqan3::views::take_exactly_or_throw.

◆ take_exactly_or_throw

constexpr auto seqan3::detail::take_exactly_or_throw
inlineconstexpr

A view adaptor that returns the first size elements from the underlying range and also exposes size information; throws if the underlying range is smaller than size.

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range is smaller than size.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]sizeThe target size of the view.
Returns
Up to size elements of the underlying range.

Header File

#include <seqan3/io/views/detail/take_exactly_view.hpp>

View properties

Concepts and traits urng_t (underlying range type) rrng_t (returned range type)
std::ranges::input_range required preserved
std::ranges::forward_range preserved
std::ranges::bidirectional_range preserved
std::ranges::random_access_range preserved
std::ranges::contiguous_range preserved
std::ranges::viewable_range required guaranteed
std::ranges::view guaranteed
std::ranges::sized_range guaranteed
std::ranges::common_range preserved
std::ranges::output_range preserved except if urng_t is std::basic_string
seqan3::const_iterable_range preserved
std::ranges::range_reference_t std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

The difference to seqan3::views::take is that this view always exposes size information – even if the underlying range is not sized. You should only use this if you know that the underlying range will always be at least size long.

For seqan3::detail::take_exactly if the underlying range is shorter than size, the behaviour is undefined. seqan3::detail::take_exactly_or_throw is a safer alternative, because it throws an exception when an iterator before the size-th one compares equal to the end sentinel; and it also throws on construction if it knows that the underlying range is smaller.

Example

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/io/views/detail/take_exactly_view.hpp>
int main()
{
std::string vec{"foobar"};
auto v = vec | seqan3::detail::take_exactly(3); // or seqan3::detail::take_exactly_or_throw
seqan3::debug_stream << v << '\n'; // "foo"
seqan3::debug_stream << std::ranges::size(v) << '\n'; // 3
auto v2 = vec | seqan3::detail::take_exactly(9);
seqan3::debug_stream << std::ranges::size(v2) << '\n'; // 9 <- here be dragons! (undefined behaviour)
}

◆ take_line

constexpr auto seqan3::detail::take_line = detail::take_until_and_consume(is_char<'\r'> || is_char<'\n'>)
inlineconstexpr

A view adaptor that returns a single line from the underlying range or the full range if there is no newline.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
All characters of the underlying range up until, but excluding a unix or windows end-line (\n or \r\n). See below for the properties of the returned range.

Header File

#include <seqan3/io/views/detail/take_line_view.hpp>

This adaptor returns a single line excluding the end-line character(s), but moving the cursor behind them for single-pass ranges. I.e. for all ranges that satisfy std::ranges::forward_range this is the same as calling std::views::take_while:

auto v = std::views::take_while(
[](auto const & l)
{
return (l != '\r') && (l != '\n');
});

but for single pass input ranges this means that any endline characters after the returned range are also consumed (this potentially includes multiple newline characters).

View properties

Concepts and traits urng_t (underlying range type) rrng_t (returned range type)
std::ranges::input_range required preserved
std::ranges::forward_range preserved
std::ranges::bidirectional_range preserved
std::ranges::random_access_range preserved
std::ranges::contiguous_range preserved
std::ranges::viewable_range required guaranteed
std::ranges::view guaranteed
std::ranges::sized_range lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range preserved
std::ranges::range_reference_t std::common_reference_with<char> std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

Example

Behaviour on std::ranges::forward_range:

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/io/views/detail/take_line_view.hpp>
int main()
{
std::string vec{"foo\nbar"};
auto v = vec | seqan3::detail::take_line;
seqan3::debug_stream << v << '\n'; // [f,o,o]
auto v2 = vec | std::views::reverse | seqan3::detail::take_line;
seqan3::debug_stream << v2 << '\n'; // [r,a,b]
seqan3::debug_stream << v2 << '\n'; // [r,a,b] (parsing it again gives us the same result)
}
seqan3::detail::take_line
constexpr auto take_line
A view adaptor that returns a single line from the underlying range or the full range if there is no ...
Definition take_line_view.hpp:70
take_line_view.hpp
Provides seqan3::detail::take_line and seqan3::detail::take_line_or_throw.

On single pass std::ranges::input_range it can be used to tokenise the input stream line-wise:

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/io/views/detail/take_line_view.hpp>
#include <seqan3/utility/views/single_pass_input.hpp>
int main()
{
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::single_pass_input | seqan3::detail::take_line;
seqan3::debug_stream << v << '\n'; // [f,o,o]
seqan3::debug_stream << v << '\n'; // [b,a,r] (parsing it again gives us the next line)
}
seqan3::views::single_pass_input
constexpr auto single_pass_input
A view adapter that decays most of the range properties and adds single pass behavior.
Definition single_pass_input.hpp:345
single_pass_input.hpp
Provides seqan3::views::single_pass_input.

◆ take_line_or_throw

constexpr auto seqan3::detail::take_line_or_throw = detail::take_until_or_throw_and_consume(is_char<'\r'> || is_char<'\n'>)
inlineconstexpr

A view adaptor that returns a single line from the underlying range (throws if there is no end-of-line).

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range contains no end-of-line marker.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
All characters of the underlying range up until, but excluding a unix or windows end-line (\n or \r\n). See below for the properties of the returned range.

Header File

#include <seqan3/io/views/detail/take_line_view.hpp>

This adaptor returns a single line excluding the end-line character(s), but moving the cursor behind them for single-pass ranges. I.e. for all ranges that satisfy std::ranges::forward_range this is the same as calling std::views::take_while:

auto v = std::views::take_while(
[](auto const & l)
{
return (l != '\r') && (l != '\n');
});

but for single pass input ranges this means that any endline characters after the returned range are also consumed (this potentially includes multiple newline characters).

View properties

Concepts and traits urng_t (underlying range type) rrng_t (returned range type)
std::ranges::input_range required preserved
std::ranges::forward_range preserved
std::ranges::bidirectional_range preserved
std::ranges::random_access_range preserved
std::ranges::contiguous_range preserved
std::ranges::viewable_range required guaranteed
std::ranges::view guaranteed
std::ranges::sized_range lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range preserved
std::ranges::range_reference_t std::common_reference_with<char> std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

Example

Behaviour on std::ranges::forward_range:

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/io/views/detail/take_line_view.hpp>
int main()
{
std::string vec{"foo\nbar"};
auto v = vec | seqan3::detail::take_line;
seqan3::debug_stream << v << '\n'; // [f,o,o]
auto v2 = vec | std::views::reverse | seqan3::detail::take_line;
seqan3::debug_stream << v2 << '\n'; // [r,a,b]
seqan3::debug_stream << v2 << '\n'; // [r,a,b] (parsing it again gives us the same result)
}

On single pass std::ranges::input_range it can be used to tokenise the input stream line-wise:

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/io/views/detail/take_line_view.hpp>
#include <seqan3/utility/views/single_pass_input.hpp>
int main()
{
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::single_pass_input | seqan3::detail::take_line;
seqan3::debug_stream << v << '\n'; // [f,o,o]
seqan3::debug_stream << v << '\n'; // [b,a,r] (parsing it again gives us the next line)
}

◆ take_until

constexpr auto seqan3::detail::take_until
inlineconstexpr

A view adaptor that returns elements from the underlying range until the functor evaluates to true (or the end of the underlying range is reached).

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_tThe type of the functor; must model std::invocable with std::ranges::range_reference_t<urng_t> and return a type convertible to bool.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]funThe functor.
Returns
All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header File

#include <seqan3/io/views/detail/take_until_view.hpp>

View properties

Concepts and traits urng_t (underlying range type) rrng_t (returned range type)
std::ranges::input_range required preserved
std::ranges::forward_range preserved¹
std::ranges::bidirectional_range preserved¹
std::ranges::random_access_range preserved¹
std::ranges::contiguous_range preserved¹
std::ranges::viewable_range required guaranteed
std::ranges::view guaranteed
std::ranges::sized_range lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range preserved¹
std::ranges::range_reference_t std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

¹ The marked properties are only preserved if the specified functor models std::regular_invocable<fun_t, std::ranges::range_reference_t<urng_t>, i.e. applying the functor doesn't change the functor. If the functor only models std::invocable and not std::regular_invocable these concepts are lost.

Throwing: seqan3::detail::take_until_or_throw and seqan3::detail::take_until_or_throw_and_consume throw an exception if the end of the underlying range is reached before their own termination criterium is met. This is useful if you want a "strict" evaluation of the functor.

Consuming: seqan3::detail::take_until_and_consume and seqan3::detail::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::ranges::forward_range. If, however, the underlying range is a pure std::ranges::input_range, the view will keep moving the underlying iterator forward as long as the termination criterium holds and the underlying range is not at end. This is useful for string tokenisation among other things.

Example

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges> // for std::views::reverse
#include <string>
#include <seqan3/core/debug_stream.hpp> // for debug_stream
#include <seqan3/io/views/detail/take_until_view.hpp> // for detail::take_until*
#include <seqan3/utility/char_operations/predicate.hpp> // for is_char
#include <seqan3/utility/views/single_pass_input.hpp> // for views::single_pass_input
int main()
{
// regular usage
std::string vec{"foo\nbar"};
auto v = vec | seqan3::detail::take_until(seqan3::is_char<'\n'>); // or use a lambda
seqan3::debug_stream << v << '\n'; // "foo"
auto v2 = vec | std::views::reverse | seqan3::detail::take_until(seqan3::is_char<'\n'>);
seqan3::debug_stream << v2 << '\n'; // "rab"
// consuming behaviour
std::string vec2{"foo bar"}; // ← multiple spaces
auto vin = vec2 | seqan3::views::single_pass_input;
auto v3 = vin | seqan3::detail::take_until_and_consume(seqan3::is_blank);
seqan3::debug_stream << v3 << '\n'; // "foo"
seqan3::debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}
std::ranges::begin
T begin(T... args)
seqan3::detail::take_until
constexpr auto take_until
A view adaptor that returns elements from the underlying range until the functor evaluates to true (o...
Definition take_until_view.hpp:557
seqan3::detail::take_until_and_consume
constexpr auto take_until_and_consume
A view adaptor that returns elements from the underlying range until the functor evaluates to true (o...
Definition take_until_view.hpp:585
seqan3::is_blank
constexpr auto is_blank
Checks whether c is a blank character.
Definition predicate.hpp:139
seqan3::is_char
constexpr auto is_char
Checks whether a given letter is the same as the template non-type argument.
Definition predicate.hpp:60
predicate.hpp
Provides character predicates for tokenisation.
take_until_view.hpp
Provides seqan3::views::take_until and seqan3::views::take_until_or_throw.

◆ take_until_and_consume

constexpr auto seqan3::detail::take_until_and_consume
inlineconstexpr

A view adaptor that returns elements from the underlying range until the functor evaluates to true (or the end of the underlying range is reached and consumes the end in single-pass ranges).

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range contains no element that satisfies the functor.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_tThe type of the functor; must model std::invocable with std::ranges::range_reference_t<urng_t> and return a type convertible to bool.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]funThe functor.
Returns
All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header File

#include <seqan3/io/views/detail/take_until_view.hpp>

View properties

Concepts and traits urng_t (underlying range type) rrng_t (returned range type)
std::ranges::input_range required preserved
std::ranges::forward_range preserved¹
std::ranges::bidirectional_range preserved¹
std::ranges::random_access_range preserved¹
std::ranges::contiguous_range preserved¹
std::ranges::viewable_range required guaranteed
std::ranges::view guaranteed
std::ranges::sized_range lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range preserved¹
std::ranges::range_reference_t std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

¹ The marked properties are only preserved if the specified functor models std::regular_invocable<fun_t, std::ranges::range_reference_t<urng_t>, i.e. applying the functor doesn't change the functor. If the functor only models std::invocable and not std::regular_invocable these concepts are lost.

Throwing: seqan3::detail::take_until_or_throw and seqan3::detail::take_until_or_throw_and_consume throw an exception if the end of the underlying range is reached before their own termination criterium is met. This is useful if you want a "strict" evaluation of the functor.

Consuming: seqan3::detail::take_until_and_consume and seqan3::detail::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::ranges::forward_range. If, however, the underlying range is a pure std::ranges::input_range, the view will keep moving the underlying iterator forward as long as the termination criterium holds and the underlying range is not at end. This is useful for string tokenisation among other things.

Example

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges> // for std::views::reverse
#include <string>
#include <seqan3/core/debug_stream.hpp> // for debug_stream
#include <seqan3/io/views/detail/take_until_view.hpp> // for detail::take_until*
#include <seqan3/utility/char_operations/predicate.hpp> // for is_char
#include <seqan3/utility/views/single_pass_input.hpp> // for views::single_pass_input
int main()
{
// regular usage
std::string vec{"foo\nbar"};
auto v = vec | seqan3::detail::take_until(seqan3::is_char<'\n'>); // or use a lambda
seqan3::debug_stream << v << '\n'; // "foo"
auto v2 = vec | std::views::reverse | seqan3::detail::take_until(seqan3::is_char<'\n'>);
seqan3::debug_stream << v2 << '\n'; // "rab"
// consuming behaviour
std::string vec2{"foo bar"}; // ← multiple spaces
auto vin = vec2 | seqan3::views::single_pass_input;
auto v3 = vin | seqan3::detail::take_until_and_consume(seqan3::is_blank);
seqan3::debug_stream << v3 << '\n'; // "foo"
seqan3::debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

◆ take_until_or_throw

constexpr auto seqan3::detail::take_until_or_throw
inlineconstexpr

A view adaptor that returns elements from the underlying range until the functor evaluates to true (throws if the end of the underlying range is reached).

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range contains no element that satisfies the functor.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_tThe type of the functor; must model std::invocable with std::ranges::range_reference_t<urng_t> and return a type convertible to bool.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]funThe functor.
Returns
All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header File

#include <seqan3/io/views/detail/take_until_view.hpp>

View properties

Concepts and traits urng_t (underlying range type) rrng_t (returned range type)
std::ranges::input_range required preserved
std::ranges::forward_range preserved¹
std::ranges::bidirectional_range preserved¹
std::ranges::random_access_range preserved¹
std::ranges::contiguous_range preserved¹
std::ranges::viewable_range required guaranteed
std::ranges::view guaranteed
std::ranges::sized_range lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range preserved¹
std::ranges::range_reference_t std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

¹ The marked properties are only preserved if the specified functor models std::regular_invocable<fun_t, std::ranges::range_reference_t<urng_t>, i.e. applying the functor doesn't change the functor. If the functor only models std::invocable and not std::regular_invocable these concepts are lost.

Throwing: seqan3::detail::take_until_or_throw and seqan3::detail::take_until_or_throw_and_consume throw an exception if the end of the underlying range is reached before their own termination criterium is met. This is useful if you want a "strict" evaluation of the functor.

Consuming: seqan3::detail::take_until_and_consume and seqan3::detail::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::ranges::forward_range. If, however, the underlying range is a pure std::ranges::input_range, the view will keep moving the underlying iterator forward as long as the termination criterium holds and the underlying range is not at end. This is useful for string tokenisation among other things.

Example

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges> // for std::views::reverse
#include <string>
#include <seqan3/core/debug_stream.hpp> // for debug_stream
#include <seqan3/io/views/detail/take_until_view.hpp> // for detail::take_until*
#include <seqan3/utility/char_operations/predicate.hpp> // for is_char
#include <seqan3/utility/views/single_pass_input.hpp> // for views::single_pass_input
int main()
{
// regular usage
std::string vec{"foo\nbar"};
auto v = vec | seqan3::detail::take_until(seqan3::is_char<'\n'>); // or use a lambda
seqan3::debug_stream << v << '\n'; // "foo"
auto v2 = vec | std::views::reverse | seqan3::detail::take_until(seqan3::is_char<'\n'>);
seqan3::debug_stream << v2 << '\n'; // "rab"
// consuming behaviour
std::string vec2{"foo bar"}; // ← multiple spaces
auto vin = vec2 | seqan3::views::single_pass_input;
auto v3 = vin | seqan3::detail::take_until_and_consume(seqan3::is_blank);
seqan3::debug_stream << v3 << '\n'; // "foo"
seqan3::debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

◆ take_until_or_throw_and_consume

constexpr auto seqan3::detail::take_until_or_throw_and_consume
inlineconstexpr

A view adaptor that returns elements from the underlying range until the functor evaluates to true (throws if the end of the underlying range is reached and consumes the end in single-pass ranges).

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range contains no element that satisfies the functor.
seqan3::unexpected_end_of_inputIf the underlying range contains no element that satisfies the functor.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_tThe type of the functor; must model std::invocable with std::ranges::range_reference_t<urng_t> and return a type convertible to bool.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]funThe functor.
Returns
All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header File

#include <seqan3/io/views/detail/take_until_view.hpp>

View properties

Concepts and traits urng_t (underlying range type) rrng_t (returned range type)
std::ranges::input_range required preserved
std::ranges::forward_range preserved¹
std::ranges::bidirectional_range preserved¹
std::ranges::random_access_range preserved¹
std::ranges::contiguous_range preserved¹
std::ranges::viewable_range required guaranteed
std::ranges::view guaranteed
std::ranges::sized_range lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range preserved¹
std::ranges::range_reference_t std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

¹ The marked properties are only preserved if the specified functor models std::regular_invocable<fun_t, std::ranges::range_reference_t<urng_t>, i.e. applying the functor doesn't change the functor. If the functor only models std::invocable and not std::regular_invocable these concepts are lost.

Throwing: seqan3::detail::take_until_or_throw and seqan3::detail::take_until_or_throw_and_consume throw an exception if the end of the underlying range is reached before their own termination criterium is met. This is useful if you want a "strict" evaluation of the functor.

Consuming: seqan3::detail::take_until_and_consume and seqan3::detail::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::ranges::forward_range. If, however, the underlying range is a pure std::ranges::input_range, the view will keep moving the underlying iterator forward as long as the termination criterium holds and the underlying range is not at end. This is useful for string tokenisation among other things.

Example

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges> // for std::views::reverse
#include <string>
#include <seqan3/core/debug_stream.hpp> // for debug_stream
#include <seqan3/io/views/detail/take_until_view.hpp> // for detail::take_until*
#include <seqan3/utility/char_operations/predicate.hpp> // for is_char
#include <seqan3/utility/views/single_pass_input.hpp> // for views::single_pass_input
int main()
{
// regular usage
std::string vec{"foo\nbar"};
auto v = vec | seqan3::detail::take_until(seqan3::is_char<'\n'>); // or use a lambda
seqan3::debug_stream << v << '\n'; // "foo"
auto v2 = vec | std::views::reverse | seqan3::detail::take_until(seqan3::is_char<'\n'>);
seqan3::debug_stream << v2 << '\n'; // "rab"
// consuming behaviour
std::string vec2{"foo bar"}; // ← multiple spaces
auto vin = vec2 | seqan3::views::single_pass_input;
auto v3 = vin | seqan3::detail::take_until_and_consume(seqan3::is_blank);
seqan3::debug_stream << v3 << '\n'; // "foo"
seqan3::debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}
Hide me