MMap String - SeqAn API Documentation

# Spec MMap String
String that is stored in external memory using direct memory mapping.

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, MMap<TConfig> >;`

## Template Parameters

`TValue` | The value type to use for the items/characters.
`TConfig` | The configuration to use for the underlying file. Default: MMapConfig.

## 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 MMapString.
- `void flush(str);`
  Waits for all open read/write requests to complete.
- `bool mmapAdvise(str, scheme[, beginPos, size]);`
  Call advise function for memory mapped files.
- `bool open(str, fileName[, openMode]);`
  Open the MMapString's underlying file from a path.
- `bool openTemp(str);`
  Open an MMapString 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

- `begin`
- `end`
- `length`
- `empty`
- `swap`
- `writeValue`
- `write`
- `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 MMap String enables to access sequences larger than the available physical memory (RAM) by using external memory (e.g. Hard disk, Network storage, ...) mapped into memory. The size of the string is limited by external memory and the logical address space (4GB on a 32bit OS). See the String constructor for more details.

This string also supports fast appending and removing of values at the end.

## 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 ensture 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.

#### Data Races

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

## Interface Functions Detail

### `bool close(str);`

Close the MMapString.

#### Parameters

`str` | The MMapString 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 MMapString to flush.

#### Data Races

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

### `bool mmapAdvise(str, scheme[, beginPos, size]);`

Call advise function for memory mapped files.

#### Parameters

`str` | The MMapString to call advise in.
`scheme` | The memory access scheme to use. Type: FileMappingAdvise.
`beginPos` | Begin position in the string for the advise call.
`size` | Size of the range used for the advise call.

#### Returns

`bool` | `true` if the advise was successful, `false` otherwise.

#### Data Races

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

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

Open the MMapString's underlying file from a path.

#### Parameters

`str` | The MMapString 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 MMapString using an temporary file.

#### Parameters

`str` | The MMapString 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 MMapString MMap String
     *
     * @extends String
     *
     * @headerfile <seqan/file.h>
     *
     * @brief String that is stored in external memory using direct memory mapping.
     *
     * @signature template <typename TValue[, typename TConfig]> class
     *            String<TValue, MMap<TConfig> >;
     *
     * @tparam TValue The value type to use for the items/characters.
     * @tparam TConfig The configuration to use for the underlying file. Default:
     *                 @link MMapConfig @endlink.
     *
     * The MMap String enables to access sequences larger than the available
     * physical memory (RAM) by using external memory (e.g. Hard disk, Network
     * storage, ...) mapped into memory. The size of the string is limited by
     * external memory and the logical address space (4GB on a 32bit OS). See the
     * String constructor for more details.
     *
     * This string also supports fast appending and removing of values at the end.
     *
     * @fn MMapString::String
     *
     * @brief Constructor.
     *
     * @signature String::String();
     * @signature String::String(file);
     * @signature String::String(fileName[, openMode]);
     *
     * @param[in,out] file The @link File @endlink to use for reading and writing.
     *                     You must ensture 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] openMode The open mode.
     *
     * @fn MMapString#flush
     *
     * @brief Waits for all open read/write requests to complete.
     *
     * @signature void flush(str);
     *
     * @param[in,out] str The MMapString to flush.
     *
     * @fn MMapString#mmapAdvise
     *
     * @brief Call advise function for memory mapped files.
     *
     * @signature bool mmapAdvise(str, scheme[, beginPos, size]);
     *
     * @param[in,out] str The MMapString to call advise in.
     * @param[in] scheme The memory access scheme to use. Type: FileMappingAdvise.
     * @param[in] beginPos Begin position in the string for the advise call.
     * @param[in] size Size of the range used for the advise call.
     *
     * @return bool <tt>true</tt> if the advise was successful, <tt>false</tt>
     *              otherwise.
     *
     * @fn MMapString#open
     *
     * @brief Open the MMapString's underlying file from a path.
     *
     * @signature bool open(str, fileName[, openMode]);
     *
     * @param[in,out] str The MMapString 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 MMapString#openTemp
     *
     * @brief Open an MMapString using an temporary file.
     *
     * @signature bool openTemp(str);
     *
     * @param[in,out] str The MMapString to open using temporary file.
     *
     * @return bool <tt>true</tt> if opening succeeded, <tt>false</tt> otherwise.
     *
     * @fn MMapString#close
     *
     * @brief Close the MMapString.
     *
     * @signature bool close(str);
     *
     * @param[in] str The MMapString to close the file of.
     *
     * @return bool <tt>true</tt> if the closing succeeded, <tt>false</tt>
     *              otherwise.
     */