SeqAn3
seqan3::bi_fm_index_iterator< index_t > Class Template Reference

The SeqAn Bidirectional FM Index Iterator. More...

#include <seqan3/search/fm_index/bi_fm_index_iterator.hpp>

Inheritance diagram for seqan3::bi_fm_index_iterator< index_t >:
[legend]

Public Types

using index_type = index_t
 Type of the index.
 
Text types
using size_type = typename index_type::size_type
 Type for representing positions in the indexed text.
 
Iterator types
using fwd_iterator = fm_index_iterator< fm_index< typename index_type::text_type, typename index_type::index_traits::fm_index_traits > >
 Type for the unidirectional iterator on the original text.
 
using rev_iterator = fm_index_iterator< fm_index< typename index_type::rev_text_type, typename index_type::index_traits::fm_index_traits > >
 Type for the unidirectional iterator on the reversed text.
 

Public Member Functions

size_type count () const noexcept
 Counts the number of occurrences of the searched query in the text. More...
 
bool cycle_back () noexcept
 Tries to replace the rightmost character of the query by the next lexicographically larger character such that the query is found in the text. More...
 
bool cycle_front () noexcept
 Tries to replace the leftmost character of the query by the next lexicographically larger character such that the query is found in the text. More...
 
bool extend_left () noexcept
 Tries to extend the query by the smallest possible character to the left such that the query is found in the text. More...
 
template<alphabet_concept char_t>
bool extend_left (char_t const c) noexcept
 Tries to extend the query by the character c to the left. More...
 
template<std::ranges::RandomAccessRange seq_t>
bool extend_left (seq_t &&seq) noexcept
 Tries to extend the query by seq to the left. More...
 
bool extend_right () noexcept
 Tries to extend the query by the smallest possible character to the right such that the query is found in the text. More...
 
template<alphabet_concept char_t>
bool extend_right (char_t const c) noexcept
 Tries to extend the query by the character c to the right. More...
 
template<std::ranges::RandomAccessRange seq_t>
bool extend_right (seq_t &&seq) noexcept
 Tries to extend the query by seq to the right. More...
 
index_t::char_type last_char () noexcept
 Outputs the rightmost respectively leftmost character depending on whether extend_right() or extend_left() has been called last. More...
 
auto lazy_locate () const
 Locates the occurrences of the searched query in the text on demand, i.e. a ranges::view is returned and every position is located once it is accessed. More...
 
std::vector< size_typelocate () const
 Locates the occurrences of the searched query in the text. More...
 
bool operator!= (bi_fm_index_iterator const &rhs) const noexcept
 Compares two iterators. More...
 
auto operator* () const noexcept
 Returns the searched query. More...
 
bool operator== (bi_fm_index_iterator const &rhs) const noexcept
 Compares two iterators. More...
 
auto query () const noexcept
 Returns the searched query. More...
 
size_type query_length () const noexcept
 Returns the depth of the iterator node in the implicit suffix tree, i.e. the length of the sequence searched. More...
 
fwd_iterator to_fwd_iterator () const noexcept
 Returns a unidirectional seqan3::fm_index_iterator on the original text. query() on the returned unidirectional index iterator will be equal to query() on the bidirectional index iterator. cycle_back() and last_char() will be undefined behavior if the last extension on the bidirectional FM index has been to the left. The behavior will be well-defined after the first extension to the right on the unidirectional index. More...
 
rev_iterator to_rev_iterator () const noexcept
 Returns a unidirectional seqan3::fm_index_iterator on the reversed text. query() on the returned unidirectional index iterator will be equal to reversing query() on the bidirectional index iterator. Note that because of the text being reversed, extend_right() resp. cycle_back() correspond to extend_left() resp. cycle_front() on the bidirectional index iterator. Furthermore cycle_back() and last_char() will be undefined behavior if the last extension on the bidirectional FM index has been to the left. The behavior will be well-defined after the first extension to the right on the unidirectional index. More...
 
Constructors, destructor and assignment
 bi_fm_index_iterator () noexcept=default
 Default constructor. Accessing member functions on a default constructed object is undefined behavior.
 
 bi_fm_index_iterator (bi_fm_index_iterator const &) noexcept=default
 
