Enable-If Functionality - SeqAn API Documentation

# Group Enable-If Functionality
The metafunctions and macros for enabling/disabling of functions.

## Grouped Macros Overview

`SEQAN_CTOR_DISABLE_IF(TCondition);` Bind the visibility of a constructor to an expression.
`SEQAN_CTOR_ENABLE_IF(TCondition);` Bind the visibility of a constructor to an expression.
`SEQAN_FUNC_DISABLE_IF(TCondition, TResult);` Bind the visibility of a function to an expression.
`SEQAN_FUNC_ENABLE_IF(TCondition, TResult);` Bind the visibility of a function to an expression.

## Grouped Metafunction Overview

- `DisableIf<TBool, T = void>::Type`
  Metafunction to use for conditionally disabling code.
- `DisableIf2<BOOL, T = void>::Type`
  Metafunction to use for conditionally disabling code, bool version.
- `EnableIf<TBool, T = void>::Type`
  Metafunction to use for conditionally enabling code.
- `EnableIf2<BOOL, T = void>::Type`
  Metafunction to use for conditionally enabling code, bool version.

## Detailed Description

The `EnableIf` metafunctions also support the shortcut to `::Type` members as described for the logical metaprogramming metafunctions.

Enable-if is an advanced technique and mostly interesting if you want to extend the SeqAn library with generic algorithms. The average developer does not have to know about this technique..

## See Also

- LogicMetaprogramming
- LogicalValuesTags

## Grouped Macros Detail

### EnableIfFunctionality#SEQAN_CTOR_DISABLE_IF

Defined in
  <seqan/basic.h>

`SEQAN_CTOR_DISABLE_IF(TCondition);`
Bind the visibility of a constructor to an expression.

Parameters
  `TCondition` - Boolean type, one of `True` and `False` or a metafunction returning such a tag type. If `False` then the constructor is visible, otherwise, it is not.
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

This macro allows one to bind the visibility of a construtor to a boolean expression by using the SFINAE principle for an optional argument with default value. The macro call must be used as the last dummy-argument of a constructor.

To avoid an unused argument warning, call `ignoreUnusedVariableWarning(dummy)` in the constructor's body.

Important: The constructor to disable must be a function template and `TCondition` must include at least one template parameter of the function template.

#### Example

The following shows an example on how to properly use `SEQAN_CTOR_DISABLE_IF` as the last argument to the constructor and suppressing the unused variable warning for the dummy parameter.

        template <typename T>
        EnableIfExample(T const & n, SEQAN_CTOR_DISABLE_IF(Is<IntegerConcept<T> >)) :
            num(0)
        {
            ignoreUnusedVariableWarning(dummy);
        }

Snippet from: demos/dox/basic/enable_if.cpp

### EnableIfFunctionality#SEQAN_CTOR_ENABLE_IF

Defined in
  <seqan/basic.h>

`SEQAN_CTOR_ENABLE_IF(TCondition);`
Bind the visibility of a constructor to an expression.

Parameters
  `TCondition` - Boolean type, one of `True` and `False` or a metafunction returning such a tag type. If `True` then the constructor is visible, otherwise, it is not.
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

This macro allows one to bind the visibility of a construtor to a boolean expression by using the SFINAE principle for an optional argument with default value. The macro call must be used as the last dummy-argument of a constructor.

To avoid an unused argument warning, call `ignoreUnusedVariableWarning(dummy)` in the constructor's body.

Important: The constructor to enable must be a function template and `TCondition` must include at least one template parameter of the function template.

#### Example

The following shows an example on how to properly use `SEQAN_CTOR_ENABLE_IF` as the last argument to the constructor and suppressing the unused variable warning for the dummy parameter.

        template <typename T>
        EnableIfExample(T const & n, SEQAN_CTOR_ENABLE_IF(Is<IntegerConcept<T> >)) :
            num(0)
        {
            ignoreUnusedVariableWarning(dummy);
        }

Snippet from: demos/dox/basic/enable_if.cpp

### EnableIfFunctionality#SEQAN_FUNC_DISABLE_IF

Defined in
  <seqan/basic.h>

`SEQAN_FUNC_DISABLE_IF(TCondition, TResult);`
Bind the visibility of a function to an expression.

Parameters
  `TCondition` - Boolean type, one of `True` and `False` or a metafunction returning such a tag type. If `False` then the function is visible, otherwise, it is not.
  `TResult` - The type that the function should have as the return type in case it is enabled.
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

This macro allows one to bind the visibility of a construtor to a boolean expression by using the SFINAE principle for an optional argument with default value. The macro call must occur as the return type definition of the function.

To avoid an unused argument warning, call `ignoreUnusedVariableWarning(dummy)` in the constructor's body.

Important: The function to disable must be a function template and `TCondition` must include at least one template parameter of the function template.

