/*!
* @concept StreamConcept
*
* @headerfile <seqan/stream.h>
*
* @brief Concept for I/O streams.
*
* @signature concept StreamConcept;
*
* @mfn StreamConcept#HasStreamFeature
*
* @brief Query features of a stream type.
*
* @signature HasStreamFeature<TStream, TTag>::Type;
*
* @tparam TStream The strema type to query the property of.
* @tparam TTag A tag to select a feature.
*
* @return Type Either <tt>True</tt> or <tt>False</tt>.
*
* @section Remarks
*
* Note that this only checks whether the type principally has this feature. For
* example, if a stream wraps a Unix pipe internally, seek might always fail.
*
* @mfn StreamConcept#Size
*
* @headerfile <seqan/stream.h>
*
* @brief Return the size type for a stream.
*
* @signature Size<TStream>::Type;
*
* @tparam TStream The stream to query for its size type.
*
* @return Type The size type of <tt>TStream</tt>.
*
* @fn StreamConcept#streamSeek
*
* @headerfile <seqan/stream.h>
*
* @brief Perform a seek operation on the stream.
*
* @signature int streamSeek(stream, delta, origin);
*
* @param[in,out] stream The stream object to seek on.
* @param[in] delta The (relative) position. Type: <tt>__int64</tt>
* @param[in] origin Where to seek from, we use the integers from
* <cstdio>. Possible values are <tt>SEEK_SET</tt>,
* <tt>SEEK_CUR</tt>, and <tt>SEEK_END</tt>. Type:
* <tt>int</tt>
*
* @return int A status code, 0 on success, non-0 value on errors.
*
* @see StreamConcept#streamTell
*
* @fn StreamConcept#streamPut
*
* @headerfile <seqan/stream.h>
*
* @brief Write different types to stream
*
* @signature int streamPut(stream, source);
*
* @param[in,out] stream The stream object to write to. Types: StreamConcept
* @param[in] source The data to write to the stream.
*
* @return int A status code, 0 on success, non-0 value on errors.
*
* @section Remarks
*
* Implementation note: for some specializations of @link StreamConcept @endlink
* certain conversions take place through stringstream and a buffer of size
* 1023. It follows that the result of the conversion cannot be longer. However
* this should only effect numericals right now. If you still encounter
* truncated strings with another type, convert to <tt>const char*</tt> manually
* before writing.
*
* @see StreamConcept#streamWriteChar
* @see StreamConcept#streamWriteBlock
*
* @fn StreamConcept#streamWriteBlock
*
* @headerfile <seqan/stream.h>
*
* @brief Write a block of bytes from a buffer into a stream.
*
* @signature TReturn streamWriteBlock(stream, source, count);
*
* @param[in,out] stream The stream object to write to. Types: StreamConcept
* @param[in] source The data to write to the stream. Types: nolink:<tt>char
* *</tt>
* @param[in] count The number of bytes to write to the stream.
*
* @return TSize The number of successfully written objects (Metafunction: @link
* StreamConcept#Size @endlink).
*
* @section Examples
*
* Copying data from a std::fstream into another std::fstream using SeqAn's
* stream adaption.
*
* @code{.cpp}
* #include <fstream>
* #include <seqan/sequence.h>
* #include <seqan/stream.h>
*
* int main()
* {
* std::fstream in("in.txt", std::ios::binary | std::ios::in);
* std::fstream out("out.txt", std::ios::binary | std::ios::in);
*
* seqan::CharString buffer;
* resize(buffer, 1000);
*
* while (!seqan::atEnd(in) && seqan::streamError(in) == 0)
* {
* int num = seqan::streamReadBlock(&buffer[0], in, length(buffer));
* seqan::streamWriteBlock(out, &buffer[0], num);
* }
*
* return 0;
* }
* @endcode
*
*
* @see StreamConcept#streamWriteChar
* @see StreamConcept#streamPut
*
* @fn StreamConcept#streamPeek
*
* @headerfile <seqan/stream.h>
*
* @brief Read next character from stream without advancing current position.
*
* @signature int streamPeek(c, stream);
*
* @param[out] c The read character is written here. Type: <tt>char &</tt>.
* @param[in,out] stream The stream object to read from.
*
* @return int 0 on success, otherwise the error value from the underlying
* string system.
*
* @section Remarks
*
* Note that this might involve two calls into the stream library, e.g. for
* cstdio streams, it involves a call to both <tt>getc()</tt> and
* <tt>ungetc()</tt>.
*
* @see StreamConcept#streamReadChar
* @see StreamConcept#streamReadBlock
*
* @fn StreamConcept#streamReadBlock
*
* @headerfile <seqan/stream.h>
*
* @brief Read a block of bytes into a buffer.
*
* @signature TSize streamReadBlock(target, stream, maxLen)
*
* @param[in] maxLen maximal number of characters to read (<tt>size_t</tt>).
* @param[out] target The buffer to read into. There has to be enough space for
* <tt>maxLen</tt> bytes (<tt>char *</tt>).
* @param[in,out] stream The stream to read from.
*
* @return TSize Number of read bytes (Metafunction: @link StreamConcept#Size
* @endlink).
*
* @section Examples
*
* Copying data from a std::fstream into another std::fstream using SeqAn's
* stream adaption.
*
* @code{.cpp}
* #include <fstream>
* #include <seqan/sequence.h>
* #include <seqan/stream.h>
*
* int main()
* {
* std::fstream in("in.txt", std::ios::binary | std::ios::in);
* std::fstream out("out.txt", std::ios::binary | std::ios::in);
*
* seqan::CharString buffer;
* resize(buffer, 1000);
*
* while (!seqan::atEnd(in) && seqan::streamError(in) == 0)
* {
* int num = seqan::streamReadBlock(&buffer[0], in, length(buffer));
* seqan::streamWriteBlock(out, &buffer[0], num);
* }
*
* return 0;
* }
* @endcode
*
*
* @see StreamConcept#streamPeek
* @see StreamConcept#streamReadChar
*
* @fn StreamConcept#streamTell
*
* @headerfile <seqan/stream.h>
*
* @brief Get the position in the current stream.
*
* @signature TPos streamTell(stream);
*
* @param[in] stream The stream object to query the current position for.
*
* @return TPos The position within the stream.
*
* @see StreamConcept#streamSeek
*
* @fn StreamConcept#streamError
*
* @headerfile <seqan/stream.h>
*
* @brief Return the stream's error code.
*
* @signature int streamError(stream);
*
* @param[in] stream The stream object to query.
*
* @return int An error code, 0 is used for "no errors."
*
* @fn StreamConcept#streamWriteChar
*
* @headerfile <seqan/stream.h>
*
* @brief Write one character to the stream.
*
* @signature int streamWriteChar(stream, c);
*
* @param[in,out] stream The stream object to write to.
* @param[in] c The character to write to the stream. Types: <tt>char</tt>
*
* @return int Error code, 0 on success.
*
* @see StreamConcept#streamWriteBlock
* @see StreamConcept#streamPut
*
* @fn StreamConcept#streamReadChar
*
* @headerfile <seqan/stream.h>
*
* @brief Read next character from stream and advance the current position.
*
* @signature int streamReadChar(c, stream);
*
* @param[out] c The read character is written here. Types: <tt>char &</tt>
* @param[in,out] stream The stream object to read from.
*
* @return TReturn <tt>int</tt>, 0 on success, otherwise the error value from
* the underlying string system.
*
* @see StreamConcept#streamPeek
* @see StreamConcept#streamReadBlock
*
* @fn StreamConcept#streamEof
*
* @headerfile <seqan/stream.h>
*
* @brief Check end-of-file state of a @link StreamConcept @endlink.
*
* @signature bool streamEof(stream);
*
* @param[in] stream The stream object to check.
*
* @return bool true if the stream is in end-of-file state, false otherwise.
*
* @section Remarks
*
* Note that the exact behaviour depends on the underlying implementation. With
* <tt>FILE *</tt> streams, the stream can be in the end-of-file state from the
* point where the last character was read or from the point where the user
* tried to read beyond the end of the file.
*
* @fn StreamConcept#streamFlush
*
* @headerfile <seqan/stream.h>
*
* @brief Flush the underlying stream.
*
* @signature int streamFlush(stream);
*
* @param[in,out] stream The stream object to flush.
*
* @return int with an error code, 0 on success.
*
* @fn StreamConcept#writeRecord
*
* @headerfile <seqan/stream.h>
*
* @brief Write one record (e.g. a single DNA-sequence and its meta data) to a
* @link StreamConcept @endlink
*
* @signature int writeRecord(stream, RECORD, tag);
*
* @param[in] RECORD possibly multiple fields (e.g. meta and sequence)
* @param[in] tag The file format tag
* @param[in,out] stream The Stream object to write to. Type: StreamConcept
*
* @return int An integer with the status code (0 on success).
*
* @see StreamConcept#write2
*
* @fn StreamConcept#write2
*
* @headerfile <seqan/stream.h>
*
* @brief Writes an entire document to a @link StreamConcept @endlink.
*
* @signature write2(stream, DOCUMENT, tag);
*
* @param[in,out] stream The Stream object to write to. Types: StreamConcept
* @param[in] DOCUMENT Format specific possibly multiple StringSets (e.g. of
* meta and sequences).
* @param[in] tag The file format tag
*
* @section Status
*
* Should be renamed to "write" once the old IO-Code is removed
*
* @see StreamConcept#writeRecord
*/