File - SeqAn API Documentation

# Class File
Represents a file.

All Subcl's | AsyncFile, SyncFile
Defined in | <seqan/file.h>
Signature | `template <[typename TSpec]> class File<TSpec>;`

## Template Parameters

`TSpec` | Specializing type. Default: `Async<>`.

## Interface Function Overview

- `bool asyncReadAt(file, memPtr, count, fileOfs, request);`
  Asynchronously loads records from a specific position in a file.
- `bool asyncWriteAt(file, memPtr, count, fileOfs, request);`
  Asynchronously writes records to a specific position in a file.
- `bool cancel(file, request);`
  Cancels an asynchronous request.
- `bool close(file);`
  Close a file.
- `void flush(file);`
  Waits for all open requests to complete.
- `TSize length(file);`
  Return the file size.
- `bool open(file, fileName, openMode);`
  Opens a file, stream, or persistent string.
- `bool openTemp(file);`
  Opens a temporary file.
- `bool read(file, memPtr, count);`
  Loads record from a file.
- `bool readAt(file, memPtr, count, fileOfs);`
  Loads records from a specific position in a file.
- `void resize(file, newLength);`
  A file object.
- `void rewind(file);`
  Sets the current file pointer to the beginning of a file.
- `TPosition seek(file, fileOfs[, origin]);`
  Changes the current file pointer.
- `bool setEof(file);`
  Sets the file end to the current pointer.
- `TPosition tell(file);`
  Gets the current file pointer.
- `bool waitFor(request[, timeout]);`
  Waits for an asynchronous request to complete.
- `bool write(file, memPtr, count);`
  Saves records to a file.
- `bool writeAt(file, memPtr, count, fileOfs);`
  Saves records to a specific position in a file.

## Interface Functions Detail

### `bool asyncReadAt(file, memPtr, count, fileOfs, request);`

Asynchronously loads records from a specific position in a file.

#### Parameters

`file` | The File object to read from.
`memPtr` | A pointer to the first destination record in memory.
`count` | The amount of records to be read.
`fileOfs` | The absolute file position in bytes measured from the beginning.
`request` | Reference to a structure that will be associated with this asynchronous request. Type: AsyncRequest.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Data Races

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

### `bool asyncWriteAt(file, memPtr, count, fileOfs, request);`

Asynchronously writes records to a specific position in a file.

#### Parameters

`file` | The File object.
`memPtr` | A pointer to the first source record in memory.
`count` | The amount of records to be written.
`fileOfs` | The absolute file position in bytes measured form the beginning.
`request` | Reference to a structure that will be associated with this asynchronous request.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Data Races

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

### `bool cancel(file, request);`

Cancels an asynchronous request.

#### Parameters

`file` | The File to cancel the request for.
`request` | Reference to an AsyncRequest object. Type: AsyncRequest.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Data Races

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

### `bool close(file);`

Close a file.

#### Parameters

`file` | The File object to close.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Data Races

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

### `void flush(file);`

Waits for all open requests to complete.

#### Parameters

`file` | The File object to flush.

#### Data Races

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

### `TSize length(file);`

Return the file size.

#### Parameters

`file` | The File object to query for its size.

#### Returns

`TSize` | The file size measured in bytes.

#### Data Races

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

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

Opens a file, stream, or persistent string.

#### Parameters

`file` | The File to open.
`fileName` | A `char const *` string containing the file name.
`openMode` | Combination of flags defining how the file should be opened. See FileOpenMode for more details. Type: `int`. If you omit the `OPEN_APPEND` flag in write mode, the file will be cleared when opened. Default: `OPEN_RDWR | OPEN_CREATE | OPEN_APPEND`.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Data Races

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

### `bool openTemp(file);`

Opens a temporary file.

#### Parameters

`file` | The File object to open the temporary file.

#### Returns

`bool` | `true` on success, `false` on failure.
`bool` | `true` on success `false` on failure.

#### Remarks

After closing this file will be deleted automatically. The openmode (see open) is `OPEN_RDWR | OPEN_CREATE`.

#### Data Races

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

### `bool read(file, memPtr, count);`

Loads record from a file.

#### Parameters

`file` | The File object.
`memPtr` | A pointer to the first destination record in memory.
`count` | The amount of records to be read.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Remarks

The records are read from the position pointed to by the current file pointer (see seek).

#### Data Races

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

### `bool readAt(file, memPtr, count, fileOfs);`

Loads records from a specific position in a file.

#### Parameters

`file` | The File object to read from.
`memPtr` | A pointer to the first destination record in memory.
`count` | The amount of records to be read.
`fileOfs` | The absolute file position in bytes measured from the beginning.

#### Returns

`bool` | `true` on success and `false` on failure.

#### Data Races

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

### `void resize(file, newLength);`

A file object.

#### Parameters

