Finder - SeqAn API Documentation

# Class Finder
Holds the haystack and a current search context.

All Subcl's | PigeonholeFinder, SwiftFinder, SwiftLocalFinder, SwiftSemiGlobalFinder
Defined in | <seqan/find.h>
Signature | `template <typename THaystack[, typename TSpec]> class Finder;`

## Template Parameters

`TSpec` | The index-algorithm to search with (Optional).Leave empty for online pattern matching (see Pattern).If `THaystack` is an Index, then `TSpec` specifies the index search algorithm. Types: Pigeonhole, Swift, Backtracking Default: The result of DefaultFinder
`THaystack` | The haystack type. Types: String, Index

## Member Function Overview

- `Finder::Finder();, Finder::Finder(other);, Finder::Finder(haystack);, Finder::Finder(iter);`
  Constructor

## Interface Function Overview

- `TIter begin(finder[, tag]);`
  Return begin iterator of the match in the haystack.
- `TPosition beginPosition(finder);`
  Return begin position of match.
- `void clear(finder);`
  Clear the Finder.
- `TIter end(finder[, tag]);`
  Return end iterator of the match in the haystack.
- `TPosition endPosition(finder);`
  Return end position of match.
- `bool find(finder, pattern[, k]);`
  Search for a Pattern in a Finder object.
- `bool findBegin(finder, pattern[, limit]);`
  Search the begin of an approximate match.
- `void goBegin(finder);`
  Go to the beginning of the text.
- `void goEnd(finder);`
  Go to the end of the text.
- `THaystack haystack(finder);`
  Returns the haystack of a Finder.
- `TInfix infix(finder);`
  Returns the segment of the last found match in the haystack.
- `TSize length(finder);`
  Return the length of the match.
- `TPosition position(finder);`
  Return current position of the finder in the haystack.
- `void setHaystack(finder, haystack);`
  Sets the haystack of a Finder object.
- `void setPosition(finder, pos);`
  Sets the position of a finder.

## Interface Metafunction Overview

- `Haystack<TFinder>::Type;`
  Returns the haystack type of a Finder type.

## Detailed Description

`position(finder)` returns the position of the current hit in the haystack. If `THaystack` is a set of strings or an index of a set of strings, then `position(finder)` returns a Pair `(hayNo, pos)`, in which `hayNo` is the haystack index and `pos` the local position of the hit.

To reset the finder object and use it on another text or different text position, use `clear(finder)` Note that `clear(finder)` doesn't move the text iterator. To start the search from the beginning or somewhere else in the text, use goBegin or setPosition.

### Examples

The following example shows how to restart a search from the beginning of a text.

    #include <seqan/find.h>

    using namespace seqan2;

    int main()
    {
        CharString hstck = "I spy with my little eye something that is yellow";
        Finder<CharString> finder(hstck);

        Pattern<CharString, Horspool> p1("y");

        while (find(finder, p1))
            std::cout << "Hit at position: " << position(finder) << std::endl;

        goBegin(finder);    // move Finder to the beginning of the text
        clear(finder);      // reset Finder

        Pattern<CharString, Horspool> p2("t");
        while (find(finder, p2))
            std::cout << "Hit at position: " << position(finder) << std::endl;
    }

Demo: demos/dox/find/finder_online.cpp

The output is as follows:

    Hit at position: 4
    Hit at position: 12
    Hit at position: 22
    Hit at position: 43
    Hit at position: 8
    Hit at position: 16
    Hit at position: 17
    Hit at position: 29
    Hit at position: 35
    Hit at position: 38

Demo: Demo.Index Finder StringSet

Demo: Demo.Index Finder

## Member Functions Detail

### `Finder::Finder(); Finder::Finder(other); Finder::Finder(haystack); Finder::Finder(iter);`

Constructor

#### Parameters

`other` | Other Finder of the same type (copy constructor).
`haystack` | The haystack to work on, of type `THaystack`.
`iter` | The iter to work on on, either const or non-const.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

## Interface Functions Detail

### `TIter begin(finder[, tag]);`

Return begin iterator of the match in the haystack.

#### Parameters

`finder` | The Finder to query.
`tag` | The tag to select the iterator type.

#### Returns

`TIter` | The iterator to the begin of the match in the haystack. TIter is the same type as returned by `begin(haystack[, tag])` where `haystack` is the haystack.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TPosition beginPosition(finder);`

Return begin position of match.

#### Parameters

`finder` | The Finder to query.

#### Returns

`TPosition` | The begin position of the finder. TPosition is the position type of THaystack.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void clear(finder);`

Clear the Finder.

#### Parameters

`finder` | The Finder to clear.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TIter end(finder[, tag]);`

Return end iterator of the match in the haystack.

#### Parameters

`finder` | The Finder to query.
`tag` | The tag to select the iterator type.

#### Returns

`TIter` | The iterator to the end of the match in the haystack. TIter is the same type as returned by `end(haystack[, tag])` where `haystack` is the haystack.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TPosition endPosition(finder);`

