Language Entity Types - SeqAn API Documentation

# Page Language Entity Types

SeqAn is a C++ template library that relies on template metaprogramming to achieve good performance and maintainability. Our way of using C++ template metaprogramming introduces some approaches that might be unfamiliar to you.

For example, functions that would to be member functions in OOP are technically implemented as global functions. For this reason we semantically annotated all variables, functions, metafunctions, classes, etc. throughout the whole online documentation with a small label to tell you with what you're semantically dealing - although there sometimes is no technical counterpart.

We call the above mentioned things like variables, functions, metafunctions, classes, etc. language entity types. This page serves as a reference for the language entity types used in SeqAn and answers the following questions:

- What is each language entity type originally meant to do?
- How is each language entity type used in SeqAn?
- What variants of each language entity type exist?

## Typedef

Typedefs are a common, standardized C++ language feature that allows one to give custom names to arbitrary types.

When programming SeqAn, they are often used for giving short names to complicated, nested template instantiations or to the result of a metafunction.

### Example

The following example shows you how the lengthy type `Iterator<String<char, Alloc<> >::Type` is shortened to `TIt`. (Iterator is a metafunction that returns the iterator type of a container).

    using namespace seqan2;

    typedef typename Iterator<String<char, Alloc<> >::Type TIt;

    for (TIt it = begin(str, Standard()); it != end(str, Standard()); ++it)
        std::cout << *it;

## Concept

Concepts are a rarely used, not yet standardized C++ language feature. They are informal interfaces that define a set of requirements for a type.

In contrast to Java interfaces, C++ concepts can be added to custom types and built-in types without having access to the source code of the type. You might know the typical (Java) interface limitation if you ever tried to make a built-in type implement a custom interface.

Concepts are currently still a proposal for a future C++ language release and thus not respected by IDEs and compilers. As a consequence, your IDE can't tell you if a concept's function is actually implemented for a given class or not. You may still expect the implementation to exist for an implementing class because this is what the SeqAn library guarantees. Functions and metafunctions that are part of a concept are called interface functions respectively interface metafunctions.

### Example

You can expect the globally implemented interface functions appendValue, append, assignValue and many others to work with String because they are part of StringConcept which is implemented by String.

### External Resources

See the concepts chapter at cppreference.com.

## Class

Classes are a common, standardized C++ language feature. It allows the definition of custom types using classes that basically encapsulate variables and functions.

In SeqAn, classes usually have few or no technical member functions. Instead, their member functions are implemented globally and typically expect the class instance as the first argument.

SeqAn provides many class templates that are roughly comparable to Java Generic.

### Example

The following example shows a class template for objects that can hold two values of the same type.

    template class<T>
    class Pair
    {
    public:
        T values [2];

        Pair (T first, T second)
        {
          values[0] = first;
          values[1] = second;
        }
    };

`Pair` can now be instantiated using `Pair<int> myPair1(42, 115);` or `Pair<float>(3.141, 2.72);`.

### Variants

specialization

  Specializations are similar to subclasses but the mechanism uses template specialization instead of C++ subclassing.

  In SeqAn, this is widely used in containers such as strings or indices to achieve good performance.

struct

  C++ inherited `struct`s from C. Structs and classes are very similar, the main difference is that all members of structs are declared with public visibility by default.

  In SeqAn, structs are used instead of classes for simple record types that only store data and do not provide any major logic through interface or member functions.

### Example

The following shows a class `Klass` that is specialized two times using the tags `OneKlass` and `AnotherKlass`.

    struct OneKlass_;
    typedef seqan2::Tag<OneKlass_> OneKlass;

    struct OtherKlass_;
    typedef seqan2::Tag<OtherKlass_> OtherKlass;

    template <typename TSpec>
    class Klass;
    // Note that the body here is optional.  In this case, we create this class "abstract".

    template <>
    class Klass<OneKlass>
    {
    public:
        int x;
    };

    template <>
    class Klass<OtherKlass>
    {
    public:
        double x;
    };

## Enum

Enums are a common, standardized C++ feature that allow the definition of a set of named, enumerable integral constants.