`file` | The File object to resize.
`newLength` | The file size in bytes to resize to in bytes.

#### Data Races

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

### `void rewind(file);`

Sets the current file pointer to the beginning of a file.

#### Parameters

`file` | The file to reset the file pointer of.

#### Data Races

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

### `TPosition seek(file, fileOfs[, origin]);`

Changes the current file pointer.

#### Parameters

`file` | The File object to seek in.
`fileOfs` | A file offset measured in bytes relative to `origin`.
`origin` | Selects the origin from where to calculate the new position. One of `SEEK_BEGIN`, `SEEK_CURRENT`, and `SEEK_END`(origin is beginning, current pointer, end of the file). Default: `SEEK_BEGIN`.``

#### Returns

`TPosition` | The new file position measured in bytes from the beginning.

#### Data Races

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

### `bool setEof(file);`

Sets the file end to the current pointer.

#### Parameters

`file` | The File object to set the end of.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Data Races

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

### `TPosition tell(file);`

Gets the current file pointer.

#### Parameters

`file` | The File object to query for the current position.

#### Returns

`TPosition` | The current position in the file.

#### Data Races

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

### `bool waitFor(request[, timeout]);`

Waits for an asynchronous request to complete.

#### Parameters

`request` | Reference to an AsyncRequest.
`timeout` | A timeout value in milliseconds. A value of 0 can be used to test for completion without waiting. Default: 0.

#### Returns

`bool` | `true` on completion, `false` on timeout.

#### Remarks

`waitfor` block sand suspends the calling thread process until `request` is completed or after `timeout` milliseconds.

#### Data Races

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

### `bool write(file, memPtr, count);`

Saves records to a file.

#### Parameters

`file` | The File object.
`memPtr` | Pointer to the source for the data to write.
`count` | The number of records to write.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Remarks

The records are written at the position pointed to by the current file pointer (see seek).

#### Data Races

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

### `bool writeAt(file, memPtr, count, fileOfs);`

Saves records to a specific position in a file.

#### Parameters

`file` | The File object to write to.
`memPtr` | Pointer to the memory to write.
`count` | The amount of records to be written.
`fileOfs` | The absolute file position in bytes measured from the beginning.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Data Races

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

