Streams
class Stream
Stream is the base class of all U++ streams.
U++ streams generally serve in three different roles:
As basic raw binary streams.
As text output with enhanced indentation feature. This is realized by storing indentation level in the stream and inserting the corresponding number of '\t' characters at the beginning of each line (Putf method must be used instead of Put).
As binary serialization target/source. This mainly needs to store flag indicating serialization direction.
In order to achieve optimal performance of buffered stream operations, the most frequent operations have a little bit more complicated implementation that demands proper definition of virtual methods, as they must correctly adjust some protected data members of Stream. Therefore the implementation of some method can be considered a part of interface definition:
void Stream::Put(int c)
{
if(ptr < wrlim)
*ptr++ = c;
else
_Put(c);
}
int Stream::Term()
{
return ptr < rdlim ? *ptr : _Term();
}
int Stream::Get()
{
return ptr < rdlim ? *ptr++ : _Get();
}
int64 Stream::GetPos() const
{
return dword(ptr - buffer) + pos;
}
Protected members for Stream implementation
int64 pos
Protected.
Position of buffer in the stream.
byte *buffer
Protected.
Pointer to beginning of buffer.
byte *ptr
Protected.
Pointer to current input/output byte.
byte *rdlim
Protected.
Read limit. Get method returns values from buffer as long as ptr < rdlim.
byte *wrlim
Protected.
Write limit. Put method returns values from buffer as long as ptr < wrlim.
virtual void _Put(int w)
Called by Put method in case that output byte cannot be stored into buffer (ptr >= wrlim). If Stream wants to use buffering, this method should adjust buffer, ptr and wrlim.
virtual int _Term()
Called by Term method in case that input byte is not in buffer (ptr >= rdlim). If Stream wants to use buffering, this method should adjust buffer, ptr and rdlim.
|
Return value |
Value at current position in the stream. Current position is not advanced. |
virtual int _Get()
Called by Get method in case that input byte is not in buffer (ptr >= rdlim). If Stream wants to use buffering, this method should adjust buffer, ptr and rdlim.
|
Return value |
Value read from the stream. |
virtual void _Put(const void *data, dword size)
Directly called by Put method. Writes a block of binary data.
virtual dword _Get(void *data, dword size)
Directly called by Get method.
Raw stream
virtual void Seek(int64 pos)
Seeks to given position.
virtual int64 GetSize() const
|
Return value |
Size of stream. |
virtual void SetSize(int64 size)
Alters the size of the stream.
virtual void Flush()
If stream has any internal buffers (like FileStream), writes these bufers to OS.
virtual void Close()
Closes stream.
virtual bool IsOpen() const = 0
|
Return value |
true if stream is open. |
bool IsError() const
|
Return value |
true if error was encountered during stream operations since opening it or last ClearError call - error code is non-zero. |
bool IsOK() const
void SetError(int c = 0)
Sets stream error code.
void SetLastError()
Sets stream error to last OS-specific error (obtained e.g. by GetLastError call in Win32 or in errno in Posix). This error can be interpreted by GetErrorMessage function.
int GetError() const
|
Return value |
Current error-code. Zero indicates no error. |
void ClearError()
Clears error code.
int64 GetPos() const
|
Return value |
Current position in the stream. |
bool IsEof() const
|
Return value |
There are no more byte to be read from the stream. Is also true in case of error. |
int64 GetLeft() const
|
Return value |
Bytes between current position and the end of stream - equivalent to GetSize() - GetPos(). |
void SeekEnd(int64 rel = 0)
Sets current position in the stream relative to the end of stream. Same as Seek(GetSize() + rel).
|
rel |
Position - should be less or equal to zero. |
void SeekCur(int64 rel)
Sets current position in the stream relative to the current position. Same as Seek(GetPos() + rel).
void Put(int c)
Puts single byte into the output stream.
int Term()
Peeks byte from input stream not advancing current position. If there are no more bytes in input stream or error occurred, negative value is returned.
|
Return value |
Byte at current position in the stream. |
int Get()
Reads single byte from input stream, advancing current position. If there are no more bytes in input stream or error occurred, negative value is returned.
|
Return value |
Byte read from input stream. |
void Put(const void *data, dword size)
Writes a block of raw binary data to the output stream.
|
size |
Number of bytes to write. |
dword Get(void *data, dword size)
Reads a block of raw binary data from the input stream.
|
data |
Pointer to buffer to receive the data. |
|
size |
Number of bytes to read. |
|
Return value |
Number of bytes actually read (lower or equal to the requested size). |
String Get(dword size)
Reads a block of raw binary data from the input stream. The number of bytes read is the length of String.
void LoadThrowing()
Sets stream into the mode that throws LoadingError exception when LoadError is invoked. This mode is typical for serialization usage of stream.
void LoadError()
Performs SetError(ERROR_LOADING_FAILED). If Stream set to the LoadThrowing mode (by LoadThrowing() method), LoadingError exception is thrown.
bool GetAll(void *data, dword size)
Reads a block of raw binary data from the stream. If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
data |
Pointer to buffer to receive the data. |
|
size |
Number of bytes to read. |
|
Return value |
true if required number of bytes was read. |
int Get8()
Reads a single byte from the stream. If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception) - this is the difference from Get() method.
|
Return value |
Byte from stream or -1. |
int Get16()
Reads 16-bit value from the stream in platform specific format (either little-endian or big-endian). If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
Return value |
16-bit value. |
int Get32()
Reads 32-bit value from the stream in platform specific format (either little-endian or big-endian). If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
Return value |
32-bit value. |
int64 Get64()
Reads 64-bit value from the stream in platform specific format (either little-endian or big-endian). If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
Return value |
64-bit value. |
int Get16le()
Reads 16-bit value from the stream in the little-endian mode. If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
Return value |
16-bit value. |
int Get32le()
Reads 32-bit value from the stream in the little-endian mode. If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
Return value |
32-bit value. |
int64 Get64le()
Reads 64-bit value from the stream in the little-endian mode. If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
Return value |
64-bit value. |
int Get16be()
Reads 16-bit value from the stream in the big-endian mode. If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
Return value |
16-bit value. |
int Get32be()
Reads 32-bit value from the stream in the big-endian mode. If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
Return value |
32-bit value. |
int64 Get64be()
Reads 32-bit value from the stream in the big-endian mode. If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
|
Return value |
64-bit value. |
String GetLine()
Reads single line from the stream. Line is delimited by '\n' character or the end of file (or error). '\r' characters are ignored.
|
Return value |
Line from the stream. |
int GetUtf8()
Reads single utf-8 encoded value from the stream.
|
Return value |
Utf-8 value. |
void Put16(word q)
Writes 16-bit value in platform specific format (either little-endian or big-endian).
void Put32(int q)
Writes 32-bit value in platform specific format (either little-endian or big-endian).
void Put64(int64 q)
Writes 64-bit value in platform specific format (either little-endian or big-endian).
void Put16le(word q)
Writes 16-bit value in little-endian mode.
void Put32le(int q)
Writes 32-bit value in little-endian mode.
void Put64le(int64 q)
Writes 64-bit value in little-endian mode.
void Put16be(word q)
Writes 16-bit value in big-endian mode.
void Put32be(int q)
Writes 32-bit value in big-endian mode.
void Put64be(int64 q)
Writes 64-bit value in big-endian mode.
void PutUtf8(int c)
Puts a single utf-8 value to the stream.
void Put(const char *s)
Writes zero terminated string to the stream (zero is not written).
void Put(const String& s)
Writes String to the the stream. String can contain zero characters.
void Put(int c, int count)
Writes single byte to the stream requested number of times.
void Put0(int count)
Writes zero byte to the stream requested number of times. This variation is mainly provided because Put(0, count) causes ambiguity as 0 is considered as NULL pointer too...
void PutW(const wchar *s, int count)
Writes a specified number of wchars (16-bit character values) to the stream in platform specific format (little-endian or big-endian).
dword GetW(wchar *s, int count)
Reads a specified number of wchars (16-bit character values) from the stream in platform specific format.
|
s |
Pointer to buffer to receive wchars. |
|
Return value |
Number of wchars actually read. |
bool GetAllW(wchar *s, int count)
Reads a specified number of wchars (16-bit character values) from the stream in platform specific format. If there is not enough data in the stream, LoadError is invoked (that in turn might throw an exception).
void PutCrLf()
Writes CR-LF pair to the stream.
void PutEol()
Writes platform specific "end of line" to the stream. It is CR-LF pair on Win32 platform or single LF on Posix platform.
void PutLine(const char *s)
Writes a line to stream - equivalent of Put(s); PutEol();
|
s |
Zero-terminated string. |
void PutLine(const String& s)
Writes a line to stream - equivalent of Put(s); PutEol();
void Put(Stream& s, int64 size = INT64_MAX, dword click = 4096)
Writes a content of specified stream to the stream.
|
size |
Maximum number of bytes to write. Default value INT64_MAX means whole input stream from current position to the end is written. |
|
click |
Size of buffer used for copying. |
Formated output
void Putf(int c)
Formated output - each start of line (that is, byte passed by Putf after '\n') is indented using '\t' characters, as controlled by Begin/End methods. Also, '\n' are translated by PutEol and '\r' are ignored.
void Putf(const char *s)
Outputs zero terminated string using Putf method.
void Putf(const String& s)
Outputs String using Putf.
void Begin()
Increases Putf line indentation level by 1.
void End()
Decreases Putf line indentation level by 1.
Stream& operator<<(BeginIndentEnum)
Calls Begin() - BeginIndentEnum has single value - "BeginIndent".
|
Return value |
Stream for operator<< chaining. |
Stream& operator<<(EndIndentEnum)
Calls End() - EndIndentEnum has single value - "EndIndent".
|
Return value |
Stream for operator<< chaining. |
Serialization support
void SetLoading()
Sets the stream into the loading mode.
void SetStoring()
Sets the stream into the storing mode.
bool IsLoading()
|
Return value |
true if stream is in loading mode. |
bool IsStoring()
|
Return value |
true if stream is in storing mode. |
void SerializeRaw(byte *data, dword count)
Serializes raw 8-bit data. Might invoke LoadError if there is not enough data to load.
|
data |
Pointer to data to store or buffer to receive loaded data. |
|
count |
Number of bytes to load/store. |
void SerializeRaw(word *data, dword count)
Serializes raw 16-bit data. Might invoke LoadError if there is not enough data to load.
|
data |
Pointer to data to store or buffer to receive loaded data. |
|
count |
Number of values to load/store. |
void SerializeRaw(dword *data, dword count)
Serializes raw 32-bit data. Might invoke LoadError if there is not enough data to load.
|
data |
Pointer to data to store or buffer to receive loaded data. |
|
count |
Number of values to load/store. |
void SerializeRaw(uint64 *data, dword count)
Serializes raw 64-bit data. Might invoke LoadError if there is not enough data to load.
|
data |
Pointer to data to store or buffer to receive loaded data. |
|
count |
Number of values to load/store. |
Stream& operator%(bool& d)
Serializes bool variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(char& d)
Serializes char variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(signed char& d)
Serializes signed char variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(unsigned char& d)
Serializes unsigned char variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(short& d)
Serializes short variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(unsigned short& d)
Serializes unsigned short variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(int& d)
Serializes int variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(unsigned int& d)
Serializes unsigned int variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(long& d)
Serializes long variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(unsigned long& d)
Serializes unsigned long variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(float& d)
Serializes float variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(double& d)
Serializes double variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(int64& d)
Serializes int64 variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(uint64& d)
Serializes uint64 variable. Might invoke LoadError if there is not enough data to load.
|
Return value |
*this for chaining. |
Stream& operator%(String& s)
Serializes String variable. Might invoke LoadError if there is not enough data to load or input data are invalid.
|
Return value |
*this for chaining. |
Stream& operator/(String& s)
Serializes String variable using RLE compression and packed format for length. Might invoke LoadError if there is not enough data to load or input data are invalid.
|
Return value |
*this for chaining. |
Stream& operator%(WString& s)
Serializes WString variable. Might invoke LoadError if there is not enough data to load or input data are invalid.
|
Return value |
*this for chaining. |
Stream& operator/(WString& s)
Serializes String variable using RLE compression and packed format for length. Might invoke LoadError if there is not enough data to load or input data are invalid.
|
Return value |
*this for chaining. |
void Pack(dword& i)
Serializes dword value using format optimized for storing small values. Values 0..254 are stored as serializes as single byte, other values result in 5 bytes. Might invoke LoadError if there is not enough data to load or input data are invalid.
Stream& operator/(int& i)
Serializes int value using format optimized for storing small values. Might invoke LoadError if there is not enough data to load or input data are invalid.
|
Return value |
*this for chaining. |
Stream& operator/(unsigned int& i)
Serializes unsigned int value using format optimized for storing small values. Might invoke LoadError if there is not enough data to load or input data are invalid.
|
Return value |
*this for chaining. |
void Magic(dword magic = 0x7d674d7b)
Serializes "magic value" to ensure stream integrity. When loading, this value is loaded and checked - mismatch results in invoking LoadError.
void Pack(bool& a, bool& b, bool& c, bool& d, bool& e, bool& f, bool& g, bool& h)
Serializes a set of boolean values compressed into single byte.
void Pack(bool& a, bool& b, bool& c, bool& d, bool& e, bool& f, bool& g)
Serializes a set of boolean values compressed into single byte.
void Pack(bool& a, bool& b, bool& c, bool& d, bool& e, bool& f)
Serializes a set of boolean values compressed into single byte.
void Pack(bool& a, bool& b, bool& c, bool& d, bool& e)
Serializes a set of boolean values compressed into single byte.
void Pack(bool& a, bool& b, bool& c, bool& d)
Serializes a set of boolean values compressed into single byte.
void Pack(bool& a, bool& b, bool& c)
Serializes a set of boolean values compressed into single byte.
void Pack(bool& a, bool& b)
Serializes a set of boolean values compressed into single byte.
Stream()
Constructor. Sets stream into Loading serialization mode and zero level indentation. All protected variables are set to 0 / NULL.
~Stream()
Destructor.
class StringStream : public Stream
StringStream is stream that uses String as storage medium.
Derived from Stream
void Open(const String& data)
Sets the content of stream to specified String and sets it into the Loading serialization mode.
void Create()
Creates empty StringStream and sets it into Storing serialization mode.
String GetResult()
Returns resulting String.
operator String()
|
Return value |
GetResult(). |
StringStream()
Consructs empty stream and sets it into Storing serialization mode (like Create).
StringStream(const String& data)
Constructs stream with specified content and sets it into Loading serialization mode (like Open).
class MemStream : public Stream
Stream that is using raw memory as its content.
Derived from Stream
MemStream(void *data, int size)
Constructs MemStream at specified memory buffer.
|
data |
Pointer to the stream content. |
class MemReadStream : public MemStream
Read-only stream using raw memory as content.
Derived from MemStream
MemReadStream(const void *data, int size)
Constructs MemStream at specified memory buffer.
|
data |
Pointer to the stream content. |
class BlockStream : public Stream
BlockStream implements operations needed to manage streams that are able to read or write a block of data at random positon. BlockStream provides buffered implementation of such stream. It implements all virtual methods of Stream, with exception of IsOpen and Close, using new virtual methods Read, Write and SetStreamSize.
Derived from BufferStream
enum { READ, CREATE, APPEND, READWRITE, NOWRITESHARE, DELETESHARE, NOREADSHARE, SHAREMASK }
This enum defines basic operation modes of BlockStream (used combined with binary or).
|
APPEND |
Append mode - means that initial position in the stream is at the end of it. |
|
READWRITE |
Enables subsequent streams full access to stream. |
|
NOWRITESHARE |
Disables subsequent streams to write to the stream. |
|
DELETESHARE |
Enables subsequent streams to delete the stream. |
|
NOREADSHARE |
Disables subsequent streams to read the stream. |
virtual dword Read(int64 at, void *ptr, dword size)
Protected.
Implementation of this virtual method in derived class should read a block of data at specified position in media.
|
ptr |
Pointer to buffer to receive data. |
|
size |
Requested size of data. |
|
Return value |
Size of data read. |
virtual void Write(int64 at, const void *data, dword size)
Protected.
Implementation of this virtual method in derived method should write a block of data at specified position in media.
virtual void SetStreamSize(int64 size)
Protected.
Implementation of this virtual method in derived class should adjust the size of media.
|
size |
Requested new size of media. |
int64 GetStreamSize() const
Protected.
Returns current media size. Note that this might be different from current GetSize() - media size adjustment can be deffered to flushing the buffer.
|
Return value |
Current media size. |
void OpenInit(dword mode, int64 file_size)
Protected.
Initializes the BlockStream to specified mode and actual media size.
|
file_size |
Actual media size. |
void SetBufferSize(dword newsize)
Sets a new size of internal buffer.
|
newsize |
The new size of buffer. |
dword GetBufferSize() const
|
Return value |
Size of buffer. |
class FileStream : public BlockStream
Classical file stream.
Derived from BlockStream
FileStream(const char *filename, dword mode)
Opens file stream in specified mode (as defined in BlockStream).
|
filename |
The name of the file. |
FileStream(const char *filename, dword mode, mode_t acm = 0644)
Posix specific.
Opens file stream in specified mode (as defined in BlockStream) and specific POSIX access rights.
|
filename |
The name of the file. |
FileStream(int std_handle)
Posix specific.
Assigns existing file handle to FileStream.
|
std_handle |
File handle of open file. FileStream takes ownership of this handle. |
FileStream()
Creates empty unopened FileStream.
operator bool() const
|
Return value |
True if stream is open. |
FileTime GetTime() const
Returns last-write time of stream.
void SetTime(const FileTime& tm)
Opens file stream in specified mode (as defined in BlockStream).
|
filename |
The name of the file. |
mode Open mode.
bool Open(const char *filename, dword mode, mode_t acm = 0644)
Posix specific.
Opens file stream in specified mode (as defined in BlockStream) and specific POSIX access rights.
|
filename |
The name of the file. |
acm Access rights.
HANDLE GetHandle() const
Win32 specific.
|
Return value |
File handle. |
HANDLE GetHandle() const
Posix specific.
|
Return value |
File handle. |
class FileIn : public FileStream
Simple helper class that represents FileStream in read mode.
Derived from FileStream
FileIn(const char *fn)
Opens file for reading.
FileIn()
Constructs empty FileStream.
bool Open(const char *fn)
Opens file for reading.
|
Return value |
True if open was successful. |
class FileOut : public FileStream
Simple helper class that represents FileStream in write mode.
Derived from FileStream
FileOut(const char *fn)
Opens file for writing.
FileOut()
Constructs non-opened FileStream.
bool Open(const char *fn, mode_t acm = 0644)
Opens file for writing.
|
Return value |
True if open was successful. |
class FileAppend : public FileStream
Simple helper class that represents FileStream in append mode - that in fact means in write mode with current position at the end of the file.
Derived from FileStream
FileAppend(const char *fn)
Opens file in append mode.
FileAppend()
Constructs empty FileStream.
bool Open(const char *fn)
Opens file in append mode.
|
Return value |
true when Open was successful. |
class SizeStream : public Stream
Special output stream that in fact does not store output data, only counts the total number of bytes written.
Derived from BufferStream
SizeStream()
Constructor - co
virtual void _Put(int w)
|
Return value |
Current number of bytes written. |
void Open()
Reopens data - resets the counter of output bytes.
class CompareStream : public Stream
Special output stream that instead of storing data performs their comparison to the data of another stream.
Derived from BufferStream
CompareStream()
Constructs closed CompareStream.
CompareStream(Stream& aStream)
Constructors CompareStream opened for comparison with specified stream.
|
aStream |
Stream to compare with. |
virtual void _Put(int w)
Opens CompareStream for comparison with the specified stream.
|
aStream |
Stream to compare with. |
bool IsEqual()
|
Return value |
true if all bytes written so far match those in comparison stream. |
operator bool()
|
