/*!
* @class Lexical
*
* @headerfile <seqan/sequence.h>
*
* @brief Comparator for lexical comparison.
*
* @signature template <[typename TSpec]> class Lexical;
*
* @tparam TSpec The specializing size type, defaults to <tt>size_t</tt>.
*
* This class implement comparator objects that perform (lexical) comparisons
* between two sequences. The result of the comparison is stored in the data
* members of the instance and can be accessed by some functions, for example
* @link Lexical#isLess @endlink or @link Lexical#isEqual @endlink.
*
* In most cases, there is no need for an explicite use of comparators, but
* sometimes this concept provide the opportunity to speed up the code.
*
* @section Examples
*
* This program compares the strings <tt>str1</tt> and <tt>str2</tt>:
*
* @code{.cpp}
* if (isLess(str1, str2)) //first comparison
* {
* //str1 < str2
* }
* else if (isGreater(str1, str2)) //second comparison
* {
* //str1 > str2
* }
* else
* {
* //str == str2
* }
* @endcode
*
*
* Using a comparator, the same program only needs one comparison instead of
* two:
*
* @code{.cpp}
* Lexical <> comparator(str1, str2); //comparison is executed here
* if (isLess(comparator))
* {
* //str1 < str2
* }
* else if (lexGreater(comparator))
* {
* //str1 > str2
* }
* else
* {
* //str == str2
* }
* @endcode
*
*
* The state of a default constructed <tt>Lexical</tt> instance is undefined
* until it is set by a call of @link Lexical#compare @endlink.
*
* @see Comparator
*
* @fn Lexical#compare
*
* @headerfile <seqan/sequence.h>
*
* @brief Compares two objects.
*
* @signature void compare(comparator, left, right);
*
* @param[out] comparator Object that stores the results. Types: Lexical
* @param[in] left The first objects.
* @param[in] right The second objects that is compared to <tt>left</tt>.
*
* @see Comparator
*
* @fn Lexical#isEqual
*
* @headerfile <seqan/sequence.h>
*
* @brief Operator "==".
*
* @signature bool isEqual(left, right);
* @signature bool isEqual(comparator);
*
* @param[in] left The first parameter.
* @param[in] right The second parameter that is compared to <tt>left</tt>.
* @param[in] comparator A comparator. Types: Lexical
*
* @return bool <tt>true</tt> if <tt>left</tt> equals <tt>right</tt>,
* <tt>false</tt> otherwise.
*
* @fn Lexical#isNotEqual
*
* @headerfile <seqan/sequence.h>
*
* @brief Operator "!=".
*
* @signature bool isNotEqual(left, right);
* @signature bool isNotEqual(comparator);
*
* @param[in] left The first parameter.
* @param[in] right The second parameter that is compared to <tt>left</tt>.
* @param[in] comparator A comparator. Types: Lexical
*
* @return bool <tt>true</tt> if <tt>left</tt> does not equal <tt>right</tt>,
* <tt>false</tt> otherwise.
*
* @fn Lexical#isLess
*
* @headerfile <seqan/sequence.h>
*
* @brief Operator "<".
*
* @signature bool isLess(left, right);
* @signature bool isLess(comparator);
*
* @param[in] left The first parameter.
* @param[in] right The second parameter that is compared to <tt>left</tt>.
* @param[in] comparator A comparator. Types: Lexical
*
* @return bool <tt>true</tt> if <tt>left</tt> is less than <tt>right</tt>,
* <tt>false</tt> otherwise.
*
* @fn Lexical#isLessOrEqual
*
* @headerfile <seqan/sequence.h>
*
* @brief Operator "<=".
*
* @signature bool isLessOrEqual(left, right);
* @signature bool isLessOrEqual(comparator);
*
* @param[in] left The first parameter.
* @param[in] right The second parameter that is compared to <tt>left</tt>.
* @param[in] comparator A comparator. Types: Lexical
*
* @return bool <tt>true</tt> if <tt>left</tt> is less than or equal to
* <tt>right</tt>, <tt>false</tt> otherwise.
*
* @fn Lexical#isGreater
*
* @headerfile <seqan/sequence.h>
*
* @brief Operator ">".
*
* @signature bool isGreater(left, right);
* @signature bool isGreater(comparator);
*
* @param[in] left The first parameter.
* @param[in] right The second parameter that is compared to <tt>left</tt>.
* @param[in] comparator A comparator. Types: Lexical
*
* @return bool <tt>true</tt> if <tt>left</tt> is greater than <tt>right</tt>,
* <tt>false</tt> otherwise.
*
* @fn Lexical#isGreaterOrEqual
*
* @headerfile <seqan/sequence.h>
*
* @brief Operator ">=".
*
* @signature bool isGreaterOrEqual(left, right);
* @signature bool isGreaterOrEqual(comparator);
*
* @param[in] left The first parameter.
* @param[in] right The second parameter that is compared to <tt>left</tt>.
* @param[in] comparator A comparator. Types: Lexical
*
* @return bool <tt>true</tt> if <tt>left</tt> is greater than or equal to
* <tt>right</tt>, <tt>false</tt> otherwise.
*
* @fn Lexical#isPrefix
*
* @headerfile <seqan/sequence.h>
*
* @brief Test whether a sequence is the prefix of another sequence.
*
* @signature bool isPrefix(left, right);
* @signature bool isPrefix(comparator);
*
* @param[in] left The putative prefix.
* @param[in] right The second sequence.
* @param[in] comparator A comparator. Types: Lexical
*
* @return bool <tt>true</tt> if <tt>left</tt> is a prefix of<tt>right</tt>,
* <tt>false</tt> otherwise.
*
* By definition, a sequence is a prefix of itself: <tt>isPrefix("abc",
* "abc")</tt> is <tt>true</tt>.
*
* @fn Lexical#hasPrefix
*
* @headerfile <seqan/sequence.h>
*
* @brief Test whether a sequence is the prefix of another sequence.
*
* @signature bool isPrefix(left, right);
* @signature bool isPrefix(comparator);
*
* @param[in] left The first sequence.
* @param[in] right The putative prefix.
* @param[in] comparator A comparator. Types: Lexical
*
* @return bool <tt>true</tt> if <tt>left</tt> is a prefix of<tt>right</tt>,
* <tt>false</tt> otherwise.
*
* By definition, a sequence is a prefix of itself: <tt>hasPrefix("abc",
* "abc")</tt> is <tt>true</tt>.
*
* @fn Lexical#lcpLength
*
* @headerfile <seqan/sequence.h>
*
* @brief Length of the longest common prefix.
*
* @signature TSize lcpLength(left, right);
* @signature TSize lcpLength(comparator);
*
* @param[in] left The first sequence.
* @param[in] right The second sequence.
* @param[in] comparator A comparator. Types: Lexical
*
* @return TSize The length of the longest common prefix of <tt>left</tt> and
* <tt>right</tt>. TSize is the Size type of the left size type.
*
* By definition, a sequence is a prefix of itself: <tt>hasPrefix("abc",
* "abc")</tt> is <tt>true</tt>.
*/