External String - SeqAn API Documentation

# Spec External String
String that is stored in external memory.

Extends | String
All Extended | String
All Impl'd | AssignableConcept, ContainerConcept, DestructibleConcept, ForwardContainerConcept, RandomAccessContainerConcept, ReversibleContainerConcept, SegmentableConcept, StringConcept, TextConcept
Defined in | <seqan/file.h>
Signature | `template <typename TValue[, typename TConfig]> class String<TValue, External<TConfig> >;`

## Template Parameters

`TValue` | The type that is used for the items/characters stored in the string.
`TConfig` | A structure to configure the external string. Defaults to `ExternalConfigLarge<>. See ExternalConfig, ExternalConfigLarge, and ExternalConfigSize.`

## Member Function Overview

- `String::String();, String::String(file);, String::String(fileName[, openMode]);`
  Constructor

### Member Functions Inherited From String

- `operator=`
- `String`

### Member Functions Inherited From AssignableConcept

- `operator=`

### Member Functions Inherited From RandomAccessContainerConcept

- `operator[]`

## Interface Function Overview

- `bool close(str);`
  Close the external string.
- `void flush(str);`
  Waits for all open read/write requests to complete.
- `bool open(str, fileName[, openMode]);`
  Open the ExternalString's underlying file from a path.
- `bool openTemp(str);`
  Open an ExternalString using an temporary file.

### Interface Functions Inherited From String

- `beginPosition`
- `endPosition`
- `reserve`
- `resizeSpace`
- `toCString`

### Interface Functions Inherited From AssignableConcept

- `assign`
- `set`
- `move`

### Interface Functions Inherited From ContainerConcept

- `writeValue`
- `write`
- `begin`
- `end`
- `length`
- `empty`
- `swap`
- `getObjectId`
- `moveValue`
- `append`
- `appendValue`
- `shrinkToFit`
- `directionIterator`

### Interface Functions Inherited From RandomAccessContainerConcept

- `value`
- `assignValue`
- `getValue`

### Interface Functions Inherited From SegmentableConcept

- `prefix`
- `infixWithLength`
- `infix`
- `suffix`

### Interface Functions Inherited From StringConcept

- `iter`
- `append`
- `appendValue`
- `front`
- `back`
- `resize`
- `clear`
- `erase`
- `eraseFront`
- `eraseBack`
- `capacity`
- `computeGenerousCapacity`
- `insert`
- `insertValue`
- `replace`

### Interface Functions Inherited From TextConcept

- `stringSetLimits`
- `posLocalToX`
- `posLocalize`
- `posGlobalize`
- `getSeqNo`
- `getSeqOffset`

## Interface Metafunction Overview

### Interface Metafunctions Inherited From ContainerConcept

- `DefaultGetIteratorSpec`
- `DefaultIteratorSpec`
- `Difference`
- `DirectionIterator`
- `GetValue`
- `Iterator`
- `Position`
- `Reference`
- `Size`
- `Value`

### Interface Metafunctions Inherited From SegmentableConcept

- `Infix`
- `Prefix`
- `Suffix`

### Interface Metafunctions Inherited From TextConcept

- `SAValue`
- `StringSetLimits`

## Detailed Description

The External String enables to access sequences larger than the available internal memory (RAM) by using external memory (e.g. Hard disk, Network storage, ...) via a File object. Sequences of nearly arbitrary size can be accessed even larger than the logically addressable memory, i.e. they can in particular contain more than 2^32 elements on a 32bit system (see Tag.ExternalConfigLarge). See the String constructor for more details.

This String also supports fast appending and removing of values at the end (see Block String, appendValue)

The External String implements a LRU mechanism to swap out pages. The External String's Iterator detects a forward or backward iteration and asynchronously prefetches pages that certainly will be accessed and automatically swaps out pages that certainly won't be accessed any more in the iteration process.

The String is implemented like a virtual memory manager. It divides its character sequence into pages of a fixed length (e.g. 4MB) and maintains a page table with information for each page (e.g. resides in memory or was swapped out, is dirty and needs to be saved, ...). Besides the page table the String also contains a size-limited list of page frames. A page frame is reserved internal memory for a page. When accessing values of a page that is stored in external memory, the page is loaded to a page frame first. In case that there is no page frame free, another page is swapped out before to free a page frame.

## Member Functions Detail

### `String::String(); String::String(file); String::String(fileName[, openMode]);`

Constructor

#### Parameters

`file` | The File to use for reading and writing. You must ensure that `file` is open as the string will not call `open` and `close` on the file.
`fileName` | The path to open. Type: `char const *`
`openMode` | The open mode.

#### Remarks

When a file or file name is given, this file will be used for the ExternalString. If the file exists, this file will be used and determines the strings length and content. If the file doesn't exist, a new and empty file will be created and used for the string. In both cases, the string won't delete the file in the destructor.