bi_fm_index_iteratoroperator= (bi_fm_index_iterator const &) noexcept=default
 
 bi_fm_index_iterator (bi_fm_index_iterator &&) noexcept=default
 
bi_fm_index_iteratoroperator= (bi_fm_index_iterator &&) noexcept=default
 
 bi_fm_index_iterator (index_t const &_index) noexcept
 

Detailed Description

template<typename index_t>
class seqan3::bi_fm_index_iterator< index_t >

The SeqAn Bidirectional FM Index Iterator.

Template Parameters
index_tThe type of the underlying index; must model seqan3::bi_fm_index_concept.

The iterator's interface provides searching a string both from left to right as well as from right to left in the indexed text. It extends the interface of the unidirectional seqan3::fm_index_iterator. All methods modifying the iterator (e.g. extending by a character with extend_right()) return a bool value whether the operation was successful or not. In case of an unsuccessful operation the iterator remains unmodified, i.e. an iterator can never be in an invalid state except default constructed iterators that are always invalid.

The asymptotic running times for using the iterator depend on the SDSL index configuration. To determine the exact running times, you have to additionally look up the running times of the used traits (configuration).

Member Function Documentation

◆ count()

template<typename index_t >
size_type seqan3::bi_fm_index_iterator< index_t >::count ( ) const
inlinenoexcept

Counts the number of occurrences of the searched query in the text.

Returns
Number of occurrences of the searched query in the text.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ cycle_back()

template<typename index_t >
bool seqan3::bi_fm_index_iterator< index_t >::cycle_back ( )
inlinenoexcept

Tries to replace the rightmost character of the query by the next lexicographically larger character such that the query is found in the text.

Returns
true if there exists a query in the text where the rightmost character of the query is lexicographically larger than the current rightmost character of the query.

Example:

std::vector<dna4> genome{"GAATTAATGAAC"_dna4};
bi_fm_index index{genome}; // build the index
auto it = index.begin(); // create an iterator
// it.cycle_back(); // cycle_back / cycle_front on begin() is undefined behaviour!
it.extend_right("AAC"_dna4); // search the sequence "AAC"
debug_stream << it.query() << '\n'; // outputs "AAC"
debug_stream << it.last_char() << '\n'; // outputs 'C'
// it.cycle_front(); // undefined behaviour! only cycle_back() is allowed after extend_right()
it.cycle_back(); // search the sequence "AAT"
debug_stream << it.query() << '\n'; // outputs "AAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'
it.extend_left('G'_dna4); // search the sequence "GAAT"
debug_stream << it.query() << '\n'; // outputs "GAAC"
debug_stream << it.last_char() << '\n'; // outputs 'G'
// it.cycle_back(); // undefined behaviour! only cycle_front() is allowed after extend_left()
it.cycle_front(); // search the sequence "TAAT"
debug_stream << it.query() << '\n'; // outputs "TAAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'
it.cycle_front(); // search the sequence "TAAT"
debug_stream << it.query() << '\n'; // outputs "TAAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'

Complexity

$O(\Sigma) * O(T_{BACKWARD\_SEARCH})$

It scans linearly over the alphabet starting from the rightmost character until it finds the query with a larger rightmost character.

Exceptions

No-throw guarantee.

◆ cycle_front()

template<typename index_t >
bool seqan3::bi_fm_index_iterator< index_t >::cycle_front ( )
inlinenoexcept

Tries to replace the leftmost character of the query by the next lexicographically larger character such that the query is found in the text.

Returns
true if there exists a query in the text where the leftmost character of the query is lexicographically larger than the current leftmost character of the query.

Example:

