From a82c33c314287b5e888939eddbb55ee395d7e83d Mon Sep 17 00:00:00 2001 From: Gawaboumga Date: Sun, 21 Feb 2016 14:36:49 +0100 Subject: [PATCH] Documentation for Stream Former-commit-id: 0e77be8d238879c114c5e7b166ae646254fac9eb --- include/Nazara/Core/Stream.inl | 71 ++++++++++++++++++++++++++++++++++ src/Nazara/Core/Stream.cpp | 46 +++++++++++++++++++++- 2 files changed, 115 insertions(+), 2 deletions(-) diff --git a/include/Nazara/Core/Stream.inl b/include/Nazara/Core/Stream.inl index 104d5e300..fa90682b0 100644 --- a/include/Nazara/Core/Stream.inl +++ b/include/Nazara/Core/Stream.inl @@ -7,12 +7,25 @@ namespace Nz { + /*! + * \brief Constructs a Stream object with options + * + * \param streamOptions Options for the stream + * \param openMode Reading/writing mode for the stream + */ + inline Stream::Stream(UInt32 streamOptions, UInt32 openMode) : m_openMode(openMode), m_streamOptions(streamOptions) { } + /*! + * \brief Enables the text mode + * + * \param textMode Enables the mode or disables + */ + inline void Stream::EnableTextMode(bool textMode) { if (textMode) @@ -21,6 +34,12 @@ namespace Nz m_streamOptions &= ~StreamOption_Text; } + /*! + * \brief Flushes the stream + * + * \remark Produces a NazaraAssert if file is not writable + */ + inline void Stream::Flush() { NazaraAssert(IsWritable(), "Stream is not writable"); @@ -28,36 +47,77 @@ namespace Nz FlushStream(); } + /*! + * \brief Gets the open mode of the stream + * \return Reading/writing mode for the stream + */ + inline UInt32 Stream::GetOpenMode() const { return m_openMode; } + /*! + * \brief Gets the options of the stream + * \return Options of the stream + */ + inline UInt32 Stream::GetStreamOptions() const { return m_streamOptions; } + /*! + * \brief Checks whether the stream is readable + * \return true if it is the case + */ + inline bool Stream::IsReadable() const { return (m_openMode & OpenMode_ReadOnly) != 0; } + /*! + * \brief Checks whether the stream is sequential + * \return true if it is the case + */ + inline bool Stream::IsSequential() const { return (m_streamOptions & StreamOption_Sequential) != 0; } + /*! + * \brief Checks whether the stream has text mode enabled + * \return true if it is the case + */ + inline bool Stream::IsTextModeEnabled() const { return (m_streamOptions & StreamOption_Text) != 0; } + /*! + * \brief Checks whether the stream can be written + * \return true if it is the case + */ + inline bool Stream::IsWritable() const { return (m_openMode & OpenMode_WriteOnly) != 0; } + /*! + * \brief Reads the stream and puts the result in a buffer + * \return Size of the read + * + * \param buffer Buffer to stock data + * \param size Size meant to be read + * + * \remark Produces a NazaraAssert if stream is not readable + * \remark If preallocated space of buffer is less than the size, the behaviour is undefined + */ + inline std::size_t Stream::Read(void* buffer, std::size_t size) { NazaraAssert(IsReadable(), "Stream is not readable"); @@ -65,6 +125,17 @@ namespace Nz return ReadBlock(buffer, size); } + /*! + * \brief Writes in the stream the content of a buffer + * \return Size of the writing + * + * \param buffer Buffer to get data from + * \param size Size meant to be written + * + * \remark Produces a NazaraAssert if stream is not writable + * \remark If preallocated space of buffer is less than the size, the behaviour is undefined + */ + inline std::size_t Stream::Write(const void* buffer, std::size_t size) { NazaraAssert(IsWritable(), "Stream is not writable"); diff --git a/src/Nazara/Core/Stream.cpp b/src/Nazara/Core/Stream.cpp index f8aab413e..3ddcb9fc7 100644 --- a/src/Nazara/Core/Stream.cpp +++ b/src/Nazara/Core/Stream.cpp @@ -11,22 +11,50 @@ namespace Nz { + /*! + * \class Nz::Stream + * \brief Core class that represents a stream + */ + + /*! + * \brief Destructs the object + */ + Stream::~Stream() = default; + /*! + * \brief Gets the directory of the stream + * \return Empty string (meant to be virtual) + */ + String Stream::GetDirectory() const { return String(); } + /*! + * \brief Gets the path of the stream + * \return Empty string (meant to be virtual) + */ + String Stream::GetPath() const { return String(); } + /*! + * \brief Reads characters in the stream + * \return Line containing characters + * + * \param lineSize Number of characters to read, if lineSize is 0, read as much as possible + * + * \remark Produces a NazaraWarning if cursor position could not be reset + */ + String Stream::ReadLine(unsigned int lineSize) { String line; - if (lineSize == 0) // Taille maximale indéterminée + if (lineSize == 0) // Maximal size undefined { const unsigned int bufferSize = 64; @@ -63,7 +91,7 @@ namespace Nz line.Set(lineSize, '\0'); std::size_t readSize = Read(&line[0], lineSize); std::size_t pos = line.Find('\n'); - if (pos <= readSize) // Faux uniquement si le caractère n'est pas présent (npos étant le plus grand entier) + if (pos <= readSize) // False only if the character is not available (npos being the biggest integer) { if (m_streamOptions & StreamOption_Text && pos > 0 && line[pos - 1] == '\r') line.Resize(pos); @@ -80,12 +108,26 @@ namespace Nz return line; } + /*! + * \brief Writes a ByteArray into the stream + * \return true if successful + * + * \param byteArray Bytes to write + */ + bool Stream::Write(const ByteArray& byteArray) { ByteArray::size_type size = byteArray.GetSize(); return Write(byteArray.GetConstBuffer(), size) == size; } + /*! + * \brief Writes a String into the stream + * \return true if successful + * + * \param string String to write + */ + bool Stream::Write(const String& string) { String temp(string);