/*!
* @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.
*
* @code{.cpp}
* CharString hstck = "I spy with my little eye something that is yellow";
* Finder<CharString> finder(hstck);
*
* Pattern<CharString, Horspool> p1("y");
* findAll(finder, p1);
*
* goBegin(finder); // move Finder to the beginning of the text
* clear(finder); // reset Finder
*
* Pattern<CharString, Horspool> p2("t");
* findAll(finder, p2);
* @endcode
* 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<THaystack, TSpec></tt>. This is an alias to
* function <tt>host()</tt> of the pattern function.
*
* @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.
*
* @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
* occurences 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#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><= 0</tt>. Differences are deletions,
* insertions, and substitutions.
*
* @return bool <tt>true</tt> if an occurence was found and <tt>false</tt> if
* not.
*
* Repeated calls of this function iterate through all occurences 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 befor 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 befor 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.
*/