SeqAn3
seqan3::fm_index< text_t, fm_index_traits > Class Template Reference

The SeqAn FM Index. More...

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

Inheritance diagram for seqan3::fm_index< text_t, fm_index_traits >:
[legend]

Public Member Functions

iterator_type begin () const noexcept
 Returns a seqan3::fm_index_iterator on the index that can be used for searching. More...
 
void construct (text_t const &text)
 Constructs the index given a range. The range cannot be an rvalue (i.e. a temporary object) and has to be non-empty. More...
 
void construct (text_t &&)=delete
 
void construct (text_t const &&)=delete
 
bool empty () const noexcept
 Checks whether the index is empty. More...
 
bool load (filesystem::path const &path)
 Loads the index from disk. Temporary function until cereal is supported. More...
 
size_type size () const noexcept
 Returns the length of the indexed text including sentinel characters. More...
 
bool store (filesystem::path const &path) const
 Stores the index to disk. Temporary function until cereal is supported. More...
 
Constructors, destructor and assignment
 fm_index ()=default
 
 fm_index (fm_index const &)=default
 
fm_indexoperator= (fm_index const &)=default
 
 fm_index (fm_index &&)=default
 
fm_indexoperator= (fm_index &&)=default
 
 ~fm_index ()=default
 
 fm_index (text_t const &text)
 Constructor that immediately constructs the index given a range. The range cannot be an rvalue (i.e. a temporary object) and has to be non-empty. More...
 
 fm_index (text_t &&)=delete
 
 fm_index (text_t const &&)=delete
 

Friends

template<typename bi_fm_index_t >
class bi_fm_index_iterator
 
template<typename fm_index_t >
class fm_index_iterator
 

Member types

using text_type = text_t
 The type of the indexed text.
 
using char_type = innermost_value_type_t< text_t >
 The type of the underlying character of text_type.
 
using size_type = typename sdsl_index_type::size_type
 Type for representing positions in the indexed text.
 
using iterator_type = fm_index_iterator< fm_index< text_t, fm_index_traits > >
 The type of the (unidirectional) iterator.
 

Detailed Description

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
class seqan3::fm_index< text_t, fm_index_traits >

The SeqAn FM Index.

Template Parameters
text_tThe type of the text to be indexed; must model std::ranges::ForwardRange.
fm_index_traitsThe traits determining the implementation of the underlying SDSL index; must model seqan3::fm_index_traits_concept.

The seqan3::fm_index is a fast and space-efficient string index to search strings and collections of strings.

General information

Here is a short example on how to build an index and search a pattern using an iterator. Please note that there is a very powerful search module with a high-level interface

Todo:
seqan3::search that encapsulates the use of iterators.
#include <vector>
using namespace seqan3;
int main()
{
std::vector<dna4> genome{"ATCGATCGAAGGCTAGCTAGCTAAGGGA"_dna4};
fm_index index{genome}; // build the index
auto it = index.begin(); // create an iterator
it.extend_right("AAGG"_dna4); // search the pattern "AAGG"
debug_stream << "Number of hits: " << it.count() << '\n'; // outputs: 2
debug_stream << "Positions in the genome: ";
for (auto const & pos : it.locate()) // outputs: 8, 22
debug_stream << pos << ' ';
debug_stream << '\n';
return 0;
}

Here is an example using a collection of strings (e.g. a genome with multiple chromosomes or a protein database):

Coming soon. Stay tuned!

Choosing an index implementation

Todo:
The underlying implementation of the FM Index (Rank data structure, sampling rates, etc.) can be specified ...

Constructor & Destructor Documentation

◆ fm_index() [1/3]

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
seqan3::fm_index< text_t, fm_index_traits >::fm_index ( text_t const &  text)
inline

Constructor that immediately constructs the index given a range. The range cannot be an rvalue (i.e. a temporary object) and has to be non-empty.

Template Parameters
text_tThe type of range to construct from; must model std::ranges::RandomAccessRange.
Parameters
[in]textThe text to construct from.

Complexity

Todo:
At least linear.

◆ fm_index() [2/3]

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
seqan3::fm_index< text_t, fm_index_traits >::fm_index ( text_t &&  )
delete

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ fm_index() [3/3]

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
seqan3::fm_index< text_t, fm_index_traits >::fm_index ( text_t const &&  )
delete

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Member Function Documentation

◆ begin()

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
iterator_type seqan3::fm_index< text_t, fm_index_traits >::begin ( ) const
inlinenoexcept

Returns a seqan3::fm_index_iterator on the index that can be used for searching.

Returns
Returns a (unidirectional) seqan3::fm_index_iterator on the index.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ construct() [1/3]

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
void seqan3::fm_index< text_t, fm_index_traits >::construct ( text_t const &  text)
inline

Constructs the index given a range. The range cannot be an rvalue (i.e. a temporary object) and has to be non-empty.

Template Parameters
text_tThe type of range to construct from; must model std::ranges::RandomAccessRange.
Parameters
[in]textThe text to construct from.
Todo:
This has to be better implemented with regard to the memory peak due to not matching interfaces with the SDSL.

Complexity

Todo:
At least linear.

Exceptions

No guarantees.

◆ construct() [2/3]

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
void seqan3::fm_index< text_t, fm_index_traits >::construct ( text_t &&  )
delete

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ construct() [3/3]

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
void seqan3::fm_index< text_t, fm_index_traits >::construct ( text_t const &&  )
delete

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ empty()

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
bool seqan3::fm_index< text_t, fm_index_traits >::empty ( ) const
inlinenoexcept

Checks whether the index is empty.

Returns
true if the index is empty, false otherwise.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ load()

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
bool seqan3::fm_index< text_t, fm_index_traits >::load ( filesystem::path const &  path)
inline

Loads the index from disk. Temporary function until cereal is supported.

Todo:
cereal
Returns
true if the index was successfully loaded from disk.

Complexity

Linear.

Exceptions

Strong exception guarantee.

◆ size()

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
size_type seqan3::fm_index< text_t, fm_index_traits >::size ( ) const
inlinenoexcept

Returns the length of the indexed text including sentinel characters.

Returns
Returns the length of the indexed text including sentinel characters.

Complexity

Constant.

Exceptions

No-throw guarantee.

◆ store()

template<std::ranges::RandomAccessRange text_t, fm_index_traits_concept fm_index_traits = fm_index_default_traits>
bool seqan3::fm_index< text_t, fm_index_traits >::store ( filesystem::path const &  path) const
inline

Stores the index to disk. Temporary function until cereal is supported.

Todo:
cereal
Returns
true if the index was successfully stored to disk.

Complexity

Linear.

Exceptions

Strong exception guarantee.


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