SeqAn3
seqan3::fm_index_iterator< index_t > Class Template Reference

The SeqAn FM Index Iterator. More...

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

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

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 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 character. 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!= (fm_index_iterator const &rhs) const noexcept
 Compares two iterators. More...
 
auto operator* () const noexcept
 Returns the searched query. More...
 
bool operator== (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 length of the searched query. More...
 
Constructors, destructor and assignment
 fm_index_iterator () noexcept=default
 Default constructor. Accessing member functions on a default constructed object is undefined behavior.
 
 fm_index_iterator (fm_index_iterator const &) noexcept=default
 
fm_index_iteratoroperator= (fm_index_iterator const &) noexcept=default
 
 fm_index_iterator (fm_index_iterator &&) noexcept=default
 
fm_index_iteratoroperator= (fm_index_iterator &&) noexcept=default
 
 fm_index_iterator (index_t const &_index) noexcept
 

Friends

template<typename _index_t >
class bi_fm_index_iterator
 

Member types

using index_type = index_t
 Type of the index.
 
using size_type = typename index_type::size_type
 Type for representing positions in the indexed text.
 

Detailed Description

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

The SeqAn FM Index Iterator.

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

The iterator's interface provides searching a string from left to right in the indexed text. 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::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::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{"AATAATAAC"_dna4};
fm_index index{genome}; // build the index
auto it = index.begin(); // create an iterator
// it.cycle_back(); // cycle_back 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_back(); // search the sequence "AAT"
debug_stream << it.query() << '\n'; // outputs "AAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'
it.cycle_back(); // "it" doesn't change because the rightmost char is already the largest dna4 char.
debug_stream << it.query() << '\n'; // outputs "AAT"
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.

◆ extend_right() [1/3]

template<typename index_t >
bool seqan3::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::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::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::fm_index_iterator< index_t >::last_char ( )
inlinenoexcept

Outputs the rightmost character.

Returns
Rightmost character.

Example:

std::vector<dna4> genome{"AATAATAAC"_dna4};
fm_index index{genome}; // build the index
auto it = index.begin(); // create an iterator
// it.cycle_back(); // cycle_back 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_back(); // search the sequence "AAT"
debug_stream << it.query() << '\n'; // outputs "AAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'
it.cycle_back(); // "it" doesn't change because the rightmost char is already the largest dna4 char.
debug_stream << it.query() << '\n'; // outputs "AAT"
debug_stream << it.last_char() << '\n'; // outputs 'T'

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ lazy_locate()

template<typename index_t >
auto seqan3::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::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::fm_index_iterator< index_t >::operator!= ( 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::fm_index_iterator< index_t >::operator* ( ) const
inlinenoexcept

Returns the searched query.

Returns
Searched query.

Complexity

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

Exceptions

No-throw guarantee.

◆ operator==()

template<typename index_t >
bool seqan3::fm_index_iterator< index_t >::operator== ( 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::fm_index_iterator< index_t >::query ( ) const
inlinenoexcept

Returns the searched query.

Returns
Searched query.

Complexity

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

Exceptions

No-throw guarantee.

◆ query_length()

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

Returns the length of the searched query.

Returns
Length of query.

Complexity

Constant.

Exceptions

No-throw guarantee.


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