#### Example

The following shows an example on how to properly use `SEQAN_FUNC_DISABLE_IF` as the last argument to the constructor and suppressing the unused variable warning for the dummy parameter.

        template <typename T>
        SEQAN_FUNC_DISABLE_IF(Is<IntegerConcept<T> >)
        f(T /* x */)
        { /* ... */}

Snippet from: demos/dox/basic/enable_if.cpp

### EnableIfFunctionality#SEQAN_FUNC_ENABLE_IF

Defined in
  <seqan/basic.h>

`SEQAN_FUNC_ENABLE_IF(TCondition, TResult);`
Bind the visibility of a function to an expression.

Parameters
  `TCondition` - Boolean type, one of `True` and `False` or a metafunction returning such a tag type. If `True` then the function is visible, otherwise, it is not.
  `TResult` - The type that the function should have as the return type in case it is enabled.
Data Races
  If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

This macro allows one to bind the visibility of a construtor to a boolean expression by using the SFINAE principle for an optional argument with default value. The macro call must occur as the return type definition of the function.

To avoid an unused argument warning, call `ignoreUnusedVariableWarning(dummy)` in the constructor's body.

Important: The function to enable must be a function template and `TCondition` must include at least one template parameter of the function template.

#### Example

The following shows an example on how to properly use `SEQAN_FUNC_ENABLE_IF` as the last argument to the constructor and suppressing the unused variable warning for the dummy parameter.

        template <typename T>
        SEQAN_FUNC_ENABLE_IF(Is<IntegerConcept<T> >)
        f(T /* x */)
        { /* ... */ }

Snippet from: demos/dox/basic/enable_if.cpp

## Grouped Metafunctions Detail

### `DisableIf<TBool, T = void>::Type`

Defined in
  <seqan/basic.h>

Metafunction to use for conditionally disabling code.

#### Template Parameters

`TBool` | The Tag `True` or `False` to use for enabling/disabling.
`T` | Dummy, do not set.

#### Returns

`Type` | Set to `T`. Only defined if `TBool` is `False`. This triggers the SFINAE behaviour in C++ which can be used to enable/disable functions.

Do not use directly but use through the enable if/disable if macros.

### `DisableIf2<BOOL, T = void>::Type`

Defined in
  <seqan/basic.h>

Deprecated.

Will be renamed to DisableIfC.

Metafunction to use for conditionally disabling code, bool version.

#### Template Parameters

`BOOL` | The `bool` constant to evaluate for enabling/disabling.
`T` | Dummy, do not set.

#### Returns

`Type` | Set to `T`. Only defined if `BOOL` is `false`. This triggers the SFINAE behaviour in C++ which can be used to enable/disable functions.

Do not use directly but use through the enable if/disable if macros.

### `EnableIf<TBool, T = void>::Type`

Defined in
  <seqan/basic.h>

Metafunction to use for conditionally enabling code.

#### Template Parameters

`TBool` | The Tag `True` or `False` to use for enabling/disabling.
`T` | Dummy, do not set.

#### Returns

`Type` | Set to `T`. Only defined if `TBool` is `True`. This triggers the SFINAE behaviour in C++ which can be used to enable/disable functions.

Do not use directly but use through the enable if/disable if macros.

### `EnableIf2<BOOL, T = void>::Type`

Defined in
  <seqan/basic.h>

Deprecated.

Will be renamed to EnableIfC.

Metafunction to use for conditionally enabling code, bool version.

#### Template Parameters

`BOOL` | The `bool` constant to evaluate for enabling/disabling.
`T` | Dummy, do not set.

#### Returns

`Type` | Set to `T`. Only defined if `BOOL` is `true`. This triggers the SFINAE behaviour in C++ which can be used to enable/disable functions.

Do not use directly but use through the enable if/disable if macros.

