/* +------------------------------------------------------------------------+
   |                     Mobile Robot Programming Toolkit (MRPT)            |
   |                          https://www.mrpt.org/                         |
   |                                                                        |
   | Copyright (c) 2005-2023, Individual contributors, see AUTHORS file     |
   | See: https://www.mrpt.org/Authors - All rights reserved.               |
   | Released under BSD License. See: https://www.mrpt.org/License          |
   +------------------------------------------------------------------------+ */
#pragma once

#include <mrpt/core/common.h>  // MRPT_printf_format_check

#include <cstdint>
#include <string>

namespace mrpt::io
{
/** This base class is used to provide a unified interface to
 *    files,memory buffers,..Please see the derived classes. This class is
 *    largely inspired by Borland VCL "TStream" class. <br><br>
 *  Apart of the "VCL like" methods, operators ">>" and "<<" have been
 *    defined so that simple types (int,bool,char,float,char *,std::string,...)
 *    can be directly written and read to and from any CStream easily.
 *  Please, it is recomendable to read CSerializable documentation also.
 *
 * \ingroup mrpt_io_grp
 * \sa CFileStream, CMemoryStream,CSerializable
 */
class CStream
{
   public:
	/** Used in CStream::Seek */
	enum TSeekOrigin
	{
		sFromBeginning = 0,
		sFromCurrent = 1,
		sFromEnd = 2
	};

	/** Introduces a pure virtual method responsible for reading from the
	 * stream. */
	virtual size_t Read(void* Buffer, size_t Count) = 0;

	/** Introduces a pure virtual method responsible for writing to the stream.
	 *  Write attempts to write up to Count bytes to Buffer, and returns the
	 * number of bytes actually written. */
	virtual size_t Write(const void* Buffer, size_t Count) = 0;

	/** Constructor */
	CStream() = default;

	/** Destructor */
	virtual ~CStream();

	/** Reads a block of bytes from the stream into Buffer, and returns the
	 *amound of bytes actually read, without waiting for more extra bytes to
	 *arrive (just those already enqued in the stream).
	 *  Note that this method will fallback to ReadBuffer() in most CStream
	 *classes but in some hardware-related  classes.
	 *	\exception std::exception On any error, or if ZERO bytes are read.
	 */
	virtual size_t ReadBufferImmediate(void* Buffer, size_t Count)
	{
		return Read(Buffer, Count);
	}

	/** Introduces a pure virtual method for moving to a specified position in
	 *the streamed resource.
	 *   he Origin parameter indicates how to interpret the Offset parameter.
	 *Origin should be one of the following values:
	 *	- sFromBeginning	(Default) Offset is from the beginning of the
	 *resource. Seek moves to the position Offset. Offset must be >= 0.
	 *	- sFromCurrent		Offset is from the current position in the resource.
	 *Seek moves to Position + Offset.
	 *	- sFromEnd			Offset is from the end of the resource. Offset must
	 *be
	 *<= 0 to indicate a number of bytes before the end of the file.
	 * \return Seek returns the new value of the Position property.
	 */
	virtual uint64_t Seek(
		int64_t Offset, CStream::TSeekOrigin Origin = sFromBeginning) = 0;

	/** Returns the total amount of bytes in the stream.
	 */
	virtual uint64_t getTotalBytesCount() const = 0;

	/** Method for getting the current cursor position, where 0 is the first
	 * byte and TotalBytesCount-1 the last one.
	 */
	virtual uint64_t getPosition() const = 0;

	/** Writes a string to the stream in a textual form.
	 * \sa CStdOutStream
	 */
	virtual int printf(const char* fmt, ...)
		MRPT_printf_format_check(2, 3);	 // The first argument (1) is "this" !!!

	/** Prints a vector in the format [A,B,C,...] using CStream::printf, and the
	 * fmt string for <b>each</b> vector element `T`.
	 * \tparam CONTAINER_TYPE can be any vector<T>, deque<T> or alike. */
	template <typename CONTAINER_TYPE>
	void printf_vector(
		const char* fmt, const CONTAINER_TYPE& V, char separator = ',')
	{
		this->printf("[");
		const size_t N = V.size();
		for (size_t i = 0; i < N; i++)
		{
			this->printf(fmt, V[i]);
			if (i != (N - 1)) this->printf("%c", separator);
		}
		this->printf("]");
	}

	/** Reads from the stream until a `\n` character is found (`\r` characters
	 * are ignored).
	 * \return false on EOF or any other read error.
	 */
	bool getline(std::string& out_str);

	/** Returns a human-friendly description of the stream, e.g. a filename. */
	virtual std::string getStreamDescription() const
	{
		return "Generic mrpt::io::CStream";
	}

};	// End of class def.

}  // namespace mrpt::io