std::vector<dna4> genome{"GAATTAATGAAC"_dna4};
bi_fm_index index{genome}; // build the index
auto it = index.begin(); // create an iterator
// it.cycle_back(); // cycle_back / cycle_front on begin() is undefined behaviour!
it.extend_right("AAC"_dna4); // search the sequence "AAC"
debug_stream << it.query() << '\n'; // outputs "AAC"
debug_stream << it.last_char() << '\n'; // outputs 'C'
// it.cycle_front(); // undefined behaviour! only cycle_back() is allowed after extend_right()
it.cycle_back(); // search the sequence "AAT"
debug_stream << it.query() << '\n'; // outputs "AAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'
it.extend_left('G'_dna4); // search the sequence "GAAT"
debug_stream << it.query() << '\n'; // outputs "GAAC"
debug_stream << it.last_char() << '\n'; // outputs 'G'
// it.cycle_back(); // undefined behaviour! only cycle_front() is allowed after extend_left()
it.cycle_front(); // search the sequence "TAAT"
debug_stream << it.query() << '\n'; // outputs "TAAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'
it.cycle_front(); // search the sequence "TAAT"
debug_stream << it.query() << '\n'; // outputs "TAAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'

Complexity

$O(\Sigma) * O(T_{BACKWARD\_SEARCH})$

It scans linearly over the alphabet starting from the leftmost character until it finds the query with a larger leftmost character.

Exceptions

No-throw guarantee.

◆ extend_left() [1/3]

template<typename index_t >
bool seqan3::bi_fm_index_iterator< index_t >::extend_left ( )
inlinenoexcept

Tries to extend the query by the smallest possible character to the left such that the query is found in the text.

Returns
true if the iterator could extend the query successfully.

Complexity

$O(\Sigma) * O(T_{BACKWARD\_SEARCH})$

It scans linearly over the alphabet until it finds the smallest character that is represented by an edge.

Exceptions

No-throw guarantee.

◆ extend_left() [2/3]

template<typename index_t >
template<alphabet_concept char_t>
bool seqan3::bi_fm_index_iterator< index_t >::extend_left ( char_t const  c)
inlinenoexcept

Tries to extend the query by the character c to the left.

Template Parameters
char_tType of the character needs to be convertible to the character type char_type of the indexed text.
Parameters
[in]cCharacter to extend the query with to the left.
Returns
true if the iterator could extend the query successfully.

Complexity

$O(T_{BACKWARD\_SEARCH})$

Exceptions

No-throw guarantee.

◆ extend_left() [3/3]

template<typename index_t >
template<std::ranges::RandomAccessRange seq_t>
bool seqan3::bi_fm_index_iterator< index_t >::extend_left ( seq_t &&  seq)
inlinenoexcept

Tries to extend the query by seq to the left.

Template Parameters
seq_tThe type of range of the sequence to search; must model std::ranges::RandomAccessRange.
Parameters
[in]seqSequence to extend the query with to the left (starting from right to left, see example).
Returns
true if the iterator could extend the query successfully.

If extending fails in the middle of the sequence, all previous computations are rewound to restore the iterator's state before calling this method.

Example:

std::vector<dna4> genome{"GAATTAATGAAC"_dna4};
bi_fm_index index{genome}; // build the index
auto it = index.begin(); // create an iterator
it.extend_right("AAC"_dna4); // search the sequence "AAC"
debug_stream << it.query() << '\n'; // outputs "AAC"
it.extend_left("ATG"_dna4); // extend the query to "ATGAAT"
// The rightmost character of "ATG" is extended to the left first.
debug_stream << it.query() << '\n'; // outputs "ATGAAT"

Complexity

$|seq| * O(T_{BACKWARD\_SEARCH})$

Exceptions

No-throw guarantee.

◆ extend_right() [1/3]

template<typename index_t >
bool seqan3::bi_fm_index_iterator< index_t >::extend_right ( )
inlinenoexcept

Tries to extend the query by the smallest possible character to the right such that the query is found in the text.

Returns
true if the iterator could extend the query successfully.

Complexity

$O(\Sigma) * O(T_{BACKWARD\_SEARCH})$

It scans linearly over the alphabet until it finds the smallest character that is represented by an edge.

Exceptions

No-throw guarantee.

◆ extend_right() [2/3]

template<typename index_t >
template<alphabet_concept char_t>
bool seqan3::bi_fm_index_iterator< index_t >::extend_right ( char_t const  c)
inlinenoexcept

Tries to extend the query by the character c to the right.

Template Parameters
char_tType of the character needs to be convertible to the character type char_type of the indexed text.
Parameters
[in]cCharacter to extend the query with to the right.
Returns
true if the iterator could extend the query successfully.