In SeqAn, they are mainly used to define the integral value of the `VALUE` member of a metafunction, e.g. `Log2<32>::VALUE`.

### Example

In the following example, the enum `MyEnum` with the constants `ENUM_VALUE1` and `ENUM_VALUE2` is defined.

    enum MyEnum
    {
         ENUM_VALUE1,
         ENUM_VALUE2
    };

You may later write `MyEnum x = ENUM_VALUE2`.

The following example defines the metafunction `QualityValueSize` using a template struct. The struct contains an unnamed enum with a single integral constant named `VALUE` that has the value `63`.

    template <>
    struct QualityValueSize<Dna5Q>
    {
        enum { VALUE = 63 };
    };

Later you may write `int x = QualityValueSize<Dna5Q>::VALUE` whichs results in `63` and is calculated at compile-time.

If the enum was named (e.g. `MyEnum`) you would have to write `int x = QualityValueSize<Dna5Q>::MyEnum::VALUE (TODO: How is the correct syntax?!?!?!)`.<

## Metafunction

Metafunctions are a rarely used, not yet standardized C++ language feature that allows for compile-time evaluated functions.

In contrast to standard functions that use objects as arguments and optionally return an object, metafunctions use types as arguments and return a type or an integral value.

In SeqAn, they are mainly used to retrieve the appropriate type for a specific task, such as the iteration over a ContainerConcept.

See the Metafunctions in the More C++ Idioms Wikibook for more information.

### Example

The following two examples iterate over each character of `str` and print it. The first example is not recommended but purely demonstrates the use of a metafunction. The second example shows the recommended use of metafunctions in combination with a typedef.

    using namespace seqan2;

    for (typename Iterator<String<char, Alloc<> >::Type it = begin(str, Standard()); it != end(str, Standard()); ++it)
        std::cout << *it;
    std::cout << "\n";

    using namespace seqan2;

    typedef typename Iterator<String<char, Alloc<> >::Type TIt;

    for (TIt it = begin(str, Standard()); it != end(str, Standard()); ++it)
        std::cout << *it;
    std::cout << "\n";

### Variants

Global Metafunction

  Global metafunctions are technically and semantically implemented globally.

  A typical global metafunctions is Log2.

Interface Metafunction

  Interface metafunctions semantically belong to one or more concepts. Types that implement a specific concept are guaranteed to work with all interface functions belonging to this specific concept.

  Example: Class String implement Concept StringConcept. Since the metafunction fn()append is part of Concept StringConcept, fn()append accepts Class String as an argument.

  Although concepts are formally specified they are not yet part of the C++ language and thus ignored by compilers. As a consequence your IDE will pretty certainly not stop you from using a metafunction with a type that does not implements one of the metafunction's concepts.

## Function

Functions are a common, fundamental C++ feature and the basic building block for programs.

### Example

A runnable C++ program always contains a `main` function.

    int main()
    {
      return 0;
    }

### Variants

Global Function

  Global functions are defined outside any class and not directly connected to one class. They might be in a namespace (such as the `seqan` namespace).

  Examples are the functions for the global and local alignment, e.g. globalAlignment and localAlignment. These functions use many classes to realize their behaviour but do not directly belong to any of the signature's data types.
Interface Function

  SeqAn uses global interface functions instead of member functions. This allows (1) to extend types without access to their source code and (2) to use template-based inheritance and static type dispatching.

Member Function

  Member functions are a standard C++ function. They are defined in classes or structs.

  In SeqAn, few member functions are used in the interface of types. Of course, the constructor, and destructor are always implemented as member functions.

## Tag

Tags are classes that are only used for their type. They are often used for tag-based dispatching.

## Variable

Variables are a standard C++ feature.

## Adaption

Adaptions are collections of functions and metafunctions that make a type T follow an interface C. This can be used to make a class from an external library follow a SeqAn concept.

### Example

The following shows a small part of the adaption of `std::string` to the ContainerConcept: the implementation of the length functions.

    #include <string>

    namespace seqan2
    {

    size_t length(std::string const & str)
    {
        return str.size();
    }

    };  // namespace seqan2

