FormattedFile - SeqAn API Documentation

# Class FormattedFile
Base class for formatted file I/O.

All Subcl's | BamFileIn, BamFileOut, BedFileIn, BedFileOut, BlastReportFileOut, BlastTabularFileIn, BlastTabularFileOut, FormattedFileIn, FormattedFileOut, GffFileIn, GffFileOut, RnaStructFileIn, RnaStructFileOut, RoiFileIn, RoiFileOut, SeqFileIn, SeqFileOut, SimpleIntervalsFileIn, SimpleIntervalsFileInOut, UcscFileIn, UcscFileOut, VcfFileIn, VcfFileOut
Defined in | <seqan/stream.h>
Signature | `template <typename TFileFormat, typename TDirection[, typename TSpec]> struct FormattedFile;`

## Template Parameters

`TFileFormat` | A type specifying the file format.
`TDirection` | The direction of the file, one of Input or Output.
`TSpec` | A tag for the specialization, defauls to `void`.

## Member Function Overview

- `TExtensionVector getFileExtensions()`
  Static function that returns a list of allowed file format extension.
- `TDependentContext & FormattedFile::operator TDependentContext();`
  Allows conversion to a dependent context for the FormattedFile

## Interface Function Overview

- `bool atEnd(file);`
  Determines whether a FormattedFile is at the end.
- `bool close(file);`
  Close a FormattedFile.
- `TDependentContext & context(file);`
  Return the FormattedFile's dependent context object.
- `TFormat format(file);`
  Return the format of a FormattedFile.
- `FormattedFile::FormattedFile();, FormattedFile::FormattedFile(fileName[, openMode]);, FormattedFile::FormattedFile(stream);, FormattedFile::FormattedFile(other);, FormattedFile::FormattedFile(otherContext);, FormattedFile::FormattedFile(otherContext, fileName[, openMode]);, FormattedFile::FormattedFile(otherContext, stream);`
  Provides default construction.
- `TExtensionVector getFileExtensions(file)`
  Static function that returns a list of allowed file format extension.
- `bool guessFormat(file);`
  Guess the format of an open FormattedFile.
- `bool isOpen(file);`
  Determines whether a FormattedFile is currently open.
- `bool open(file, fileName, mode);`
  Open a FormattedFile.
- `void setFormat(file, format);`
  Set the format of a FormattedFile.

## Interface Metafunction Overview

- `FileFormat<TFormattedFile>::Type;`
  Metafunction for retrieving the file format type of a formatted file.
- `FormattedFileContext<TFormattedFile, TStorageSpec>::Type`
  Returns the context type for a FormattedFile.

## Detailed Description

FormattedFile provides the following basic I/O operations on formatted files:

- Open a file given its filename or attach to an existing stream like stdin/stdout.
- Guess the file format from the file content or filename extension.
- Set the file format manually.
- Access compressed or uncompressed files transparently.

FormattedFile encapsulates a VirtualStream and provides access to its DirectionIterator. Each instance of FormattedFile keeps a FormattedFileContext while reading or writing the formatted file.

## Member Functions Detail

### `TExtensionVector getFileExtensions()`

Static function that returns a list of allowed file format extension.

#### Returns

`TExtensionVector` | A `std::vector<std::string>` with the allowed file extensions.

#### Data Races

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

### `TDependentContext & FormattedFile::operator TDependentContext();`

Allows conversion to a dependent context for the FormattedFile

#### Returns

`TDependentContext` | The dependent context of this FormattedFile.

#### Data Races

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

## Interface Functions Detail

### `bool atEnd(file);`

Determines whether a FormattedFile is at the end.

#### Parameters

`file` | The FormattedFile to check.

#### Returns

`bool` | `true` in the case of success, `false` otherwise.

#### Data Races

Not thread safe.

### `bool close(file);`

Close a FormattedFile.

#### Parameters

`file` | The FormattedFile to close.

#### Returns

`bool` | `true` in the case of success, `false` otherwise.

#### Data Races

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

### `TDependentContext & context(file);`

Return the FormattedFile's dependent context object.

#### Parameters

`file` | The FormattedFile to query for its context.

#### Returns

`TDependentContext` | The dependent context, type as returned from FormattedFileContext.

#### Data Races

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

### `TFormat format(file);`

Return the format of a FormattedFile.

#### Parameters

`file` | The FormattedFile to check.

#### Returns

`TFormat` | The type as returned from FileFormat.

#### Data Races

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

### `FormattedFile::FormattedFile(); FormattedFile::FormattedFile(fileName[, openMode]); FormattedFile::FormattedFile(stream); FormattedFile::FormattedFile(other); FormattedFile::FormattedFile(otherContext); FormattedFile::FormattedFile(otherContext, fileName[, openMode]); FormattedFile::FormattedFile(otherContext, stream);`

Provides default construction.