Complexity

$O(T_{BACKWARD\_SEARCH})$

Exceptions

No-throw guarantee.

◆ extend_right() [3/3]

template<typename index_t >
template<std::ranges::RandomAccessRange seq_t>
bool seqan3::bi_fm_index_iterator< index_t >::extend_right ( seq_t &&  seq)
inlinenoexcept

Tries to extend the query by seq to the right.

Template Parameters
seq_tThe type of range of the sequence to search; must model std::ranges::RandomAccessRange.
Parameters
[in]seqSequence to extend the query with to the right.
Returns
true if the iterator could extend the query successfully.

If extending fails in the middle of the sequence, all previous computations are rewound to restore the iterator's state before calling this method.

Complexity

$|seq| * O(T_{BACKWARD\_SEARCH})$

Exceptions

No-throw guarantee.

◆ last_char()

template<typename index_t >
index_t::char_type seqan3::bi_fm_index_iterator< index_t >::last_char ( )
inlinenoexcept

Outputs the rightmost respectively leftmost character depending on whether extend_right() or extend_left() has been called last.

Returns
Rightmost or leftmost character.

Example:

std::vector<dna4> genome{"GAATTAATGAAC"_dna4};
bi_fm_index index{genome}; // build the index
auto it = index.begin(); // create an iterator
// it.cycle_back(); // cycle_back / cycle_front on begin() is undefined behaviour!
it.extend_right("AAC"_dna4); // search the sequence "AAC"
debug_stream << it.query() << '\n'; // outputs "AAC"
debug_stream << it.last_char() << '\n'; // outputs 'C'
// it.cycle_front(); // undefined behaviour! only cycle_back() is allowed after extend_right()
it.cycle_back(); // search the sequence "AAT"
debug_stream << it.query() << '\n'; // outputs "AAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'
it.extend_left('G'_dna4); // search the sequence "GAAT"
debug_stream << it.query() << '\n'; // outputs "GAAC"
debug_stream << it.last_char() << '\n'; // outputs 'G'
// it.cycle_back(); // undefined behaviour! only cycle_front() is allowed after extend_left()
it.cycle_front(); // search the sequence "TAAT"
debug_stream << it.query() << '\n'; // outputs "TAAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'
it.cycle_front(); // search the sequence "TAAT"
debug_stream << it.query() << '\n'; // outputs "TAAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ lazy_locate()

template<typename index_t >
auto seqan3::bi_fm_index_iterator< index_t >::lazy_locate ( ) const
inline

Locates the occurrences of the searched query in the text on demand, i.e. a ranges::view is returned and every position is located once it is accessed.

Returns
Positions in the text.

Complexity

$count() * O(T_{BACKWARD\_SEARCH} * SAMPLING\_RATE)$

Exceptions

Strong exception guarantee (no data is modified in case an exception is thrown).

◆ locate()

template<typename index_t >
std::vector<size_type> seqan3::bi_fm_index_iterator< index_t >::locate ( ) const
inline

Locates the occurrences of the searched query in the text.

Returns
Positions in the text.

Complexity

$count() * O(T_{BACKWARD\_SEARCH} * SAMPLING\_RATE)$

Exceptions

Strong exception guarantee (no data is modified in case an exception is thrown).

◆ operator!=()

template<typename index_t >
bool seqan3::bi_fm_index_iterator< index_t >::operator!= ( bi_fm_index_iterator< index_t > const &  rhs) const
inlinenoexcept

Compares two iterators.

Parameters
[in]rhsOther iterator to compare it to.
Returns
true if the iterators are not equal, false otherwise.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ operator*()

template<typename index_t >
auto seqan3::bi_fm_index_iterator< index_t >::operator* ( ) const
inlinenoexcept

Returns the searched query.

Complexity

$O(SAMPLING\_RATE * T_{BACKWARD\_SEARCH}) + query\_length()$

Exceptions

No-throw guarantee.

◆ operator==()

template<typename index_t >
bool seqan3::bi_fm_index_iterator< index_t >::operator== ( bi_fm_index_iterator< index_t > const &  rhs) const
inlinenoexcept