When no file is given (default c'tor) the string will be empty and no file is used until the string needs to swap out page frames. Then a temporary file will be used which will be deleted when the string is destroyed.

Instead of giving file or fileName to the constructor, you could also use the default constructor and call open or openTemp afterwards to reach the same behaviour.

#### Data Races

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

## Interface Functions Detail

### `bool close(str);`

Close the external string.

#### Parameters

`str` | The ExternalString to close the file of.

#### Returns

`bool` | `true` if the closing succeeded, `false` otherwise.

#### Data Races

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

### `void flush(str);`

Waits for all open read/write requests to complete.

#### Parameters

`str` | The ExternalString to flush.

#### Data Races

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

### `bool open(str, fileName[, openMode]);`

Open the ExternalString's underlying file from a path.

#### Parameters

`str` | The ExternalString to open.
`fileName` | Path to the file to open. Type: `char const *`.
`openMode` | The open mode. Type: `int`.

#### Returns

`bool` | `true` if the operation succeeded and `false` otherwise.

#### Data Races

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

### `bool openTemp(str);`

Open an ExternalString using an temporary file.

#### Parameters

`str` | The ExternalString to open using temporary file.

#### Returns

`bool` | `true` if opening succeeded, `false` otherwise.

#### Data Races

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

#### Dox Sources

    /*!
     * @class ExternalString External String
     *
     * @extends String
     *
     * @headerfile <seqan/file.h>
     *
     * @brief String that is stored in external memory.
     *
     * @signature template <typename TValue[, typename TConfig]> class
     *            String<TValue, External<TConfig> >;
     *
     * @tparam TValue The type that is used for the items/characters stored in the
     *                string.
     * @tparam TConfig A structure to configure the external string. Defaults to
     *                 <tt>ExternalConfigLarge&lt;&gt;. See ExternalConfig,
     *                 ExternalConfigLarge, and ExternalConfigSize.
     *
     * The External String enables to access sequences larger than the available
     * internal memory (RAM) by using external memory (e.g. Hard disk, Network
     * storage, ...) via a File object. Sequences of nearly arbitrary size can be
     * accessed even larger than the logically addressable memory, i.e. they can in
     * particular contain more than 2^32 elements on a 32bit system (see
     * Tag.ExternalConfigLarge). See the String constructor for more details.
     *
     * This String also supports fast appending and removing of values at the end
     * (see Block String, appendValue)
     *
     * The External String implements a LRU mechanism to swap out pages. The
     * External String's Iterator detects a forward or backward iteration and
     * asynchronously prefetches pages that certainly will be accessed and
     * automatically swaps out pages that certainly won't be accessed any more in
     * the iteration process.
     *
     * The String is implemented like a virtual memory manager. It divides its
     * character sequence into pages of a fixed length (e.g. 4MB) and maintains a
     * page table with information for each page (e.g. resides in memory or was
     * swapped out, is dirty and needs to be saved, ...). Besides the page table the
     * String also contains a size-limited list of page frames. A page frame is
     * reserved internal memory for a page. When accessing values of a page that is
     * stored in external memory, the page is loaded to a page frame first. In case
     * that there is no page frame free, another page is swapped out before to free
     * a page frame.
     *
     * @fn ExternalString::String
     *
     * @brief Constructor
     *
     * @signature String::String();
     * @signature String::String(file);
     * @signature String::String(fileName[, openMode]);
     *
     * @param[in] file The @link File @endlink to use for reading and writing. You
     *                 must ensure that <tt>file</tt> is open as the string will not
     *                 call <tt>open</tt> and <tt>close</tt> on the file.
     * @param[in] fileName The path to open. Type: <tt>char const *</tt>
     * @param[in,out] openMode The open mode.
     *
     * @section Remarks
     *
     * When a file or file name is given, this file will be used for the
     * ExternalString. If the file exists, this file will be used and determines the
     * strings length and content. If the file doesn't exist, a new and empty file
     * will be created and used for the string. In both cases, the string won't
     * delete the file in the destructor.
     *
     * When no file is given (default c'tor) the string will be empty and no file is
     * used until the string needs to swap out page frames. Then a temporary file
     * will be used which will be deleted when the string is destroyed.
     *
     * Instead of giving file or fileName to the constructor, you could also use the
     * default constructor and call open or openTemp afterwards to reach the same
     * behaviour.
     *
     * @fn ExternalString#flush
     *
     * @brief Waits for all open read/write requests to complete.
     *
     * @signature void flush(str);
     *
     * @param[in,out] str The ExternalString to flush.
     *
     * @fn ExternalString#open
     *
     * @brief Open the ExternalString's underlying file from a path.
     *
     * @signature bool open(str, fileName[, openMode]);
     *
     * @param[in,out] str The ExternalString to open.
     * @param[in] fileName Path to the file to open. Type: <tt>char const *</tt>.
     * @param[in] openMode The open mode. Type: <tt>int</tt>.
     *
     * @return bool <tt>true</tt> if the operation succeeded and <tt>false</tt>
     *              otherwise.
     *
     * @fn ExternalString#openTemp
     *
     * @brief Open an ExternalString using an temporary file.
     *
     * @signature bool openTemp(str);
     *
     * @param[in,out] str The ExternalString to open using temporary file.
     *
     * @return bool <tt>true</tt> if opening succeeded, <tt>false</tt> otherwise.
     *
     * @fn ExternalString#close
     *
     * @brief Close the external string.
     *
     * @signature bool close(str);
     *
     * @param[in] str The ExternalString to close the file of.
     *
     * @return bool <tt>true</tt> if the closing succeeded, <tt>false</tt>
     *              otherwise.
     */