#### Parameters

`fileName` | Path to file to open, `char const *`.
`openMode` | Optionally, the file open mode, default obtained from `TDirection`.
`stream` | A `std::basic_istream<>` to read from or `std::basic_ostream<>` to write to, depending on `TDirection`.
`other` | A second FormattedFile, this FormattedFile's dependent context will depend on `other`'s dependent context.
`otherContext` | The dependent context of another FormattedFile, this FormattedFile's dependent context will depend on `otherContext`.

#### Thrown Exceptions

`IOError` | The variants that accept the `fileName` parameter throw an exception of this type in case opening the file fails.

#### Data Races

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

### `TExtensionVector getFileExtensions(file)`

Static function that returns a list of allowed file format extension.

#### Parameters

`file` | The FormattedFile to query.

#### Returns

`TExtensionVector` | A `std::vector<std::string>` with the allowed file extensions.

This is a shortcut to getFileExtensions.

#### Data Races

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

### `bool guessFormat(file);`

Guess the format of an open FormattedFile.

#### Parameters

`file` | The open FormattedFile for which the format is to be guessed.

#### Data Races

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

### `bool isOpen(file);`

Determines whether a FormattedFile is currently open.

#### Parameters

`file` | The FormattedFile to check.

#### Returns

`bool` | `true` if file is currently open, `false` otherwise.

#### Data Races

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

### `bool open(file, fileName, mode);`

Open a FormattedFile.

#### Parameters

`file` | The FormattedFile to open.
`fileName` | The name of the file open.
`mode` | The open mode: FileOpenMode.

#### Returns

`bool` | `true` in the case of success, `false` otherwise.

#### Data Races

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

### `void setFormat(file, format);`

Set the format of a FormattedFile.

#### Parameters

`file` | The FormattedFile to change.
`format` | The FileFormat to set.

#### Data Races

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

## Interface Metafunctions Detail

### `FileFormat<TFormattedFile>::Type;`

Metafunction for retrieving the file format type of a formatted file.

#### Template Parameters

`TFormattedFile` | The formatted file type to query for its file format type.

#### Returns

`Type` | The resulting FileFormats file formats type.

### `FormattedFileContext<TFormattedFile, TStorageSpec>::Type`

Returns the context type for a FormattedFile.

#### Template Parameters

`TFormattedFile` | The FormattedFile to query.
`TStorageSpec` | The storage specification, passed as specialization to any StringSet contained in the context.
`Type` | The resulting FormattedFile context type.