Return end position of match.

#### Parameters

`finder` | The Finder to query.

#### Returns

`TPosition` | The end position of the finder. TPosition is the position type of THaystack.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool find(finder, pattern[, k]);`

Search for a Pattern in a Finder object.

#### Parameters

`finder` | The Finder object to search through.
`pattern` | The Pattern to search for. For index finders, pattern can also be a text. Types: Pattern, TextConcept.
`k` | Desired minimal score (for approximate matching). `k` is a number `<= 0`. Differences are deletions, insertions, and substitutions.

#### Returns

`bool` | `true` if an occurrence was found and `false` if not.

Repeated calls of this function iterate through all occurrences of `pattern`.

#### Examples

The following example shows how one can search online for a pattern in a haystack. Note that it is neccessary to reset the finder before searching for another pattern.

    #include <seqan/find.h>

    using namespace seqan2;

    int main()
    {
        CharString hstck = "I spy with my little eye something that is yellow";
        Finder<CharString> finder(hstck);

        Pattern<CharString, Horspool> p1("y");

        while (find(finder, p1))
            std::cout << "Hit at position: " << position(finder) << std::endl;

        goBegin(finder);    // move Finder to the beginning of the text
        clear(finder);      // reset Finder

        Pattern<CharString, Horspool> p2("t");
        while (find(finder, p2))
            std::cout << "Hit at position: " << position(finder) << std::endl;
    }

Demo: demos/dox/find/finder_online.cpp

The output is as follows.

    Hit at position: 4
    Hit at position: 12
    Hit at position: 22
    Hit at position: 43
    Hit at position: 8
    Hit at position: 16
    Hit at position: 17
    Hit at position: 29
    Hit at position: 35
    Hit at position: 38

In contrast to the example above the code below shows how one can use a Finder with an index as base. Again, note that it is neccessary to reset the finder before searching for another pattern.

    #include <seqan/find.h>
    #include <seqan/index.h>

    using namespace seqan2;

    int main()
    {
        CharString hstck = "I spy with my little eye something that is yellow";
        Index<CharString, FMIndex<> > index(hstck);
        Finder<Index<CharString, FMIndex<> > > finder(hstck);

        while (find(finder, "y"))
            std::cout << "Hit at position: " << position(finder) << std::endl;

        clear(finder);      // reset Finder

        while (find(finder, "t"))
            std::cout << "Hit at position: " << position(finder) << std::endl;
    }

Demo: demos/dox/find/finder_index.cpp

The output is as follows.

    Hit at position: 12
    Hit at position: 4
    Hit at position: 22
    Hit at position: 43
    Hit at position: 38
    Hit at position: 8
    Hit at position: 35
    Hit at position: 29
    Hit at position: 17
    Hit at position: 16

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool findBegin(finder, pattern[, limit]);`

Search the begin of an approximate match.

#### Parameters

`finder` | The Finder object to search through.
`pattern` | The Pattern object to search for. This must be a pattern for approximate string matching.
`limit` | The score limit. The default is the limit used during the last `find` call, see `getScore`. All occurrences that score at least `limit` are reported.

#### Returns

`bool` | `true` indicates a match, `false` indicates no match.

The function `find` successfully called be called - that is an end position was found - before calling findBegin to find a begin position.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void goBegin(finder);`

Go to the beginning of the text.

#### Parameters

`finder` | The finder to reset to the beginning of the text.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void goEnd(finder);`

Go to the end of the text.

#### Parameters

`finder` | The finder to reset to the end of the text.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `THaystack haystack(finder);`

Returns the haystack of a Finder.

#### Parameters

`finder` | The Finder to query for its haystack.

#### Returns

`THaystack` | The result type can be retrieved using Haystack.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TInfix infix(finder);`

Returns the segment of the last found match in the haystack.

#### Parameters

`finder` | The Finder to query.

#### Returns

`TInfix` | The Infix of the match in the haystack.

This function works only correct if the begin position of the match was already found, see findBegin

For finders or patterns of filtering algorithms (e.g. @Spec.Swift@) the returned infix is a potential match.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TSize length(finder);`

Return the length of the match.

#### Parameters

`finder` | The finder to query for its match length.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TPosition position(finder);`

Return current position of the finder in the haystack.

#### Parameters

`finder` | The Finder to query.

#### Returns

`TPosition` | The current position. TPosition is the position type of the haystack.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void setHaystack(finder, haystack);`

Sets the haystack of a Finder object.

#### Parameters

`finder` | The finder to set the haystack for.
`haystack` | The haystack to set.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `void setPosition(finder, pos);`

Sets the position of a finder.

#### Parameters

