Concept Checking - SeqAn API Documentation

# Group Concept Checking
Macros for the concept checking system in SeqAn.

## Grouped Macros Overview

`SEQAN_CONCEPT(name, params)` Defines a new concept.
`SEQAN_CONCEPT_ASSERT((concept))` Perform a concept check.
`template<> // required, even if name has no template arguments SEQAN_CONCEPT_IMPL((name), implementedConcepts)` Defines which concepts a model fulfills.
`SEQAN_CONCEPT_REFINE(name, params, refinedConcepts)` Defines a new concept as a refinement of existing concepts.
`SEQAN_CONCEPT_USAGE(name)` Defines valid expressions.

## Grouped Function Overview

- `void requireBooleanExpr(x);`
  Tests for a boolean expression.
- `void sameType(x, y);`
  Tests for equality of types.

## Detailed Description

SeqAn's concept checking system is copied from Boost. The license for the library is as follows:

    // Copyright David Abrahams 2006. Distributed under the Boost Software
    // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
    // http://www.boost.org/LICENSE_1_0.txt).

## Grouped Macros Detail

### ConceptChecking#SEQAN_CONCEPT

Defined in
  <seqan/basic.h>

`SEQAN_CONCEPT(name, params)`
Defines a new concept.

Parameters
  `params` - Template paramter list in parantheses, e.g. (T) or (T1)(T2). Typically, template parameters are models, i.e. one or multiple classes that should be checked for fulfilling a concept.This is a sequence of the Boost Preprocessor Library, read more.
  `name` - Concept identifier. Non-trivial concepts should have an identifier with a Concept-suffix.
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
See Also
  SEQAN_CONCEPT_USAGE