#### Dox Sources

    /*!
     * @class FormattedFile
     *
     * @headerfile <seqan/stream.h>
     *
     * @brief Base class for formatted file I/O.
     *
     * @signature template <typename TFileFormat, typename TDirection[, typename
     *            TSpec]> struct FormattedFile;
     *
     * @tparam TFileFormat A type specifying the file format.
     * @tparam TDirection The direction of the file, one of @link
     *                    DirectionTags#Input Input @endlink or @link
     *                    DirectionTags#Output @endlink.
     * @tparam TSpec A tag for the specialization, defauls to <tt>void</tt>.
     *
     * FormattedFile provides the following basic I/O operations on formatted files:
     *
     * <ul> <li>Open a file given its filename or attach to an existing stream like
     * stdin/stdout.</li> <li>Guess the file format from the file content or
     * filename extension.</li> <li>Set the file format manually.</li> <li>Access
     * compressed or uncompressed files transparently.</li> </ul>
     *
     * FormattedFile encapsulates a VirtualStream and provides access to its @link
     * StreamConcept#DirectionIterator @endlink. Each instance of FormattedFile
     * keeps a @link FormattedFile#FormattedFileContext @endlink while reading or
     * writing the formatted file.
     *
     * @mfn FormattedFile#FileFormat
     *
     * @brief Metafunction for retrieving the file format type of a formatted file.
     *
     * @signature FileFormat<TFormattedFile>::Type;
     *
     * @tparam TFormattedFile The formatted file type to query for its file format
     *                        type.
     *
     * @return Type The resulting @link FileFormats @endlink file formats type.
     *
     * @mfn FormattedFile#FormattedFileContext
     *
     * @brief Returns the context type for a FormattedFile.
     *
     * @signature FormattedFileContext<TFormattedFile, TStorageSpec>::Type
     *
     * @tparam TFormattedFile The FormattedFile to query.
     * @tparam TStorageSpec The storage specification, passed as specialization to
     *                      any @link StringSet @endlink contained in the context.
     * @tparam Type The resulting FormattedFile context type.
     *
     * @fn FormattedFile::operatorTDependentContext
     *
     * @brief Allows conversion to a dependent context for the FormattedFile
     *
     * @signature TDependentContext & FormattedFile::operator TDependentContext();
     *
     * @return TDependentContext The dependent context of this FormattedFile.
     *
     * @fn FormattedFile::getFileExtensions
     *
     * @brief Static function that returns a list of allowed file format extension.
     *
     * @signature TExtensionVector getFileExtensions()
     *
     * @return TExtensionVector A <tt>std::vector&lt;std::string&gt;</tt> with the
     *                          allowed file extensions.
     *
     * @fn FormattedFile#FormattedFile
     *
     * @brief Provides default construction.
     *
     * @signature FormattedFile::FormattedFile();
     * @signature FormattedFile::FormattedFile(fileName[, openMode]);
     * @signature FormattedFile::FormattedFile(stream);
     * @signature FormattedFile::FormattedFile(other);
     * @signature FormattedFile::FormattedFile(otherContext);
     * @signature FormattedFile::FormattedFile(otherContext, fileName[, openMode]);
     * @signature FormattedFile::FormattedFile(otherContext, stream);
     *
     * @param[in] fileName Path to file to open, <tt>char const *</tt>.
     * @param[in] openMode Optionally, the file open mode, default obtained from
     *                     <tt>TDirection</tt>.
     * @param[in] stream A <tt>std::basic_istream&lt;&gt;</tt> to read from or
     *                   <tt>std::basic_ostream&lt;&gt;</tt> to write to, depending
     *                   on <tt>TDirection</tt>.
     * @param[in] other A second FormattedFile, this FormattedFile's dependent
     *                  context will depend on <tt>other</tt>'s dependent context.
     * @param[in] otherContext The dependent context of another FormattedFile, this
     *                         FormattedFile's dependent context will depend on
     *                         <tt>otherContext</tt>.
     *
     * @throw IOError The variants that accept the <tt>fileName</tt> parameter throw
     *                an exception of this type in case opening the file fails.
     *
     * @fn FormattedFile#format
     *
     * @brief Return the format of a FormattedFile.
     *
     * @signature TFormat format(file);
     *
     * @param[in] file The FormattedFile to check.
     *
     * @return TFormat The type as returned from @link FormattedFile#FileFormat
     *                 @endlink.
     *
     * @fn FormattedFile#setFormat
     *
     * @brief Set the format of a FormattedFile.
     *
     * @signature void setFormat(file, format);
     *
     * @param[in,out] file The FormattedFile to change.
     * @param[in] format The @link FormattedFile#FileFormat @endlink to set.
     *
     * @fn FormattedFile#guessFormat
     *
     * @brief Guess the format of an open FormattedFile.
     *
     * @signature bool guessFormat(file);
     *
     * @param[in,out] file The open FormattedFile for which the format is to be
     *                     guessed.
     *
     * @fn FormattedFile#open
     *
     * @brief Open a FormattedFile.
     *
     * @signature bool open(file, fileName, mode);
     *
     * @param[in,out] file The FormattedFile to open.
     * @param[in] fileName The name of the file open.
     * @param[in] mode The open mode: @link FileOpenMode @endlink.
     *
     * @return bool <tt>true</tt> in the case of success, <tt>false</tt> otherwise.
     *
     * @fn FormattedFile#isOpen
     *
     * @brief Determines whether a FormattedFile is currently open.
     *
     * @signature bool isOpen(file);
     *
     * @param[in] file The FormattedFile to check.
     *
     * @return bool <tt>true</tt> if file is currently open, <tt>false</tt>
     *              otherwise.
     *
     * @fn FormattedFile#close
     *
     * @brief Close a FormattedFile.
     *
     * @signature bool close(file);
     *
     * @param[in,out] file The FormattedFile to close.
     *
     * @return bool <tt>true</tt> in the case of success, <tt>false</tt> otherwise.
     *
     * @fn FormattedFile#atEnd
     *
     * @brief Determines whether a FormattedFile is at the end.
     *
     * @signature bool atEnd(file);
     *
     * @param[in,out] file The FormattedFile to check.
     *
     * @return bool <tt>true</tt> in the case of success, <tt>false</tt> otherwise.
     *
     * @datarace Not thread safe.
     *
     * @fn FormattedFile#context
     *
     * @brief Return the FormattedFile's dependent context object.
     *
     * @signature TDependentContext & context(file);
     *
     * @param[in,out] file The FormattedFile to query for its context.
     *
     * @return TDependentContext The dependent context, type as returned from @link
     *                           FormattedFile#FormattedFileContext @endlink.
     *
     * @fn FormattedFile#getFileExtensions
     *
     * @brief Static function that returns a list of allowed file format extension.
     *
     * @signature TExtensionVector getFileExtensions(file)
     *
     * @param[in] file The FormattedFile to query.
     *
     * @return TExtensionVector A <tt>std::vector&lt;std::string&gt;</tt> with the
     *                          allowed file extensions.
     *
     * This is a shortcut to @link FormattedFile#getFileExtensions @endlink.
     */