`finder` | The Findre to set the position for.
`pos` | The position to set the finder to.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

## Interface Metafunctions Detail

### `Haystack<TFinder>::Type;`

Returns the haystack type of a Finder type.

#### Template Parameters

`TFinder` | The finder to query.

#### Returns

`Type` | The haystack type of `TFinder`, i.e. `THaystack` for `Finder<THaystack, TSpec>`. This is an alias to function `host()` of the pattern function.

#### Dox Sources

    /*!
     * @class Finder
     *
     * @headerfile <seqan/find.h>
     *
     * @brief Holds the haystack and a current search context.
     *
     * @signature template <typename THaystack[, typename TSpec]> class Finder;
     *
     * @tparam TSpec The index-algorithm to search with (Optional).Leave empty for
     *               online pattern matching (see @link Pattern @endlink).If
     *               <tt>THaystack</tt> is an @link Index @endlink, then
     *               <tt>TSpec</tt> specifies the index search algorithm. Types:
     *               Pigeonhole, Swift, Backtracking Default: The result of @link
     *               DefaultFinder @endlink
     * @tparam THaystack The haystack type. Types: String, Index
     *
     * <tt>position(finder)</tt> returns the position of the current hit in the
     * haystack. If <tt>THaystack</tt> is a set of strings or an index of a set of
     * strings, then <tt>position(finder)</tt> returns a @link Pair @endlink
     * <tt>(hayNo, pos)</tt>, in which <tt>hayNo</tt> is the haystack index and
     * <tt>pos</tt> the local position of the hit.
     *
     * To reset the finder object and use it on another text or different text
     * position, use <tt>clear(finder)</tt> Note that <tt>clear(finder)</tt> doesn't
     * move the text iterator. To start the search from the beginning or somewhere
     * else in the text, use @link Finder#goBegin @endlink or @link
     * Finder#setPosition @endlink.
     *
     * @section Examples
     *
     * The following example shows how to restart a search from the beginning of a
     * text.
     *
     * @include demos/dox/find/finder_online.cpp
     *
     * The output is as follows:
     *
     * @include demos/dox/find/finder_online.cpp.stdout
     *
     * Demo: Demo.Index Finder StringSet
     *
     * Demo: Demo.Index Finder
     *
     * @mfn Finder#Haystack
     *
     * @headerfile <seqan/file.h>
     *
     * @brief Returns the haystack type of a @link Finder @endlink type.
     *
     * @signature Haystack<TFinder>::Type;
     *
     * @tparam TFinder The finder to query.
     *
     * @return Type The haystack type of <tt>TFinder</tt>, i.e. <tt>THaystack</tt>
     *              for <tt>Finder&lt;THaystack, TSpec&gt;</tt>. This is an alias to
     *              function <tt>host()</tt> of the pattern function.
     *
     * @fn Finder#find
     *
     * @headerfile <seqan/find.h>
     *
     * @brief Search for a @link Pattern @endlink in a @link Finder @endlink object.
     *
     * @signature bool find(finder, pattern[, k]);
     *
     * @param[in,out] finder The @link Finder @endlink object to search through.
     * @param[in] pattern The @link Pattern @endlink to search for. For index
     *                    finders, pattern can also be a text. Types: @link Pattern
     *                    @endlink, @link TextConcept @endlink.
     * @param[in] k Desired minimal score (for approximate matching). <tt>k</tt> is
     *              a number <tt>&lt;= 0</tt>. Differences are deletions,
     *              insertions, and substitutions.
     *
     * @return bool <tt>true</tt> if an occurrence was found and <tt>false</tt> if
     *              not.
     *
     * Repeated calls of this function iterate through all occurrences of
     * <tt>pattern</tt>.
     *
     * @section Examples
     *
     * The following example shows how one can search online for a pattern in a
     * haystack. Note that it is neccessary to reset the finder before searching for
     * another pattern.
     *
     * @include demos/dox/find/finder_online.cpp
     *
     * The output is as follows.
     *
     * @include demos/dox/find/finder_online.cpp.stdout
     *
     * In contrast to the example above the code below shows how one can use a
     * Finder with an index as base. Again, note that it is neccessary to reset the
     * finder before searching for another pattern.
     *
     * @include demos/dox/find/finder_index.cpp
     *
     * The output is as follows.
     *
     * @include demos/dox/find/finder_index.cpp.stdout
     *
     *
     *
     * @fn Finder#beginPosition
     *
     * @brief Return begin position of match.
     *
     * @signature TPosition beginPosition(finder);
     *
     * @param[in] finder The Finder to query.
     *
     * @return TPosition The begin position of the finder. TPosition is the position
     *                   type of THaystack.
     *
     * @fn Finder#begin
     *
     * @brief Return begin iterator of the match in the haystack.
     *
     * @signature TIter begin(finder[, tag]);
     *
     * @param[in] finder The Finder to query.
     * @param[in] tag The tag to select the iterator type.
     *
     * @return TIter The iterator to the begin of the match in the haystack. TIter
     *               is the same type as returned by <tt>begin(haystack[, tag])</tt>
     *               where <tt>haystack</tt> is the haystack.
     *
     * @fn Finder#endPosition
     *
     * @brief Return end position of match.
     *
     * @signature TPosition endPosition(finder);
     *
     * @param[in] finder The Finder to query.
     *
     * @return TPosition The end position of the finder. TPosition is the position
     *                   type of THaystack.
     *
     * @fn Finder#end
     *
     * @brief Return end iterator of the match in the haystack.
     *
     * @signature TIter end(finder[, tag]);
     *
     * @param[in] finder The Finder to query.
     * @param[in] tag The tag to select the iterator type.
     *
     * @return TIter The iterator to the end of the match in the haystack. TIter is
     *               the same type as returned by <tt>end(haystack[, tag])</tt>
     *               where <tt>haystack</tt> is the haystack.
     *
     * @fn Finder#length
     *
     * @brief Return the length of the match.
     *
     * @signature TSize length(finder);
     *
     * @param[in] finder The finder to query for its match length.
     *
     * @fn Finder#infix
     *
     * @brief Returns the segment of the last found match in the haystack.
     *
     * @signature TInfix infix(finder);
     *
     * @param[in] finder The Finder to query.
     *
     * @return TInfix The @link SegmentableConcept#Infix @endlink of the match in
     *                the haystack.
     *
     * This function works only correct if the begin position of the match was
     * already found, see @link Finder#findBegin @endlink
     *
     * For finders or patterns of filtering algorithms (e.g. @Spec.Swift@) the
     * returned infix is a potential match.
     *
     * @fn Finder#clear
     *
     * @headerfile <seqan/find.h>
     *
     * @brief Clear the Finder.
     *
     * @signature void clear(finder);
     *
     * @param[in,out] finder The Finder to clear.
     *
     * @fn Finder#goBegin
     *
     * @brief Go to the beginning of the text.
     *
     * @signature void goBegin(finder);
     *
     * @param[in] finder The finder to reset to the beginning of the text.
     *
     * @fn Finder#goEnd
     *
     * @brief Go to the end of the text.
     *
     * @signature void goEnd(finder);
     *
     * @param[in] finder The finder to reset to the end of the text.
     *
     * @fn Finder#position
     *
     * @brief Return current position of the finder in the haystack.
     *
     * @signature TPosition position(finder);
     *
     * @param[in] finder The Finder to query.
     *
     * @return TPosition The current position. TPosition is the position type of the
     *                   haystack.
     *
     * @fn Finder#setPosition
     *
     * @brief Sets the position of a finder.
     *
     * @signature void setPosition(finder, pos);
     *
     * @param[in,out] finder The Findre to set the position for.
     * @param[in] pos The position to set the finder to.
     *
     * @fn Finder#setHaystack
     *
     * @brief Sets the haystack of a @link Finder @endlink object.
     *
     * @signature void setHaystack(finder, haystack);
     *
     * @param[in,out] finder The finder to set the haystack for.
     * @param[in] haystack The haystack to set.
     *
     * @fn Finder#haystack
     *
     * @brief Returns the haystack of a Finder.
     *
     * @signature THaystack haystack(finder);
     *
     * @param[in] finder The Finder to query for its haystack.
     *
     * @return THaystack The result type can be retrieved using @link
     *                   Finder#Haystack @endlink.
     *
     * @fn Finder#findBegin
     *
     * @headerfile <seqan/find.h>
     *
     * @brief Search the begin of an approximate match.
     *
     * @signature bool findBegin(finder, pattern[, limit]);
     *
     * @param[in,out] finder The Finder object to search through.
     * @param[in,out] pattern The Pattern object to search for. This must be a
     *                        pattern for approximate string matching.
     * @param[in] limit The score limit. The default is the limit used during the
     *                  last <tt>find</tt> call, see <tt>getScore</tt>. All
     *                  occurrences that score at least <tt>limit</tt> are reported.
     *
     * @return bool <tt>true</tt> indicates a match, <tt>false</tt> indicates no
     *              match.
     *
     * The function <tt>find</tT> successfully called be called - that is an end
     * position was found - before calling findBegin to find a begin position.
     *
     * @fn Finder::Finder
     *
     * @brief Constructor
     *
     * @signature Finder::Finder();
     * @signature Finder::Finder(other);
     * @signature Finder::Finder(haystack);
     * @signature Finder::Finder(iter);
     *
     * @param[in] other Other Finder of the same type (copy constructor).
     * @param[in] haystack The haystack to work on, of type <tt>THaystack</tt>.
     * @param[in] iter The iter to work on on, either const or non-const.
     */