Compares two iterators.

Parameters
[in]rhsOther iterator to compare it to.
Returns
true if both iterators are equal, false otherwise.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ query()

template<typename index_t >
auto seqan3::bi_fm_index_iterator< index_t >::query ( ) const
inlinenoexcept

Returns the searched query.

Complexity

$O(SAMPLING\_RATE * T_{BACKWARD\_SEARCH}) + query\_length()$

Exceptions

No-throw guarantee.

◆ query_length()

template<typename index_t >
size_type seqan3::bi_fm_index_iterator< index_t >::query_length ( ) const
inlinenoexcept

Returns the depth of the iterator node in the implicit suffix tree, i.e. the length of the sequence searched.

Returns
Length of searched sequence.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ to_fwd_iterator()

template<typename index_t >
fwd_iterator seqan3::bi_fm_index_iterator< index_t >::to_fwd_iterator ( ) const
inlinenoexcept

Returns a unidirectional seqan3::fm_index_iterator on the original text. query() on the returned unidirectional index iterator will be equal to query() on the bidirectional index iterator. cycle_back() and last_char() will be undefined behavior if the last extension on the bidirectional FM index has been to the left. The behavior will be well-defined after the first extension to the right on the unidirectional index.

Returns
Returns a unidirectional seqan3::fm_index_iterator on the index of the original text.

Example:

std::vector<dna4> genome{"GAATTAACGAAC"_dna4};
bi_fm_index index{genome}; // build the index
auto it = index.begin(); // create an iterator
it.extend_left("AAC"_dna4); // search the sequence "AAC"
debug_stream << it.query() << '\n'; // outputs "AAC"
auto uni_it = it.to_fwd_iterator(); // unidirectional iterator on the text "GAATTAACGAAC"
debug_stream << uni_it.query() << '\n'; // outputs "CAA"
// Undefined behaviour! Cannot be called on the forward iterator if the last extension on the bidirectional
// iterator was to the left:
// it.cycle_back();
// debug_stream << it.last_char() << '\n';
uni_it.extend_right('G'_dna4); // search the sequence "AACG"
debug_stream << uni_it.query() << '\n'; // outputs "AACG"
debug_stream << uni_it.last_char() << '\n'; // outputs 'G'
uni_it.cycle_back(); // returns false since there is no sequence "AACT" in the text.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ to_rev_iterator()

template<typename index_t >
rev_iterator seqan3::bi_fm_index_iterator< index_t >::to_rev_iterator ( ) const
inlinenoexcept

Returns a unidirectional seqan3::fm_index_iterator on the reversed text. query() on the returned unidirectional index iterator will be equal to reversing query() on the bidirectional index iterator. Note that because of the text being reversed, extend_right() resp. cycle_back() correspond to extend_left() resp. cycle_front() on the bidirectional index iterator. Furthermore cycle_back() and last_char() will be undefined behavior if the last extension on the bidirectional FM index has been to the left. The behavior will be well-defined after the first extension to the right on the unidirectional index.

Returns
Returns a unidirectional seqan3::fm_index_iterator on the index of the reversed text.

Example:

std::vector<dna4> genome{"GAATTAACGAAC"_dna4};
bi_fm_index index{genome}; // build the index
auto it = index.begin(); // create an iterator
it.extend_right("AAC"_dna4); // search the sequence "AAC"
debug_stream << it.query() << '\n'; // outputs "AAC"
auto uni_it = it.to_rev_iterator(); // unidirectional iterator on the text "CAAGCAATTAAG"
debug_stream << uni_it.query() << '\n'; // outputs "CAA"
// Undefined behaviour! Cannot be called on the reversed iterator if the last extension on the bidirectional
// iterator was to the right:
// it.cycle_back();
// debug_stream << it.last_char() << '\n';
uni_it.extend_right('G'_dna4); // search the sequence "CAAG"
debug_stream << uni_it.query() << '\n'; // outputs "CAAG"
debug_stream << uni_it.last_char() << '\n'; // outputs 'G'
uni_it.cycle_back(); // search the sequence "CAAT"

Complexity

Constant.

Exceptions

No-throw guarantee.


The documentation for this class was generated from the following file: