// DWBS ------------------------------------------------------------------ DWBS
//
// PLATFORM		: ALL
// PRODUCT		: BIT_DEMON
// VISIBILITY	: PUBLIC
//
// DWBS ------------------------------------------------------------------ DWBS

// PURPOSE: Used for writing to & reading from a file.

#ifndef BD_STDIO_FILE_STREAMBUF_H
#define BD_STDIO_FILE_STREAMBUF_H

#include <bdCore/bdMemory/bdMemory.h>
#include <bdCore/bdStreams/bdStdioStreambuf.h>

/// A stream buffer that can be used for output or input to or from a file.
/// This class inherits from bdStdioStreambuf and hence uses the standard
/// i/o routines of <cstdio.h> for file reads and writes.
class bdStdioFileStreambuf : public bdStdioStreambuf
{
	public:

		BD_DECLARE_NEW_AND_DELETE_OPERATORS

		/// Supported file opening modes.
		/// READ indicates a file it to be opened for output.
		/// Any existing contents will be erased.
		/// WRITE indicates a file it to be opened for input.
		/// The file must exist.
		/// APPEND indicates a file it to be opened for output. New output
		/// will be appended at the end of the file.
		enum OpenMode
		{
			READ,
			WRITE,
			APPEND
		};

		/// Constructor, attempts to initialize the stream buffer using
		/// the given file name and OpenMode. If the file cannot be opened
		/// or created, depending on the OpenMode, this constructor may
		/// indicate failure by setting the END_OF_FILE flag.
		/// \param filename[in] Create a stream buffer using this filename.
		/// \param mode[in] The mode to use when opening the file.
		/// \remark It is always a good idea to call bdStreambuf::isOk()
		///  before proceeding with any further stream operations since
		///  it is possible that opening/creating the file may fail.
		bdStdioFileStreambuf(const bdNChar8 *const filename,
							 const OpenMode mode);

		/// Destructor, flushes and closes the open file.
		~bdStdioFileStreambuf();
};

#endif // BD_STDIO_FILE_STREAMBUF_H