## Macro

Macros are pieces of code evaluated by the C preprocessor.

All SeqAn macros are prefixed with `SEQAN_`.

### Example

    // If SeqAn would provide a macro to compute the square of a number, it would
    // look as follows.
    #define SEQAN_SQUARE(x) (x * x)

    // In applications and user code, it could be used as follows:
    #define SQUARE(x) (x * x)

    // The SeqAn library defines the SEQAN_ASSERT* macros, for example:
    SEQAN_ASSERT_EQ(SQUARE(10), 100);

## Template Parameter

Templates can take types or constant integral values as parameters.

#### Dox Sources

    @page LanguageEntities Language Entity Types

    SeqAn is a C++ template library that relies on template metaprogramming to
    achieve good performance and maintainability. Our way of using C++ template
    metaprogramming introduces some approaches that might be unfamiliar to you.

    For example, functions that would to be member functions in OOP are
    technically implemented as global functions. For this reason we semantically
    annotated all variables, functions, metafunctions, classes, etc. throughout
    the whole online documentation with a <span class="data-lang-entity-
    example"><span>small label</span></span> to tell you with what you're
    semantically dealing - although there sometimes is no technical counterpart.

    We call the above mentioned things like variables, functions, metafunctions,
    classes, etc. <acronym title="Imagine you're trying to understand some piece
    of code. The code consists of units normally separated by white-spaces or the
    like. Those units can hold a value (variable), group a sequence of commands
    (function) or represent a template for some object (class). All of these
    units we call language entity type.">language entity type</acronym>s. This
    page serves as a reference for the language entity types used in SeqAn and
    answers the following questions:

    <ul> <li>What is each language entity type originally <b>meant to
    do</b>?</li> <li>How is each language entity type <b>used in SeqAn</b>?</li>
    <li>What <b>variants</b> of each language entity type exist?</li> </ul>

    @endhtmlonly <h2 data-lang-entity="typedef" id="typedef">Typedef</h2> @endhtmlonly

    <strong>Typedefs are a common, standardized C++ language feature that allows
    one to give custom names to arbitrary types.</strong>

    When programming SeqAn, they are often used for giving short names to
    complicated, nested template instantiations or to the result of a <a
    href="#metafunction">metafunction</a>.

    @endhtmlonly <h3 data-toc="hidden">Example</h3> @endhtmlonly

    The following example shows you how the lengthy type
    <code>Iterator&lt;String&lt;char, Alloc&lt;&gt; &gt;::Type</code> is
    shortened to <code>TIt</code>. (@link ContainerConcept#Iterator @endlink is a
    <a href="#metafunction">metafunction</a> that returns the iterator type of a
    container).

    @code{.cpp}
    using namespace seqan2;

    typedef typename Iterator<String<char, Alloc<> >::Type TIt;

    for (TIt it = begin(str, Standard()); it != end(str, Standard()); ++it)
        std::cout << *it;
    @endcode

    @endhtmlonly <h2 data-lang-entity="concept" id="concept">Concept</h2> @endhtmlonly

    <strong>Concepts are a rarely used, not yet standardized C++ language
    feature. They are <u>informal interfaces</u> that define a set of
    requirements for a type.</strong>

    In contrast to Java interfaces, C++ concepts can be added to custom types and
    built-in types without having access to the source code of the type. You
    might know the typical (Java) interface limitation if you ever tried to make
    a built-in type implement a custom interface.

    Concepts are currently still a proposal for a future C++ language release and
    thus not respected by IDEs and compilers. As a consequence, your IDE can't
    tell you if a concept's function is actually implemented for a given <a
    href="#class">class</a> or not. You may still expect the implementation to
    exist for an implementing <a href="#class">class</a> because this is what the
    SeqAn library guarantees. Functions and metafunctions that are part of a
    concept are called <a href="#interface_function">interface functions</a>
    respectively <a href="#interface_metafunction">interface metafunctions</a>.

    @endhtmlonly <h3 data-toc="hidden">Example</h3> @endhtmlonly

    You can expect the globally implemented interface functions @link
    ContainerConcept#appendValue @endlink, @link ContainerConcept#append
    @endlink, @link RandomAccessContainerConcept#assignValue @endlink and many
    others to work with @link String @endlink because they are part of @link
    StringConcept @endlink which is implemented by @link String @endlink.

    @endhtmlonly <h3 data-toc="hidden">External Resources</h3> @endhtmlonly

    See the <a href="https://en.cppreference.com/w/cpp/named_req">concepts
    chapter at cppreference.com</a>.

    @endhtmlonly <h2 data-lang-entity="class" id="class">Class</h2> @endhtmlonly

    <strong>Classes are a common, standardized C++ language feature. It allows
    the definition of custom types using classes that basically encapsulate
    variables and functions.</strong>

    In SeqAn, classes usually have few or no technical member functions. Instead,
    their <a href="#member_function">member functions</a> are implemented
    globally and typically expect the class instance as the first argument.

    SeqAn provides many class templates that are roughly comparable to Java
    Generic.

    @endhtmlonly <h3 data-toc="hidden">Example</h3> @endhtmlonly

    The following example shows a class template for objects that can hold two
    values of the same type.

    @code{.cpp}
    template class<T>
    class Pair
    {
    public:
        T values [2];

        Pair (T first, T second)
        {
          values[0] = first;
          values[1] = second;
        }
    };
    @endcode

    <code>Pair</code> can now be instantiated using <code>Pair&lt;int&gt;
    myPair1(42, 115);</code> or <code>Pair&lt;float&gt;(3.141, 2.72);</code>.

    @endhtmlonly <h3 data-toc="hidden">Variants</h3> @endhtmlonly

    <dl> <dt data-lang-entity="specialization"
    id="specialization">specialization</dt> <dd><p>Specializations are similar to
    subclasses but the mechanism uses template specialization instead of C++
    subclassing.</p> <p>In SeqAn, this is widely used in containers such as
    strings or indices to achieve good performance.</p> </dd> <dt
    id="struct">struct</dt> <dd><p>C++ inherited <code>struct</code>s from C.
    Structs and classes are very similar, the main difference is that all members
    of structs are declared with public visibility by default.</p> <p>In SeqAn,
    structs are used instead of classes for simple record types that only store
    data and do not provide any major logic through interface or member
    functions.</p> </dd> </dl>

    @endhtmlonly <h3 data-toc="hidden">Example</h3> @endhtmlonly

    The following shows a class <code>Klass</code> that is specialized two times
    using the tags <code>OneKlass</code> and <code>AnotherKlass</code>.

    @code{.cpp}
    struct OneKlass_;
    typedef seqan2::Tag<OneKlass_> OneKlass;

    struct OtherKlass_;
    typedef seqan2::Tag<OtherKlass_> OtherKlass;

    template <typename TSpec>
    class Klass;
    // Note that the body here is optional.  In this case, we create this class "abstract".

    template <>
    class Klass<OneKlass>
    {
    public:
        int x;
    };

    template <>
    class Klass<OtherKlass>
    {
    public:
        double x;
    };
    @endcode

    <h2 data-lang-entity="enum" id="enum">Enum</h2>

    <strong>Enums are a common, standardized C++ feature that allow the
    definition of a set of named, <u>enum</u>erable integral constants.</strong>

    In SeqAn, they are mainly used to define the integral value of the
    <code>VALUE</code> member of a metafunction, e.g.
    <code>Log2&lt;32&gt;::VALUE</code>.

    @endhtmlonly <h3 data-toc="hidden">Example</h3> @endhtmlonly

    In the following example, the enum <code>MyEnum</code> with the constants
    <code>ENUM_VALUE1</code> and <code>ENUM_VALUE2</code> is defined.

    @code{.cpp}
    enum MyEnum
    {
         ENUM_VALUE1,
         ENUM_VALUE2
    };
    @endcode

    You may later write <code>MyEnum x = ENUM_VALUE2</code>.

    The following example defines the <a href="#metafunction">metafunction</a>
    <code>QualityValueSize</code> using a template struct. The struct contains an
    unnamed enum with a single integral constant named <code>VALUE</code> that
    has the value <code>63</code>.

    @code{.cpp}
    template <>
    struct QualityValueSize<Dna5Q>
    {
        enum { VALUE = 63 };
    };
    @endcode

    Later you may write <code>int x = QualityValueSize&lt;Dna5Q&gt;::VALUE</code>
    whichs results in <code>63</code> and is calculated at compile-time.

    If the enum was named (e.g. <code>MyEnum</code>) you would have to write
    <code>int x = QualityValueSize&lt;Dna5Q&gt;::MyEnum::VALUE (TODO: How is the
    correct syntax?!?!?!)</code>.<

    @endhtmlonly <h2 data-lang-entity="metafunction" id="metafunction">Metafunction</h2> @endhtmlonly

    <strong>Metafunctions are a rarely used, not yet standardized C++ language
    feature that allows for compile-time evaluated functions.</strong>

    In contrast to standard <a href="#function">functions</a> that use objects as
    arguments and optionally return an object, metafunctions use types as
    arguments and return a type or an integral value.

    In SeqAn, they are mainly used to retrieve the appropriate type for a
    specific task, such as the iteration over a @link ContainerConcept @endlink.

    See the <a href="https://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Metafuncti
    on">Metafunctions in the More C++ Idioms Wikibook</a> for more information.

    @endhtmlonly <h3 data-toc="hidden">Example</h3> @endhtmlonly

    The following two examples iterate over each character of <code>str</code>
    and print it. The first example is not recommended but purely demonstrates
    the use of a metafunction. The second example shows the recommended use of
    metafunctions in combination with a <a href="#typedef">typedef</a>.

    @code{.cpp}
    using namespace seqan2;

    for (typename Iterator<String<char, Alloc<> >::Type it = begin(str, Standard()); it != end(str, Standard()); ++it)
        std::cout << *it;
    std::cout << "\n";
    @endcode

    @code{.cpp}
    using namespace seqan2;

    typedef typename Iterator<String<char, Alloc<> >::Type TIt;

    for (TIt it = begin(str, Standard()); it != end(str, Standard()); ++it)
        std::cout << *it;
    std::cout << "\n";
    @endcode

    @endhtmlonly <h3 data-toc="hidden">Variants</h3> @endhtmlonly

    <dl> <dt data-lang-entity="global_metafunction"
    id="global_metafunction">Global Metafunction</dt> <dd><p>Global metafunctions
    are technically and semantically implemented globally.</p></dd> <dd><p>A
    typical global metafunctions is @link MetaprogrammingMath#Log2
    @endlink.</p></dd> <dt data-lang-entity="interface_metafunction"
    id="interface_metafunction">Interface Metafunction</dt> <dd><p>Interface
    metafunctions semantically belong to one or more <a
    href="#concept">concepts</a>. Types that implement a specific concept are
    guaranteed to work with all interface functions belonging to this specific
    concept.</p> <p>Example: <span data-lang-entity="class" data-pimped="true"><a
    href="page_LanguageEntities.html#class">Class</a><a
    href="class_String.html">String</a></span> implement <span data-lang-
    entity="concept" data-pimped="true"><a
    href="page_LanguageEntities.html#concept">Concept</a><a
    href="concept_StringConcept.html">StringConcept</a></span>. Since the
    metafunction <span data-lang-entity="global_function" data-pimped="true"><a
    href="page_LanguageEntities.html#global_function">fn()</a><a
    href="global_function_append.html">append</a></span> is part of <span data-
    lang-entity="concept" data-pimped="true"><a
    href="page_LanguageEntities.html#concept">Concept</a><a
    href="concept_StringConcept.html">StringConcept</a></span>, <span data-lang-
    entity="global_function" data-pimped="true"><a
    href="page_LanguageEntities.html#global_function">fn()</a><a
    href="global_function_append.html">append</a></span> accepts <span data-lang-
    entity="class" data-pimped="true"><a
    href="page_LanguageEntities.html#class">Class</a><a
    href="class_String.html">String</a></span> as an argument.</p></dd>
    <dd><p>Although <a href="#concept">concepts</a> are formally specified they
    are not yet part of the C++ language and thus ignored by compilers. As a
    consequence your IDE will pretty certainly not stop you from using a
    metafunction with a type that does not implements one of the metafunction's
    concepts.</p></dd> </dl>

    @endhtmlonly <h2 data-lang-entity="function" id="function">Function</h2> @endhtmlonly

    <strong>Functions are a common, fundamental C++ feature and the basic
    building block for programs.</strong>

    @endhtmlonly <h3 data-toc="hidden">Example</h3> @endhtmlonly

    A runnable C++ program always contains a <code>main</code> function.

    @code{.cpp}
    int main()
    {
      return 0;
    }
    @endcode

    <h3 data-toc="hidden">Variants</h3>

    <dl> <dt data-lang-entity="global_function" id="global_function">Global
    Function</dt> <dd><p>Global functions are defined outside any class and not
    directly connected to one class. They might be in a namespace (such as the
    <code>seqan</code> namespace).</p> </dd> <dd>Examples are the functions for
    the global and local alignment, e.g. @link globalAlignment @endlink and @link
    localAlignment @endlink. These functions use many classes to realize their
    behaviour but do not directly belong to any of the signature's data
    types.</dd> <dt data-lang-entity="interface_function"
    id="interface_function">Interface Function</dt> <dd><p>SeqAn uses global
    interface functions instead of member functions. This allows (1) to extend
    types without access to their source code and (2) to use template-based
    inheritance and static type dispatching.</p> </dd> <dt data-lang-
    entity="member_function" id="member_function">Member Function</dt>
    <dd><p>Member functions are a standard C++ function. They are defined in
    classes or structs.</p></dd> <dd><p>In SeqAn, few member functions are used
    in the interface of types. Of course, the constructor, and destructor are
    always implemented as member functions.</p></dd> </dl>

    @endhtmlonly <h2 data-lang-entity="tag" id="tag">Tag</h2> @endhtmlonly

    Tags are classes that are only used for their type. They are often used for
    tag-based dispatching.

    @endhtmlonly <h2 data-lang-entity="variable" id="variable">Variable</h2> @endhtmlonly

    Variables are a standard C++ feature.

    @endhtmlonly <h2 data-lang-entity="adaption" id="adaption">Adaption</h2> @endhtmlonly

    Adaptions are collections of functions and metafunctions that make a type
    <b>T</b> follow an interface <b>C</b>. This can be used to make a class from
    an external library follow a SeqAn concept.

    @endhtmlonly <h3 data-toc="hidden">Example</h3> @endhtmlonly

    The following shows a small part of the adaption of <code>std::string</code>
    to the @link ContainerConcept @endlink: the implementation of the length
    functions.

    @code{.cpp}
    #include <string>

    namespace seqan2
    {

    size_t length(std::string const & str)
    {
        return str.size();
    }

    };  // namespace seqan2
    @endcode

    @endhtmlonly <h2 data-lang-entity="macro" id="macro">Macro</h2> @endhtmlonly

    Macros are pieces of code evaluated by the C preprocessor.

    All SeqAn macros are prefixed with <tt>SEQAN_</tt>.

    @endhtmlonly <h3 data-toc="hidden">Example</h3> @endhtmlonly

    @code{.cpp}
    // If SeqAn would provide a macro to compute the square of a number, it would
    // look as follows.
    #define SEQAN_SQUARE(x) (x * x)

    // In applications and user code, it could be used as follows:
    #define SQUARE(x) (x * x)

    // The SeqAn library defines the SEQAN_ASSERT* macros, for example:
    SEQAN_ASSERT_EQ(SQUARE(10), 100);
    @endcode

    @endhtmlonly <h2 data-lang-entity="template_parameter" id="template_parameter">Template Parameter</h2> @endhtmlonly

    Templates can take types or constant integral values as parameters.