A concept is implemented as a template struct with name `name` and arguments `params`. The concept checking should be part of the struct definition. Associated types should be checked via SEQAN_CONCEPT_ASSERT and valid expressions in a function SEQAN_CONCEPT_USAGE, see below. Variables used in valid expressions should be (private) struct members instead of local variables in member functions (read more.

#### Examples

    SEQAN_CONCEPT(Assignable,(T))
    {
        SEQAN_CONCEPT_USAGE(Assignable)
        {
            a = b;              // require assignment operator
            constConstraints(b);
        }
    private:
        void constConstraints(const T& x)
        {
            a = x;              // const required for argument to assignment
            ignoreUnusedVariableWarning(x);
        }
    private:
        T a;
        T b;
    };

    SEQAN_CONCEPT(EqualityComparable,(T))
    {
        SEQAN_CONCEPT_USAGE(EqualityComparable)
        {
            requireBooleanExpr(a == b);
            requireBooleanExpr(a != b);
        }
    private:
        T a, b;
    };

### ConceptChecking#SEQAN_CONCEPT_ASSERT

Defined in
  <seqan/basic.h>

`SEQAN_CONCEPT_ASSERT((concept))`
Perform a concept check.

Parameters
  `concept` - Concept specialized with a the type that should be checked.
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
See Also
  Is

This macro is a compile-time assertion and requires the concept specialized with the tested types to compile. The check neither consumes memory nor running time. The macro can be used at the beginning of a function or within a struct/class definition. The checked concepts should be as restrictive and generic as possible to on the one hand cover all used functionality and on the other hand not limit the applicability of a function/class.

#### Examples

    typedef typename Value<TContainer>::Type                TValue;
    typedef typename Position<TContainer>::Type             TPosition;
    typedef typename Difference<TContainer>::Type           TDifference;

    SEQAN_CONCEPT_ASSERT((AlphabetConcept<TValue>));
    SEQAN_CONCEPT_ASSERT((SignedIntegerConcept<TDifference>));
    SEQAN_CONCEPT_ASSERT((UnsignedIntegerConcept<TSize>));

### ConceptChecking#SEQAN_CONCEPT_IMPL

Defined in
  <seqan/basic.h>

`template<> // required, even if name has no template arguments SEQAN_CONCEPT_IMPL((name), implementedConcepts)`
Defines which concepts a model fulfills.

Parameters
  `implementedConcepts` - Identifiers of concepts that are fulfilled by the model. This is a sequence of the Boost Preprocessor Library, read more.
  `name` - Model type, i.e. an identifier or an identifier with template arguments.
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

template<typename T, int I> SEQAN_CONCEPT_IMPL((name<T,I>), implementedConcepts)

The metafunction Is can be used to determine whether a class models (fulfills) a concepts. A model of a concept must pass the concept check via SEQAN_CONCEPT_ASSERT.

#### Examples

    template <typename TValue, typename TSpec>
    SEQAN_CONCEPT_IMPL((String<TValue, TSpec>), (StringConcept));

### ConceptChecking#SEQAN_CONCEPT_REFINE

Defined in
  <seqan/basic.h>

`SEQAN_CONCEPT_REFINE(name, params, refinedConcepts)`
Defines a new concept as a refinement of existing concepts.

Parameters
  `params` - Template parameter list in parantheses, e.g. (T) or (T1)(T2). Typically, template parameters are models, i.e. one or multiple classes that should be checked for fulfilling a concept.This is a sequence of the Boost Preprocessor Library, read more.
  `name` - Concept identifier. Non-trivial concepts should have an identifier with a Concept-suffix.
  `refinedConcepts` - Identifiers of concepts that are refined by the new concept.Refined concepts are implicitly integrated into the requirements of the new concept.This is a sequence of the Boost Preprocessor Library, read more
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
See Also
  SEQAN_CONCEPT_USAGE

A concept is implemented as a template struct with name `name` and arguments `params`. The struct inherits all refined concept structs. The concept checking should be part of the struct definition. For more information, see SEQAN_CONCEPT.

#### Examples

    SEQAN_CONCEPT_REFINE(AlphabetConcept, (TValue), (Assignable)(DefaultConstructible)(CopyConstructible))
    {
        TValue val, val2;

        SEQAN_CONCEPT_USAGE(AlphabetConcept)
        {
            assign(val, val2);
        }
    };

### ConceptChecking#SEQAN_CONCEPT_USAGE

Defined in
  <seqan/basic.h>

`SEQAN_CONCEPT_USAGE(name)`
Defines valid expressions.

Parameters
  `name` (in) - Identifier of the concept defined with SEQAN_CONCEPT or SEQAN_CONCEPT_REFINE.
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
See Also
  SEQAN_CONCEPT
  SEQAN_CONCEPT_REFINE
  requireBooleanExpr

This macro should be used to introduce a block (enclosed with curly braces) of valid expressions within a newly defined concept. Valid expressions should test for available functions, operators and the correctness of return types. Use helper functions, e.g. ignoreUnusedVariableWarning, requireBooleanExpr and sameType.

#### Examples

    SEQAN_CONCEPT(EqualityComparable,(T))
    {
        SEQAN_CONCEPT_USAGE(EqualityComparable)
        {
            requireBooleanExpr(a == b);
            requireBooleanExpr(a != b);
        }
    private:
        T a, b;
    };

## Grouped Functions Detail

### `void requireBooleanExpr(x);`

Defined in
  <seqan/basic.h>

Tests for a boolean expression.

#### Parameters

`x` | Object that must be convertible to `bool`

This function can be used to test for functions returning bools, e.g. less operators.

#### Data Races

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

#### See Also

- SEQAN_CONCEPT_USAGE

### `void sameType(x, y);`

Tests for equality of types.

#### Parameters

`x` | Object of a certain type.
`y` | Object that must be of the same type.

This function can be used to test for the correctness of function return types or the type of an expression in concept tests.

#### Data Races

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

#### See Also

- SEQAN_CONCEPT_USAGE

#### Dox Sources

    /*!
     * @defgroup ConceptChecking Concept Checking
     *
     * @brief Macros for the concept checking system in SeqAn.
     *
     * SeqAn's concept checking system is copied from Boost. The license for the
     * library is as follows:
     *
     * @code{.cpp}
     * // Copyright David Abrahams 2006. Distributed under the Boost Software
     * // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
     * // http://www.boost.org/LICENSE_1_0.txt).
     * @endcode
     *
     *
     * @macro ConceptChecking#SEQAN_CONCEPT_ASSERT
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Perform a concept check.
     *
     * @signature SEQAN_CONCEPT_ASSERT((concept))
     *
     * @param concept Concept specialized with a the type that should be checked.
     *
     * This macro is a compile-time assertion and requires the concept specialized
     * with the tested types to compile. The check neither consumes memory nor
     * running time. The macro can be used at the beginning of a function or within
     * a struct/class definition. The checked concepts should be as restrictive and
     * generic as possible to on the one hand cover all used functionality and on
     * the other hand not limit the applicability of a function/class.
     *
     * @section Examples
     *
     * @code{.cpp}
     * typedef typename Value<TContainer>::Type                TValue;
     * typedef typename Position<TContainer>::Type             TPosition;
     * typedef typename Difference<TContainer>::Type           TDifference;
     *
     * SEQAN_CONCEPT_ASSERT((AlphabetConcept<TValue>));
     * SEQAN_CONCEPT_ASSERT((SignedIntegerConcept<TDifference>));
     * SEQAN_CONCEPT_ASSERT((UnsignedIntegerConcept<TSize>));
     * @endcode
     *
     *
     * @see Is
     *
     * @macro ConceptChecking#SEQAN_CONCEPT_USAGE
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Defines valid expressions.
     *
     * @signature SEQAN_CONCEPT_USAGE(name)
     *
     * @param[in] name Identifier of the concept defined with @link
     *                 ConceptChecking#SEQAN_CONCEPT @endlink or @link
     *                 ConceptChecking#SEQAN_CONCEPT_REFINE @endlink.
     *
     * This macro should be used to introduce a block (enclosed with curly braces)
     * of valid expressions within a newly defined concept. Valid expressions should
     * test for available functions, operators and the correctness of return types.
     * Use helper functions, e.g. @link ignoreUnusedVariableWarning @endlink, @link
     * ConceptChecking#requireBooleanExpr @endlink and @link
     * ConceptChecking#sameType @endlink.
     *
     * @section Examples
     *
     * @code{.cpp}
     * SEQAN_CONCEPT(EqualityComparable,(T))
     * {
     *     SEQAN_CONCEPT_USAGE(EqualityComparable)
     *     {
     *         requireBooleanExpr(a == b);
     *         requireBooleanExpr(a != b);
     *     }
     * private:
     *     T a, b;
     * };
     * @endcode
     *
     *
     * @see ConceptChecking#requireBooleanExpr
     * @see ConceptChecking#SEQAN_CONCEPT
     * @see ConceptChecking#SEQAN_CONCEPT_REFINE
     *
     * @macro ConceptChecking#SEQAN_CONCEPT
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Defines a new concept.
     *
     * @signature SEQAN_CONCEPT(name, params)
     *
     * @param params Template paramter list in parantheses, e.g. (T) or (T1)(T2).
     *               Typically, template parameters are models, i.e. one or multiple
     *               classes that should be checked for fulfilling a concept.This is
     *               a sequence of the Boost Preprocessor Library, read <a
     *               href="http://www.boost.org/doc/libs/1_47_0/libs/preprocessor/do
     *               c/index.html">more</a>.
     * @param name Concept identifier. Non-trivial concepts should have an
     *             identifier with a Concept-suffix.
     *
     * A concept is implemented as a template struct with name <tt>name</tt> and
     * arguments <tt>params</tt>. The concept checking should be part of the struct
     * definition. Associated types should be checked via @link
     * ConceptChecking#SEQAN_CONCEPT_ASSERT @endlink and valid expressions in a
     * function @link ConceptChecking#SEQAN_CONCEPT_USAGE @endlink, see below.
     * Variables used in valid expressions should be (private) struct members
     * instead of local variables in member functions (read <a href="http://www.boos
     * t.org/doc/libs/1_47_0/libs/concept_check/creating_concepts.htm">more</a>.
     *
     * @section Examples
     *
     * @code{.cpp}
     * SEQAN_CONCEPT(Assignable,(T))
     * {
     *     SEQAN_CONCEPT_USAGE(Assignable)
     *     {
     *         a = b;              // require assignment operator
     *         constConstraints(b);
     *     }
     * private:
     *     void constConstraints(const T& x)
     *     {
     *         a = x;              // const required for argument to assignment
     *         ignoreUnusedVariableWarning(x);
     *     }
     * private:
     *     T a;
     *     T b;
     * };
     *
     * SEQAN_CONCEPT(EqualityComparable,(T))
     * {
     *     SEQAN_CONCEPT_USAGE(EqualityComparable)
     *     {
     *         requireBooleanExpr(a == b);
     *         requireBooleanExpr(a != b);
     *     }
     * private:
     *     T a, b;
     * };
     * @endcode
     *
     *
     * @see ConceptChecking#SEQAN_CONCEPT_USAGE
     *
     * @macro ConceptChecking#SEQAN_CONCEPT_REFINE
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Defines a new concept as a refinement of existing concepts.
     *
     * @signature SEQAN_CONCEPT_REFINE(name, params, refinedConcepts)
     *
     * @param params Template parameter list in parantheses, e.g. (T) or (T1)(T2).
     *               Typically, template parameters are models, i.e. one or multiple
     *               classes that should be checked for fulfilling a concept.This is
     *               a sequence of the Boost Preprocessor Library, read <a
     *               href="http://boost.org/doc/libs/1_47_0/libs/preprocessor/doc/in
     *               dex.html">more</a>.
     * @param name Concept identifier. Non-trivial concepts should have an
     *             identifier with a Concept-suffix.
     * @param refinedConcepts Identifiers of concepts that are refined by the new
     *                        concept.Refined concepts are implicitly integrated
     *                        into the requirements of the new concept.This is a
     *                        sequence of the Boost Preprocessor Library, read <a hr
     *                        ef="http://boost.org/doc/libs/1_47_0/libs/preprocessor
     *                        /doc/index.html">more</a>
     *
     * A concept is implemented as a template struct with name <tt>name</tt> and
     * arguments <tt>params</tt>. The struct inherits all refined concept structs.
     * The concept checking should be part of the struct definition. For more
     * information, see @link ConceptChecking#SEQAN_CONCEPT @endlink.
     *
     * @section Examples
     *
     * @code{.cpp}
     * SEQAN_CONCEPT_REFINE(AlphabetConcept, (TValue), (Assignable)(DefaultConstructible)(CopyConstructible))
     * {
     *     TValue val, val2;
     *
     *     SEQAN_CONCEPT_USAGE(AlphabetConcept)
     *     {
     *         assign(val, val2);
     *     }
     * };
     * @endcode
     *
     *
     * @see ConceptChecking#SEQAN_CONCEPT_USAGE
     *
     * @macro ConceptChecking#SEQAN_CONCEPT_IMPL
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Defines which concepts a model fulfills.
     *
     * @signature template<> // required, even if name has no template arguments
     *            SEQAN_CONCEPT_IMPL((name), implementedConcepts)
     *
     * @param implementedConcepts Identifiers of concepts that are fulfilled by the
     *                            model. This is a sequence of the Boost
     *                            Preprocessor Library, read <a
     *                            href="http://www.boost.org/doc/libs/1_47_0/libs/pr
     *                            eprocessor/doc/index.html">more</a>.
     * @param name Model type, i.e. an identifier or an identifier with template
     *             arguments.
     *
     * template<typename T, int I> SEQAN_CONCEPT_IMPL((name<T,I>),
     * implementedConcepts)
     *
     * The metafunction @link Is @endlink can be used to determine whether a class
     * models (fulfills) a concepts. A model of a concept must pass the concept
     * check via @link ConceptChecking#SEQAN_CONCEPT_ASSERT @endlink.
     *
     * @section Examples
     *
     * @code{.cpp}
     * template <typename TValue, typename TSpec>
     * SEQAN_CONCEPT_IMPL((String<TValue, TSpec>), (StringConcept));
     * @endcode
     *
     *
     * @fn ConceptChecking#sameType
     *
     * @brief Tests for equality of types.
     *
     * @signature void sameType(x, y);
     *
     * @param[in] x Object of a certain type.
     * @param[in] y Object that must be of the same type.
     *
     * This function can be used to test for the correctness of function return
     * types or the type of an expression in concept tests.
     *
     * @see ConceptChecking#SEQAN_CONCEPT_USAGE
     *
     * @fn ConceptChecking#requireBooleanExpr
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Tests for a boolean expression.
     *
     * @signature void requireBooleanExpr(x);
     *
     * @param[in] x Object that must be convertible to <tt>bool</tt>
     *
     * This function can be used to test for functions returning bools, e.g. less
     * operators.
     *
     * @see ConceptChecking#SEQAN_CONCEPT_USAGE
     */