MemoryStream class
Implements an memory-based stream that supports the IStream interface.
This class is not inherently thread-safe. As a result, thread-safe usage between multiple threads requires higher level coordination, such as a mutex.
Base classes
- class IStream
Public types
- enum Options { kOptionNone = 0, kOptionResizeEnabled = 1, kOptionResizeFactor = 2, kOptionResizeIncrement = 3, kOptionClearNewMemory = 4 }
- enum Options Specifies policies regarding the internal operation of this class.
- using Allocator = ICoreAllocator
Public static variables
Constructors, destructors, conversion operators
- MemoryStream(const char* pName = NULL)
-
MemoryStream(SharedPointer* pSharedPointer = NULL,
size_
type nSize = 0, const char* pName = NULL) -
MemoryStream(void* pData,
size_
type nSize, bool bUsePointer, bool bFreePointer = true, Allocator* pAllocator = NULL, const char* pName = NULL) - ~MemoryStream()
Public functions
- auto GetOption(Options option) const -> float
- auto SetOption(Options option, float fValue) -> void
- auto GetSharedPointer() -> SharedPointer*
- auto GetData() const -> void*
-
auto SetData(SharedPointer* pSharedPointer,
size_
type nSize) -> bool -
auto SetDataRaw(void* pData,
size_
type nSize, bool bUsePointer, bool bFreePointer = true, Allocator* pAllocator = NULL) -> bool - auto AddRef() -> int override
- auto Release() -> int override
-
auto GetType() const -> uint32_
t override - Returns the type of the stream, which is different for each Stream subclass.
- auto GetAccessFlags() const -> AccessFlags override
- Returns one of enum AccessFlags.
- auto GetState() const -> FileError override
- Returns the error state of the stream.
- auto Close() -> bool override
- Closes the stream and releases resouces associated with it.
-
auto GetSize() const -> size_
type override - Returns the size of the stream, which is not the same as the size of bytes remaining to be read from the stream.
-
auto SetSize(size_
type size) -> bool override - Sets the size of the stream, if possible.
-
auto GetPosition(PositionType positionType = PositionType::
Begin) const -> int override - Gets the current read/write position within the stream.
-
auto SetPosition(int distance,
PositionType positionType = PositionType::
Begin) -> bool override - Sets the read/write position of the stream.
- auto GetAvailable() const -> int override
- Returns the number of bytes available for reading.
-
auto Read(void* pData,
size_
t nSize) -> int override - Reads bytes from the stream given by the input count 'nSize'.
- auto Flush() -> bool override
- Flush any non-empty stream write buffers.
-
auto Write(const void* pData,
size_
t nSize) -> int override - Writes bytes to the stream.
Protected variables
- SharedPointer* mpSharedPointer
- int mnRefCount
- Pointer to memory block.
-
size_
type mnSize - Reference count. May or may not be in use.
-
size_
type mnCapacity - The size of the stream, in bytes.
-
size_
type mnPosition - The size of the memory buffer, in bytes.
- bool mbResizeEnabled
- Current position within memory block.
- bool mbClearNewMemory
- True if resizing is enabled.
- float mfResizeFactor
- True if clearing of newly allocated memory is enabled.
- int mnResizeIncrement
- Specifies how capacity is increased.
Enum documentation
enum IO::
enum Options Specifies policies regarding the internal operation of this class.
| Enumerators | |
|---|---|
| kOptionNone |
|
| kOptionResizeEnabled |
No options. |
| kOptionResizeFactor |
0 or 1. Default is disabled. If set, then the buffer is automatically resized on beyond-bounds position sets, beyond-bounds writes, and beyond-bounds SetSize calls. |
| kOptionResizeIncrement |
1.0+ Default is 1.5. Specifies how much a resize multiplies in size; is applied before kOptionResizeIncrement. Can be 1.0 if kOptionResizeIncrement > 0. |
| kOptionClearNewMemory |
0.0+ Default is 0.0. Specifies how much a resize increments; is applied after kOptionResizeFactor. Can be set to zero if kOptionResizeFactor is > 1. |
Function documentation
AccessFlags IO::
Returns one of enum AccessFlags.
This function also tells you if the stream is open, as a return value of zero means the stream is not open. It is not allowed that a stream
be open with no type of access.
FileError IO::
Returns the error state of the stream.
Returns FileError::
bool IO::
Closes the stream and releases resouces associated with it.
Returns true upon success, else false. If the return value is false, GetState will give the error code. If an IStream encounters an error during operations on an open stream, it is guaranteed that you can safely call the Close function on the stream.
bool IO::
Sets the size of the stream, if possible.
| Parameters | |
|---|---|
| size | |
It is debatable whether this function should be present in IStream or only in suclasses of StreamBase which are writable. For consistency with GetSize, we put the function here. But also consider that a SetSize function is not necessarily a data writing function, depending on the stream implementation.
int IO::
Gets the current read/write position within the stream.
| Parameters | |
|---|---|
| positionType | |
The read and write positions of a stream must be the same value; you cannot have a read position that is different from a write position. However, a Stream subclass can provide such functionality if needed. Returns -1 upon error.
bool IO::
Sets the read/write position of the stream.
| Parameters | |
|---|---|
| distance | |
| positionType | |
If the specified position is beyond the size of a fixed stream, the position is set to the end of the stream. A writable stream subclass may provide a policy whereby setting the position beyond the end of the stream results in an increase in the stream size.
int IO::
Returns the number of bytes available for reading.
Returns (size_type)-1 (a.k.a. kSizeTypeError) upon error. This function is non-blocking; it should return immediately.
int IO::
Reads bytes from the stream given by the input count 'nSize'.
| Parameters | |
|---|---|
| pData | |
| nSize | |
If less then nSize bytes are available, then those bytes will be read. Returns the number of bytes read. A return value of zero means that there were no bytes to be read or no bytes were requested to be read. A return value of zero means the end of file was reached. A return value > 0 but < 'nSize' is possible, and it does not necessarily mean that the end of the file was reached. Returns (size_type)-1 (a.k.a. kSizeTypeError) if there was an error. You can use this return value or IStream::
bool IO::
Flush any non-empty stream write buffers.
If the return value is false, GetState will give the error code. This function implements the flushing as per the underlying file system. The behavior of the Flush function varies with the underlying platform.
A common use of Flush is write a file to disk immediately in order to prevent the file from being corrupted if the application crashes before the file is closed. However, on desktop platforms such as Windows this strategy is unnecesary, as the Windows OS file flush doesn't write the file to disk as might be expected. This actually is not a problem, because the Windows OS manages files outside the process and if your process crashes the OS will take care of safely closing the files. Only if the machine power is lost or if certain kinds of kernel-level crashes occur may you lose file data.