Lexical - SeqAn API Documentation

# Class Lexical
Comparator for lexical comparison.

Defined in | <seqan/sequence.h>
Signature | `template <[typename TSpec]> class Lexical;`

## Template Parameters

`TSpec` | The specializing size type, defaults to `size_t`.

## Interface Function Overview

- `void compare(comparator, left, right);`
  Compares two objects.
- `bool isPrefix(left, right);, bool isPrefix(comparator);`
  Test whether a sequence is the prefix of another sequence.
- `bool isEqual(left, right);, bool isEqual(comparator);`
  Operator "==".
- `bool isGreater(left, right);, bool isGreater(comparator);`
  Operator ">".
- `bool isGreaterOrEqual(left, right);, bool isGreaterOrEqual(comparator);`
  Operator ">=".
- `bool isLess(left, right);, bool isLess(comparator);`
  Operator "<".
- `bool isLessOrEqual(left, right);, bool isLessOrEqual(comparator);`
  Operator "<=".
- `bool isNotEqual(left, right);, bool isNotEqual(comparator);`
  Operator "!=".
- `bool isPrefix(left, right);, bool isPrefix(comparator);`
  Test whether a sequence is the prefix of another sequence.
- `TSize lcpLength(left, right);, TSize lcpLength(comparator);`
  Length of the longest common prefix.

## Detailed Description

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 isLess or isEqual.

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.

### Examples

This program compares the strings `str1` and `str2`:

    if (isLess(str1, str2)) //first comparison
    {
        //str1 < str2
    }
    else if (isGreater(str1, str2)) //second comparison
    {
        //str1 > str2
    }
    else
    {
        //str == str2
    }

Using a comparator, the same program only needs one comparison instead of two:

    Lexical <> comparator(str1, str2); //comparison is executed here
    if (isLess(comparator))
    {
        //str1 < str2
    }
    else if (lexGreater(comparator))
    {
        //str1 > str2
    }
    else
    {
        //str == str2
    }

The state of a default constructed `Lexical` instance is undefined until it is set by a call of compare.

## See Also

- Comparator

## Interface Functions Detail

### `void compare(comparator, left, right);`

Compares two objects.

#### Parameters

`comparator` | Object that stores the results. Types: Lexical
`left` | The first objects.
`right` | The second objects that is compared to `left`.

#### Data Races

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

#### See Also

- Comparator

### `bool isPrefix(left, right); bool isPrefix(comparator);`

Test whether a sequence is the prefix of another sequence.

#### Parameters

`left` | The first sequence.
`right` | The putative prefix.
`comparator` | A comparator. Types: Lexical

#### Returns

`bool` | `true` if `left` is a prefix of`right`, `false` otherwise.

By definition, a sequence is a prefix of itself: `hasPrefix("abc", "abc")` is `true`.

#### Data Races

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

### `bool isEqual(left, right); bool isEqual(comparator);`

Operator "==".

#### Parameters

`left` | The first parameter.
`right` | The second parameter that is compared to `left`.
`comparator` | A comparator. Types: Lexical

#### Returns

`bool` | `true` if `left` equals `right`, `false` otherwise.

#### Data Races

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

### `bool isGreater(left, right); bool isGreater(comparator);`

Operator ">".

#### Parameters

`left` | The first parameter.
`right` | The second parameter that is compared to `left`.
`comparator` | A comparator. Types: Lexical

#### Returns

`bool` | `true` if `left` is greater than `right`, `false` otherwise.

#### Data Races

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

### `bool isGreaterOrEqual(left, right); bool isGreaterOrEqual(comparator);`

Operator ">=".

#### Parameters

`left` | The first parameter.
`right` | The second parameter that is compared to `left`.
`comparator` | A comparator. Types: Lexical

#### Returns

`bool` | `true` if `left` is greater than or equal to `right`, `false` otherwise.

#### Data Races

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

### `bool isLess(left, right); bool isLess(comparator);`

Operator "<".

#### Parameters

`left` | The first parameter.
`right` | The second parameter that is compared to `left`.
`comparator` | A comparator. Types: Lexical

#### Returns

`bool` | `true` if `left` is less than `right`, `false` otherwise.

#### Data Races

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

### `bool isLessOrEqual(left, right); bool isLessOrEqual(comparator);`

Operator "<=".

#### Parameters

`left` | The first parameter.
`right` | The second parameter that is compared to `left`.
`comparator` | A comparator. Types: Lexical

#### Returns

`bool` | `true` if `left` is less than or equal to `right`, `false` otherwise.

#### Data Races

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

### `bool isNotEqual(left, right); bool isNotEqual(comparator);`

Operator "!=".

#### Parameters

`left` | The first parameter.
`right` | The second parameter that is compared to `left`.
`comparator` | A comparator. Types: Lexical

#### Returns

`bool` | `true` if `left` does not equal `right`, `false` otherwise.

#### Data Races

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

### `bool isPrefix(left, right); bool isPrefix(comparator);`

Test whether a sequence is the prefix of another sequence.

#### Parameters

`left` | The putative prefix.
`right` | The second sequence.
`comparator` | A comparator. Types: Lexical

#### Returns

`bool` | `true` if `left` is a prefix of`right`, `false` otherwise.

By definition, a sequence is a prefix of itself: `isPrefix("abc", "abc")` is `true`.

#### Data Races

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

### `TSize lcpLength(left, right); TSize lcpLength(comparator);`

Length of the longest common prefix.

#### Parameters

`left` | The first sequence.
`right` | The second sequence.
`comparator` | A comparator. Types: Lexical

#### Returns

`TSize` | The length of the longest common prefix of `left` and `right`. TSize is the Size type of the left size type.

By definition, a sequence is a prefix of itself: `hasPrefix("abc", "abc")` is `true`.

#### Data Races

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

#### Dox Sources

    /*!
     * @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 "&lt;".
     *
     * @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 "&lt;=".
     *
     * @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 "&gt;".
     *
     * @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 "&gt;=".
     *
     * @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>.
     */