#### Dox Sources

    /*!
     * @defgroup EnableIfFunctionality Enable-If Functionality
     *
     * @brief The metafunctions and macros for enabling/disabling of functions.
     *
     * The <tt>EnableIf</tt> metafunctions also support the shortcut to
     * <tt>::Type</tt> members as described for the @link LogicMetaprogramming
     * logical metaprogramming metafunctions @endlink.
     *
     * <b>Enable-if is an advanced technique and mostly interesting if you want to
     * extend the SeqAn library with generic algorithms. The average developer does
     * not have to know about this technique.</b>.
     *
     * @see LogicalValuesTags
     * @see LogicMetaprogramming
     *
     * @mfn EnableIfFunctionality#EnableIf
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Metafunction to use for conditionally enabling code.
     *
     * @signature EnableIf<TBool, T = void>::Type
     *
     * @tparam TBool The Tag <tt>True</tt> or <tt>False</tt> to use for
     *               enabling/disabling.
     * @tparam T Dummy, do not set.
     *
     * @return Type Set to <tt>T</tt>. Only defined if <tt>TBool</tt> is
     *              <tt>True</tt>. This triggers the SFINAE behaviour in C++ which
     *              can be used to enable/disable functions.
     *
     * Do not use directly but use through the enable if/disable if macros.
     *
     * @see EnableIfFunctionality#SEQAN_FUNC_ENABLE_IF
     * @see EnableIfFunctionality#SEQAN_FUNC_DISABLE_IF
     * @see EnableIfFunctionality#SEQAN_CTOR_ENABLE_IF
     * @see EnableIfFunctionality#SEQAN_CTOR_DISABLE_IF
     *
     * @mfn EnableIfFunctionality#DisableIf
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Metafunction to use for conditionally disabling code.
     *
     * @signature DisableIf<TBool, T = void>::Type
     *
     * @tparam TBool The Tag <tt>True</tt> or <tt>False</tt> to use for
     *               enabling/disabling.
     * @tparam T Dummy, do not set.
     *
     * @return Type Set to <tt>T</tt>. Only defined if <tt>TBool</tt> is
     *              <tt>False</tt>. This triggers the SFINAE behaviour in C++ which
     *              can be used to enable/disable functions.
     *
     * Do not use directly but use through the enable if/disable if macros.
     *
     * @see EnableIfFunctionality#SEQAN_FUNC_ENABLE_IF
     * @see EnableIfFunctionality#SEQAN_FUNC_DISABLE_IF
     * @see EnableIfFunctionality#SEQAN_CTOR_ENABLE_IF
     * @see EnableIfFunctionality#SEQAN_CTOR_DISABLE_IF
     *
     * @mfn EnableIfFunctionality#EnableIf2
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Metafunction to use for conditionally enabling code, bool version.
     *
     * @deprecated Will be renamed to EnableIfC.
     *
     * @signature EnableIf2<BOOL, T = void>::Type
     *
     * @tparam BOOL The <tt>bool</tt> constant to evaluate for enabling/disabling.
     * @tparam T Dummy, do not set.
     *
     * @return Type Set to <tt>T</tt>. Only defined if <tt>BOOL</tt> is
     *              <tt>true</tt>. This triggers the SFINAE behaviour in C++ which
     *              can be used to enable/disable functions.
     *
     * Do not use directly but use through the enable if/disable if macros.
     *
     * @see EnableIfFunctionality#SEQAN_FUNC_ENABLE_IF
     * @see EnableIfFunctionality#SEQAN_FUNC_DISABLE_IF
     * @see EnableIfFunctionality#SEQAN_CTOR_ENABLE_IF
     * @see EnableIfFunctionality#SEQAN_CTOR_DISABLE_IF
     *
     * @mfn EnableIfFunctionality#DisableIf2
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Metafunction to use for conditionally disabling code, bool version.
     *
     * @deprecated Will be renamed to DisableIfC.
     *
     * @signature DisableIf2<BOOL, T = void>::Type
     *
     * @tparam BOOL The <tt>bool</tt> constant to evaluate for enabling/disabling.
     * @tparam T Dummy, do not set.
     *
     * @return Type Set to <tt>T</tt>. Only defined if <tt>BOOL</tt> is
     *              <tt>false</tt>. This triggers the SFINAE behaviour in C++ which
     *              can be used to enable/disable functions.
     *
     * Do not use directly but use through the enable if/disable if macros.
     *
     * @see EnableIfFunctionality#SEQAN_FUNC_ENABLE_IF
     * @see EnableIfFunctionality#SEQAN_FUNC_DISABLE_IF
     * @see EnableIfFunctionality#SEQAN_CTOR_ENABLE_IF
     * @see EnableIfFunctionality#SEQAN_CTOR_DISABLE_IF
     *
     * @macro EnableIfFunctionality#SEQAN_CTOR_ENABLE_IF
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Bind the visibility of a constructor to an expression.
     *
     * @signature SEQAN_CTOR_ENABLE_IF(TCondition);
     *
     * @param TCondition Boolean type, one of <tt>True</tt> and <tt>False</tt> or a
     *                   metafunction returning such a tag type. If <tt>True</tt>
     *                   then the constructor is visible, otherwise, it is not.
     *
     * This macro allows one to bind the visibility of a construtor to a boolean
     * expression by using the <a href="http://en.wikipedia.org/wiki/Substitution_fa
     * ilure_is_not_an_error">SFINAE</a> principle for an optional argument with
     * default value. The macro call must be used as the last dummy-argument of a
     * constructor.
     *
     * To avoid an unused argument warning, call
     * <tt>ignoreUnusedVariableWarning(dummy)</tt> in the constructor's body.
     *
     * <b>Important:</b> The constructor to enable must be a function template and
     * <tt>TCondition</tt> must include at least one template parameter of the
     * function template.
     *
     * @section Example
     *
     * The following shows an example on how to properly use
     * <tt>SEQAN_CTOR_ENABLE_IF</tt> as the last argument to the constructor and
     * suppressing the unused variable warning for the dummy parameter.
     *
     * @snippet demos/dox/basic/enable_if.cpp enable if example constructor
     *
     *
     *
     * @macro EnableIfFunctionality#SEQAN_CTOR_DISABLE_IF
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Bind the visibility of a constructor to an expression.
     *
     * @signature SEQAN_CTOR_DISABLE_IF(TCondition);
     *
     * @param TCondition Boolean type, one of <tt>True</tt> and <tt>False</tt> or a
     *                   metafunction returning such a tag type. If <tt>False</tt>
     *                   then the constructor is visible, otherwise, it is not.
     *
     * This macro allows one to bind the visibility of a construtor to a boolean
     * expression by using the <a href="http://en.wikipedia.org/wiki/Substitution_fa
     * ilure_is_not_an_error">SFINAE</a> principle for an optional argument with
     * default value. The macro call must be used as the last dummy-argument of a
     * constructor.
     *
     * To avoid an unused argument warning, call
     * <tt>ignoreUnusedVariableWarning(dummy)</tt> in the constructor's body.
     *
     * <b>Important:</b> The constructor to disable must be a function template and
     * <tt>TCondition</tt> must include at least one template parameter of the
     * function template.
     *
     * @section Example
     *
     * The following shows an example on how to properly use
     * <tt>SEQAN_CTOR_DISABLE_IF</tt> as the last argument to the constructor and
     * suppressing the unused variable warning for the dummy parameter.
     *
     * @snippet demos/dox/basic/enable_if.cpp disable if example constructor
     *
     *
     *
     * @macro EnableIfFunctionality#SEQAN_FUNC_ENABLE_IF
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Bind the visibility of a function to an expression.
     *
     * @signature SEQAN_FUNC_ENABLE_IF(TCondition, TResult);
     *
     * @param TCondition Boolean type, one of <tt>True</tt> and <tt>False</tt> or a
     *                   metafunction returning such a tag type. If <tt>True</tt>
     *                   then the function is visible, otherwise, it is not.
     * @param TResult The type that the function should have as the return type in
     *                case it is enabled.
     *
     * This macro allows one to bind the visibility of a construtor to a boolean
     * expression by using the <a href="http://en.wikipedia.org/wiki/Substitution_fa
     * ilure_is_not_an_error">SFINAE</a> principle for an optional argument with
     * default value. The macro call must occur as the return type definition of the
     * function.
     *
     * To avoid an unused argument warning, call
     * <tt>ignoreUnusedVariableWarning(dummy)</tt> in the constructor's body.
     *
     * <b>Important:</b> The function to enable must be a function template and
     * <tt>TCondition</tt> must include at least one template parameter of the
     * function template.
     *
     * @section Example
     *
     * The following shows an example on how to properly use
     * <tt>SEQAN_FUNC_ENABLE_IF</tt> as the last argument to the constructor and
     * suppressing the unused variable warning for the dummy parameter.
     *
     * @snippet demos/dox/basic/enable_if.cpp enable if example function
     *
     *
     *
     * @macro EnableIfFunctionality#SEQAN_FUNC_DISABLE_IF
     *
     * @headerfile <seqan/basic.h>
     *
     * @brief Bind the visibility of a function to an expression.
     *
     * @signature SEQAN_FUNC_DISABLE_IF(TCondition, TResult);
     *
     * @param TCondition Boolean type, one of <tt>True</tt> and <tt>False</tt> or a
     *                   metafunction returning such a tag type. If <tt>False</tt>
     *                   then the function is visible, otherwise, it is not.
     * @param TResult The type that the function should have as the return type in
     *                case it is enabled.
     *
     * This macro allows one to bind the visibility of a construtor to a boolean
     * expression by using the <a href="http://en.wikipedia.org/wiki/Substitution_fa
     * ilure_is_not_an_error">SFINAE</a> principle for an optional argument with
     * default value. The macro call must occur as the return type definition of the
     * function.
     *
     * To avoid an unused argument warning, call
     * <tt>ignoreUnusedVariableWarning(dummy)</tt> in the constructor's body.
     *
     * <b>Important:</b> The function to disable must be a function template and
     * <tt>TCondition</tt> must include at least one template parameter of the
     * function template.
     *
     * @section Example
     *
     * The following shows an example on how to properly use
     * <tt>SEQAN_FUNC_DISABLE_IF</tt> as the last argument to the constructor and
     * suppressing the unused variable warning for the dummy parameter.
     *
     * @snippet demos/dox/basic/enable_if.cpp disable if example function
     */