#### Dox Sources

    /*!
     * @class File
     *
     * @headerfile <seqan/file.h>
     *
     * @brief Represents a file.
     *
     * @signature template <[typename TSpec]> class File<TSpec>;
     *
     * @tparam TSpec Specializing type. Default: <tt>Async&lt;&gt;</tt>.
     *
     * @fn File#open
     *
     * @brief Opens a file, stream, or persistent string.
     *
     * @signature bool open(file, fileName, openMode);
     *
     * @param[in,out] file The File to open.
     * @param[in] fileName A <tt>char const *</tt> string containing the file name.
     * @param[in] openMode Combination of flags defining how the file should be
     *                     opened. See @link FileOpenMode @endlink for more details.
     *                     Type: <tt>int</tt>. If you omit the <tt>OPEN_APPEND</tt>
     *                     flag in write mode, the file will be cleared when opened.
     *                     Default: <tt>OPEN_RDWR | OPEN_CREATE | OPEN_APPEND</tt>.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     *
     * @fn File#openTemp
     *
     * @brief Opens a temporary file.
     *
     * @signature bool openTemp(file);
     *
     * @param[in,out] file The File object to open the temporary file.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     * @return bool <tt>true</tt> on success <tt>false</tt> on failure.
     *
     * @section Remarks
     *
     * After closing this file will be deleted automatically. The openmode (see
     * @link File#open @endlink) is <tt>OPEN_RDWR | OPEN_CREATE</tt>.
     *
     * @fn File#close
     *
     * @brief Close a file.
     *
     * @signature bool close(file);
     *
     * @param[in,out] file The File object to close.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     *
     * @fn File#read
     *
     * @brief Loads record from a file.
     *
     * @signature bool read(file, memPtr, count);
     *
     * @param[in,out] file The File object.
     * @param[out] memPtr A pointer to the first destination record in memory.
     * @param[in] count The amount of records to be read.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     *
     * @section Remarks
     *
     * The records are read from the position pointed to by the current file pointer
     * (see @link File#seek @endlink).
     *
     * @fn File#write
     *
     * @brief Saves records to a file.
     *
     * @signature bool write(file, memPtr, count);
     *
     * @param[in,out] file The File object.
     * @param[in] memPtr Pointer to the source for the data to write.
     * @param[in] count The number of records to write.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     *
     * @section Remarks
     *
     * The records are written at the position pointed to by the current file
     * pointer (see @link File#seek @endlink).
     *
     * @fn File#readAt
     *
     * @brief Loads records from a specific position in a file.
     *
     * @signature bool readAt(file, memPtr, count, fileOfs);
     *
     * @param[in,out] file The File object to read from.
     * @param[out] memPtr A pointer to the first destination record in memory.
     * @param[in] count The amount of records to be read.
     * @param[in] fileOfs The absolute file position in bytes measured from the
     *                    beginning.
     *
     * @return bool <tt>true</tt> on success and <tt>false</tt> on failure.
     *
     * @fn File#writeAt
     *
     * @brief Saves records to a specific position in a file.
     *
     * @signature bool writeAt(file, memPtr, count, fileOfs);
     *
     * @param[in,out] file The File object to write to.
     * @param[in] memPtr Pointer to the memory to write.
     * @param[in] count The amount of records to be written.
     * @param[in] fileOfs The absolute file position in bytes measured from the
     *                    beginning.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     *
     * @fn File#seek
     *
     * @brief Changes the current file pointer.
     *
     * @signature TPosition seek(file, fileOfs[, origin]);
     *
     * @param[in,out] file The File object to seek in.
     * @param[in] fileOfs A file offset measured in bytes relative to
     *                    <tt>origin</tt>.
     * @param[in] origin Selects the origin from where to calculate the new
     *                   position. One of <tt>SEEK_BEGIN</tt>,
     *                   <tt>SEEK_CURRENT</tt>, and <tt>SEEK_END<tt> (origin is
     *                   beginning, current pointer, end of the file). Default:
     *                   <tt>SEEK_BEGIN</tt>.
     *
     * @return TPosition The new file position measured in bytes from the beginning.
     *
     * @fn File#tell
     *
     * @brief Gets the current file pointer.
     *
     * @signature TPosition tell(file);
     *
     * @param[in] file The File object to query for the current position.
     *
     * @return TPosition The current position in the file.
     *
     * @fn File#rewind
     *
     * @brief Sets the current file pointer to the beginning of a file.
     *
     * @signature void rewind(file);
     *
     * @param[in,out] file The file to reset the file pointer of.
     *
     * @fn File#length
     *
     * @brief Return the file size.
     *
     * @signature TSize length(file);
     *
     * @param[in] file The File object to query for its size.
     *
     * @return TSize The file size measured in bytes.
     *
     * @fn File#resize
     *
     * @brief A file object.
     *
     * @signature void resize(file, newLength);
     *
     * @param[in,out] file The File object to resize.
     * @param[in] newLength The file size in bytes to resize to in bytes.
     *
     * @fn File#setEof
     *
     * @brief Sets the file end to the current pointer.
     *
     * @signature bool setEof(file);
     *
     * @param[in,out] file The File object to set the end of.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     *
     * @fn File#asyncReadAt
     *
     * @brief Asynchronously loads records from a specific position in a file.
     *
     * @signature bool asyncReadAt(file, memPtr, count, fileOfs, request);
     *
     * @param[in,out] file The File object to read from.
     * @param[out] memPtr A pointer to the first destination record in memory.
     * @param[in] count The amount of records to be read.
     * @param[in] fileOfs The absolute file position in bytes measured from the
     *                    beginning.
     * @param[in] request Reference to a structure that will be associated with this
     *                    asynchronous request. Type: @link AsyncRequest @endlink.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     *
     * @fn File#asyncWriteAt
     *
     * @brief Asynchronously writes records to a specific position in a file.
     *
     * @signature bool asyncWriteAt(file, memPtr, count, fileOfs, request);
     *
     * @param[in,out] file The File object.
     * @param[in] memPtr A pointer to the first source record in memory.
     * @param[in] count The amount of records to be written.
     * @param[in] fileOfs The absolute file position in bytes measured form the
     *                    beginning.
     * @param[in] request Reference to a structure that will be associated with this
     *                    asynchronous request.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     *
     * @fn File#flush
     *
     * @brief Waits for all open requests to complete.
     *
     * @signature void flush(file);
     *
     * @param[in,out] file The File object to flush.
     *
     * @fn File#waitFor
     *
     * @brief Waits for an asynchronous request to complete.
     *
     * @signature bool waitFor(request[, timeout]);
     *
     * @param[in,out] request Reference to an AsyncRequest.
     * @param[in] timeout A timeout value in milliseconds. A value of 0 can be used
     *                    to test for completion without waiting. Default: 0.
     *
     * @return bool <tt>true</tt> on completion, <tt>false</tt> on timeout.
     *
     * @section Remarks
     *
     * <tt>waitfor</tt> block sand suspends the calling thread process until
     * <tt>request</tt> is completed or after <tt>timeout</tt> milliseconds.
     *
     * @fn File#cancel
     *
     * @brief Cancels an asynchronous request.
     *
     * @signature bool cancel(file, request);
     *
     * @param[in,out] file The File to cancel the request for.
     * @param[in] request Reference to an AsyncRequest object. Type: @link
     *                    AsyncRequest @endlink.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     */